622 lines
13 KiB
Markdown
622 lines
13 KiB
Markdown
# MPC Party Service API 文档
|
||
|
||
## 概述
|
||
|
||
MPC Party Service 提供 RESTful API，用于参与 MPC 密钥生成、签名和密钥轮换操作。
|
||
|
||
**基础 URL**: `/api/v1/mpc-party`
|
||
|
||
**认证方式**: Bearer Token (JWT)
|
||
|
||
## 认证
|
||
|
||
除了健康检查端点外，所有 API 都需要 JWT 认证：
|
||
|
||
```http
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
JWT Payload 结构：
|
||
```json
|
||
{
|
||
"sub": "user-id",
|
||
"type": "access",
|
||
"partyId": "user123-server",
|
||
"iat": 1699887766,
|
||
"exp": 1699895766
|
||
}
|
||
```
|
||
|
||
## API 端点
|
||
|
||
### 健康检查
|
||
|
||
#### GET /health
|
||
|
||
检查服务健康状态。此端点不需要认证。
|
||
|
||
**请求**:
|
||
```http
|
||
GET /api/v1/mpc-party/health
|
||
```
|
||
|
||
**响应** `200 OK`:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"status": "ok",
|
||
"service": "mpc-party-service",
|
||
"timestamp": "2024-01-15T10:30:00.000Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 密钥生成 (Keygen)
|
||
|
||
#### POST /keygen/participate
|
||
|
||
参与 MPC 密钥生成会话（异步）。立即返回 202，后台异步执行 MPC 协议。
|
||
|
||
**请求**:
|
||
```http
|
||
POST /api/v1/mpc-party/keygen/participate
|
||
Content-Type: application/json
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
|
||
"partyId": "user123-server",
|
||
"joinToken": "join-token-abc123",
|
||
"shareType": "wallet",
|
||
"userId": "user-id-123"
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 描述 |
|
||
|------|------|------|------|
|
||
| sessionId | string (UUID) | 是 | 会话唯一标识 |
|
||
| partyId | string | 是 | 参与方 ID，格式：`{identifier}-{type}` |
|
||
| joinToken | string | 是 | 加入会话的令牌 |
|
||
| shareType | enum | 是 | 分片类型：`wallet` 或 `custody` |
|
||
| userId | string | 否 | 关联的用户 ID |
|
||
|
||
**响应** `202 Accepted`:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"message": "Keygen participation started",
|
||
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
|
||
"partyId": "user123-server"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
`400 Bad Request` - 参数验证失败:
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "Validation failed",
|
||
"errors": [
|
||
{
|
||
"field": "sessionId",
|
||
"message": "sessionId must be a UUID"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
`401 Unauthorized` - 认证失败:
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "缺少认证令牌"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### POST /keygen/participate-sync
|
||
|
||
参与 MPC 密钥生成会话（同步）。等待 MPC 协议完成后返回结果。
|
||
|
||
**请求**: 与异步端点相同
|
||
|
||
**响应** `200 OK`:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"shareId": "share_1699887766123_abc123xyz",
|
||
"publicKey": "03a1b2c3d4e5f6...",
|
||
"threshold": "2-of-3",
|
||
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
|
||
"partyId": "user123-server"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 签名 (Signing)
|
||
|
||
#### POST /signing/participate
|
||
|
||
参与 MPC 签名会话（异步）。
|
||
|
||
**请求**:
|
||
```http
|
||
POST /api/v1/mpc-party/signing/participate
|
||
Content-Type: application/json
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"sessionId": "660e8400-e29b-41d4-a716-446655440001",
|
||
"partyId": "user123-server",
|
||
"joinToken": "join-token-def456",
|
||
"messageHash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
|
||
"publicKey": "03a1b2c3d4e5f6..."
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 描述 |
|
||
|------|------|------|------|
|
||
| sessionId | string (UUID) | 是 | 签名会话唯一标识 |
|
||
| partyId | string | 是 | 参与方 ID |
|
||
| joinToken | string | 是 | 加入会话的令牌 |
|
||
| messageHash | string (hex, 64 chars) | 是 | 待签名的消息哈希 |
|
||
| publicKey | string (hex) | 是 | 对应的公钥 |
|
||
|
||
**响应** `202 Accepted`:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"message": "Signing participation started",
|
||
"sessionId": "660e8400-e29b-41d4-a716-446655440001",
|
||
"partyId": "user123-server"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
`400 Bad Request` - 消息哈希格式无效:
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "Validation failed",
|
||
"errors": [
|
||
{
|
||
"field": "messageHash",
|
||
"message": "messageHash must be a 64-character hex string"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### POST /signing/participate-sync
|
||
|
||
参与 MPC 签名会话（同步）。
|
||
|
||
**响应** `200 OK`:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"signature": "1122334455...",
|
||
"r": "aabbccdd...",
|
||
"s": "11223344...",
|
||
"v": 27,
|
||
"messageHash": "abcdef1234...",
|
||
"publicKey": "03a1b2c3d4e5f6..."
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 密钥轮换 (Key Rotation)
|
||
|
||
#### POST /share/rotate
|
||
|
||
参与密钥轮换会话（异步）。更新密钥分片而不改变公钥。
|
||
|
||
**请求**:
|
||
```http
|
||
POST /api/v1/mpc-party/share/rotate
|
||
Content-Type: application/json
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"sessionId": "770e8400-e29b-41d4-a716-446655440002",
|
||
"partyId": "user123-server",
|
||
"joinToken": "join-token-ghi789",
|
||
"publicKey": "03a1b2c3d4e5f6..."
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 描述 |
|
||
|------|------|------|------|
|
||
| sessionId | string (UUID) | 是 | 轮换会话唯一标识 |
|
||
| partyId | string | 是 | 参与方 ID |
|
||
| joinToken | string | 是 | 加入会话的令牌 |
|
||
| publicKey | string (hex) | 是 | 要轮换的密钥公钥 |
|
||
|
||
**响应** `202 Accepted`:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"message": "Share rotation started",
|
||
"sessionId": "770e8400-e29b-41d4-a716-446655440002",
|
||
"partyId": "user123-server"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 分片管理 (Share Management)
|
||
|
||
#### GET /shares
|
||
|
||
列出分片，支持过滤和分页。
|
||
|
||
**请求**:
|
||
```http
|
||
GET /api/v1/mpc-party/shares?partyId=user123-server&status=active&page=1&limit=10
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
**查询参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 描述 |
|
||
|------|------|------|--------|------|
|
||
| partyId | string | 否 | - | 按参与方 ID 过滤 |
|
||
| status | enum | 否 | - | 按状态过滤：`active`, `rotated`, `revoked` |
|
||
| shareType | enum | 否 | - | 按类型过滤：`wallet`, `custody` |
|
||
| publicKey | string | 否 | - | 按公钥过滤 |
|
||
| page | number | 否 | 1 | 页码（从 1 开始） |
|
||
| limit | number | 否 | 20 | 每页数量（1-100） |
|
||
|
||
**响应** `200 OK`:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"id": "share_1699887766123_abc123xyz",
|
||
"partyId": "user123-server",
|
||
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
|
||
"shareType": "wallet",
|
||
"publicKey": "03a1b2c3d4e5f6...",
|
||
"threshold": "2-of-3",
|
||
"status": "active",
|
||
"createdAt": "2024-01-15T10:30:00.000Z",
|
||
"updatedAt": "2024-01-15T10:30:00.000Z"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"page": 1,
|
||
"limit": 10,
|
||
"totalPages": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### GET /shares/:shareId
|
||
|
||
获取单个分片的详细信息。
|
||
|
||
**请求**:
|
||
```http
|
||
GET /api/v1/mpc-party/shares/share_1699887766123_abc123xyz
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
**响应** `200 OK`:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "share_1699887766123_abc123xyz",
|
||
"partyId": "user123-server",
|
||
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
|
||
"shareType": "wallet",
|
||
"publicKey": "03a1b2c3d4e5f6...",
|
||
"threshold": "2-of-3",
|
||
"status": "active",
|
||
"createdAt": "2024-01-15T10:30:00.000Z",
|
||
"updatedAt": "2024-01-15T10:30:00.000Z",
|
||
"lastUsedAt": "2024-01-15T12:00:00.000Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
`404 Not Found`:
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "Share not found"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 错误处理
|
||
|
||
### 错误响应格式
|
||
|
||
所有错误响应遵循统一格式：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误描述",
|
||
"errors": [
|
||
{
|
||
"field": "字段名",
|
||
"message": "具体错误信息"
|
||
}
|
||
],
|
||
"statusCode": 400,
|
||
"timestamp": "2024-01-15T10:30:00.000Z",
|
||
"path": "/api/v1/mpc-party/keygen/participate"
|
||
}
|
||
```
|
||
|
||
### HTTP 状态码
|
||
|
||
| 状态码 | 描述 |
|
||
|--------|------|
|
||
| 200 | 成功 |
|
||
| 202 | 已接受（异步操作） |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未认证 |
|
||
| 403 | 无权限 |
|
||
| 404 | 资源不存在 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
### 业务错误码
|
||
|
||
| 错误码 | 描述 |
|
||
|--------|------|
|
||
| SHARE_NOT_FOUND | 分片不存在 |
|
||
| SHARE_REVOKED | 分片已撤销 |
|
||
| INVALID_SESSION | 无效的会话 |
|
||
| SESSION_EXPIRED | 会话已过期 |
|
||
| THRESHOLD_NOT_MET | 参与方数量未达到门限 |
|
||
| ENCRYPTION_ERROR | 加密/解密错误 |
|
||
| TSS_PROTOCOL_ERROR | TSS 协议执行错误 |
|
||
|
||
---
|
||
|
||
## 数据模型
|
||
|
||
### ShareType 枚举
|
||
|
||
```typescript
|
||
enum ShareType {
|
||
WALLET = 'wallet', // 用户钱包密钥分片
|
||
CUSTODY = 'custody' // 托管密钥分片
|
||
}
|
||
```
|
||
|
||
### ShareStatus 枚举
|
||
|
||
```typescript
|
||
enum ShareStatus {
|
||
ACTIVE = 'active', // 活跃状态
|
||
ROTATED = 'rotated', // 已轮换（旧分片）
|
||
REVOKED = 'revoked' // 已撤销
|
||
}
|
||
```
|
||
|
||
### Threshold 格式
|
||
|
||
门限以 `t-of-n` 格式表示：
|
||
- `n`: 总分片数
|
||
- `t`: 签名所需最小分片数
|
||
|
||
示例：`2-of-3` 表示 3 个分片中需要 2 个才能签名。
|
||
|
||
---
|
||
|
||
## Webhook 事件（通过 Kafka）
|
||
|
||
当关键操作完成时，服务会发布事件到 Kafka：
|
||
|
||
### ShareCreatedEvent
|
||
|
||
```json
|
||
{
|
||
"eventType": "share.created",
|
||
"eventId": "evt_1699887766123_xyz",
|
||
"occurredAt": "2024-01-15T10:30:00.000Z",
|
||
"payload": {
|
||
"shareId": "share_1699887766123_abc123xyz",
|
||
"partyId": "user123-server",
|
||
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
|
||
"shareType": "wallet",
|
||
"publicKey": "03a1b2c3d4e5f6...",
|
||
"threshold": "2-of-3"
|
||
}
|
||
}
|
||
```
|
||
|
||
### ShareRotatedEvent
|
||
|
||
```json
|
||
{
|
||
"eventType": "share.rotated",
|
||
"eventId": "evt_1699887766124_abc",
|
||
"occurredAt": "2024-01-15T11:00:00.000Z",
|
||
"payload": {
|
||
"newShareId": "share_1699887766124_def456uvw",
|
||
"oldShareId": "share_1699887766123_abc123xyz",
|
||
"partyId": "user123-server",
|
||
"sessionId": "770e8400-e29b-41d4-a716-446655440002"
|
||
}
|
||
}
|
||
```
|
||
|
||
### ShareRevokedEvent
|
||
|
||
```json
|
||
{
|
||
"eventType": "share.revoked",
|
||
"eventId": "evt_1699887766125_def",
|
||
"occurredAt": "2024-01-15T12:00:00.000Z",
|
||
"payload": {
|
||
"shareId": "share_1699887766123_abc123xyz",
|
||
"partyId": "user123-server",
|
||
"reason": "Security audit requirement"
|
||
}
|
||
}
|
||
```
|
||
|
||
### SigningCompletedEvent
|
||
|
||
```json
|
||
{
|
||
"eventType": "signing.completed",
|
||
"eventId": "evt_1699887766126_ghi",
|
||
"occurredAt": "2024-01-15T13:00:00.000Z",
|
||
"payload": {
|
||
"sessionId": "660e8400-e29b-41d4-a716-446655440001",
|
||
"signature": "1122334455...",
|
||
"publicKey": "03a1b2c3d4e5f6...",
|
||
"messageHash": "abcdef1234..."
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 速率限制
|
||
|
||
| 端点类型 | 限制 |
|
||
|----------|------|
|
||
| 健康检查 | 无限制 |
|
||
| 查询端点 | 100 次/分钟 |
|
||
| Keygen | 10 次/分钟 |
|
||
| Signing | 60 次/分钟 |
|
||
| Rotation | 5 次/分钟 |
|
||
|
||
超出限制时返回 `429 Too Many Requests`。
|
||
|
||
---
|
||
|
||
## SDK 使用示例
|
||
|
||
### TypeScript/JavaScript
|
||
|
||
```typescript
|
||
import axios from 'axios';
|
||
|
||
const api = axios.create({
|
||
baseURL: 'https://api.example.com/api/v1/mpc-party',
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`,
|
||
'Content-Type': 'application/json'
|
||
}
|
||
});
|
||
|
||
// 参与 Keygen
|
||
async function participateInKeygen(params: {
|
||
sessionId: string;
|
||
partyId: string;
|
||
joinToken: string;
|
||
shareType: 'wallet' | 'custody';
|
||
}) {
|
||
const response = await api.post('/keygen/participate', params);
|
||
return response.data;
|
||
}
|
||
|
||
// 参与签名
|
||
async function participateInSigning(params: {
|
||
sessionId: string;
|
||
partyId: string;
|
||
joinToken: string;
|
||
messageHash: string;
|
||
publicKey: string;
|
||
}) {
|
||
const response = await api.post('/signing/participate', params);
|
||
return response.data;
|
||
}
|
||
|
||
// 列出分片
|
||
async function listShares(params?: {
|
||
partyId?: string;
|
||
status?: string;
|
||
page?: number;
|
||
limit?: number;
|
||
}) {
|
||
const response = await api.get('/shares', { params });
|
||
return response.data;
|
||
}
|
||
|
||
// 获取分片信息
|
||
async function getShareInfo(shareId: string) {
|
||
const response = await api.get(`/shares/${shareId}`);
|
||
return response.data;
|
||
}
|
||
```
|
||
|
||
### cURL 示例
|
||
|
||
```bash
|
||
# 健康检查
|
||
curl -X GET https://api.example.com/api/v1/mpc-party/health
|
||
|
||
# 参与 Keygen
|
||
curl -X POST https://api.example.com/api/v1/mpc-party/keygen/participate \
|
||
-H "Authorization: Bearer <token>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
|
||
"partyId": "user123-server",
|
||
"joinToken": "join-token-abc123",
|
||
"shareType": "wallet",
|
||
"userId": "user-id-123"
|
||
}'
|
||
|
||
# 列出分片
|
||
curl -X GET "https://api.example.com/api/v1/mpc-party/shares?partyId=user123-server&page=1&limit=10" \
|
||
-H "Authorization: Bearer <token>"
|
||
```
|
||
|
||
---
|
||
|
||
## Swagger 文档
|
||
|
||
在非生产环境，Swagger UI 可通过以下地址访问：
|
||
|
||
```
|
||
http://localhost:3006/api/docs
|
||
```
|
||
|
||
提供交互式 API 文档和测试功能。
|