revm_context_interface/

result.rs

//! Result of the EVM execution. Containing both execution result, state and errors.
//!
//! [`ExecutionResult`] is the result of the EVM execution.
//!
//! [`InvalidTransaction`] is the error that is returned when the transaction is invalid.
//!
//! [`InvalidHeader`] is the error that is returned when the header is invalid.
//!
//! [`SuccessReason`] is the reason that the transaction successfully completed.
use crate::{context::ContextError, transaction::TransactionError};
use core::fmt::{self, Debug};
use database_interface::DBErrorMarker;
use primitives::{Address, Bytes, Log, U256};
use state::EvmState;
use std::{borrow::Cow, boxed::Box, string::String, sync::Arc, vec::Vec};

/// Trait for the halt reason.
pub trait HaltReasonTr: Clone + Debug + PartialEq + Eq + From<HaltReason> {}

impl<T> HaltReasonTr for T where T: Clone + Debug + PartialEq + Eq + From<HaltReason> {}

/// Tuple containing evm execution result and state.s
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct ExecResultAndState<R, S = EvmState> {
    /// Execution result
    pub result: R,
    /// Output State.
    pub state: S,
}

/// Type alias for backwards compatibility.
pub type ResultAndState<H = HaltReason, S = EvmState> = ExecResultAndState<ExecutionResult<H>, S>;

/// Tuple containing multiple execution results and state.
pub type ResultVecAndState<R, S> = ExecResultAndState<Vec<R>, S>;

impl<R, S> ExecResultAndState<R, S> {
    /// Creates new ResultAndState.
    pub const fn new(result: R, state: S) -> Self {
        Self { result, state }
    }
}

/// Gas accounting result from transaction execution.
///
/// Self-contained gas snapshot with all values needed for downstream consumers.
///
/// ## Stored values
///
/// | Getter                 | Source                             | Description                                    |
/// |------------------------|------------------------------------|------------------------------------------------|
/// | [`total_gas_spent()`]  | `Gas::spent()` = limit − remaining | Total gas consumed before refund               |
/// | [`inner_refunded()`]   | `Gas::refunded()` as u64           | Gas refunded (capped per EIP-3529)             |
/// | [`floor_gas()`]        | `InitialAndFloorGas::floor_gas`    | EIP-7623 floor gas (0 if not applicable)       |
/// | [`state_gas_spent_final()`] | `Gas::state_gas_spent`        | State gas consumed during execution (EIP-8037) |
///
/// [`total_gas_spent()`]: ResultGas::total_gas_spent
/// [`inner_refunded()`]: ResultGas::inner_refunded
/// [`floor_gas()`]: ResultGas::floor_gas
/// [`state_gas_spent_final()`]: ResultGas::state_gas_spent_final
///
/// ## Derived values
///
/// - [`tx_gas_used()`](ResultGas::tx_gas_used) = `max(total_gas_spent − refunded, floor_gas)` (the value that goes into receipts)
/// - [`block_regular_gas_used()`](ResultGas::block_regular_gas_used) = `max(total_gas_spent − state_gas_spent, floor_gas)`
///   (EIP-8037 + EIP-7778: pre-refund; the EIP-7623 calldata floor binds against the regular component)
/// - [`block_state_gas_used()`](ResultGas::block_state_gas_used) = `state_gas_spent`
/// - [`spent_sub_refunded()`](ResultGas::spent_sub_refunded) = `total_gas_spent − refunded` (before floor gas check)
/// - [`final_refunded()`](ResultGas::final_refunded) = `refunded` when floor gas is inactive, `0` when floor gas kicks in
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct ResultGas {
    /// Total gas spent consisting of regular and state gas.
    /// For actual gas used, use [`used()`](ResultGas::used).
    #[cfg_attr(feature = "serde", serde(rename = "gas_spent"))]
    total_gas_spent: u64,
    /// State gas consumed during execution (EIP-8037), net of the EIP-7702
    /// per-authorization state-gas refund applied at result-build time.
    /// Tracks gas for storage creation, account creation, and code deposit.
    /// Zero when state gas is not enabled.
    #[cfg_attr(feature = "serde", serde(default))]
    state_gas_spent: u64,
    /// Gas refund amount (capped per EIP-3529).
    ///
    /// Note: This is the raw refund before EIP-7623 floor gas adjustment.
    /// Use [`final_refunded()`](ResultGas::final_refunded) for the effective refund.
    #[cfg_attr(feature = "serde", serde(rename = "gas_refunded"))]
    refunded: u64,
    /// EIP-7623 floor gas. Zero when not applicable.
    floor_gas: u64,
}

impl ResultGas {
    /****** Constructor functions *****/

    /// Creates a new `ResultGas`.
    #[inline]
    #[deprecated(
        since = "32.0.0",
        note = "It can be a footgun as gas limit is removed, use ResultGas::with_* functions instead"
    )]
    pub const fn new(total_gas_spent: u64, refunded: u64, floor_gas: u64) -> Self {
        Self {
            total_gas_spent,
            refunded,
            floor_gas,
            state_gas_spent: 0,
        }
    }

    /// Creates a new `ResultGas` with state gas tracking.
    #[inline]
    pub const fn new_with_state_gas(
        total_gas_spent: u64,
        refunded: u64,
        floor_gas: u64,
        state_gas_spent: u64,
    ) -> Self {
        Self {
            total_gas_spent,
            refunded,
            floor_gas,
            state_gas_spent,
        }
    }

    /****** Simple getters *****/

    /// Returns the total gas spent inside execution before any refund.
    ///
    /// If you want final gas used, use [`used()`](ResultGas::used).
    #[inline]
    pub const fn total_gas_spent(&self) -> u64 {
        self.total_gas_spent
    }

    /// Returns the final state gas spent during execution (EIP-8037).
    ///
    /// The stored value is already net of the EIP-7702 per-authorization
    /// state-gas refund (subtracted when the result is built).
    ///
    /// This is same as [`ResultGas::block_state_gas_used`] for the transaction.
    #[inline]
    pub const fn state_gas_spent_final(&self) -> u64 {
        self.state_gas_spent
    }

    /// Returns the EIP-7623 floor gas.
    #[inline]
    pub const fn floor_gas(&self) -> u64 {
        self.floor_gas
    }

    /// Returns the raw refund from EVM execution, before EIP-7623 floor gas adjustment.
    ///
    /// This is the `refunded` field value (capped per EIP-3529 but not adjusted for floor gas).
    /// See [`final_refunded()`](ResultGas::final_refunded) for the effective refund.
    #[inline]
    pub const fn inner_refunded(&self) -> u64 {
        self.refunded
    }

    /// Returns the total gas spent.
    #[inline]
    #[deprecated(
        since = "32.0.0",
        note = "After EIP-8037 gas is split on
    regular and state gas, this method is no longer valid.
    Use [`ResultGas::total_gas_spent`] instead"
    )]
    pub const fn spent(&self) -> u64 {
        self.total_gas_spent()
    }

    /****** Simple setters *****/

    /// Sets the `total_gas_spent` field by mutable reference.
    #[inline]
    pub const fn set_total_gas_spent(&mut self, total_gas_spent: u64) {
        self.total_gas_spent = total_gas_spent;
    }

    /// Sets the `refunded` field by mutable reference.
    #[inline]
    pub const fn set_refunded(&mut self, refunded: u64) {
        self.refunded = refunded;
    }

    /// Sets the `floor_gas` field by mutable reference.
    #[inline]
    pub const fn set_floor_gas(&mut self, floor_gas: u64) {
        self.floor_gas = floor_gas;
    }

    /// Sets the `state_gas_spent` field by mutable reference.
    #[inline]
    pub const fn set_state_gas_spent(&mut self, state_gas_spent: u64) {
        self.state_gas_spent = state_gas_spent;
    }

    /// Sets the `spent` field by mutable reference.
    #[inline]
    #[deprecated(
        since = "32.0.0",
        note = "After EIP-8037 gas is split on
            regular and state gas, this method is no longer valid.
            Use [`ResultGas::set_total_gas_spent`] instead"
    )]
    pub const fn set_spent(&mut self, spent: u64) {
        self.total_gas_spent = spent;
    }

    /****** Builder with_* methods *****/

    /// Sets the `total_gas_spent` field.
    #[inline]
    pub const fn with_total_gas_spent(mut self, total_gas_spent: u64) -> Self {
        self.total_gas_spent = total_gas_spent;
        self
    }

    /// Sets the `refunded` field.
    #[inline]
    pub const fn with_refunded(mut self, refunded: u64) -> Self {
        self.refunded = refunded;
        self
    }

    /// Sets the `floor_gas` field.
    #[inline]
    pub const fn with_floor_gas(mut self, floor_gas: u64) -> Self {
        self.floor_gas = floor_gas;
        self
    }

    /// Sets the `state_gas_spent` field.
    #[inline]
    pub const fn with_state_gas_spent(mut self, state_gas_spent: u64) -> Self {
        self.state_gas_spent = state_gas_spent;
        self
    }

    /// Sets the `spent` field.
    #[inline]
    #[deprecated(
        since = "32.0.0",
        note = "After EIP-8037 gas is split on
    regular and state gas, this method is no longer valid.
    Use [`ResultGas::with_total_gas_spent`] instead"
    )]
    pub const fn with_spent(mut self, spent: u64) -> Self {
        self.total_gas_spent = spent;
        self
    }

    /* Aggregated getters */

    /// Returns the total gas used by the transaction.
    ///
    /// This value is set inside Receipt.
    #[inline]
    pub const fn tx_gas_used(&self) -> u64 {
        // consiste of regular and state gas.
        let total_gas_spent = self.total_gas_spent();
        // from total gas subtract the refunded gas. Refunded is capped by 20% of total gas spent.
        let tx_gas_refunded = total_gas_spent.saturating_sub(self.inner_refunded());
        max(tx_gas_refunded, self.floor_gas())
    }

    /// Returns the regular gas used by the block per EIP-8037 + EIP-7778.
    ///
    /// `max(total_gas_spent - state_gas_spent, floor_gas)` (pre-refund). The
    /// EIP-7623 calldata floor binds against the regular component only (it is
    /// not discounted by state gas), while the refund only affects
    /// `tx_gas_used` (the receipt value), not the block-level regular
    /// component.
    #[inline]
    pub const fn block_regular_gas_used(&self) -> u64 {
        max(
            self.total_gas_spent()
                .saturating_sub(self.state_gas_spent_final()),
            self.floor_gas(),
        )
    }

    /// Returns the state gas used by the block.
    ///
    /// This is same as [`ResultGas::state_gas_spent_final`] for the block.
    #[inline]
    pub const fn block_state_gas_used(&self) -> u64 {
        self.state_gas_spent_final()
    }

    /// Returns the final gas used: `max(spent - refunded, floor_gas)`.
    ///
    /// This is the value used for receipt `cumulative_gas_used` accumulation
    /// and the per-transaction gas charge.
    #[inline]
    #[deprecated(
        since = "32.0.0",
        note = "Used is not descriptive enough, use [`ResultGas::tx_gas_used`] instead"
    )]
    pub const fn used(&self) -> u64 {
        // EIP-7623: Increase calldata cost
        // spend at least a gas_floor amount of gas.
        let spent_sub_refunded = self.spent_sub_refunded();
        if spent_sub_refunded < self.floor_gas {
            return self.floor_gas;
        }
        spent_sub_refunded
    }

    /// Returns the gas spent minus the refunded gas.
    ///
    /// This does not take into account EIP-7623 floor gas. If you want to get the gas used in
    /// receipt, use [`used()`](ResultGas::used) instead.
    #[inline]
    pub const fn spent_sub_refunded(&self) -> u64 {
        self.total_gas_spent().saturating_sub(self.refunded)
    }

    /// Returns the effective refund after EIP-7623 floor gas adjustment.
    ///
    /// When floor gas kicks in (`spent - refunded < floor_gas`), the refund is zero
    /// because the floor gas charge absorbs it entirely. Otherwise returns the raw refund.
    #[inline]
    pub const fn final_refunded(&self) -> u64 {
        if self.spent_sub_refunded() < self.floor_gas {
            0
        } else {
            self.refunded
        }
    }
}

/// Const function that returns the maximum of two u64 values.
#[inline(always)]
pub const fn max(a: u64, b: u64) -> u64 {
    if a > b {
        a
    } else {
        b
    }
}

/// Const function that returns the minimum of two u64 values.
#[inline(always)]
pub const fn min(a: u64, b: u64) -> u64 {
    if a < b {
        a
    } else {
        b
    }
}

impl fmt::Display for ResultGas {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "Gas used: {}, total spent: {}",
            self.tx_gas_used(),
            self.total_gas_spent()
        )?;
        if self.refunded > 0 {
            write!(f, ", refunded: {}", self.refunded)?;
        }
        if self.floor_gas > 0 {
            write!(f, ", floor: {}", self.floor_gas)?;
        }
        if self.state_gas_spent > 0 {
            write!(f, ", state_gas: {}", self.state_gas_spent)?;
        }
        Ok(())
    }
}

/// Result of a transaction execution
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum ExecutionResult<HaltReasonTy = HaltReason> {
    /// Returned successfully
    Success {
        /// Reason for the success.
        reason: SuccessReason,
        /// Gas accounting for the transaction.
        gas: ResultGas,
        /// Logs emitted by the transaction.
        logs: Vec<Log>,
        /// Output of the transaction.
        output: Output,
    },
    /// Reverted by `REVERT` opcode that doesn't spend all gas
    Revert {
        /// Gas accounting for the transaction.
        gas: ResultGas,
        /// Logs emitted before the revert.
        logs: Vec<Log>,
        /// Output of the transaction.
        output: Bytes,
    },
    /// Reverted for various reasons and spend all gas
    Halt {
        /// Reason for the halt.
        reason: HaltReasonTy,
        /// Gas accounting for the transaction.
        ///
        /// For standard EVM halts, gas used typically equals the gas limit.
        /// Some system- or L2-specific halts may intentionally report less gas used.
        gas: ResultGas,
        /// Logs emitted before the halt.
        logs: Vec<Log>,
    },
}

impl<HaltReasonTy> ExecutionResult<HaltReasonTy> {
    /// Returns if transaction execution is successful.
    ///
    /// 1 indicates success, 0 indicates revert.
    ///
    /// <https://eips.ethereum.org/EIPS/eip-658>
    pub const fn is_success(&self) -> bool {
        matches!(self, Self::Success { .. })
    }

    /// Maps a `DBError` to a new error type using the provided closure, leaving other variants unchanged.
    pub fn map_haltreason<F, OHR>(self, op: F) -> ExecutionResult<OHR>
    where
        F: FnOnce(HaltReasonTy) -> OHR,
    {
        match self {
            Self::Success {
                reason,
                gas,
                logs,
                output,
            } => ExecutionResult::Success {
                reason,
                gas,
                logs,
                output,
            },
            Self::Revert { gas, logs, output } => ExecutionResult::Revert { gas, logs, output },
            Self::Halt { reason, gas, logs } => ExecutionResult::Halt {
                reason: op(reason),
                gas,
                logs,
            },
        }
    }

    /// Returns created address if execution is Create transaction
    /// and Contract was created.
    pub fn created_address(&self) -> Option<Address> {
        match self {
            Self::Success { output, .. } => output.address().cloned(),
            _ => None,
        }
    }

    /// Returns true if execution result is a Halt.
    pub const fn is_halt(&self) -> bool {
        matches!(self, Self::Halt { .. })
    }

    /// Returns the output data of the execution.
    ///
    /// Returns [`None`] if the execution was halted.
    pub const fn output(&self) -> Option<&Bytes> {
        match self {
            Self::Success { output, .. } => Some(output.data()),
            Self::Revert { output, .. } => Some(output),
            _ => None,
        }
    }

    /// Consumes the type and returns the output data of the execution.
    ///
    /// Returns [`None`] if the execution was halted.
    pub fn into_output(self) -> Option<Bytes> {
        match self {
            Self::Success { output, .. } => Some(output.into_data()),
            Self::Revert { output, .. } => Some(output),
            _ => None,
        }
    }

    /// Returns the logs emitted during execution.
    pub const fn logs(&self) -> &[Log] {
        match self {
            Self::Success { logs, .. } | Self::Revert { logs, .. } | Self::Halt { logs, .. } => {
                logs.as_slice()
            }
        }
    }

    /// Consumes [`self`] and returns the logs emitted during execution.
    pub fn into_logs(self) -> Vec<Log> {
        match self {
            Self::Success { logs, .. } | Self::Revert { logs, .. } | Self::Halt { logs, .. } => {
                logs
            }
        }
    }

    /// Returns the gas accounting information.
    pub const fn gas(&self) -> &ResultGas {
        match self {
            Self::Success { gas, .. } | Self::Revert { gas, .. } | Self::Halt { gas, .. } => gas,
        }
    }

    /// Returns the gas used needed for the transaction receipt.
    pub const fn tx_gas_used(&self) -> u64 {
        self.gas().tx_gas_used()
    }

    /// Returns the gas used.
    #[inline]
    #[deprecated(
        since = "32.0.0",
        note = "Use `tx_gas_used()` instead, `gas_used` is ambiguous after EIP-8037 state gas split"
    )]
    pub const fn gas_used(&self) -> u64 {
        self.tx_gas_used()
    }
}

impl<HaltReasonTy: fmt::Display> fmt::Display for ExecutionResult<HaltReasonTy> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Success {
                reason,
                gas,
                logs,
                output,
            } => {
                write!(f, "Success ({reason}): {gas}")?;
                if !logs.is_empty() {
                    write!(
                        f,
                        ", {} log{}",
                        logs.len(),
                        if logs.len() == 1 { "" } else { "s" }
                    )?;
                }
                write!(f, ", {output}")
            }
            Self::Revert { gas, logs, output } => {
                write!(f, "Revert: {gas}")?;
                if !logs.is_empty() {
                    write!(
                        f,
                        ", {} log{}",
                        logs.len(),
                        if logs.len() == 1 { "" } else { "s" }
                    )?;
                }
                if !output.is_empty() {
                    write!(f, ", {} bytes output", output.len())?;
                }
                Ok(())
            }
            Self::Halt { reason, gas, logs } => {
                write!(f, "Halted: {reason} ({gas})")?;
                if !logs.is_empty() {
                    write!(
                        f,
                        ", {} log{}",
                        logs.len(),
                        if logs.len() == 1 { "" } else { "s" }
                    )?;
                }
                Ok(())
            }
        }
    }
}

/// Output of a transaction execution
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum Output {
    /// Output of a call.
    Call(Bytes),
    /// Output of a create.
    Create(Bytes, Option<Address>),
}

impl Output {
    /// Returns the output data of the execution output.
    pub fn into_data(self) -> Bytes {
        match self {
            Output::Call(data) => data,
            Output::Create(data, _) => data,
        }
    }

    /// Returns the output data of the execution output.
    pub const fn data(&self) -> &Bytes {
        match self {
            Output::Call(data) => data,
            Output::Create(data, _) => data,
        }
    }

    /// Returns the created address, if any.
    pub const fn address(&self) -> Option<&Address> {
        match self {
            Output::Call(_) => None,
            Output::Create(_, address) => address.as_ref(),
        }
    }
}

impl fmt::Display for Output {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Output::Call(data) => {
                if data.is_empty() {
                    write!(f, "no output")
                } else {
                    write!(f, "{} bytes output", data.len())
                }
            }
            Output::Create(data, Some(addr)) => {
                if data.is_empty() {
                    write!(f, "contract created at {}", addr)
                } else {
                    write!(f, "contract created at {} ({} bytes)", addr, data.len())
                }
            }
            Output::Create(data, None) => {
                if data.is_empty() {
                    write!(f, "contract creation (no address)")
                } else {
                    write!(f, "contract creation (no address, {} bytes)", data.len())
                }
            }
        }
    }
}

/// Type-erased error type.
#[derive(Debug, Clone)]
pub struct AnyError(Arc<dyn core::error::Error + Send + Sync>);
impl AnyError {
    /// Creates a new [`AnyError`] from any error type.
    pub fn new(err: impl core::error::Error + Send + Sync + 'static) -> Self {
        Self(Arc::new(err))
    }
}

impl PartialEq for AnyError {
    fn eq(&self, other: &Self) -> bool {
        Arc::ptr_eq(&self.0, &other.0)
    }
}
impl Eq for AnyError {}
impl core::hash::Hash for AnyError {
    fn hash<H: core::hash::Hasher>(&self, state: &mut H) {
        (Arc::as_ptr(&self.0) as *const ()).hash(state);
    }
}
impl fmt::Display for AnyError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(&self.0, f)
    }
}
impl core::error::Error for AnyError {
    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
        self.0.source()
    }
}

#[cfg(feature = "serde")]
impl serde::Serialize for AnyError {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.collect_str(self)
    }
}

#[derive(Debug)]
struct StringError(String);
impl fmt::Display for StringError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.0)
    }
}
impl core::error::Error for StringError {}

impl From<String> for AnyError {
    fn from(value: String) -> Self {
        Self::new(StringError(value))
    }
}
impl From<&'static str> for AnyError {
    fn from(s: &'static str) -> Self {
        Self::new(StringError(s.into()))
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for AnyError {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let s = String::deserialize(deserializer)?;
        Ok(s.into())
    }
}

/// Main EVM error
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum EVMError<DBError, TransactionError = InvalidTransaction> {
    /// Transaction validation error
    Transaction(TransactionError),
    /// Header validation error
    Header(InvalidHeader),
    /// Database error
    Database(DBError),
    /// Custom error for non-standard EVM failures.
    ///
    /// This includes fatal precompile errors (`PrecompileError::Fatal` and `PrecompileError::FatalAny`)
    /// errors as well as any custom errors returned by handler registers.
    Custom(String),
    /// Custom error for non-standard EVM failures.
    ///
    /// This includes fatal precompile errors (`PrecompileError::Fatal` and `PrecompileError::FatalAny`)
    /// errors as well as any custom errors returned by handler registers.
    CustomAny(AnyError),
}

impl<DBError, TransactionValidationErrorT> From<ContextError<DBError>>
    for EVMError<DBError, TransactionValidationErrorT>
{
    fn from(value: ContextError<DBError>) -> Self {
        match value {
            ContextError::Db(e) => Self::Database(e),
            ContextError::Custom(e) => Self::Custom(e),
        }
    }
}

impl<DBError: DBErrorMarker, TX> From<DBError> for EVMError<DBError, TX> {
    fn from(value: DBError) -> Self {
        Self::Database(value)
    }
}

/// Trait for converting a string to an [`EVMError::Custom`] error.
pub trait FromStringError {
    /// Converts a string to an [`EVMError::Custom`] error.
    fn from_string(value: String) -> Self;
}

impl<DB, TX> FromStringError for EVMError<DB, TX> {
    fn from_string(value: String) -> Self {
        Self::Custom(value)
    }
}

impl<DB, TXE: From<InvalidTransaction>> From<InvalidTransaction> for EVMError<DB, TXE> {
    fn from(value: InvalidTransaction) -> Self {
        Self::Transaction(TXE::from(value))
    }
}

impl<DBError, TransactionValidationErrorT> EVMError<DBError, TransactionValidationErrorT> {
    /// Maps a `DBError` to a new error type using the provided closure, leaving other variants unchanged.
    pub fn map_db_err<F, E>(self, op: F) -> EVMError<E, TransactionValidationErrorT>
    where
        F: FnOnce(DBError) -> E,
    {
        match self {
            Self::Transaction(e) => EVMError::Transaction(e),
            Self::Header(e) => EVMError::Header(e),
            Self::Database(e) => EVMError::Database(op(e)),
            Self::Custom(e) => EVMError::Custom(e),
            Self::CustomAny(e) => EVMError::CustomAny(e),
        }
    }
}

impl<DBError, TransactionValidationErrorT> core::error::Error
    for EVMError<DBError, TransactionValidationErrorT>
where
    DBError: core::error::Error + 'static,
    TransactionValidationErrorT: core::error::Error + 'static,
{
    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
        match self {
            Self::Transaction(e) => Some(e),
            Self::Header(e) => Some(e),
            Self::Database(e) => Some(e),
            Self::Custom(_) => None,
            Self::CustomAny(e) => Some(e.0.as_ref()),
        }
    }
}

impl<DBError, TransactionValidationErrorT> fmt::Display
    for EVMError<DBError, TransactionValidationErrorT>
where
    DBError: fmt::Display,
    TransactionValidationErrorT: fmt::Display,
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Transaction(e) => write!(f, "transaction validation error: {e}"),
            Self::Header(e) => write!(f, "header validation error: {e}"),
            Self::Database(e) => write!(f, "database error: {e}"),
            Self::Custom(e) => f.write_str(e),
            Self::CustomAny(e) => write!(f, "{e}"),
        }
    }
}

impl<DBError, TransactionValidationErrorT> From<InvalidHeader>
    for EVMError<DBError, TransactionValidationErrorT>
{
    fn from(value: InvalidHeader) -> Self {
        Self::Header(value)
    }
}

/// Transaction validation error.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum InvalidTransaction {
    /// When using the EIP-1559 fee model introduced in the London upgrade, transactions specify two primary fee fields:
    /// - `gas_max_fee`: The maximum total fee a user is willing to pay, inclusive of both base fee and priority fee.
    /// - `gas_priority_fee`: The extra amount a user is willing to give directly to the miner, often referred to as the "tip".
    ///
    /// Provided `gas_priority_fee` exceeds the total `gas_max_fee`.
    PriorityFeeGreaterThanMaxFee,
    /// EIP-1559: `gas_price` is less than `basefee`.
    GasPriceLessThanBasefee,
    /// `gas_limit` in the tx is bigger than `block_gas_limit`.
    CallerGasLimitMoreThanBlock,
    /// Initial gas for a Call is bigger than `gas_limit`.
    ///
    /// Initial gas for a Call contains:
    /// - initial stipend gas
    /// - gas for access list and input data
    CallGasCostMoreThanGasLimit {
        /// Initial gas for a Call.
        initial_gas: u64,
        /// Gas limit for the transaction.
        gas_limit: u64,
    },
    /// Gas floor calculated from EIP-7623 Increase calldata cost
    /// is more than the gas limit.
    ///
    /// Tx data is too large to be executed.
    GasFloorMoreThanGasLimit {
        /// Gas floor calculated from EIP-7623 Increase calldata cost.
        gas_floor: u64,
        /// Gas limit for the transaction.
        gas_limit: u64,
    },
    /// EIP-3607 Reject transactions from senders with deployed code
    RejectCallerWithCode,
    /// Transaction account does not have enough amount of ether to cover transferred value and gas_limit*gas_price.
    LackOfFundForMaxFee {
        /// Fee for the transaction.
        fee: Box<U256>,
        /// Balance of the sender.
        balance: Box<U256>,
    },
    /// Overflow payment in transaction.
    OverflowPaymentInTransaction,
    /// Nonce overflows in transaction.
    NonceOverflowInTransaction,
    /// Nonce is too high.
    NonceTooHigh {
        /// Nonce of the transaction.
        tx: u64,
        /// Nonce of the state.
        state: u64,
    },
    /// Nonce is too low.
    NonceTooLow {
        /// Nonce of the transaction.
        tx: u64,
        /// Nonce of the state.
        state: u64,
    },
    /// EIP-3860: Limit and meter initcode
    CreateInitCodeSizeLimit,
    /// Transaction chain id does not match the config chain id.
    InvalidChainId,
    /// Missing chain id.
    MissingChainId,
    /// Transaction gas limit is greater than the cap.
    TxGasLimitGreaterThanCap {
        /// Transaction gas limit.
        gas_limit: u64,
        /// Gas limit cap.
        cap: u64,
    },
    /// Access list is not supported for blocks before the Berlin hardfork.
    AccessListNotSupported,
    /// `max_fee_per_blob_gas` is not supported for blocks before the Cancun hardfork.
    MaxFeePerBlobGasNotSupported,
    /// `blob_hashes`/`blob_versioned_hashes` is not supported for blocks before the Cancun hardfork.
    BlobVersionedHashesNotSupported,
    /// Block `blob_gas_price` is greater than tx-specified `max_fee_per_blob_gas` after Cancun.
    BlobGasPriceGreaterThanMax {
        /// Block `blob_gas_price`.
        block_blob_gas_price: u128,
        /// Tx-specified `max_fee_per_blob_gas`.
        tx_max_fee_per_blob_gas: u128,
    },
    /// There should be at least one blob in Blob transaction.
    EmptyBlobs,
    /// Blob transaction can't be a create transaction.
    ///
    /// `to` must be present
    BlobCreateTransaction,
    /// Transaction has more then `max` blobs
    TooManyBlobs {
        /// Maximum number of blobs allowed.
        max: usize,
        /// Number of blobs in the transaction.
        have: usize,
    },
    /// Blob transaction contains a versioned hash with an incorrect version
    BlobVersionNotSupported,
    /// EIP-7702 is not enabled.
    AuthorizationListNotSupported,
    /// EIP-7702 transaction has invalid fields set.
    AuthorizationListInvalidFields,
    /// Empty Authorization List is not allowed.
    EmptyAuthorizationList,
    /// EIP-2930 is not supported.
    Eip2930NotSupported,
    /// EIP-1559 is not supported.
    Eip1559NotSupported,
    /// EIP-4844 is not supported.
    Eip4844NotSupported,
    /// EIP-7702 is not supported.
    Eip7702NotSupported,
    /// EIP-7873 is not supported.
    Eip7873NotSupported,
    /// EIP-7873 initcode transaction should have `to` address.
    Eip7873MissingTarget,
    /// Custom string error for flexible error handling.
    Str(Cow<'static, str>),
}

impl TransactionError for InvalidTransaction {}

impl core::error::Error for InvalidTransaction {}

impl fmt::Display for InvalidTransaction {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::PriorityFeeGreaterThanMaxFee => {
                write!(f, "priority fee is greater than max fee")
            }
            Self::GasPriceLessThanBasefee => {
                write!(f, "gas price is less than basefee")
            }
            Self::CallerGasLimitMoreThanBlock => {
                write!(f, "caller gas limit exceeds the block gas limit")
            }
            Self::TxGasLimitGreaterThanCap { gas_limit, cap } => {
                write!(
                    f,
                    "transaction gas limit ({gas_limit}) is greater than the cap ({cap})"
                )
            }
            Self::CallGasCostMoreThanGasLimit {
                initial_gas,
                gas_limit,
            } => {
                write!(
                    f,
                    "call gas cost ({initial_gas}) exceeds the gas limit ({gas_limit})"
                )
            }
            Self::GasFloorMoreThanGasLimit {
                gas_floor,
                gas_limit,
            } => {
                write!(
                    f,
                    "gas floor ({gas_floor}) exceeds the gas limit ({gas_limit})"
                )
            }
            Self::RejectCallerWithCode => {
                write!(f, "reject transactions from senders with deployed code")
            }
            Self::LackOfFundForMaxFee { fee, balance } => {
                write!(f, "lack of funds ({balance}) for max fee ({fee})")
            }
            Self::OverflowPaymentInTransaction => {
                write!(f, "overflow payment in transaction")
            }
            Self::NonceOverflowInTransaction => {
                write!(f, "nonce overflow in transaction")
            }
            Self::NonceTooHigh { tx, state } => {
                write!(f, "nonce {tx} too high, expected {state}")
            }
            Self::NonceTooLow { tx, state } => {
                write!(f, "nonce {tx} too low, expected {state}")
            }
            Self::CreateInitCodeSizeLimit => {
                write!(f, "create initcode size limit")
            }
            Self::InvalidChainId => write!(f, "invalid chain ID"),
            Self::MissingChainId => write!(f, "missing chain ID"),
            Self::AccessListNotSupported => write!(f, "access list not supported"),
            Self::MaxFeePerBlobGasNotSupported => {
                write!(f, "max fee per blob gas not supported")
            }
            Self::BlobVersionedHashesNotSupported => {
                write!(f, "blob versioned hashes not supported")
            }
            Self::BlobGasPriceGreaterThanMax {
                block_blob_gas_price,
                tx_max_fee_per_blob_gas,
            } => {
                write!(
                    f,
                    "blob gas price ({block_blob_gas_price}) is greater than max fee per blob gas ({tx_max_fee_per_blob_gas})"
                )
            }
            Self::EmptyBlobs => write!(f, "empty blobs"),
            Self::BlobCreateTransaction => write!(f, "blob create transaction"),
            Self::TooManyBlobs { max, have } => {
                write!(f, "too many blobs, have {have}, max {max}")
            }
            Self::BlobVersionNotSupported => write!(f, "blob version not supported"),
            Self::AuthorizationListNotSupported => write!(f, "authorization list not supported"),
            Self::AuthorizationListInvalidFields => {
                write!(f, "authorization list tx has invalid fields")
            }
            Self::EmptyAuthorizationList => write!(f, "empty authorization list"),
            Self::Eip2930NotSupported => write!(f, "Eip2930 is not supported"),
            Self::Eip1559NotSupported => write!(f, "Eip1559 is not supported"),
            Self::Eip4844NotSupported => write!(f, "Eip4844 is not supported"),
            Self::Eip7702NotSupported => write!(f, "Eip7702 is not supported"),
            Self::Eip7873NotSupported => write!(f, "Eip7873 is not supported"),
            Self::Eip7873MissingTarget => {
                write!(f, "Eip7873 initcode transaction should have `to` address")
            }
            Self::Str(msg) => f.write_str(msg),
        }
    }
}

/// Errors related to misconfiguration of a [`crate::Block`].
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum InvalidHeader {
    /// `prevrandao` is not set for Merge and above.
    PrevrandaoNotSet,
    /// `excess_blob_gas` is not set for Cancun and above.
    ExcessBlobGasNotSet,
}

impl core::error::Error for InvalidHeader {}

impl fmt::Display for InvalidHeader {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::PrevrandaoNotSet => write!(f, "`prevrandao` not set"),
            Self::ExcessBlobGasNotSet => write!(f, "`excess_blob_gas` not set"),
        }
    }
}

/// Reason a transaction successfully completed.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum SuccessReason {
    /// Stop [`state::bytecode::opcode::STOP`] opcode.
    Stop,
    /// Return [`state::bytecode::opcode::RETURN`] opcode.
    Return,
    /// Self destruct opcode.
    SelfDestruct,
}

impl fmt::Display for SuccessReason {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Stop => write!(f, "Stop"),
            Self::Return => write!(f, "Return"),
            Self::SelfDestruct => write!(f, "SelfDestruct"),
        }
    }
}

/// Indicates that the EVM has experienced an exceptional halt.
///
/// This causes execution to immediately end with all gas being consumed.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum HaltReason {
    /// Out of gas error.
    OutOfGas(OutOfGasError),
    /// Opcode not found error.
    OpcodeNotFound,
    /// Invalid FE opcode error.
    InvalidFEOpcode,
    /// Invalid jump destination.
    InvalidJump,
    /// The feature or opcode is not activated in hardfork.
    NotActivated,
    /// Attempting to pop a value from an empty stack.
    StackUnderflow,
    /// Attempting to push a value onto a full stack.
    StackOverflow,
    /// Invalid memory or storage offset for [`state::bytecode::opcode::RETURNDATACOPY`].
    OutOfOffset,
    /// Address collision during contract creation.
    CreateCollision,
    /// Precompile error.
    PrecompileError,
    /// Precompile error with message from context.
    PrecompileErrorWithContext(String),
    /// Nonce overflow.
    NonceOverflow,
    /// Create init code size exceeds limit (runtime).
    CreateContractSizeLimit,
    /// Error on created contract that begins with EF
    CreateContractStartingWithEF,
    /// EIP-3860: Limit and meter initcode. Initcode size limit exceeded.
    CreateInitCodeSizeLimit,

    /* Internal Halts that can be only found inside Inspector */
    /// Overflow payment. Not possible to happen on mainnet.
    OverflowPayment,
    /// State change during static call.
    StateChangeDuringStaticCall,
    /// Call not allowed inside static call.
    CallNotAllowedInsideStatic,
    /// Out of funds to pay for the call.
    OutOfFunds,
    /// Call is too deep.
    CallTooDeep,
}

impl core::error::Error for HaltReason {}

impl fmt::Display for HaltReason {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::OutOfGas(err) => write!(f, "{err}"),
            Self::OpcodeNotFound => write!(f, "opcode not found"),
            Self::InvalidFEOpcode => write!(f, "invalid 0xFE opcode"),
            Self::InvalidJump => write!(f, "invalid jump destination"),
            Self::NotActivated => write!(f, "feature or opcode not activated"),
            Self::StackUnderflow => write!(f, "stack underflow"),
            Self::StackOverflow => write!(f, "stack overflow"),
            Self::OutOfOffset => write!(f, "out of offset"),
            Self::CreateCollision => write!(f, "create collision"),
            Self::PrecompileError => write!(f, "precompile error"),
            Self::PrecompileErrorWithContext(msg) => write!(f, "precompile error: {msg}"),
            Self::NonceOverflow => write!(f, "nonce overflow"),
            Self::CreateContractSizeLimit => write!(f, "create contract size limit"),
            Self::CreateContractStartingWithEF => {
                write!(f, "create contract starting with 0xEF")
            }
            Self::CreateInitCodeSizeLimit => write!(f, "create initcode size limit"),
            Self::OverflowPayment => write!(f, "overflow payment"),
            Self::StateChangeDuringStaticCall => write!(f, "state change during static call"),
            Self::CallNotAllowedInsideStatic => write!(f, "call not allowed inside static call"),
            Self::OutOfFunds => write!(f, "out of funds"),
            Self::CallTooDeep => write!(f, "call too deep"),
        }
    }
}

/// Out of gas errors.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum OutOfGasError {
    /// Basic OOG error. Not enough gas to execute the opcode.
    Basic,
    /// Tried to expand past memory limit.
    MemoryLimit,
    /// Basic OOG error from memory expansion
    Memory,
    /// Precompile threw OOG error
    Precompile,
    /// When performing something that takes a U256 and casts down to a u64, if its too large this would fire
    /// i.e. in `as_usize_or_fail`
    InvalidOperand,
    /// When performing SSTORE the gasleft is less than or equal to 2300
    ReentrancySentry,
}

impl core::error::Error for OutOfGasError {}

impl fmt::Display for OutOfGasError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Basic => write!(f, "out of gas"),
            Self::MemoryLimit => write!(f, "out of gas: memory limit exceeded"),
            Self::Memory => write!(f, "out of gas: memory expansion"),
            Self::Precompile => write!(f, "out of gas: precompile"),
            Self::InvalidOperand => write!(f, "out of gas: invalid operand"),
            Self::ReentrancySentry => write!(f, "out of gas: reentrancy sentry"),
        }
    }
}

/// Error that includes transaction index for batch transaction processing.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct TransactionIndexedError<Error> {
    /// The original error that occurred.
    pub error: Error,
    /// The index of the transaction that failed.
    pub transaction_index: usize,
}

impl<Error> TransactionIndexedError<Error> {
    /// Create a new `TransactionIndexedError` with the given error and transaction index.
    #[must_use]
    pub const fn new(error: Error, transaction_index: usize) -> Self {
        Self {
            error,
            transaction_index,
        }
    }

    /// Get a reference to the underlying error.
    pub const fn error(&self) -> &Error {
        &self.error
    }

    /// Convert into the underlying error.
    #[must_use]
    pub fn into_error(self) -> Error {
        self.error
    }
}

impl<Error: fmt::Display> fmt::Display for TransactionIndexedError<Error> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "transaction {} failed: {}",
            self.transaction_index, self.error
        )
    }
}

impl<Error: core::error::Error + 'static> core::error::Error for TransactionIndexedError<Error> {
    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
        Some(&self.error)
    }
}

impl From<&'static str> for InvalidTransaction {
    fn from(s: &'static str) -> Self {
        Self::Str(Cow::Borrowed(s))
    }
}

impl From<String> for InvalidTransaction {
    fn from(s: String) -> Self {
        Self::Str(Cow::Owned(s))
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_execution_result_display() {
        let result: ExecutionResult<HaltReason> = ExecutionResult::Success {
            reason: SuccessReason::Return,
            gas: ResultGas::default()
                .with_total_gas_spent(100000)
                .with_refunded(26000)
                .with_floor_gas(5000),
            logs: vec![Log::default(), Log::default()],
            output: Output::Call(Bytes::from(vec![1, 2, 3])),
        };
        assert_eq!(
            result.to_string(),
            "Success (Return): Gas used: 74000, total spent: 100000, refunded: 26000, floor: 5000, 2 logs, 3 bytes output"
        );

        let result: ExecutionResult<HaltReason> = ExecutionResult::Revert {
            gas: ResultGas::default()
                .with_total_gas_spent(100000)
                .with_refunded(100000),
            logs: vec![],
            output: Bytes::from(vec![1, 2, 3, 4]),
        };
        assert_eq!(
            result.to_string(),
            "Revert: Gas used: 0, total spent: 100000, refunded: 100000, 4 bytes output"
        );

        let result: ExecutionResult<HaltReason> = ExecutionResult::Halt {
            reason: HaltReason::OutOfGas(OutOfGasError::Basic),
            gas: ResultGas::default()
                .with_total_gas_spent(1000000)
                .with_refunded(1000000),
            logs: vec![],
        };
        assert_eq!(
            result.to_string(),
            "Halted: out of gas (Gas used: 0, total spent: 1000000, refunded: 1000000)"
        );
    }

    #[test]
    fn test_result_gas_display() {
        // No refund, no floor
        assert_eq!(
            ResultGas::default().with_total_gas_spent(21000).to_string(),
            "Gas used: 21000, total spent: 21000"
        );
        // With refund
        assert_eq!(
            ResultGas::default()
                .with_total_gas_spent(50000)
                .with_refunded(10000)
                .to_string(),
            "Gas used: 40000, total spent: 50000, refunded: 10000"
        );
        // With refund and floor
        assert_eq!(
            ResultGas::default()
                .with_total_gas_spent(50000)
                .with_refunded(10000)
                .with_floor_gas(30000)
                .to_string(),
            "Gas used: 40000, total spent: 50000, refunded: 10000, floor: 30000"
        );
    }

    #[test]
    fn test_result_gas_used_and_remaining() {
        let gas = ResultGas::default()
            .with_total_gas_spent(100)
            .with_refunded(30);
        assert_eq!(gas.total_gas_spent(), 100);
        assert_eq!(gas.inner_refunded(), 30);
        assert_eq!(gas.spent_sub_refunded(), 70);

        // Saturating: refunded > spent
        let gas = ResultGas::default()
            .with_total_gas_spent(10)
            .with_refunded(50);
        assert_eq!(gas.spent_sub_refunded(), 0);
    }

    #[test]
    fn test_final_refunded_with_floor_gas() {
        // No floor gas: final_refunded == refunded
        let gas = ResultGas::default()
            .with_total_gas_spent(50000)
            .with_refunded(10000);
        assert_eq!(gas.tx_gas_used(), 40000);
        assert_eq!(gas.final_refunded(), 10000);

        // Floor gas active (spent_sub_refunded < floor_gas): final_refunded == 0
        // spent=50000, refunded=10000, spent_sub_refunded=40000 < floor_gas=45000
        let gas = ResultGas::default()
            .with_total_gas_spent(50000)
            .with_refunded(10000)
            .with_floor_gas(45000);
        assert_eq!(gas.tx_gas_used(), 45000);
        assert_eq!(gas.final_refunded(), 0);

        // Floor gas inactive (spent_sub_refunded >= floor_gas): final_refunded == refunded
        // spent=50000, refunded=10000, spent_sub_refunded=40000 >= floor_gas=30000
        let gas = ResultGas::default()
            .with_total_gas_spent(50000)
            .with_refunded(10000)
            .with_floor_gas(30000);
        assert_eq!(gas.tx_gas_used(), 40000);
        assert_eq!(gas.final_refunded(), 10000);

        // Edge case: spent_sub_refunded == floor_gas exactly
        // spent=50000, refunded=10000, spent_sub_refunded=40000 == floor_gas=40000
        let gas = ResultGas::default()
            .with_total_gas_spent(50000)
            .with_refunded(10000)
            .with_floor_gas(40000);
        assert_eq!(gas.tx_gas_used(), 40000);
        assert_eq!(gas.final_refunded(), 10000);
    }

    #[test]
    fn test_block_regular_gas_used_no_floor_no_refund() {
        // block_regular_gas_used = total_gas_spent - state_gas_spent.
        // Refund and floor only affect tx_gas_used, never block_regular.

        // No state, no refund, no floor.
        let gas = ResultGas::default().with_total_gas_spent(100_000);
        assert_eq!(gas.block_regular_gas_used(), 100_000);

        // With state gas.
        let gas = ResultGas::default()
            .with_total_gas_spent(100_000)
            .with_state_gas_spent(30_000);
        assert_eq!(gas.block_regular_gas_used(), 70_000);
        assert_eq!(gas.block_state_gas_used(), 30_000);

        // Refund present: tx_gas_used drops, block_regular does not.
        let gas = ResultGas::default()
            .with_total_gas_spent(100_000)
            .with_refunded(10_000)
            .with_state_gas_spent(30_000);
        assert_eq!(gas.tx_gas_used(), 90_000);
        assert_eq!(gas.block_regular_gas_used(), 70_000);

        // Floor active: tx_gas_used floors up, block_regular does not.
        let gas = ResultGas::default()
            .with_total_gas_spent(100_000)
            .with_refunded(90_000)
            .with_floor_gas(50_000)
            .with_state_gas_spent(30_000);
        assert_eq!(gas.tx_gas_used(), 50_000);
        assert_eq!(gas.block_regular_gas_used(), 70_000);

        // State gas exceeds total → saturates to 0.
        let gas = ResultGas::default()
            .with_total_gas_spent(20_000)
            .with_state_gas_spent(30_000);
        assert_eq!(gas.block_regular_gas_used(), 0);
    }
}