Struct RevertDecoder 

pub struct RevertDecoder { /* private fields */ }

Decodes raw EVM revert data into a RevertReason.

The two standard Solidity built-ins — Error(string) and Panic(uint256) — are always recognized. Register additional contract-defined custom errors with with_error, register, or register_raw. Duplicate custom-error selectors keep the first registration; use try_register or try_register_raw when collisions should be handled as errors instead of warnings.

The decoder is cheap to Clone and is Send + Sync, so a configured decoder can be shared across parallel simulations.

Implementations

impl RevertDecoder

pub fn new() -> Self

Create a decoder that recognizes only the standard Solidity built-ins (Error(string) and Panic(uint256)) and no custom errors.

use evm_fork_cache::errors::RevertDecoder;

let decoder = RevertDecoder::new();
assert!(decoder.is_empty());

pub fn with_error<E>(self) -> Self

where E: SolError + Debug + 'static,

Register a sol!-generated custom error type for decoding, consuming and returning self for builder-style chaining.

If the selector is already registered, the first registration is kept and a warning is emitted. Use try_register when duplicate selectors should fail configuration.

use alloy_sol_types::sol;
use evm_fork_cache::errors::RevertDecoder;

sol! {
    #[derive(Debug)]
    error SlippageExceeded(uint256 wanted, uint256 got);
    #[derive(Debug)]
    error Paused();
}

let decoder = RevertDecoder::new()
    .with_error::<SlippageExceeded>()
    .with_error::<Paused>();
assert_eq!(decoder.len(), 2);

pub fn register<E>(&mut self) -> &mut Self

where E: SolError + Debug + 'static,

Register a sol!-generated custom error type for decoding.

If an error with the same selector is already registered, the first registration is kept and a warning is emitted. Use try_register to surface duplicates as errors.

pub fn try_register<E>(&mut self) -> Result<&mut Self, DuplicateSelectorError>

where E: SolError + Debug + 'static,

Register a sol!-generated custom error type for decoding, returning an error when another custom error already owns the same selector.

pub fn register_raw( &mut self, selector: [u8; 4], name: impl Into<Cow<'static, str>>, decode: impl Fn(&Bytes) -> Option<String> + Send + Sync + 'static, ) -> &mut Self

Register a custom error by raw selector, name, and parameter decoder.

Use this when there is no sol!-generated type to hand — for example when the selector and signature come from an ABI loaded at runtime. The decode closure receives the full revert bytes (selector included) and returns the formatted parameters, or None if it cannot decode them.

If the closure returns None, the selector still matches: the decode yields a RevertReason::Custom whose params is None. If an error with the same selector is already registered, the first registration is kept and a warning is emitted. Use try_register_raw to surface duplicates as errors.

use alloy_primitives::Bytes;
use evm_fork_cache::errors::{RevertDecoder, RevertReason};

let mut decoder = RevertDecoder::new();
// A closure that decodes the parameters when there is a payload byte,
// and otherwise reports a decode failure by returning `None`.
decoder.register_raw([0xde, 0xad, 0xbe, 0xef], "MyError(uint256)", |data| {
    (data.len() > 4).then(|| format!("payload {} bytes", data.len() - 4))
});

// Selector plus a payload byte: the closure decodes the parameters.
let with_params = Bytes::from(vec![0xde, 0xad, 0xbe, 0xef, 0x00]);
match decoder.decode(&with_params) {
    RevertReason::Custom(custom) => {
        assert_eq!(custom.name, "MyError(uint256)");
        assert_eq!(custom.params.as_deref(), Some("payload 1 bytes"));
    }
    other => panic!("expected Custom, got {other}"),
}

// Bare selector: the closure returns `None`, but the selector still
// matches, so the result is a `Custom` with `params == None`.
let bare = Bytes::from(vec![0xde, 0xad, 0xbe, 0xef]);
match decoder.decode(&bare) {
    RevertReason::Custom(custom) => assert!(custom.params.is_none()),
    other => panic!("expected Custom, got {other}"),
}

pub fn try_register_raw( &mut self, selector: [u8; 4], name: impl Into<Cow<'static, str>>, decode: impl Fn(&Bytes) -> Option<String> + Send + Sync + 'static, ) -> Result<&mut Self, DuplicateSelectorError>

Register a custom error by raw selector, name, and parameter decoder, returning an error when another custom error already owns the selector.

The decode closure receives the full revert bytes (selector included) and returns formatted parameters, or None if the selector matched but the parameter payload could not be decoded.

pub fn len(&self) -> usize

Number of registered custom errors. The two Solidity built-ins are always recognized and are not counted, so a freshly new decoder reports 0.

pub fn is_empty(&self) -> bool

Returns true if no custom errors are registered. The built-ins are always recognized regardless, so this is true for a freshly new decoder.

pub fn decode(&self, data: &Bytes) -> RevertReason

Decode raw EVM revert data into a RevertReason.

Resolution order: the two Solidity built-ins (Error(string) and Panic(uint256)), then registered custom errors by selector, then RevertReason::Unknown for anything else. Empty input decodes to RevertReason::Empty, and data shorter than 4 bytes decodes to RevertReason::Unknown with the selector right-padded with zeros.

use alloy_primitives::{Bytes, U256};
use alloy_sol_types::{Panic, SolError, sol};
use evm_fork_cache::errors::{RevertDecoder, RevertReason, ERROR_SELECTOR};

sol! {
    #[derive(Debug)]
    error Custom();
}

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

// Built-in `Error(string)` decodes natively, without registration.
// Layout: selector | offset(0x20) | length | utf8 bytes (padded).
let mut bytes = ERROR_SELECTOR.to_vec();
bytes.extend_from_slice(&{ let mut o = [0u8; 32]; o[31] = 0x20; o }); // offset
bytes.extend_from_slice(&{ let mut l = [0u8; 32]; l[31] = 2; l });    // length 2
bytes.extend_from_slice(b"hi");
bytes.extend_from_slice(&[0u8; 30]);                                  // pad to 32
assert_eq!(decoder.decode(&Bytes::from(bytes)), RevertReason::Error("hi".into()));

// Built-in `Panic(uint256)` decodes natively too.
let panic = Bytes::from(Panic { code: U256::from(0x11) }.abi_encode());
assert_eq!(decoder.decode(&panic), RevertReason::Panic(0x11));

// A registered selector resolves to `Custom`.
let raw = Bytes::from(Custom::SELECTOR.to_vec());
match decoder.decode(&raw) {
    RevertReason::Custom(err) => assert_eq!(err.name, "Custom()"),
    other => panic!("expected Custom, got {other}"),
}

// An unregistered selector falls through to `Unknown`.
let unknown = Bytes::from(vec![0xde, 0xad, 0xbe, 0xef]);
assert!(matches!(decoder.decode(&unknown), RevertReason::Unknown { .. }));

Trait Implementations

impl Clone for RevertDecoder

fn clone(&self) -> RevertDecoder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RevertDecoder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for RevertDecoder

fn default() -> RevertDecoder

Returns the “default value” for a type.