docs: 完善 TSS Node 回调与 Webhook 验签文档并新增服务端签名人问题排查页#370
Open
rcsh1 wants to merge 1 commit into
Open
Conversation
补充 TSS Node 回调 HTTP 响应要求与 request_type 事件类型说明， 新增 initiator_type 字段、Webhook 原始报文 Ed25519 验签警告， 澄清 check_policy 私钥分片验证风控需联系 Cobo， 并新增服务端签名人 (TypeKeyGen/node_ids) 问题排查页。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
关联来源
意图
在 TSS Node / Vault 服务端签名人 / Webhook 验签开发者文档中发现了六个文档问题，均来自 2025-11 至 2026-05 期间的支持工单：用户因文档缺失、表述不清或未记录已有字段与行为而遇到报错或不得不咨询 Cobo。本次变更针对这六个问题补充和澄清相关文档，覆盖回调 HTTP 响应要求、回调请求类型、
initiator_type字段、check_policy私钥分片验证风控、服务端签名人设置错误排查以及 Webhook 原始报文验签。变更摘要
v2/guides/mpc-wallets/server-co-signer/callback-server-data-structure.mdx：新增「HTTP response requirements」小节，澄清 HTTP 状态码（应返回200）与响应体status字段（0表示处理成功）的区别，并补充请求/响应示例；新增initiator_type字段说明（API/Web/App/External）；补充TypePing成功响应表示回调服务器可用的说明。对应工单 T1107893227762327800、T1154342774703738925。v2/guides/mpc-wallets/server-co-signer/callback-server-overview.mdx：新增「Callback request types」小节，说明request_type各取值（TypePing/TypeKeyGen/TypeKeySign/TypeKeyReshare）及其含义，并区分回调request_type与 Webhook 事件类型。对应工单 T1155740949590704279。v2/guides/mpc-wallets/server-co-signer/key-share-verify.mdx：澄清默认情况下 TSS Node 回调不对私钥分片验证做风控，且无自助check_policy配置项，启用回调风控需联系 help@cobo.com。对应工单 T1174142165782008200。v2/guides/mpc-wallets/server-co-signer/troubleshooting.mdx（新增）：新增服务端签名人设置问题排查页，覆盖TypeKeyGen因node_ids不匹配导致密钥生成失败的原因与解决步骤。对应工单 T1123472740002119854。v2/guides/webhooks-callbacks/set-up-endpoint.mdx：新增<Warning>，强调 Ed25519 签名是基于 HTTP 请求体的原始字节计算的，必须对原始报文验签，不可解析后重新序列化（避免剥离null/空字段或重排键导致验签失败）。对应工单 T1168372573432774681。v2_cn/...对应四个文件与新增troubleshooting.mdx：与英文版同步翻译，内容保持一致。docs.json：在中英文导航中将新增的troubleshooting页面加入服务端签名人小节。API spec 改动：无。API spec 同步：无。
待确认事项
以下事项的权威行为依赖于 TSS Node 客户端软件源码，本次文档基于已确认的契约（响应体
status=0表示成功、超过最大重试次数后风控结果置为REJECT）编写，但仍有以下细节需人工核实：response status 20 is not OK：20不是合法的 HTTP 状态码，疑似指响应体status字段。需确认该报错具体指 HTTP 状态码还是响应体status字段，以及 TSS Node 将哪些 HTTP 状态码视为成功、对非200响应如何反应（本次文档仅保留已确认的「响应体status=0表示成功」契约，未对非200节点反应做断言）。check_policy配置项：需确认是否存在自助配置项，以及回调式私钥分片验证风控是否确实需经 help@cobo.com 支持开通（本次文档已据此表述）。node_idsvstss_node_ids）与具体修复步骤位于 TSS Node 客户端软件中，需核实排查页所述内容与实际一致。注：
docs.json中cancel-auto-sweep-task-by-id的 autosweep 导航告警为既有问题，超出本次范围，非本次变更引入。🤖 Generated with Claude Code