etherscan-transaction-debugger

Etherscan Transaction Debugger

Turn Etherscan's transaction, contract, token, and label data into a clear execution story that users can verify directly on the explorer. Preserve raw hashes and addresses, make important claims auditable, and never make trace completeness sound stronger than the available data.

Inputs

Require a 32-byte transaction hash. Accept a second hash for a focused comparison.

Determine the chain from the user, a chain-specific explorer URL, transaction data, or surrounding context. Ask only when the hash is valid on multiple candidate chains or cannot be found. Default to Ethereum only when no chain clue exists, and state the assumption.

Treat the expected outcome, protocol name, and requested audience as optional. Infer a useful explanation level when omitted:

• simple: short, nontechnical outcome.
• standard: outcome, important calls, and asset changes.
• developer: decoded calldata, call semantics, proxy path, and failure evidence.
• support: customer-ready explanation plus escalation notes.
• security: permissions, callbacks, delegate calls, recipients, and evidence-backed anomalies.

Core Workflow

1. Validate the hash and resolve the chain.
2. Use Etherscan as the primary data and verification surface. Collect live transaction, receipt, status, internal-operation, contract, ABI, verified source, proxy, label, token, and explorer-link evidence. Prefer the Etherscan CLI when installed; use scripts/collect_transaction_data.py for a reproducible evidence bundle. Read references/evidence-collection.md when collection fails, the CLI is unavailable, or deep trace data is needed.
3. Establish facts before interpreting intent: sender, destination, status, block time, top-level value and calldata, gas used, effective gas price, logs, created contract, and returned errors.
4. Decode the top-level method and important logs with verified ABIs. Resolve proxy and implementation roles before attributing behavior. Read references/execution-semantics.md for proxies, call types, callbacks, asset movements, and common patterns.
5. Build only the execution path supported by evidence. Label inferred edges and omitted low-value details. Never call Etherscan internal transactions a complete call trace.
6. Reconcile native, ERC-20, ERC-721, and ERC-1155 movements; approvals; operator permissions; ownership or role changes; and proxy upgrades. Calculate the execution gas fee as gasUsed * effectiveGasPrice using integers. Include L1 data or blob fees when the receipt provides them, and report a total transaction fee only when every applicable component is known.
7. If the transaction failed or contains a suspicious child failure, read references/failure-analysis.md and identify the narrowest supported root cause.
8. Cross-check the narrative against the receipt status, logs, values, addresses, and trace. Read references/reporting.md before producing security, support, comparison, or low-confidence reports.
9. Create an Etherscan evidence trail: link the transaction and each important address, contract, implementation, token, and relevant explorer view on the correct Etherscan-family explorer.