Skip to content

docs: 补充 MPC 钱包余额可用性模型、资金锁定与 BTC/UTXO 说明并优化 12007/30010 错误码指引#369

Open
rcsh1 wants to merge 1 commit into
CoboGlobal:masterfrom
rcsh1:playbook/run-run_a208ff156e7e
Open

docs: 补充 MPC 钱包余额可用性模型、资金锁定与 BTC/UTXO 说明并优化 12007/30010 错误码指引#369
rcsh1 wants to merge 1 commit into
CoboGlobal:masterfrom
rcsh1:playbook/run-run_a208ff156e7e

Conversation

@rcsh1

@rcsh1 rcsh1 commented Jun 19, 2026

Copy link
Copy Markdown
Collaborator

意图

根据 developer 文档仓库中 7 个工单(严重程度:medium,反复出现的理解混淆,confidence 0.87,时间跨度 2026-01 至 2026-04)识别出的 7 个文档问题,集中在账户余额可用性如何建模以及资金如何被锁定这两方面。本次变更主要在 balance-amounts.mdx 中补充余额可用性模型、资金锁定、BTC/UTXO 相关说明、支付余额类型以及「余额不足」排查指引,并优化错误码 12007/30010 的描述与处理建议。

变更摘要

  • v2/guides/mpc-wallets/balance-amounts.mdx:新增「Balance availability model」(映射 using_amount/locked_amount/spendable 到公开字段 data.balance.pending/locked/available 并给出 spendable 计算公式)、「Fund locking」(创建即锁定、释放条件、UTXO 跨地址并发锁定)、「Bitcoin and UTXO considerations」(充币后索引延迟导致可用余额为 0、按代币配置的尘埃阈值与错误 30010、UTXO 归集建议)、「Payment balances」(total = available + frozen)以及「Troubleshooting insufficient balance」决策树,解决工单反映的余额不足却无法定位、UTXO 提币失败、错误码含义不清等问题。
  • v2_cn/guides/mpc-wallets/balance-amounts.mdx:同步上述全部新增章节的简体中文版本,章节锚点与术语与英文版对应。
  • snippets/error-codes.mdx:完善错误码 12007/30012 的处理建议(区分当前余额与可用余额、链接到 balance-amounts 指南、提示极小金额可能改为 30010),并补充 30010 描述(尘埃阈值按代币配置、与 12007 的区别)。
  • snippets/error-codes-cn.mdx:同步 12007/30012 与 30010 的简体中文描述。

API spec edits: 无(未改动任何 OpenAPI/spec 源文件)。
API spec sync: 无。

待确认事项

以下事实在文档中被有意省略或以保守措辞处理,合入前需人工与代码/规范核实其权威性:

  1. BTC/UTXO 充币后索引服务:文档仅说明「索引完成前可用余额可能为 0」,但具体的索引/解析服务名称与预期延迟时长未在代码中核实,故未写入。
  2. 单笔交易最大 UTXO 输入数:工单提及约 400 个上限及超限错误码,但未经代码确认,文档未给出具体数值,仅以「归集小额 UTXO」建议替代。
  3. 尘埃阈值默认值(约 800 sats):文档采用「按代币配置」的表述,未写入具体数值,需核实确切默认值及是否按链可配置。
  4. dust_threshold 是否经公开 API 暴露:当前 v2 get-token-information 未暴露该字段;文档未声称可通过 API 查询,需确认是否有其他公开接口暴露。
  5. 支付(Payment)字段命名与文档归属total/available/frozen 三类余额的公开规范字段名,以及 MPC 钱包余额指南是否为其正式归属页面(还是仅交叉链接),需与 Payment 公开规范核对。
  6. spendable 计算公式对外暴露的安全性spendable = 链上余额 - using_amount - 待合规筛查金额 - 净冻结金额 是否适合对外部开发者公开,需确认。

备注:本次运行的 mintlify validate 退出码为 1,唯一告警来自 docs.json 导航中预先存在的 v2/api-references/autosweep/cancel-auto-sweep-task-by-id 引用,与本 PR 改动的 4 个文件无关。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant