---
title: "Cosigner 架构"
description: "Cosigner 架构：组件、传输通道、信任边界以及 MPC 会话生命周期。"
url: https://docs.fystack.io/zh/cosigner/architecture
last_updated: 2026-11-13
---

> ## Documentation index
> Fetch the complete documentation index at: https://docs.fystack.io/llms.txt
> Use it to discover all available pages before exploring further.

# Cosigner 架构

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

_Diagram: Cosigner 架构概览_

## 组件

### Cosigner 运行时

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

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

### 你的服务

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

### Fystack 服务

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

## 通道

| 发送方 → 接收方 | 传输方式 | 认证 | 承载内容 |
| --- | --- | --- | --- |
| 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**：无法单独签名。签名委员会在密钥生成时即已固定。

详情请参阅[安全模型](https://docs.fystack.io/cosigner/security.md)。

## 会话

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

_Diagram: 会话状态：created、waiting、key_exchange、active_mpc、completed，以及 failed 和 expired_

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` 并停止运行。