hailin
/
rwadurian
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
rwadurian/docs/co-managed-wallet-implement...

11 KiB
Raw Blame History

分布式多方共管钱包创建功能实现计划

概述

为 RWADurian 项目实现分布式多方共管钱包创建功能，包括：

  1. Admin-Web 扩展: 在授权管理页面添加创建共管钱包入口
  2. Service-Party 桌面应用: 跨平台 Electron 应用，用户可在各自电脑上参与钱包创建

系统架构

+-------------------+         +-------------------+         +-------------------+
|   Admin Web       |         |  Service Party    |         |  Service Party    |
|   (发起者/管理员) |         |  Desktop App #1   |         |  Desktop App #2   |
+--------+----------+         +--------+----------+         +--------+----------+
         |                             |                             |
         | HTTP/WebSocket              | gRPC                        | gRPC
         |                             |                             |
         v                             v                             v
+--------+-----------------------------+-----------------------------+----------+
|                     Message Router (现有 gRPC 服务)                           |
|              backend/mpc-system/services/message-router                       |
+--------+-----------------------------+-----------------------------+----------+
         |                             |                             |
         v                             v                             v
+-------------------+         +----------------------------------------+
| Session           |         |   TSS Keygen Protocol (分布式执行)     |
| Coordinator       |         |   所有参与方通过 Message Router 交换消息|
+-------------------+         +----------------------------------------+

第一阶段：Admin-Web 扩展

1.1 修改授权管理页面

文件: frontend/admin-web/src/app/(dashboard)/authorization/page.tsx

添加"创建共管钱包"卡片区域：

  • 配置钱包名称
  • 配置阈值 (T-of-N)
  • 生成邀请链接/二维码
  • 实时显示参与方加入状态

1.2 新增组件

目录: frontend/admin-web/src/components/features/co-managed-wallet/

文件 功能
CreateWalletModal.tsx 创建钱包向导对话框
ThresholdConfig.tsx 阈值配置 (T-of-N)
InviteQRCode.tsx 邀请二维码生成
ParticipantList.tsx 参与方列表实时状态
SessionProgress.tsx Keygen 进度显示
WalletResult.tsx 创建结果展示

1.3 新增 API 服务

文件: frontend/admin-web/src/services/coManagedWalletService.ts

export const coManagedWalletService = {
  // 创建共管钱包会话
  createSession(params: {
    walletName: string;
    thresholdT: number;
    thresholdN: number;
  }): Promise<SessionResponse>;

  // 获取会话状态
  getSessionStatus(sessionId: string): Promise<SessionStatus>;

  // WebSocket 订阅会话更新
  subscribeSession(sessionId: string, onUpdate: (status: SessionStatus) => void): () => void;
};

1.4 新增 React Query Hooks

文件: frontend/admin-web/src/hooks/useCoManagedWallet.ts

export function useCreateCoManagedWallet();
export function useCoManagedWalletSession(sessionId: string);
export function useCoManagedWalletList();

第二阶段：Service-Party 桌面应用

2.1 项目结构

新项目目录: backend/mpc-system/services/service-party-app/

backend/mpc-system/services/service-party-app/
├── electron/
│   ├── main.ts                 # Electron 主进程
│   ├── preload.ts              # 预加载脚本
│   └── modules/
│       ├── grpc-client.ts      # gRPC 客户端 (连接 Message Router)
│       ├── tss-handler.ts      # TSS 协议处理
│       ├── storage.ts          # 本地加密存储
│       └── server.ts           # 内置 HTTP 服务器
├── src/
│   ├── App.tsx
│   ├── pages/
│   │   ├── Home.tsx            # 主页 - Share 列表
│   │   ├── Join.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
├── wasm/
│   └── tss_lib.wasm            # TSS 库 WASM 编译版
├── package.json
├── electron-builder.json       # Electron 打包配置
└── tsconfig.json

2.2 技术选型

组件 技术 说明
桌面框架 Electron 28+ 跨平台支持 Windows/Mac/Linux
前端框架 React 18 + TypeScript 与 admin-web 保持一致
状态管理 Zustand 轻量级状态管理
gRPC 客户端 @grpc/grpc-js Node.js gRPC 实现
TSS 协议 Go -> WASM 编译 tss-lib 到 WebAssembly
本地存储 electron-store 加密本地存储
加密 Node.js crypto AES-256-GCM 加密
打包 electron-builder 多平台打包

2.3 核心功能实现

gRPC 客户端模块

文件: electron/modules/grpc-client.ts

连接到现有 Message Router，实现以下接口：

  • RegisterParty() - 注册为参与方
  • Heartbeat() - 心跳保活
  • SubscribeSessionEvents() - 订阅会话事件
  • JoinSession() - 加入会话
  • SubscribeMessages() - 订阅 MPC 消息
  • RouteMessage() - 发送 MPC 消息
  • ReportCompletion() - 报告完成

TSS 协议处理

文件: electron/modules/tss-handler.ts

参考现有实现: backend/mpc-system/services/server-party/application/use_cases/participate_keygen.go

class TSSHandler {
  // 参与 keygen
  async participateKeygen(sessionInfo: SessionInfo): Promise<KeygenResult>;

  // 参与 signing (未来扩展)
  async participateSigning(sessionInfo: SessionInfo, messageHash: string): Promise<SignResult>;
}

本地加密存储

文件: electron/modules/storage.ts

interface ShareEntry {
  id: string;
  sessionId: string;
  walletName: string;
  partyId: string;
  partyIndex: number;
  threshold: { t: number; n: number };
  publicKey: string;
  encryptedShare: string;  // AES-256-GCM 加密
  createdAt: string;
  metadata: {
    participants: Array<{ partyId: string; name: string }>;
  };
}

class SecureStorage {
  saveShare(share: ShareEntry, password: string): void;
  loadShare(id: string, password: string): ShareEntry;
  listShares(): ShareEntry[];
  exportShare(id: string, password: string): Buffer;  // 加密导出文件
  importShare(data: Buffer, password: string): ShareEntry;
}

2.4 用户界面

主页 (Share 列表)

  • 显示已保存的 share 列表
  • 每个 share 显示：钱包名称、公钥、创建时间、参与方数量
  • 操作：导出备份、删除

加入会话页面

  • 输入/粘贴邀请链接
  • 或扫描二维码 (使用摄像头)
  • 输入参与者名称
  • 显示会话信息确认

会话进度页面

  • 显示当前状态：等待其他参与方 / Keygen 进行中 / 完成
  • 参与方列表及其状态
  • 进度条显示 Keygen 轮次

设置页面

  • Message Router 连接地址配置
  • 存储密码管理
  • 自动备份设置

第三阶段：后端扩展

3.1 Admin-Service API 扩展

目录: backend/services/admin-service/src/modules/co-managed-wallet/

文件 功能
co-managed-wallet.module.ts 模块定义
co-managed-wallet.controller.ts REST 控制器
co-managed-wallet.service.ts 业务逻辑
co-managed-wallet.gateway.ts WebSocket 网关

API 端点:

POST   /api/v1/co-managed-wallets/sessions
       创建共管钱包会话

GET    /api/v1/co-managed-wallets/sessions/:id
       获取会话状态

GET    /api/v1/co-managed-wallets
       获取共管钱包列表

WebSocket /co-managed-wallets/:sessionId
       实时会话状态推送

3.2 Session Coordinator 扩展

文件: backend/mpc-system/services/session-coordinator/application/use_cases/create_co_managed_session.go

扩展现有 create_session.go，支持：

  • co_managed_keygen 会话类型
  • 邀请码生成
  • 参与方名称管理

实现步骤

Step 1: Admin-Web 基础 UI (2-3天)

  1. 在 authorization 页面添加"共管钱包"卡片
  2. 实现 CreateWalletModal 组件
  3. 实现阈值配置 UI

Step 2: 后端 API (2-3天)

  1. 实现 admin-service 的共管钱包 API
  2. 扩展 Session Coordinator 支持新会话类型
  3. 实现 WebSocket 状态推送

Step 3: Admin-Web 完善 (2天)

  1. 实现邀请链接/二维码生成
  2. 实现参与方列表实时更新
  3. 实现会话状态显示

Step 4: Service-Party 脚手架 (2天)

  1. 创建 Electron 项目结构
  2. 配置 React + TypeScript
  3. 实现基础 UI 框架

Step 5: gRPC 集成 (3天)

  1. 复制 proto 文件
  2. 实现 gRPC 客户端
  3. 实现会话订阅和消息处理

Step 6: TSS 集成 (5天)

  1. 编译 tss-lib 到 WASM
  2. 实现 TSS 协议处理器
  3. 集成到 Electron 应用

Step 7: 本地存储 (2天)

  1. 实现加密存储模块
  2. 实现导出/导入功能
  3. 实现备份下载

Step 8: 测试与优化 (3天)

  1. 端到端测试
  2. 多机/多网络测试
  3. 错误处理优化

关键文件清单

需要修改的现有文件

文件路径 修改内容
frontend/admin-web/src/app/(dashboard)/authorization/page.tsx 添加共管钱包入口卡片
frontend/admin-web/src/infrastructure/api/endpoints.ts 添加共管钱包 API 端点
backend/mpc-system/services/session-coordinator/domain/entities/session.go 扩展会话类型

需要新增的文件

文件路径 说明
frontend/admin-web/src/components/features/co-managed-wallet/* 前端组件 (6个文件)
frontend/admin-web/src/services/coManagedWalletService.ts API 服务
frontend/admin-web/src/hooks/useCoManagedWallet.ts React Query Hooks
backend/mpc-system/services/service-party-app/* 整个桌面应用项目
backend/services/admin-service/src/modules/co-managed-wallet/* 后端模块 (4个文件)

技术风险与解决方案

风险1: TSS 库编译到 WASM

问题: Go 的 tss-lib 使用了大量加密原语，编译到 WASM 可能有兼容性问题

解决方案:

  • 优先尝试 TinyGo 编译
  • 备选方案：编译为动态库 (.dll/.so/.dylib)，通过 ffi-napi 调用

风险2: 网络连通性

问题: 参与方可能在 NAT 后或防火墙内

解决方案:

  • Message Router 部署在公网，所有客户端主动连接
  • gRPC 使用 HTTP/2，对防火墙友好
  • 实现断线重连和消息重发

风险3: Share 安全

问题: 本地存储的 share 可能被恶意软件窃取

解决方案:

  • AES-256-GCM 加密，密钥由用户密码派生 (PBKDF2)
  • 可选集成硬件安全密钥
  • 提醒用户备份到安全位置

预计工时

阶段 工时
Admin-Web 扩展 5-7天
Service-Party 桌面应用 12-15天
后端扩展 3-4天
测试与优化 3-5天
总计 23-31天