diff --git a/docs/service-party-app.md b/docs/service-party-app.md new file mode 100644 index 00000000..e0dc8273 --- /dev/null +++ b/docs/service-party-app.md @@ -0,0 +1,339 @@ +# Service Party App - 分布式共管钱包桌面应用 + +## 概述 + +Service Party App 是一个**跨平台 Electron 桌面应用**，用于参与分布式多方共管钱包的创建和签名过程。用户可以在各自的电脑上运行此应用，通过扫描邀请二维码加入共管钱包创建会话，参与 TSS (Threshold Signature Scheme) 密钥生成协议。 + +## 应用场景 + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ Admin Web │ │ Service Party │ │ Service Party │ +│ (管理员电脑) │ │ App (用户A电脑) │ │ App (用户B电脑) │ +└────────┬────────┘ └────────┬────────┘ └────────┬────────┘ + │ │ │ + │ 创建会话/生成邀请码 │ 扫码加入 │ 扫码加入 + │ │ │ + └───────────────────────┼───────────────────────┘ + │ + ┌────────────┴────────────┐ + │ Message Router │ + │ (gRPC 消息路由) │ + └────────────┬────────────┘ + │ + ┌────────────┴────────────┐ + │ TSS Keygen Protocol │ + │ (分布式密钥生成) │ + └─────────────────────────┘ +``` + +### 典型使用流程 + +1. **管理员** 在 Admin Web 创建共管钱包会话，配置阈值 (如 2-of-3) +2. **管理员** 生成邀请二维码，分享给参与方 +3. **参与方** 在各自电脑上打开 Service Party App，扫描二维码加入 +4. **所有参与方就绪后**，自动开始 TSS 密钥生成协议 +5. **完成后**，每个参与方本地保存自己的加密 share，管理员获得钱包公钥 + +## 目录结构 + +``` +backend/mpc-system/services/service-party-app/ +├── electron/ # Electron 主进程 +│ ├── main.ts # 主进程入口 +│ ├── preload.ts # 预加载脚本 (安全 IPC) +│ └── modules/ +│ ├── grpc-client.ts # gRPC 客户端 (连接 Message Router) +│ ├── tss-handler.ts # TSS 协议处理器 +│ └── storage.ts # 本地加密存储 (AES-256-GCM) +│ +├── src/ # React 前端 (渲染进程) +│ ├── App.tsx # 应用入口 +│ ├── pages/ +│ │ ├── Home.tsx # 主页 - Share 列表 +│ │ ├── Join.tsx # 加入会话页面 +│ │ ├── Create.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 +│ +├── tss-party/ # Go TSS 子进程 +│ ├── main.go # TSS 协议执行程序 +│ ├── go.mod # Go 模块定义 +│ └── go.sum # 依赖锁定 +│ +├── bin/ # 编译后的二进制文件 +│ ├── win32-x64/ +│ │ └── tss-party.exe +│ ├── darwin-x64/ +│ │ └── tss-party +│ └── linux-x64/ +│ └── tss-party +│ +├── package.json # Node.js 依赖 +├── electron-builder.json # Electron 打包配置 +├── tsconfig.json # TypeScript 配置 +└── vite.config.ts # Vite 构建配置 +``` + +## 技术架构 + +### 技术栈 + +| 组件 | 技术 | 说明 | +|------|------|------| +| 桌面框架 | Electron 28+ | 跨平台支持 Windows/Mac/Linux | +| 前端框架 | React 18 + TypeScript | 与 admin-web 保持一致 | +| 构建工具 | Vite | 快速开发和构建 | +| 状态管理 | Zustand | 轻量级状态管理 | +| gRPC 客户端 | @grpc/grpc-js | Node.js gRPC 实现 | +| TSS 协议 | Go 子进程 | 使用 bnb-chain/tss-lib | +| 本地存储 | electron-store | 加密本地存储 | +| 加密算法 | AES-256-GCM | Share 加密存储 | +| 打包工具 | electron-builder | 多平台打包 | + +### TSS 子进程架构 + +为什么使用 Go 子进程而不是 WASM？ + +1. **稳定性**: tss-lib 是复杂的密码学库，Go 原生执行比 WASM 更稳定 +2. **性能**: 原生执行性能优于 WASM +3. **兼容性**: 避免 WASM 在不同平台的兼容性问题 +4. **调试**: 更容易调试和排查问题 + +``` +┌──────────────────────────────────────────────────────────────┐ +│ Electron App (TypeScript) │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ tss-handler.ts │ │ +│ │ - 启动 Go 子进程 (spawn) │ │ +│ │ - stdin/stdout JSON 消息通信 │ │ +│ │ - 转发 gRPC 消息到子进程 │ │ +│ │ - 接收子进程输出并处理 │ │ +│ └───────────────────────┬────────────────────────────────┘ │ +└──────────────────────────┼───────────────────────────────────┘ + │ spawn + JSON IPC + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ tss-party (Go 子进程) │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ - 使用 bnb-chain/tss-lib v2 │ │ +│ │ - 执行 GG20 Keygen 协议 (4 轮) │ │ +│ │ - 通过 stdin 接收 MPC 消息 │ │ +│ │ - 通过 stdout 发送 MPC 消息 │ │ +│ │ - 完成后返回公钥 + 加密 share │ │ +│ └────────────────────────────────────────────────────────┘ │ +└──────────────────────────────────────────────────────────────┘ +``` + +### IPC 消息格式 + +Electron 主进程与 Go 子进程之间使用 JSON 消息通信： + +```typescript +// 发送给 Go 子进程的消息 +interface IncomingMessage { + type: 'incoming'; + fromPartyIndex: number; + isBroadcast: boolean; + payload: string; // base64 encoded +} + +// Go 子进程发出的消息 +interface OutgoingMessage { + type: 'outgoing' | 'result' | 'error' | 'progress'; + isBroadcast?: boolean; + toParties?: string[]; + payload?: string; // base64 encoded + publicKey?: string; // base64 encoded (result) + encryptedShare?: string; // base64 encoded (result) + partyIndex?: number; + round?: number; + totalRounds?: number; + error?: string; +} +``` + +## 核心功能 + +### 1. 加入会话 + +用户通过以下方式加入共管钱包创建会话： + +- **扫描二维码**: 使用摄像头扫描 Admin Web 生成的邀请二维码 +- **粘贴邀请链接**: 手动粘贴邀请链接 +- **输入邀请码**: 手动输入 6 位邀请码 + +### 2. TSS 密钥生成 + +参与 GG20 (Gennaro-Goldfeder 2020) 门限签名密钥生成协议： + +- 支持任意 T-of-N 阈值配置 +- 4 轮消息交换 +- 零知识证明保证安全性 +- 每个参与方获得自己的 share，无需信任其他方 + +### 3. 本地加密存储 + +Share 使用 AES-256-GCM 加密后存储在本地： + +```typescript +interface ShareEntry { + id: string; // Share 唯一标识 + sessionId: string; // 会话 ID + walletName: string; // 钱包名称 + partyId: string; // 参与方 ID + partyIndex: number; // 参与方索引 + threshold: { + t: number; // 签名阈值 + n: number; // 总参与方数 + }; + publicKey: string; // 钱包公钥 (hex) + encryptedShare: string; // AES-256-GCM 加密的 share + createdAt: string; // 创建时间 + metadata: { + participants: Array<{ + partyId: string; + name: string; + }>; + }; +} +``` + +### 4. 备份与恢复 + +- **导出备份**: 将加密的 share 导出为文件 +- **导入恢复**: 从备份文件恢复 share +- **密码保护**: 备份文件使用用户密码加密 + +## 编译与运行 + +### 前置条件 + +- Node.js 18+ +- Go 1.21+ +- pnpm 或 npm + +### 编译 TSS 子进程 + +```bash +# Windows +cd backend/mpc-system/services/service-party-app/tss-party +go build -o ../bin/win32-x64/tss-party.exe . + +# macOS +GOOS=darwin GOARCH=amd64 go build -o ../bin/darwin-x64/tss-party . + +# Linux +GOOS=linux GOARCH=amd64 go build -o ../bin/linux-x64/tss-party . +``` + +### 开发模式 + +```bash +cd backend/mpc-system/services/service-party-app + +# 安装依赖 +npm install + +# 启动开发服务器 +npm run dev +``` + +### 生产构建 + +```bash +# 构建前端 +npm run build + +# 打包 Electron 应用 +npm run package + +# 输出目录: dist/ +``` + +## 安全考虑 + +### Share 安全 + +1. **本地加密**: Share 使用 AES-256-GCM 加密存储 +2. **密钥派生**: 加密密钥由用户密码通过 PBKDF2 派生 +3. **内存保护**: Share 在内存中的时间尽量短 +4. **安全删除**: 删除 share 时安全擦除 + +### 网络安全 + +1. **TLS 加密**: 与 Message Router 的 gRPC 连接使用 TLS +2. **消息签名**: MPC 消息包含签名验证 +3. **会话隔离**: 每个会话使用独立的密钥对 + +### 应用安全 + +1. **代码签名**: 发布的应用经过代码签名 +2. **自动更新**: 支持安全的自动更新机制 +3. **沙箱隔离**: Electron 渲染进程在沙箱中运行 + +## 与现有系统的集成 + +### 与 Message Router 的通信 + +``` +Service Party App + │ + │ gRPC (TLS) + ▼ +┌─────────────────────┐ +│ Message Router │ +│ ┌───────────────┐ │ +│ │ RegisterParty │ │ ← 注册为参与方 +│ │ Heartbeat │ │ ← 心跳保活 +│ │ JoinSession │ │ ← 加入会话 +│ │ Subscribe │ │ ← 订阅消息 +│ │ RouteMessage │ │ ← 发送消息 +│ │ ReportDone │ │ ← 报告完成 +│ └───────────────┘ │ +└─────────────────────┘ +``` + +### 与 Admin Web 的协作 + +1. Admin Web 创建 `co_managed_keygen` 类型的会话 +2. Session Coordinator 生成邀请码 +3. Admin Web 显示邀请二维码 +4. Service Party App 扫码获取会话信息 +5. 双方通过 Message Router 交换 MPC 消息 +6. 完成后各自获得结果 + +## 未来扩展 + +### 签名功能 + +当前版本仅支持密钥生成，未来将支持： + +- 参与门限签名 +- 支持多种签名算法 (ECDSA, EdDSA) +- 批量签名 + +### 密钥刷新 + +- 支持 share 刷新而不改变公钥 +- 支持增加/减少参与方 + +### 硬件钱包集成 + +- 支持将 share 存储在硬件安全模块 +- 支持 Ledger/Trezor 等硬件钱包 + +## 相关文档 + +- [共管钱包实现计划](./co-managed-wallet-implementation-plan.md) +- [MPC 系统架构](./architecture/)