Assertion Failure Explainer

WHAT IT DOES

Assertion Failure Explainer takes a failed transaction hash on any EVM-compatible chain and returns a precise, plain‑language diagnosis of why it reverted. It reads the transaction receipt, extracts the revert data (panic codes 0x00–0x21, custom error selectors, or raw bytes), fetches the target contract’s bytecode at the exact block height, and decodes the function selector along with its arguments. It then retrieves relevant storage slots for the called function (using a historical state override) and checks for past revert patterns for the same function signature on that contract. The output includes: the decoded panic or custom error reason, the specific condition that failed (e.g., “require(amount > 0) failed because amount = 0”), the function name and arguments, the sender address and nonce, gas limit and effective gas price, and a link to the block explorer. All of this is synthesized into a single, readable explanation – so you know exactly what broke and why.

HOW TO USE

Paste any failed transaction hash into the input field, select the network, and click “Explain failure”. The tool connects to your wallet via the EVM bridge (read‑only; it never signs or sends anything) to fetch the transaction and call debug_traceTransaction if available. If the transaction is still pending, it will inform you and wait for confirmation. Once the receipt is obtained, it automatically fetches the contract bytecode, decodes the calldata, and queries storage slots that are likely involved in the assertion. The AI layer then generates a human‑readable summary of the failure, highlighting the exact condition and current state that caused the revert. You can click on the transaction hash to view it on the block explorer for additional context.

CALL TRACE BINARY SEARCH WITH STATE OVERRIDES

Unlike simple revert reason extractors, this tool performs a binary‑search reconstruction of the failing call frame across multiple RPC backends. Public RPCs have varying limits on trace depth (some allow only 128 steps, others up to 1,000). The scanner issues parallel debug_traceCall requests with incremental step limits; if any endpoint returns a “block range too large” error or times out, it halves the chunk size and retries with exponential backoff (starting at 500ms, doubling up to 8s). This ensures that even for complex contract calls that revert deep inside nested libraries, proxy patterns, or multi‑hop delegatecalls, the tool still captures the exact failing opcode and program counter. Additionally, it uses historical state overrides (eth_call with block number) to read storage values as they existed at the time of the transaction – not current values – so the explanation reflects the actual state that caused the assertion, not a later change.

WHAT IT CANNOT SEE

This tool cannot detect assertion failures that depend on off‑chain state (e.g., price feeds updated after the transaction is submitted), cross‑chain conditions (e.g., a bridge message that hasn’t arrived yet), or human intent behind the call (e.g., the user meant to send a different amount). It cannot prove that the explanation covers all edge cases in the contract’s logic, especially if the bytecode is obfuscated, unverified, or uses inline assembly that does not emit standard revert data (e.g., a raw revert with no selector). It cannot predict whether resubmitting with different parameters will succeed even if the failure reason is identified – the root cause may be transient (e.g., a front‑running attack) or dependent on external state that changes every block. It also cannot see panics that occur in external calls that are not captured in the revert data (e.g., a call that consumes all gas and returns no data).

PLEASE NOTE

This tool works only for EVM‑compatible chains (Ethereum, Polygon, BSC, Arbitrum, Optimism, Avalanche C‑chain, etc.). All explanations are AI‑generated from data the app reads on‑chain – the AI synthesizes the revert bytes, opcode context, and storage diffs into plain English, but it does not have special access to private contract logic or off‑chain data. Always review what you are actually signing in your wallet before approving any transaction; a panic code explanation does not replace your own due diligence on the contract’s business logic. This tool is provided free of charge, with no warranty of accuracy or completeness.