# 分布式多方共管钱包创建功能实现计划

## 概述

为 RWADurian 项目实现分布式多方共管钱包创建功能，包括：
1. **Admin-Web 扩展**: 在授权管理页面添加创建共管钱包入口
2. **Service-Party 桌面应用**: 跨平台 Electron 应用，用户可在各自电脑上参与钱包创建

## 系统架构

```
+-------------------+         +-------------------+         +-------------------+
|   Admin Web       |         |  Service Party    |         |  Service Party    |
|   (发起者/管理员) |         |  Desktop App #1   |         |  Desktop App #2   |
+--------+----------+         +--------+----------+         +--------+----------+
         |                             |                             |
         | HTTP/WebSocket              | gRPC                        | gRPC
         |                             |                             |
         v                             v                             v
+--------+-----------------------------+-----------------------------+----------+
|                     Message Router (现有 gRPC 服务)                           |
|              backend/mpc-system/services/message-router                       |
+--------+-----------------------------+-----------------------------+----------+
         |                             |                             |
         v                             v                             v
+-------------------+         +----------------------------------------+
| Session           |         |   TSS Keygen Protocol (分布式执行)     |
| Coordinator       |         |   所有参与方通过 Message Router 交换消息|
+-------------------+         +----------------------------------------+
```

## 第一阶段：Admin-Web 扩展

### 1.1 修改授权管理页面

**文件**: `frontend/admin-web/src/app/(dashboard)/authorization/page.tsx`

添加"创建共管钱包"卡片区域：
- 配置钱包名称
- 配置阈值 (T-of-N)
- 生成邀请链接/二维码
- 实时显示参与方加入状态

### 1.2 新增组件

**目录**: `frontend/admin-web/src/components/features/co-managed-wallet/`

| 文件 | 功能 |
|------|------|
| `CreateWalletModal.tsx` | 创建钱包向导对话框 |
| `ThresholdConfig.tsx` | 阈值配置 (T-of-N) |
| `InviteQRCode.tsx` | 邀请二维码生成 |
| `ParticipantList.tsx` | 参与方列表实时状态 |
| `SessionProgress.tsx` | Keygen 进度显示 |
| `WalletResult.tsx` | 创建结果展示 |

### 1.3 新增 API 服务

**文件**: `frontend/admin-web/src/services/coManagedWalletService.ts`

```typescript
export const coManagedWalletService = {
  // 创建共管钱包会话
  createSession(params: {
    walletName: string;
    thresholdT: number;
    thresholdN: number;
  }): Promise<SessionResponse>;

  // 获取会话状态
  getSessionStatus(sessionId: string): Promise<SessionStatus>;

  // WebSocket 订阅会话更新
  subscribeSession(sessionId: string, onUpdate: (status: SessionStatus) => void): () => void;
};
```

### 1.4 新增 React Query Hooks

**文件**: `frontend/admin-web/src/hooks/useCoManagedWallet.ts`

```typescript
export function useCreateCoManagedWallet();
export function useCoManagedWalletSession(sessionId: string);
export function useCoManagedWalletList();
```

---

## 第二阶段：Service-Party 桌面应用

### 2.1 项目结构

**新项目目录**: `backend/mpc-system/services/service-party-app/`

```
backend/mpc-system/services/service-party-app/
├── electron/
│   ├── main.ts                 # Electron 主进程
│   ├── preload.ts              # 预加载脚本
│   └── modules/
│       ├── grpc-client.ts      # gRPC 客户端 (连接 Message Router)
│       ├── tss-handler.ts      # TSS 协议处理
│       ├── storage.ts          # 本地加密存储
│       └── server.ts           # 内置 HTTP 服务器
├── src/
│   ├── App.tsx
│   ├── pages/
│   │   ├── Home.tsx            # 主页 - Share 列表
│   │   ├── Join.tsx            # 加入会话页面
│   │   ├── Session.tsx         # 会话进度页面
│   │   └── Settings.tsx        # 设置页面
│   ├── components/
│   │   ├── ShareCard.tsx       # Share 卡片
│   │   ├── JoinForm.tsx        # 加入会话表单
│   │   ├── ProgressSteps.tsx   # 进度步骤
│   │   ├── ExportDialog.tsx    # 导出对话框
│   │   └── ImportDialog.tsx    # 导入对话框
│   └── hooks/
│       ├── useGrpc.ts          # gRPC 连接 Hook
│       ├── useSession.ts       # 会话状态 Hook
│       └── useStorage.ts       # 本地存储 Hook
├── wasm/
│   └── tss_lib.wasm            # TSS 库 WASM 编译版
├── package.json
├── electron-builder.json       # Electron 打包配置
└── tsconfig.json
```

### 2.2 技术选型

| 组件 | 技术 | 说明 |
|------|------|------|
| 桌面框架 | Electron 28+ | 跨平台支持 Windows/Mac/Linux |
| 前端框架 | React 18 + TypeScript | 与 admin-web 保持一致 |
| 状态管理 | Zustand | 轻量级状态管理 |
| gRPC 客户端 | @grpc/grpc-js | Node.js gRPC 实现 |
| TSS 协议 | Go -> WASM | 编译 tss-lib 到 WebAssembly |
| 本地存储 | electron-store | 加密本地存储 |
| 加密 | Node.js crypto | AES-256-GCM 加密 |
| 打包 | electron-builder | 多平台打包 |

### 2.3 核心功能实现

#### gRPC 客户端模块

**文件**: `electron/modules/grpc-client.ts`

连接到现有 Message Router，实现以下接口：
- `RegisterParty()` - 注册为参与方
- `Heartbeat()` - 心跳保活
- `SubscribeSessionEvents()` - 订阅会话事件
- `JoinSession()` - 加入会话
- `SubscribeMessages()` - 订阅 MPC 消息
- `RouteMessage()` - 发送 MPC 消息
- `ReportCompletion()` - 报告完成

#### TSS 协议处理

**文件**: `electron/modules/tss-handler.ts`

参考现有实现: `backend/mpc-system/services/server-party/application/use_cases/participate_keygen.go`

```typescript
class TSSHandler {
  // 参与 keygen
  async participateKeygen(sessionInfo: SessionInfo): Promise<KeygenResult>;

  // 参与 signing (未来扩展)
  async participateSigning(sessionInfo: SessionInfo, messageHash: string): Promise<SignResult>;
}
```

#### 本地加密存储

**文件**: `electron/modules/storage.ts`

```typescript
interface ShareEntry {
  id: string;
  sessionId: string;
  walletName: string;
  partyId: string;
  partyIndex: number;
  threshold: { t: number; n: number };
  publicKey: string;
  encryptedShare: string;  // AES-256-GCM 加密
  createdAt: string;
  metadata: {
    participants: Array<{ partyId: string; name: string }>;
  };
}

class SecureStorage {
  saveShare(share: ShareEntry, password: string): void;
  loadShare(id: string, password: string): ShareEntry;
  listShares(): ShareEntry[];
  exportShare(id: string, password: string): Buffer;  // 加密导出文件
  importShare(data: Buffer, password: string): ShareEntry;
}
```

### 2.4 用户界面

#### 主页 (Share 列表)
- 显示已保存的 share 列表
- 每个 share 显示：钱包名称、公钥、创建时间、参与方数量
- 操作：导出备份、删除

#### 加入会话页面
- 输入/粘贴邀请链接
- 或扫描二维码 (使用摄像头)
- 输入参与者名称
- 显示会话信息确认

#### 会话进度页面
- 显示当前状态：等待其他参与方 / Keygen 进行中 / 完成
- 参与方列表及其状态
- 进度条显示 Keygen 轮次

#### 设置页面
- Message Router 连接地址配置
- 存储密码管理
- 自动备份设置

---

## 第三阶段：后端扩展

### 3.1 Admin-Service API 扩展

**目录**: `backend/services/admin-service/src/modules/co-managed-wallet/`

| 文件 | 功能 |
|------|------|
| `co-managed-wallet.module.ts` | 模块定义 |
| `co-managed-wallet.controller.ts` | REST 控制器 |
| `co-managed-wallet.service.ts` | 业务逻辑 |
| `co-managed-wallet.gateway.ts` | WebSocket 网关 |

**API 端点**:

```
POST   /api/v1/co-managed-wallets/sessions
       创建共管钱包会话

GET    /api/v1/co-managed-wallets/sessions/:id
       获取会话状态

GET    /api/v1/co-managed-wallets
       获取共管钱包列表

WebSocket /co-managed-wallets/:sessionId
       实时会话状态推送
```

### 3.2 Session Coordinator 扩展

**文件**: `backend/mpc-system/services/session-coordinator/application/use_cases/create_co_managed_session.go`

扩展现有 `create_session.go`，支持：
- `co_managed_keygen` 会话类型
- 邀请码生成
- 参与方名称管理

---

## 实现步骤

### Step 1: Admin-Web 基础 UI (2-3天)
1. 在 authorization 页面添加"共管钱包"卡片
2. 实现 CreateWalletModal 组件
3. 实现阈值配置 UI

### Step 2: 后端 API (2-3天)
1. 实现 admin-service 的共管钱包 API
2. 扩展 Session Coordinator 支持新会话类型
3. 实现 WebSocket 状态推送

### Step 3: Admin-Web 完善 (2天)
1. 实现邀请链接/二维码生成
2. 实现参与方列表实时更新
3. 实现会话状态显示

### Step 4: Service-Party 脚手架 (2天)
1. 创建 Electron 项目结构
2. 配置 React + TypeScript
3. 实现基础 UI 框架

### Step 5: gRPC 集成 (3天)
1. 复制 proto 文件
2. 实现 gRPC 客户端
3. 实现会话订阅和消息处理

### Step 6: TSS 集成 (5天)
1. 编译 tss-lib 到 WASM
2. 实现 TSS 协议处理器
3. 集成到 Electron 应用

### Step 7: 本地存储 (2天)
1. 实现加密存储模块
2. 实现导出/导入功能
3. 实现备份下载

### Step 8: 测试与优化 (3天)
1. 端到端测试
2. 多机/多网络测试
3. 错误处理优化

---

## 关键文件清单

### 需要修改的现有文件

| 文件路径 | 修改内容 |
|----------|----------|
| `frontend/admin-web/src/app/(dashboard)/authorization/page.tsx` | 添加共管钱包入口卡片 |
| `frontend/admin-web/src/infrastructure/api/endpoints.ts` | 添加共管钱包 API 端点 |
| `backend/mpc-system/services/session-coordinator/domain/entities/session.go` | 扩展会话类型 |

### 需要新增的文件

| 文件路径 | 说明 |
|----------|------|
| `frontend/admin-web/src/components/features/co-managed-wallet/*` | 前端组件 (6个文件) |
| `frontend/admin-web/src/services/coManagedWalletService.ts` | API 服务 |
| `frontend/admin-web/src/hooks/useCoManagedWallet.ts` | React Query Hooks |
| `backend/mpc-system/services/service-party-app/*` | 整个桌面应用项目 |
| `backend/services/admin-service/src/modules/co-managed-wallet/*` | 后端模块 (4个文件) |

---

## 技术风险与解决方案

### 风险1: TSS 库编译到 WASM

**问题**: Go 的 tss-lib 使用了大量加密原语，编译到 WASM 可能有兼容性问题

**解决方案**:
- 优先尝试 TinyGo 编译
- 备选方案：编译为动态库 (.dll/.so/.dylib)，通过 ffi-napi 调用

### 风险2: 网络连通性

**问题**: 参与方可能在 NAT 后或防火墙内

**解决方案**:
- Message Router 部署在公网，所有客户端主动连接
- gRPC 使用 HTTP/2，对防火墙友好
- 实现断线重连和消息重发

### 风险3: Share 安全

**问题**: 本地存储的 share 可能被恶意软件窃取

**解决方案**:
- AES-256-GCM 加密，密钥由用户密码派生 (PBKDF2)
- 可选集成硬件安全密钥
- 提醒用户备份到安全位置

---

## 预计工时

| 阶段 | 工时 |
|------|------|
| Admin-Web 扩展 | 5-7天 |
| Service-Party 桌面应用 | 12-15天 |
| 后端扩展 | 3-4天 |
| 测试与优化 | 3-5天 |
| **总计** | **23-31天** |