# 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/)