Cosigner 架构

各组件运行在哪里、彼此如何通信，以及会话如何协调。

Cosigner 架构概览
Click to open the full-size diagram

组件

Cosigner 运行时

一个 Go 二进制文件，以 ghcr.io/fystack/cosigner 发布，支持 linux/amd64 和 linux/arm64。它只加入会话，不负责协调会话。

  • MPC 引擎：Fystack 的 tss-lib 分支，与 MPCium 相同。ECDSA 在 secp256k1 上使用 GG18。EdDSA 使用 tss-lib 的门限 Ed25519。
  • 身份密钥：Ed25519，在配对时创建。用于认证 cosigner 并签名其消息。
  • 密钥存储：以 AES-256-GCM 加密的记录，存储在 SQLite（默认）、Badger 或 DynamoDB 中。
  • Gateway 中继：一条出站 gRPC 流。每 5 秒发送一次在线状态。
  • 审批客户端：在每个会话开始前调用你的审批回调。
  • 审计日志：经过签名、哈希链式连接的 JSONL。

你的服务

  • cosigner-cli：负责安装、校验、配对、启动和备份运行时。
  • 审批回调：你的 HTTPS 服务器。返回 approve 或 reject。
  • 存储密钥来源：密码（manual 配置）或 AWS KMS（unattended 配置）。

Fystack 服务

  • Apex：签发配对 token、注册 cosigner 密钥、处理吊销并提交 MPC 请求。
  • Gateway：接收 cosigner 流，检查身份和吊销状态，并将流量桥接到 NATS。在所有副本中，每个 cosigner 只有一条活动流。
  • Orchestrator：运行会话状态机并签名每条控制消息。从不接触密钥分片。
  • MPCium：Fystack 的 MPC 节点。请参阅 MPCium。

通道

发送方 → 接收方 传输方式 认证 承载内容
Cosigner → Apex HTTPS 一次性配对 token 身份注册
Cosigner ↔ Gateway gRPC 流，TLS EdDSA JWT，有效期 60 秒 全部会话流量
Gateway ↔ Orchestrator ↔ MPCium NATS 每条消息使用 Ed25519 Fystack 内部协调
参与方 ↔ 参与方 中继转发 X25519 + ChaCha20-Poly1305 MPC 轮次，端到端加密
Cosigner → Callback HTTPS 双向 RS256 JWT 批准或拒绝

流信封

每一帧都携带经过认证的 workspace_id、cosigner_id 和 participant_id。Gateway 会丢弃与流身份不匹配的帧。

类型 方向 主题
CONTROL Orchestrator → cosigner mpc.v1.peer.<participant_id>.control
SESSION_EVENT Cosigner → orchestrator mpc.v1.session.<session_id>.event
P2P 参与方 ↔ 参与方 mpc.v1.peer.<to>.session.<session_id>.p2p
PRESENCE Cosigner → orchestrator mpc.v1.peer.<participant_id>.presence

信任边界

  • Gateway：中继密文。可以丢弃或延迟流量，但无法读取或伪造 MPC 消息。
  • Orchestrator：使用 cosigner 在配对时固定的密钥签名每条控制消息。未签名或签名错误的消息会被丢弃。
  • Apex：无法跳过你的回调。每个会话都会先经过你的回调。
  • 你的 cosigner：无法单独签名。签名委员会在密钥生成时即已固定。

详情请参阅安全模型。

会话

每次密钥生成、签名或重新分享都是一个 orchestrator 会话，TTL 为 120 秒。

会话状态：created、waiting、key_exchange、active_mpc、completed，以及 failed 和 expired
Click to open the full-size diagram
  1. 准入：Orchestrator 校验 Apex 签名、检查委员会，并确认每个参与方都在线。每个钱包和协议同一时间只能有一个会话。
  2. waiting：参与方收到已签名的 session_start，执行本地检查（cosigner 会调用你的回调），然后回复 peer_joined、peer_ready。
  3. key_exchange：参与方交换已签名的 X25519 密钥。配置了审批方的钱包还需要在此阶段获得其签名的批准。
  4. active_mpc：Orchestrator 发送 mpc_begin。参与方直接运行 tss-lib 轮次。
  5. completed：所有参与方报告相同的结果哈希。Orchestrator 签名并发布结果。

当参与方出错、断开连接或结果不一致时，会话会失败；超过 120 秒则会过期。无论哪种情况，orchestrator 都会广播一条已签名的 session_abort。

委员会

门限 t 表示需要 t + 1 个签名方（tss-lib 语义）。由 MPCium 节点和 cosigner 组成的委员会在密钥生成时即已固定。之后的每个会话都必须使用相同的参与方密钥、身份密钥和审批方角色。

连接

  • 每个 cosigner 身份只有一条活动流。使用相同身份的第二个实例会被拒绝。
  • 每个会话都绑定到其启动时处于活动状态的流。如果该流断开，会话将以 PARTICIPANT_DISCONNECTED 失败。
  • 已被吊销的 cosigner 会收到 PermissionDenied 并停止运行。