# MPC Party Service 架构文档

## 概述

MPC Party Service 是 RWA Durian 系统中的多方计算（Multi-Party Computation）服务端组件。该服务负责参与分布式密钥生成、签名和密钥轮换协议，安全地管理服务端的密钥分片。

## 架构设计原则

### 1. 六边形架构 (Hexagonal Architecture)

本服务采用六边形架构（又称端口与适配器架构），实现业务逻辑与外部依赖的解耦：

```
┌─────────────────────────────────────────────────────────────┐
│                      API Layer (Driving Adapters)            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │ REST API    │  │ gRPC API    │  │ WebSocket   │          │
│  │ Controllers │  │ (Future)    │  │ Handlers    │          │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │
└─────────┼────────────────┼────────────────┼─────────────────┘
          │                │                │
          ▼                ▼                ▼
┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                         │
│  ┌─────────────────┐  ┌─────────────────┐                   │
│  │ Command Handlers│  │ Query Handlers  │                   │
│  │ - Keygen        │  │ - GetShareInfo  │                   │
│  │ - Signing       │  │ - ListShares    │                   │
│  │ - Rotate        │  │                 │                   │
│  └────────┬────────┘  └────────┬────────┘                   │
│           │                    │                             │
│  ┌────────▼────────────────────▼────────┐                   │
│  │     Application Services              │                   │
│  │     - MPCPartyApplicationService      │                   │
│  └────────────────┬─────────────────────┘                   │
└───────────────────┼─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────┐
│                      Domain Layer                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │  Entities   │  │   Value     │  │  Domain     │          │
│  │ - PartyShare│  │   Objects   │  │  Services   │          │
│  │ - Session   │  │ - ShareId   │  │ - TSS       │          │
│  │   State     │  │ - PartyId   │  │ - Encryption│          │
│  │             │  │ - Threshold │  │             │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
│                                                              │
│  ┌─────────────────────────────────────────────────┐        │
│  │              Domain Events                       │        │
│  │  - ShareCreatedEvent                            │        │
│  │  - ShareRotatedEvent                            │        │
│  │  - ShareRevokedEvent                            │        │
│  └─────────────────────────────────────────────────┘        │
└─────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────┐
│                Infrastructure Layer (Driven Adapters)        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │  Prisma     │  │   Redis     │  │   Kafka     │          │
│  │  Repository │  │   Cache     │  │   Events    │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
│                                                              │
│  ┌─────────────┐  ┌─────────────┐                           │
│  │ Coordinator │  │  Message    │                           │
│  │   Client    │  │  Router     │                           │
│  └─────────────┘  └─────────────┘                           │
└─────────────────────────────────────────────────────────────┘
```

### 2. CQRS 模式 (Command Query Responsibility Segregation)

命令和查询分离，提高系统的可扩展性和可维护性：

- **Commands**: 改变系统状态的操作
  - `ParticipateInKeygenCommand`
  - `ParticipateInSigningCommand`
  - `RotateShareCommand`

- **Queries**: 只读操作
  - `GetShareInfoQuery`
  - `ListSharesQuery`

### 3. 领域驱动设计 (DDD)

- **聚合根 (Aggregate Root)**: `PartyShare`
- **值对象 (Value Objects)**: `ShareId`, `PartyId`, `SessionId`, `Threshold`, `ShareData`, `PublicKey`, `Signature`, `MessageHash`
- **领域事件 (Domain Events)**: 用于解耦和异步处理
- **仓储接口 (Repository Interfaces)**: 定义在领域层，实现在基础设施层

## 目录结构

```
src/
├── api/                          # API 层 (Driving Adapters)
│   ├── controllers/              # REST 控制器
│   │   └── mpc-party.controller.ts
│   ├── dto/                      # 数据传输对象
│   │   ├── request/              # 请求 DTO
│   │   └── response/             # 响应 DTO
│   └── api.module.ts
│
├── application/                  # 应用层
│   ├── commands/                 # 命令处理器
│   │   ├── participate-keygen/
│   │   ├── participate-signing/
│   │   └── rotate-share/
│   ├── queries/                  # 查询处理器
│   │   ├── get-share-info/
│   │   └── list-shares/
│   ├── services/                 # 应用服务
│   │   └── mpc-party-application.service.ts
│   └── application.module.ts
│
├── domain/                       # 领域层
│   ├── entities/                 # 实体
│   │   ├── party-share.entity.ts
│   │   └── session-state.entity.ts
│   ├── value-objects/            # 值对象
│   │   └── index.ts
│   ├── enums/                    # 枚举
│   │   └── index.ts
│   ├── events/                   # 领域事件
│   │   └── index.ts
│   ├── repositories/             # 仓储接口
│   │   ├── party-share.repository.interface.ts
│   │   └── session-state.repository.interface.ts
│   ├── services/                 # 领域服务
│   │   ├── share-encryption.domain-service.ts
│   │   └── tss-protocol.domain-service.ts
│   └── domain.module.ts
│
├── infrastructure/               # 基础设施层 (Driven Adapters)
│   ├── persistence/              # 持久化
│   │   ├── prisma/               # Prisma ORM
│   │   ├── repositories/         # 仓储实现
│   │   └── mappers/              # 数据映射器
│   ├── redis/                    # Redis 缓存与锁
│   │   ├── cache/
│   │   └── lock/
│   ├── messaging/                # 消息传递
│   │   └── kafka/
│   ├── external/                 # 外部服务客户端
│   │   └── mpc-system/
│   └── infrastructure.module.ts
│
├── shared/                       # 共享模块
│   ├── decorators/               # 装饰器
│   ├── filters/                  # 异常过滤器
│   ├── guards/                   # 守卫
│   └── interceptors/             # 拦截器
│
├── config/                       # 配置
│   └── index.ts
│
├── app.module.ts                 # 根模块
└── main.ts                       # 入口文件
```

## 核心组件详解

### 1. Domain Layer (领域层)

#### PartyShare 实体

```typescript
// src/domain/entities/party-share.entity.ts
export class PartyShare {
  private readonly _id: ShareId;
  private readonly _partyId: PartyId;
  private readonly _sessionId: SessionId;
  private readonly _shareType: PartyShareType;
  private readonly _shareData: ShareData;
  private readonly _publicKey: PublicKey;
  private readonly _threshold: Threshold;
  private _status: PartyShareStatus;
  private _lastUsedAt?: Date;
  private readonly _domainEvents: DomainEvent[] = [];

  // 工厂方法 - 创建新分片
  static create(props: CreatePartyShareProps): PartyShare;

  // 工厂方法 - 从持久化数据重建
  static reconstruct(props: ReconstructPartyShareProps): PartyShare;

  // 业务方法
  markAsUsed(): void;
  rotate(newShareData: ShareData, newSessionId: SessionId): PartyShare;
  revoke(reason: string): void;
}
```

#### Value Objects (值对象)

值对象是不可变的，通过值来识别：

```typescript
// ShareId - 分片唯一标识
export class ShareId {
  static create(value: string): ShareId;
  static generate(): ShareId;
  get value(): string;
  equals(other: ShareId): boolean;
}

// Threshold - 门限配置
export class Threshold {
  static create(n: number, t: number): Threshold;
  get n(): number;  // 总分片数
  get t(): number;  // 签名门限
  canSign(availableParties: number): boolean;
}

// ShareData - 加密的分片数据
export class ShareData {
  static create(encryptedData: Buffer, iv: Buffer, authTag: Buffer): ShareData;
  toJSON(): ShareDataJson;
  static fromJSON(json: ShareDataJson): ShareData;
}
```

#### Domain Services (领域服务)

```typescript
// 分片加密服务
export class ShareEncryptionDomainService {
  encrypt(plaintext: Buffer, masterKey: Buffer): EncryptedData;
  decrypt(encryptedData: EncryptedData, masterKey: Buffer): Buffer;
  generateMasterKey(): Buffer;
  deriveKeyFromPassword(password: string, salt: Buffer): Promise<Buffer>;
}

// TSS 协议服务接口
export interface TssProtocolDomainService {
  runKeygen(params: KeygenParams): Promise<KeygenResult>;
  runSigning(params: SigningParams): Promise<SigningResult>;
  runRefresh(params: RefreshParams): Promise<RefreshResult>;
}
```

### 2. Application Layer (应用层)

#### Command Handlers

```typescript
// ParticipateInKeygenHandler
@CommandHandler(ParticipateInKeygenCommand)
export class ParticipateInKeygenHandler {
  async execute(command: ParticipateInKeygenCommand): Promise<KeygenResultDto> {
    // 1. 加入会话
    const sessionInfo = await this.coordinatorClient.joinSession(/*...*/);

    // 2. 运行 TSS Keygen 协议
    const keygenResult = await this.tssProtocolService.runKeygen(/*...*/);

    // 3. 加密并保存分片
    const encryptedShare = this.encryptionService.encrypt(/*...*/);
    const partyShare = PartyShare.create(/*...*/);
    await this.partyShareRepository.save(partyShare);

    // 4. 发布领域事件
    await this.eventPublisher.publishAll(partyShare.domainEvents);

    return result;
  }
}
```

#### Application Service

应用服务协调命令和查询处理器：

```typescript
@Injectable()
export class MPCPartyApplicationService {
  async participateInKeygen(params: ParticipateKeygenParams): Promise<KeygenResultDto>;
  async participateInSigning(params: ParticipateSigningParams): Promise<SigningResultDto>;
  async rotateShare(params: RotateShareParams): Promise<RotateResultDto>;
  async getShareInfo(shareId: string): Promise<ShareInfoDto>;
  async listShares(params: ListSharesParams): Promise<ListSharesResultDto>;
}
```

### 3. Infrastructure Layer (基础设施层)

#### Repository Implementation

```typescript
@Injectable()
export class PartyShareRepositoryImpl implements PartyShareRepository {
  constructor(
    private readonly prisma: PrismaService,
    private readonly mapper: PartyShareMapper,
  ) {}

  async save(share: PartyShare): Promise<void> {
    const entity = this.mapper.toPersistence(share);
    await this.prisma.partyShare.create({ data: entity });
  }

  async findById(id: ShareId): Promise<PartyShare | null> {
    const entity = await this.prisma.partyShare.findUnique({
      where: { id: id.value },
    });
    return entity ? this.mapper.toDomain(entity) : null;
  }
}
```

#### External Service Clients

```typescript
// MPC Coordinator Client - 与协调器通信
@Injectable()
export class MPCCoordinatorClient {
  async joinSession(params: JoinSessionParams): Promise<SessionInfo>;
  async reportCompletion(sessionId: string, status: string): Promise<void>;
}

// Message Router Client - P2P 消息传递
@Injectable()
export class MPCMessageRouterClient {
  async subscribeMessages(sessionId: string): Promise<AsyncIterator<Message>>;
  async sendMessage(message: Message): Promise<void>;
}
```

### 4. API Layer (API 层)

#### Controller

```typescript
@Controller('mpc-party')
@UseGuards(JwtAuthGuard)
export class MPCPartyController {
  // 异步端点 - 立即返回 202
  @Post('keygen/participate')
  @HttpCode(HttpStatus.ACCEPTED)
  async participateInKeygen(@Body() dto: ParticipateKeygenDto): Promise<KeygenAcceptedDto>;

  // 同步端点 - 等待完成
  @Post('keygen/participate-sync')
  async participateInKeygenSync(@Body() dto: ParticipateKeygenDto): Promise<KeygenResultDto>;

  // 查询端点
  @Get('shares')
  async listShares(@Query() query: ListSharesDto): Promise<ListSharesResponseDto>;

  @Get('shares/:shareId')
  async getShareInfo(@Param('shareId') shareId: string): Promise<ShareInfoResponseDto>;

  // 公开端点
  @Public()
  @Get('health')
  health(): HealthStatus;
}
```

## 数据流

### Keygen 流程

```
┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Client  │     │Controller│     │ Handler  │     │TSS Service│
└────┬─────┘     └────┬─────┘     └────┬─────┘     └────┬─────┘
     │                │                │                │
     │ POST /keygen   │                │                │
     │ /participate   │                │                │
     │───────────────>│                │                │
     │                │ execute()      │                │
     │                │───────────────>│                │
     │                │                │ joinSession()  │
     │                │                │───────────────>│ Coordinator
     │                │                │<───────────────│
     │                │                │                │
     │                │                │ runKeygen()    │
     │                │                │───────────────>│
     │                │                │    ...MPC...   │
     │                │                │<───────────────│
     │                │                │                │
     │                │                │ save(share)    │
     │                │                │───────────────>│ Repository
     │                │                │<───────────────│
     │                │                │                │
     │                │                │ publish(event) │
     │                │                │───────────────>│ Kafka
     │  202 Accepted  │<───────────────│                │
     │<───────────────│                │                │
     │                │                │                │
```

### Signing 流程

```
┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Client  │     │Controller│     │ Handler  │     │TSS Service│
└────┬─────┘     └────┬─────┘     └────┬─────┘     └────┬─────┘
     │                │                │                │
     │ POST /signing  │                │                │
     │ /participate   │                │                │
     │───────────────>│                │                │
     │                │ execute()      │                │
     │                │───────────────>│                │
     │                │                │ findShare()    │
     │                │                │───────────────>│ Repository
     │                │                │<───────────────│
     │                │                │                │
     │                │                │ decrypt()      │
     │                │                │───────────────>│ Encryption
     │                │                │<───────────────│
     │                │                │                │
     │                │                │ runSigning()   │
     │                │                │───────────────>│
     │                │                │    ...MPC...   │
     │                │                │<───────────────│
     │                │                │                │
     │  202 Accepted  │<───────────────│ signature      │
     │<───────────────│                │                │
```

## 安全设计

### 1. 分片加密

所有密钥分片在存储前使用 AES-256-GCM 加密：

```typescript
// 加密流程
const { encryptedData, iv, authTag } = encryptionService.encrypt(
  shareData,
  masterKey
);

// 存储加密后的数据
const shareData = ShareData.create(encryptedData, iv, authTag);
```

### 2. 访问控制

- JWT Token 验证
- Party ID 绑定
- 操作审计日志

### 3. 安全通信

- TLS 加密传输
- 消息签名验证
- 会话令牌认证

## 扩展性设计

### 1. 水平扩展

- 无状态服务设计
- Redis 分布式锁
- Kafka 事件驱动

### 2. 多协议支持

通过领域服务接口抽象，支持不同的 TSS 实现：

```typescript
// 接口定义
export interface TssProtocolDomainService {
  runKeygen(params: KeygenParams): Promise<KeygenResult>;
  runSigning(params: SigningParams): Promise<SigningResult>;
  runRefresh(params: RefreshParams): Promise<RefreshResult>;
}

// 可替换实现
// - GG20 实现
// - FROST 实现
// - 其他 TSS 协议
```

### 3. 插件化设计

基础设施层的实现可以轻松替换：

- 数据库：Prisma 支持多种数据库
- 缓存：可替换为其他缓存方案
- 消息队列：可替换为 RabbitMQ 等

## 配置管理

```typescript
// src/config/index.ts
export const configurations = [
  () => ({
    port: parseInt(process.env.APP_PORT, 10) || 3006,
    env: process.env.NODE_ENV || 'development',
    apiPrefix: process.env.API_PREFIX || 'api/v1',

    database: {
      url: process.env.DATABASE_URL,
    },

    redis: {
      host: process.env.REDIS_HOST,
      port: parseInt(process.env.REDIS_PORT, 10) || 6379,
    },

    mpc: {
      coordinatorUrl: process.env.MPC_COORDINATOR_URL,
      messageRouterWsUrl: process.env.MPC_MESSAGE_ROUTER_WS_URL,
      partyId: process.env.MPC_PARTY_ID,
    },

    security: {
      jwtSecret: process.env.JWT_SECRET,
      shareMasterKey: process.env.SHARE_MASTER_KEY,
    },
  }),
];
```

## 监控与可观测性

### 1. 日志

使用 NestJS Logger，支持结构化日志：

```typescript
private readonly logger = new Logger(MPCPartyController.name);

this.logger.log(`Keygen request: session=${sessionId}, party=${partyId}`);
this.logger.error(`Keygen failed: ${error.message}`, error.stack);
```

### 2. 健康检查

```typescript
@Get('health')
health() {
  return {
    status: 'ok',
    timestamp: new Date().toISOString(),
    service: 'mpc-party-service',
  };
}
```

### 3. 指标（待实现）

- 请求延迟
- 错误率
- MPC 协议执行时间
- 分片操作统计

## 依赖关系图

```
┌─────────────────────────────────────────────────────────────┐
│                         AppModule                            │
├─────────────────────────────────────────────────────────────┤
│  imports:                                                    │
│    ├── ConfigModule (global)                                │
│    ├── JwtModule (global)                                   │
│    ├── DomainModule                                         │
│    ├── InfrastructureModule                                 │
│    ├── ApplicationModule                                    │
│    └── ApiModule                                            │
│                                                              │
│  providers:                                                  │
│    ├── GlobalExceptionFilter                                │
│    ├── TransformInterceptor                                 │
│    └── JwtAuthGuard                                         │
└─────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  DomainModule   │  │Infrastructure   │  │ApplicationModule│
│                 │  │    Module       │  │                 │
│ - Encryption    │◄─┤ - Prisma        │◄─┤ - Handlers      │
│   Service       │  │ - Redis         │  │ - AppService    │
│ - TSS Service   │  │ - Kafka         │  │                 │
│   (interface)   │  │ - Clients       │  │                 │
└─────────────────┘  └─────────────────┘  └─────────────────┘
                              │
                              ▼
                     ┌─────────────────┐
                     │    ApiModule    │
                     │                 │
                     │ - Controllers   │
                     │ - DTOs          │
                     └─────────────────┘
```

## 总结

MPC Party Service 采用清晰的分层架构，遵循 DDD 和 CQRS 原则，实现了：

1. **高内聚低耦合**：各层职责明确，依赖于抽象
2. **可测试性**：依赖注入使得单元测试和集成测试易于实现
3. **可扩展性**：插件化设计支持不同的 TSS 协议和基础设施
4. **安全性**：多层安全措施保护敏感的密钥分片
5. **可观测性**：完善的日志和健康检查支持运维监控