docs: 添加 Service Party App 技术文档
添加分布式共管钱包桌面应用的详细技术文档，包括： - 应用概述和使用场景 - 目录结构说明 - 技术架构和技术栈 - TSS 子进程架构设计 - IPC 消息格式定义 - 核心功能说明 - 编译与运行指南 - 安全考虑 - 系统集成说明 - 未来扩展规划 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
cc3644de9d
commit
8df2046a4e
|
|
@ -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/)
|
||||
Loading…
Reference in New Issue