614 lines
11 KiB
Markdown
614 lines
11 KiB
Markdown
# 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
|
|
```
|