ton-bug-triage

TON Bug Triage

ローカルの tontester ネットワークで何かを立証することが目的で、単にバリデーターを起動するだけではない場合に、このスキルを使用します。

典型的な用途：

• コントラクトをデプロイし、内部メッセージでバグを発生させる
• ベースラインのバリデータービルドと調査対象のバリデータービルドを比較する
• クラッシュ、ライブネスの失敗、不正パケットの処理経路、互換性に関する主張を検証する
• ローカル TON 再現用の、メンテナーに提出できる証拠を収集する

基本方針は、問いに答えられる最小のトポロジーを選び、実行前に成功条件を定め、結果を解釈するのに十分な証拠を集めることです。

作業モデル

以下のパスを区別してください。

• スキルスクリプト：scripts/run_basic_network.py など、このスキルのディレクトリにあるファイル
• ソースツリー：--repo-root で指定する、実際の TON チェックアウト
• ビルドディレクトリ：validator-engine、create-state、tonlibjson、tolk などのバイナリとライブラリ
• 作業ディレクトリ：実行ごとの状態、ログ、設定、出力されたアーティファクト

スキルのディレクトリとリポジトリが同じものだと想定しないでください。スクリプトはスキル内にあります。指定したリポジトリとビルドに対して動作します。

wallet-env.txt は、ランチャーから後続のヘルパーへの主要な引き継ぎ用アーティファクトです。

これらのヘルパーは tontester の内部実装とプライベート API に依存します。tontester が変更された場合は、ヘルパーの動作、生成されたバインディング、またはコマンドの前提を調整する必要があると想定してください。

ワークフローの選択

実行を始める前に、ワークフローを 1 つ選んでください。

• Workflow A — transaction 経由の発生 コントラクトのデプロイ、内部メッセージの送信、または不正／カスタムペイロードのコントラクトアカウントへの配信によってバグに到達する場合に使用します。

• Workflow B — バリデーターの動作による発生 パッチ適用済みのバリデーターコード、異なるビルドの混在、コンセンサスへの干渉、不正なプロトコルパケット、トラフィックの順序変更、または意図的に無効なブロック動作が必要な場合に使用します。

再現に両方が関係する場合は、まず次の点を確認してください。通常のデプロイ／送信経路の後、未変更のネットワークで発生させられますか？ 可能であれば、Workflow A から始めてください。不可能であれば、Workflow B として扱ってください。

基本ルール

1. 問いに答えられる最小のネットワークから始めます。 ピア、コンセンサス、または異なるビルドの混在が必要でない限り、バリデーターは 1 台にします。

2. zerostate の編集よりも、通常のデプロイ／送信フローを優先します。 zerostate の変更後にしか再現しない場合は、そのことを明確に伝えてください。

3. ベースラインと調査対象のビルドを分けます。 通常、ベースラインには vanilla-build/ を、変更したビルドには build/ または build-probing/ を使用します。

4. 実行前に成功条件を決めます。 例：対象の mc_seqno、明示的なクラッシュマーカー、プロセスの終了、アクティブなコントラクトアカウント、検査済みのトランザクション、または不正パケットに対する正常なノードの拒否などです。

5. Workflow B では、調査対象ノードが自身の挙動から免疫を持つようにします。 運用上の意味：調査対象ノードは不正または敵対的な挙動を送出しても、正常なノードで対象の影響が観測されるまで稼働し続けなければなりません。調査対象ノードが先に停止し、その停止が結果の説明となり得る場合、その実行は無効です。

6. 同じシナリオを再実行するのに十分な証拠を記録します。 実行ディレクトリ、ビルドディレクトリ、コマンド、関連するアドレス、エクスポートしたアーティファクトを保存してください。

7. メンテナーに提出できる状態と判断する前に、クリーンなチェックアウトまたはデタッチされたワークツリーから、意図したアーティファクトだけを使って再実行してください。

コアスクリプト

単発のシェルコマンド列より、同梱スクリプトを優先してください。

• scripts/run_basic_network.py 1 つのビルドから 1 つ以上のバリデーターを起動します。--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 wallet_send.py で再構築せずに、事前に作成したシリアライズ済み外部メッセージ BoC を tonlib 経由で送信します。

• scripts/address_info.py ヘルパーの入力を照合する必要がある場合に、raw 形式と friendly 形式の TON アドレスを正規化して調査します。

• scripts/account_state.py raw アカウント状態を取得し、調査用にコードとデータの BoC をダンプします。

• scripts/get_method.py tonlib 経由で get-method を実行し、JSON を出力します。

• scripts/inspect_latest_transaction.py アカウントの最新トランザクションを取得し、raw トランザクションデータをエクスポートします。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. 資金がある組み込みの main-wallet から、scripts/wallet_send.py --init-boc を使ってデプロイします。 --init-boc を使うデプロイメッセージは、コントラクトの内部メッセージハンドラーも呼び出すことがあります。別途トリガーを送信する前に、デプロイトランザクション自体によってコントラクトの状態が変化したか確認してください。
5. アクティベーションを待ちます。 マスター チェーンが 1 回進むだけで十分だと決めつけず、account_state.py とコントラクト固有の get メソッドを使うことをおすすめします。
6. ペイロードがカスタム形式またはバイナリーの場合は、トリガーボディを BoC として構築します。 run_fift_script.py を使うと、単発の body.boc を最も簡単に生成できます。
7. scripts/wallet_send.py --body-boc でトリガーを送信します。 --body-boc は正式なペイロード指定方法であり、--comment を上書きします。 署名済みの外部メッセージ BoC がすでにある場合は、wallet_send.py で再構築せず、代わりに scripts/send_boc.py --boc を使います。 --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-method が失敗する場合は、ネットワークトポロジーを変更する前に、メソッド 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 として渡し続けます。インクルードファイルと生成アーティファクトはスキルフォルダーではなく、リポジトリから取得されます。
• tonlib ベースのスクリプト（account_state.py、get_method.py、inspect_latest_transaction.py、wallet_send.py --auto-seqno）が KeyError: '@extra' または類似の tonlib ラッパーエラーでクラッシュする場合は、ローカルの tonlib ビルドに互換性の問題があります。確認には lite-client を使用し、--auto-seqno の代わりに手動の --seqno を指定して wallet_send.py を使用してください。 共通のフォールバック手順については、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 複数ネットワークが関係する具体的な否定的結果の例については、こちらを参照してください。