ton-bug-triage

TON Bug Triage

当任务是在本地 tontester 网络上验证某个问题，而不只是启动验证器时，使用此技能。

典型触发场景：

• 部署合约并通过内部消息触发 Bug
• 比较基线验证器构建与探测验证器构建
• 验证崩溃、活性故障、畸形数据包路径或兼容性声明
• 为本地 TON 复现收集可供维护者使用的证据

标准做法是：选择足以回答问题的最小拓扑，在运行前定义成功条件，并收集足够的证据，确保结果可解释。

工作模型

区分以下路径：

• 技能脚本：此技能目录下的文件，例如 scripts/run_basic_network.py
• 源代码树：通过 --repo-root 传入的真实 TON 检出目录
• 构建目录：包含 validator-engine、create-state、tonlibjson 和 tolk 等二进制文件与库的目录
• 工作目录：每次运行的状态、日志、配置和生成的产物所在目录

不要假设技能目录和仓库是同一个目录。脚本位于技能目录中，会操作你传入的仓库和构建目录。

wallet-env.txt 是启动器与后续辅助工具之间的主要交接产物。

这些辅助工具依赖 tontester 的内部实现和私有 API。如果 tontester 发生变化，可能需要调整辅助工具行为、生成的绑定或命令假设。

工作流选择

运行任何操作前，先选择一种工作流：

• Workflow A — trigger via transaction 如果 Bug 是通过部署合约、发送内部消息，或向合约账户传送畸形／自定义载荷触发的，请使用此工作流。

• Workflow B — trigger via validator behavior 如果 Bug 需要修改过的验证器代码、混合构建、共识干扰、畸形协议数据包、乱序流量或刻意无效的区块行为，请使用此工作流。

如果复现涉及两者，先问一个问题：能否在未修改的网络上，通过正常的部署／发送路径触发问题？如果可以，从 Workflow A 开始；如果不可以，则按 Workflow B 处理。

核心规则

1. 从能够回答问题的最小网络开始。 除非路径需要节点对等、共识或混合构建，否则只使用一个验证器。

2. 优先使用常规部署／发送流程，而不是修改 zerostate。 如果 Bug 只有在修改 zerostate 后才能复现，请明确说明。

3. 将基线构建与探测构建分开。 通常，vanilla-build/ 是基线构建，而 build/ 或 build-probing/ 是修改后的构建。

4. 运行前先确定成功条件。 示例：目标 mc_seqno、明确的崩溃标记、进程退出、活跃合约账户、已检查的交易，或诚实节点拒绝畸形数据包。

5. 对于 Workflow B，确保探测节点自身不会因攻击行为而失效。 具体来说：探测节点可以发出畸形或对抗性行为，但必须保持存活，直到在诚实节点上观察到目标效果。如果探测节点先死亡，且其死亡可能解释结果，则本次运行无效。

6. 记录足够的证据，以便精确重现该场景。 保留运行目录、构建目录、命令、相关地址和导出的产物。

7. 在将结果称为可供维护者使用之前，从干净的检出目录或独立工作树重新运行，并且只保留预期的产物。

核心脚本

优先使用随附脚本，而非临时编写 Shell 命令序列。

• scripts/run_basic_network.py 从单个构建启动一个或多个验证器。支持 --emit-wallet-env、--base-port、--validators 和 --keep-alive。

• scripts/run_mixed_network.py 从不同的构建目录启动基线验证器和探测验证器。用于恶意与诚实验、基于日志的崩溃检测，以及探测节点存活检查。

• scripts/compile_tolk.py 将 .tolk 源文件编译为 .fif，并生成合约代码 BoC。如果 tolk 二进制文件相对于仓库 HEAD 已过期，则会直接失败。

• scripts/build_stateinit.py 使用代码以及可选的数据和库字典 BoC，构建可部署的 StateInit BoC。

• scripts/run_fift_script.py 使用正确的包含路径运行 .fif 脚本。

• scripts/wallet_send.py 构建并可选择发送由钱包签名的消息。部署时使用 --init-boc，任意内部负载则使用 --body-boc。

• scripts/send_boc.py 通过 tonlib 发送预先构建的序列化外部消息 BoC，而不通过 wallet_send.py 重新构建。

• scripts/address_info.py 规范化并检查原始和友好格式的 TON 地址，以便交叉核对辅助工具的输入。

• scripts/account_state.py 获取原始账户状态，并转储代码和数据 BoC 以供检查。

• scripts/get_method.py 通过 tonlib 运行 get-method 并打印 JSON。

• scripts/inspect_latest_transaction.py 获取最新账户交易，导出原始交易数据，并在 tonlib 以 msg.dataRaw 返回消息时，保存消息正文和初始状态 BoC。

• scripts/run_liteclient.py 使用 wallet-env.txt 或显式指定的仓库、构建和配置输入，运行 lite-client 命令。

• scripts/dump_boc.py 通过 Fift 打印 BoC 单元树。用于检查负载、StateInit、导出的交易数据，以及转储的账户代码和数据。

• scripts/summarize_run.py 汇总已完成或正在运行的目录中的节点存活状态和崩溃标记。

• scripts/demo_wallet_flow.py 用于简单钱包流程的已验证端到端验证器。

工作流 A

当触发条件为“部署合约，然后发送消息”时，使用工作流 A。

1. 使用 --emit-wallet-env 启动一个小型网络。
2. 使用 scripts/compile_tolk.py 编译合约；如果不使用 Tolk，则提供通过 Fift 汇编手工构建的代码 BoC。
3. 使用 scripts/build_stateinit.py 构建可部署的 StateInit。 仅当合约确实需要时，才传入 --data-boc 和 --library-boc。
4. 使用 scripts/wallet_send.py --init-boc 从已注资的内置 main-wallet 部署。 使用 --init-boc 的部署消息也可能调用合约的内部消息处理器。发送单独的触发消息前，请检查部署交易本身是否已更改合约状态。
5. 等待激活。 优先使用 account_state.py 和合约专用的 get 方法，不要假设主链只需前进一步就足够。
6. 当负载为自定义或二进制内容时，将触发消息体构建为 BoC。 run_fift_script.py 是生成一次性 body.boc 最简单的方法。
7. 使用 scripts/wallet_send.py --body-boc 发送触发消息。 --body-boc 是权威负载路径，会覆盖 --comment。 如果已有已签名的外部消息 BoC，请使用 scripts/send_boc.py --boc，而不是用 wallet_send.py 重新构建。 --wait-mc-advance 可以证明网络仍在运行，但不能证明交易成功、部署已激活或合约状态已更改。务必直接检查目标账户。
8. 使用 inspect_latest_transaction.py --out-dir 和 dump_boc.py 进行观察。 导出的 transaction-data.boc 和 in-msg-body.boc 是进行单元格级调试的起点。 如果基于 tonlib 的辅助工具崩溃（常见症状：KeyError: '@extra'），请将 run_liteclient.py 用作所有观察步骤的回退方案。参见 references/liteclient_fallback.md。

完整的操作流程请阅读 references/contract_deploy_flow.md。

仅需了解简单钱包冒烟测试流程时，请阅读 references/wallet_and_deploy_helpers.md。

工作流 B

当触发条件为“修改验证者行为，然后观察诚实节点的反应”时，使用工作流 B。

1. 在探测更改前保存基线构建的快照。
2. 仅修改探测构建，并确保所有行为更改都由明确的 TON_PROBING_* 环境变量控制。
3. 选择混合拓扑，并明确成功和失败条件。 有针对性地使用 --success-log、--failure-log、--require-node-alive 和 --require-node-dead。
4. 使用 scripts/run_mixed_network.py 运行混合网络。
5. 确认论断的两个方面：探测标记已触发，且诚实节点上的影响已发生或未发生。
6. 使用 scripts/summarize_run.py 总结运行结果，然后仅在摘要指出需要时手动检查特定日志。

常见补丁模式请阅读 references/probing_patterns.md。

端到端示例请阅读 references/bug_hunt_example.md。

否定结果

有效的“未能复现”仍然是有用的证据。只有满足以下所有条件时，才将一次运行视为真正的否定结果：

• 所选工作流确实执行了触发路径
• 存在相关的探测标记或触发标记
• 网络保持足够健康，使未出现该问题这一结果具有意义
• 观察步骤检查了正确的账户、交易或节点日志
• 已达到超时或 seqno 目标，但目标影响仍未出现

如果一次干净的重跑得出相同结果，且剩余更改仅是细微的参数调整，请停止迭代并报告否定结果。

迭代与调试

• 如果 compile_tolk.py 因旧构建产物报错，先重新构建 tolk。 通常可通过 ninja -C <build-dir> tolk 修复。

• 如果部署看似成功，但目标位置仍为空，先检查是否观察得太早。 等待激活，而不是假定部署路径有问题。

• 如果合约已激活，但预期的 get 方法调用失败，请先验证方法 ID 和初始数据布局，再更改网络拓扑。

• 如果 inspect_latest_transaction.py 显示的负载不正确，请导出原始触发 BoC 和导出的 in-msg-body.boc，并比较它们的单元树。

• 如果 Workflow B 中缺少探测标记，说明环境变量未传递到节点，或者补丁代码路径从未执行。

• 如果探测到目标效果之前探测节点就已退出，则本次运行无效。

证据标准

记录足够的信息来支撑结论：

• 确切的运行目录
• 使用的构建目录
• 使用的成功条件
• 相关的启动器和辅助命令
• 目标地址或节点名称
• Workflow A 导出的交易和 BoC 工件
• Workflow B 的节点存活状态和日志标记

对于 Workflow A，请记住，--wait-mc-advance 只是存活状态提示；请从目标账户或交易中确认成功。

故障排查

• 如果缺少 python，请使用 python3。
• 如果缺少 tonapi 绑定，辅助脚本通常会通过 test/tontester/generate_tl.py 生成它们。
• 如果将辅助脚本复制到仓库之外，请继续通过 --repo-root 传入真实仓库；include 和生成的工件来自仓库，而不是技能文件夹。
• 如果基于 tonlib 的脚本（account_state.py、get_method.py、inspect_latest_transaction.py、wallet_send.py --auto-seqno）因 KeyError: '@extra' 或类似的 tonlib 包装器错误而崩溃，则本地 tonlib 构建存在兼容性问题。请改用 lite-client 进行检查，并在 wallet_send.py 中手动指定 --seqno，不要使用 --auto-seqno。 有关通用回退流程，请参阅 references/liteclient_fallback.md。
• 如果 vanilla-build/CMakeCache.txt 指向 build/，则应将 vanilla-build 视为无效并重新创建。不要信任会重新配置到错误目录的构建树。
• 不要假定传入的构建目录中存在 lite-client。有些检出版本只构建了 create-state、tonlibjson 和 tolk。
• 如果磁盘已满，请在重试前清理旧的 run-* 目录。

参考资料

• references/wallet_and_deploy_helpers.md 阅读此文以了解经过验证的简单钱包冒烟测试流程。

• references/contract_deploy_flow.md 阅读此文以了解通用的 Workflow A 编译、部署、触发和检查流程。

• references/liteclient_fallback.md 当基于 tonlib 的辅助工具失败，且 Workflow A 需要使用 lite-client 检查或手动处理钱包 seqno 时，请阅读此文。

• references/probing_patterns.md 设计 Workflow B 代码更改时，请阅读此文。

• references/diagnostic_checklist.md 运行已完成但结果不明确时，请阅读此文。

• references/bug_hunt_example.md 阅读此文以了解一个具体的混合网络负面结果示例。