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

AccessListError

Access-list pricing query failure.

BlockContextError

Error raised when validating or refreshing the block-execution context (NUMBER / BASEFEE / COINBASE / PREVRANDAO / GASLIMIT opcodes).

CacheError

General cache-operation error for APIs that execute or mutate local fork state but do not classify EVM reverts as SimError.

DeployError

Deployment and Foundry-artifact loading failure.

FreshnessError

Error returned by speculative freshness orchestration.

MulticallError

Multicall3 helper failure.

OverlayError

Error for immutable snapshot-overlay execution helpers that do not classify reverts as SimError.

PersistenceError

Persistence failure for crate-owned on-disk cache files.

RevertReason

A decoded EVM revert reason.

RpcError

Error returned by direct RPC call callbacks installed on EvmCache.

RuntimeError

Error returned when crate-managed synchronous RPC bridges cannot enter the required tokio runtime context.

SimError

Error returned by simulation entry points.

SimHostError

Host-side failure for simulation entry points.

StorageFetchError

Error returned by storage/proof batch callbacks.

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

AccessListResult

Result type returned by access-list pricing helpers.

CacheResult

Result type returned by cache APIs.

DeployResult

Result type returned by deployment helpers.

FreshnessResult

Result type returned by freshness APIs.

MulticallResult

Result type returned by Multicall3 helpers.

OverlayResult

Result type returned by overlay APIs that return raw ExecutionResult values instead of classifying reverts.

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.

StorageFetchResult

Result type returned by storage/proof batch callbacks.