exploring-blockchain-data

ブロックチェーンデータの調査

概要

Ethereum、Polygon、Arbitrum、Optimism、BSC など、複数の EVM 互換ネットワークにまたがるブロックチェーンデータを照会・分析します。統一された CLI を通じて、トランザクションの検索、アドレス残高の確認、ブロックの調査、トークン残高の照会、トランザクション履歴の取得、クジラウォレットの追跡に対応します。

前提条件

• Python 3.8 以降がインストールされ、requests と web3 ライブラリが利用可能であること（pip install requests web3）
• Etherscan API キー（無料枠では 1 秒あたり 5 件のリクエストが可能です。ETHERSCAN_API_KEY 環境変数で設定します）
• 任意：レート制限を引き上げる場合は、Polygonscan、Arbiscan など、各チェーン固有のエクスプローラーの API キー
• プラグインディレクトリで blockchain_explorer.py CLI スクリプト、chain_client.py、token_resolver.py モジュールが利用可能であること
• RPC エンドポイントへのアクセス（パブリックエンドポイントも利用できますが、信頼性を高めるには Alchemy、Infura、Chainstack、QuickNode などの専用プロバイダーを推奨します）

手順

1. Etherscan API キーを環境変数として設定します。export ETHERSCAN_API_KEY=<key> を実行すると、デフォルトの 1 秒あたり 5 件を超えるレート制限を利用できます。
2. python blockchain_explorer.py tx <hash> を実行してハッシュでトランザクションを検索します。ステータス、ブロック番号、送信元／送信先アドレス、送金額、ガスの詳細が返されます。
3. トランザクションの照会に --detailed を追加すると、関数呼び出しがデコードされ、やり取りしたプロトコルが特定され、入力パラメーターが表示されます。
4. ハッシュが Ethereum で見つからない場合は、--chain polygon、--chain arbitrum、または --chain bsc を指定して、別の EVM チェーン上のトランザクションを照会します。
5. python blockchain_explorer.py address <address> を実行して、ウォレットのネイティブトークン残高とトランザクション総数を確認します。
6. アドレスの照会に --history --limit 50 を追加すると、タイムスタンプ、金額、取引相手を含む直近 50 件のトランザクションを取得できます。
7. アドレスの照会に --tokens を追加すると、CoinGecko による価格解決を通じて、すべての ERC-20 トークン保有分を残高、シンボル、米ドル換算額とともに一覧表示します。
8. python blockchain_explorer.py block latest を実行して最新のブロックを調べるか、python blockchain_explorer.py block <number> を実行して特定のブロックを調べます。
9. python blockchain_explorer.py token <wallet> <contract> を実行して、ウォレットアドレスにおける特定の ERC-20 トークンの残高を確認します。小数桁数とシンボルは自動的に解決されます。
10. 任意の照会結果を JSON または CSV 形式でエクスポートするには、--format json または --format csv を使用し、後続の処理用にファイルへリダイレクトします。
11. デバッグ用に --verbose で詳細モードを有効にすると、API リクエスト URL、応答時間、キャッシュのヒット／ミス状態、レート制限カウンターが表示されます。

4 段階の実装ワークフローの詳細については、${CLAUDE_SKILL_DIR}/references/implementation.md を参照してください。

出力

• ハッシュ、チェーン、ステータス、ブロック番号、送信元／送信先アドレス、金額、ガス価格（Gwei）、ガス上限、使用ガス量、ガスコストを示すトランザクション詳細テーブル
• 関数名、プロトコルの特定結果、解析済み入力パラメーターを含む、デコードされたトランザクションデータ（--detailed を使用した場合）
• ネイティブ残高、トランザクション数、エクスプローラーへのリンクを含むアドレスの概要
• タイムスタンプ、ハッシュ、送信元／送信先、金額、方向（入金／出金）を含むトランザクション履歴テーブル
• コントラクトアドレス、トークン名、シンボル、生の残高、人間が読み取れる形式の残高、米ドル換算額を含むトークン残高一覧
• ブロック番号、タイムスタンプ、トランザクション数、使用ガス量、マイナー／バリデーターを含むブロックの詳細
• プログラムから利用できる JSON（output.json）または CSV（transactions.csv）のエクスポートファイル

エラー処理

エラー	原因	解決策
Transaction not found	トランザクションがメンプールで保留中、選択したチェーンが間違っている、またはハッシュが無効です	保留中のトランザクションはしばらく待ってから再試行してください。--chain polygon、--chain arbitrum、--chain bsc を試してください。ハッシュが 0x で始まる66文字であることを確認してください
Explorer API error: Max rate limit reached	リクエストが多すぎる、API キーがない、またはクォータを使い切っています	1～5秒待ってから再試行してください。より高い制限を利用するには ETHERSCAN_API_KEY を設定してください。本番環境で使用する場合は有料プランにアップグレードしてください
RPC error: execution timeout	RPC エンドポイントが過負荷になっている、または複雑なクエリがタイムアウトしました	別の RPC エンドポイントで再試行してください。専用プロバイダー（Alchemy、Infura、QuickNode）を利用してください。クエリを簡素化してください
Invalid address: 0xinvalid	アドレスの長さが正しくない、チェックサムが無効、または16進数以外の文字が含まれています	0x を含めて42文字であることを確認してください。ブロックエクスプローラーでチェックサム付きの形式を確認してください。チェックサムエラーが発生する場合は小文字に変換してください
Contract source code not verified	コントラクトのソースコードがエクスプローラーに公開されていません	既知の関数シグネチャデータベースを使ってデコードしてください。コントラクトがプロキシかどうかを確認し、実装アドレスを調べてください
Token: ??? (Unknown Token)	トークンが新しすぎる、あまり知られていない、または CoinGecko に追跡されていません	エクスプローラーでトークンのコントラクトを直接確認してください。DEX（Uniswap、SushiSwap）で調べてください。既知の場合は小数桁数を手動で指定してください
Price: N/A	トークンが CoinGecko に登録されていない、API のレート制限に達している、または流動性が非常に低い状態です	DEX でオンチェーン価格を確認してください。別の価格フィードを利用してください。LP リザーブから計算してください
ImportError: No module named 'requests'	Python の依存関係が不足しています	必要なパッケージをインストールするには pip install requests web3 を実行してください

使用例

複数のチェーンにまたがるトランザクションの検索

# Try Ethereum first, then Polygon if not found
python blockchain_explorer.py tx 0x1234...abcdef --chain ethereum
python blockchain_explorer.py tx 0x1234...abcdef --chain polygon

トランザクションのステータス、ブロック番号、送金額、ガスの詳細、ブロックエクスプローラーへのリンクを含む、整形済みのテーブルを返します。--detailed を追加すると、関数呼び出し（例：Uniswap の swapExactTokensForTokens）をデコードします。

ウォレットの詳細分析

python blockchain_explorer.py address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --history --tokens --limit 50

ウォレットの概要（ETH 残高、トランザクション総数）、タイムスタンプと取引相手を含む直近50件のトランザクション、USD 価値を含む ERC-20 トークン保有量の完全な一覧を生成します。大口保有者の動向調査や、ウォレットのデューデリジェンスに役立ちます。

USDC 残高の確認と JSON へのエクスポート

python blockchain_explorer.py token 0xYourWallet 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 --format json > usdc_balance.json

USDC コントラクトを特定し、適切な小数桁数の処理（USDC は小数桁数6桁）でウォレット残高を取得します。現在の USD 価格を含め、ダッシュボードやアラート用パイプラインとの連携に使えるよう、結果を usdc_balance.json に書き込みます。

リソース

• Etherscan API ドキュメント -- Ethereum の主要なエクスプローラー API。登録すれば無料プランを利用できます
• CoinGecko API -- トークン価格の特定とメタデータの検索
• web3.py ドキュメント -- EVM チェーンと直接 RPC 通信するための Python ライブラリ
• Alchemy / Infura / QuickNode -- 信頼性の高いノードアクセスを提供する専用 RPC プロバイダー
• 4byte.directory -- 未検証のコントラクトとのやり取りをデコードするための関数シグネチャデータベース