revert_reason

Documentation for eth_defi.revert_reason Python module.

Revert reason extraction.

Further reading

Functions

extract_revert_data(error)

Extract ABI-encoded custom-error data from a failed eth_call.

fetch_transaction_revert_reason(web3, tx_hash)

Gets a transaction revert reason.

Exceptions

TransactionReverted

Python exception to signal a transaction error with a good revert reason.
exception TransactionReverted

Bases: Exception

Python exception to signal a transaction error with a good revert reason.

See eth_defi.middleware.revert_reason_middleware().

__init__(*args, **kwargs)
__new__(**kwargs)
add_note(note, /)

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

extract_revert_data(error)

Extract ABI-encoded custom-error data from a failed eth_call.

Use this after catching a simulation exception when the caller needs to distinguish an expected, typed contract decision from an unexpected execution failure. Solidity custom errors encode a four-byte selector followed by ABI-encoded arguments. Web3 and JSON-RPC providers do not use one common exception shape: the same bytes may appear in error.data, a nested data/result mapping, or an exception argument string.

This is useful for preflight simulations such as GuardV0 settlement. A gross-flow cap breach and an active cooldown are valid contract outcomes that a caller may turn into a deferred action; insufficient liquidity, access-control failures and unknown selectors must remain failures. Recovering raw data lets protocol code decode only its explicitly supported selectors instead of matching provider-specific error text.

Do not use this helper to suppress arbitrary exceptions. If it returns None, or if the selector is not one the caller explicitly supports, re-raise the original exception. This helper only extracts transport data; the calling protocol owns selector matching and ABI argument decoding.

Example custom-error handling:

try:
    web3.eth.call(transaction)
except Exception as exc:
    revert_data = extract_revert_data(exc)
    if revert_data is None:
        raise

    selector = revert_data[:4]
    if selector == expected_error_selector:
        value = abi_decode(["uint256"], revert_data[4:])[0]
        handle_expected_contract_decision(value)
    else:
        raise
Parameters

error (Exception) – Exception raised by a reverted eth_call or contract call().

Returns

Raw Solidity revert bytes, including the four-byte selector, or None when no usable ABI payload is present.

Return type

Optional[bytes]

fetch_transaction_revert_reason(web3, tx_hash, use_archive_node=False, unknown_error_message='<could not extract the revert reason>')

Gets a transaction revert reason.

Ethereum nodes do not store the transaction failure reason in any database or index.

There is two ways to get the revert reason

  • Replay the transaction against the same block, and the same EVM state, where it was mined. An archive node is needed.

  • Replay the transaction against the current state. No archive node is needed, but the revert reason might be wrong.

To make this work

  • Live node must have had enough archive state for the replay to success (full nodes store only 128 blocks by default)

  • Ganache must have been started with block_time >= 1 so that transactions do not revert on transaction broadcast

  • When sending transsaction using web3.eth.send_transaction it must have gas set, or the transaction will revert during the gas estimation

Example:

receipts = wait_transactions_to_complete(web3, [tx_hash])

# Check that the transaction reverted
assert len(receipts) == 1
receipt = receipts[tx_hash]
assert receipt.status == 0

reason = fetch_transaction_revert_reason(web3, tx_hash)
assert reason == "VM Exception while processing transaction: revert BEP20: transfer amount exceeds balance"

Note

use_archive_node=True path cannot be tested in unit testing.

Different JSON-RPC providers may return payloads and this function needs to handle each provider as a special case. See manual_bnb_chain_check_revert_reason.py for testing. Currently tested:

  • Ethereum Tester

  • Ganache

  • BNB Chain + geth

Parameters

  • web3 (web3.main.Web3) – Our JSON-RPC connection

  • tx_hash (Union[hexbytes.main.HexBytes, str]) – Transaction hash of which reason we extract by simulation.

  • use_archive_node – Look up exact reason by running the tx against the past state. This only works if you are connected to the archive node.

  • unknown_error_message – Return this message if the revert reason extraction fails. Check the logs for details and pointers.

Returns

The revert reason of the placeholder message if we could not extract the reason somehow.

Return type

str