DEV Community: TangHaosuan

REVM Source Code - Execution Flow Part 5

TangHaosuan — Fri, 03 Apr 2026 14:12:16 +0000

PostExecution logic is relatively simple, mainly used for calculating gas refunds and paying miner rewards.

So this chapter combines PostExecution and ExecutionResult.

PostExecution

PostExecution uses the results from the previous three stages as input.

Let's recall the return values:

init_and_floor_gas: Return value from Validate

init_gas — the transaction's inherent, most basic gas consumption that must be deducted regardless of what the transaction executes
floor_gas — the minimum gas amount that must be reserved for the transaction, preventing gas_limit from being too low for the transaction to execute at all

eip7702_gas_refund: Return value from PreExecute — the EIP-7702 gas refund. If the delegated address already exists in the database rather than being a new address, partial gas is refunded.

exec_result: Return value from the Execution stage — the core output of the entire transaction execution.

Success
- output — return data
- gas_used — actual gas consumed (excluding refund)
- gas_refunded — refundable gas
- logs — event logs
- created_address — if CREATE, the new contract address
Revert
- output — failure reason
Halt
- reason — abnormal termination reason

// crates/handler/src/handler.rs
#[inline]
    fn post_execution(
        &self,
        evm: &mut Self::Evm,
        exec_result: &mut FrameResult,
        init_and_floor_gas: InitialAndFloorGas,
        eip7702_gas_refund: i64,
    ) -> Result<(), Self::Error> {
        // Calculate final refund and add EIP-7702 refund to gas.
        self.refund(evm, exec_result, eip7702_gas_refund);
        // 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)?;
        Ok(())
    }

refund

Let's jump directly to the refund implementation.

The function calculates the Gas refund value and ensures the refund doesn't exceed a specified ratio:

pub fn refund(spec: SpecId, gas: &mut Gas, eip7702_refund: i64) {
    // Internal implementation is self.refunded += refund, won't expand
    gas.record_refund(eip7702_refund);

    gas.set_final_refund(spec.is_enabled_in(SpecId::LONDON));
}

Jump to the set_final_refund implementation.

This sets the maximum allowed refund to not exceed a specified value.

Before the London upgrade, the maximum was 50% of spent; after London, it cannot exceed 20%:

#[inline]
pub fn set_final_refund(&mut self, is_london: bool) {
    let max_refund_quotient = if is_london { 5 } else { 2 };
    //
    self.refunded = (self.refunded() as u64).min(self.spent() / max_refund_quotient) as i64;
}

eip7623_check_gas_floor

Jump to the eip7623_check_gas_floor implementation.

The name spent_sub_refunded is fairly self-explanatory: spent_sub_refunded = spent - refunded.

The result of subtracting refunded from spent is the actual gas consumed.

This ensures the minimum consumption is greater than floor_gas (the floor value) — like a restaurant's minimum charge.

It's designed to prevent nodes from being DOS-attacked with a flood of low-gas-cost transactions:

// crates/handler/src/post_execution.rs
pub fn eip7623_check_gas_floor(gas: &mut Gas, init_and_floor_gas: InitialAndFloorGas) {
    // spent_sub_refunded = spent - refunded
    // i.e., the actual gas spent, ensuring actual gas spent meets the floor
    if gas.spent_sub_refunded() < init_and_floor_gas.floor_gas {
        gas.set_spent(init_and_floor_gas.floor_gas);
        gas.set_refund(0);
    }
}

reimburse_caller

Jump to the reimburse_caller implementation.

Earlier we only calculated the spent and refund settings — the actual refund hasn't been returned to the Caller yet.

This is where the pending gas refund is added to the Caller's account.

additional_refund is 0 in the current EVM version.

effective_gas_price uses the same formula as mentioned before:

GasPrice = Priority Fee + min(Base Fee, Max Fee - Base Fee)

The subsequent logic is straightforward, layer by layer from inside out.

Total refund GasLimit = (gas.remaining() + gas.refunded() as u64)

saturating_mul is multiplication.

context.journal_mut().load_account_mut(caller)?.incr_balance finds the caller and increases their balance:

// crates/handler/src/post_execution.rs
#[inline]
pub fn reimburse_caller<CTX: ContextTr>(
    context: &mut CTX,
    gas: &Gas,
    additional_refund: U256,
) -> Result<(), <CTX::Db as Database>::Error> {
    let basefee = context.block().basefee() as u128;
    let caller = context.tx().caller();
    let effective_gas_price = context.tx().effective_gas_price(basefee);

    context
        .journal_mut()
        .load_account_mut(caller)?
        .incr_balance(
            U256::from(
                effective_gas_price
                    .saturating_mul((gas.remaining() + gas.refunded() as u64) as u128),
            ) + additional_refund,
        );

    Ok(())
}

reward_beneficiary

Pays the tx's Gas fees to the miner.

This is the Priority reward from tx Gas fees, not the block mining reward.

Before EIP-1559, miners could take the entire GasPrice set by the user.

After EIP-1559, miners can only take the PriorityFee reward — the BaseFee portion is burned.

The main difficulty here is EIP-1559; the rest of the logic is fairly simple:

// crates/handler/src/post_execution.rs
#[inline]
pub fn reward_beneficiary<CTX: ContextTr>(
    context: &mut CTX,
    gas: &Gas,
) -> Result<(), <CTX::Db as Database>::Error> {
    let (block, tx, cfg, journal, _, _) = context.all_mut();
    let basefee = block.basefee() as u128;
    let effective_gas_price = tx.effective_gas_price(basefee);

    // Transfer fee to coinbase/beneficiary.
    // EIP-1559 discard basefee for coinbase transfer. Basefee amount of gas is discarded.
    let coinbase_gas_price = if cfg.spec().into().is_enabled_in(SpecId::LONDON) {
        effective_gas_price.saturating_sub(basefee)
    } else {
        effective_gas_price
    };

    // reward beneficiary
    journal
        .load_account_mut(block.beneficiary())?
        .incr_balance(U256::from(coinbase_gas_price * gas.used() as u128));

    Ok(())
}

ExecutionResult

core::mem::replace(evm.ctx().error(), Ok(())) checks whether there were errors during previous execution:

DB error → directly return Err
Custom error → convert to Self::Error and return
Ok → continue execution

// crates/handler/src/handler.rs
fn execution_result(
        &mut self,
        evm: &mut Self::Evm,
        result: <<Self::Evm as EvmTr>::Frame as FrameTr>::FrameResult,
    ) -> Result<ExecutionResult<Self::HaltReason>, Self::Error> {
        match core::mem::replace(evm.ctx().error(), Ok(())) {
            Err(ContextError::Db(e)) => return Err(e.into()),
            Err(ContextError::Custom(e)) => return Err(Self::Error::from_string(e)),
            Ok(()) => (),
        }

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

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

        Ok(exec_result)
    }

post_execution::output

Processes the execution result return value — nothing special to explain here, skipping:

// crates/handler/src/post_execution.rs
pub fn output<CTX: ContextTr<Journal: JournalTr>, HALTREASON: HaltReasonTr>(
    context: &mut CTX,
    // TODO, make this more generic and nice.
    // FrameResult should be a generic that returns gas and interpreter result.
    result: FrameResult,
) -> ExecutionResult<HALTREASON> {
    // Used gas with refund calculated.
    let gas_refunded = result.gas().refunded() as u64;
    let gas_used = result.gas().used();
    let output = result.output();
    let instruction_result = result.into_interpreter_result();

    // take logs from journal.
    let logs = context.journal_mut().take_logs();

    match SuccessOrHalt::<HALTREASON>::from(instruction_result.result) {
        SuccessOrHalt::Success(reason) => ExecutionResult::Success {
            reason,
            gas_used,
            gas_refunded,
            logs,
            output,
        },
        SuccessOrHalt::Revert => ExecutionResult::Revert {
            gas_used,
            output: output.into_data(),
        },
        SuccessOrHalt::Halt(reason) => {
            // Bubble up precompile errors from context when available
            if matches!(
                instruction_result.result,
                interpreter::InstructionResult::PrecompileError
            ) {
                if let Some(message) = context.local_mut().take_precompile_error_context() {
                    return ExecutionResult::Halt {
                        reason: HALTREASON::from(HaltReason::PrecompileErrorWithContext(message)),
                        gas_used,
                    };
                }
            }
            ExecutionResult::Halt { reason, gas_used }
        }
        // Only two internal return flags.
        flag @ (SuccessOrHalt::FatalExternalError | SuccessOrHalt::Internal(_)) => {
            panic!(
                "Encountered unexpected internal return flag: {flag:?} with instruction result: {instruction_result:?}"
            )
        }
    }
}

evm.ctx().journal_mut().commit_tx()

The name here is a bit misleading — it sounds like it commits and saves the current tx's execution results to the database.

But actually, this mainly prepares for the next tx.

The entire function has no commit/write operations, only clearing and resetting:

// crates/context/src/journal/inner.rs
pub fn commit_tx(&mut self) {
        // Clears all field from JournalInner. Doing it this way to avoid
        // missing any field.
        let Self {
            state,
            transient_storage,
            logs,
            depth,
            journal,
            transaction_id,
            spec,
            warm_addresses,
        } = self;

        let _ = spec;
        let _ = state;
        transient_storage.clear();
        *depth = 0;

        journal.clear();

        warm_addresses.clear_coinbase_and_access_list();
        *transaction_id += 1;

        logs.clear();
    }

The subsequent evm.ctx().local_mut().clear(); and evm.frame_stack().clear(); are also just clearing.

So where is the logic that actually commits changes and saves to the database?

evm.ctx().journal_mut().finalize

Let's go back to the first article.

Jump to examples/erc20_gas/src/exec.rs -> transact_erc20evm.

Here the results from Erc20MainnetHandler::new().run are processed:

pub fn transact_erc20evm<EVM>(
    evm: &mut EVM,
) -> Result<(ExecutionResult<HaltReason>, EvmState), Erc20Error<EVM::Context>>
where
    EVM: EvmTr<
        Context: ContextTr<Journal: JournalTr<State = EvmState>>,
        Precompiles: PrecompileProvider<EVM::Context, Output = InterpreterResult>,
        Instructions: InstructionProvider<
            Context = EVM::Context,
            InterpreterTypes = EthInterpreter,
        >,
        Frame = EthFrame<EthInterpreter>,
    >,
{
    Erc20MainnetHandler::new().run(evm).map(|r| {
        let state = evm.ctx().journal_mut().finalize();
        (r, state)
    })
}

Jump directly to the finalize implementation.

It's another round of clearing and resetting, but the difference is it returns the state, and transaction_id is also reset to 0.

commit_tx is executed after each tx ends, preparing for the next tx. At this point, data is still held in memory.

finalize is called after the current block has finished executing all its txs:

// 
#[inline]
pub fn finalize(&mut self) -> EvmState {
    let Self {
        state,
        transient_storage,
        logs,
        depth,
        journal,
        transaction_id,
        spec,
        warm_addresses,
    } = self;
    let _ = spec;
    warm_addresses.clear_coinbase_and_access_list();

    let state = mem::take(state);
    logs.clear();
    transient_storage.clear();

    journal.clear();
    *depth = 0;
    *transaction_id = 0;

    state
}

evm.ctx().db_mut().commit

Jump back to examples/erc20_gas/src/exec.rs -> transact_erc20evm_commit.

Here the return result from transact_erc20evm is processed:

// examples/erc20_gas/src/exec.rs
pub fn transact_erc20evm_commit<EVM>(
    evm: &mut EVM,
) -> Result<ExecutionResult<HaltReason>, Erc20Error<EVM::Context>>
where
    EVM: EvmTr<
        Context: ContextTr<Journal: JournalTr<State = EvmState>, Db: DatabaseCommit>,
        Precompiles: PrecompileProvider<EVM::Context, Output = InterpreterResult>,
        Instructions: InstructionProvider<
            Context = EVM::Context,
            InterpreterTypes = EthInterpreter,
        >,
        Frame = EthFrame<EthInterpreter>,
    >,
{
    transact_erc20evm(evm).map(|(result, state)| {
        evm.ctx().db_mut().commit(state);
        result
    })
}

Let's click into commit.

It jumps to DatabaseCommit.

First, a note: this can be any database, as long as it implements the various Traits required by EVM.

Because EVM is only responsible for TX execution, not the database persistence layer.

The database is provided by the party that calls EVM for TX execution.

For example, RETH calls REVM — the database is provided by RETH.

In the Example we're looking at, erc20_gas calls EVM, so the database is provided by erc20_gas:

// crates/database/interface/src/lib.rs
#[auto_impl(&mut, Box)]
pub trait DatabaseCommit {
    /// Commit changes to the database.
    fn commit(&mut self, changes: HashMap<Address, Account>);
    fn commit_iter(&mut self, changes: impl IntoIterator<Item = (Address, Account)>) {
        let changes: HashMap<Address, Account> = changes.into_iter().collect();
        self.commit(changes);
    }
}

Back to examples/erc20_gas/src/main.rs -> transfer.

with_db(cache_db) — this is where the db is passed in and set:

// examples/erc20_gas/src/main.rs
// type AlloyCacheDB = CacheDB<WrapDatabaseAsync<AlloyDB<Ethereum, DynProvider>>>;
fn transfer(from: Address, to: Address, amount: U256, cache_db: &mut AlloyCacheDB) -> Result<()> {
    let mut ctx = Context::mainnet()
        .with_db(cache_db)
        .modify_cfg_chained(|cfg| {
            cfg.spec = SpecId::CANCUN;
        })
        .with_tx(
            TxEnv::builder()
                .caller(from)
                .kind(TxKind::Call(to))
                .value(amount)
                .gas_price(2)
                .build()
                .unwrap(),
        )
        .modify_block_chained(|b| {
            b.basefee = 1;
        })
        .build_mainnet();

    transact_erc20evm_commit(&mut ctx).unwrap();

    Ok(())
}

It uses AlloyCacheDB — let's jump directly to AlloyCacheDB's commit implementation.

Nothing special to say — check it out yourself if interested:

impl<ExtDB> DatabaseCommit for CacheDB<ExtDB> {
    fn commit(&mut self, changes: HashMap<Address, Account>) {
        for (address, mut account) in changes {
            if !account.is_touched() {
                continue;
            }
            if account.is_selfdestructed() {
                let db_account = self.cache.accounts.entry(address).or_default();
                db_account.storage.clear();
                db_account.account_state = AccountState::NotExisting;
                db_account.info = AccountInfo::default();
                continue;
            }
            let is_newly_created = account.is_created();
            self.insert_contract(&mut account.info);

            let db_account = self.cache.accounts.entry(address).or_default();
            db_account.info = account.info;

            db_account.account_state = if is_newly_created {
                db_account.storage.clear();
                AccountState::StorageCleared
            } else if db_account.account_state.is_storage_cleared() {
                // Preserve old account state if it already exists
                AccountState::StorageCleared
            } else {
                AccountState::Touched
            };
            db_account.storage.extend(
                account
                    .storage
                    .into_iter()
                    .map(|(key, value)| (key, value.present_value())),
            );
        }
    }
}

REVM Source Code - Execution Flow Part 4

TangHaosuan — Fri, 03 Apr 2026 13:57:59 +0000

Execute

The Execute stage is the most important in the entire flow.

All transactions are executed here.

Let's jump directly to the source implementation.

The second parameter, init_and_floor_gas, is the return value from the Validate stage — it represents the transaction's "initial gas consumption + floor gas limit".

gas_limit = tx's GasLimit - init_and_floor_gas.initial_gas

// crates/handler/src/handler.rs
    #[inline]
    fn execution(
        &mut self,
        evm: &mut Self::Evm,
        init_and_floor_gas: &InitialAndFloorGas,
    ) -> Result<FrameResult, Self::Error> {
        let gas_limit = evm.ctx().tx().gas_limit() - init_and_floor_gas.initial_gas;
        // Create first frame action
        let first_frame_input = self.first_frame_input(evm, gas_limit)?;

        // 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)?;
        Ok(frame_result)
    }

1. first_frame_input

Creates the initial frame input using transaction parameters, gas limit, and configuration.

Let's jump directly to the code implementation:

// crates/handler/src/handler.rs
#[inline]
    fn first_frame_input(
        &mut self,
        evm: &mut Self::Evm,
        gas_limit: u64,
    ) -> Result<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 (tx, journal) = ctx.tx_journal_mut();
        let bytecode = if let Some(&to) = tx.kind().to() {
            let account = &journal.load_account_with_code(to)?.info;

            if let Some(Bytecode::Eip7702(eip7702_bytecode)) = &account.code {
                let delegated_address = eip7702_bytecode.delegated_address;
                let account = &journal.load_account_with_code(delegated_address)?.info;
                Some((
                    account.code.clone().unwrap_or_default(),
                    account.code_hash(),
                ))
            } else {
                Some((
                    account.code.clone().unwrap_or_default(),
                    account.code_hash(),
                ))
            }
        } else {
            None
        };

        Ok(FrameInit {
            depth: 0,
            memory,
            frame_input: execution::create_init_frame(tx, bytecode, gas_limit),
        })
    }

ctx.local() returns a LocalContext, whose purpose is to provide a "local, temporary, shared context cache" for the current transaction (tx). It's used throughout the entire transaction execution process (including multiple call layers) to reuse resources and state, avoiding redundant allocation and copying, improving performance, and handling special scenarios (such as initcode transactions, precompile error propagation).

SharedMemory::new_with_buffer simply wraps an outer layer, packaging Rc<RefCell<Vec<u8>>> (i.e., ctx.local().shared_memory_buffer()) into a safer, more user-friendly, pre-allocatable shared memory object. The goal is to make memory copying and slicing operations during transaction execution more efficient and less error-prone, while maintaining the performance advantage of sharing a single buffer across the entire tx.

I haven't looked into SharedMemory and LocalContext in detail yet — the above is Grok's explanation.

Let's finish the flow first, and cover them in separate chapters later.

tx.kind was introduced earlier — it's divided into Create and Call.

Contract creation is Create; contract calls and transfers are Call.

EIP-4844 and EIP-7702 can only Call, cannot Create.

Here we get the tx's to:

if let Some(&to) = tx.kind().to()

Gets the to's code and checks if it's EIP7702.

If so, finds the delegated address and loads the delegated address's code:

if let Some(Bytecode::Eip7702(eip7702_bytecode)) = &account.code {
    let delegated_address = eip7702_bytecode.delegated_address;
    let account = &journal.load_account_with_code(delegated_address)?.info;
    Some((
        account.code.clone().unwrap_or_default(),
        account.code_hash(),
    ))
}

If it's not EIP7702, it's a contract — directly get the contract's code:

else {
    Some((
        account.code.clone().unwrap_or_default(),
        account.code_hash(),
    ))
}

Let's briefly introduce Frame here.

A Frame is a Call Frame. During EVM execution, every inter-contract call (not function calls), such as CALL, DELEGATECALL, STATICCALL, CREATE, generates a Frame containing the context for that call.

Later there will also be a frame_stack responsible for storing all generated frames.

Return result of first_frame_input:

depth refers to the frame call depth — for example, if contract A calls contract B, which then calls contract C, contract C's frame depth is 2.

FrameInit {
    depth: 0,
    memory,
    frame_input: execution::create_init_frame(tx, bytecode, gas_limit),
}

create_init_frame doesn't need special explanation either — it returns a FrameInput type:

// crates/handler/src/execution.rs
#[inline]
pub fn create_init_frame(
    tx: &impl Transaction,
    bytecode: Option<(Bytecode, B256)>,
    gas_limit: u64,
) -> FrameInput {
    let input = tx.input().clone();

    match tx.kind() {
        TxKind::Call(target_address) => {
            let known_bytecode = bytecode.map(|(code, hash)| (hash, code));
            FrameInput::Call(Box::new(CallInputs {
                input: CallInput::Bytes(input),
                gas_limit,
                target_address,
                bytecode_address: target_address,
                known_bytecode,
                caller: tx.caller(),
                value: CallValue::Transfer(tx.value()),
                scheme: CallScheme::Call,
                is_static: false,
                return_memory_offset: 0..0,
            }))
        }
        TxKind::Create => FrameInput::Create(Box::new(CreateInputs::new(
            tx.caller(),
            CreateScheme::Create,
            tx.value(),
            input,
            gas_limit,
        ))),
    }
}

2. run_exec_loop

The functionality of run_exec_loop as described in the comments:

Executes the main frame processing loop. This loop manages the frame stack, processing each frame until execution completes.

Each iteration:

Runs the current frame
Handles the returned frame input or result
Creates new frames or propagates results as needed

Let's look at the code directly.

The input parameters are EVM and the FrameInit returned from the previous step first_frame_input.

// crates/handler/src/handler.rs
#[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);
            }
        }
    }

Let's first look at the frame_init implementation:

frame_init

// crates/handler/src/evm.rs
#[inline]
    fn frame_init(
        &mut self,
        frame_input: <Self::Frame as FrameTr>::FrameInit,
    ) -> Result<FrameInitResult<'_, Self::Frame>, ContextDbError<CTX>> {
        let is_first_init = self.frame_stack.index().is_none();
        let new_frame = if is_first_init {
            self.frame_stack.start_init()
        } else {
            self.frame_stack.get_next()
        };

        let ctx = &mut self.ctx;
        let precompiles = &mut self.precompiles;
        let res = Self::Frame::init_with_context(
            new_frame,
            ctx,
            precompiles,
            frame_input,
            self.instruction.gas_params(),
        )?;

        Ok(res.map_frame(|token| {
            if is_first_init {
                unsafe { self.frame_stack.end_init(token) };
            } else {
                unsafe { self.frame_stack.push(token) };
            }
            self.frame_stack.get()
        }))
    }

Determines whether this is the first initialization based on frame_stack.index.

Calls start_init and get_next respectively:

start_init
- If the stack is empty, pre-allocates space for 8 elements
get_next
- If the stack is full, pre-allocates space for 8 more elements
out_frame_at returns a reference to the element at the given position

// crates/context/interface/src/local.rs
#[inline]
pub fn start_init(&mut self) -> OutFrame<'_, T> {
    self.index = None;
    if self.stack.is_empty() {
        self.stack.reserve(8);
    }
    self.out_frame_at(0)
}
#[inline]
pub fn get_next(&mut self) -> OutFrame<'_, T> {
    if self.index.unwrap() + 1 == self.stack.capacity() {
        // allocate 8 more items
        self.stack.reserve(8);
    }
    self.out_frame_at(self.index.unwrap() + 1)
}

Continuing further, the main focus is init_with_context:

init_with_context

The purpose of init_with_context is to initialize a frame with the given context and precompiles.

Let's jump to the implementation. First, an explanation of the input parameters:

OutFrame — the empty Frame created and returned by start_init and get_next above
precompiles — precompiled contracts
frame_init — returned from the earlier call to first_frame_input
gas_params — instruction.gas_params(), stores the base gas consumption for each opcode (static part only; if memory expansion or similar occurs during execution, additional gas is charged)

// crates/handler/src/frame.rs
pub fn init_with_context<
        CTX: ContextTr,
        PRECOMPILES: PrecompileProvider<CTX, Output = InterpreterResult>,
    >(
        this: OutFrame<'_, Self>,
        ctx: &mut CTX,
        precompiles: &mut PRECOMPILES,
        frame_init: FrameInit,
        gas_params: GasParams,
    ) -> Result<
        ItemOrResult<FrameToken, FrameResult>,
        ContextError<<<CTX as ContextTr>::Db as Database>::Error>,
    > {
        // TODO cleanup inner make functions
        let FrameInit {
            depth,
            memory,
            frame_input,
        } = frame_init;

        match frame_input {
            FrameInput::Call(inputs) => {
                Self::make_call_frame(this, ctx, precompiles, depth, memory, inputs, gas_params)
            }
            FrameInput::Create(inputs) => {
                Self::make_create_frame(this, ctx, depth, memory, inputs, gas_params)
            }
            FrameInput::Empty => unreachable!(),
        }
    }
}

Different Frames are generated based on the frame_input type. frame_input is from the result returned by first_frame_input.

make_call_frame

The function is too long, so we won't paste it all this time.

Let's first cover the function parameters — only the parts not in init_with_context:

depth — current inter-contract call depth
memory — the shared context cache mentioned in first_frame_input
inputs — the frame_input returned earlier

Continuing with the function implementation.

This creates a closure for returning error results:

// crates/handler/src/frame.rs -> make_call_frame
let return_result = |instruction_result: InstructionResult| {
    Ok(ItemOrResult::Result(FrameResult::Call(CallOutcome {
        result: InterpreterResult {
            result: instruction_result,
            gas,
            output: Bytes::new(),
        },
        memory_offset: inputs.return_memory_offset.clone(),
        was_precompile_called: false,
        precompile_call_logs: Vec::new(),
    })))
};

Creates a checkpoint, used to revert to this point if execution fails later:

let checkpoint = ctx.journal_mut().checkpoint();

Let's jump in and look at the checkpoint implementation.

It simply creates a JournalCheckpoint and returns it.

We'll cover the Revert mechanism later.

The depth here is the same thing mentioned earlier — the inter-contract call depth.

However, here depth is a global state:

// crates/context/src/journal/inner.rs
#[inline]
pub fn checkpoint(&mut self) -> JournalCheckpoint {
    let checkpoint = JournalCheckpoint {
        log_i: self.logs.len(),
        journal_i: self.journal.len(),
    };
    self.depth += 1;
    checkpoint
}

Continuing further — if the tx has a value, the Balance is pre-deducted from from and added to to:

// crates/handler/src/frame.rs -> make_call_frame
if let CallValue::Transfer(value) = inputs.value {
    // Transfer value from caller to called account
    // Target will get touched even if balance transferred is zero.
    if let Some(i) =
        ctx.journal_mut()
            .transfer_loaded(inputs.caller, inputs.target_address, value)
    {
        ctx.journal_mut().checkpoint_revert(checkpoint);
        return return_result(i.into());
    }
}

Let's look at the transfer_loaded implementation — explanations are provided directly in the comments:

// crates/context/src/journal/inner.rs
#[inline]
    pub fn transfer_loaded(
        &mut self,
        from: Address,
        to: Address,
        balance: U256,
    ) -> Option<TransferError> {
        // Self-transfer case
        if from == to {
            let from_balance = self.state.get_mut(&to).unwrap().info.balance;
            // Check if from balance is enough to transfer the balance.
            if balance > from_balance {
                return Some(TransferError::OutOfFunds);
            }
            return None;
        }
        // Case where tx.value is 0
        // touch_account marks the account as touched, to facilitate account state handling after transaction completion
        if balance.is_zero() {
            Self::touch_account(&mut self.journal, to, self.state.get_mut(&to).unwrap());
            return None;
        }
        // Deduct from's balance
        let from_account = self.state.get_mut(&from).unwrap();
        Self::touch_account(&mut self.journal, from, from_account);
        let from_balance = &mut from_account.info.balance;
        let Some(from_balance_decr) = from_balance.checked_sub(balance) else {
            return Some(TransferError::OutOfFunds);
        };
        *from_balance = from_balance_decr;

        // Add to to's balance
        let to_account = self.state.get_mut(&to).unwrap();
        Self::touch_account(&mut self.journal, to, to_account);
        let to_balance = &mut to_account.info.balance;
        let Some(to_balance_incr) = to_balance.checked_add(balance) else {
            // Overflow of U256 balance is not possible to happen on mainnet. We don't bother to return funds from from_acc.
            return Some(TransferError::OverflowPayment);
        };
        *to_balance = to_balance_incr;

        // Push journal entry — every change is pushed for later revert
        self.journal
            .push(ENTRY::balance_transfer(from, to, balance));

        None
    }

Let's continue and look at the checkpoint_revert implementation.

The revert mechanism works by saving every change to the journal — what's saved is the differential change, not the state.

Just like git, it saves the diff each time rather than a full copy.

Revert works by undoing changes from back to front until the checkpoint is reached.

The logic here is explained directly in the comments:

// crates/context/src/journal/inner.rs
#[inline]
    pub fn checkpoint_revert(&mut self, checkpoint: JournalCheckpoint) {
        let is_spurious_dragon_enabled = self.spec.is_enabled_in(SPURIOUS_DRAGON);
        let state = &mut self.state;
        let transient_storage = &mut self.transient_storage;
        // The checkpoint was generated when the contract call started,
        // reverting means undoing this contract call, so depth - 1
        self.depth = self.depth.saturating_sub(1);
        // Truncate logs to the log position saved at checkpoint time.
        // This effectively deletes all logs after the checkpoint
        self.logs.truncate(checkpoint.log_i);
        // self.journal.drain(checkpoint.journal_i..) removes all entries after the checkpoint
        // and returns them as an iterator, then .rev() reverses the order
        // This means restoring step by step from back to front
        if checkpoint.journal_i < self.journal.len() {
            self.journal
                .drain(checkpoint.journal_i..)
                .rev()
                .for_each(|entry| {
                    entry.revert(state, Some(transient_storage), is_spurious_dragon_enabled);
                });
        }
    }

The key part is entry.revert, which handles each situation individually.

The code is too long to paste — check it out yourself if interested.

Location: crates/context/interface/src/journaled_state/entry.rs -> revert

Continuing with the make_call_frame logic.

This checks whether tx.to is a precompile address.

If so, it goes directly to the precompile logic rather than the interpreter logic — saving time and improving performance.

We won't dive deep into precompiles.run here.

// crates/handler/src/frame.rs -> make_call_frame
let interpreter_input = InputsImpl {
    target_address: inputs.target_address,
    caller_address: inputs.caller,
    bytecode_address: Some(inputs.bytecode_address),
    input: inputs.input.clone(),
    call_value: inputs.value.get(),
};
let is_static = inputs.is_static;
let gas_limit = inputs.gas_limit;

if let Some(result) = precompiles.run(ctx, &inputs).map_err(ERROR::from_string)? {
    let mut logs = Vec::new();
    if result.result.is_ok() {
        ctx.journal_mut().checkpoint_commit();
    } else {
        // If precompile execution errors, revert
        logs = ctx.journal_mut().logs()[checkpoint.log_i..].to_vec();
        ctx.journal_mut().checkpoint_revert(checkpoint);
    }
    return Ok(ItemOrResult::Result(FrameResult::Call(CallOutcome {
        result,
        memory_offset: inputs.return_memory_offset.clone(),
        was_precompile_called: true,
        precompile_call_logs: logs,
    })));
}

Continuing further.

This handles a special case branch.

When forking mainnet or simulating transactions, the caller may have already obtained the bytecode from RPC or cache, so passing in known_bytecode directly is faster — avoiding load_account_with_code every time.

If known_bytecode doesn't exist, it's loaded from the database.

If the bytecode is empty, it means to is an EOA account — return directly:

// crates/handler/src/frame.rs -> make_call_frame
let (bytecode, bytecode_hash) = if let Some((hash, code)) = inputs.known_bytecode.clone() {
    (code, hash)
} else {
    let account = ctx
        .journal_mut()
        .load_account_with_code(inputs.bytecode_address)?;
    (
        account.info.code.clone().unwrap_or_default(),
        account.info.code_hash,
    )
};

// 
if bytecode.is_empty() {
    ctx.journal_mut().checkpoint_commit();
    return return_result(InstructionResult::Stop);
}

Continuing further.

Initialize and start a new CallFrame.

get(EthFrame::invalid).clear finds the invalid frame in the stack and resets it to a new CallFrame.

Ok(ItemOrResult::Item(this.consume())) indicates the frame has been initialized:

// crates/handler/src/frame.rs -> make_call_frame
this.get(EthFrame::invalid).clear(
    FrameData::Call(CallFrame {
        return_memory_range: inputs.return_memory_offset.clone(),
    }),
    FrameInput::Call(inputs),
    depth,
    memory,
    ExtBytecode::new_with_hash(bytecode, bytecode_hash),
    interpreter_input,
    is_static,
    ctx.cfg().spec().into(),
    gas_limit,
    checkpoint,
    gas_params,
);
Ok(ItemOrResult::Item(this.consume()))

make_create_frame

Function parameters are the same as above:

depth — current inter-contract call depth
memory — the shared context cache mentioned in first_frame_input
inputs — the frame_input returned earlier

Many parts are similar to make_call_frame — we'll mainly cover the differences.

Here it checks whether Create or Create2 is used.

The two compute addresses differently and produce different addresses.

CREATE2's generation is independent of nonce, so it can produce the same address each time.

CREATE address = last 20 bytes of keccak256(rlp([sender_address, sender_nonce]))
CREATE2 last 20 bytes of keccak256(0xff ++ sender_address ++ salt ++ keccak256(initcode))

We won't dive into the details here — check it out yourself if interested:

// crates/handler/src/frame.rs -> make_create_frame
let mut init_code_hash = None;
let created_address = match inputs.scheme() {
    CreateScheme::Create => inputs.caller().create(old_nonce),
    CreateScheme::Create2 { salt } => {
        let init_code_hash = *init_code_hash.insert(keccak256(inputs.init_code()));
        inputs.caller().create2(salt.to_be_bytes(), init_code_hash)
    }
    CreateScheme::Custom { address } => address,
};

Continuing further.

Explanations directly in the code:

// crates/handler/src/frame.rs -> make_create_frame
// Wrap the transaction's init_code (initialization code) into ExtBytecode
let bytecode = ExtBytecode::new_with_optional_hash(
    Bytecode::new_legacy(inputs.init_code().clone()),
    init_code_hash,
);

// REVM interpreter (Interpreter) input structure describing the "current execution context"
let interpreter_input = InputsImpl {
    target_address: created_address,
    caller_address: inputs.caller(),
    bytecode_address: None,
    input: CallInput::Bytes(Bytes::new()),
    call_value: inputs.value(),
};
let gas_limit = inputs.gas_limit();

// Initialize and start a new CreateFrame
// get(EthFrame::invalid).clear finds the invalid frame in the stack and resets it to a new CreateFrame
this.get(EthFrame::invalid).clear(
    FrameData::Create(CreateFrame { created_address }),
    FrameInput::Create(inputs),
    depth,
    memory,
    bytecode,
    interpreter_input,
    false,
    spec,
    gas_limit,
    checkpoint,
    gas_params,
);

Back to crates/handler/src/evm.rs -> frame_init

The token mainly contains a bool value indicating whether frame initialization succeeded:

Ok(res.map_frame(|token| {
    if is_first_init {
        unsafe { self.frame_stack.end_init(token) };
    } else {
        unsafe { self.frame_stack.push(token) };
    }
    self.frame_stack.get()
}))

Remember earlier when we checked is_first_init via self.frame_stack.index().is_none()?

let is_first_init = self.frame_stack.index().is_none()

Let's look at end_init.

As you can see, end_init sets self.index to 0, so next time is_first_init will be false:

// crates/context/interface/src/local.rs
#[inline]
pub unsafe fn end_init(&mut self, token: FrameToken) {
    token.assert();
    if self.stack.is_empty() {
        unsafe { self.stack.set_len(1) };
    }
    self.index = Some(0);
}

Let's also look at push:

// crates/context/interface/src/local.rs
#[inline]
pub unsafe fn push(&mut self, token: FrameToken) {
    token.assert();
    // The index here has a similar effect to the depth mentioned earlier
    let index = self.index.as_mut().unwrap();
    *index += 1;
    // capacity of stack is incremented in `get_next`
    debug_assert!(
        *index < self.stack.capacity(),
        "Stack capacity is not enough for index"
    );
    // If index is the last element, increase the length
    if *index == self.stack.len() {
        unsafe { self.stack.set_len(self.stack.len() + 1) };
    }
}

Back to crates/handler/src/handler.rs -> run_exec_loop

// to is an EOA account, precompiled contract, or other failure cases
if let ItemOrResult::Result(frame_result) = res {
    return Ok(frame_result);
}

Continuing further — let's first explain the overall flow, then dive deeper into frame_run and frame_return_result:

loop {
    // Try to run the current frame (execute one or more opcodes)
    let call_or_result = evm.frame_run()?;

    // Based on frame_run's return, determine whether to "initialize a new frame" or "get the result directly"
    let result = match call_or_result {
        ItemOrResult::Item(init) => {
            match evm.frame_init(init)? {
                // New frame created successfully, continue loop to execute this new frame
                ItemOrResult::Item(_) => {
                    continue;
                }
                // New frame initialization failed
                ItemOrResult::Result(result) => result,
            }
        }
        ItemOrResult::Result(result) => result,
    };

    // Handle the frame's return result (may end the entire execution, or may continue)
    if let Some(result) = evm.frame_return_result(result)? {
        return Ok(result);
    }
    // If frame_return_result returns None, execution needs to continue (e.g., there are still parent frames)
}

Diving into frame_run:

// crates/handler/src/evm.rs
#[inline]
    fn frame_run(&mut self) -> Result<FrameInitOrResult<Self::Frame>, ContextDbError<CTX>> {
        // Pop the current frame from frame_stack
        let frame = self.frame_stack.get();
        let context = &mut self.ctx;
        // instructions stores opcodes and their corresponding function pointers
        let instructions = &mut self.instruction;

        let action = frame
            .interpreter
            .run_plain(instructions.instruction_table(), context);

        frame.process_next_action(context, action).inspect(|i| {
            if i.is_result() {
                frame.set_finished(true);
            }
        })
    }

Diving further into run_plain.

The logic is simple — it loops through self.bytecode, and if not empty, executes step:

// crates/interpreter/src/interpreter.rs
#[inline]
pub fn run_plain<H: Host + ?Sized>(
    &mut self,
    instruction_table: &InstructionTable<IW, H>,
    host: &mut H,
) -> InterpreterAction {
    while self.bytecode.is_not_end() {
        self.step(instruction_table, host);
    }
    self.take_next_action()
}

Diving further into step.

The flow is quite clear.

The difficulty isn't in the flow but in the opcodes.

In this article series, we won't dive deep into opcodes — there will be a dedicated series later:

#[inline]
    pub fn step<H: Host + ?Sized>(
        &mut self,
        instruction_table: &InstructionTable<IW, H>,
        host: &mut H,
    ) {
        // Get the current opcode
        let opcode = self.bytecode.opcode();
        // Jump to the next opcode
        self.bytecode.relative_jump(1);

        // Get the function corresponding to the opcode
        let instruction = unsafe { instruction_table.get_unchecked(opcode as usize) };

        // Get the static gas for the current instruction
        // Check if current gas is sufficient; if not, return out-of-gas error
        if self.gas.record_cost_unsafe(instruction.static_gas()) {
            return self.halt_oog();
        }
        let context = InstructionContext {
            interpreter: self,
            host,
        };
        // Execute
        instruction.execute(context);
    }

take_next_action

During frame execution (running opcodes), some actions are generated.

For example, CALL, CREATE, RETURN — as mentioned earlier, inter-contract calls generate new frames.

After generating an action, the loop breaks (while self.bytecode.is_not_end()).

take_next_action extracts the action and hands it to the outer frame_run for processing:

// crates/interpreter/src/interpreter.rs
#[inline]
pub fn take_next_action(&mut self) -> InterpreterAction {
    self.bytecode.reset_action();
    // Return next action if it is some.
    let action = core::mem::take(self.bytecode.action()).expect("Interpreter to set action");
    action
}

Back to frame_run:

frame.process_next_action(context, action).inspect(|i| {
    if i.is_result() {
        frame.set_finished(true);
    }
})

Jumping to the actual implementation:

// crates/handler/src/frame.rs
pub fn process_next_action<
        CTX: ContextTr,
        ERROR: From<ContextTrDbError<CTX>> + FromStringError,
    >(
        &mut self,
        context: &mut CTX,
        next_action: InterpreterAction,
    ) -> Result<FrameInitOrResult<Self>, ERROR> {
        let spec = context.cfg().spec().into();
        // Handle the action returned by take_next_action here
        let mut interpreter_result = match next_action {
            // This returns the result for creating a new frame
            // The actual processing doesn't happen here, but in the outer handler's run_exec_loop, going through the flow again
            InterpreterAction::NewFrame(frame_input) => {
                let depth = self.depth + 1;
                return Ok(ItemOrResult::Item(FrameInit {
                    frame_input,
                    depth,
                    memory: self.interpreter.memory.new_child_context(),
                }));
            }
            // Frame ended (includes both normal and abnormal endings)
            InterpreterAction::Return(result) => result,
        };

        // Handle the frame's return — this is similar to tx.kind
        // Only two result types: call and create
        let result = match &self.data {
            FrameData::Call(frame) => {
                // Normal result
                if interpreter_result.result.is_ok() {
                    context.journal_mut().checkpoint_commit();
                } else {
                    // Frame revert case
                    context.journal_mut().checkpoint_revert(self.checkpoint);
                }
                ItemOrResult::Result(FrameResult::Call(CallOutcome::new(
                    interpreter_result,
                    frame.return_memory_range.clone(),
                )))
            }
            FrameData::Create(frame) => {
                let max_code_size = context.cfg().max_code_size();
                let is_eip3541_disabled = context.cfg().is_eip3541_disabled();
                return_create(
                    context.journal_mut(),
                    self.checkpoint,
                    &mut interpreter_result,
                    frame.created_address,
                    max_code_size,
                    is_eip3541_disabled,
                    spec,
                );

                ItemOrResult::Result(FrameResult::Create(CreateOutcome::new(
                    interpreter_result,
                    Some(frame.created_address),
                )))
            }
        };

        Ok(result)
    }

Jumping back to crates/handler/src/handler.rs -> run_exec_loop:

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

Let's look at the implementation.

Explanations directly in the code:

// crates/handler/src/evm.rs
#[inline]
    fn frame_return_result(
        &mut self,
        result: <Self::Frame as FrameTr>::FrameResult,
    ) -> Result<Option<<Self::Frame as FrameTr>::FrameResult>, ContextDbError<Self::Context>> {
        // Check if the current frame has finished
        // If so, pop it — now the stack top becomes the parent frame
        if self.frame_stack.get().is_finished() {
            self.frame_stack.pop();
        }
        // If index is None after popping, we've reached the outermost layer
        // Transaction execution is complete
        if self.frame_stack.index().is_none() {
            return Ok(Some(result));
        }
        // After the pop above, the stack top is the parent frame
        // Here the current frame's return_result is passed back to the parent frame
        self.frame_stack
            .get()
            .return_result::<_, ContextDbError<Self::Context>>(&mut self.ctx, result)?;
        Ok(None)
    }

Jumping back to the outermost crates/handler/src/handler.rs > execution:

last_frame_result

This handles Gas refund processing:

#[inline]
    fn last_frame_result(
        &mut self,
        evm: &mut Self::Evm,
        frame_result: &mut <<Self::Evm as EvmTr>::Frame as FrameTr>::FrameResult,
    ) -> Result<(), Self::Error> {
        let instruction_result = frame_result.interpreter_result().result;
        // The current frame's gas struct, containing spent, remaining, and refunded
        let gas = frame_result.gas_mut();
        // Remaining gas — to be returned to the caller later
        let remaining = gas.remaining();
        // Refundable gas — refunds generated by SSTORE zeroing, SELFDESTRUCT, etc.
        let refunded = gas.refunded();
        // Pre-deduct all gas first, then calculate refunds later
        *gas = Gas::new_spent(evm.ctx().tx().gas_limit());
        // Regardless of success or failure, refund remaining gas from execution
        if instruction_result.is_ok_or_revert() {
            gas.erase_cost(remaining);
        }
        // Only refund on successful execution; no refund on revert
        if instruction_result.is_ok() {
            gas.record_refund(refunded);
        }
        Ok(())
    }

REVM Source Code - Execution Flow Part 3

TangHaosuan — Fri, 03 Apr 2026 13:56:51 +0000

PreExecute

According to the code comments, PreExecute is responsible for:

Preparing the EVM state for execution
Loading the beneficiary account (EIP-3651: Warm COINBASE) and all accounts/storage from the access list (EIP-2929)
Deducting the maximum possible fees from the caller's balance
For EIP-7702 transactions, applying the authorization list and delegating successful authorizations
Returning the EIP-7702 gas refund amount. Authorizations are applied before execution begins

That's rather abstract, so let's jump directly to the source code:

// crates/handler/src/handler.rs
    #[inline]
    fn pre_execution(&self, evm: &mut Self::Evm) -> Result<u64, Self::Error> {
        self.validate_against_state_and_deduct_caller(evm)?;
        self.load_accounts(evm)?;

        let gas = self.apply_eip7702_auth_list(evm)?;
        Ok(gas)
    }

It's divided into 3 steps. Let's look at step 1 first: validate_against_state_and_deduct_caller.

Jump to the source implementation:

1. validate_against_state_and_deduct_caller

// crates/handler/src/handler.rs
    #[inline]
    fn validate_against_state_and_deduct_caller(
        &self,
        evm: &mut Self::Evm,
    ) -> Result<(), Self::Error> {
        pre_execution::validate_against_state_and_deduct_caller(evm.ctx())
    }

Continue jumping:

// crates/handler/src/pre_execution.rs
#[inline]
pub fn validate_against_state_and_deduct_caller<
    CTX: ContextTr,
    ERROR: From<InvalidTransaction> + From<<CTX::Db as Database>::Error>,
>(
    context: &mut CTX,
) -> Result<(), ERROR> {
    let (block, tx, cfg, journal, _, _) = context.all_mut();

    // Load caller's account.
    let mut caller = journal.load_account_with_code_mut(tx.caller())?.data;

    validate_account_nonce_and_code_with_components(&caller.account().info, tx, cfg)?;

    let new_balance = calculate_caller_fee(*caller.balance(), tx, block, cfg)?;

    caller.set_balance(new_balance);
    if tx.kind().is_call() {
        caller.bump_nonce();
    }
    Ok(())
}

Let's look at the definition of context.all_mut():

// crates/context/interface/src/context.rs
    fn all_mut(
        &mut self,
    ) -> (
        &Self::Block,
        &Self::Tx,
        &Self::Cfg,
        &mut Self::Journal,
        &mut Self::Chain,
        &mut Self::Local,
    );

The functions of these returned variables were introduced earlier, so we won't repeat them here.

Continuing to look further:

let mut caller = journal.load_account_with_code_mut(tx.caller())?.data;

This actually calls the following function (skipping the lookup/jump chain):

// crates/context/src/journal/inner.rs
/// Loads account into memory. If account is already loaded it will be marked as warm.
 #[inline]
    pub fn load_account_mut_optional_code<'a, 'db, DB: Database>(
        &'a mut self,
        db: &'db mut DB,
        address: Address,
        load_code: bool,
        skip_cold_load: bool,
    ) -> Result<StateLoad<JournaledAccount<'a, DB, ENTRY>>, JournalLoadError<DB::Error>>
    where
        'db: 'a,
    {
        let mut load = self.load_account_mut_optional(db, address, skip_cold_load)?;
        if load_code {
            load.data.load_code_preserve_error()?;
        }
        Ok(load)
    }

Database hasn't appeared before — it's responsible for data persistence. It provides all the underlying state data needed for EVM execution. Here it handles loading account information and account bytecode.

Let's first jump to the load_account_mut_optional implementation:

// crates/context/src/journal/inner.rs
#[inline(never)]
    pub fn load_account_mut_optional<'a, 'db, DB: Database>(
        &'a mut self,
        db: &'db mut DB,
        address: Address,
        skip_cold_load: bool,
    ) -> Result<StateLoad<JournaledAccount<'a, DB, ENTRY>>, JournalLoadError<DB::Error>>
    where
        'db: 'a,
    {
        let (account, is_cold) = match self.state.entry(address) {
            Entry::Occupied(entry) => {
                let account = entry.into_mut();

                // skip load if account is cold.
                let mut is_cold = account.is_cold_transaction_id(self.transaction_id);

                if unlikely(is_cold) {
                    is_cold = self
                        .warm_addresses
                        .check_is_cold(&address, skip_cold_load)?;

                    // mark it warm.
                    account.mark_warm_with_transaction_id(self.transaction_id);

                    // if it is cold loaded and we have selfdestructed locally it means that
                    // account was selfdestructed in previous transaction and we need to clear its information and storage.
                    if account.is_selfdestructed_locally() {
                        account.selfdestruct();
                        account.unmark_selfdestructed_locally();
                    }
                    // set original info to current info.
                    *account.original_info = account.info.clone();

                    // unmark locally created
                    account.unmark_created_locally();

                    // journal loading of cold account.
                    self.journal.push(ENTRY::account_warmed(address));
                }
                (account, is_cold)
            }
            Entry::Vacant(vac) => {
                // Precompiles,  among some other account(access list and coinbase included)
                // are warm loaded so we need to take that into account
                let is_cold = self
                    .warm_addresses
                    .check_is_cold(&address, skip_cold_load)?;

                let account = if let Some(account) = db.basic(address)? {
                    let mut account: Account = account.into();
                    account.transaction_id = self.transaction_id;
                    account
                } else {
                    Account::new_not_existing(self.transaction_id)
                };

                // journal loading of cold account.
                if is_cold {
                    self.journal.push(ENTRY::account_warmed(address));
                }

                (vac.insert(account), is_cold)
            }
        };

        Ok(StateLoad::new(
            JournaledAccount::new(
                address,
                account,
                &mut self.journal,
                db,
                self.warm_addresses.access_list(),
                self.transaction_id,
            ),
            is_cold,
        ))
    }

self.state is a HashMap where Key is Address and Value is Account.

This checks whether the Account has been loaded before and handles the respective logic.

Although the code checks the found case first, let's look at the not-found case first.

Entry::Vacant(vac)


// Check if the current address exists in warm_addresses
// warm_addresses contains precompiles, AccessList, and Coinbase
let is_cold = self
                    .warm_addresses
                    .check_is_cold(&address, skip_cold_load)?;

Here's the definition of warm_addresses:

// crates/context/src/journal/warm_addresses.rs
pub struct WarmAddresses {
    /// Set of warm loaded precompile addresses.
    precompile_set: HashSet<Address>,
    /// Bit vector of precompile short addresses. If address is shorter than [`SHORT_ADDRESS_CAP`] it
    /// will be stored in this bit vector for faster access.
    precompile_short_addresses: BitVec,
    /// `true` if all precompiles are short addresses.
    precompile_all_short_addresses: bool,
    /// Coinbase address.
    coinbase: Option<Address>,
    /// Access list
    access_list: HashMap<Address, HashSet<StorageKey>>,
}

check_is_cold checks whether the current address exists in any of the properties.

Too much expansion, so we won't show the code here.

Let's continue with the rest of Entry::Vacant(vac):

let account = if let Some(account) = db.basic(address)? {
                    let mut account: Account = account.into();
                    account.transaction_id = self.transaction_id;
                    account
                } else {
                    Account::new_not_existing(self.transaction_id)
                };

Looks up the address in the database. If found, sets the account's transaction_id and returns.

The transaction_id here is NOT the transaction_hash.

It's the current tx's index in the block — the tx's position in the current block.

Remember this — the reason we looked at the not-found case first is because of the transaction_id setting.

Continuing below is fairly easy to understand — if is_cold, insert into journal and self.state:

if is_cold {
                    self.journal.push(ENTRY::account_warmed(address));
                }

                (vac.insert(account), is_cold)

Now let's look at the found case:

Entry::Occupied(entry)

let account = entry.into_mut();
let mut is_cold = account.is_cold_transaction_id(self.transaction_id);

Let's jump to the is_cold_transaction_id implementation:

    #[inline]
    pub fn is_cold_transaction_id(&self, transaction_id: usize) -> bool {
        self.transaction_id != transaction_id || self.status.contains(AccountStatus::Cold)
    }

Why can self.transaction_id != transaction_id determine whether the Account is cold?

It's because the self.transaction_id was set in the not-found case earlier.

If they're equal, it means the Account was loaded during this tx execution.

If they're not equal, the Account was loaded during a previous tx execution, so it's already warm.

Continuing:

// This relates to Rust's branch prediction hint — look it up if interested, we won't expand here.
if unlikely(is_cold){
    // Already discussed above  
    is_cold = self
        .warm_addresses
        .check_is_cold(&address, skip_cold_load)?;

    // Mark as warm address
    account.mark_warm_with_transaction_id(self.transaction_id);
    // Contract self-destruct related code, skipping for now
    if account.is_selfdestructed_locally() {
        account.selfdestruct();
        account.unmark_selfdestructed_locally();
    }
    // All fairly obvious, won't go into detail
    *account.original_info = account.info.clone();
    account.unmark_created_locally();
    self.journal.push(ENTRY::account_warmed(address));
}

After covering load_account_mut_optional,

jump back to crates/context/src/journal/inner.rs -> load_account_mut_optional_code

and continue:

 if load_code {
    load.data.load_code_preserve_error()?;
}

Jump in.

The logic is fairly clear, nothing that needs special explanation.

Here code_hash is the hash of the Account's code.

EOA accounts don't have code, so code_hash is empty.

Contract accounts and abstract accounts have code, so code_hash is non-empty.

// crates/context/interface/src/journaled_state/account.rs
 pub fn load_code_preserve_error(&mut self) -> Result<&Bytecode, JournalLoadError<DB::Error>> {
    if self.account.info.code.is_none() {
        let hash = *self.code_hash();
        let code = if hash == KECCAK_EMPTY {
            Bytecode::default()
        } else {
            self.db.code_by_hash(hash)?
        };
        self.account.info.code = Some(code);
    }

    Ok(self.account.info.code.as_ref().unwrap())
}

After covering load_account_mut_optional_code,

jump back to crates/handler/src/pre_execution.rs -> validate_against_state_and_deduct_caller

and continue to:

validate_account_nonce_and_code_with_components(&caller.account().info, tx, cfg)?;

The actual call is to validate_account_nonce_and_code — let's jump directly to it.

The logic is simple — two checks:

eip3607
- This proposal prohibits contracts from signing transactions like EOA accounts using private keys
- It's meant to prevent address collision attacks — look it up if interested
nonce
- Validates whether the tx's nonce is set correctly
- nonce equals the number of transactions you've signed and committed on-chain

// crates/handler/src/pre_execution.rs
#[inline]
pub fn validate_account_nonce_and_code(
    caller_info: &AccountInfo,
    tx_nonce: u64,
    is_eip3607_disabled: bool,
    is_nonce_check_disabled: bool,
) -> Result<(), InvalidTransaction> {
    if !is_eip3607_disabled {
        let bytecode = match caller_info.code.as_ref() {
            Some(code) => code,
            None => &Bytecode::default(),
        };

        if !bytecode.is_empty() && !bytecode.is_eip7702() {
            return Err(InvalidTransaction::RejectCallerWithCode);
        }
    }

    // Check that the transaction's nonce is correct
    if !is_nonce_check_disabled {
        let tx = tx_nonce;
        let state = caller_info.nonce;
        match tx.cmp(&state) {
            Ordering::Greater => {
                return Err(InvalidTransaction::NonceTooHigh { tx, state });
            }
            Ordering::Less => {
                return Err(InvalidTransaction::NonceTooLow { tx, state });
            }
            _ => {}
        }
    }
    Ok(())
}

Back to crates/handler/src/pre_execution.rs -> validate_against_state_and_deduct_caller,

continuing:

let new_balance = calculate_caller_fee(*caller.balance(), tx, block, cfg)?;
caller.set_balance(new_balance);

Jump to the implementation:

// crates/handler/src/pre_execution.rs
#[inline]
pub fn calculate_caller_fee(
    balance: U256,
    tx: impl Transaction,
    block: impl Block,
    cfg: impl Cfg,
) -> Result<U256, InvalidTransaction> {
    let basefee = block.basefee() as u128;
    let blob_price = block.blob_gasprice().unwrap_or_default();
    let is_balance_check_disabled = cfg.is_balance_check_disabled();

    if !is_balance_check_disabled {
        tx.ensure_enough_balance(balance)?;
    }

    let effective_balance_spending = tx
        .effective_balance_spending(basefee, blob_price)
        .expect("effective balance is always smaller than max balance so it can't overflow");
    let gas_balance_spending = effective_balance_spending - tx.value();
    let mut new_balance = balance.saturating_sub(gas_balance_spending);
    if is_balance_check_disabled {
        new_balance = new_balance.max(tx.value());
    }
    Ok(new_balance)
}

The early part just fetches parameters. Let's jump directly to effective_balance_spending and look at its implementation.

Focus on the first section — this estimates the maximum fee the tx will spend:

gas_limit * max_fee + value + additional_gas_cost

// crates/context/interface/src/transaction.rs
#[inline]
    fn effective_balance_spending(
        &self,
        base_fee: u128,
        blob_price: u128,
    ) -> Result<U256, InvalidTransaction> {
        let mut effective_balance_spending = (self.gas_limit() as u128)
            .checked_mul(self.effective_gas_price(base_fee))
            .and_then(|gas_cost| U256::from(gas_cost).checked_add(self.value()))
            .ok_or(InvalidTransaction::OverflowPaymentInTransaction)?;

        // add blob fee
        if self.tx_type() == TransactionType::Eip4844 {
            let blob_gas = self.total_blob_gas() as u128;
            effective_balance_spending = effective_balance_spending
                .checked_add(U256::from(blob_price.saturating_mul(blob_gas)))
                .ok_or(InvalidTransaction::OverflowPaymentInTransaction)?;
        }

        Ok(effective_balance_spending)
    }

Jump to effective_gas_price.

Gas Price is similar to the validate_tx_env from the previous article, so we won't go into detail.

You can compare them:

// crates/context/interface/src/transaction.rs
fn effective_gas_price(&self, base_fee: u128) -> u128 {
        if self.tx_type() == TransactionType::Legacy as u8
            || self.tx_type() == TransactionType::Eip2930 as u8
        {
            return self.gas_price();
        }

        // for EIP-1559 tx and onwards gas_price represents maximum price.
        let max_price = self.gas_price();
        let Some(max_priority_fee) = self.max_priority_fee_per_gas() else {
            return max_price;
        };
        min(max_price, base_fee.saturating_add(max_priority_fee))
    }

Back to calculate_caller_fee.

The logic is fairly simple — subtracts Gas fees from the caller's Balance and ensures the remaining balance is greater than tx.value:

let gas_balance_spending = effective_balance_spending - tx.value();
let mut new_balance = balance.saturating_sub(gas_balance_spending);
if is_balance_check_disabled {
    new_balance = new_balance.max(tx.value());
}
Ok(new_balance)

Back to crates/handler/src/pre_execution.rs -> validate_against_state_and_deduct_caller:

if tx.kind().is_call() {
    caller.bump_nonce();
}

tx.kind has two variants:

Call — both transfers and contract calls fall under this category
Create — creating contracts bump_nonce increments the Caller's nonce by 1. Only the Call case is handled here. Both Create and Call are transactions initiated by the Caller, so normally both should nonce + 1. Create isn't handled here — it's deferred to the Execute stage, where nonce + 1 happens only after the contract is successfully created. Only on-chain transactions get nonce + 1. If contract creation fails during the constructor stage, it won't go on-chain.

2. load_accounts

Jump back to crates/handler/src/handler.rs -> pre_execution:

self.load_accounts(evm)?;

Jump directly to the implementation:

pub fn load_accounts<
    EVM: EvmTr<Precompiles: PrecompileProvider<EVM::Context>>,
    ERROR: From<<<EVM::Context as ContextTr>::Db as Database>::Error>,
>(
    evm: &mut EVM,
) -> Result<(), ERROR> {
    let (context, precompiles) = evm.ctx_precompiles();

    let gen_spec = context.cfg().spec();
    let spec = gen_spec.clone().into();
    // sets eth spec id in journal
    context.journal_mut().set_spec_id(spec);
    let precompiles_changed = precompiles.set_spec(gen_spec);
    let empty_warmed_precompiles = context.journal_mut().precompile_addresses().is_empty();

    if precompiles_changed || empty_warmed_precompiles {
        // load new precompile addresses into journal.
        // When precompiles addresses are changed we reset the warmed hashmap to those new addresses.
        context
            .journal_mut()
            .warm_precompiles(precompiles.warm_addresses().collect());
    }

    // Load coinbase
    // EIP-3651: Warm COINBASE. Starts the `COINBASE` address warm
    if spec.is_enabled_in(SpecId::SHANGHAI) {
        let coinbase = context.block().beneficiary();
        context.journal_mut().warm_coinbase_account(coinbase);
    }

    // Load access list
    let (tx, journal) = context.tx_journal_mut();
    // legacy is only tx type that does not have access list.
    if tx.tx_type() != TransactionType::Legacy {
        if let Some(access_list) = tx.access_list() {
            let mut map: HashMap<Address, HashSet<StorageKey>> = HashMap::default();
            for item in access_list {
                map.entry(*item.address())
                    .or_default()
                    .extend(item.storage_slots().map(|key| U256::from_be_bytes(key.0)));
            }
            journal.warm_access_list(map);
        }
    }

    Ok(())
}

Looks long, but the functionality is similar throughout.

Loading Precompiles addresses, Coinbase (miner) address, and the AccessList addresses mentioned in the previous article.

Let's look directly at the loading source code.

Except for Precompiles, the other two are simply set directly.

Precompiles initial addresses take this form:

0x0000000000000000000000000000000000000001
0x0000000000000000000000000000000000000002
0x0000000000000000000000000000000000000003 Short addresses only need the last two non-zero digits.

/// crates/context/src/journal/warm_addresses.rs
    #[inline]
    pub fn set_precompile_addresses(&mut self, addresses: HashSet<Address>) {
        self.precompile_short_addresses.fill(false);

        let mut all_short_addresses = true;
        for address in addresses.iter() {
            if let Some(short_address) = short_address(address) {
                self.precompile_short_addresses.set(short_address, true);
            } else {
                all_short_addresses = false;
            }
        }

        self.precompile_all_short_addresses = all_short_addresses;
        self.precompile_set = addresses;
    }

    /// Set the coinbase address.
    #[inline]
    pub fn set_coinbase(&mut self, address: Address) {
        self.coinbase = Some(address);
    }

    /// Set the access list.
    #[inline]
    pub fn set_access_list(&mut self, access_list: HashMap<Address, HashSet<StorageKey>>) {
        self.access_list = access_list;
    }

3. apply_eip7702_auth_list

Jump back to crates/handler/src/handler.rs -> pre_execution:

let gas = self.apply_eip7702_auth_list(evm)?;

This handles transactions of type EIP7702.

Non-EIP7702 types are skipped directly.

Before we begin, let's introduce EIP-7702.

Its core feature allows EOA accounts to execute complex logic like smart contracts.

The principle is using a private key signature to set the code field to a special bytecode pointing to a delegated address.

Subsequently, the EOA account can choose to make other contract calls through this delegated address.

The delegated account is called a smart contract account, and this delegation process is called account abstraction.

Let's jump directly to the function implementation.

This sets an EOA account as a smart contract account — it's not the Sender calling contracts through the delegated address.

One more point: the account abstraction account isn't necessarily issued by tx.caller (not distinguishing tx.origin here).

It can be signed by the account that wants to be abstracted and then broadcast by someone else.

// crates/handler/src/pre_execution.rs
#[inline]
pub fn apply_eip7702_auth_list<
    CTX: ContextTr,
    ERROR: From<InvalidTransaction> + From<<CTX::Db as Database>::Error>,
>(
    context: &mut CTX,
) -> Result<u64, ERROR> {
    let chain_id = context.cfg().chain_id();
    let (tx, journal) = context.tx_journal_mut();

    // Return if not EIP-7702 transaction.
    if tx.tx_type() != TransactionType::Eip7702 {
        return Ok(0);
    }
    apply_auth_list(chain_id, tx.authorization_list(), journal)
}

Continue jumping. The logic below has fairly clear comments, so instead of explaining one by one, comments are added directly in the code:

// crates/handler/src/pre_execution.rs
#[inline]
pub fn apply_auth_list<
    JOURNAL: JournalTr,
    ERROR: From<InvalidTransaction> + From<<JOURNAL::Database as Database>::Error>,
>(
    chain_id: u64,
    auth_list: impl Iterator<Item = impl AuthorizationTr>,
    journal: &mut JOURNAL,
) -> Result<u64, ERROR> {
    let mut refunded_accounts = 0;
    for authorization in auth_list {
        // 1. Verify the chain ID is 0 or the chain's current ID.
        let auth_chain_id = authorization.chain_id();
        if !auth_chain_id.is_zero() && auth_chain_id != U256::from(chain_id) {
            continue;
        }
        // 2. Verify the `nonce` is less than `2**64 - 1`.
        if authorization.nonce() == u64::MAX {
            continue;
        }

        // Recover authority and authorization address.
        // "authority" here refers to the address being abstracted.
        // Since it's not necessarily the tx's caller, it must be recovered from the signature.
        // 3. `authority = ecrecover(keccak(MAGIC || rlp([chain_id, address, nonce])), y_parity, r, s]`
        let Some(authority) = authorization.authority() else {
            continue;
        };
        // 4. Warm the authority and check the nonce.
        // load_account_with_code_mut was discussed in depth earlier — loads account info.
        let mut authority_acc = journal.load_account_with_code_mut(authority)?;
        let authority_acc_info = &authority_acc.account().info;
        // 5. Verify that `authority`'s code is empty or already delegated.
        if let Some(bytecode) = &authority_acc_info.code {
            // if it is not empty and it is not eip7702
            if !bytecode.is_empty() && !bytecode.is_eip7702() {
                continue;
            }
        }
        // 6. Verify that `authority`'s nonce equals `nonce`. If `authority` doesn't exist in the trie, verify `nonce` equals `0`.
        // authorization.nonce here is the original EOA account's nonce for authority.
        // If sender and authority are the same, sender's nonce is authority's nonce.
        if authorization.nonce() != authority_acc_info.nonce {
            continue;
        }

        // 7. If `authority` exists in the trie, add `PER_EMPTY_ACCOUNT_COST - PER_AUTH_BASE_COST` gas to the global refund counter.
        // This calculates refunds. EIP-7702 specifies that if authority is not an empty account, partial auth refund is returned.
        // Auth fee calculation is in crates/interpreter/src/gas/calc.rs
        // -> calculate_initial_tx_gas, covered in the previous article.
        if !(authority_acc_info.is_empty()
            && authority_acc
                .account()
                .is_loaded_as_not_existing_not_touched())
        {
            refunded_accounts += 1;
        }

        // 8. Set `authority`'s code to `0xef0100 || address`. This is a delegation designation.
        // * As a special case, if `address` is `0x000000000000000000000000000000000000000000`, no designation is written.
        // Clear the account code and reset the account code hash to the empty hash `0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470`.
        // 9. Increment `authority`'s nonce by 1.
        authority_acc.delegate(authorization.address());
    }

    let refunded_gas =
        refunded_accounts * (eip7702::PER_EMPTY_ACCOUNT_COST - eip7702::PER_AUTH_BASE_COST);

    Ok(refunded_gas)
}

REVM Source Code - Execution Flow Part 2

TangHaosuan — Fri, 03 Apr 2026 13:48:34 +0000

Validate

The previous article mentioned that the handler has five major steps. Validate is step one.

In this article, we'll analyze it in detail and understand what it's responsible for.

// crates/handler/src/handler.rs
 #[inline]
    fn validate(&self, evm: &mut Self::Evm) -> Result<InitialAndFloorGas, Self::Error> {
        self.validate_env(evm)?;
        self.validate_initial_tx_gas(evm)
    }

From the function and internal function call names, we can see that Validate is mainly responsible for two parts:

validate_env: Validate the environment.

validate_initial_tx_gas: Validate the initial gas for the transaction.

validate_env

Let's first analyze validate_env — jump in:

// crates/handler/src/handler.rs
#[inline]
    fn validate_env(&self, evm: &mut Self::Evm) -> Result<(), Self::Error> {
        validation::validate_env(evm.ctx())
    }

Nothing useful — just a function call. Continue jumping:

// crates/handler/src/validation.rs
pub fn validate_env<CTX: ContextTr, ERROR: From<InvalidHeader> + From<InvalidTransaction>>(
    context: CTX,
) -> Result<(), ERROR> {
    let spec = context.cfg().spec().into();
    // `prevrandao` is required for the merge
    if spec.is_enabled_in(SpecId::MERGE) && context.block().prevrandao().is_none() {
        return Err(InvalidHeader::PrevrandaoNotSet.into());
    }
    // `excess_blob_gas` is required for Cancun
    if spec.is_enabled_in(SpecId::CANCUN) && context.block().blob_excess_gas_and_price().is_none() {
        return Err(InvalidHeader::ExcessBlobGasNotSet.into());
    }
    validate_tx_env::<CTX>(context, spec).map_err(Into::into)
}

let spec = context.cfg().spec().into()

Gets the spec from the current context, which can be understood as the current EVM version. Returns an enum type.

is_enabled_in()

Compares the current spec with the passed-in spec. Returns true if the current spec is greater than or equal to the passed-in spec.

context.block().prevrandao().is_none()

Checks whether prevrandao is set in the context.

context.block().blob_excess_gas_and_price().is_none()

Checks whether blob_excess_gas_and_price is set in the context.

We can see this section mainly checks: if a specific EVM version is set in the context, whether the features and upgrades of that version are implemented.

Moving on to this line — from the function name, it checks the tx environment:

validate_tx_env::<CTX>(context, spec).map_err(Into::into)

Let's jump directly to the function implementation:

// crates/handler/src/validation.rs
pub fn validate_tx_env<CTX: ContextTr>(
    context: CTX,
    spec_id: SpecId,
) -> Result<(), InvalidTransaction> {
    // Check if the transaction's chain id is correct
    let tx_type = context.tx().tx_type();
    let tx = context.tx();

    let base_fee = if context.cfg().is_base_fee_check_disabled() {
        None
    } else {
        Some(context.block().basefee() as u128)
    };

    let tx_type = TransactionType::from(tx_type);

    // Check chain_id if config is enabled.
    // EIP-155: Simple replay attack protection
    if context.cfg().tx_chain_id_check() {
        if let Some(chain_id) = tx.chain_id() {
            if chain_id != context.cfg().chain_id() {
                return Err(InvalidTransaction::InvalidChainId);
            }
        } else if !tx_type.is_legacy() && !tx_type.is_custom() {
            // Legacy transaction are the only one that can omit chain_id.
            return Err(InvalidTransaction::MissingChainId);
        }
    }

    // EIP-7825: Transaction Gas Limit Cap
    let cap = context.cfg().tx_gas_limit_cap();
    if tx.gas_limit() > cap {
        return Err(InvalidTransaction::TxGasLimitGreaterThanCap {
            gas_limit: tx.gas_limit(),
            cap,
        });
    }

    let disable_priority_fee_check = context.cfg().is_priority_fee_check_disabled();

    match tx_type {
        TransactionType::Legacy => {
            validate_legacy_gas_price(tx.gas_price(), base_fee)?;
        }
        TransactionType::Eip2930 => {
            // Enabled in BERLIN hardfork
            if !spec_id.is_enabled_in(SpecId::BERLIN) {
                return Err(InvalidTransaction::Eip2930NotSupported);
            }
            validate_legacy_gas_price(tx.gas_price(), base_fee)?;
        }
        TransactionType::Eip1559 => {
            if !spec_id.is_enabled_in(SpecId::LONDON) {
                return Err(InvalidTransaction::Eip1559NotSupported);
            }
            validate_priority_fee_for_tx(tx, base_fee, disable_priority_fee_check)?;
        }
        TransactionType::Eip4844 => {
            if !spec_id.is_enabled_in(SpecId::CANCUN) {
                return Err(InvalidTransaction::Eip4844NotSupported);
            }

            validate_priority_fee_for_tx(tx, base_fee, disable_priority_fee_check)?;

            validate_eip4844_tx(
                tx.blob_versioned_hashes(),
                tx.max_fee_per_blob_gas(),
                context.block().blob_gasprice().unwrap_or_default(),
                context.cfg().max_blobs_per_tx(),
            )?;
        }
        TransactionType::Eip7702 => {
            // Check if EIP-7702 transaction is enabled.
            if !spec_id.is_enabled_in(SpecId::PRAGUE) {
                return Err(InvalidTransaction::Eip7702NotSupported);
            }

            validate_priority_fee_for_tx(tx, base_fee, disable_priority_fee_check)?;

            let auth_list_len = tx.authorization_list_len();
            // The transaction is considered invalid if the length of authorization_list is zero.
            if auth_list_len == 0 {
                return Err(InvalidTransaction::EmptyAuthorizationList);
            }
        }
        TransactionType::Custom => {
            // Custom transaction type check is not done here.
        }
    };

    // Check if gas_limit is more than block_gas_limit
    if !context.cfg().is_block_gas_limit_disabled() && tx.gas_limit() > context.block().gas_limit()
    {
        return Err(InvalidTransaction::CallerGasLimitMoreThanBlock);
    }

    // EIP-3860: Limit and meter initcode. Still valid with EIP-7907 and increase of initcode size.
    if spec_id.is_enabled_in(SpecId::SHANGHAI)
        && tx.kind().is_create()
        && context.tx().input().len() > context.cfg().max_initcode_size()
    {
        return Err(InvalidTransaction::CreateInitCodeSizeLimit);
    }

    Ok(())
}

It looks long, but it's really just various checks. Let's break it down section by section:

// crates/handler/src/validation.rs
    // Check chain_id if config is enabled.
    // EIP-155: Simple replay attack protection
    if context.cfg().tx_chain_id_check() {
        if let Some(chain_id) = tx.chain_id() {
            if chain_id != context.cfg().chain_id() {
                return Err(InvalidTransaction::InvalidChainId);
            }
        } else if !tx_type.is_legacy() && !tx_type.is_custom() {
            // Legacy transaction are the only one that can omit chain_id.
            return Err(InvalidTransaction::MissingChainId);
        }
    }

Checks whether tx_chain_id_check is enabled in the Context.

If tx_chain_id_check is enabled, it checks whether the current tx's chain_id matches the context's.

The chain_id verification is to prevent replay attacks.

Without a chain_id, a successful transaction you sent on ETH could be replayed by others on another EVM chain, causing you to lose assets on other chains. (For example, if you have 10 tokens on both BSC and ETH, and you only sent 1 ETH to A on ETH. Someone else could take your raw Transaction from ETH and broadcast it on BSC, causing you to also send 1 BNB to A on BSC.)

// EIP-7825: Transaction Gas Limit Cap
    let cap = context.cfg().tx_gas_limit_cap();
    if tx.gas_limit() > cap {
        return Err(InvalidTransaction::TxGasLimitGreaterThanCap {
            gas_limit: tx.gas_limit(),
            cap,
        });
    }

Checks whether the current tx's GasLimit exceeds the value set in Context.

EIP-7825 is primarily to prevent attacks.

Without a limit, a single tx could bloat the block, reducing the number of transactions that can be packaged. This would cause network congestion.

The higher the GasLimit, the more complex the logic, and during processing CPU/memory can explode, slowing down node synchronization too.

match tx_type {
        TransactionType::Legacy => {
            validate_legacy_gas_price(tx.gas_price(), base_fee)?;
        }
        TransactionType::Eip2930 => {
            // Enabled in BERLIN hardfork
            if !spec_id.is_enabled_in(SpecId::BERLIN) {
                return Err(InvalidTransaction::Eip2930NotSupported);
            }
            validate_legacy_gas_price(tx.gas_price(), base_fee)?;
        }
        TransactionType::Eip1559 => {
            if !spec_id.is_enabled_in(SpecId::LONDON) {
                return Err(InvalidTransaction::Eip1559NotSupported);
            }
            validate_priority_fee_for_tx(tx, base_fee, disable_priority_fee_check)?;
        }
        TransactionType::Eip4844 => {
            if !spec_id.is_enabled_in(SpecId::CANCUN) {
                return Err(InvalidTransaction::Eip4844NotSupported);
            }

            validate_priority_fee_for_tx(tx, base_fee, disable_priority_fee_check)?;

            validate_eip4844_tx(
                tx.blob_versioned_hashes(),
                tx.max_fee_per_blob_gas(),
                context.block().blob_gasprice().unwrap_or_default(),
                context.cfg().max_blobs_per_tx(),
            )?;
        }
        TransactionType::Eip7702 => {
            // Check if EIP-7702 transaction is enabled.
            if !spec_id.is_enabled_in(SpecId::PRAGUE) {
                return Err(InvalidTransaction::Eip7702NotSupported);
            }

            validate_priority_fee_for_tx(tx, base_fee, disable_priority_fee_check)?;

            let auth_list_len = tx.authorization_list_len();
            // The transaction is considered invalid if the length of authorization_list is zero.
            if auth_list_len == 0 {
                return Err(InvalidTransaction::EmptyAuthorizationList);
            }
        }
        TransactionType::Custom => {
            // Custom transaction type check is not done here.
        }

Before we start, let's explain EIP-1559. After EIP-1559, GasPrice is influenced by 3 components:

Max Fee: The maximum GasPrice the Sender is willing to pay
Priority Fee: Miner tip, used to speed up transactions
Base Fee: The block's base fee, which gets burned
GasPrice = Priority Fee + min(Base Fee, Max Fee - Base Fee)

Back to the code — this section looks long, but if you look closely,

except for Eip4844 and Eip7702, each check mainly does two things:

Checks whether the current EVM version supports the transaction type
Checks whether the GasPrice settings are correct
- validate_legacy_gas_price
  - Ensures the tx's GasPrice is greater than the Base_Fee set in Context
- validate_priority_fee_for_tx
  - Actually calls validate_priority_fee_tx; specifics are in the code

pub fn validate_priority_fee_tx(
    max_fee: u128,
    max_priority_fee: u128,
    base_fee: Option<u128>,
    disable_priority_fee_check: bool,
) -> Result<(), InvalidTransaction> {
    // Ensures max_priority_fee doesn't exceed max_fee
    if !disable_priority_fee_check && max_priority_fee > max_fee {
        return Err(InvalidTransaction::PriorityFeeGreaterThanMaxFee);
    }
    // This is the formula above — ensures Base fee + Max Priority Fee doesn't exceed Max Fee
    if let Some(base_fee) = base_fee {
        let effective_gas_price = cmp::min(max_fee, base_fee.saturating_add(max_priority_fee));
        if effective_gas_price < base_fee {
            return Err(InvalidTransaction::GasPriceLessThanBasefee);
        }
    }

    Ok(())
}

EIP-4844 tx handling — EIP-4844 mainly targets L2, skipping
EIP-7702 tx handling — validates whether there's an authorization_list

validate_initial_tx_gas

According to the code comments, validate_initial_tx_gas is responsible for:

Calculating the initial gas fee based on the transaction type and input data
Including additional costs for access lists and authorization lists
Verifying that the initial cost doesn't exceed the transaction gas limit

Let's continue with the code:

// crates/handler/src/handler.rs
 #[inline]
    fn validate_initial_tx_gas(
        &self,
        evm: &mut Self::Evm,
    ) -> Result<InitialAndFloorGas, Self::Error> {
        let ctx = evm.ctx_ref();
        validation::validate_initial_tx_gas(
            ctx.tx(),
            ctx.cfg().spec().into(),
            ctx.cfg().is_eip7623_disabled(),
        )
        .map_err(From::from)
    }

The main call is to validation::validate_initial_tx_gas. Let's jump in:

// crates/handler/src/validation.rs
pub fn validate_initial_tx_gas(
    tx: impl Transaction,
    spec: SpecId,
    is_eip7623_disabled: bool,
) -> Result<InitialAndFloorGas, InvalidTransaction> {
    let mut gas = gas::calculate_initial_tx_gas_for_tx(&tx, spec);

    if is_eip7623_disabled {
        gas.floor_gas = 0
    }

    // Additional check to see if limit is big enough to cover initial gas.
    if gas.initial_gas > tx.gas_limit() {
        return Err(InvalidTransaction::CallGasCostMoreThanGasLimit {
            gas_limit: tx.gas_limit(),
            initial_gas: gas.initial_gas,
        });
    }

    // EIP-7623: Increase calldata cost
    // floor gas should be less than gas limit.
    if spec.is_enabled_in(SpecId::PRAGUE) && gas.floor_gas > tx.gas_limit() {
        return Err(InvalidTransaction::GasFloorMoreThanGasLimit {
            gas_floor: gas.floor_gas,
            gas_limit: tx.gas_limit(),
        });
    };

    Ok(gas)
}

Let's analyze step by step. First, focus on the first line — from the name it calculates the tx's initial gas:

let mut gas = gas::calculate_initial_tx_gas_for_tx(&tx, spec);

Jump in to see the implementation:

pub fn calculate_initial_tx_gas_for_tx(tx: impl Transaction, spec: SpecId) -> InitialAndFloorGas {
    let mut accounts = 0;
    let mut storages = 0;
    // legacy is only tx type that does not have access list.
    if tx.tx_type() != TransactionType::Legacy {
        (accounts, storages) = tx
            .access_list()
            .map(|al| {
                al.fold((0, 0), |(mut num_accounts, mut num_storage_slots), item| {
                    num_accounts += 1;
                    num_storage_slots += item.storage_slots().count();

                    (num_accounts, num_storage_slots)
                })
            })
            .unwrap_or_default();
    }

    calculate_initial_tx_gas(
        spec,
        tx.input(),
        tx.kind().is_create(),
        accounts as u64,
        storages as u64,
        tx.authorization_list_len() as u64,
    )
}

The first big section handles the access_list.

access_list: When sending a tx, you can pre-declare the list of addresses and storage keys that the tx will read or write during execution.

Addresses and storage keys declared in the tx are pre-loaded and warmed, which can reduce Gas consumption.

The first section looks uncomfortable to read, so let's break it down step by step.

First, let's look at the access_list return type — it returns

Option>>

fn access_list(&self) -> Option<impl Iterator<Item = Self::AccessListItem<'_>>>

// access_list is an Option — nothing happens for None, for Some the closure function inside map is executed
tx.access_list().map()

// fold performs an accumulation over the iterator's elements
// (0, 0) initial value
// (mut num_accounts, mut num_storage_slots) temp variables for storing results during accumulation
// item — the iterator's element
|al| {al.fold((0, 0), |(mut num_accounts, mut num_storage_slots), item| {
    num_accounts += 1;
    num_storage_slots += item.storage_slots().count();
    (num_accounts, num_storage_slots)
}) }

Combined: if the access_list is not empty, it accumulates the accounts and storage_slots in the access_list, calculating the actual number of accounts and storage_slots.

Next, look at the calculate_initial_tx_gas part — jump to the implementation:

// crates/interpreter/src/gas/calc.rs
pub fn calculate_initial_tx_gas(
    spec_id: SpecId,
    input: &[u8],
    is_create: bool,
    access_list_accounts: u64,
    access_list_storages: u64,
    authorization_list_num: u64,
) -> InitialAndFloorGas {
    let mut gas = InitialAndFloorGas::default();

    // Initdate stipend
    let tokens_in_calldata = get_tokens_in_calldata(input, spec_id.is_enabled_in(SpecId::ISTANBUL));

    gas.initial_gas += tokens_in_calldata * STANDARD_TOKEN_COST;

    // Get number of access list account and storages.
    gas.initial_gas += access_list_accounts * ACCESS_LIST_ADDRESS;
    gas.initial_gas += access_list_storages * ACCESS_LIST_STORAGE_KEY;

    // Base stipend
    gas.initial_gas += if is_create {
        if spec_id.is_enabled_in(SpecId::HOMESTEAD) {
            // EIP-2: Homestead Hard-fork Changes
            53000
        } else {
            21000
        }
    } else {
        21000
    };

    // EIP-3860: Limit and meter initcode
    // Init code stipend for bytecode analysis
    if spec_id.is_enabled_in(SpecId::SHANGHAI) && is_create {
        gas.initial_gas += initcode_cost(input.len())
    }

    // EIP-7702
    if spec_id.is_enabled_in(SpecId::PRAGUE) {
        gas.initial_gas += authorization_list_num * eip7702::PER_EMPTY_ACCOUNT_COST;

        // Calculate gas floor for EIP-7623
        gas.floor_gas = calc_tx_floor_cost(tokens_in_calldata);
    }

    gas
}

Continue jumping to the get_tokens_in_calldata implementation:

#[inline]
pub fn get_tokens_in_calldata(input: &[u8], is_istanbul: bool) -> u64 {
    let zero_data_len = input.iter().filter(|v| **v == 0).count() as u64;
    let non_zero_data_len = input.len() as u64 - zero_data_len;
    let non_zero_data_multiplier = if is_istanbul {
        // EIP-2028: Transaction data gas cost reduction
        NON_ZERO_BYTE_MULTIPLIER_ISTANBUL
    } else {
        NON_ZERO_BYTE_MULTIPLIER
    };
    zero_data_len + non_zero_data_len * non_zero_data_multiplier
}

The logic is simple — it finds the count of zero and non-zero bytes in the tx's calldata, multiplying the non-zero count by a fixed value.

This is done because calldata is permanently stored on-chain. Data with many zero bytes can be efficiently compressed for storage with low cost, while non-zero data is harder to compress and costs more to store.

The remaining logic in calculate_initial_tx_gas is fairly obvious, so we won't go into detail.

Jumping back to validate_initial_tx_gas, the remaining logic is also fairly obvious, so we won't continue either.

The validate stage ends here.

REVM Source Code - Execution Flow Part 1

TangHaosuan — Fri, 03 Apr 2026 13:47:42 +0000

Preface

After a few years of crypto trading — winning some, losing some — it became increasingly exhausting, but I didn't want to leave the crypto space.

After much thought, I decided to look at the RETH source code.

REVM, as the most important module of RETH, understanding it would be a major accomplishment.

I hadn't learned Rust before — I'd read tutorials but never used it in a real project. I decided to learn while reading, using AI for Q&A.

REVM Official Repository

Directory Structure

Main directories to focus on:

book
- REVM documentation
crates
- Where the actual source code lives
examples
- Examples

Getting Started

The best way to learn a project is to start from the examples.

Here we'll start with the examples/erc20_gas project.

Open the project's src.

// examples/erc20_gas/src/main.rs
let rpc_url = "https://mainnet.infura.io/v3/c60b0bb42f8a4c6481ecd229eddaca27";
let provider = ProviderBuilder::new().connect(rpc_url).await?.erased();
let alloy_db = WrapDatabaseAsync::new(AlloyDB::new(provider, BlockId::latest())).unwrap();
let mut cache_db = CacheDB::new(alloy_db);

The first two lines are easy to understand — creating a provider to fetch on-chain data.

The next two lines involve 3 new concepts:

AlloyDB: Lets the EVM fetch on-chain data directly via RPC on demand
WrapDatabaseAsync: Converts AlloyDB from Async to Sync
CacheDB: Acts as a middle layer, caching read data and staging write modifications

In other words, CacheDB is created to cache data read from the chain. When the EVM needs it, data is read directly from CacheDB rather than fetching from the chain again.

These three classes are mainly used for forking mainnet for transaction simulation and testing, so we won't dive into their implementation.

The code after the above is just configuration, so let's jump directly to the transfer function implementation.

fn transfer(from: Address, to: Address, amount: U256, cache_db: &mut AlloyCacheDB) -> Result<()> {
    let mut ctx = Context::mainnet()
        .with_db(cache_db)
        .modify_cfg_chained(|cfg| {
            cfg.spec = SpecId::CANCUN;
        })
        .with_tx(
            TxEnv::builder()
                .caller(from)
                .kind(TxKind::Call(to))
                .value(amount)
                .gas_price(2)
                .build()
                .unwrap(),
        )
        .modify_block_chained(|b| {
            b.basefee = 1;
        })
        .build_mainnet();

    transact_erc20evm_commit(&mut ctx).unwrap();

    Ok(())
}

Context::mainnet() creates a mainnet context (Context).

Context is a very important concept that permeates the entire EVM.

Understanding Context's functionality will make reading the subsequent source code much easier.

Let's jump to the Context::mainnet implementation.

//crates/handler/src/mainnet_builder.rs
impl MainContext for Context<BlockEnv, TxEnv, CfgEnv, EmptyDB, Journal<EmptyDB>, ()> {
    fn mainnet() -> Self {
        Context::new(EmptyDB::new(), SpecId::default())
    }
}

Nothing useful here — just uses a MainContext Trait.

Let's continue jumping deeper:

// crates/context/src/context.rs
impl<
        BLOCK: Block + Default,
        TX: Transaction + Default,
        DB: Database,
        JOURNAL: JournalTr<Database = DB>,
        CHAIN: Default,
        LOCAL: LocalContextTr + Default,
        SPEC: Default + Copy + Into<SpecId>,
    > Context<BLOCK, TX, CfgEnv<SPEC>, DB, JOURNAL, CHAIN, LOCAL>
{
    /// Creates a new context with a new database type.
    ///
    /// This will create a new [`Journal`] object.
    pub fn new(db: DB, spec: SPEC) -> Self {
        let mut journaled_state = JOURNAL::new(db);
        journaled_state.set_spec_id(spec.into());
        Self {
            tx: TX::default(),
            block: BLOCK::default(),
            cfg: CfgEnv {
                spec,
                ..Default::default()
            },
            local: LOCAL::default(),
            journaled_state,
            chain: Default::default(),
            error: Ok(()),
        }
    }
}

A new Context is created, configured, and returned. Context contains the following:

tx — creates a new Transaction (each Transaction creates a new EVM, so one EVM only has one tx)
block — the block
cfg
- chain_id — chain ID
- tx_chain_id_check — whether to check chain_id (Transactions carry a chain_id; this checks if the Transaction's chain_id matches the current EVM's chain_id)
- spec — current EVM version
- limit_contract_code_size — contract code size limit
- limit_contract_initcode_size — contract initialization code size limit
- disable_nonce_check — whether to check nonce (each transaction carries the sender's nonce, equal to the number of sent transactions)
- max_blobs_per_tx — used by L2
- blob_base_fee_update_fraction — used by L2
- tx_gas_limit_cap — Transaction Gas upper limit
- memory_limit — maximum memory limit used by EVM
- disable_balance_check
- disable_block_gas_limit
- disable_eip3541
- disable_eip3607
- disable_eip7623
- disable_base_fee
- disable_priority_fee_check
- disable_fee_charge
local — LocalContext, a local temporary context that gets gradually populated by the interpreter/execution logic during EVM execution
journaled_state — Journaled state (tracks account modifications, logs, reverts, etc.)
chain — placeholder, currently unused

From the fields, we can see that Context contains the data and state needed for EVM transaction execution.

After reviewing Context, let's return to main.rs:

//***examples/erc20_gas/src/main.rs***
 .with_db(cache_db)
        .modify_cfg_chained(|cfg| {
            cfg.spec = SpecId::CANCUN;
        })
        .with_tx(
            TxEnv::builder()
                .caller(from)
                .kind(TxKind::Call(to))
                .value(amount)
                .gas_price(2)
                .build()
                .unwrap(),
        )
        .modify_block_chained(|b| {
            b.basefee = 1;
        })
        .build_mainnet();

Nothing special in the earlier part — just setting the chain version, current tx, and block's basefee.

Let's go directly to build_mainnet and jump in:

//crates/handler/src/mainnet_builder.rs
fn build_mainnet(self) -> MainnetEvm<Self::Context> {
        Evm {
            ctx: self,
            inspector: (),
            instruction: EthInstructions::default(),
            precompiles: EthPrecompiles::default(),
            frame_stack: FrameStack::new_prealloc(8),
        }
    }

It directly creates an Evm object. Let me explain the other fields here.

inspector: Think of it as a monitor (hook), mainly used for debugging. You can hook before/after opcode execution to inspect memory, stack, and gas consumption at that point.

precompiles: Collection of precompiled contracts (sha256, ecrecover, etc.)

instruction: Instruction table. Stores the gas cost for each opcode and the corresponding function for each opcode.

frame_stack: Call stack — a frame is created for each cross-contract call, used for inter-contract calls.

Many new concepts are introduced here. These concepts are important components of the EVM. Remember their roles — it will make understanding the EVM flow much easier later.

Let's return to the Transfer function in examples/erc20_gas/src/main.rs:

transact_erc20evm_commit(&mut ctx).unwrap();

Jump in — just one function call. The key is transact_erc20evm:

pub fn transact_erc20evm_commit<EVM>(
    evm: &mut EVM,
) -> Result<ExecutionResult<HaltReason>, Erc20Error<EVM::Context>>
where
    EVM: EvmTr<
        Context: ContextTr<Journal: JournalTr<State = EvmState>, Db: DatabaseCommit>,
        Precompiles: PrecompileProvider<EVM::Context, Output = InterpreterResult>,
        Instructions: InstructionProvider<
            Context = EVM::Context,
            InterpreterTypes = EthInterpreter,
        >,
        Frame = EthFrame<EthInterpreter>,
    >,
{
    transact_erc20evm(evm).map(|(result, state)| {
        evm.ctx().db_mut().commit(state);
        result
    })
}

Let's continue jumping to transact_erc20evm:

pub fn transact_erc20evm<EVM>(
    evm: &mut EVM,
) -> Result<(ExecutionResult<HaltReason>, EvmState), Erc20Error<EVM::Context>>
where
    EVM: EvmTr<
        Context: ContextTr<Journal: JournalTr<State = EvmState>>,
        Precompiles: PrecompileProvider<EVM::Context, Output = InterpreterResult>,
        Instructions: InstructionProvider<
            Context = EVM::Context,
            InterpreterTypes = EthInterpreter,
        >,
        Frame = EthFrame<EthInterpreter>,
    >,
{
    Erc20MainnetHandler::new().run(evm).map(|r| {
        let state = evm.ctx().journal_mut().finalize();
        (r, state)
    })
}

For now, just focus on Erc20MainnetHandler::new().run(evm).

The first part just creates an Erc20MainnetHandler, but that's not our focus today.

Although we're approaching from erc20_gas, it's only to find an entry point. Let's jump directly to run:

// crates/handler/src/handler.rs
 #[inline]
    fn run(
        &mut self,
        evm: &mut Self::Evm,
    ) -> Result<ExecutionResult<Self::HaltReason>, Self::Error> {
        self.configure(evm);
        // 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),
        }
    }

Again just one function call — let's continue:

// crates/handler/src/handler.rs
#[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)?;
        let eip7702_refund = self.pre_execution(evm)? as i64;
        let mut exec_result = self.execution(evm, &init_and_floor_gas)?;
        self.post_execution(evm, &mut exec_result, init_and_floor_gas, eip7702_refund)?;

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

And here we arrive at today's focus: run_without_catch_error.

run_without_catch_error is an important function in the handler, used to execute the complete EVM flow.

Handler

Just like at the very beginning, main.rs is the project's entry point.

Handler is the entry point for the entire EVM.

Core purpose: Defines and organizes the various stages of EVM execution flow (such as transaction validation, Gas consumption, instruction execution, Log and Selfdestruct handling, etc.), and allows users to insert custom logic (Hooks) at these stages.

run_without_catch_error is where REVM's five major stages execute:

Validation: Ensures the transaction complies with protocol rules and locks fees before execution.
pre_execution: Prepares for specific protocols (like EIP-7702) or custom logic.
execution: Executes contract logic, completing all state modifications and log recording.
post_execution: Based on execution results, completes final Gas settlement and all state cleanup work.
execution_result: Provides a standardized transaction execution result containing all final data.

This is a rather rough overview, because conceptual content is hard to remember from just reading. We'll cover it in detail in the dedicated handler articles later.