# MPC 分布式签名系统 - API 参考文档

## 1. API 概览

系统提供两种 API 接口:
- **gRPC**: 服务间通信，高性能
- **HTTP/REST**: 客户端接入，易用性

### 1.1 服务端点

| 服务 | gRPC 端口 | HTTP 端口 | 说明 |
|------|----------|----------|------|
| Session Coordinator | 50051 | 8080 | 会话管理 |
| Message Router | 50052 | 8081 | 消息路由 |
| Server Party 1 | 50053 | 8082 | 计算节点 |
| Server Party 2 | 50055 | 8084 | 计算节点 |
| Server Party 3 | 50056 | 8085 | 计算节点 |
| Account Service | 50054 | 8083 | 账户管理 |

## 2. Session Coordinator API

### 2.1 创建会话 (Create Session)

创建一个新的 MPC 会话 (keygen 或 sign)。

**gRPC**
```protobuf
rpc CreateSession(CreateSessionRequest) returns (CreateSessionResponse);
```

**HTTP**
```
POST /api/v1/sessions
Content-Type: application/json
```

**请求体**
```json
{
  "session_type": "keygen",
  "threshold_n": 3,
  "threshold_t": 2,
  "participants": [
    {
      "party_id": "party_user_device",
      "device_type": "iOS",
      "device_id": "device_001"
    },
    {
      "party_id": "party_server",
      "device_type": "server",
      "device_id": "server_001"
    },
    {
      "party_id": "party_recovery",
      "device_type": "recovery",
      "device_id": "recovery_001"
    }
  ],
  "message_hash": "abc123...",  // 仅签名会话需要
  "expires_in_seconds": 300
}
```

**响应**
```json
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "join_tokens": {
    "party_user_device": "token-uuid-1",
    "party_server": "token-uuid-2",
    "party_recovery": "token-uuid-3"
  },
  "expires_at": 1703145600
}
```

**状态码**
| 状态码 | 说明 |
|--------|------|
| 201 | 创建成功 |
| 400 | 请求参数错误 |
| 500 | 服务器内部错误 |

---

### 2.2 加入会话 (Join Session)

参与方使用 join token 加入会话。

**HTTP**
```
POST /api/v1/sessions/join
Content-Type: application/json
```

**请求体**
```json
{
  "join_token": "token-uuid-1",
  "party_id": "party_user_device",
  "device_type": "iOS",
  "device_id": "device_001"
}
```

**响应**
```json
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "party_index": 0,
  "status": "joined",
  "participants": [
    {
      "party_id": "party_user_device",
      "status": "joined"
    },
    {
      "party_id": "party_server",
      "status": "waiting"
    }
  ]
}
```

**状态码**
| 状态码 | 说明 |
|--------|------|
| 200 | 加入成功 |
| 400 | 会话已满或参数错误 |
| 401 | Token 无效 |
| 404 | 会话不存在 |

---

### 2.3 标记就绪 (Mark Party Ready)

参与方表示已准备好开始协议。

**HTTP**
```
PUT /api/v1/sessions/{session_id}/parties/{party_id}/ready
Content-Type: application/json
```

**请求体**
```json
{
  "party_id": "party_user_device"
}
```

**响应**
```json
{
  "success": true,
  "all_ready": false,
  "ready_count": 2,
  "total_parties": 3
}
```

---

### 2.4 启动会话 (Start Session)

当所有参与方就绪后，启动 MPC 协议。

**HTTP**
```
POST /api/v1/sessions/{session_id}/start
```

**响应**
```json
{
  "success": true,
  "status": "in_progress"
}
```

---

### 2.5 获取会话状态 (Get Session Status)

查询会话当前状态。

**HTTP**
```
GET /api/v1/sessions/{session_id}
```

**响应**
```json
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "in_progress",
  "threshold_t": 2,
  "threshold_n": 3,
  "participants": [
    {
      "party_id": "party_user_device",
      "party_index": 0,
      "status": "computing"
    },
    {
      "party_id": "party_server",
      "party_index": 1,
      "status": "computing"
    },
    {
      "party_id": "party_recovery",
      "party_index": 2,
      "status": "computing"
    }
  ]
}
```

**会话状态**
| 状态 | 说明 |
|------|------|
| created | 会话已创建，等待参与方加入 |
| waiting | 参与方已加入，等待就绪 |
| in_progress | MPC 协议执行中 |
| completed | 协议完成 |
| failed | 协议失败 |
| expired | 会话超时 |

---

### 2.6 报告完成 (Report Completion)

参与方报告协议完成。

**HTTP**
```
POST /api/v1/sessions/{session_id}/complete
Content-Type: application/json
```

**请求体 (Keygen)**
```json
{
  "party_id": "party_user_device",
  "public_key": "04a1b2c3d4..."
}
```

**请求体 (Signing)**
```json
{
  "party_id": "party_user_device",
  "signature": "r_value||s_value",
  "recovery_id": 0
}
```

**响应**
```json
{
  "success": true,
  "all_completed": true
}
```

---

## 3. Message Router API

### 3.1 发送消息 (Route Message)

发送 TSS 协议消息给其他参与方。

**gRPC**
```protobuf
rpc RouteMessage(MPCMessage) returns (RouteMessageResponse);
```

**请求**
```json
{
  "session_id": "550e8400-...",
  "from_party": "party_0",
  "to_parties": ["party_1"],  // 空表示广播
  "round": 1,
  "payload": "base64_encoded_tss_message",
  "is_broadcast": false
}
```

### 3.2 订阅消息 (Subscribe Messages)

实时接收发给自己的 TSS 消息。

**gRPC (Stream)**
```protobuf
rpc SubscribeMessages(SubscribeRequest) returns (stream MPCMessage);
```

**WebSocket**
```
WS /api/v1/messages/subscribe?session_id=xxx&party_id=yyy
```

### 3.3 获取待处理消息 (Get Pending Messages)

获取缓存的待处理消息。

**HTTP**
```
GET /api/v1/sessions/{session_id}/messages?party_id=xxx
```

**响应**
```json
{
  "messages": [
    {
      "from_party": "party_0",
      "round": 1,
      "payload": "base64...",
      "timestamp": 1703145600
    }
  ]
}
```

---

## 4. Account Service API

### 4.1 创建账户 (Create Account)

**HTTP**
```
POST /api/v1/accounts
Content-Type: application/json
```

**请求体**
```json
{
  "username": "alice",
  "email": "alice@example.com",
  "phone": "+1234567890",
  "publicKey": "04a1b2c3..."
}
```

**响应**
```json
{
  "id": "acc-uuid-123",
  "username": "alice",
  "email": "alice@example.com",
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z"
}
```

---

### 4.2 创建 Keygen 会话 (Create Keygen Session)

通过账户服务创建密钥生成会话。

**HTTP**
```
POST /api/v1/mpc/keygen
Content-Type: application/json
```

**请求体**
```json
{
  "threshold_n": 3,
  "threshold_t": 2,
  "participants": [
    {
      "party_id": "user_device",
      "device_type": "iOS",
      "device_id": "iphone_001"
    },
    {
      "party_id": "server_party",
      "device_type": "server",
      "device_id": "server_001"
    },
    {
      "party_id": "recovery_party",
      "device_type": "recovery",
      "device_id": "recovery_001"
    }
  ]
}
```

**响应**
```json
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_type": "keygen",
  "threshold_n": 3,
  "threshold_t": 2,
  "join_tokens": {
    "user_device": "token-1",
    "server_party": "token-2",
    "recovery_party": "token-3"
  },
  "status": "waiting"
}
```

---

### 4.3 创建签名会话 (Create Signing Session)

**HTTP**
```
POST /api/v1/mpc/sign
Content-Type: application/json
```

**请求体**
```json
{
  "account_id": "acc-uuid-123",
  "message_hash": "8dcd9f3511659638d5c33938ddb7fee9bb63533b94a97c7467d3fd36abbdca81",
  "participants": [
    {
      "party_id": "user_device",
      "device_type": "iOS",
      "device_id": "iphone_001"
    },
    {
      "party_id": "server_party",
      "device_type": "server",
      "device_id": "server_001"
    }
  ]
}
```

**响应**
```json
{
  "session_id": "660e8400-e29b-41d4-a716-446655440001",
  "session_type": "sign",
  "account_id": "acc-uuid-123",
  "message_hash": "8dcd9f35...",
  "threshold_t": 2,
  "join_tokens": {
    "user_device": "token-a",
    "server_party": "token-b"
  },
  "status": "waiting"
}
```

---

### 4.4 获取 MPC 会话状态

**HTTP**
```
GET /api/v1/mpc/sessions/{session_id}
```

**响应**
```json
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "completed_parties": 3,
  "total_parties": 3,
  "public_key": "04a1b2c3d4...",  // keygen 完成后
  "signature": "r||s"              // signing 完成后
}
```

---

## 5. 健康检查 API

所有服务都提供健康检查端点。

**HTTP**
```
GET /health
```

**响应**
```json
{
  "status": "healthy",
  "service": "session-coordinator",
  "version": "1.0.0",
  "uptime": "24h30m15s"
}
```

---

## 6. 错误响应格式

所有 API 错误遵循统一格式:

```json
{
  "error": "error_code",
  "message": "Human readable error message",
  "details": {
    "field": "specific field error"
  }
}
```

**常见错误码**
| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| invalid_request | 400 | 请求参数无效 |
| unauthorized | 401 | 未授权 |
| not_found | 404 | 资源不存在 |
| session_expired | 410 | 会话已过期 |
| session_full | 409 | 会话参与方已满 |
| threshold_not_met | 400 | 未达到阈值要求 |
| internal_error | 500 | 服务器内部错误 |

---

## 7. gRPC Proto 定义

完整的 Proto 定义位于 `api/proto/session_coordinator.proto`:

```protobuf
syntax = "proto3";
package mpc.coordinator.v1;

service SessionCoordinator {
  rpc CreateSession(CreateSessionRequest) returns (CreateSessionResponse);
  rpc JoinSession(JoinSessionRequest) returns (JoinSessionResponse);
  rpc GetSessionStatus(GetSessionStatusRequest) returns (GetSessionStatusResponse);
  rpc MarkPartyReady(MarkPartyReadyRequest) returns (MarkPartyReadyResponse);
  rpc StartSession(StartSessionRequest) returns (StartSessionResponse);
  rpc ReportCompletion(ReportCompletionRequest) returns (ReportCompletionResponse);
  rpc CloseSession(CloseSessionRequest) returns (CloseSessionResponse);
}
```

---

## 8. SDK 使用示例

### 8.1 Go 客户端

```go
import (
    "context"
    coordinator "github.com/rwadurian/mpc-system/api/grpc/coordinator/v1"
    "google.golang.org/grpc"
)

func main() {
    conn, _ := grpc.Dial("localhost:50051", grpc.WithInsecure())
    client := coordinator.NewSessionCoordinatorClient(conn)

    // 创建 keygen 会话
    resp, _ := client.CreateSession(context.Background(), &coordinator.CreateSessionRequest{
        SessionType: "keygen",
        ThresholdN:  3,
        ThresholdT:  2,
        Participants: []*coordinator.ParticipantInfo{
            {PartyId: "party_0"},
            {PartyId: "party_1"},
            {PartyId: "party_2"},
        },
    })

    fmt.Println("Session ID:", resp.SessionId)
}
```

### 8.2 cURL 示例

```bash
# 创建 keygen 会话
curl -X POST http://localhost:8080/api/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "session_type": "keygen",
    "threshold_n": 3,
    "threshold_t": 2,
    "participants": [
      {"party_id": "party_0"},
      {"party_id": "party_1"},
      {"party_id": "party_2"}
    ]
  }'

# 加入会话
curl -X POST http://localhost:8080/api/v1/sessions/join \
  -H "Content-Type: application/json" \
  -d '{
    "join_token": "token-uuid-1",
    "party_id": "party_0",
    "device_type": "iOS",
    "device_id": "device_001"
  }'

# 查询会话状态
curl http://localhost:8080/api/v1/sessions/550e8400-e29b-41d4-a716-446655440000
```