Trait BlockExecutorFactory

pub trait BlockExecutorFactory: 'static {
    type EvmFactory: EvmFactory;
    type ExecutionCtx<'a>: Clone;
    type Transaction;
    type Receipt;

    // Required methods
    fn evm_factory(&self) -> &Self::EvmFactory;
    fn create_executor<'a, DB, I>(
        &'a self,
        evm: <Self::EvmFactory as EvmFactory>::Evm<&'a mut State<DB>, I>,
        ctx: Self::ExecutionCtx<'a>,
    ) -> impl BlockExecutorFor<'a, Self, DB, I>
       where DB: Database + 'a,
             I: Inspector<<Self::EvmFactory as EvmFactory>::Context<&'a mut State<DB>>> + 'a;
}

Available on crate feature evm only.

Expand description

A factory that can create BlockExecutors.

This trait serves as the main entry point for block execution, providing a way to construct BlockExecutor instances with the necessary context. It separates the concerns of:

EVM configuration (handled by EvmFactory)
Block-specific execution context (provided via ExecutionCtx)

It allows for:

Reusable EVM configuration across multiple block executions
Separation of EVM-related state from block execution state
Flexible instantiation of executors with different contexts

§Relationship with EvmFactory

Every block executor factory contains an EvmFactory instance which handles:

EVM configuration and instantiation
Transaction environment setup
State database management

The block executor factory extends this by adding block-level execution concerns.

For more context on the executor design, see the documentation for BlockExecutor.

Required Associated Types§

type ExecutionCtx<'a>: Clone

Context required for block execution beyond what the EVM provides (e.g. EvmEnv)

While the EVM contains transaction-level context (gas limits, caller, value) and block-level context (block number, timestamp, base fee), the ExecutionCtx provides additional block execution context that is specific to your consensus implementation.

§Purpose

This type provides data needed for system calls that occur outside normal transaction execution. Block execution requires additional context for:

Pre-execution system calls: Setting up block hash history, beacon block roots
Post-execution system calls: Applying block rewards, validator withdrawals
Consensus-specific data: Uncle/ommer blocks, L2 data availability info
Protocol parameters: Fork-specific rules, precompile configurations
Precompile metadata: Context for precompiles that require block-level data (e.g. parameters stored in the block body)

For example, in Ethereum: EthBlockExecutionCtx contains:

Parent block hash for EIP-2935 block hash system call
Parent beacon block root for EIP-4788 beacon root system call
Uncle blocks for handling uncle rewards
Withdrawals for EIP-4895 validator withdrawals

§Design Considerations

Must be Clone to support creating multiple executors, can use Cow borrowed from the block.
Should be lightweight (use references where possible)
Contains only block-level data, not transaction-specific data

type Transaction

Transaction type used by the executor, see BlockExecutor::Transaction.

This should be the same consensus transaction type that the block executor operates on. It represents the transaction format from your consensus layer that needs to be executed by the EVM.

type Receipt

Receipt type produced by the executor, see BlockExecutor::Receipt.

Required Methods§

fn evm_factory(&self) -> &Self::EvmFactory

Reference to EVM factory used by the executor.

fn create_executor<'a, DB, I>( &'a self, evm: <Self::EvmFactory as EvmFactory>::Evm<&'a mut State<DB>, I>, ctx: Self::ExecutionCtx<'a>, ) -> impl BlockExecutorFor<'a, Self, DB, I>
where DB: Database + 'a, I: Inspector<<Self::EvmFactory as EvmFactory>::Context<&'a mut State<DB>>> + 'a,

Creates an executor with given EVM and execution context.

This method combines:

An EVM instance (already configured with block environment and state)
The execution context (containing additional data for system calls)

To create a BlockExecutor that can:

Apply pre-execution system calls (e.g., EIP-2935 blockhashes, EIP-4788 beacon roots)
Execute transactions
Apply post-execution system calls (e.g., withdrawals, rewards)

§Parameters

evm: A configured EVM instance with block environment and state
ctx: The execution context containing consensus-specific data needed for system calls

§Example

// Create EVM with block environment
let evm = factory.evm_factory().create_evm(block_env, state_db, inspector);

// Create execution context with consensus-specific data required for block execution
let ctx = EthBlockExecutionCtx {
    parent_hash: parent_block.hash(),
    parent_beacon_block_root: parent_block.parent_beacon_block_root,
    ommers: &uncle_blocks,
    withdrawals: Some(Cow::Borrowed(&withdrawals)),
};

// Create executor - it will use ctx for system calls
let mut executor = factory.create_executor(evm, ctx);

// The executor will:
// 1. Apply pre-execution changes
// 2. Execute all transactions
// 3. Apply post-execution changes (e.g., process withdrawals, apply rewards)
let result = executor.execute_block(transactions)?;