From e76b3d19e0bb3ce537d6bcb20bf0327e00be362f Mon Sep 17 00:00:00 2001 From: rcsh <163504257+rcsh1@users.noreply.github.com> Date: Fri, 19 Jun 2026 16:44:59 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=20TSS=20Node=20?= =?UTF-8?q?=E5=9B=9E=E8=B0=83=E4=B8=8E=20Webhook=20=E9=AA=8C=E7=AD=BE?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=B9=B6=E6=96=B0=E5=A2=9E=E6=9C=8D=E5=8A=A1?= =?UTF-8?q?=E7=AB=AF=E7=AD=BE=E5=90=8D=E4=BA=BA=E9=97=AE=E9=A2=98=E6=8E=92?= =?UTF-8?q?=E6=9F=A5=E9=A1=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 补充 TSS Node 回调 HTTP 响应要求与 request_type 事件类型说明， 新增 initiator_type 字段、Webhook 原始报文 Ed25519 验签警告， 澄清 check_policy 私钥分片验证风控需联系 Cobo， 并新增服务端签名人 (TypeKeyGen/node_ids) 问题排查页。 Co-Authored-By: Claude Opus 4.8 (1M context) --- docs.json | 2 ++ .../callback-server-data-structure.mdx | 35 ++++++++++++++++++- .../callback-server-overview.mdx | 17 +++++++++ .../server-co-signer/key-share-verify.mdx | 6 ++-- .../server-co-signer/troubleshooting.mdx | 31 ++++++++++++++++ .../webhooks-callbacks/set-up-endpoint.mdx | 4 +++ .../callback-server-data-structure.mdx | 32 +++++++++++++++++ .../callback-server-overview.mdx | 17 +++++++++ .../server-co-signer/key-share-verify.mdx | 6 ++-- .../server-co-signer/troubleshooting.mdx | 31 ++++++++++++++++ .../webhooks-callbacks/set-up-endpoint.mdx | 4 +++ 11 files changed, 178 insertions(+), 7 deletions(-) create mode 100644 v2/guides/mpc-wallets/server-co-signer/troubleshooting.mdx create mode 100644 v2_cn/guides/mpc-wallets/server-co-signer/troubleshooting.mdx diff --git a/docs.json b/docs.json index d76c3113..a44ea896 100644 --- a/docs.json +++ b/docs.json @@ -115,6 +115,7 @@ ] }, "v2/guides/mpc-wallets/server-co-signer/key-share-verify", + "v2/guides/mpc-wallets/server-co-signer/troubleshooting", "v2/guides/mpc-wallets/server-co-signer/appendix" ] }, @@ -922,6 +923,7 @@ ] }, "v2_cn/guides/mpc-wallets/server-co-signer/key-share-verify", + "v2_cn/guides/mpc-wallets/server-co-signer/troubleshooting", "v2_cn/guides/mpc-wallets/server-co-signer/appendix" ] }, diff --git a/v2/guides/mpc-wallets/server-co-signer/callback-server-data-structure.mdx b/v2/guides/mpc-wallets/server-co-signer/callback-server-data-structure.mdx index df8430d4..9698f819 100644 --- a/v2/guides/mpc-wallets/server-co-signer/callback-server-data-structure.mdx +++ b/v2/guides/mpc-wallets/server-co-signer/callback-server-data-structure.mdx @@ -92,6 +92,10 @@ Used for transaction or message signing operations. | source_addresses | `array[object]` | The information of the source addresses of the transaction. For details, see the response of the [List wallet addresses](/v2/api-references/wallets/list-wallet-addresses) operation. | | transaction | `object` | The information of the transaction to sign. For details, see the response of the [Get transaction information](/v2/api-references/transactions/get-transaction-information) operation. | + +The `transaction` object includes an `initiator_type` field that identifies how the transaction was initiated, so your callback server can distinguish, for example, an API-initiated transaction from an App-initiated one. Possible values are `API` (initiated through the WaaS API), `Web` (initiated from Cobo Portal), `App` (initiated from Cobo Portal Apps), and `External` (initiated outside Cobo). For the full transaction schema, see the response of the [Get transaction information](/v2/api-references/transactions/get-transaction-information) operation. + + ### TypeKeyReshare request Used for [key resharing](https://manuals.cobo.com/en/portal/mpc-wallets/ocw/manage-key-share-groups#manage-recovery-groups) operations. Resharing means to use an existing key share holder group to generate key shares for a new group. @@ -132,7 +136,36 @@ Your callback server must respond to all callback requests with the following st | action | `string` | Action to take. Possible values:
- `APPROVE`: Approve the request and proceed with the operation
- `REJECT`: Deny the request and stop the operation | | error | `string` | The error message:
- When `status` is not `0`: Contains internal error messages from the callback server.
- When `status` is `0` and action is `REJECT`: Contains the specific reason for the rejection. | +### HTTP response requirements + +The callback response described above is the JSON body of the HTTP response. Return your response with an HTTP `200` (OK) status code, and set the body `status` field to `0` to indicate that your callback server processed the callback successfully. + +The HTTP status code and the body `status` field are different. The HTTP status code reports whether the HTTP request reached and was handled by your callback server, while the body `status` field reports the result of processing the callback: a value of `0` indicates success, and any other value indicates that an error occurred in the callback server while processing the request. + +#### Example + +```json +// Callback request (TypeKeySign) from the TSS Node +{ + "request_id": "f1e2d3c4b5a6", + "request_type": 2, + "request_detail": "{...}", + "extra_info": "{...}" +} +``` + +```json +// Callback response (HTTP status code 200) +{ + "status": 0, + "request_id": "f1e2d3c4b5a6", + "action": "APPROVE", + "error": "" +} +``` + ### Important notes - If the TSS Node fails to receive an HTTP response, it will retry the callback request. -- After exceeding the maximum retry attempts, the risk control result will be set to `REJECT`. \ No newline at end of file +- After exceeding the maximum retry attempts, the risk control result will be set to `REJECT`. +- For `TypePing` requests, a successful response (body `status` `0`) indicates that your callback server is available. \ No newline at end of file diff --git a/v2/guides/mpc-wallets/server-co-signer/callback-server-overview.mdx b/v2/guides/mpc-wallets/server-co-signer/callback-server-overview.mdx index 4b9f8c6f..1501ecf8 100644 --- a/v2/guides/mpc-wallets/server-co-signer/callback-server-overview.mdx +++ b/v2/guides/mpc-wallets/server-co-signer/callback-server-overview.mdx @@ -24,6 +24,23 @@ After startup, the TSS Node establishes a persistent connection with the Cobo Wa Without the callback mechanism, the TSS Node executes tasks directly or waits for approval from the [embedded risk control module](/v2/guides/mpc-wallets/server-co-signer/embedded-risk-controls) if it is enabled. With the callback mechanism enabled, the TSS Node requests approval from your TSS Node callback servers for each task. The TSS Node only executes tasks that all of your callback servers approve. +## Callback request types + +Each callback request carries a `request_type` field that identifies the operation the TSS Node asks your callback server to approve. + +| `request_type` | Name | Meaning | +|---|---|---| +| `0` | `TypePing` | Heartbeat check that verifies your callback server is reachable. | +| `1` | `TypeKeyGen` | A request to create new key shares for your MPC Wallets. | +| `2` | `TypeKeySign` | A request to sign a transaction or message. | +| `3` | `TypeKeyReshare` | A request to redistribute key shares to a new key share holder group. | + +For the full payload schema of each request type, and for the HTTP response your callback server must return, see [Callback request and response formats](/v2/guides/mpc-wallets/server-co-signer/callback-server-data-structure). + + +These callback `request_type` values are sent by the TSS Node to your callback server for approval. They are distinct from Cobo webhook event types (such as `wallets.transaction.*` and `wallets.mpc.tss_request.*`), which the WaaS service sends to notify your application of status changes. For webhook event types, see [Webhook event types](/v2/guides/webhooks-callbacks/webhook-event-type). + + ## Communication security The TSS Node and callback server communicate via HTTP, using JSON Web Token (JWT) with RS256 signing algorithm to ensure secure data transmission. This involves: diff --git a/v2/guides/mpc-wallets/server-co-signer/key-share-verify.mdx b/v2/guides/mpc-wallets/server-co-signer/key-share-verify.mdx index d0ccb824..b1f83b4c 100644 --- a/v2/guides/mpc-wallets/server-co-signer/key-share-verify.mdx +++ b/v2/guides/mpc-wallets/server-co-signer/key-share-verify.mdx @@ -78,8 +78,8 @@ This section explains how to verify your active key shares - the ones currently -### Note -Key share verification is enabled by default in a TSS Node. If you want to disable key share verification by using the embedded risk control module, you can modify the `configs/cobo-tss-node-config.yaml` file as follows: +### Manual key share verification and callback risk control +Key share verification (also called manual key share verification or manual verification) is enabled by default in a TSS Node. If you want to disable key share verification by using the embedded risk control module, you can modify the `configs/cobo-tss-node-config.yaml` file as follows: ```yaml embedded_risk_control_rules: @@ -88,7 +88,7 @@ embedded_risk_control_rules: reject_all: true ``` -By default, the TSS Node callback does not include risk control for key share verification. If you want to implement risk control for key share verification in the TSS Node callback, please reach out to our support team at help@cobo.com for assistance. +By default, the TSS Node callback does not perform risk control for key share verification, and there is no self-serve callback `check_policy` configuration to turn it on. The only built-in control is the embedded risk control module shown above, configured through `embedded_risk_control_rules.enable` together with `key_share_sign.reject_all` in `configs/cobo-tss-node-config.yaml`. To enable callback-based risk control for key share verification for your organization, contact Cobo at help@cobo.com. diff --git a/v2/guides/mpc-wallets/server-co-signer/troubleshooting.mdx b/v2/guides/mpc-wallets/server-co-signer/troubleshooting.mdx new file mode 100644 index 00000000..f74b5eae --- /dev/null +++ b/v2/guides/mpc-wallets/server-co-signer/troubleshooting.mdx @@ -0,0 +1,31 @@ +--- +title: "Troubleshoot server co-signer setup" +lang: "en" +sidebarTitle: "Troubleshoot server co-signer setup" +description: "Resolve common errors when setting up a server co-signer and generating key shares." +--- + +import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx'; + + + +This page lists common errors that you may encounter when you deploy a server co-signer and generate key shares, together with their likely causes and remediation steps. + +## Key generation (TypeKeyGen) fails because node IDs do not match + +`TypeKeyGen` is the callback request type that the TSS Node sends to your callback server to create new key shares. The request payload includes a `node_ids` field that lists the TSS Node IDs of the key share holder group for the task. For details, see the `TypeKeyGen request` `request_detail` `node_ids` field in [Callback request and response formats](/v2/guides/mpc-wallets/server-co-signer/callback-server-data-structure). + +**Likely cause:** The TSS Node IDs configured for your node do not match the TSS Node IDs of the key share holder group for the key generation task. + +**Remediation:** + +1. Verify the node IDs in your TSS Node configuration. +2. Compare them against the `node_ids` listed in the `TypeKeyGen` `request_detail`. +3. Correct any mismatch so that every node ID matches the key share holder group. +4. Restart the TSS Node and retry key generation. + +## Related guides + +- [TSS Node callback mechanism](/v2/guides/mpc-wallets/server-co-signer/callback-server-overview) +- [Callback request and response formats](/v2/guides/mpc-wallets/server-co-signer/callback-server-data-structure) +- [Verify key shares](/v2/guides/mpc-wallets/server-co-signer/key-share-verify) diff --git a/v2/guides/webhooks-callbacks/set-up-endpoint.mdx b/v2/guides/webhooks-callbacks/set-up-endpoint.mdx index 05944a50..4153a322 100644 --- a/v2/guides/webhooks-callbacks/set-up-endpoint.mdx +++ b/v2/guides/webhooks-callbacks/set-up-endpoint.mdx @@ -23,6 +23,10 @@ After you create the endpoint, you need to implement the logic on the server to To prevent unauthorized access, when you receive a webhook event or a callback message, you need to validate the authenticity of the API request by verifying the signature. + +The Ed25519 signature is computed over the exact raw bytes of the HTTP request body. You must verify the signature against the raw body exactly as you received it. Do not parse the JSON and then re-serialize it before verifying — re-encoding can strip `null` or empty fields and reorder keys, which changes the bytes and causes signature verification to fail. Always build the message as `raw_body|timestamp` using the unmodified raw body. + + The verification steps are as follows: 1. Retrieve raw body and timestamp. diff --git a/v2_cn/guides/mpc-wallets/server-co-signer/callback-server-data-structure.mdx b/v2_cn/guides/mpc-wallets/server-co-signer/callback-server-data-structure.mdx index 68035b41..8ee1806a 100644 --- a/v2_cn/guides/mpc-wallets/server-co-signer/callback-server-data-structure.mdx +++ b/v2_cn/guides/mpc-wallets/server-co-signer/callback-server-data-structure.mdx @@ -92,6 +92,10 @@ callback: | source_addresses | `array[object]` | 交易源地址的信息。详情请参阅[列出钱包地址](/v2/api-references/wallets/list-wallet-addresses)操作的响应。 | | transaction | `object` | 要签名的交易信息。详情请参阅[获取交易信息](/v2/api-references/transactions/get-transaction-information)操作的响应。 | + +`transaction` 对象包含一个 `initiator_type` 字段，用于标识交易的发起方式，因此您的回调服务器可以区分交易，例如区分通过 API 发起的交易和通过 App 发起的交易。可能的值为 `API`（通过 WaaS API 发起）、`Web`（通过 Cobo Portal 发起）、`App`（通过 Cobo Portal Apps 发起）和 `External`（在 Cobo 之外发起）。有关完整的交易结构，请参阅[获取交易信息](/v2/api-references/transactions/get-transaction-information)操作的响应。 + + ### TypeKeyReshare 请求 用于[密钥reshare](https://manuals.cobo.com/cn/portal/mpc-wallets/ocw/manage-key-share-groups#manage-recovery-groups)操作。reshare意味着使用现有的私钥分片持有者组为新组生成私钥分片。 @@ -132,6 +136,34 @@ callback: | action | `string` | 要采取的操作。可能的值：
- `APPROVE`：批准请求并继续操作
- `REJECT`：拒绝请求并停止操作 | | error | `string` | 错误消息：
- 当 `status` 不为 `0` 时：包含回调服务器的内部错误消息。
- 当 `status` 为 `0` 且 action 为 `REJECT` 时：包含拒绝的具体原因。 | +### HTTP 响应要求 + +上述回调响应是 HTTP 响应的 JSON 包体。请使用 HTTP `200`（OK）状态码返回您的响应，并将包体中的 `status` 字段设置为 `0`，以表明您的回调服务器已成功处理该回调。 + +HTTP 状态码和包体中的 `status` 字段是不同的：HTTP 状态码表示 HTTP 请求是否到达并由您的回调服务器处理，而包体中的 `status` 字段表示回调的处理结果——值为 `0` 表示成功，任何其他值表示回调服务器在处理请求时发生了错误。 + +#### 示例 + +```json +// 来自 TSS Node 的回调请求（TypeKeySign） +{ + "request_id": "f1e2d3c4b5a6", + "request_type": 2, + "request_detail": "{...}", + "extra_info": "{...}" +} +``` + +```json +// 回调响应（HTTP 状态码 200） +{ + "status": 0, + "request_id": "f1e2d3c4b5a6", + "action": "APPROVE", + "error": "" +} +``` + ### 重要说明 - 如果 TSS Node未能收到 HTTP 响应，它将重试回调请求。 diff --git a/v2_cn/guides/mpc-wallets/server-co-signer/callback-server-overview.mdx b/v2_cn/guides/mpc-wallets/server-co-signer/callback-server-overview.mdx index 74ab3037..1fcd0731 100644 --- a/v2_cn/guides/mpc-wallets/server-co-signer/callback-server-overview.mdx +++ b/v2_cn/guides/mpc-wallets/server-co-signer/callback-server-overview.mdx @@ -21,6 +21,23 @@ TSS Node Callback 机制是服务端签名人解决方案中的关键组件， 如果没有回调机制，TSS Node 会直接执行任务。如果您启用了[嵌入式风险控制模块](/v2_cn/guides/mpc-wallets/server-co-signer/embedded-risk-controls)，则会在该模块批准后执行每个任务。启用回调机制后，TSS Node 会请求您的 TSS Node Callback 服务器批准每个任务。TSS Node 仅执行所有回调服务器批准的任务。 +## 回调请求类型 + +每个回调请求都包含一个 `request_type` 字段，用于标识 TSS Node 请求您的回调服务器批准的操作。 + +| `request_type` | 名称 | 含义 | +|---|---|---| +| `0` | `TypePing` | 心跳检查，用于验证您的回调服务器是否可达。 | +| `1` | `TypeKeyGen` | 为您的 MPC 钱包创建新私钥分片的请求。 | +| `2` | `TypeKeySign` | 签署交易或消息的请求。 | +| `3` | `TypeKeyReshare` | 将私钥分片重新分配给新私钥分片持有者组的请求。 | + +有关每种请求类型的完整 Payload 结构，以及您的回调服务器必须返回的 HTTP 响应，请参阅[回调请求和响应格式](/v2_cn/guides/mpc-wallets/server-co-signer/callback-server-data-structure)。 + + +这些回调 `request_type` 值由 TSS Node 发送到您的回调服务器以请求批准。它们与 Cobo Webhook 事件类型（例如 `wallets.transaction.*` 和 `wallets.mpc.tss_request.*`）不同，后者由 WaaS 服务发送，用于通知您的 App 状态变更。有关 Webhook 事件类型，请参阅 [Webhook 事件类型](/v2_cn/guides/webhooks-callbacks/webhook-event-type)。 + + ## 通信安全 TSS Node 和回调服务器通过 HTTP 通信，使用 RS256 签名算法的 JSON Web Token (JWT) 确保数据传输安全。这包括： diff --git a/v2_cn/guides/mpc-wallets/server-co-signer/key-share-verify.mdx b/v2_cn/guides/mpc-wallets/server-co-signer/key-share-verify.mdx index 115fbc3b..0b8057e8 100644 --- a/v2_cn/guides/mpc-wallets/server-co-signer/key-share-verify.mdx +++ b/v2_cn/guides/mpc-wallets/server-co-signer/key-share-verify.mdx @@ -78,8 +78,8 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; -### 注意 -私钥分片验证在 TSS Node 中默认启用。如果您想使用嵌入式风险控制模块禁用私钥分片验证，可以修改 `configs/cobo-tss-node-config.yaml` 文件如下： +### 手动私钥分片验证与 Callback 风险控制 +私钥分片验证（也称为手动私钥分片验证或手动验证，manual key share verification 或 manual verification）在 TSS Node 中默认启用。如果您想使用嵌入式风险控制模块禁用私钥分片验证，可以修改 `configs/cobo-tss-node-config.yaml` 文件如下： ```yaml embedded_risk_control_rules: @@ -88,7 +88,7 @@ embedded_risk_control_rules: reject_all: true ``` -默认情况下，TSS Node Callback 不包括私钥分片验证的风险控制。如果您想在 TSS Node Callback 中实现私钥分片验证的风险控制，请联系我们的支持团队 help@cobo.com 获取帮助。 +默认情况下，TSS Node Callback 不对私钥分片验证执行风险控制，并且没有可自助配置的 Callback `check_policy` 选项来启用它。唯一的内置控制是上文所示的嵌入式风险控制模块，通过 `configs/cobo-tss-node-config.yaml` 中的 `embedded_risk_control_rules.enable` 与 `key_share_sign.reject_all` 进行配置。如需为您的组织启用基于 Callback 的私钥分片验证风险控制，请联系 Cobo：help@cobo.com。 diff --git a/v2_cn/guides/mpc-wallets/server-co-signer/troubleshooting.mdx b/v2_cn/guides/mpc-wallets/server-co-signer/troubleshooting.mdx new file mode 100644 index 00000000..ac8f2166 --- /dev/null +++ b/v2_cn/guides/mpc-wallets/server-co-signer/troubleshooting.mdx @@ -0,0 +1,31 @@ +--- +title: "服务端签名人设置问题排查" +lang: "zh-hans" +sidebarTitle: "服务端签名人设置问题排查" +description: "解决设置服务端签名人和生成私钥分片时的常见错误。" +--- + +import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; + + + +本页列出了您在部署服务端签名人和生成私钥分片时可能遇到的常见错误，以及它们的可能原因和解决步骤。 + +## 密钥生成（TypeKeyGen）因节点 ID 不匹配而失败 + +`TypeKeyGen` 是 TSS Node 发送到您的回调服务器以创建新私钥分片的回调请求类型。该请求 Payload 包含一个 `node_ids` 字段，列出该任务的私钥分片持有者组的 TSS Node ID。详情请参阅[回调请求和响应格式](/v2_cn/guides/mpc-wallets/server-co-signer/callback-server-data-structure)中 `TypeKeyGen request` 的 `request_detail` `node_ids` 字段。 + +**可能原因：** 为您的节点配置的 TSS Node ID 与密钥生成任务的私钥分片持有者组的 TSS Node ID 不匹配。 + +**解决方法：** + +1. 检查您的 TSS Node 配置中的节点 ID。 +2. 将其与 `TypeKeyGen` `request_detail` 中列出的 `node_ids` 进行比较。 +3. 更正任何不匹配项，使每个节点 ID 都与私钥分片持有者组匹配。 +4. 重启 TSS Node 并重试密钥生成。 + +## 相关指南 + +- [TSS Node Callback 机制](/v2_cn/guides/mpc-wallets/server-co-signer/callback-server-overview) +- [回调请求和响应格式](/v2_cn/guides/mpc-wallets/server-co-signer/callback-server-data-structure) +- [验证私钥分片](/v2_cn/guides/mpc-wallets/server-co-signer/key-share-verify) diff --git a/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx b/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx index 10d4f67c..ae7e44c0 100644 --- a/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx +++ b/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx @@ -23,6 +23,10 @@ Webhook 事件和 Callback 消息对于确保 WaaS 服务与您的 App 之间的 为了防止未经授权的访问，当您收到 Webhook 事件或 Callback 消息时，您需要通过验证签名来验证 API 请求的真实性。 + +Ed25519 签名是基于 HTTP 请求包体的原始字节精确计算的。您必须使用收到的原始包体（raw body）来验证签名。请勿先解析 JSON 再重新序列化后进行验证——重新编码可能会去除 `null` 或空字段并重新排列键的顺序，从而改变字节内容并导致签名验证失败。请始终使用未经修改的原始包体，将消息构造为 `raw_body|timestamp`。 + + 验证步骤如下： 1. 获取请求包体的原始数据和时间戳。