Module errors 

Simulation error types and revert-reason decoding.

Every EVM revert is either one of the two Solidity built-ins — Error(string) (from require/revert("msg")) and Panic(uint256) (from overflow, division-by-zero, etc.) — or a contract-defined custom error identified by a 4-byte selector. This module decodes the two built-ins natively and lets callers register any number of their own custom Solidity errors with a RevertDecoder.

Application-specific selectors therefore live in the application, not in this generic layer: define them with sol! and register them once.

Note that Panic(uint256) codes that exceed u64::MAX are dropped to None during decoding (and so surface as RevertReason::Unknown). This is benign: real compiler-emitted panic codes are single-byte constants (e.g. 0x11, 0x32).

use alloy_sol_types::{SolError, sol};
use evm_fork_cache::errors::{RevertDecoder, RevertReason};

sol! {
    #[derive(Debug)]
    error Unauthorized(address caller);
}

let decoder = RevertDecoder::new().with_error::<Unauthorized>();

// 4-byte selector of `Unauthorized`, with no parameter bytes.
let raw = alloy_primitives::Bytes::from(Unauthorized::SELECTOR.to_vec());
match decoder.decode(&raw) {
    RevertReason::Custom(err) => assert_eq!(err.name, "Unauthorized(address)"),
    other => panic!("expected a custom error, got {other}"),
}

Structs

CustomRevert

A decoded contract-defined custom error.

DuplicateSelectorError

Error returned when registering a custom error selector that already exists.

RevertDecoder

Decodes raw EVM revert data into a RevertReason.

SimulationError

A structured simulation revert with its decoded reason.

Enums

RevertReason

A decoded EVM revert reason.

SimError

Error returned by simulation entry points.

Constants

ERROR_SELECTOR

4-byte selector of the standard Solidity Error(string) revert (0x08c379a0), emitted by require/revert("msg").

PANIC_SELECTOR

4-byte selector of the standard Solidity Panic(uint256) revert (0x4e487b71), emitted on overflow, division-by-zero, etc.

Functions

decode_revert_reason

Decode revert data using only the standard Solidity built-ins.

Type Aliases

SimulationResult

Result type returned by simulation entry points: Ok(T) on success, or a SimError distinguishing a transaction-level revert, an EVM halt, and a host-side failure.