373 lines
11 KiB
Markdown
373 lines
11 KiB
Markdown
# 分布式多方共管钱包创建功能实现计划
|
||
|
||
## 概述
|
||
|
||
为 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天** |
|