hailin
/
rwadurian
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
rwadurian/backend/mpc-system/docs/02-api-reference.md

12 KiB
Raw Blame History

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

rpc CreateSession(CreateSessionRequest) returns (CreateSessionResponse);

HTTP

POST /api/v1/sessions
Content-Type: application/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
}

响应

{
  "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

请求体

{
  "join_token": "token-uuid-1",
  "party_id": "party_user_device",
  "device_type": "iOS",
  "device_id": "device_001"
}

响应

{
  "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

请求体

{
  "party_id": "party_user_device"
}

响应

{
  "success": true,
  "all_ready": false,
  "ready_count": 2,
  "total_parties": 3
}

2.4 启动会话 (Start Session)

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

HTTP

POST /api/v1/sessions/{session_id}/start

响应

{
  "success": true,
  "status": "in_progress"
}

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

查询会话当前状态。

HTTP

GET /api/v1/sessions/{session_id}

响应

{
  "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)

{
  "party_id": "party_user_device",
  "public_key": "04a1b2c3d4..."
}

请求体 (Signing)

{
  "party_id": "party_user_device",
  "signature": "r_value||s_value",
  "recovery_id": 0
}

响应

{
  "success": true,
  "all_completed": true
}

3. Message Router API

3.1 发送消息 (Route Message)

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

gRPC

rpc RouteMessage(MPCMessage) returns (RouteMessageResponse);

请求

{
  "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)

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

响应

{
  "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

请求体

{
  "username": "alice",
  "email": "alice@example.com",
  "phone": "+1234567890",
  "publicKey": "04a1b2c3..."
}

响应

{
  "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

请求体

{
  "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"
    }
  ]
}

响应

{
  "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

请求体

{
  "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"
    }
  ]
}

响应

{
  "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}

响应

{
  "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

响应

{
  "status": "healthy",
  "service": "session-coordinator",
  "version": "1.0.0",
  "uptime": "24h30m15s"
}

6. 错误响应格式

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

{
  "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:

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 客户端

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 示例

# 创建 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