solidity-debug について
solidity-debugは、失敗したトランザクションを調べるSolidity開発者向けのワークフロー技能です。Foundry castで取引データやオンチェーン状態を確認し、原因の特定と安全な再試行を支援します。
主な機能
- 01レシートと取引詳細の確認
- 02OOGやRevertなどの分類
- 03セレクターとcalldataのデコード
- 04呼び出しのシミュレーションと原因取得
- 05ロールバック確認と取引比較
- 06Foundry Keystoreによる再試行
活用シーン
- 01取引失敗の原因調査
- 02gas limit不足の確認
- 03呼び出し引数とコントラクト状態の確認
- 04修正後の検証と取引再試行
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/solidity-debugを入力して読み込まれたか確認します。
詳細
失敗したトランザクションのデバッグワークフロー
言語ルール
- 常にユーザーが使用している言語と同じ言語で回答してください。 ユーザーが中国語で質問した場合は中国語で回答してください。英語の場合は英語で回答してください。
Step 1: トランザクションレシートを取得 — 成功／失敗を判定する
Foundry cast CLI を使用して、tx hash と RPC endpoint を指定し、トランザクションレシート（receipt）を照会します。
確認するフィールド：
| フィールド | 意味 |
|---|---|
status | 0 = 失敗、1 = 成功 |
gasUsed | 実際に消費された gas |
logs | 空の配列 [] = トランザクションが revert し、イベントが発行されていない |
to | 宛先のコントラクトアドレス |
Step 2: トランザクションの詳細を取得 — gas limit と input を確認する
Foundry cast CLI を使用して、tx hash と RPC endpoint を指定し、トランザクションの詳細（tx）を照会します。
確認するフィールド：
| フィールド | 意味 |
|---|---|
gas | 送信者が設定した gas limit |
input | 呼び出しの calldata（関数セレクター + パラメーターのエンコード） |
from / to | 送信者と宛先のコントラクト |
value | 送信されたネイティブトークンの数量 |
Step 3: 失敗の種類を判定 — gasUsed と gas limit を比較する
| 現象 | 判定 | 解決の方向性 |
|---|---|---|
| gasUsed / gas ≈ 100%（例：999,472 / 1,000,000） | Out of Gas (OOG) | gas limit を引き上げるか、gas を見積もります |
| gasUsed が gas limit を大幅に下回る（例：50,000 / 1,000,000） | Revert | revert reason を取得する必要があります。Step 6 を参照してください |
| gasUsed は正常だが status=0 | 内部呼び出しの失敗 | 残高、承認、内部 call の戻り値を確認します |
| トランザクションがブロックチェーンに取り込まれていない | Nonce/Gas Price の問題 | pending キューを確認します |
Step 4: 関数セレクターをデコード — 呼び出された関数を特定する
Foundry cast の 4byte 機能を使用し、input の先頭 4 バイトを渡して、対応する関数シグネチャを照会します。
例：入力 0xb51a038a → 出力 unstake(uint256,address[],uint256[])
Step 5: 完全な calldata をデコード — 呼び出しパラメーターを復元する
Foundry cast の calldata-decode 機能を使用し、Step 4 で取得した関数シグネチャと完全な input data を渡します。
デコードされたパラメーターは、次の用途に使用できます：
- 入力パラメーターに誤りがないか分析する
- トランザクションの再試行にそのまま使用する
Step 6: Revert Reason を取得（OOG 以外のケース）
| 方法 | 説明 |
|---|---|
| シミュレーション呼び出し | Foundry cast call を使用して失敗したブロック番号でシミュレーションし、from アドレスと block number を指定して revert 情報を再現します |
| トランザクションの再実行 | Foundry cast run を使用してトランザクションを再実行します（archive ノードが必要です） |
| オンライン分析プラットフォーム | サードパーティのトランザクション分析プラットフォームを使用して詳細な呼び出しスタックを確認します（代替手段） |
Step 7: オンチェーン状態を照会 — トランザクション失敗後にデータがロールバックされたことを確認する
Foundry cast call を使用して、コントラクトの public 変数と mapping を照会します。コントラクトアドレス、関数シグネチャ、パラメーターを渡します。
struct 型の戻り値の場合は、ABI の順序に従って戻り値の型を指定する必要があります。
失敗したトランザクションによる状態変更は完全にロールバックされるため、データが元の状態のままであることを確認してください。
Step 8: 成功したトランザクションと失敗したトランザクションを比較 — 差異を特定する
成功したトランザクションと失敗したトランザクションを並べて比較します：
| 比較項目 | 説明 |
|---|---|
| gas 消費量 | OOG かどうかを判定します |
| 呼び出しパラメーター | 入力パラメーターに問題があるかどうかを判定します |
| 宛先アドレス | 誤ったコントラクトを呼び出していないかを判定します |
| ブロック時刻 | タイムロックなどの制限がないかを判定します |
| コントラクトの状態 | 前提条件を満たしていないかどうかを判定します |
Step 9: トランザクションを再試行する
| ケース | 方法 |
|---|---|
| 通常の再試行 | Foundry cast send を使用し、gas limit を指定しません（ノードによる自動見積もりに任せます） |
| 消費量の範囲が分かっている場合 | Foundry cast send を使用し、高めの gas limit を指定します |
再試行時は Foundry Keystore を使用して署名 ID を管理し、コマンドに秘密鍵を平文で渡さないでください。
セキュリティ上の注意事項
| ルール | 説明 |
|---|---|
| 秘密鍵の管理 | Foundry Keystore を使用して署名 ID を管理し、秘密鍵を平文で渡さないでください |
| シミュレーションを優先 | 実際に送信する前に、シミュレーション呼び出しを行って revert しないことを確認します |
| 1 件ずつ送信 | 一括再試行では、まず 1 件を送信して検証し、成功した後に残りを送信します |
| 状態の確認 | 送信後に status=1 を確認し、さらにオンチェーン状態を照会して変更が反映されたことを確認します |
デバッグワークフロー全体のまとめ
| ステップ | 操作 | 目的 |
|---|---|---|
| 1 | トランザクションレシートを照会 | status が 0（失敗）かどうかを判定する |
| 2 | トランザクションの詳細を照会 | gas limit と input data を取得する |
| 3 | gasUsed と gas limit を比較 | OOG と Revert を区別する |
| 4 | 関数セレクターをデコード | どの関数が呼び出されたかを特定する |
| 5 | 完全な calldata をデコード | 呼び出しパラメーターを復元する |
| 6 | シミュレーション呼び出しで revert reason を取得 | 具体的な失敗理由を取得する |
| 7 | オンチェーン状態を照会 | データがロールバックされたことを確認する |
| 8 | 成功したトランザクションと比較 | 差異を特定する |
| 9 | 修正後に再試行 | Keystore で署名して送信し、成功を確認する |