revm_handler/

handler.rs

use crate::{
    evm::FrameTr,
    execution,
    frame::handle_reservoir_remaining_gas,
    post_execution::{self, build_result_gas},
    pre_execution::{self, apply_eip7702_auth_list, PreExecutionOutput},
    system_call::SYSTEM_CALL_REGULAR_GAS_LIMIT,
    validation, EvmTr, FrameResult, ItemOrResult,
};
use context::{
    result::{ExecutionResult, FromStringError},
    LocalContextTr,
};
use context_interface::{
    cfg::gas_params,
    context::{take_error, ContextError},
    journaled_state::JournalCheckpoint,
    result::{HaltReasonTr, InvalidHeader, InvalidTransaction, ResultGas},
    Cfg, ContextTr, Database, JournalTr, Transaction,
};
use interpreter::{interpreter_action::FrameInit, GasTracker, InitialAndFloorGas, SharedMemory};
use primitives::{TxKind, U256};

/// Trait for errors that can occur during EVM execution.
///
/// This trait represents the minimal error requirements for EVM execution,
/// ensuring that all necessary error types can be converted into the handler's error type.
pub trait EvmTrError<EVM: EvmTr>:
    From<InvalidTransaction>
    + From<InvalidHeader>
    + From<<<EVM::Context as ContextTr>::Db as Database>::Error>
    + From<ContextError<<<EVM::Context as ContextTr>::Db as Database>::Error>>
    + FromStringError
{
}

impl<
        EVM: EvmTr,
        T: From<InvalidTransaction>
            + From<InvalidHeader>
            + From<<<EVM::Context as ContextTr>::Db as Database>::Error>
            + From<ContextError<<<EVM::Context as ContextTr>::Db as Database>::Error>>
            + FromStringError,
    > EvmTrError<EVM> for T
{
}

/// The main implementation of Ethereum Mainnet transaction execution.
///
/// The [`Handler::run`] method serves as the entry point for execution and provides
/// out-of-the-box support for executing Ethereum mainnet transactions.
///
/// This trait allows EVM variants to customize execution logic by implementing
/// their own method implementations.
///
/// The handler logic consists of four phases:
///   * Validation - Validates tx/block/config fields and loads caller account and validates initial gas requirements and
///     balance checks.
///   * Pre-execution - Loads and warms accounts, deducts initial gas
///   * Execution - Executes the main frame loop, delegating to [`EvmTr`] for creating and running call frames.
///   * Post-execution - Calculates final refunds, validates gas floor, reimburses caller,
///     and rewards beneficiary
///
///
/// The [`Handler::catch_error`] method handles cleanup of intermediate state if an error
/// occurs during execution.
///
/// # Returns
///
/// Returns execution status, error, gas spend and logs. State change is not returned and it is
/// contained inside Context Journal. This setup allows multiple transactions to be chain executed.
///
/// To finalize the execution and obtain changed state, call [`JournalTr::finalize`] function.
pub trait Handler {
    /// The EVM type containing Context, Instruction, and Precompiles implementations.
    type Evm: EvmTr<
        Context: ContextTr<Journal: JournalTr, Local: LocalContextTr>,
        Frame: FrameTr<FrameInit = FrameInit, FrameResult = FrameResult>,
    >;
    /// The error type returned by this handler.
    type Error: EvmTrError<Self::Evm>;
    /// The halt reason type included in the output
    type HaltReason: HaltReasonTr;

    /// The main entry point for transaction execution.
    ///
    /// This method calls [`Handler::run_without_catch_error`] and if it returns an error,
    /// calls [`Handler::catch_error`] to handle the error and cleanup.
    ///
    /// The [`Handler::catch_error`] method ensures intermediate state is properly cleared.
    ///
    /// # Error handling
    ///
    /// In case of error, the journal can be in an inconsistent state and should be cleared by calling
    /// [`JournalTr::discard_tx`] method or dropped.
    ///
    /// # Returns
    ///
    /// Returns execution result, error, gas spend and logs.
    #[inline]
    fn run(
        &mut self,
        evm: &mut Self::Evm,
    ) -> Result<ExecutionResult<Self::HaltReason>, Self::Error> {
        // Run inner handler and catch all errors to handle cleanup.
        match self.run_without_catch_error(evm) {
            Ok(output) => Ok(output),
            Err(e) => self.catch_error(evm, e),
        }
    }

    /// Runs the system call.
    ///
    /// System call is a special transaction where caller is a [`crate::SYSTEM_ADDRESS`]
    ///
    /// It is used to call a system contracts and it skips all the `validation` and `pre-execution` and most of `post-execution` phases.
    /// For example it will not deduct the caller or reward the beneficiary.
    ///
    /// State changs can be obtained by calling [`JournalTr::finalize`] method from the [`EvmTr::Context`].
    ///
    /// # Error handling
    ///
    /// By design system call should not fail and should always succeed.
    /// In case of an error (If fetching account/storage on rpc fails), the journal can be in an inconsistent
    /// state and should be cleared by calling [`JournalTr::discard_tx`] method or dropped.
    #[inline]
    fn run_system_call(
        &mut self,
        evm: &mut Self::Evm,
    ) -> Result<ExecutionResult<Self::HaltReason>, Self::Error> {
        // dummy values that are not used.
        let init_and_floor_gas = InitialAndFloorGas::new(0, 0);
        let mut gas = self.system_call_gas(evm);
        // System calls skip pre-execution, so the checkpoint that
        // [`Handler::execution`] settles is opened here.
        let checkpoint = evm.ctx().journal_mut().checkpoint();
        // call execution and than output.
        match self
            .execution(evm, checkpoint, &mut gas)
            .and_then(|exec_result| {
                let exec_result = match exec_result {
                    Some(exec_result) => exec_result,
                    // Unreachable in practice: system calls carry no value and
                    // target non-delegated system contracts, so no runtime
                    // charges apply.
                    None => self.runtime_oog_result(evm, &init_and_floor_gas, &mut gas)?,
                };
                // System calls have no intrinsic gas; build ResultGas from frame result.
                let gas = exec_result.gas();
                let result_gas = build_result_gas(false, gas, init_and_floor_gas);
                self.execution_result(evm, exec_result, result_gas)
            }) {
            out @ Ok(_) => out,
            Err(e) => self.catch_error(evm, e),
        }
    }

    /// Called by [`Handler::run`] to execute the core handler logic.
    ///
    /// Executes the four phases in sequence: [Handler::validate],
    /// [Handler::pre_execution], [Handler::execution], [Handler::post_execution].
    ///
    /// Returns any errors without catching them or calling [`Handler::catch_error`].
    #[inline]
    fn run_without_catch_error(
        &mut self,
        evm: &mut Self::Evm,
    ) -> Result<ExecutionResult<Self::HaltReason>, Self::Error> {
        let init_and_floor_gas = self.validate(evm)?;
        // Create the transaction-level gas tracker from the validated
        // intrinsic gas, mirroring how frames create their gas at frame init.
        // All later phases charge and settle against it.
        let mut gas = self.tx_gas(evm, &init_and_floor_gas);
        // Pre-execution returns the EIP-7702 refund and the EIP-2780 runtime
        // gas phase checkpoint. `None` — from pre-execution or execution —
        // means the runtime gas phase ran out of gas: the transaction is
        // included as an out-of-gas halt without entering execution.
        let pre_execution = self.pre_execution(evm, &mut gas)?;

        let refund = pre_execution.map(|pe| pe.eip7702_refund).unwrap_or(0) as i64;

        let mut exec_result = None;
        if let Some(pre_execution) = pre_execution {
            exec_result = self.execution(evm, pre_execution.checkpoint, &mut gas)?;
        }
        let mut exec_result = match exec_result {
            Some(exec_result) => exec_result,
            None => self.runtime_oog_result(evm, &init_and_floor_gas, &mut gas)?,
        };

        let result_gas = self.post_execution(evm, &mut exec_result, init_and_floor_gas, refund)?;

        // Prepare the output
        self.execution_result(evm, exec_result, result_gas)
    }

    /// Validates the execution environment and transaction parameters.
    ///
    /// Calculates initial and floor gas requirements, verifies they are covered by the gas limit,
    /// validates the transaction against state, and deducts the caller.
    #[inline]
    fn validate(&self, evm: &mut Self::Evm) -> Result<InitialAndFloorGas, Self::Error> {
        self.validate_env(evm)?;
        let mut init_and_floor_gas = self.validate_initial_tx_gas(evm)?;
        self.validate_against_state_and_deduct_caller(evm, &mut init_and_floor_gas)?;
        Ok(init_and_floor_gas)
    }

    /// Creates the transaction-level [`GasTracker`] from the validated initial gas.
    ///
    /// The gas limit is the transaction gas limit, `remaining` is the regular
    /// gas budget left after the intrinsic gas (constrained by the EIP-8037
    /// `TX_MAX_GAS_LIMIT` cap) and `reservoir` is the state gas pool, so the
    /// intrinsic gas is accounted as already spent.
    #[inline]
    fn tx_gas(&self, evm: &mut Self::Evm, init_and_floor_gas: &InitialAndFloorGas) -> GasTracker {
        let ctx = evm.ctx_ref();
        let tx_gas_limit = ctx.tx().gas_limit();
        let (remaining, reservoir) = init_and_floor_gas
            .initial_gas_and_reservoir(tx_gas_limit, ctx.cfg().tx_gas_limit_cap());
        GasTracker::new(tx_gas_limit, remaining, reservoir)
    }

    /// Creates the transaction-level [`GasTracker`] for a system call.
    ///
    /// System calls have no intrinsic gas and are not subject to the EIP-7825
    /// `TX_MAX_GAS_LIMIT` cap. Under EIP-8037 the base
    /// [`SYSTEM_CALL_REGULAR_GAS_LIMIT`] is the regular budget (`gas_left`) and
    /// everything above it, the margin sized for [`SYSTEM_MAX_SSTORES_PER_CALL`]
    /// fresh storage writes, is placed in the state-gas reservoir, so `GAS`
    /// inside a system contract reports the regular budget only. Without
    /// EIP-8037 the whole gas limit is regular gas.
    ///
    /// [`SYSTEM_MAX_SSTORES_PER_CALL`]: crate::system_call::SYSTEM_MAX_SSTORES_PER_CALL
    #[inline]
    fn system_call_gas(&self, evm: &mut Self::Evm) -> GasTracker {
        let ctx = evm.ctx_ref();
        let gas_limit = ctx.tx().gas_limit();
        let reservoir = if ctx.cfg().is_amsterdam_eip8037_enabled() {
            gas_limit.saturating_sub(SYSTEM_CALL_REGULAR_GAS_LIMIT)
        } else {
            0
        };
        GasTracker::new(gas_limit, gas_limit - reservoir, reservoir)
    }

    /// Prepares the EVM state for execution.
    ///
    /// Loads the beneficiary account (EIP-3651: Warm COINBASE) and all accounts/storage from the access list (EIP-2929).
    ///
    /// For EIP-7702 transactions, applies the authorization list and delegates successful authorizations.
    /// Authorizations are applied before execution begins.
    ///
    /// Returns the pre-execution gas decisions ([`PreExecutionOutput`]): the
    /// EIP-7702 gas refund and the still-open EIP-2780 runtime gas phase
    /// checkpoint, which [`Handler::execution`] settles. Returns `None` when
    /// the EIP-2780 authorization charges ran out of gas: the transaction
    /// stays valid but must skip execution and be included as an out-of-gas
    /// halt ([`Handler::runtime_oog_result`]).
    #[inline]
    fn pre_execution(
        &self,
        evm: &mut Self::Evm,
        gas: &mut GasTracker,
    ) -> Result<Option<PreExecutionOutput>, Self::Error> {
        self.load_accounts(evm)?;

        // EIP-2780: the checkpoint spans the whole runtime gas phase.
        let checkpoint = evm.ctx().journal_mut().checkpoint();

        let Some(eip7702_refund) = self.apply_eip7702_auth_list(evm, gas)? else {
            // Out-of-gas while processing the authorizations: revert the
            // applied delegations; the transaction is included as an
            // out-of-gas halt. (An EIP-7702 transaction is always a call, so
            // no create nonce bump is needed here.)
            evm.ctx().journal_mut().checkpoint_revert(checkpoint);
            return Ok(None);
        };

        Ok(Some(PreExecutionOutput {
            eip7702_refund,
            checkpoint,
        }))
    }

    /// Creates and executes the initial frame, then processes the execution loop.
    ///
    /// First-frame creation completes the EIP-2780 runtime gas phase: it
    /// charges the recipient/create-target costs on the transaction-level
    /// gas, and `checkpoint` (opened at pre-execution around the applied
    /// authorizations) is committed here — or reverted when those charges run
    /// out of gas, in which case `None` is returned and the caller includes
    /// the transaction as an out-of-gas halt
    /// ([`Handler::runtime_oog_result`]).
    ///
    /// Always calls [Handler::last_frame_result] to handle returned gas from the call.
    #[inline]
    fn execution(
        &mut self,
        evm: &mut Self::Evm,
        checkpoint: JournalCheckpoint,
        gas: &mut GasTracker,
    ) -> Result<Option<FrameResult>, Self::Error> {
        // Create the first frame action from the transaction-level gas. Like a
        // frame forwarding gas to a child, the first frame receives all
        // remaining regular gas and the reservoir. The EIP-2780 refundable
        // first-frame charges travel on the frame inputs like the `charged_*`
        // flags of the CALL/CREATE opcodes.
        let Some(first_frame_input) = self.first_frame_input(evm, gas)? else {
            execution::runtime_oog_unwind(evm.ctx(), checkpoint)?;
            return Ok(None);
        };
        // The runtime gas phase is complete: commit its state changes.
        evm.ctx().journal_mut().checkpoint_commit();

        // Run execution loop
        let mut frame_result = self.run_exec_loop(evm, first_frame_input)?;

        // Handle last frame result
        self.last_frame_result(evm, &mut frame_result, gas)?;
        Ok(Some(frame_result))
    }

    /// Builds the result for a transaction whose EIP-2780 runtime gas phase
    /// ran out of gas ([`Handler::pre_execution`] or [`Handler::execution`]
    /// returned `None`).
    ///
    /// The transaction is valid but its gas cannot cover the state-dependent
    /// runtime charges. It is included as an out-of-gas halt: execution is
    /// skipped, all regular gas is consumed (the reservoir is returned), and
    /// the runtime state changes were already reverted when the phase bailed
    /// out.
    #[inline]
    fn runtime_oog_result(
        &mut self,
        evm: &mut Self::Evm,
        init_and_floor_gas: &InitialAndFloorGas,
        gas: &mut GasTracker,
    ) -> Result<FrameResult, Self::Error> {
        // The runtime gas phase's partial charges are dropped: rebuild the
        // pristine transaction-level gas. Execution is skipped and the
        // untouched reservoir is carried by the synthetic out-of-gas frame
        // result; the settle below consumes all regular gas and returns the
        // reservoir.
        *gas = self.tx_gas(evm, init_and_floor_gas);
        let tx_gas_limit = evm.ctx().tx().gas_limit();
        let reservoir = gas.reservoir();
        let mut frame_result = match evm.ctx().tx().kind() {
            TxKind::Call(_) => FrameResult::new_call_oog(tx_gas_limit, 0..0, reservoir),
            TxKind::Create => FrameResult::new_create_oog(tx_gas_limit, reservoir),
        };
        self.last_frame_result(evm, &mut frame_result, gas)?;
        Ok(frame_result)
    }

    /// Handles the final steps of transaction execution.
    ///
    /// Calculates final refunds and validates the gas floor (EIP-7623) to ensure minimum gas is spent.
    /// After EIP-7623, at least floor gas must be consumed.
    ///
    /// Reimburses unused gas to the caller and rewards the beneficiary with transaction fees.
    /// The effective gas price determines rewards, with the base fee being burned.
    ///
    /// Finally, finalizes output by returning the journal state and clearing internal state
    /// for the next execution.
    #[inline]
    fn post_execution(
        &self,
        evm: &mut Self::Evm,
        exec_result: &mut FrameResult,
        init_and_floor_gas: InitialAndFloorGas,
        eip7702_gas_refund: i64,
    ) -> Result<ResultGas, Self::Error> {
        // Calculate final refund and add EIP-7702 refund to gas.
        self.refund(evm, exec_result, eip7702_gas_refund)?;

        // Build ResultGas from the final gas state
        // This includes all necessary fields and gas values.
        let result_gas = post_execution::build_result_gas(
            exec_result.instruction_result().is_halt(),
            exec_result.gas(),
            init_and_floor_gas,
        );

        // Ensure gas floor is met and minimum floor gas is spent.
        // if `cfg.is_eip7623_disabled` is true, floor gas will be set to zero
        self.eip7623_check_gas_floor(evm, exec_result, init_and_floor_gas);
        // Return unused gas to caller
        self.reimburse_caller(evm, exec_result)?;
        // Pay transaction fees to beneficiary
        self.reward_beneficiary(evm, exec_result)?;
        // Build ResultGas from the final gas state
        Ok(result_gas)
    }

    /* VALIDATION */

    /// Validates block, transaction and configuration fields.
    ///
    /// Performs all validation checks that can be done without loading state.
    /// For example, verifies transaction gas limit is below block gas limit.
    #[inline]
    fn validate_env(&self, evm: &mut Self::Evm) -> Result<(), Self::Error> {
        validation::validate_env(evm.ctx())
    }

    /// Calculates initial gas costs based on transaction type and input data.
    ///
    /// Includes additional costs for access list and authorization list.
    ///
    /// Verifies the initial cost does not exceed the transaction gas limit.
    #[inline]
    fn validate_initial_tx_gas(
        &self,
        evm: &mut Self::Evm,
    ) -> Result<InitialAndFloorGas, Self::Error> {
        let ctx = evm.ctx_ref();
        let is_amsterdam_eip2780_enabled = ctx.cfg().is_amsterdam_eip2780_enabled();
        let tx = ctx.tx();
        let eip2780 = is_amsterdam_eip2780_enabled.then(|| {
            // Self-transfer: a `Call` whose recipient is the sender itself.
            let is_self_transfer = tx.kind().to() == Some(&tx.caller());
            gas_params::Eip2780TxInfo {
                value: tx.value(),
                is_self_transfer,
            }
        });
        let gas = validation::validate_initial_tx_gas_with_gas_params(
            tx,
            ctx.cfg().spec().into(),
            ctx.cfg().gas_params(),
            ctx.cfg().is_eip7623_disabled(),
            ctx.cfg().is_amsterdam_eip8037_enabled(),
            ctx.cfg().tx_gas_limit_cap(),
            eip2780,
        )?;

        Ok(gas)
    }

    /* PRE EXECUTION */

    /// Loads access list and beneficiary account, marking them as warm in the [`context::Journal`].
    #[inline]
    fn load_accounts(&self, evm: &mut Self::Evm) -> Result<(), Self::Error> {
        pre_execution::load_accounts(evm)
    }

    /// Processes the authorization list, validating authority signatures, nonces and chain IDs.
    /// Applies valid authorizations to accounts.
    ///
    /// Returns the EIP-7702 gas refund, or `None` when the EIP-2780
    /// authorization charges ran out of gas — [`Handler::pre_execution`] owns
    /// the runtime gas phase checkpoint and reverts it in that case.
    #[inline]
    fn apply_eip7702_auth_list(
        &self,
        evm: &mut Self::Evm,
        gas: &mut GasTracker,
    ) -> Result<Option<u64>, Self::Error> {
        apply_eip7702_auth_list(evm.ctx_mut(), gas)
    }

    /// Deducts the maximum possible fee from caller's balance.
    ///
    /// If cfg.is_balance_check_disabled, this method will add back enough funds to ensure that
    /// the caller's balance is at least tx.value() before returning. Note that the amount of funds
    /// added back in this case may exceed the maximum fee.
    ///
    /// Unused fees are returned to caller after execution completes.
    #[inline]
    fn validate_against_state_and_deduct_caller(
        &self,
        evm: &mut Self::Evm,
        _init_and_floor_gas: &mut InitialAndFloorGas,
    ) -> Result<(), Self::Error> {
        pre_execution::validate_against_state_and_deduct_caller(evm.ctx())
    }

    /* EXECUTION */

    /// Creates initial frame input from the transaction parameters and the
    /// transaction-level gas, forwarding all remaining regular gas and the
    /// reservoir to the frame.
    ///
    /// Under EIP-2780 the target loading also records the runtime
    /// recipient/create-target charges on `gas` and marks the refundable ones
    /// on the frame inputs' `charged_*` flags (see
    /// [`execution::create_init_frame`]), so [`Handler::last_frame_result`]
    /// can refund them from the outcome.
    ///
    /// Returns `None` when those charges run out of gas.
    #[inline]
    fn first_frame_input(
        &mut self,
        evm: &mut Self::Evm,
        gas: &mut GasTracker,
    ) -> Result<Option<FrameInit>, Self::Error> {
        let ctx = evm.ctx_mut();
        let mut memory = SharedMemory::new_with_buffer(ctx.local().shared_memory_buffer().clone());
        memory.set_memory_limit(ctx.cfg().memory_limit());

        let Some(frame_input) = execution::create_init_frame(ctx, gas)? else {
            return Ok(None);
        };

        Ok(Some(FrameInit {
            depth: 0,
            memory,
            frame_input,
        }))
    }

    /// Processes the result of the initial call and settles it into the
    /// transaction-level gas.
    ///
    /// Emulates how a parent frame settles a returning child
    /// ([`handle_reservoir_remaining_gas`]): a failing frame rolls its
    /// state-gas charges back in LIFO order and drops its refund counter, an
    /// exceptional halt additionally consumes its regular gas; unused regular
    /// gas then returns to the transaction-level gas and the reservoir is
    /// adopted from the frame. The EIP-2780 refundable first-frame charge is
    /// refunded from the outcome's `charged_*` flags, mirroring
    /// `EthFrame::return_result`.
    ///
    /// The settled transaction-level gas is written back to the frame result,
    /// which carries it into the post-execution phase.
    #[inline]
    fn last_frame_result(
        &mut self,
        evm: &mut Self::Evm,
        frame_result: &mut <<Self::Evm as EvmTr>::Frame as FrameTr>::FrameResult,
        parent_gas: &mut GasTracker,
    ) -> Result<(), Self::Error> {
        let instruction_result = frame_result.instruction_result();

        // All regular gas was forwarded to the first frame: consume it on the
        // transaction-level gas; the settle below returns the frame's unused
        // part.
        parent_gas.spend_all();

        // Settle the frame into the transaction-level gas like a parent frame.
        handle_reservoir_remaining_gas(
            instruction_result,
            parent_gas,
            frame_result.gas_mut().tracker_mut(),
        );

        // Refund the EIP-2780 refundable first-frame charge when no account
        // leaf was created, exactly like `EthFrame::return_result` refunds
        // the upfront CALL/CREATE state charges of inner frames.
        if let Some(charge) = frame_result.refundable_state_gas(evm.ctx().cfg().gas_params()) {
            parent_gas.refill_reservoir(charge);
            // Unlike an inner frame's caller, the transaction ends here: an
            // exceptional halt consumes all regular gas, including the
            // spilled portion the refill just credited back to `remaining`.
            if instruction_result.is_halt() {
                parent_gas.spend_all();
            }
        }

        // The frame result carries the transaction-level gas onward to the
        // post-execution phase.
        *frame_result.gas_mut().tracker_mut() = *parent_gas;

        Ok(())
    }

    /* FRAMES */

    /// Executes the main frame processing loop.
    ///
    /// This loop manages the frame stack, processing each frame until execution completes.
    /// For each iteration:
    /// 1. Calls the current frame
    /// 2. Handles the returned frame input or result
    /// 3. Creates new frames or propagates results as needed
    #[inline]
    fn run_exec_loop(
        &mut self,
        evm: &mut Self::Evm,
        first_frame_input: <<Self::Evm as EvmTr>::Frame as FrameTr>::FrameInit,
    ) -> Result<FrameResult, Self::Error> {
        let res = evm.frame_init(first_frame_input)?;

        if let ItemOrResult::Result(frame_result) = res {
            return Ok(frame_result);
        }

        loop {
            let call_or_result = evm.frame_run()?;

            let result = match call_or_result {
                ItemOrResult::Item(init) => {
                    match evm.frame_init(init)? {
                        ItemOrResult::Item(_) => {
                            continue;
                        }
                        // Do not pop the frame since no new frame was created
                        ItemOrResult::Result(result) => result,
                    }
                }
                ItemOrResult::Result(result) => result,
            };

            if let Some(result) = evm.frame_return_result(result)? {
                return Ok(result);
            }
        }
    }

    /* POST EXECUTION */

    /// Validates that the minimum gas floor requirements are satisfied.
    ///
    /// Ensures that at least the floor gas amount has been consumed during execution.
    #[inline]
    fn eip7623_check_gas_floor(
        &self,
        _evm: &mut Self::Evm,
        exec_result: &mut <<Self::Evm as EvmTr>::Frame as FrameTr>::FrameResult,
        init_and_floor_gas: InitialAndFloorGas,
    ) {
        post_execution::eip7623_check_gas_floor(exec_result.gas_mut(), init_and_floor_gas)
    }

    /// Calculates the final gas refund amount, including any EIP-7702 refunds.
    #[inline]
    fn refund(
        &self,
        evm: &mut Self::Evm,
        exec_result: &mut <<Self::Evm as EvmTr>::Frame as FrameTr>::FrameResult,
        eip7702_refund: i64,
    ) -> Result<(), Self::Error> {
        post_execution::refund(
            evm.ctx().cfg().gas_params(),
            exec_result.gas_mut(),
            eip7702_refund,
        );

        Ok(())
    }

    /// Returns unused gas costs to the transaction sender's account.
    #[inline]
    fn reimburse_caller(
        &self,
        evm: &mut Self::Evm,
        exec_result: &mut <<Self::Evm as EvmTr>::Frame as FrameTr>::FrameResult,
    ) -> Result<(), Self::Error> {
        post_execution::reimburse_caller(evm.ctx(), exec_result.gas(), U256::ZERO)
            .map_err(From::from)
    }

    /// Transfers transaction fees to the block beneficiary's account.
    #[inline]
    fn reward_beneficiary(
        &self,
        evm: &mut Self::Evm,
        exec_result: &mut <<Self::Evm as EvmTr>::Frame as FrameTr>::FrameResult,
    ) -> Result<(), Self::Error> {
        post_execution::reward_beneficiary(evm.ctx(), exec_result.gas()).map_err(From::from)
    }

    /// Processes the final execution output.
    ///
    /// This method, retrieves the final state from the journal, converts internal results to the external output format.
    /// Internal state is cleared and EVM is prepared for the next transaction.
    #[inline]
    fn execution_result(
        &mut self,
        evm: &mut Self::Evm,
        result: <<Self::Evm as EvmTr>::Frame as FrameTr>::FrameResult,
        result_gas: ResultGas,
    ) -> Result<ExecutionResult<Self::HaltReason>, Self::Error> {
        take_error::<Self::Error, _>(evm.ctx().error())?;

        let exec_result = post_execution::output(evm.ctx(), result, result_gas);

        // commit transaction
        evm.ctx().journal_mut().commit_tx();
        evm.ctx().local_mut().clear();
        evm.frame_stack().clear();

        Ok(exec_result)
    }

    /// Handles cleanup when an error occurs during execution.
    ///
    /// Ensures the journal state is properly cleared before propagating the error.
    /// On happy path journal is cleared in [`Handler::execution_result`] method.
    #[inline]
    fn catch_error(
        &self,
        evm: &mut Self::Evm,
        error: Self::Error,
    ) -> Result<ExecutionResult<Self::HaltReason>, Self::Error> {
        // clean up local context. Initcode cache needs to be discarded.
        evm.ctx().local_mut().clear();
        evm.ctx().journal_mut().discard_tx();
        evm.frame_stack().clear();
        Err(error)
    }
}