arb_evm/

evm.rs

use core::fmt::Debug;

use alloy_evm::{
    Database, Evm, EvmEnv, EvmFactory, eth::EthEvmContext, precompiles::PrecompilesMap,
};
use alloy_primitives::{Address, B256, Bytes, U256};
use arb_precompiles::register_arb_precompiles;
use arb_stylus::{
    StylusEvmApi, config::StylusConfig, ink::Gas as StylusGas, meter::MeteredMachine,
    run::RunProgram,
};
use arbos::programs::types::EvmData;
use revm::{
    ExecuteEvm, InspectEvm, Inspector, SystemCallEvm,
    context::{
        ContextSetters, Evm as RevmEvm, FrameStack,
        result::{EVMError, ExecutionResult, InvalidTransaction},
    },
    context_interface::{
        ContextTr, JournalTr,
        host::LoadError,
        result::{HaltReason, ResultAndState},
    },
    handler::{
        EthFrame, EvmTr, FrameResult, Handler, ItemOrResult, MainnetHandler, PrecompileProvider,
        instructions::EthInstructions,
    },
    inspector::{InspectorHandler, NoOpInspector},
    interpreter::{
        CallInput, CallInputs, CallOutcome, CallScheme, FrameInput, Gas as EvmGas, Host,
        InstructionContext, InstructionResult, InterpreterResult, InterpreterTypes,
        interpreter::EthInterpreter,
        interpreter_action::FrameInit,
        interpreter_types::{InputsTr, ReturnData, RuntimeFlag, StackTr},
    },
    primitives::hardfork::SpecId,
};

use crate::transaction::ArbTransaction;

/// BLOBBASEFEE opcode (0x4a).
const BLOBBASEFEE_OPCODE: u8 = 0x4a;

/// SELFDESTRUCT opcode (0xff).
const SELFDESTRUCT_OPCODE: u8 = 0xff;

/// NUMBER opcode (0x43).
const NUMBER_OPCODE: u8 = 0x43;

/// BLOCKHASH opcode (0x40).
const BLOCKHASH_OPCODE: u8 = 0x40;

/// BALANCE opcode (0x31).
const BALANCE_OPCODE: u8 = 0x31;

/// Arbitrum NUMBER: returns the L1 block number recorded during StartBlock.
///
/// `block_env.number` is configured to hold the L1 block number for Arbitrum
/// EVM execution; reading the host preserves consensus semantics without
/// touching any per-thread global.
fn arb_number<WIRE: InterpreterTypes, H: Host + ?Sized>(ctx: InstructionContext<'_, H, WIRE>) {
    let l1_block = ctx.host.block_number();
    if !ctx.interpreter.stack.push(l1_block) {
        ctx.interpreter.halt(InstructionResult::StackOverflow);
    }
}

/// Arbitrum BLOCKHASH: uses L1 block number for range check.
///
/// Standard BLOCKHASH compares the requested block number against block_env.number,
/// which is the L2 block number. Since Arbitrum's NUMBER opcode returns the L1
/// block number, BLOCKHASH must also use L1 block numbers for the range check.
/// Otherwise requests for L1 block hashes would always be out of range.
fn arb_blockhash<WIRE: InterpreterTypes, H: Host + ?Sized>(ctx: InstructionContext<'_, H, WIRE>) {
    use revm::interpreter::InstructionResult;

    let requested = match ctx.interpreter.stack.pop() {
        Some(v) => v,
        None => {
            ctx.interpreter.halt(InstructionResult::StackUnderflow);
            return;
        }
    };

    let l1_block_number = ctx.host.block_number();

    let Some(diff) = l1_block_number.checked_sub(requested) else {
        if !ctx.interpreter.stack.push(U256::ZERO) {
            ctx.interpreter.halt(InstructionResult::StackOverflow);
        }
        return;
    };

    let diff_u64: u64 = diff.try_into().unwrap_or(u64::MAX);
    if diff_u64 == 0 || diff_u64 > 256 {
        if !ctx.interpreter.stack.push(U256::ZERO) {
            ctx.interpreter.halt(InstructionResult::StackOverflow);
        }
        return;
    }

    let requested_u64: u64 = requested.try_into().unwrap_or(u64::MAX);
    match ctx.host.block_hash(requested_u64) {
        Some(hash) => {
            if !ctx.interpreter.stack.push(U256::from_be_bytes(hash.0)) {
                ctx.interpreter.halt(InstructionResult::StackOverflow);
            }
        }
        None => {
            ctx.interpreter.halt_fatal();
        }
    }
}

// SHA3 tracer removed — can't easily wrap standard handler

/// Arbitrum BALANCE: subtracts the poster-fee correction when a contract
/// reads the transaction sender's balance, so that the observed value matches
/// a full-`gas_limit * basefee` buy-gas charge.
fn arb_balance<WIRE: InterpreterTypes, H: Host + ?Sized>(ctx: InstructionContext<'_, H, WIRE>) {
    let addr_u256 = match ctx.interpreter.stack.pop() {
        Some(v) => v,
        None => {
            ctx.interpreter
                .halt(revm::interpreter::InstructionResult::StackUnderflow);
            return;
        }
    };

    let addr = alloy_primitives::Address::from_word(alloy_primitives::B256::from(
        addr_u256.to_be_bytes::<32>(),
    ));

    let sender = ctx.host.caller();
    let correction = poster_balance_correction_word();

    let spec_id = ctx.interpreter.runtime_flag.spec_id();
    if spec_id.is_enabled_in(revm::primitives::hardfork::SpecId::BERLIN) {
        let Some(state_load) = ctx.host.balance(addr) else {
            ctx.interpreter.halt_fatal();
            return;
        };
        let gas_cost = if state_load.is_cold { 2600u64 } else { 100u64 };
        if !ctx.interpreter.gas.record_cost(gas_cost) {
            ctx.interpreter
                .halt(revm::interpreter::InstructionResult::OutOfGas);
            return;
        }

        let balance = if addr == sender {
            state_load.data.saturating_sub(correction)
        } else {
            state_load.data
        };

        if !ctx.interpreter.stack.push(balance) {
            ctx.interpreter
                .halt(revm::interpreter::InstructionResult::StackOverflow);
        }
    } else {
        let Some(state_load) = ctx.host.balance(addr) else {
            ctx.interpreter.halt_fatal();
            return;
        };

        let balance = if addr == sender {
            state_load.data.saturating_sub(correction)
        } else {
            state_load.data
        };

        if !ctx.interpreter.stack.push(balance) {
            ctx.interpreter
                .halt(revm::interpreter::InstructionResult::StackOverflow);
        }
    }
}

/// SELFBALANCE opcode (0x47).
const SELFBALANCE_OPCODE: u8 = 0x47;

/// Arbitrum SELFBALANCE: adjusts for poster fee correction if the executing
/// contract IS the tx sender (edge case: sender calls own address).
fn arb_selfbalance<WIRE: InterpreterTypes, H: Host + ?Sized>(ctx: InstructionContext<'_, H, WIRE>) {
    let target = ctx.interpreter.input.target_address();

    let Some(state_load) = ctx.host.balance(target) else {
        ctx.interpreter.halt_fatal();
        return;
    };

    let sender = ctx.host.caller();
    let balance = if target == sender {
        state_load
            .data
            .saturating_sub(poster_balance_correction_word())
    } else {
        state_load.data
    };

    if !ctx.interpreter.stack.push(balance) {
        ctx.interpreter
            .halt(revm::interpreter::InstructionResult::StackOverflow);
    }
}

// EVM opcodes are wired into revm via a `[Instruction; 256]` table built from
// bare `fn` pointers, so the `arb_balance` / `arb_selfbalance` overrides cannot
// accept an extra ctx parameter. The executor publishes the active tx's
// `poster_balance_correction` into this thread-local at the same point it
// stages the precompile ctx; opcode reads stay zero-cost and consensus-only.
//
// Scope: arb-evm only — `arb-precompiles` is forbidden from holding any
// `thread_local!` by the lint job in `.github/workflows/lint.yml`.
thread_local! {
    static POSTER_BALANCE_CORRECTION: std::cell::Cell<u128> = const { std::cell::Cell::new(0) };
}

/// Publish the poster-balance correction word for the active tx so that
/// `arb_balance` / `arb_selfbalance` opcode reads observe it.
pub fn set_poster_balance_correction(value: u128) {
    POSTER_BALANCE_CORRECTION.with(|cell| cell.set(value));
}

/// Reset the per-tx poster-balance correction to zero.
pub fn clear_poster_balance_correction() {
    POSTER_BALANCE_CORRECTION.with(|cell| cell.set(0));
}

fn poster_balance_correction_word() -> U256 {
    POSTER_BALANCE_CORRECTION.with(|cell| U256::from(cell.get()))
}

/// BLOBBASEFEE is not supported on Arbitrum — execution halts.
fn arb_blob_basefee<WIRE: InterpreterTypes, H: Host + ?Sized>(
    ctx: InstructionContext<'_, H, WIRE>,
) {
    ctx.interpreter.halt(InstructionResult::OpcodeNotFound);
}

/// Arbitrum SELFDESTRUCT: reverts if the acting account is a Stylus program,
/// otherwise delegates to the standard EIP-6780 selfdestruct logic.
fn arb_selfdestruct<WIRE: InterpreterTypes, H: Host + ?Sized>(
    ctx: InstructionContext<'_, H, WIRE>,
) {
    if ctx.interpreter.runtime_flag.is_static() {
        ctx.interpreter
            .halt(InstructionResult::StateChangeDuringStaticCall);
        return;
    }

    // Stylus programs cannot be self-destructed.
    let acting_addr = ctx.interpreter.input.target_address();
    match ctx.host.load_account_code(acting_addr) {
        Some(code_load) => {
            if arb_stylus::is_stylus_runnable(&code_load.data) {
                ctx.interpreter.halt(InstructionResult::Revert);
                return;
            }
        }
        None => {
            ctx.interpreter.halt_fatal();
            return;
        }
    }

    // Standard selfdestruct logic (matching revm's EIP-6780 implementation).
    // Pop U256 and convert to Address manually (avoids pop_address() which
    // triggers a ruint 1.17 const eval panic due to U256->Address byte size mismatch).
    let Some(raw) = ctx.interpreter.stack.pop() else {
        ctx.interpreter.halt(InstructionResult::StackUnderflow);
        return;
    };
    let target = Address::from_word(alloy_primitives::B256::from(raw.to_be_bytes()));

    let spec = ctx.interpreter.runtime_flag.spec_id();
    let cold_load_gas = ctx.host.gas_params().selfdestruct_cold_cost();
    let skip_cold_load = ctx.interpreter.gas.remaining() < cold_load_gas;

    let res = match ctx.host.selfdestruct(acting_addr, target, skip_cold_load) {
        Ok(res) => res,
        Err(LoadError::ColdLoadSkipped) => {
            ctx.interpreter.halt_oog();
            return;
        }
        Err(LoadError::DBError) => {
            ctx.interpreter.halt_fatal();
            return;
        }
    };

    // EIP-161: State trie clearing.
    let should_charge_topup = if spec.is_enabled_in(SpecId::SPURIOUS_DRAGON) {
        res.had_value && !res.target_exists
    } else {
        !res.target_exists
    };

    let gas_cost = ctx
        .host
        .gas_params()
        .selfdestruct_cost(should_charge_topup, res.is_cold);
    if !ctx.interpreter.gas.record_cost(gas_cost) {
        ctx.interpreter.halt_oog();
        return;
    }

    if !res.previously_destroyed {
        ctx.interpreter
            .gas
            .record_refund(ctx.host.gas_params().selfdestruct_refund());
    }

    ctx.interpreter.halt(InstructionResult::SelfDestruct);
}

/// Reset per-tx Stylus state at the start of every transaction.
pub fn reset_stylus_pages(ctx: &arb_context::ArbPrecompileCtx) {
    let mut tx = ctx.tx.lock();
    tx.stylus_program_counts.clear();
}

// ── Stylus storage helpers ───────────────────────────────────────────

use arb_storage::{
    ARBOS_STATE_ADDRESS, DatabaseError, DatabaseErrorInfo, Detached, Storage, StorageBackend,
    StorageError, SystemStateBackend,
    layout::{
        PROGRAMS_SUBSPACE, ROOT_STORAGE_KEY, derive_subspace_key, map_slot_b256,
        programs::{MODULE_HASHES_KEY, PARAMS_KEY, PROGRAM_DATA_KEY},
    },
};
use arbos::programs::{Program, memory::MemoryModel, params::StylusParams};

/// Read a storage slot from ArbOS state via the journal.
fn sload_arbos<DB: Database>(journal: &mut revm::Journal<DB>, slot: U256) -> Option<U256> {
    let _ = journal
        .inner
        .load_account(&mut journal.database, ARBOS_STATE_ADDRESS)
        .ok()?;
    let result = journal
        .inner
        .sload(&mut journal.database, ARBOS_STATE_ADDRESS, slot, false)
        .ok()?;
    Some(result.data)
}

/// `StorageBackend` adapter over a live `revm::Journal`, used so dispatch can
/// drive the canonical `arb-storage` accessors without an `EvmInternals` in
/// scope. Reads route through the journal's cold/warm cache; writes are
/// unused on the dispatch path but routed identically for completeness.
struct JournalBackend<'a, DB: Database> {
    journal: &'a mut revm::Journal<DB>,
}

impl<'a, DB: Database> JournalBackend<'a, DB> {
    fn new(journal: &'a mut revm::Journal<DB>) -> Self {
        Self { journal }
    }
}

impl<DB: Database> SystemStateBackend for JournalBackend<'_, DB> {
    type Error = StorageError;

    fn sload_system(&mut self, account: Address, slot: U256) -> Result<U256, Self::Error> {
        // Route through the journal so in-flight writes within the current
        // call are observed; the perf win comes from the per-block
        // ArbosState cache, not from bypassing the journal here.
        let journal = &mut *self.journal;
        journal
            .inner
            .load_account(&mut journal.database, account)
            .map_err(|e| {
                StorageError::Database(DatabaseError::Read(DatabaseErrorInfo::new(format!(
                    "{e:?}"
                ))))
            })?;
        let value = journal
            .inner
            .sload(&mut journal.database, account, slot, false)
            .map_err(|e| {
                StorageError::Database(DatabaseError::Read(DatabaseErrorInfo::new(format!(
                    "{e:?}"
                ))))
            })?;
        Ok(value.data)
    }
}

impl<DB: Database> StorageBackend for JournalBackend<'_, DB> {
    fn sload(&mut self, account: Address, slot: U256) -> Result<U256, StorageError> {
        let journal = &mut *self.journal;
        journal
            .inner
            .load_account(&mut journal.database, account)
            .map_err(|e| {
                StorageError::Database(DatabaseError::Read(DatabaseErrorInfo::new(format!(
                    "{e:?}"
                ))))
            })?;
        let value = journal
            .inner
            .sload(&mut journal.database, account, slot, false)
            .map_err(|e| {
                StorageError::Database(DatabaseError::Read(DatabaseErrorInfo::new(format!(
                    "{e:?}"
                ))))
            })?;
        Ok(value.data)
    }

    fn sstore(&mut self, account: Address, slot: U256, value: U256) -> Result<(), StorageError> {
        let journal = &mut *self.journal;
        journal
            .inner
            .sstore(&mut journal.database, account, slot, value, false)
            .map_err(|e| {
                StorageError::Database(DatabaseError::Write(DatabaseErrorInfo::new(format!(
                    "{e:?}"
                ))))
            })?;
        Ok(())
    }
}

/// Detached `Storage` handle for the `programs/params` subspace.
///
/// Reads route through a [`StorageBackend`]; no executor state pointer is
/// required.
fn programs_params_storage() -> Storage<'static, Detached> {
    let programs_key = derive_subspace_key(ROOT_STORAGE_KEY, PROGRAMS_SUBSPACE);
    let params_key = derive_subspace_key(programs_key.as_slice(), PARAMS_KEY);
    Storage::detached(ARBOS_STATE_ADDRESS, params_key)
}

/// Read program data word by code hash.
fn read_program_word<DB: Database>(
    journal: &mut revm::Journal<DB>,
    code_hash: B256,
) -> Option<B256> {
    let programs_key = derive_subspace_key(ROOT_STORAGE_KEY, PROGRAMS_SUBSPACE);
    let data_key = derive_subspace_key(programs_key.as_slice(), PROGRAM_DATA_KEY);
    let slot = map_slot_b256(data_key.as_slice(), &code_hash);
    sload_arbos(journal, slot).map(|v| B256::from(v.to_be_bytes::<32>()))
}

/// Read the activation-time module hash for a Stylus program by code hash.
/// Read the activation-time module hash stored at programs subspace key [2].
fn read_module_hash<DB: Database>(
    journal: &mut revm::Journal<DB>,
    code_hash: B256,
) -> Option<B256> {
    let programs_key = derive_subspace_key(ROOT_STORAGE_KEY, PROGRAMS_SUBSPACE);
    let module_hashes_key = derive_subspace_key(programs_key.as_slice(), MODULE_HASHES_KEY);
    let slot = map_slot_b256(module_hashes_key.as_slice(), &code_hash);
    sload_arbos(journal, slot).map(|v| B256::from(v.to_be_bytes::<32>()))
}

/// Compute upfront gas cost for a Stylus call, per `Programs.CallProgram`.
fn stylus_call_gas_cost(
    params: &StylusParams,
    program: &Program,
    pages_open: u16,
    pages_ever: u16,
    arbos_version: u64,
) -> u64 {
    let model = MemoryModel::new(params.free_pages, params.page_gas);
    let mut cost = model.gas_cost(program.footprint, pages_open, pages_ever);

    let cached = program.cached;
    if cached || program.version > 1 {
        cost = cost.saturating_add(program.cached_gas(params));
    }
    if !cached {
        cost = cost.saturating_add(program.init_gas(params));
    }
    let new_open = pages_open.saturating_add(program.footprint);
    if arb_stylus::env::page_limit_exceeded(arbos_version, params.page_limit, new_open) {
        cost = cost.saturating_add(u64::MAX);
    }
    cost
}

// ── Stylus sub-call trampolines ─────────────────────────────────────

use arb_stylus::evm_api_impl::{SubCallResult, SubCreateResult};

/// Read the current (pages_open, pages_ever) carried on the active `TxCtx`.
fn read_tx_pages(ctx: &arb_context::ArbPrecompileCtx) -> (u16, u16) {
    let tx = ctx.tx.lock();
    (tx.stylus_pages_open, tx.stylus_pages_ever)
}

/// Write `pages_open` and `pages_ever` to the active `TxCtx`.
fn write_tx_pages(ctx: &arb_context::ArbPrecompileCtx, pages: (u16, u16)) {
    let mut tx = ctx.tx.lock();
    tx.stylus_pages_open = pages.0;
    tx.stylus_pages_ever = pages.1;
}

/// Monomorphized trampoline for Stylus sub-calls (CALL/DELEGATECALL/STATICCALL).
#[allow(clippy::too_many_arguments)]
fn stylus_call_trampoline<BlockEnv, TxEnv, CfgEnv, DB, Chain>(
    ctx: *mut (),
    precompile_ctx: *const (),
    call_type: u8,
    contract: Address,
    caller: Address,
    storage_addr: Address,
    input: &[u8],
    gas: u64,
    value: U256,
    parent_pages: (u16, u16),
) -> SubCallResult
where
    BlockEnv: revm::context::Block,
    TxEnv: revm::context::Transaction,
    CfgEnv: revm::context::Cfg,
    DB: Database,
{
    // SAFETY: `ctx` and `precompile_ctx` are the type-erased pointers stored
    // by `execute_stylus_program` when it built the `StylusEvmApi` for this
    // call frame. The concrete `revm::Context` and `ArbPrecompileCtx` types
    // monomorphise this trampoline, so the cast is the structural inverse
    // of the type-erasure performed when the host function was installed.
    // Both pointers are valid for the duration of the parent EVM frame,
    // which is the only frame that can invoke this trampoline.
    let context = unsafe {
        &mut *(ctx as *mut revm::Context<BlockEnv, TxEnv, CfgEnv, DB, revm::Journal<DB>, Chain>)
    };
    let pre_ctx = unsafe { &*(precompile_ctx as *const arb_context::ArbPrecompileCtx) };

    write_tx_pages(pre_ctx, parent_pages);

    let is_static = call_type == 2;
    let is_delegate = call_type == 1;
    let is_callcode = call_type == 3;

    struct ActorGuard<'a> {
        ctx: &'a arb_context::ArbPrecompileCtx,
        addr: Address,
        pushed: bool,
    }
    impl Drop for ActorGuard<'_> {
        fn drop(&mut self) {
            if self.pushed {
                self.ctx.pop_stylus_program(self.addr);
            }
        }
    }
    let _actor_guard = if !is_delegate && !is_callcode {
        pre_ctx.push_stylus_program(storage_addr);
        ActorGuard {
            ctx: pre_ctx,
            addr: storage_addr,
            pushed: true,
        }
    } else {
        ActorGuard {
            ctx: pre_ctx,
            addr: storage_addr,
            pushed: false,
        }
    };

    let checkpoint = context.journaled_state.inner.checkpoint();

    if !is_delegate && !value.is_zero() {
        let transfer_result = context.journaled_state.inner.transfer(
            &mut context.journaled_state.database,
            caller,
            contract,
            value,
        );
        if matches!(transfer_result, Err(_) | Ok(Some(_))) {
            context.journaled_state.inner.checkpoint_revert(checkpoint);
            return SubCallResult {
                output: Vec::new(),
                gas_cost: 0,
                success: false,
                refund: 0,
                pages: read_tx_pages(pre_ctx),
            };
        }
    }

    let code_address = contract;
    let target_address = storage_addr;
    let _ = is_delegate;

    let call_scheme = match call_type {
        0 => CallScheme::Call,
        1 => CallScheme::DelegateCall,
        2 => CallScheme::StaticCall,
        _ => CallScheme::Call,
    };

    let call_value = if is_delegate {
        revm::interpreter::CallValue::Apparent(value)
    } else {
        revm::interpreter::CallValue::Transfer(value)
    };

    let sub_inputs = CallInputs {
        input: CallInput::Bytes(input.to_vec().into()),
        gas_limit: gas,
        target_address,
        bytecode_address: code_address,
        caller,
        value: call_value,
        scheme: call_scheme,
        is_static,
        return_memory_offset: 0..0,
        known_bytecode: None,
    };

    {
        let spec: revm::primitives::hardfork::SpecId = context.cfg.spec().into();
        let mut precompiles =
            alloy_evm::precompiles::PrecompilesMap::from(revm::handler::EthPrecompiles::new(spec));
        // SAFETY: `precompile_ctx` was obtained as `Arc::as_ptr` from a
        // live `Arc<ArbPrecompileCtx>` held by the dispatch path that
        // installed this trampoline. `increment_strong_count` keeps the
        // parent's refcount intact while `from_raw` rebuilds a clonable
        // handle whose Drop will balance the increment. The pointer is
        // valid for the duration of the parent EVM frame.
        let pre_arc = unsafe {
            let raw = precompile_ctx as *const arb_context::ArbPrecompileCtx;
            std::sync::Arc::increment_strong_count(raw);
            std::sync::Arc::from_raw(raw)
        };
        register_arb_precompiles(&mut precompiles, pre_arc.clone());
        let mut arb_map = ArbPrecompilesMap::new(precompiles, pre_arc);
        let dispatch_result = <ArbPrecompilesMap as PrecompileProvider<
            revm::Context<BlockEnv, TxEnv, CfgEnv, DB, revm::Journal<DB>, Chain>,
        >>::run(&mut arb_map, context, &sub_inputs);

        match dispatch_result {
            Ok(Some(result)) => {
                let success = result.result.is_ok();
                let output = result.output.to_vec();
                // On failure (revert, OOG, error) a non-reverting callee has
                // returned gas left in result.gas, but a precompile that
                // signalled OOG/PrecompileError leaves `result.gas` untouched
                // (see alloy-evm precompile runner). Ethereum semantics charge
                // the caller for all gas forwarded on non-revert failures.
                let gas_used = if success || matches!(result.result, InstructionResult::Revert) {
                    gas.saturating_sub(result.gas.remaining())
                } else {
                    gas
                };
                let refund = if success { result.gas.refunded() } else { 0 };
                if success {
                    context.journaled_state.inner.checkpoint_commit();
                } else {
                    context.journaled_state.inner.checkpoint_revert(checkpoint);
                }
                return SubCallResult {
                    output,
                    gas_cost: gas_used,
                    success,
                    refund,
                    pages: read_tx_pages(pre_ctx),
                };
            }
            Ok(None) => {}
            Err(_) => {
                context.journaled_state.inner.checkpoint_revert(checkpoint);
                return SubCallResult {
                    output: Vec::new(),
                    gas_cost: gas,
                    success: false,
                    refund: 0,
                    pages: read_tx_pages(pre_ctx),
                };
            }
        }
    }

    let bytecode = match context
        .journaled_state
        .inner
        .load_code(&mut context.journaled_state.database, code_address)
    {
        Ok(acc) => acc
            .data
            .info
            .code
            .as_ref()
            .map(|c| c.original_bytes())
            .unwrap_or_default(),
        Err(_) => {
            context.journaled_state.inner.checkpoint_revert(checkpoint);
            return SubCallResult {
                output: Vec::new(),
                gas_cost: 0,
                success: false,
                refund: 0,
                pages: read_tx_pages(pre_ctx),
            };
        }
    };

    // EIP-7702: if the callee carries a delegation designator
    // `0xef 0x01 0x00 || delegate_address`, load the delegate's code and use
    // that for dispatch. Without this the 23-byte stub is fed directly to the
    // EVM interpreter; `0xef` has no defined opcode (EIP-3541 is disabled
    // for Stylus) so the sub-call traps with all forwarded gas consumed.
    let (bytecode, bytecode_addr) = if bytecode.len() == 23
        && bytecode[0] == 0xef
        && bytecode[1] == 0x01
        && bytecode[2] == 0x00
    {
        let delegate = Address::from_slice(&bytecode[3..23]);
        match context
            .journaled_state
            .inner
            .load_code(&mut context.journaled_state.database, delegate)
        {
            Ok(acc) => {
                let code = acc
                    .data
                    .info
                    .code
                    .as_ref()
                    .map(|c| c.original_bytes())
                    .unwrap_or_default();
                (code, delegate)
            }
            Err(_) => {
                context.journaled_state.inner.checkpoint_revert(checkpoint);
                return SubCallResult {
                    output: Vec::new(),
                    gas_cost: 0,
                    success: false,
                    refund: 0,
                    pages: read_tx_pages(pre_ctx),
                };
            }
        }
    } else {
        (bytecode, code_address)
    };

    if bytecode.is_empty() {
        context.journaled_state.inner.checkpoint_commit();
        return SubCallResult {
            output: Vec::new(),
            gas_cost: 0,
            success: true,
            refund: 0,
            pages: read_tx_pages(pre_ctx),
        };
    }

    let sub_inputs = CallInputs {
        bytecode_address: bytecode_addr,
        ..sub_inputs
    };

    if pre_ctx.block.arbos_version >= arb_chainspec::arbos_version::ARBOS_VERSION_STYLUS
        && arb_stylus::is_stylus_runnable(&bytecode)
    {
        // SAFETY: see the `Arc::increment_strong_count` site above —
        // `precompile_ctx` was produced by `Arc::as_ptr` and is valid
        // for this frame's duration. The increment is balanced by the
        // returned `Arc`'s Drop.
        let arc = unsafe {
            let raw = precompile_ctx as *const arb_context::ArbPrecompileCtx;
            std::sync::Arc::increment_strong_count(raw);
            std::sync::Arc::from_raw(raw)
        };
        let result = execute_stylus_program(context, &sub_inputs, &bytecode, &arc);
        let pages = read_tx_pages(pre_ctx);
        let success = result.result.is_ok();
        let output = result.output.to_vec();
        let gas_used = gas.saturating_sub(result.gas.remaining());
        let refund = result.gas.refunded();
        if success {
            context.journaled_state.inner.checkpoint_commit();
        } else {
            context.journaled_state.inner.checkpoint_revert(checkpoint);
        }
        return SubCallResult {
            output,
            gas_cost: gas_used,
            success,
            refund,
            pages,
        };
    }

    let result = run_evm_bytecode(context, &sub_inputs, &bytecode, gas, pre_ctx);
    let pages = read_tx_pages(pre_ctx);
    let success = result.result.is_ok();
    let output = result.output.to_vec();
    let gas_used = if success || matches!(result.result, InstructionResult::Revert) {
        gas.saturating_sub(result.gas.remaining())
    } else {
        gas
    };
    let refund = result.gas.refunded();
    if success {
        context.journaled_state.inner.checkpoint_commit();
    } else {
        context.journaled_state.inner.checkpoint_revert(checkpoint);
    }
    SubCallResult {
        output,
        gas_cost: gas_used,
        success,
        refund,
        pages,
    }
}

/// Monomorphized trampoline for Stylus CREATE/CREATE2 operations.
#[allow(clippy::too_many_arguments)]
fn stylus_create_trampoline<BlockEnv, TxEnv, CfgEnv, DB, Chain>(
    ctx: *mut (),
    precompile_ctx: *const (),
    caller: Address,
    code: &[u8],
    gas: u64,
    endowment: U256,
    salt: Option<B256>,
    parent_pages: (u16, u16),
) -> SubCreateResult
where
    BlockEnv: revm::context::Block,
    TxEnv: revm::context::Transaction,
    CfgEnv: revm::context::Cfg,
    DB: Database,
{
    // SAFETY: see `stylus_call_trampoline` for the type-erasure invariant —
    // `ctx` and `precompile_ctx` were installed by `execute_stylus_program`
    // for this monomorphised trampoline; both are valid for the lifetime of
    // the parent EVM frame that invokes the host function.
    let pre_ctx = unsafe { &*(precompile_ctx as *const arb_context::ArbPrecompileCtx) };
    {
        let mut tx = pre_ctx.tx.lock();
        tx.stylus_pages_open = parent_pages.0;
        tx.stylus_pages_ever = parent_pages.1;
    }
    let context = unsafe {
        &mut *(ctx as *mut revm::Context<BlockEnv, TxEnv, CfgEnv, DB, revm::Journal<DB>, Chain>)
    };

    let (caller_nonce, caller_balance) = {
        let acc = context
            .journaled_state
            .inner
            .load_account(&mut context.journaled_state.database, caller);
        acc.map(|a| (a.data.info.nonce, a.data.info.balance))
            .unwrap_or((0, U256::ZERO))
    };

    if caller_balance < endowment {
        return SubCreateResult {
            address: None,
            output: Vec::new(),
            gas_cost: 0,
            pages: read_tx_pages(pre_ctx),
        };
    }

    let created_address = if let Some(salt) = salt {
        let code_hash = alloy_primitives::keccak256(code);
        let mut buf = Vec::with_capacity(1 + 20 + 32 + 32);
        buf.push(0xff);
        buf.extend_from_slice(caller.as_slice());
        buf.extend_from_slice(salt.as_slice());
        buf.extend_from_slice(code_hash.as_slice());
        Address::from_slice(&alloy_primitives::keccak256(&buf)[12..])
    } else {
        use alloy_rlp::Encodable;
        let mut rlp_buf = Vec::with_capacity(64);
        alloy_rlp::Header {
            list: true,
            payload_length: caller.length() + caller_nonce.length(),
        }
        .encode(&mut rlp_buf);
        caller.encode(&mut rlp_buf);
        caller_nonce.encode(&mut rlp_buf);
        Address::from_slice(&alloy_primitives::keccak256(&rlp_buf)[12..])
    };

    struct CreateActorGuard<'a> {
        ctx: &'a arb_context::ArbPrecompileCtx,
        addr: Address,
    }
    impl Drop for CreateActorGuard<'_> {
        fn drop(&mut self) {
            self.ctx.pop_stylus_program(self.addr);
        }
    }
    pre_ctx.push_stylus_program(created_address);
    let _create_guard = CreateActorGuard {
        ctx: pre_ctx,
        addr: created_address,
    };

    {
        use revm::context_interface::journaled_state::account::JournaledAccountTr;
        let bumped = match context
            .journaled_state
            .inner
            .load_account_mut(&mut context.journaled_state.database, caller)
        {
            Ok(mut caller_acc) => caller_acc.data.bump_nonce(),
            Err(_) => false,
        };
        if !bumped {
            return SubCreateResult {
                address: None,
                output: Vec::new(),
                gas_cost: gas,
                pages: read_tx_pages(pre_ctx),
            };
        }
    }

    if context
        .journaled_state
        .inner
        .load_account(&mut context.journaled_state.database, created_address)
        .is_err()
    {
        return SubCreateResult {
            address: None,
            output: Vec::new(),
            gas_cost: gas,
            pages: read_tx_pages(pre_ctx),
        };
    }

    let spec: revm::primitives::hardfork::SpecId = context.cfg.spec().into();
    let checkpoint = match context.journaled_state.inner.create_account_checkpoint(
        caller,
        created_address,
        endowment,
        spec,
    ) {
        Ok(cp) => cp,
        Err(_) => {
            return SubCreateResult {
                address: None,
                output: Vec::new(),
                gas_cost: gas,
                pages: read_tx_pages(pre_ctx),
            };
        }
    };

    let init_inputs = CallInputs {
        input: CallInput::Bytes(Bytes::new()),
        gas_limit: gas,
        target_address: created_address,
        bytecode_address: created_address,
        caller,
        value: revm::interpreter::CallValue::Transfer(endowment),
        scheme: CallScheme::Call,
        is_static: false,
        return_memory_offset: 0..0,
        known_bytecode: None,
    };

    let result = run_evm_bytecode(context, &init_inputs, code, gas, pre_ctx);
    let pages = read_tx_pages(pre_ctx);
    let success = result.result.is_ok();

    if success {
        let deployed_code = result.output.to_vec();
        let max_code_size = context.cfg.max_code_size();
        if deployed_code.len() > max_code_size {
            context.journaled_state.inner.checkpoint_revert(checkpoint);
            return SubCreateResult {
                address: None,
                output: Vec::new(),
                gas_cost: gas,
                pages,
            };
        }
        let is_stylus =
            arb_stylus::is_stylus_component(&deployed_code, pre_ctx.block.arbos_version);
        if !deployed_code.is_empty() && deployed_code[0] == 0xEF && !is_stylus {
            context.journaled_state.inner.checkpoint_revert(checkpoint);
            return SubCreateResult {
                address: None,
                output: Vec::new(),
                gas_cost: gas,
                pages,
            };
        }
        let deposit_cost = context
            .cfg
            .gas_params()
            .code_deposit_cost(deployed_code.len());
        let after_deposit_remaining = result.gas.remaining().saturating_sub(deposit_cost);
        if result.gas.remaining() < deposit_cost {
            context.journaled_state.inner.checkpoint_revert(checkpoint);
            return SubCreateResult {
                address: None,
                output: Vec::new(),
                gas_cost: gas,
                pages,
            };
        }
        let gas_used = gas.saturating_sub(after_deposit_remaining);
        let code_hash = alloy_primitives::keccak256(&deployed_code);
        let bytecode = revm::bytecode::Bytecode::new_raw(deployed_code.into());
        let _ = context
            .journaled_state
            .inner
            .load_account(&mut context.journaled_state.database, created_address);
        context
            .journaled_state
            .inner
            .set_code_with_hash(created_address, bytecode, code_hash);
        context.journaled_state.inner.checkpoint_commit();
        SubCreateResult {
            address: Some(created_address),
            output: Vec::new(),
            gas_cost: gas_used,
            pages,
        }
    } else {
        let output = result.output.to_vec();
        let gas_used = gas.saturating_sub(result.gas.remaining());
        context.journaled_state.inner.checkpoint_revert(checkpoint);
        SubCreateResult {
            address: None,
            output,
            gas_cost: gas_used,
            pages,
        }
    }
}

/// Run EVM bytecode from a Stylus sub-call.
///
/// Creates an interpreter and runs in a loop, dispatching nested CALL/CREATE
/// actions through the Stylus call trampoline (which in turn uses
/// ArbPrecompilesMap for precompile/Stylus dispatch).
fn run_evm_bytecode<BlockEnv, TxEnv, CfgEnv, DB, Chain>(
    context: &mut revm::Context<BlockEnv, TxEnv, CfgEnv, DB, revm::Journal<DB>, Chain>,
    inputs: &CallInputs,
    bytecode: &[u8],
    gas_limit: u64,
    pre_ctx: &arb_context::ArbPrecompileCtx,
) -> InterpreterResult
where
    BlockEnv: revm::context::Block,
    TxEnv: revm::context::Transaction,
    CfgEnv: revm::context::Cfg,
    DB: Database,
{
    use revm::{
        bytecode::Bytecode,
        interpreter::{
            FrameInput, InterpreterAction, SharedMemory,
            interpreter::{ExtBytecode, InputsImpl},
        },
    };

    let code = Bytecode::new_raw(bytecode.to_vec().into());
    let ext_bytecode = ExtBytecode::new(code);

    let call_value = inputs.value.get();
    let interp_input = InputsImpl {
        target_address: inputs.target_address,
        bytecode_address: Some(inputs.bytecode_address),
        caller_address: inputs.caller,
        input: inputs.input.clone(),
        call_value,
    };

    let spec = context.cfg.spec();

    let mut interpreter = revm::interpreter::Interpreter::new(
        SharedMemory::new(),
        ext_bytecode,
        interp_input,
        inputs.is_static,
        spec.clone().into(),
        gas_limit,
    );

    // Install the Arbitrum opcode overrides on every sub-frame. The outer
    // factory does the same; this path is taken when a Stylus contract
    // re-enters EVM bytecode and must see identical semantics (notably NUMBER
    // returning the L1 block number that EIP-712 signatures depend on).
    type Ctx<B, T, C, D, Ch> = revm::Context<B, T, C, D, revm::Journal<D>, Ch>;
    let mut instructions = EthInstructions::<
        EthInterpreter,
        Ctx<BlockEnv, TxEnv, CfgEnv, DB, Chain>,
    >::new_mainnet_with_spec(spec.into());
    instructions.insert_instruction(
        BLOBBASEFEE_OPCODE,
        revm::interpreter::Instruction::new(arb_blob_basefee, 2),
    );
    instructions.insert_instruction(
        SELFDESTRUCT_OPCODE,
        revm::interpreter::Instruction::new(arb_selfdestruct, 5000),
    );
    instructions.insert_instruction(
        NUMBER_OPCODE,
        revm::interpreter::Instruction::new(arb_number, 2),
    );
    instructions.insert_instruction(
        BLOCKHASH_OPCODE,
        revm::interpreter::Instruction::new(arb_blockhash, 20),
    );
    instructions.insert_instruction(
        BALANCE_OPCODE,
        revm::interpreter::Instruction::new(arb_balance, 0),
    );
    instructions.insert_instruction(
        SELFBALANCE_OPCODE,
        revm::interpreter::Instruction::new(arb_selfbalance, 5),
    );

    // Attribute this EVM sub-frame's opcodes by multi-gas dimension so a Stylus
    // contract calling Solidity prices the callee's storage/log gas like the EVM
    // would. Sub-calls dispatched below surface as `NewFrame`; their forwarded
    // gas is stripped via the inspector's call/create hooks and attributed by
    // the callee frame.
    let mut multi_gas_inspector = crate::multi_gas::MultiGasInspector::default();
    loop {
        let action = revm::inspector::inspect_instructions(
            context,
            &mut interpreter,
            &mut multi_gas_inspector,
            &instructions.instruction_table,
        );

        match action {
            InterpreterAction::Return(result) => {
                pre_ctx.add_stylus_multi_gas(multi_gas_inspector.take_multi_gas());
                return result;
            }
            InterpreterAction::NewFrame(FrameInput::Call(mut sub_call)) => {
                revm::Inspector::call(&mut multi_gas_inspector, context, &mut sub_call);
                // Dispatch nested call through our trampoline.
                // For DELEGATECALL, target_address is the storage context (preserved
                // from parent), and caller is the msg.sender (preserved). For
                // CALL/STATICCALL, target_address == bytecode_address.
                //
                // Resolve `sub_call.input` against the *interpreter's* SharedMemory.
                // We can't use `sub_call.input.bytes(context)` because that reads
                // from `context.local()` — the global context's local memory —
                // whereas this frame's CALL/STATICCALL was issued against the
                // private SharedMemory we created at the top of this function.
                // Reading from the wrong memory returns garbage and silently
                // corrupts the input to ecrecover, transferFrom, etc.
                let resolved_input: Bytes = match &sub_call.input {
                    revm::interpreter::CallInput::Bytes(b) => b.clone(),
                    // A zero-length range carries no input; its start offset may
                    // sit past the un-grown memory, so skip the slice read.
                    revm::interpreter::CallInput::SharedBuffer(range) if range.is_empty() => {
                        Bytes::new()
                    }
                    revm::interpreter::CallInput::SharedBuffer(range) => {
                        // The range was computed by call_helpers as
                        //   range.start = relative_offset + local_memory_offset()
                        // i.e. an absolute offset into the SharedMemory buffer.
                        Bytes::from(
                            interpreter
                                .memory
                                .global_slice_range(range.clone())
                                .to_vec(),
                        )
                    }
                };
                let bytecode_address = sub_call.bytecode_address;
                let parent_pages = read_tx_pages(pre_ctx);
                let sub_result = stylus_call_trampoline::<BlockEnv, TxEnv, CfgEnv, DB, Chain>(
                    context as *mut _ as *mut (),
                    pre_ctx as *const _ as *const (),
                    match sub_call.scheme {
                        CallScheme::Call | CallScheme::CallCode => 0,
                        CallScheme::DelegateCall => 1,
                        CallScheme::StaticCall => 2,
                    },
                    bytecode_address,
                    sub_call.caller,
                    sub_call.target_address,
                    &resolved_input,
                    sub_call.gas_limit,
                    sub_call.value.get(),
                    parent_pages,
                );
                write_tx_pages(pre_ctx, sub_result.pages);

                let gas_remaining = sub_call.gas_limit.saturating_sub(sub_result.gas_cost);
                let ins_result = if sub_result.success {
                    InstructionResult::Return
                } else {
                    InstructionResult::Revert
                };

                let output: Bytes = sub_result.output.into();
                let returned_len = output.len();
                let mem_start = sub_call.return_memory_offset.start;
                let mem_length = sub_call.return_memory_offset.len();
                let target_len = mem_length.min(returned_len);

                interpreter.return_data.set_buffer(output);

                let item = if ins_result.is_ok() {
                    U256::from(1)
                } else {
                    U256::ZERO
                };
                let _ = interpreter.stack.push(item);

                if ins_result.is_ok_or_revert() {
                    interpreter.gas.erase_cost(gas_remaining);
                    if target_len > 0 {
                        interpreter
                            .memory
                            .set(mem_start, &interpreter.return_data.buffer()[..target_len]);
                    }
                }

                if ins_result.is_ok() {
                    // Propagate the sub-call's SSTORE refund (EIP-3529) up
                    // through the Stylus -> EVM bytecode -> Stylus call chain.
                    // Mirrors revm's `EthFrame::return_result` which also does
                    // `interpreter.gas.record_refund(out_gas.refunded())` on
                    // success. Without this, a Stylus contract that goes
                    // through a Solidity intermediary to reach an inner
                    // contract that clears storage loses the 4800-gas clearing
                    // refund (block 55,755,413 tx 2).
                    interpreter.gas.record_refund(sub_result.refund);
                }
            }
            InterpreterAction::NewFrame(FrameInput::Create(mut sub_create)) => {
                revm::Inspector::create(&mut multi_gas_inspector, context, &mut sub_create);
                // Dispatch create through our trampoline
                let salt = match sub_create.scheme() {
                    revm::interpreter::CreateScheme::Create2 { salt } => {
                        Some(B256::from(salt.to_be_bytes()))
                    }
                    _ => None,
                };

                let parent_pages = read_tx_pages(pre_ctx);
                let sub_result = stylus_create_trampoline::<BlockEnv, TxEnv, CfgEnv, DB, Chain>(
                    context as *mut _ as *mut (),
                    pre_ctx as *const _ as *const (),
                    sub_create.caller(),
                    sub_create.init_code(),
                    sub_create.gas_limit(),
                    sub_create.value(),
                    salt,
                    parent_pages,
                );
                write_tx_pages(pre_ctx, sub_result.pages);

                let gas_remaining = sub_create.gas_limit().saturating_sub(sub_result.gas_cost);
                let created_addr = sub_result.address;

                let ins_result = if created_addr.is_some() {
                    InstructionResult::Return
                } else if !sub_result.output.is_empty() {
                    InstructionResult::Revert
                } else {
                    InstructionResult::CreateInitCodeStartingEF00
                };

                let output: Bytes = sub_result.output.into();
                interpreter.return_data.set_buffer(output);

                // Push created address or zero
                let item = match created_addr {
                    Some(addr) => addr.into_word().into(),
                    None => U256::ZERO,
                };
                let _ = interpreter.stack.push(item);

                if ins_result.is_ok_or_revert() {
                    interpreter.gas.erase_cost(gas_remaining);
                }
            }
            InterpreterAction::NewFrame(FrameInput::Empty) => {
                pre_ctx.add_stylus_multi_gas(multi_gas_inspector.take_multi_gas());
                return InterpreterResult::new(
                    InstructionResult::Revert,
                    Bytes::new(),
                    EvmGas::new(0),
                );
            }
        }
    }
}

// ── Stylus WASM dispatch ────────────────────────────────────────────

/// Exits the Stylus frame on drop.
struct StylusFrameGuard<'a> {
    ctx: &'a std::sync::Arc<arb_context::ArbPrecompileCtx>,
}

impl Drop for StylusFrameGuard<'_> {
    fn drop(&mut self) {
        self.ctx.exit_stylus_frame();
    }
}

/// Execute a Stylus WASM program by creating a NativeInstance and running it.
///
/// Validates the program, computes upfront gas costs (memory pages + init/cached
/// gas), deducts them, then runs the WASM. Page counters flow through
/// `TxCtx::stylus_pages_*` between dispatch boundaries.
fn execute_stylus_program<BlockEnv, TxEnv, CfgEnv, DB, Chain>(
    context: &mut revm::Context<BlockEnv, TxEnv, CfgEnv, DB, revm::Journal<DB>, Chain>,
    inputs: &CallInputs,
    bytecode: &[u8],
    ctx: &std::sync::Arc<arb_context::ArbPrecompileCtx>,
) -> InterpreterResult
where
    BlockEnv: revm::context::Block,
    TxEnv: revm::context::Transaction,
    CfgEnv: revm::context::Cfg,
    DB: Database,
{
    use arbos::programs::types::UserOutcome;

    let stylus_frame_depth = ctx.enter_stylus_frame();
    let _stylus_frame_guard = StylusFrameGuard { ctx };

    let zero_gas = || EvmGas::new(0);
    let write_pages = |open: u16, ever: u16| {
        let mut tx = ctx.tx.lock();
        tx.stylus_pages_open = open;
        tx.stylus_pages_ever = ever;
    };
    let (parent_open, parent_ever) = {
        let tx = ctx.tx.lock();
        (tx.stylus_pages_open, tx.stylus_pages_ever)
    };

    let code_hash = alloy_primitives::keccak256(bytecode);
    let arbos_version = ctx.block.arbos_version;
    let block_timestamp = ctx.block.block_timestamp;

    let params_sto = programs_params_storage();
    let params = {
        let mut backend = JournalBackend::new(&mut context.journaled_state);
        match StylusParams::load(arbos_version, &params_sto, &mut backend) {
            Ok(p) => p,
            Err(e) => {
                tracing::warn!(target: "stylus", err = %e, "failed to load StylusParams from storage");
                return InterpreterResult::new(InstructionResult::Revert, Bytes::new(), zero_gas());
            }
        }
    };

    let program_word = match read_program_word(&mut context.journaled_state, code_hash) {
        Some(w) => w,
        None => {
            tracing::warn!(target: "stylus", codehash = %code_hash, "failed to read program data");
            return InterpreterResult::new(InstructionResult::Revert, Bytes::new(), zero_gas());
        }
    };
    let program = Program::from_storage(program_word, block_timestamp);

    if program.version == 0 || program.version != params.version {
        tracing::warn!(target: "stylus", codehash = %code_hash, program_ver = program.version, params_ver = params.version, "program version mismatch");
        return InterpreterResult::new(InstructionResult::Revert, Bytes::new(), zero_gas());
    }
    let expiry_seconds = (params.expiry_days as u64) * 24 * 3600;
    if program.age_seconds > expiry_seconds {
        tracing::warn!(target: "stylus", codehash = %code_hash, "program expired");
        return InterpreterResult::new(InstructionResult::Revert, Bytes::new(), zero_gas());
    }

    let recent_wasms_hit = if arbos_version >= arb_chainspec::arbos_version::ARBOS_VERSION_60 {
        ctx.block.insert_recent_wasm(code_hash)
    } else {
        false
    };
    let effective_cached = program.cached || recent_wasms_hit;
    let effective_program = if effective_cached != program.cached {
        let mut p = program;
        p.cached = effective_cached;
        p
    } else {
        program
    };
    let upfront_cost = stylus_call_gas_cost(
        &params,
        &effective_program,
        parent_open,
        parent_ever,
        arbos_version,
    );
    let total_gas = inputs.gas_limit;

    if total_gas < upfront_cost {
        // Only the outermost Stylus frame leaves its abort gas undimensioned; a
        // Stylus ancestor folds a nested abort into its own computation.
        if stylus_frame_depth == 1 {
            ctx.add_stylus_upfront_oog_gas(total_gas);
        }
        return InterpreterResult::new(InstructionResult::OutOfGas, Bytes::new(), zero_gas());
    }
    let gas_for_wasm = total_gas - upfront_cost;

    let stylus_config = StylusConfig::new(params.version, params.max_stack_depth, params.ink_price);

    let target_addr = inputs.target_address;
    let reentrant = ctx.stylus_program_count(target_addr) > 1;

    let module_hash =
        read_module_hash(&mut context.journaled_state, code_hash).unwrap_or(code_hash);

    let mut evm_data = build_evm_data(context, inputs, ctx);
    evm_data.reentrant = reentrant as u32;
    evm_data.cached = effective_program.cached;
    evm_data.module_hash = module_hash;

    let start_open = parent_open.saturating_add(program.footprint);
    let start_ever = parent_ever.max(start_open);

    let journal_ptr = &mut context.journaled_state as *mut revm::Journal<DB>;
    let is_static = inputs.is_static || matches!(inputs.scheme, CallScheme::StaticCall);
    let ctx_ptr = context as *mut _ as *mut ();
    let precompile_ctx_ptr = std::sync::Arc::as_ptr(ctx) as *const ();
    let caller = inputs.caller;
    let call_value = inputs.value.get();
    // SAFETY: `journal_ptr`, `ctx_ptr`, and `precompile_ctx_ptr` are all
    // borrowed from values that live for the entirety of this function —
    // `context` is borrowed `&mut` through the call, the `Arc` holds `ctx`
    // pinned, and the journal is part of `context`. The `StylusEvmApi` is
    // consumed by `instance.run_main` below before this function returns,
    // so the pointers never outlive the borrows that produced them.
    let evm_api = unsafe {
        StylusEvmApi::new(
            journal_ptr,
            target_addr,
            caller,
            call_value,
            is_static,
            arbos_version,
            ctx_ptr,
            precompile_ctx_ptr,
            Some(stylus_call_trampoline::<BlockEnv, TxEnv, CfgEnv, DB, Chain>),
            Some(stylus_create_trampoline::<BlockEnv, TxEnv, CfgEnv, DB, Chain>),
        )
    };

    // Reuse the program's compiled module from the process-wide cache, compiling
    // and inserting it on a miss. Keyed by module hash, independent of block/tx state.
    let long_term_tag = if program.cached { 1u32 } else { 0u32 };
    let (module, store) = match arb_stylus::cache::InitCache::get(
        module_hash,
        params.version,
        long_term_tag,
        false,
    ) {
        Some(loaded) => loaded,
        None => {
            // A root program's WASM is reconstructed from its fragments; execution
            // does not charge for the reads (the activation path does) and reads
            // fragment code straight from the database so it is not warmed.
            let decompressed_result = if arb_stylus::is_stylus_root(bytecode) {
                arb_stylus::get_wasm_from_root(
                    bytecode,
                    params.max_wasm_size,
                    params.max_fragment_count,
                    false,
                    |addr| {
                        let db = &mut context.journaled_state.database;
                        let info = db
                            .basic(addr)
                            .map_err(|e| arb_stylus::StylusError::Backend(format!("{e:?}")))?
                            .unwrap_or_default();
                        let code = match info.code {
                            Some(c) => c,
                            None => db
                                .code_by_hash(info.code_hash)
                                .map_err(|e| arb_stylus::StylusError::Backend(format!("{e:?}")))?,
                        };
                        Ok(code.original_bytes().to_vec())
                    },
                )
            } else {
                arb_stylus::decompress_wasm(bytecode)
            };
            let decompressed = match decompressed_result {
                Ok(w) => w,
                // A backing-store failure is an infrastructure error: abort rather
                // than revert, so a transient read error can't pass as a bad program.
                Err(arb_stylus::StylusError::Backend(e)) => {
                    tracing::error!(target: "stylus", codehash = %code_hash, err = %e, "fragment read failed");
                    write_pages(parent_open, start_ever);
                    return InterpreterResult::new(
                        InstructionResult::FatalExternalError,
                        Bytes::new(),
                        zero_gas(),
                    );
                }
                Err(e) => {
                    tracing::warn!(target: "stylus", codehash = %code_hash, err = %e, "WASM decompression failed");
                    write_pages(parent_open, start_ever);
                    return InterpreterResult::new(
                        InstructionResult::Revert,
                        Bytes::new(),
                        zero_gas(),
                    );
                }
            };
            let serialized = match arb_stylus::compile_module(&decompressed, params.version, false)
            {
                Ok(s) => s,
                Err(e) => {
                    tracing::warn!(target: "stylus", codehash = %code_hash, err = %e, "failed to compile WASM");
                    write_pages(parent_open, start_ever);
                    return InterpreterResult::new(
                        InstructionResult::Revert,
                        Bytes::new(),
                        zero_gas(),
                    );
                }
            };
            match arb_stylus::cache::InitCache::insert(
                module_hash,
                &serialized,
                params.version,
                long_term_tag,
                false,
            ) {
                Ok(loaded) => loaded,
                Err(e) => {
                    tracing::warn!(target: "stylus", codehash = %code_hash, err = %e, "failed to load compiled module");
                    write_pages(parent_open, start_ever);
                    return InterpreterResult::new(
                        InstructionResult::Revert,
                        Bytes::new(),
                        zero_gas(),
                    );
                }
            }
        }
    };

    let compile = match arb_stylus::CompileConfig::version(params.version, false) {
        Ok(c) => c,
        Err(e) => {
            tracing::warn!(target: "stylus", codehash = %code_hash, err = %e, "unsupported Stylus version");
            write_pages(parent_open, start_ever);
            return InterpreterResult::new(InstructionResult::Revert, Bytes::new(), zero_gas());
        }
    };
    let mut env = arb_stylus::env::WasmEnv::new(compile, Some(stylus_config), evm_api, evm_data);
    env.set_pages(
        start_open,
        start_ever,
        params.free_pages,
        params.page_gas,
        params.page_limit,
        arbos_version,
    );
    let mut instance = match arb_stylus::NativeInstance::from_module(module, store, env) {
        Ok(inst) => inst,
        Err(e) => {
            tracing::warn!(target: "stylus", codehash = %code_hash, err = %e, "failed to build instance");
            write_pages(parent_open, start_ever);
            return InterpreterResult::new(InstructionResult::Revert, Bytes::new(), zero_gas());
        }
    };

    write_pages(start_open, start_ever);

    let ink = stylus_config.pricing.gas_to_ink(StylusGas(gas_for_wasm));

    let calldata_owned: Bytes = inputs.input.bytes(context);
    let calldata: &[u8] = &calldata_owned;
    let outcome = match instance.run_main(calldata, stylus_config, ink) {
        Ok(outcome) => outcome,
        Err(e) => {
            tracing::warn!(target: "stylus", codehash = %code_hash, err = %e, "WASM execution failed");
            let final_ever = instance.env().pages_ever.max(start_ever);
            write_pages(parent_open, final_ever);
            return InterpreterResult::new(InstructionResult::Revert, Bytes::new(), zero_gas());
        }
    };

    let final_ever = instance.env().pages_ever.max(start_ever);
    write_pages(parent_open, final_ever);

    let ink_left = match instance.ink_left() {
        arb_stylus::MachineMeter::Ready(ink_val) => ink_val,
        arb_stylus::MachineMeter::Exhausted => arb_stylus::Ink(0),
    };
    let gas_left = stylus_config.pricing.ink_to_gas(ink_left).0;

    let output: Bytes = instance.env().outs.clone().into();
    let gas_left = if !output.is_empty()
        && arbos_version >= arb_chainspec::arbos_version::ARBOS_VERSION_STYLUS_FIXES
    {
        let evm_cost = arbos::programs::types::evm_memory_cost(output.len() as u64);
        if total_gas < evm_cost {
            0
        } else {
            gas_left.min(total_gas - evm_cost)
        }
    } else {
        gas_left
    };

    let mut gas_result = EvmGas::new(gas_left);
    let sstore_refund = instance.env().evm_api.sstore_refund();
    if sstore_refund != 0 {
        gas_result.record_refund(sstore_refund);
    }

    let consumed_gas_left = match outcome {
        UserOutcome::OutOfInk | UserOutcome::OutOfStack => 0,
        _ => gas_left,
    };
    // Gas forwarded to sub-calls is attributed by the callee frame, so exclude
    // it from this frame's WasmComputation residual.
    let sub_call_gas = instance.env().evm_api.sub_call_gas();
    let mut program_multi_gas = instance.env().evm_api.multi_gas();
    arbos::programs::attribute_wasm_computation(
        &mut program_multi_gas,
        total_gas.saturating_sub(sub_call_gas),
        consumed_gas_left,
    );
    ctx.add_stylus_multi_gas(program_multi_gas);

    match outcome {
        UserOutcome::Success => {
            InterpreterResult::new(InstructionResult::Return, output, gas_result)
        }
        UserOutcome::Revert => {
            InterpreterResult::new(InstructionResult::Revert, output, gas_result)
        }
        UserOutcome::OutOfInk => {
            InterpreterResult::new(InstructionResult::OutOfGas, Bytes::new(), zero_gas())
        }
        UserOutcome::OutOfStack => {
            InterpreterResult::new(InstructionResult::CallTooDeep, Bytes::new(), zero_gas())
        }
        UserOutcome::Failure => {
            InterpreterResult::new(InstructionResult::Revert, Bytes::new(), gas_result)
        }
    }
}

/// Build [`EvmData`] from the current execution context.
fn build_evm_data<BlockEnv, TxEnv, CfgEnv, DB, Chain>(
    context: &revm::Context<BlockEnv, TxEnv, CfgEnv, DB, revm::Journal<DB>, Chain>,
    inputs: &CallInputs,
    ctx: &arb_context::ArbPrecompileCtx,
) -> EvmData
where
    BlockEnv: revm::context::Block,
    TxEnv: revm::context::Transaction,
    CfgEnv: revm::context::Cfg,
    DB: Database,
{
    let basefee = U256::from(context.block.basefee());
    // Pre-cap effective price stashed by ArbBlockExecutor; fall back to the
    // capped tx_env when unset (e.g. direct dispatch in unit tests).
    let stashed = ctx.tx_snapshot().effective_gas_price;
    let gas_price = if stashed != 0 {
        U256::from(stashed)
    } else {
        U256::from(context.tx.gas_price())
    };
    let value = inputs.value.get();

    EvmData {
        arbos_version: ctx.block.arbos_version,
        block_basefee: B256::from(basefee.to_be_bytes()),
        chain_id: context.cfg.chain_id(),
        block_coinbase: context.block.beneficiary(),
        block_gas_limit: context.block.gas_limit(),
        block_number: ctx.block.l1_block_number_for_evm,
        block_timestamp: context.block.timestamp().saturating_to(),
        contract_address: inputs.target_address,
        module_hash: alloy_primitives::keccak256(b""),
        msg_sender: inputs.caller,
        msg_value: B256::from(value.to_be_bytes()),
        tx_gas_price: B256::from(gas_price.to_be_bytes()),
        tx_origin: context.tx.caller(),
        reentrant: 0,
        cached: false,
        tracing: false,
    }
}

// ── Stylus frame-level intercept ──────────────────────────────────

/// Check if a `FrameInit` targets a Stylus WASM program via `known_bytecode`.
fn is_stylus_call(frame_init: &FrameInit, arbos_version: u64) -> Option<Bytes> {
    if arbos_version < arb_chainspec::arbos_version::ARBOS_VERSION_STYLUS {
        return None;
    }
    if let FrameInput::Call(ref inputs) = frame_init.frame_input
        && let Some((_, ref code)) = inputs.known_bytecode
    {
        let raw = code.original_bytes();
        if arb_stylus::is_stylus_runnable(&raw) {
            return Some(raw);
        }
    }
    None
}

/// Execute a Stylus call and return the appropriate `FrameResult`, handling
/// journal checkpoint commit/revert.
fn execute_stylus_call_concrete<DB: Database>(
    ctx: &mut EthEvmContext<DB>,
    inputs: &CallInputs,
    bytecode: &[u8],
    checkpoint: revm::context_interface::journaled_state::JournalCheckpoint,
    pre_ctx: &std::sync::Arc<arb_context::ArbPrecompileCtx>,
) -> FrameResult {
    // Handle value transfer for non-delegate calls (matches EthFrame::make_call_frame).
    if let revm::interpreter::CallValue::Transfer(value) = inputs.value
        && let Some(i) =
            ctx.journal_mut()
                .transfer_loaded(inputs.caller, inputs.target_address, value)
    {
        let gas = EvmGas::new(inputs.gas_limit);
        ctx.journaled_state.inner.checkpoint_revert(checkpoint);
        return FrameResult::Call(CallOutcome {
            result: InterpreterResult::new(i.into(), Bytes::new(), gas),
            memory_offset: inputs.return_memory_offset.clone(),
            was_precompile_called: false,
            precompile_call_logs: Vec::new(),
        });
    }

    let result = execute_stylus_program(ctx, inputs, bytecode, pre_ctx);

    if result.result.is_ok() {
        ctx.journaled_state.inner.checkpoint_commit();
    } else {
        ctx.journaled_state.inner.checkpoint_revert(checkpoint);
    }
    FrameResult::Call(CallOutcome {
        result,
        memory_offset: inputs.return_memory_offset.clone(),
        was_precompile_called: false,
        precompile_call_logs: Vec::new(),
    })
}

// ── Precompile provider ────────────────────────────────────────────

#[derive(Clone, Debug)]
pub struct ArbPrecompilesMap {
    pub inner: PrecompilesMap,
    /// Per-block context shared with the registered precompile closures and
    /// the Stylus dispatch path. Cheap to clone (`Arc`).
    pub ctx: std::sync::Arc<arb_context::ArbPrecompileCtx>,
}

impl ArbPrecompilesMap {
    pub fn new(inner: PrecompilesMap, ctx: std::sync::Arc<arb_context::ArbPrecompileCtx>) -> Self {
        Self { inner, ctx }
    }
}

impl<BlockEnv, TxEnv, CfgEnv, DB, Chain>
    PrecompileProvider<revm::Context<BlockEnv, TxEnv, CfgEnv, DB, revm::Journal<DB>, Chain>>
    for ArbPrecompilesMap
where
    BlockEnv: revm::context::Block,
    TxEnv: revm::context::Transaction,
    CfgEnv: revm::context::Cfg,
    DB: Database,
{
    type Output = InterpreterResult;

    fn set_spec(&mut self, spec: CfgEnv::Spec) -> bool {
        <PrecompilesMap as PrecompileProvider<
            revm::Context<BlockEnv, TxEnv, CfgEnv, DB, revm::Journal<DB>, Chain>,
        >>::set_spec(&mut self.inner, spec)
    }

    // The `String` error type comes from upstream `PrecompileProvider::run`;
    // we cannot tighten it without forking revm.
    fn run(
        &mut self,
        context: &mut revm::Context<BlockEnv, TxEnv, CfgEnv, DB, revm::Journal<DB>, Chain>,
        inputs: &CallInputs,
    ) -> Result<Option<Self::Output>, String> {
        self.ctx.set_evm_depth(context.journaled_state.inner.depth);

        // Check precompiles first.
        if let result @ Some(_) = <PrecompilesMap as PrecompileProvider<
            revm::Context<BlockEnv, TxEnv, CfgEnv, DB, revm::Journal<DB>, Chain>,
        >>::run(&mut self.inner, context, inputs)?
        {
            return Ok(result);
        }

        // Check for Stylus WASM programs (active at ArbOS v31+).
        let arbos_version = self.ctx.block.arbos_version;
        if arbos_version >= arb_chainspec::arbos_version::ARBOS_VERSION_STYLUS {
            // Use known_bytecode from CallInputs if available (already loaded by
            // revm's CALL handler), otherwise load from journal.
            let bytecode = inputs
                .known_bytecode
                .as_ref()
                .map(|(_, code)| code.original_bytes())
                .or_else(|| {
                    context
                        .journaled_state
                        .inner
                        .load_code(
                            &mut context.journaled_state.database,
                            inputs.bytecode_address,
                        )
                        .ok()
                        .and_then(|acc| acc.data.info.code.as_ref().map(|c| c.original_bytes()))
                });

            if let Some(bytecode) = bytecode
                && arb_stylus::is_stylus_runnable(&bytecode)
            {
                return Ok(Some(execute_stylus_program(
                    context, inputs, &bytecode, &self.ctx,
                )));
            }
        }

        Ok(None)
    }

    fn warm_addresses(&self) -> Box<impl Iterator<Item = Address>> {
        <PrecompilesMap as PrecompileProvider<
            revm::Context<BlockEnv, TxEnv, CfgEnv, DB, revm::Journal<DB>, Chain>,
        >>::warm_addresses(&self.inner)
    }

    fn contains(&self, address: &Address) -> bool {
        <PrecompilesMap as PrecompileProvider<
            revm::Context<BlockEnv, TxEnv, CfgEnv, DB, revm::Journal<DB>, Chain>,
        >>::contains(&self.inner, address)
    }
}

// ── ArbEvm ─────────────────────────────────────────────────────────

type InnerRevmEvm<DB, I> = RevmEvm<
    EthEvmContext<DB>,
    I,
    EthInstructions<EthInterpreter, EthEvmContext<DB>>,
    ArbPrecompilesMap,
    EthFrame,
>;

struct CreateFrameCtx {
    caller: Address,
    checkpoint: revm::context_interface::journaled_state::JournalCheckpoint,
}

/// Arbitrum EVM with frame-level Stylus dispatch and custom opcodes.
///
/// Implements [`EvmTr`] directly to intercept Stylus WASM calls in
/// `frame_init` before they reach the precompile provider.
pub struct ArbEvm<DB: Database, I> {
    inner: InnerRevmEvm<DB, I>,
    inspect: bool,
    create_ctx_stack: Vec<CreateFrameCtx>,
    actor_stack: Vec<Option<Address>>,
}

impl<DB, I> ArbEvm<DB, I>
where
    DB: Database,
{
    pub fn new(inner: InnerRevmEvm<DB, I>, inspect: bool) -> Self {
        Self {
            inner,
            inspect,
            create_ctx_stack: Vec::new(),
            actor_stack: Vec::new(),
        }
    }

    pub fn into_inner(self) -> InnerRevmEvm<DB, I> {
        self.inner
    }

    pub fn ctx(&self) -> &EthEvmContext<DB> {
        &self.inner.ctx
    }

    pub fn ctx_mut(&mut self) -> &mut EthEvmContext<DB> {
        &mut self.inner.ctx
    }

    pub fn precompiles_mut(&mut self) -> &mut ArbPrecompilesMap {
        &mut self.inner.precompiles
    }
}

/// Accessor for the `Arc<ArbPrecompileCtx>` that an EVM factory most recently
/// staged for the next [`EvmFactory::create_evm`] call. The block executor
/// reuses this `Arc` so its per-tx writes share an allocation with the EVM
/// precompile handler closures (which capture the `Arc` at registration time).
pub trait ArbEvmFactoryStaged {
    fn staged_precompile_ctx(&self) -> Option<std::sync::Arc<arb_context::ArbPrecompileCtx>>;
}

impl ArbEvmFactoryStaged for ArbEvmFactory {
    fn staged_precompile_ctx(&self) -> Option<std::sync::Arc<arb_context::ArbPrecompileCtx>> {
        self.staged()
    }
}

impl<DB: Database, I> core::ops::Deref for ArbEvm<DB, I> {
    type Target = EthEvmContext<DB>;
    fn deref(&self) -> &Self::Target {
        &self.inner.ctx
    }
}

impl<DB: Database, I> core::ops::DerefMut for ArbEvm<DB, I> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.inner.ctx
    }
}

// ── EvmTr for ArbEvm ─────────────────────────────────────────────

impl<DB, I> EvmTr for ArbEvm<DB, I>
where
    DB: Database,
    I: Inspector<EthEvmContext<DB>, EthInterpreter>,
{
    type Context = EthEvmContext<DB>;
    type Instructions = EthInstructions<EthInterpreter, EthEvmContext<DB>>;
    type Precompiles = ArbPrecompilesMap;
    type Frame = EthFrame<EthInterpreter>;

    #[inline]
    fn all(
        &self,
    ) -> (
        &Self::Context,
        &Self::Instructions,
        &Self::Precompiles,
        &FrameStack<Self::Frame>,
    ) {
        self.inner.all()
    }

    #[inline]
    fn all_mut(
        &mut self,
    ) -> (
        &mut Self::Context,
        &mut Self::Instructions,
        &mut Self::Precompiles,
        &mut FrameStack<Self::Frame>,
    ) {
        self.inner.all_mut()
    }

    #[inline]
    fn frame_init(
        &mut self,
        frame_input: FrameInit,
    ) -> Result<
        ItemOrResult<&mut Self::Frame, FrameResult>,
        revm::handler::evm::ContextDbError<Self::Context>,
    > {
        let pre_ctx = self.inner.precompiles.ctx.clone();
        let pushed_caller = match &frame_input.frame_input {
            FrameInput::Call(inputs) => {
                pre_ctx.push_caller(inputs.caller);
                true
            }
            FrameInput::Create(inputs) => {
                pre_ctx.push_caller(inputs.caller());
                true
            }
            _ => false,
        };

        match &frame_input.frame_input {
            FrameInput::Call(inputs)
                if !matches!(
                    inputs.scheme,
                    CallScheme::DelegateCall | CallScheme::CallCode
                ) =>
            {
                pre_ctx.push_stylus_program(inputs.target_address);
                self.actor_stack.push(Some(inputs.target_address));
            }
            FrameInput::Call(_) => {
                self.actor_stack.push(None);
            }
            FrameInput::Create(_) => {
                self.actor_stack.push(None);
            }
            _ => {}
        }

        if let FrameInput::Create(inputs) = &frame_input.frame_input {
            let cp = self.inner.ctx.journal_mut().checkpoint();
            self.create_ctx_stack.push(CreateFrameCtx {
                caller: inputs.caller(),
                checkpoint: cp,
            });
        }

        if let Some(bytecode) = is_stylus_call(&frame_input, pre_ctx.block.arbos_version)
            && let FrameInput::Call(ref inputs) = frame_input.frame_input
        {
            if frame_input.depth > revm::primitives::constants::CALL_STACK_LIMIT as usize {
                let gas = EvmGas::new(inputs.gas_limit);
                if pushed_caller {
                    pre_ctx.pop_caller();
                }
                return Ok(ItemOrResult::Result(FrameResult::Call(CallOutcome {
                    result: InterpreterResult::new(
                        InstructionResult::CallTooDeep,
                        Bytes::new(),
                        gas,
                    ),
                    memory_offset: inputs.return_memory_offset.clone(),
                    was_precompile_called: false,
                    precompile_call_logs: Vec::new(),
                })));
            }
            let checkpoint = self.inner.ctx.journal_mut().checkpoint();
            let result = execute_stylus_call_concrete(
                &mut self.inner.ctx,
                inputs,
                &bytecode,
                checkpoint,
                &pre_ctx,
            );
            if pushed_caller {
                pre_ctx.pop_caller();
            }
            return Ok(ItemOrResult::Result(result));
        }

        self.inner.frame_init(frame_input)
    }

    #[inline]
    fn frame_run(
        &mut self,
    ) -> Result<
        ItemOrResult<FrameInit, FrameResult>,
        revm::handler::evm::ContextDbError<Self::Context>,
    > {
        self.inner.frame_run()
    }

    #[inline]
    fn frame_return_result(
        &mut self,
        mut result: FrameResult,
    ) -> Result<Option<FrameResult>, revm::handler::evm::ContextDbError<Self::Context>> {
        let pre_ctx = self.inner.precompiles.ctx.clone();
        pre_ctx.pop_caller();

        if let Some(Some(addr)) = self.actor_stack.pop() {
            pre_ctx.pop_stylus_program(addr);
        }

        // EIP-3541: reject runtime starting with 0xEF unless it's the Stylus
        // marker (0xEF 0xF0 0x00). revm's global check is disabled so Stylus
        // can deploy; we re-apply it here with the Stylus exception.
        if let FrameResult::Create(ref mut outcome) = result {
            let create_ctx = self.create_ctx_stack.pop();
            if outcome.instruction_result().is_ok()
                && let Some(addr) = outcome.address
            {
                let code_bytes: Vec<u8> = self
                    .inner
                    .ctx
                    .journal_mut()
                    .code(addr)
                    .map(|c| c.data.to_vec())
                    .unwrap_or_default();
                let starts_with_ef = code_bytes.first() == Some(&0xEF);
                let is_stylus =
                    arb_stylus::is_stylus_component(&code_bytes, pre_ctx.block.arbos_version);
                if starts_with_ef && !is_stylus {
                    if let Some(create_ctx) = create_ctx {
                        self.inner
                            .ctx
                            .journal_mut()
                            .checkpoint_revert(create_ctx.checkpoint);
                        use revm::context_interface::journaled_state::account::JournaledAccountTr;
                        if let Ok(mut caller_acc) = self
                            .inner
                            .ctx
                            .journal_mut()
                            .load_account_mut(create_ctx.caller)
                        {
                            let _ = caller_acc.data.bump_nonce();
                        }
                    }
                    outcome.address = None;
                    outcome.result.result = InstructionResult::CreateContractStartingWithEF;
                    outcome.result.output = Bytes::new();
                    outcome.result.gas.spend_all();
                }
            }
        }
        self.inner.frame_return_result(result)
    }
}

// ── ExecuteEvm for ArbEvm ────────────────────────────────────────

impl<DB, I> ExecuteEvm for ArbEvm<DB, I>
where
    DB: Database,
    I: Inspector<EthEvmContext<DB>, EthInterpreter>,
{
    type ExecutionResult = ExecutionResult<HaltReason>;
    type State = revm::state::EvmState;
    type Error = EVMError<<DB as revm::Database>::Error, InvalidTransaction>;
    type Tx = revm::context::TxEnv;
    type Block = revm::context::BlockEnv;

    #[inline]
    fn transact_one(&mut self, tx: Self::Tx) -> Result<Self::ExecutionResult, Self::Error> {
        self.inner.ctx.set_tx(tx);
        MainnetHandler::default().run(self)
    }

    #[inline]
    fn finalize(&mut self) -> Self::State {
        self.inner.ctx.journal_mut().finalize()
    }

    #[inline]
    fn set_block(&mut self, block: Self::Block) {
        self.inner.ctx.set_block(block);
    }

    #[inline]
    fn replay(&mut self) -> Result<ResultAndState<HaltReason>, Self::Error> {
        MainnetHandler::default().run(self).map(|result| {
            let state = self.finalize();
            ResultAndState::new(result, state)
        })
    }
}

// ── SystemCallEvm for ArbEvm ─────────────────────────────────────

impl<DB, I> SystemCallEvm for ArbEvm<DB, I>
where
    DB: Database,
    I: Inspector<EthEvmContext<DB>, EthInterpreter>,
{
    fn system_call_one_with_caller(
        &mut self,
        caller: Address,
        system_contract_address: Address,
        data: Bytes,
    ) -> Result<Self::ExecutionResult, Self::Error> {
        use revm::handler::system_call::SystemCallTx;
        self.inner
            .ctx
            .set_tx(revm::context::TxEnv::new_system_tx_with_caller(
                caller,
                system_contract_address,
                data,
            ));
        MainnetHandler::default().run_system_call(self)
    }
}

// ── InspectorEvmTr for ArbEvm ────────────────────────────────────

impl<DB, I> revm::inspector::InspectorEvmTr for ArbEvm<DB, I>
where
    DB: Database,
    I: Inspector<EthEvmContext<DB>, EthInterpreter>,
    revm::Journal<DB>: revm::inspector::JournalExt,
{
    type Inspector = I;

    fn all_inspector(
        &self,
    ) -> (
        &Self::Context,
        &Self::Instructions,
        &Self::Precompiles,
        &FrameStack<Self::Frame>,
        &Self::Inspector,
    ) {
        let (ctx, inst, pre, fs) = self.inner.all();
        (ctx, inst, pre, fs, &self.inner.inspector)
    }

    fn all_mut_inspector(
        &mut self,
    ) -> (
        &mut Self::Context,
        &mut Self::Instructions,
        &mut Self::Precompiles,
        &mut FrameStack<Self::Frame>,
        &mut Self::Inspector,
    ) {
        (
            &mut self.inner.ctx,
            &mut self.inner.instruction,
            &mut self.inner.precompiles,
            &mut self.inner.frame_stack,
            &mut self.inner.inspector,
        )
    }
}

// ── InspectEvm for ArbEvm ────────────────────────────────────────

impl<DB, I> InspectEvm for ArbEvm<DB, I>
where
    DB: Database,
    I: Inspector<EthEvmContext<DB>, EthInterpreter>,
    revm::Journal<DB>: revm::inspector::JournalExt,
{
    type Inspector = I;

    fn set_inspector(&mut self, inspector: Self::Inspector) {
        self.inner.inspector = inspector;
    }

    fn inspect_one_tx(&mut self, tx: Self::Tx) -> Result<Self::ExecutionResult, Self::Error> {
        self.inner.ctx.set_tx(tx);
        MainnetHandler::default().inspect_run(self)
    }
}

// ── alloy_evm::Evm for ArbEvm ───────────────────────────────────

impl<DB, I> Evm for ArbEvm<DB, I>
where
    DB: Database,
    I: Inspector<EthEvmContext<DB>, EthInterpreter>,
    revm::Journal<DB>: revm::inspector::JournalExt,
{
    type DB = DB;
    type Tx = ArbTransaction;
    type Error = EVMError<<DB as revm::Database>::Error>;
    type HaltReason = HaltReason;
    type Spec = SpecId;
    type Precompiles = PrecompilesMap;
    type Inspector = I;
    type BlockEnv = revm::context::BlockEnv;

    fn block(&self) -> &revm::context::BlockEnv {
        &self.inner.ctx.block
    }

    fn chain_id(&self) -> u64 {
        self.inner.ctx.cfg.chain_id
    }

    fn transact_raw(
        &mut self,
        tx: Self::Tx,
    ) -> Result<ResultAndState<Self::HaltReason>, Self::Error> {
        if self.inspect {
            InspectEvm::inspect_tx(self, tx.into_inner())
        } else {
            ExecuteEvm::transact(self, tx.into_inner())
        }
    }

    fn transact_system_call(
        &mut self,
        caller: Address,
        contract: Address,
        data: Bytes,
    ) -> Result<ResultAndState<Self::HaltReason>, Self::Error> {
        SystemCallEvm::system_call_with_caller(self, caller, contract, data)
    }

    fn finish(self) -> (Self::DB, EvmEnv<Self::Spec>) {
        let revm::Context {
            block: block_env,
            cfg: cfg_env,
            journaled_state,
            ..
        } = self.inner.ctx;
        (journaled_state.database, EvmEnv { block_env, cfg_env })
    }

    fn set_inspector_enabled(&mut self, enabled: bool) {
        self.inspect = enabled;
    }

    fn components(&self) -> (&Self::DB, &Self::Inspector, &Self::Precompiles) {
        (
            &self.inner.ctx.journaled_state.database,
            &self.inner.inspector,
            &self.inner.precompiles.inner,
        )
    }

    fn components_mut(&mut self) -> (&mut Self::DB, &mut Self::Inspector, &mut Self::Precompiles) {
        (
            &mut self.inner.ctx.journaled_state.database,
            &mut self.inner.inspector,
            &mut self.inner.precompiles.inner,
        )
    }
}

// ── ArbEvmFactory ──────────────────────────────────────────────────

/// Factory for creating Arbitrum EVM instances with custom precompiles.
///
/// `staged_ctx` is the bridge that lets [`evm_env`](crate::config) on one
/// thread hand a freshly-built [`ArbPrecompileCtx`] to [`create_evm`] on
/// another (reth's RPC dispatcher uses `spawn_blocking`). The executor
/// path writes through the same slot before each block.
#[derive(Default, Debug)]
pub struct ArbEvmFactory {
    pub inner: alloy_evm::EthEvmFactory,
    staged_ctx:
        std::sync::Arc<parking_lot::RwLock<Option<std::sync::Arc<arb_context::ArbPrecompileCtx>>>>,
    chain_caches: std::sync::Arc<arb_context::ChainCaches>,
    /// When set, each clone gets its own staging slot and chain caches.
    /// Parallel offline executors need that isolation (the caches window-evict,
    /// so sharing them across workers clobbers each other); the live path
    /// shares both across clones for the cross-thread RPC handoff.
    isolate_staging_on_clone: bool,
}

impl Clone for ArbEvmFactory {
    fn clone(&self) -> Self {
        let isolate = self.isolate_staging_on_clone;
        Self {
            inner: self.inner,
            staged_ctx: if isolate {
                std::sync::Arc::default()
            } else {
                self.staged_ctx.clone()
            },
            chain_caches: if isolate {
                std::sync::Arc::default()
            } else {
                self.chain_caches.clone()
            },
            isolate_staging_on_clone: isolate,
        }
    }
}

impl ArbEvmFactory {
    pub fn new() -> Self {
        Self::default()
    }

    /// Factory whose clones each receive an independent staging slot, for
    /// parallel offline block execution (`re-execute`/`import`/`stage`).
    pub fn isolated() -> Self {
        Self {
            isolate_staging_on_clone: true,
            ..Self::default()
        }
    }

    /// Stage the per-block context that `create_evm` will install on the
    /// EVM-execution thread.
    pub fn stage_ctx(&self, ctx: std::sync::Arc<arb_context::ArbPrecompileCtx>) {
        *self.staged_ctx.write() = Some(ctx);
    }

    pub fn chain_caches(&self) -> &std::sync::Arc<arb_context::ChainCaches> {
        &self.chain_caches
    }

    fn staged(&self) -> Option<std::sync::Arc<arb_context::ArbPrecompileCtx>> {
        self.staged_ctx.read().clone()
    }
}

fn build_arb_evm<DB: Database, I>(
    inner: RevmEvm<
        EthEvmContext<DB>,
        I,
        EthInstructions<EthInterpreter, EthEvmContext<DB>>,
        PrecompilesMap,
        EthFrame,
    >,
    staged: Option<std::sync::Arc<arb_context::ArbPrecompileCtx>>,
    inspect: bool,
) -> ArbEvm<DB, I> {
    let pre_ctx =
        staged.unwrap_or_else(|| std::sync::Arc::new(arb_context::ArbPrecompileCtx::default()));
    let RevmEvm {
        ctx: evm_ctx,
        inspector,
        mut instruction,
        mut precompiles,
        frame_stack: _,
    } = inner;

    instruction.insert_instruction(
        BLOBBASEFEE_OPCODE,
        revm::interpreter::Instruction::new(arb_blob_basefee, 2),
    );
    instruction.insert_instruction(
        SELFDESTRUCT_OPCODE,
        revm::interpreter::Instruction::new(arb_selfdestruct, 5000),
    );
    instruction.insert_instruction(
        NUMBER_OPCODE,
        revm::interpreter::Instruction::new(arb_number, 2),
    );
    instruction.insert_instruction(
        BLOCKHASH_OPCODE,
        revm::interpreter::Instruction::new(arb_blockhash, 20),
    );
    instruction.insert_instruction(
        BALANCE_OPCODE,
        revm::interpreter::Instruction::new(arb_balance, 0),
    );
    instruction.insert_instruction(
        SELFBALANCE_OPCODE,
        revm::interpreter::Instruction::new(arb_selfbalance, 5),
    );
    register_arb_precompiles(&mut precompiles, pre_ctx.clone());
    let arb_precompiles = ArbPrecompilesMap::new(precompiles, pre_ctx);

    let revm_evm = RevmEvm::new_with_inspector(evm_ctx, inspector, instruction, arb_precompiles);
    ArbEvm::new(revm_evm, inspect)
}

impl EvmFactory for ArbEvmFactory {
    type Evm<DB: Database, I: Inspector<EthEvmContext<DB>, EthInterpreter>> = ArbEvm<DB, I>;
    type Context<DB: Database> = EthEvmContext<DB>;
    type Tx = ArbTransaction;
    type Error<DBError: core::error::Error + Send + Sync + 'static> = EVMError<DBError>;
    type HaltReason = HaltReason;
    type Spec = SpecId;
    type Precompiles = PrecompilesMap;
    type BlockEnv = revm::context::BlockEnv;

    fn create_evm<DB: Database>(
        &self,
        db: DB,
        input: EvmEnv<Self::Spec>,
    ) -> Self::Evm<DB, NoOpInspector> {
        let eth_evm = self.inner.create_evm(db, input);
        build_arb_evm(eth_evm.into_inner(), self.staged(), false)
    }

    fn create_evm_with_inspector<DB: Database, I: Inspector<Self::Context<DB>, EthInterpreter>>(
        &self,
        db: DB,
        input: EvmEnv<Self::Spec>,
        inspector: I,
    ) -> Self::Evm<DB, I> {
        let eth_evm = self.inner.create_evm_with_inspector(db, input, inspector);
        build_arb_evm(eth_evm.into_inner(), self.staged(), true)
    }
}

#[cfg(test)]
mod tests {
    use std::sync::Arc;

    use super::ArbEvmFactory;

    #[test]
    fn isolated_clone_has_independent_staging_and_caches() {
        let factory = ArbEvmFactory::isolated();
        let clone = factory.clone();
        factory.stage_ctx(Arc::new(arb_context::ArbPrecompileCtx::default()));
        assert!(factory.staged().is_some());
        assert!(clone.staged().is_none());
        assert!(!Arc::ptr_eq(factory.chain_caches(), clone.chain_caches()));
    }

    #[test]
    fn default_clone_shares_staging_and_caches() {
        let factory = ArbEvmFactory::new();
        let clone = factory.clone();
        factory.stage_ctx(Arc::new(arb_context::ArbPrecompileCtx::default()));
        assert!(clone.staged().is_some());
        assert!(Arc::ptr_eq(factory.chain_caches(), clone.chain_caches()));
    }
}