13 KiB

Raw Blame History

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   │
                    │  (分布式密钥生成)       │
                    └─────────────────────────┘

典型使用流程

管理员 在 Admin Web 创建共管钱包会话，配置阈值 (如 2-of-3)
管理员 生成邀请二维码，分享给参与方
参与方 在各自电脑上打开 Service Party App，扫描二维码加入
所有参与方就绪后，自动开始 TSS 密钥生成协议
完成后，每个参与方本地保存自己的加密 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？

稳定性: tss-lib 是复杂的密码学库，Go 原生执行比 WASM 更稳定
性能: 原生执行性能优于 WASM
兼容性: 避免 WASM 在不同平台的兼容性问题
调试: 更容易调试和排查问题

┌──────────────────────────────────────────────────────────────┐
│                 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 消息通信：

// 发送给 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 加密后存储在本地：

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 子进程

# 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 .

开发模式

cd backend/mpc-system/services/service-party-app

# 安装依赖
npm install

# 启动开发服务器
npm run dev

生产构建

# 构建前端
npm run build

# 打包 Electron 应用
npm run package

# 输出目录: dist/

安全考虑

本地加密: Share 使用 AES-256-GCM 加密存储
密钥派生: 加密密钥由用户密码通过 PBKDF2 派生
内存保护: Share 在内存中的时间尽量短
安全删除: 删除 share 时安全擦除

网络安全

TLS 加密: 与 Message Router 的 gRPC 连接使用 TLS
消息签名: MPC 消息包含签名验证
会话隔离: 每个会话使用独立的密钥对

应用安全

代码签名: 发布的应用经过代码签名
自动更新: 支持安全的自动更新机制
沙箱隔离: Electron 渲染进程在沙箱中运行

与现有系统的集成

与 Message Router 的通信

Service Party App
       │
       │ gRPC (TLS)
       ▼
┌─────────────────────┐
│   Message Router    │
│  ┌───────────────┐  │
│  │ RegisterParty │  │ ← 注册为参与方
│  │ Heartbeat     │  │ ← 心跳保活
│  │ JoinSession   │  │ ← 加入会话
│  │ Subscribe     │  │ ← 订阅消息
│  │ RouteMessage  │  │ ← 发送消息
│  │ ReportDone    │  │ ← 报告完成
│  └───────────────┘  │
└─────────────────────┘

与 Admin Web 的协作

Admin Web 创建 co_managed_keygen 类型的会话
Session Coordinator 生成邀请码
Admin Web 显示邀请二维码
Service Party App 扫码获取会话信息
双方通过 Message Router 交换 MPC 消息
完成后各自获得结果

未来扩展

签名功能

当前版本仅支持密钥生成，未来将支持：

参与门限签名
支持多种签名算法 (ECDSA, EdDSA)
批量签名

密钥刷新

支持 share 刷新而不改变公钥
支持增加/减少参与方

硬件钱包集成

支持将 share 存储在硬件安全模块
支持 Ledger/Trezor 等硬件钱包

13 KiB Raw Blame History Unescape Escape