340 lines
13 KiB
Markdown
340 lines
13 KiB
Markdown
# 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/)
|