foundry_evm/inspectors/

stack.rs

use super::{
    Cheatcodes, CheatsConfig, ChiselState, CmpOperands, CustomPrintTracer, EdgeCovConfig,
    EdgeCovInspector, EdgeCoverage, Fuzzer, LineCoverageCollector, LogCollector, RevertDiagnostic,
    ScriptExecutionInspector, TempoLabels, TracingInspector,
};
use alloy_primitives::{
    Address, B256, Bytes, Log, TxKind, U256, keccak256,
    map::{AddressHashMap, AddressHashSet, AddressMap},
};

use foundry_cheatcodes::{CheatcodeAnalysis, CheatcodesExecutor, NestedEvmClosureFor, Wallets};
use foundry_common::{compile::Analysis, sh_warn};
use foundry_config::FuzzCorpusConfig;
use foundry_evm_core::{
    FoundryBlock, FoundryTransaction, InspectorExt,
    backend::{ContextUpdateFor, DatabaseError, DatabaseExt, JournaledState},
    constants::DEFAULT_CREATE2_DEPLOYER_CODEHASH,
    env::FoundryContextExt,
    evm::{
        BlockEnvFor, ChainFor, EthEvmNetwork, EvmEnvFor, EvmFactoryFor, FoundryContextFor,
        FoundryEvmFactory, FoundryEvmNetwork, TxEnvFor, get_create2_factory_call_inputs,
        merge_child_state, prepare_child_state, with_inherited_evm,
    },
    precompiles::P256_VERIFY,
};
use foundry_evm_coverage::HitMaps;
use foundry_evm_networks::{NetworkConfigs, arbitrum};
use foundry_evm_traces::{SparsedTraceArena, TraceRequirements};
use revm::{
    Inspector, JournalEntry,
    context::{
        Block, Cfg, ContextTr, JournalTr, Transaction, TransactionType,
        result::{EVMError, ExecutionResult, Output},
    },
    context_interface::{CreateScheme, journaled_state::JournalCheckpoint},
    handler::FrameResult,
    interpreter::{
        CallInputs, CallOutcome, CallScheme, CreateInputs, CreateOutcome, FrameInput, Gas,
        InstructionResult, Interpreter, InterpreterResult,
        bytecode::opcode as op,
        interpreter_types::{InputsTr, Jumps},
        return_ok,
    },
    primitives::KECCAK_EMPTY,
    state::Account,
};
use std::{
    ops::{Deref, DerefMut},
    sync::Arc,
};

use crate::executors::{EarlyExit, EvmExecutionCancellation, calculate_initial_gas};

#[cfg(feature = "monad")]
use foundry_evm_core::evm::refresh_chain_journal;

#[derive(Clone, Debug)]
#[must_use = "builders do nothing unless you call `build` on them"]
pub struct InspectorStackBuilder<BLOCK: Clone> {
    /// Solar compiler instance, to grant syntactic and semantic analysis capabilities.
    pub analysis: Option<Analysis>,
    /// The block environment.
    ///
    /// Used in the cheatcode handler to overwrite the block environment separately from the
    /// execution block environment.
    pub block: Option<BLOCK>,
    /// The gas price.
    ///
    /// Used in the cheatcode handler to overwrite the gas price separately from the gas price
    /// in the execution environment.
    pub gas_price: Option<u128>,
    /// The cheatcodes config.
    pub cheatcodes: Option<Arc<CheatsConfig>>,
    /// The fuzzer inspector and its state, if it exists.
    pub fuzzer: Option<Fuzzer>,
    /// Whether to enable tracing and revert diagnostics.
    pub trace_requirements: TraceRequirements,
    /// Whether logs should be collected.
    /// - None for no log collection.
    /// - Some(true) for realtime console.log-ing.
    /// - Some(false) for log collection.
    pub logs: Option<bool>,
    /// Whether line coverage info should be collected.
    pub line_coverage: Option<bool>,
    /// Whether to print all opcode traces into the console. Useful for debugging the EVM.
    pub print: Option<bool>,
    /// The chisel state inspector.
    pub chisel_state: Option<usize>,
    /// Whether to enable call isolation.
    /// In isolation mode all top-level calls are executed as a separate transaction in a separate
    /// EVM context, enabling more precise gas accounting and transaction state changes.
    pub enable_isolation: bool,
    /// Configuration retained for Celo precompile support.
    // TODO(celo-execution-owner): Replace this residual with concrete Celo precompile
    // configuration. This is independent of the Monad lifecycle migration.
    pub networks: NetworkConfigs,
    /// Concrete Tempo label inspector selected by the Tempo executor builder.
    tempo_labels: Option<Box<TempoLabels>>,
    /// Explicitly resolved additional cheatcode addresses.
    pub extra_cheatcode_addresses: &'static [Address],
    /// The wallets to set in the cheatcodes context.
    pub wallets: Option<Wallets>,
    /// The CREATE2 deployer address.
    pub create2_deployer: Address,
}

impl<BLOCK: Clone> Default for InspectorStackBuilder<BLOCK> {
    fn default() -> Self {
        Self {
            analysis: None,
            block: None,
            gas_price: None,
            cheatcodes: None,
            fuzzer: None,
            trace_requirements: TraceRequirements::none(),
            logs: None,
            line_coverage: None,
            print: None,
            chisel_state: None,
            enable_isolation: false,
            networks: NetworkConfigs::default(),
            tempo_labels: None,
            extra_cheatcode_addresses: &[],
            wallets: None,
            create2_deployer: Default::default(),
        }
    }
}

impl<BLOCK: Clone> InspectorStackBuilder<BLOCK> {
    /// Create a new inspector stack builder.
    #[inline]
    pub fn new() -> Self {
        Self::default()
    }

    /// Set the solar compiler instance that grants syntactic and semantic analysis capabilities
    #[inline]
    pub fn set_analysis(mut self, analysis: Analysis) -> Self {
        self.analysis = Some(analysis);
        self
    }

    /// Set the block environment.
    #[inline]
    pub fn block(mut self, block: BLOCK) -> Self {
        self.block = Some(block);
        self
    }

    /// Set the gas price.
    #[inline]
    pub const fn gas_price(mut self, gas_price: u128) -> Self {
        self.gas_price = Some(gas_price);
        self
    }

    /// Enable cheatcodes with the given config.
    #[inline]
    pub fn cheatcodes(mut self, config: Arc<CheatsConfig>) -> Self {
        self.cheatcodes = Some(config);
        self
    }

    /// Set the wallets.
    #[inline]
    pub fn wallets(mut self, wallets: Wallets) -> Self {
        self.wallets = Some(wallets);
        self
    }

    /// Set the fuzzer inspector.
    #[inline]
    pub fn fuzzer(mut self, fuzzer: Fuzzer) -> Self {
        self.fuzzer = Some(fuzzer);
        self
    }

    /// Set the Chisel inspector.
    #[inline]
    pub const fn chisel_state(mut self, final_pc: usize) -> Self {
        self.chisel_state = Some(final_pc);
        self
    }

    /// Set the log collector, and whether to print the logs directly to stdout.
    #[inline]
    pub const fn logs(mut self, live_logs: bool) -> Self {
        self.logs = Some(live_logs);
        self
    }

    /// Set whether to collect line coverage information.
    #[inline]
    pub const fn line_coverage(mut self, yes: bool) -> Self {
        self.line_coverage = Some(yes);
        self
    }

    /// Set whether to enable the trace printer.
    #[inline]
    pub const fn print(mut self, yes: bool) -> Self {
        self.print = Some(yes);
        self
    }

    /// Set trace data requirements.
    #[inline]
    pub const fn trace_requirements(mut self, requirements: TraceRequirements) -> Self {
        self.trace_requirements = self.trace_requirements.merge(requirements);
        self
    }

    /// Set whether to enable the call isolation.
    /// For description of call isolation, see [`InspectorStack::enable_isolation`].
    #[inline]
    pub const fn enable_isolation(mut self, yes: bool) -> Self {
        self.enable_isolation = yes;
        self
    }

    /// Sets networks when building an inspector stack directly.
    ///
    /// [`ExecutorBuilder::build`](crate::executors::ExecutorBuilder::build) overrides this with its
    /// explicit network configuration so the executor, backend, and inspector remain in sync.
    #[inline]
    pub const fn networks(mut self, networks: NetworkConfigs) -> Self {
        self.networks = networks;
        self
    }

    /// Installs the Tempo label inspector.
    #[inline]
    pub(crate) fn tempo_labels(mut self, inspector: TempoLabels) -> Self {
        self.tempo_labels = Some(Box::new(inspector));
        self
    }

    /// Sets explicitly resolved additional cheatcode addresses.
    #[inline]
    pub const fn extra_cheatcode_addresses(mut self, addresses: &'static [Address]) -> Self {
        self.extra_cheatcode_addresses = addresses;
        self
    }

    #[inline]
    pub const fn create2_deployer(mut self, create2_deployer: Address) -> Self {
        self.create2_deployer = create2_deployer;
        self
    }

    /// Builds the stack of inspectors to use when transacting/committing on the EVM.
    pub fn build<FEN: FoundryEvmNetwork<EvmFactory: FoundryEvmFactory<BlockEnv = BLOCK>>>(
        self,
    ) -> InspectorStack<FEN> {
        let Self {
            analysis,
            block,
            gas_price,
            cheatcodes,
            fuzzer,
            trace_requirements,
            logs,
            line_coverage,
            print,
            chisel_state,
            enable_isolation,
            networks,
            tempo_labels,
            extra_cheatcode_addresses,
            wallets,
            create2_deployer,
        } = self;
        let mut stack = InspectorStack::new();
        // inspectors
        if let Some(config) = cheatcodes {
            let mut cheatcodes = Cheatcodes::new(config);
            cheatcodes.set_extra_cheatcode_addresses(extra_cheatcode_addresses);
            // Set analysis capabilities if they are provided
            if let Some(analysis) = analysis {
                stack.set_analysis(analysis.clone());
                cheatcodes.set_analysis(CheatcodeAnalysis::new(analysis));
            }
            // Set wallets if they are provided
            if let Some(wallets) = wallets {
                cheatcodes.set_wallets(wallets);
            }
            stack.set_cheatcodes(cheatcodes);
        }

        if let Some(fuzzer) = fuzzer {
            stack.set_fuzzer(fuzzer);
        }
        if let Some(chisel_state) = chisel_state {
            stack.set_chisel(chisel_state);
        }
        stack.collect_line_coverage(line_coverage.unwrap_or(false));
        stack.collect_logs(logs);
        stack.print(print.unwrap_or(false));
        stack.tracing_requirements(trace_requirements);

        stack.enable_isolation(enable_isolation);
        stack.networks(networks);
        stack.inner.tempo_labels = tempo_labels;
        stack.set_extra_cheatcode_addresses(extra_cheatcode_addresses);
        stack.set_create2_deployer(create2_deployer);

        // environment, must come after all of the inspectors
        if let Some(block) = block {
            stack.set_block(block);
        }
        if let Some(gas_price) = gas_price {
            stack.set_gas_price(gas_price);
        }

        stack
    }
}

/// Helper macro to call the same method on multiple inspectors without resorting to dynamic
/// dispatch.
#[macro_export]
macro_rules! call_inspectors {
    ([$($inspector:expr),+ $(,)?], |$id:ident $(,)?| $body:expr $(,)?) => {
        $(
            if let Some($id) = $inspector {
                $crate::utils::cold_path();
                $body;
            }
        )+
    };
    (#[ret] [$($inspector:expr),+ $(,)?], |$id:ident $(,)?| $body:expr $(,)?) => {{
        $(
            if let Some($id) = $inspector {
                $crate::utils::cold_path();
                if let Some(result) = $body {
                    return result;
                }
            }
        )+
    }};
}

/// The collected results of [`InspectorStack`].
pub struct InspectorData<FEN: FoundryEvmNetwork> {
    pub logs: Vec<Log>,
    pub labels: AddressHashMap<String>,
    pub traces: Option<SparsedTraceArena>,
    pub line_coverage: Option<HitMaps>,
    pub edge_coverage: Option<EdgeCoverage>,
    pub evm_cmp_values: Option<Vec<CmpOperands>>,
    pub cheatcodes: Option<Box<Cheatcodes<FEN>>>,
    pub chisel_state: Option<(Vec<U256>, Vec<u8>)>,
    pub reverter: Option<Address>,
}

/// Contains data about the state of outer/main EVM which created and invoked the inner EVM context.
/// Used to adjust EVM state while in inner context.
///
/// We need this to avoid breaking changes due to EVM behavior differences in isolated vs
/// non-isolated mode. For descriptions and workarounds for those changes see: <https://github.com/foundry-rs/foundry/pull/7186#issuecomment-1959102195>
#[derive(Debug, Clone)]
pub struct InnerContextData {
    /// Origin of the transaction in the outer EVM context.
    original_origin: Address,
    /// Accounts that were created locally before entering the nested EVM context.
    locally_created_accounts: AddressHashSet,
    /// Depth of the isolated root frame in the surrounding trace.
    root_depth: usize,
}

/// Gas accounting carried across an isolated frame's synthetic transaction boundary.
struct IsolatedGas {
    /// Regular execution gas available to the isolated frame.
    regular_limit: u64,
    /// State gas reservoir available to the isolated frame.
    reservoir: u64,
    /// State gas already charged by the outer opcode.
    precharged_state: Option<u64>,
}

#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
enum OpcodeStepDispatch {
    #[default]
    None,
    FuzzerOnly,
    General,
}

/// An inspector that calls multiple inspectors in sequence.
///
/// If a call to an inspector returns a value (indicating a stop or revert) the remaining inspectors
/// are not called.
///
/// Stack is divided into [Cheatcodes] and `InspectorStackInner`. This is done to allow assembling
/// `InspectorStackRefMut` inside [Cheatcodes] to allow usage of it as [revm::Inspector]. This gives
/// us ability to create and execute separate EVM frames from inside cheatcodes while still having
/// access to entire stack of inspectors and correctly handling traces, logs, debugging info
/// collection, etc.
#[derive(Clone, Debug)]
pub struct InspectorStack<FEN: FoundryEvmNetwork = EthEvmNetwork> {
    #[allow(clippy::type_complexity)]
    pub cheatcodes: Option<Box<Cheatcodes<FEN>>>,
    pub inner: InspectorStackInner,
}

#[cfg(test)]
#[derive(Clone, Debug)]
struct EarlyExitTestGate {
    entered: std::sync::mpsc::Sender<()>,
    release: Arc<std::sync::Mutex<std::sync::mpsc::Receiver<()>>>,
    target_pc: usize,
    notified: Arc<std::sync::atomic::AtomicBool>,
}

#[derive(Clone, Copy, Debug)]
struct PendingCreate2Redirect {
    depth: usize,
    charged_create_state_gas: bool,
}

#[derive(Clone, Copy, Debug)]
struct PendingCallTrace {
    trace_idx: usize,
    executed_address: Option<Address>,
}

#[derive(Clone, Copy, Debug)]
struct IsolatedFrameCheckpoint {
    checkpoint: JournalCheckpoint,
    restore_len: usize,
    return_depth: usize,
    is_create: bool,
    failed: bool,
}

/// All used inspectors besides [Cheatcodes].
///
/// See [`InspectorStack`].
#[derive(Default, Clone, Debug)]
pub struct InspectorStackInner {
    /// Solar compiler instance, to grant syntactic and semantic analysis capabilities.
    pub analysis: Option<Analysis>,

    // Inspectors.
    // These are boxed to reduce the size of the struct and slightly improve performance of the
    // `if let Some` checks.
    pub chisel_state: Option<Box<ChiselState>>,
    pub edge_coverage: Option<Box<EdgeCovInspector>>,
    pub fuzzer: Option<Box<Fuzzer>>,
    pub line_coverage: Option<Box<LineCoverageCollector>>,
    pub log_collector: Option<Box<LogCollector>>,
    pub printer: Option<Box<CustomPrintTracer>>,
    pub revert_diag: Option<Box<RevertDiagnostic>>,
    pub script_execution_inspector: Option<Box<ScriptExecutionInspector>>,
    pub tempo_labels: Option<Box<TempoLabels>>,
    pub tracer: Option<Box<TracingInspector>>,

    // FoundryInspectorExt and other internal data.
    /// Whether to collect sancov edge coverage from instrumented native crates.
    pub sancov_edges: bool,
    /// Whether to capture sancov trace-cmp operands for dictionary injection.
    pub sancov_trace_cmp: bool,
    pub enable_isolation: bool,
    pub networks: NetworkConfigs,
    /// Additional addresses installed and recognized as cheatcode contracts.
    pub extra_cheatcode_addresses: &'static [Address],
    pub create2_deployer: Address,
    /// Flag marking if we are in the inner EVM context.
    pub in_inner_context: bool,
    pub inner_context_data: Option<InnerContextData>,
    /// Accounts that should retain the per-transaction creation marker in the current context.
    pub locally_created_accounts: AddressHashSet,
    pub top_frame_journal: AddressMap<Account>,
    /// Whether the top-level frame failed before inspector result rewriting.
    top_level_frame_failed_before_rewrite: bool,
    /// Fee policy to restore when an isolated call explicitly executes another transaction.
    outer_disable_fee_charge: Option<bool>,
    /// Whether the root call of the active isolated transaction executed as a precompile.
    isolated_call_was_precompile: Option<bool>,
    /// Synthetic CREATE depth corresponding to an outer top-level deployment.
    synthetic_create_depth: Option<usize>,
    /// Address that reverted the call, if any.
    pub reverter: Option<Address>,
    /// LIFO stack tracking CREATE2 frames that were redirected to the CREATE2 factory.
    pending_create2_redirects: Vec<PendingCreate2Redirect>,
    /// LIFO stack tracking the effective address of traced calls delegated to the EVM provider.
    pending_call_traces: Vec<PendingCallTrace>,
    /// LIFO stack used to unwind snapshot restoration across reverted frames of the tracked
    /// transaction: an isolated call, or the top-level transaction when isolation is disabled.
    isolated_frame_checkpoints: Vec<IsolatedFrameCheckpoint>,
    /// Pending CREATE2 deployer validation error, deferred from `frame_start` to `create` so
    /// it goes through the normal inspector lifecycle (tracing, etc.).
    pub pending_create2_error: Option<CreateOutcome>,
    /// Counter for CREATE2 salt in `--batch` CREATE rewrites.
    pub batch_create_counter: u64,
    /// Whether the one-shot `--batch` rewrite warning has already been emitted.
    pub batch_rewrite_warned: bool,
    /// Per-inspector random seed mixed into `--batch` CREATE2 salts, ensuring re-runs
    /// at identical on-chain state still produce distinct salts. Lazily initialized.
    pub batch_rewrite_process_salt: Option<u64>,
    /// Shared cancellation state for interruptible EVM execution.
    execution_cancellation: Option<EvmExecutionCancellation>,
    /// Amortizes deadline checks in the opcode hot path.
    cancellation_poll_counter: u8,
    /// Whether this inspector halted the current execution due to cancellation.
    execution_cancelled: bool,
    #[cfg(test)]
    early_exit_test_gate: Option<EarlyExitTestGate>,
    static_step_dispatch: OpcodeStepDispatch,
    has_static_step_end_inspectors: bool,
}

/// Struct keeping mutable references to both parts of [InspectorStack] and implementing
/// [revm::Inspector]. This struct can be obtained via [InspectorStack::as_mut].
pub struct InspectorStackRefMut<'a, FEN: FoundryEvmNetwork = EthEvmNetwork> {
    pub cheatcodes: Option<&'a mut Cheatcodes<FEN>>,
    pub inner: &'a mut InspectorStackInner,
}

impl<FEN: FoundryEvmNetwork> CheatcodesExecutor<FEN> for InspectorStackInner {
    fn with_nested_evm(
        &mut self,
        cheats: &mut Cheatcodes<FEN>,
        ecx: &mut FoundryContextFor<'_, FEN>,
        f: NestedEvmClosureFor<'_, FEN>,
    ) -> Result<(), EVMError<DatabaseError>> {
        let previous = self.synthetic_create_depth;
        let create2_redirects = self.pending_create2_redirects.len();
        let snapshot_checkpoints = self.isolated_frame_checkpoints.len();
        let snapshot_restores = cheats.isolated_snapshot_restores.len();
        let pending_snapshot_journal = cheats
            .track_isolated_snapshots
            .then(|| cheats.pending_isolated_snapshot_journal.clone());
        let capture_snapshot_restore = cheats.capture_isolated_snapshot_restore;
        self.synthetic_create_depth = (ecx.journal().depth() == 1).then_some(2);
        let mut inspector = InspectorStackRefMut { cheatcodes: Some(cheats), inner: self };
        let result = with_inherited_evm::<FEN::EvmFactory, _>(ecx, &mut inspector, f);
        self.synthetic_create_depth = previous;
        // Drop redirects left behind if nested execution aborted before their frames ended.
        self.pending_create2_redirects.truncate(create2_redirects);
        if result.is_err()
            && let Some(pending_snapshot_journal) = pending_snapshot_journal
        {
            self.isolated_frame_checkpoints.truncate(snapshot_checkpoints);
            cheats.isolated_snapshot_restores.truncate(snapshot_restores);
            cheats.pending_isolated_snapshot_journal = pending_snapshot_journal;
            cheats.capture_isolated_snapshot_restore = capture_snapshot_restore;
        }
        result
    }

    fn with_fresh_nested_evm(
        &mut self,
        cheats: &mut Cheatcodes<FEN>,
        ecx: &mut FoundryContextFor<'_, FEN>,
        chain_context: ChainFor<FEN>,
        f: NestedEvmClosureFor<'_, FEN>,
    ) -> Result<EvmEnvFor<FEN>, EVMError<DatabaseError>> {
        self.with_snapshot_tracking(cheats, |inner, cheats| {
            let depth = ecx.journal().depth();
            let previous_inner_context = inner.in_inner_context;
            let previous_inner_context_data = inner.inner_context_data.replace(InnerContextData {
                original_origin: ecx.tx().caller(),
                locally_created_accounts: AddressHashSet::default(),
                root_depth: depth,
            });
            let previous_precompile = inner.isolated_call_was_precompile.take();
            inner.in_inner_context = true;
            let mut evm_env = ecx.evm_clone();
            let (db, _) = ecx.db_journal_inner_mut();
            let inherited_disable_fee_charge = evm_env.cfg_env.disable_fee_charge;
            if let Some(disable_fee_charge) = inner.outer_disable_fee_charge {
                evm_env.cfg_env.disable_fee_charge = disable_fee_charge;
            }
            let mut inspector = InspectorStackRefMut { cheatcodes: Some(cheats), inner };
            let mut evm = FEN::EvmFactory::default().create_nested_evm_with_inspector(
                db,
                evm_env,
                &mut inspector,
            );
            *evm.chain_mut() = chain_context;
            // The fresh root duplicates the suspended frame; its children share the existing
            // tracer.
            evm.journal_inner_mut().depth = depth;
            let result = f(&mut *evm).map(|()| {
                let mut evm_env = evm.to_evm_env();
                evm_env.cfg_env.disable_fee_charge = inherited_disable_fee_charge;
                evm_env
            });
            drop(evm);
            inner.in_inner_context = previous_inner_context;
            inner.inner_context_data = previous_inner_context_data;
            inner.isolated_call_was_precompile = previous_precompile;
            result
        })
    }

    fn transact_on_db(
        &mut self,
        cheats: &mut Cheatcodes<FEN>,
        ecx: &mut FoundryContextFor<'_, FEN>,
        fork_id: Option<U256>,
        transaction: B256,
    ) -> eyre::Result<ContextUpdateFor<EvmFactoryFor<FEN>>> {
        self.with_snapshot_tracking(cheats, |inner, cheats| {
            let mut evm_env = ecx.evm_clone();
            if let Some(disable_fee_charge) = inner.outer_disable_fee_charge {
                evm_env.cfg_env.disable_fee_charge = disable_fee_charge;
            }
            let outer_tx_env = ecx.tx_clone();
            let mut inspector = InspectorStackRefMut { cheatcodes: Some(cheats), inner };
            let (db, inner) = ecx.db_journal_inner_mut();
            db.transact(fork_id, transaction, evm_env, &outer_tx_env, inner, &mut inspector)
        })
    }

    fn transact_from_tx_on_db(
        &mut self,
        cheats: &mut Cheatcodes<FEN>,
        ecx: &mut FoundryContextFor<'_, FEN>,
        tx_env: TxEnvFor<FEN>,
    ) -> eyre::Result<()> {
        self.with_snapshot_tracking(cheats, |inner, cheats| {
            let mut evm_env = ecx.evm_clone();
            if let Some(disable_fee_charge) = inner.outer_disable_fee_charge {
                evm_env.cfg_env.disable_fee_charge = disable_fee_charge;
            }
            let mut inspector = InspectorStackRefMut { cheatcodes: Some(cheats), inner };
            let (db, inner) = ecx.db_journal_inner_mut();
            db.transact_from_tx(tx_env, evm_env, inner, &mut inspector)
        })
    }

    fn console_log(&mut self, msg: &str) {
        if let Some(ref mut collector) = self.log_collector {
            InspectorExt::console_log(&mut **collector, msg);
        }
    }

    fn tracing_inspector(&mut self) -> Option<&mut TracingInspector> {
        self.tracer.as_deref_mut()
    }
}

impl<FEN: FoundryEvmNetwork> Default for InspectorStack<FEN> {
    fn default() -> Self {
        Self::new()
    }
}

impl<FEN: FoundryEvmNetwork> InspectorStack<FEN> {
    /// Creates a new inspector stack.
    ///
    /// Note that the stack is empty by default, and you must add inspectors to it.
    /// This is done by calling the `set_*` methods on the stack directly, or by building the stack
    /// with [`InspectorStack`].
    #[inline]
    pub fn new() -> Self {
        Self { cheatcodes: None, inner: InspectorStackInner::default() }
    }

    /// Set the solar compiler instance.
    #[inline]
    pub fn set_analysis(&mut self, analysis: Analysis) {
        self.analysis = Some(analysis);
    }

    /// Set the cancellation state checked during EVM execution.
    #[inline]
    pub(crate) fn set_early_exit(&mut self, early_exit: EarlyExit) {
        self.set_execution_cancellation(EvmExecutionCancellation::early_exit(early_exit));
    }

    /// Set the complete cancellation state checked during EVM execution.
    #[inline]
    pub(crate) fn set_execution_cancellation(&mut self, cancellation: EvmExecutionCancellation) {
        self.execution_cancellation = Some(cancellation);
    }

    /// Returns whether this inspector halted execution due to cancellation.
    #[inline]
    pub(crate) const fn execution_cancelled(&self) -> bool {
        self.inner.execution_cancelled
    }

    #[cfg(test)]
    pub(crate) fn set_early_exit_test_gate(
        &mut self,
        entered: std::sync::mpsc::Sender<()>,
        release: std::sync::mpsc::Receiver<()>,
        target_pc: usize,
    ) {
        self.early_exit_test_gate = Some(EarlyExitTestGate {
            entered,
            release: Arc::new(std::sync::Mutex::new(release)),
            target_pc,
            notified: Arc::new(std::sync::atomic::AtomicBool::new(false)),
        });
    }

    /// Sets the block for the relevant inspectors.
    #[inline]
    pub fn set_block(&mut self, block: BlockEnvFor<FEN>) {
        if let Some(cheatcodes) = &mut self.cheatcodes {
            cheatcodes.block = Some(block);
        }
    }

    /// Sets the gas price for the relevant inspectors.
    #[inline]
    pub fn set_gas_price(&mut self, gas_price: u128) {
        if let Some(cheatcodes) = &mut self.cheatcodes {
            cheatcodes.gas_price = Some(gas_price);
        }
    }

    /// Set the cheatcodes inspector.
    #[inline]
    pub fn set_cheatcodes(&mut self, cheatcodes: Cheatcodes<FEN>) {
        self.cheatcodes = Some(cheatcodes.into());
    }

    /// Set the fuzzer inspector.
    #[inline]
    pub fn set_fuzzer(&mut self, fuzzer: Fuzzer) {
        self.fuzzer = Some(fuzzer.into());
        self.refresh_static_step_dispatch();
    }

    /// Set the Chisel inspector.
    #[inline]
    pub fn set_chisel(&mut self, final_pc: usize) {
        self.chisel_state = Some(ChiselState::new(final_pc).into());
        self.refresh_static_step_end_dispatch();
    }

    /// Set whether to enable the line coverage collector.
    #[inline]
    pub fn collect_line_coverage(&mut self, yes: bool) {
        self.line_coverage = yes.then(Default::default);
        self.refresh_static_step_dispatch();
    }

    /// Set whether to enable the edge coverage collector with default config.
    #[inline]
    pub fn collect_edge_coverage(&mut self, yes: bool) {
        self.edge_coverage = yes.then(|| EdgeCovInspector::default().into());
        self.refresh_static_step_dispatch();
    }

    /// Enable edge coverage with an explicit configuration.
    #[inline]
    pub fn collect_edge_coverage_with_edge_config(&mut self, config: EdgeCovConfig) {
        self.edge_coverage = Some(EdgeCovInspector::with_config(config).into());
        self.refresh_static_step_dispatch();
    }

    /// Configure the edge coverage collector from a [`FuzzCorpusConfig`].
    ///
    /// Derives both the on/off gate and [`EdgeCovConfig`] from `corpus`.
    #[inline]
    pub fn collect_edge_coverage_with_config(&mut self, corpus: &FuzzCorpusConfig) {
        self.edge_coverage = corpus
            .collect_evm_edge_coverage()
            .then(|| EdgeCovInspector::with_config(corpus.into()).into());
        self.refresh_static_step_dispatch();
    }

    /// Set whether to collect EVM comparison operands.
    #[inline]
    pub fn collect_evm_cmp_log(&mut self, yes: bool) {
        if yes {
            self.edge_coverage
                .get_or_insert_with(|| EdgeCovInspector::with_cmp_log_only().into())
                .enable_cmp_log(true);
        } else if let Some(edge_coverage) = &mut self.edge_coverage {
            edge_coverage.enable_cmp_log(false);
        }
        self.refresh_static_step_dispatch();
    }

    /// Set whether to collect sancov edge coverage from instrumented native crates.
    #[inline]
    pub const fn collect_sancov_edges(&mut self, yes: bool) {
        self.inner.sancov_edges = yes;
    }

    /// Set whether to capture sancov trace-cmp operands for dictionary injection.
    #[inline]
    pub const fn collect_sancov_trace_cmp(&mut self, yes: bool) {
        self.inner.sancov_trace_cmp = yes;
    }

    /// Set whether to enable call isolation.
    #[inline]
    pub const fn enable_isolation(&mut self, yes: bool) {
        self.inner.enable_isolation = yes;
    }

    /// Set networks with enabled features.
    #[inline]
    pub const fn networks(&mut self, networks: NetworkConfigs) {
        self.inner.networks = networks;
    }

    /// Returns additional addresses installed and recognized as cheatcode contracts.
    #[inline]
    pub const fn extra_cheatcode_addresses(&self) -> &'static [Address] {
        self.inner.extra_cheatcode_addresses
    }

    /// Sets additional addresses installed and recognized as cheatcode contracts.
    #[inline]
    pub const fn set_extra_cheatcode_addresses(&mut self, addresses: &'static [Address]) {
        self.inner.extra_cheatcode_addresses = addresses;
    }

    /// Set the CREATE2 deployer address.
    #[inline]
    pub fn set_create2_deployer(&mut self, deployer: Address) {
        self.create2_deployer = deployer;
    }

    /// Set whether to enable the log collector.
    /// - None for no log collection.
    /// - Some(true) for realtime console.log-ing.
    /// - Some(false) for log collection.
    #[inline]
    pub fn collect_logs(&mut self, live_logs: Option<bool>) {
        self.log_collector = live_logs.map(|live_logs| {
            Box::new(if live_logs {
                LogCollector::LiveLogs
            } else {
                LogCollector::Capture { logs: Vec::new() }
            })
        });
    }

    /// Set whether to enable the trace printer.
    #[inline]
    pub fn print(&mut self, yes: bool) {
        self.printer = yes.then(Default::default);
        self.refresh_static_opcode_dispatch();
    }

    /// Set trace data requirements.
    #[inline]
    pub fn tracing_requirements(&mut self, requirements: TraceRequirements) {
        let config = requirements.into_config();
        self.revert_diag = config.is_some().then(RevertDiagnostic::default).map(Into::into);

        if let Some(config) = config {
            *self.tracer.get_or_insert_with(Default::default).config_mut() = config;
        } else {
            self.tracer = None;
        }
        self.refresh_static_opcode_dispatch();
    }

    /// Set whether to enable script execution inspector.
    #[inline]
    pub fn script(&mut self, script_address: Address) {
        self.script_execution_inspector.get_or_insert_with(Default::default).script_address =
            script_address;
        if let Some(cheatcodes) = &mut self.cheatcodes {
            cheatcodes.script_address = Some(script_address);
        }
        self.refresh_static_step_dispatch();
    }

    #[inline(always)]
    fn as_mut(&mut self) -> InspectorStackRefMut<'_, FEN> {
        InspectorStackRefMut { cheatcodes: self.cheatcodes.as_deref_mut(), inner: &mut self.inner }
    }

    /// Collects all the data gathered during inspection into a single struct.
    pub fn collect(self) -> InspectorData<FEN> {
        let Self {
            mut cheatcodes,
            inner:
                InspectorStackInner {
                    chisel_state,
                    line_coverage,
                    edge_coverage,
                    log_collector,
                    tempo_labels,
                    tracer,
                    revert_diag,
                    reverter,
                    ..
                },
        } = self;

        let trace_diagnostics =
            revert_diag.map(|revert_diag| revert_diag.into_diagnostics()).unwrap_or_default();

        let traces = tracer.map(|tracer| tracer.into_traces()).map(|arena| {
            let ignored = cheatcodes
                .as_mut()
                .map(|cheatcodes| {
                    let mut ignored = std::mem::take(&mut cheatcodes.ignored_traces.ignored);

                    // If the last pause call was not resumed, ignore the rest of the trace
                    if let Some(last_pause_call) = cheatcodes.ignored_traces.last_pause_call {
                        ignored.insert(last_pause_call, (arena.nodes().len(), 0));
                    }

                    ignored
                })
                .unwrap_or_default();

            SparsedTraceArena { arena, ignored, diagnostics: trace_diagnostics }
        });

        let (edge_coverage, evm_cmp_values) = edge_coverage
            .map(|edge_coverage| {
                let (hitcount, cmp_values) = edge_coverage.into_parts();
                (Some(hitcount), (!cmp_values.is_empty()).then_some(cmp_values))
            })
            .unwrap_or_default();

        InspectorData {
            logs: log_collector.and_then(|logs| logs.into_captured_logs()).unwrap_or_default(),
            labels: {
                let mut labels = cheatcodes.as_ref().map(|c| c.labels.clone()).unwrap_or_default();
                if let Some(tempo_labels) = tempo_labels {
                    labels.extend(tempo_labels.labels);
                }
                labels
            },
            traces,
            line_coverage: line_coverage.map(|line_coverage| line_coverage.finish()),
            edge_coverage,
            evm_cmp_values,
            cheatcodes,
            chisel_state: chisel_state.and_then(|state| state.state),
            reverter,
        }
    }
}

impl<FEN: FoundryEvmNetwork> InspectorStackRefMut<'_, FEN> {
    fn finish_create2_redirect(&mut self, depth: usize, frame_result: &mut FrameResult) {
        let Some(redirect) = self
            .inner
            .pending_create2_redirects
            .last()
            .copied()
            .filter(|redirect| redirect.depth == depth)
        else {
            return;
        };
        self.inner.pending_create2_redirects.pop();

        let FrameResult::Call(call) = frame_result else {
            debug_assert!(false, "pending CREATE2 redirect ended with non-call result");
            return;
        };

        let address = match call.instruction_result() {
            return_ok!() => Address::try_from(call.output().as_ref())
                .map_err(|_| {
                    call.result = InterpreterResult {
                        result: InstructionResult::Revert,
                        output: "invalid CREATE2 factory output".into(),
                        gas: Gas::new(call.result.gas.limit()),
                    };
                })
                .ok(),
            _ => None,
        };

        *frame_result = FrameResult::Create(CreateOutcome {
            result: call.result.clone(),
            address,
            charged_create_state_gas: redirect.charged_create_state_gas,
        });
    }

    /// Adjusts the EVM data for the inner EVM context.
    /// Should be called on the top-level call of inner context (depth == 0 &&
    /// self.in_inner_context) Decreases sender nonce for CALLs to keep backwards compatibility
    /// Updates tx.origin to the value before entering inner context
    fn adjust_evm_data_for_inner_context<CTX: FoundryContextExt>(&mut self, ecx: &mut CTX) {
        let inner_context_data =
            self.inner_context_data.as_ref().expect("should be called in inner context");
        ecx.tx_mut().set_caller(inner_context_data.original_origin);
    }

    fn do_call_end(
        &mut self,
        ecx: &mut FoundryContextFor<'_, FEN>,
        inputs: &CallInputs,
        outcome: &mut CallOutcome,
    ) {
        let storage_hook_active =
            self.cheatcodes.as_deref().is_some_and(Cheatcodes::is_storage_hook_active);
        if !storage_hook_active && let Some(fuzzer) = &mut self.fuzzer {
            fuzzer.call_end(ecx, inputs, outcome);
        }

        let result = outcome.result.result;
        call_inspectors!(
            #[ret]
            [&mut self.tracer, &mut self.cheatcodes, &mut self.printer, &mut self.revert_diag],
            |inspector| {
                let previous_output = outcome.output().clone();
                inspector.call_end(ecx, inputs, outcome);

                // If the inspector returns a different status or a revert with a non-empty message,
                // we assume it wants to tell us something
                let different = outcome.result.result != result
                    || (outcome.result.result == InstructionResult::Revert
                        && outcome.output() != &previous_output);
                different.then_some(())
            },
        );

        // Record first address that reverted the call.
        if result.is_revert() && self.reverter.is_none() {
            self.reverter = Some(inputs.transfer_to());
        }
    }

    fn do_create_end(
        &mut self,
        ecx: &mut FoundryContextFor<'_, FEN>,
        call: &CreateInputs,
        outcome: &mut CreateOutcome,
    ) {
        let result = outcome.result.result;
        call_inspectors!(
            #[ret]
            [&mut self.line_coverage, &mut self.tracer, &mut self.cheatcodes, &mut self.printer],
            |inspector| {
                let previous_output = outcome.output().clone();
                inspector.create_end(ecx, call, outcome);

                // If the inspector returns a different status or a revert with a non-empty message,
                // we assume it wants to tell us something
                let different = outcome.result.result != result
                    || (outcome.result.result == InstructionResult::Revert
                        && outcome.output() != &previous_output);
                different.then_some(())
            },
        );
    }

    fn transact_inner(
        &mut self,
        ecx: &mut FoundryContextFor<'_, FEN>,
        kind: TxKind,
        caller: Address,
        input: Bytes,
        gas: IsolatedGas,
        value: U256,
    ) -> (InterpreterResult, Option<Address>, bool) {
        let IsolatedGas { regular_limit, reservoir, precharged_state } = gas;
        let source_fork_id = ecx.db().active_fork_id();
        let cached_evm_env = ecx.evm_clone();
        let cached_tx_env = ecx.tx_clone();
        self.isolated_call_was_precompile = None;

        ecx.block_mut().set_basefee(0);
        ecx.cfg_env_mut().disable_fee_charge = true;

        let chain_id = ecx.cfg().chain_id();
        ecx.tx_mut().set_chain_id(Some(chain_id));
        ecx.tx_mut().set_caller(caller);
        ecx.tx_mut().set_kind(kind);
        ecx.tx_mut().set_data(input);
        ecx.tx_mut().set_enveloped_tx(Bytes::new());
        ecx.tx_mut().set_value(value);
        let initial_gas = calculate_initial_gas(ecx.tx(), ecx.cfg());
        // Preserve the frame's regular gas and reservoir across the synthetic transaction
        // boundary. The extra state gas offsets the account-creation charge already paid by the
        // outer opcode.
        let regular_gas_limit = regular_limit.saturating_add(initial_gas.initial_total_gas());
        ecx.cfg_env_mut().tx_gas_limit_cap = Some(regular_gas_limit);
        // revm rejects transactions whose gas limit is below the EIP-7623 calldata floor. Raising
        // the limit would give the frame more gas than it was forwarded, so skip that check and
        // apply the floor to the transaction result instead.
        let floor_gas =
            (initial_gas.floor_gas() > regular_gas_limit).then_some(initial_gas.floor_gas());
        if floor_gas.is_some() {
            ecx.cfg_env_mut().disable_eip7623 = true;
        }
        let mut tx_gas_limit = regular_gas_limit.saturating_add(reservoir);
        if let Some(precharged_state) = precharged_state {
            tx_gas_limit = tx_gas_limit.saturating_add(precharged_state);
        }
        ecx.tx_mut().set_gas_limit(tx_gas_limit);

        // If we haven't disabled gas limit checks, ensure that transaction gas limit will not
        // exceed block gas limit.
        if !ecx.cfg().is_block_gas_limit_disabled() {
            let gas_limit = std::cmp::min(ecx.tx().gas_limit(), ecx.block().gas_limit());
            ecx.tx_mut().set_gas_limit(gas_limit);
        }
        ecx.tx_mut().set_gas_price(0);
        // If the cached tx is EIP-4844 (e.g. set by `vm.blobhashes`), downgrade
        // it to EIP-1559 and drop the blob hashes so revm doesn't reject the
        // synthetic inner tx because `gas_price = 0` plus blob fields fail
        // 4844 validation. The contract-visible `BLOBHASH` opcode is restored
        // via `EnvOverrides`. Other types (incl. EIP-2930 access lists) are
        // intentionally left intact, and the full original tx is restored
        // from `cached_tx_env` after the inner call.
        if ecx.tx().tx_type() == TransactionType::Eip4844 as u8 {
            ecx.tx_mut().set_tx_type(TransactionType::Eip1559 as u8);
            ecx.tx_mut().set_blob_hashes(Vec::new());
        }

        let locally_created_accounts = ecx
            .journal()
            .evm_state()
            .iter()
            .filter_map(|(addr, acc)| acc.is_created_locally().then_some(*addr))
            .collect();
        let root_depth = ecx.journal().depth();
        self.inner_context_data = Some(InnerContextData {
            original_origin: cached_tx_env.caller(),
            locally_created_accounts,
            root_depth,
        });
        self.outer_disable_fee_charge = Some(cached_evm_env.cfg_env.disable_fee_charge);
        self.in_inner_context = true;

        // Tell cheatcodes we're entering the synthetic inner transaction so
        // env-mutating cheatcodes route through `env_overrides` instead of
        // fighting with the fee-accounting zeroing above. See `EnvOverrides`.
        if let Some(cheats) = self.cheatcodes.as_deref_mut() {
            cheats.pending_isolated_snapshot_journal = None;
            cheats.track_isolated_snapshots = true;
            cheats.isolated_snapshot_restores.clear();
            cheats.in_isolation_context = true;
        }
        self.inner.isolated_frame_checkpoints.clear();

        let evm_env = ecx.evm_clone();
        let tx_env = ecx.tx_clone();
        let factory = FEN::EvmFactory::default();
        let chain_context = ecx.chain().clone();

        let isolated_state = prepare_child_state(ecx.journal_inner());

        #[cfg(feature = "monad")]
        let state = foundry_evm_core::FoundryJournal::capture_reserve_balance(ecx.journal());
        #[cfg(feature = "monad")]
        let mut reserve_balance = None;
        let mut nested_chain_context = None;
        let res = self.with_inspector(|mut inspector| {
            let (res, nested_env) = {
                let (db, _) = ecx.db_journal_inner_mut();
                let mut evm = factory.create_nested_evm_with_inspector(db, evm_env, &mut inspector);
                *evm.chain_mut() = chain_context;
                evm.journal_inner_mut().state = isolated_state;
                #[cfg(feature = "monad")]
                {
                    foundry_evm_core::FoundryJournal::restore_reserve_balance(
                        evm.journal_mut(),
                        state,
                    );
                    foundry_evm_core::evm::refresh_nested_chain_journal(&mut *evm);
                    foundry_evm_core::FoundryJournal::set_preserve_reserve_balance(
                        evm.journal_mut(),
                        true,
                    );
                }
                // Preserve the surrounding trace depth, including a synthetic CREATE frame.
                evm.journal_inner_mut().depth = root_depth;
                let res = evm.transact_raw(tx_env);
                nested_chain_context = Some(evm.chain_mut().clone());
                #[cfg(feature = "monad")]
                {
                    reserve_balance =
                        Some(foundry_evm_core::FoundryJournal::capture_reserve_balance(
                            evm.journal_mut(),
                        ));
                }
                (res, evm.to_evm_env())
            };

            // Restore env, preserving cheatcode cfg/block changes from the nested EVM but restoring
            // the original tx and temporary fee overrides used for the nested call.
            let mut restored_evm_env = nested_env;
            restored_evm_env.block_env.set_basefee(cached_evm_env.block_env.basefee());
            restored_evm_env.cfg_env.disable_fee_charge = cached_evm_env.cfg_env.disable_fee_charge;
            restored_evm_env.cfg_env.tx_gas_limit_cap = cached_evm_env.cfg_env.tx_gas_limit_cap;
            restored_evm_env.cfg_env.disable_eip7623 = cached_evm_env.cfg_env.disable_eip7623;
            ecx.set_evm(restored_evm_env);
            ecx.set_tx(cached_tx_env);

            res
        });
        *ecx.chain_mut() = nested_chain_context.expect("nested EVM chain context was captured");

        self.in_inner_context = false;
        self.inner_context_data = None;
        self.outer_disable_fee_charge = None;

        // Reset the cheatcodes isolation flag now that the synthetic inner
        // transaction has finished.
        if let Some(cheats) = self.cheatcodes.as_deref_mut() {
            cheats.in_isolation_context = false;
            cheats.track_isolated_snapshots = false;
        }

        let mut gas = Gas::new_with_regular_gas_and_reservoir(regular_limit, reservoir);
        let was_precompile_called = self.isolated_call_was_precompile.take().unwrap_or(false);

        let Ok(res) = res else {
            if let Some(cheats) = self.cheatcodes.as_deref_mut() {
                cheats.pending_isolated_snapshot_journal = None;
                cheats.isolated_snapshot_restores.clear();
            }
            self.inner.isolated_frame_checkpoints.clear();
            #[cfg(feature = "monad")]
            foundry_evm_core::FoundryJournal::restore_reserve_balance(
                ecx.journal_mut(),
                reserve_balance.expect("isolated transaction state was captured"),
            );
            #[cfg(feature = "monad")]
            refresh_chain_journal(ecx);
            // Should we match, encode and propagate error as a revert reason?
            let result =
                InterpreterResult { result: InstructionResult::Revert, output: Bytes::new(), gas };
            return (result, None, was_precompile_called);
        };

        let mut transaction_gas = *res.result.gas();
        if let Some(floor_gas) = floor_gas {
            transaction_gas = transaction_gas.with_floor_gas(floor_gas);
        }
        let tx_state_gas_used = transaction_gas.block_state_gas_used();
        // A failed frame refunds the account-creation charge to the outer opcode, and its
        // transaction does not charge that state gas either.
        let precharged_state = precharged_state.map_or(0, |gas| gas.min(tx_state_gas_used));
        let state_gas_used = tx_state_gas_used - precharged_state;
        if let Some(cheats) = self.cheatcodes.as_deref_mut() {
            cheats
                .gas_metering
                .set_isolated_snapshot_gas_used(transaction_gas.tx_gas_used(), precharged_state);
        }
        // The transaction also pays its intrinsic gas and calldata floor, which can exceed the
        // gas forwarded to the frame. The frame then consumes its whole regular budget, as on an
        // exceptional halt.
        if !(gas.record_state_cost(state_gas_used)
            && gas.record_regular_cost(transaction_gas.block_regular_gas_used()))
        {
            gas.spend_all();
        }

        let rolled_back = !res.result.is_success();

        let restored_journal = self
            .cheatcodes
            .as_deref_mut()
            .and_then(|cheats| cheats.pending_isolated_snapshot_journal.take());
        if let Some(cheats) = self.cheatcodes.as_deref_mut() {
            cheats.isolated_snapshot_restores.clear();
        }
        self.inner.isolated_frame_checkpoints.clear();
        let restored_snapshot = if !rolled_back && let Some(restored_journal) = restored_journal {
            let (_, journaled_state) = ecx.db_journal_inner_mut();
            journaled_state.journal = restored_journal;
            true
        } else {
            false
        };
        if source_fork_id == ecx.db().active_fork_id() {
            merge_child_state(ecx.journal_mut().evm_state_mut(), res.state, restored_snapshot);
        } else {
            *ecx.journal_mut().evm_state_mut() = res.state;
        }
        #[cfg(feature = "monad")]
        foundry_evm_core::FoundryJournal::restore_reserve_balance(
            ecx.journal_mut(),
            reserve_balance.expect("isolated transaction state was captured"),
        );
        #[cfg(feature = "monad")]
        refresh_chain_journal(ecx);

        let (result, address, output) = match res.result {
            ExecutionResult::Success { reason, gas: _, logs: _, output } => {
                gas.set_refund(transaction_gas.final_refunded() as i64);
                let address = match output {
                    Output::Create(_, address) => address,
                    Output::Call(_) => None,
                };
                (reason.into(), address, output.into_data())
            }
            ExecutionResult::Halt { reason, .. } => {
                (InstructionResult::from(reason), None, Bytes::new())
            }
            ExecutionResult::Revert { output, .. } => (InstructionResult::Revert, None, output),
        };
        #[cfg(feature = "monad")]
        if rolled_back {
            refresh_chain_journal(ecx);
        }
        (InterpreterResult { result, output, gas }, address, was_precompile_called)
    }

    /// Moves out of references, constructs a new [`InspectorStackRefMut`] and runs the given
    /// closure with it.
    fn with_inspector<O>(&mut self, f: impl FnOnce(InspectorStackRefMut<'_, FEN>) -> O) -> O {
        let mut cheatcodes = self
            .cheatcodes
            .as_deref_mut()
            .map(|cheats| core::mem::replace(cheats, Cheatcodes::new(cheats.config.clone())));
        let mut inner = std::mem::take(self.inner);

        // Save pending CREATE2 redirects so frame_end in the nested EVM doesn't consume them.
        // These belong to the outer EVM's frame lifecycle and must be restored after.
        let saved_create2_redirects = std::mem::take(&mut inner.pending_create2_redirects);

        let out = f(InspectorStackRefMut { cheatcodes: cheatcodes.as_mut(), inner: &mut inner });

        if let Some(cheats) = self.cheatcodes.as_deref_mut() {
            *cheats = cheatcodes.unwrap();
        }

        inner.pending_create2_redirects = saved_create2_redirects;
        *self.inner = inner;

        out
    }

    /// Invoked at the beginning of a new top-level (0 depth) frame.
    fn top_level_frame_start(&mut self, ecx: &mut FoundryContextFor<'_, FEN>) {
        self.locally_created_accounts.clear();
        self.top_level_frame_failed_before_rewrite = false;
        warm_arbitrum_system_contract::<FEN>(ecx);
        if let Some(cheatcodes) = &mut self.cheatcodes {
            cheatcodes.clear_storage_hook_mapping_slots();
        }

        if self.enable_isolation {
            // If we're in isolation mode, we need to keep track of the state at the beginning of
            // the frame to be able to roll back on revert
            self.top_frame_journal.clone_from(ecx.journal().evm_state());
        }
    }

    /// Invoked at the end of root frame.
    fn top_level_frame_end(&mut self, ecx: &mut FoundryContextFor<'_, FEN>, failed: bool) {
        if let Some(cheatcodes) = &mut self.cheatcodes {
            cheatcodes.clear_storage_hook_mapping_slots();
        }
        if !failed {
            return;
        }
        // The frame was rolled back. Since cheatcodes may have altered the EVM state in a way
        // that violates some constraints, e.g. `deal`, restore those changes explicitly.
        if let Some(cheats) = self.cheatcodes.as_mut() {
            cheats.on_revert(ecx);
        }

        // In isolation mode, restore the state from before the root frame. We cannot rely on
        // revm's journal because it does not account for changes made by isolated calls.
        if self.enable_isolation {
            *ecx.journal_mut().evm_state_mut() = std::mem::take(&mut self.top_frame_journal);
        }

        #[cfg(feature = "monad")]
        refresh_chain_journal(ecx);
    }

    // We take extra care in optimizing `step` and `step_end`, as they're are likely the most
    // hot functions in all of Foundry.
    // We want to `#[inline(always)]` these functions so that `InspectorStack` does not
    // delegate to `InspectorStackRefMut` in this case.

    #[inline(always)]
    fn step_inlined(
        &mut self,
        interpreter: &mut Interpreter,
        ecx: &mut FoundryContextFor<'_, FEN>,
    ) {
        let storage_hook_active = if let Some(cheats) = self.cheatcodes.as_mut() {
            if cheats.has_storage_hooks() && cheats.finish_storage_hook_callback(interpreter, ecx) {
                return;
            }
            cheats.pc = interpreter.bytecode.pc();
            cheats.is_storage_hook_active()
        } else {
            false
        };

        #[cfg(test)]
        if interpreter.bytecode.opcode() == op::JUMPDEST
            && let Some(gate) = &self.inner.early_exit_test_gate
            && interpreter.bytecode.pc() == gate.target_pc
            && !gate.notified.swap(true, std::sync::atomic::Ordering::Relaxed)
        {
            let _ = gate.entered.send(());
            let _ = gate
                .release
                .lock()
                .expect("early-exit test gate lock poisoned")
                .recv_timeout(std::time::Duration::from_secs(1));
        }

        if let Some(cancellation) = &self.inner.execution_cancellation {
            let poll_deadline = self.inner.cancellation_poll_counter == 0;
            self.inner.cancellation_poll_counter =
                self.inner.cancellation_poll_counter.wrapping_add(1);
            if cancellation.should_stop(poll_deadline) {
                self.inner.execution_cancelled = true;
                interpreter.halt(InstructionResult::Stop);
                return;
            }
        }

        match self.static_step_dispatch {
            OpcodeStepDispatch::None => {}
            OpcodeStepDispatch::FuzzerOnly => {
                if !storage_hook_active && let Some(inspector) = &mut self.fuzzer {
                    inspector.step(interpreter, ecx);
                }
            }
            OpcodeStepDispatch::General => {
                if !storage_hook_active {
                    call_inspectors!(
                        [
                            // These are sorted in definition order.
                            &mut self.edge_coverage,
                            &mut self.fuzzer,
                            &mut self.line_coverage,
                        ],
                        |inspector| (**inspector).step(interpreter, ecx),
                    );
                }
                call_inspectors!(
                    [
                        // These are sorted in definition order.
                        &mut self.printer,
                        &mut self.revert_diag,
                        &mut self.script_execution_inspector,
                        &mut self.tracer,
                    ],
                    |inspector| (**inspector).step(interpreter, ecx),
                );
            }
        }

        if let Some(cheats) = self.cheatcodes.as_mut()
            && cheats.has_step_hooks()
        {
            let opcode = interpreter.bytecode.opcode();
            if !cheats.has_recording_accesses_only_step_hook()
                || matches!(opcode, op::SLOAD | op::SSTORE)
            {
                crate::utils::cold_path();
                cheats.step(interpreter, ecx);
            }
        }
    }

    #[inline(always)]
    fn step_end_inlined(
        &mut self,
        interpreter: &mut Interpreter,
        ecx: &mut FoundryContextFor<'_, FEN>,
    ) {
        if self.has_static_step_end_inspectors {
            call_inspectors!(
                [
                    // These are sorted in definition order.
                    &mut self.chisel_state,
                    &mut self.printer,
                    &mut self.revert_diag,
                    &mut self.tracer,
                ],
                |inspector| (**inspector).step_end(interpreter, ecx),
            );
        }

        if let Some(fuzzer) = &mut self.fuzzer
            && fuzzer.mapping_slots.is_some()
        {
            fuzzer.step_end(interpreter, ecx);
        }

        if let Some(cheats) = self.cheatcodes.as_mut()
            && cheats.has_step_end_hooks()
        {
            crate::utils::cold_path();
            cheats.step_end(interpreter, ecx);
        }
    }

    fn finish_isolated_snapshot_frame(&mut self, ecx: &mut FoundryContextFor<'_, FEN>) {
        let Some(frame) = self.inner.isolated_frame_checkpoints.pop() else { return };

        if frame.failed
            && let Some(cheats) = self.cheatcodes.as_deref_mut()
            && cheats.isolated_snapshot_restores.len() > frame.restore_len
        {
            cheats.isolated_snapshot_restores.truncate(frame.restore_len + 1);
            let mut journal = cheats.isolated_snapshot_restores.pop().unwrap();
            journal.checkpoint_revert(frame.checkpoint);
            journal.depth = frame.return_depth;
            if cheats.isolated_snapshot_restores.is_empty() {
                cheats.pending_isolated_snapshot_journal = None;
            }
            ecx.set_journal_inner(journal);
        }

        // The caller only needs the first restoration made since it started, so drop the ones a
        // finished call captured after it. This bounds their count by call depth; each retained
        // journal can still contain all loaded account state.
        if let Some(caller) = self.inner.isolated_frame_checkpoints.last()
            && let Some(cheats) = self.cheatcodes.as_deref_mut()
        {
            cheats.isolated_snapshot_restores.truncate(caller.restore_len + 1);
        }

        if let Some(cheats) = self.cheatcodes.as_deref_mut()
            && cheats.pending_isolated_snapshot_journal.is_some()
        {
            cheats.pending_isolated_snapshot_journal = Some(ecx.journal_inner().journal.clone());
        }
    }
}

impl<FEN: FoundryEvmNetwork> Inspector<FoundryContextFor<'_, FEN>>
    for InspectorStackRefMut<'_, FEN>
{
    fn initialize_interp(
        &mut self,
        interpreter: &mut Interpreter,
        ecx: &mut FoundryContextFor<'_, FEN>,
    ) {
        if self.cheatcodes.as_deref().is_some_and(|cheats| cheats.track_isolated_snapshots)
            && let Some(frame) = self.inner.isolated_frame_checkpoints.last_mut()
            && frame.is_create
            && let Some(offset) = ecx.journal_inner().journal[frame.checkpoint.journal_i..]
                .iter()
                .position(|entry| matches!(entry, JournalEntry::AccountCreated { .. }))
        {
            frame.checkpoint.journal_i += offset;
        }

        let address = interpreter.input.target_address();
        let should_mark_created_locally = self.locally_created_accounts.contains(&address)
            || self
                .inner_context_data
                .as_ref()
                .is_some_and(|ctx| ctx.locally_created_accounts.contains(&address));
        if should_mark_created_locally
            && let Some(account) = ecx.journal_mut().evm_state_mut().get_mut(&address)
            && account.is_created()
        {
            account.mark_created_locally();
        }

        call_inspectors!(
            [
                &mut self.line_coverage,
                &mut self.tracer,
                &mut self.cheatcodes,
                &mut self.script_execution_inspector,
                &mut self.printer
            ],
            |inspector| inspector.initialize_interp(interpreter, ecx),
        );
    }

    fn step(&mut self, interpreter: &mut Interpreter, ecx: &mut FoundryContextFor<'_, FEN>) {
        self.step_inlined(interpreter, ecx);
    }

    fn step_end(&mut self, interpreter: &mut Interpreter, ecx: &mut FoundryContextFor<'_, FEN>) {
        self.step_end_inlined(interpreter, ecx);
    }

    #[allow(clippy::redundant_clone)]
    fn log(&mut self, ecx: &mut FoundryContextFor<'_, FEN>, log: Log) {
        call_inspectors!([&mut self.tracer, &mut self.log_collector], |inspector| {
            inspector.log(ecx, log.clone())
        });
        if let Some(inspector) = &mut self.cheatcodes
            && inspector.has_log_hooks()
        {
            crate::utils::cold_path();
            inspector.log(ecx, log.clone());
        }
        call_inspectors!([&mut self.printer], |inspector| { inspector.log(ecx, log.clone()) });
    }

    #[allow(clippy::redundant_clone)]
    fn log_full(
        &mut self,
        interpreter: &mut Interpreter,
        ecx: &mut FoundryContextFor<'_, FEN>,
        log: Log,
    ) {
        call_inspectors!([&mut self.tracer, &mut self.log_collector], |inspector| {
            inspector.log_full(interpreter, ecx, log.clone())
        });
        if let Some(inspector) = &mut self.cheatcodes
            && inspector.has_log_hooks()
        {
            crate::utils::cold_path();
            inspector.log_full(interpreter, ecx, log.clone());
        }
        call_inspectors!([&mut self.printer], |inspector| {
            inspector.log_full(interpreter, ecx, log.clone())
        });
    }

    fn frame_start(
        &mut self,
        ecx: &mut FoundryContextFor<'_, FEN>,
        frame_input: &mut FrameInput,
    ) -> Option<FrameResult> {
        // A non-isolated top-level transaction needs the same restore tracking as an isolated call.
        if !self.enable_isolation
            && !self.in_inner_context
            && ecx.journal().depth() == 0
            && let Some(cheats) = self.cheatcodes.as_deref_mut()
        {
            cheats.pending_isolated_snapshot_journal = None;
            cheats.track_isolated_snapshots = true;
            cheats.isolated_snapshot_restores.clear();
            self.inner.isolated_frame_checkpoints.clear();
        }
        if let Some(cheats) = self.cheatcodes.as_deref_mut()
            && cheats.track_isolated_snapshots
        {
            let journal = ecx.journal_inner();
            let restore_len = cheats.isolated_snapshot_restores.len();
            // Unwinding a frame only needs the first restoration made inside it, so a restoration
            // requested by this call is captured only if none was captured since its caller
            // started.
            cheats.capture_isolated_snapshot_restore = self
                .inner
                .isolated_frame_checkpoints
                .last()
                .is_none_or(|caller| caller.restore_len == restore_len);
            self.inner.isolated_frame_checkpoints.push(IsolatedFrameCheckpoint {
                checkpoint: JournalCheckpoint {
                    log_i: journal.logs.len(),
                    journal_i: journal.journal.len(),
                    selfdestructed_i: journal.selfdestructed_addresses.len(),
                },
                restore_len,
                return_depth: journal.depth,
                is_create: matches!(frame_input, FrameInput::Create(_)),
                failed: false,
            });
        }

        if let FrameInput::Create(inputs) = frame_input
            && self.should_use_create2_factory(ecx.journal().depth(), inputs)
        {
            // `get_create2_factory_call_inputs` forwards `inputs.value()` to the factory
            // as `CallValue::Transfer`, and the default factory runtime forwards CALLVALUE
            // into CREATE2, so payable deploys are supported on both the explicit
            // `new C{salt, value}` path and the `--batch` rewrite path.
            let salt = match inputs.scheme() {
                CreateScheme::Create2 { salt } => salt,
                // --batch: process_salt (random per run) + counter make each deploy unique.
                // The nonce below is from the EVM frame caller (script contract), not the EOA.
                CreateScheme::Create => {
                    if !self.inner.batch_rewrite_warned {
                        let _ = sh_warn!(
                            "--batch rewrites CREATE → CREATE2 via the Arachnid factory; \
                             deployed addresses follow the CREATE2 formula and constructor \
                             msg.sender is the factory, not the EOA."
                        );
                        self.inner.batch_rewrite_warned = true;
                    }
                    let chain_id = ecx.cfg().chain_id();
                    let nonce = ecx.journal_mut().load_account(inputs.caller()).ok()?.info.nonce;
                    self.inner.next_batch_create_salt(chain_id, nonce)
                }
                _ => return None,
            };

            let gas_limit = inputs.gas_limit();
            let create2_deployer = self.create2_deployer();

            // Validate deployer before rewriting.
            let code_hash = ecx.journal_mut().load_account(create2_deployer).ok()?.info.code_hash;
            if code_hash == KECCAK_EMPTY {
                // Store the revert so `create` can return it inside the normal inspector
                // lifecycle (avoids tracing mismatch from short-circuiting in frame_start).
                self.inner.pending_create2_error = Some(CreateOutcome {
                    result: InterpreterResult {
                        result: InstructionResult::Revert,
                        output: Bytes::from(
                            format!("missing CREATE2 deployer: {create2_deployer}").into_bytes(),
                        ),
                        gas: Gas::new(gas_limit),
                    },
                    address: None,
                    charged_create_state_gas: inputs.charged_create_state_gas(),
                });
                return None;
            } else if code_hash != DEFAULT_CREATE2_DEPLOYER_CODEHASH {
                self.inner.pending_create2_error = Some(CreateOutcome {
                    result: InterpreterResult {
                        result: InstructionResult::Revert,
                        output: "invalid CREATE2 deployer bytecode".into(),
                        gas: Gas::new(gas_limit),
                    },
                    address: None,
                    charged_create_state_gas: inputs.charged_create_state_gas(),
                });
                return None;
            }

            let call_inputs =
                get_create2_factory_call_inputs(salt, inputs, create2_deployer, ecx.journal_mut())
                    .ok()?;

            // Record the redirect depth *after* validation succeeds.
            self.inner.pending_create2_redirects.push(PendingCreate2Redirect {
                depth: ecx.journal().depth(),
                charged_create_state_gas: inputs.charged_create_state_gas(),
            });

            // Rewrite the frame input from Create to Call.
            *frame_input = FrameInput::Call(Box::new(call_inputs));
        }

        None
    }

    fn frame_end(
        &mut self,
        ecx: &mut FoundryContextFor<'_, FEN>,
        _frame_input: &FrameInput,
        frame_result: &mut FrameResult,
    ) {
        let depth = ecx.journal().depth();
        self.finish_create2_redirect(depth, frame_result);
        if self.cheatcodes.as_deref().is_some_and(|cheats| cheats.track_isolated_snapshots) {
            self.finish_isolated_snapshot_frame(ecx);
        }

        let result = frame_result.instruction_result();
        if !self.in_inner_context && depth == 0 {
            let failed = std::mem::take(&mut self.inner.top_level_frame_failed_before_rewrite)
                || !result.is_ok();
            self.top_level_frame_end(ecx, failed);
            if !self.enable_isolation {
                if let Some(cheats) = self.cheatcodes.as_deref_mut() {
                    cheats.track_isolated_snapshots = false;
                    cheats.isolated_snapshot_restores.clear();
                }
                self.inner.isolated_frame_checkpoints.clear();
            }
        }
    }

    fn call(
        &mut self,
        ecx: &mut FoundryContextFor<'_, FEN>,
        call: &mut CallInputs,
    ) -> Option<CallOutcome> {
        if self.is_inner_context_root(ecx.journal().depth()) {
            self.adjust_evm_data_for_inner_context(ecx);
            warm_arbitrum_system_contract::<FEN>(ecx);
            // Transaction call inputs use the original target, so resolve function mocks here too.
            if let Some(cheatcodes) = self.cheatcodes.as_deref() {
                apply_mocked_function(cheatcodes, ecx, call);
            }
            return None;
        }

        if ecx.journal().depth() == 0 {
            self.top_level_frame_start(ecx);
        }

        if let Some(revert_diag) = self.revert_diag.as_deref_mut() {
            revert_diag.frame_start();
        }

        let storage_hook_callback = self
            .cheatcodes
            .as_deref()
            .is_some_and(|cheatcodes| cheatcodes.is_storage_hook_callback(ecx, call));
        let storage_hook_active =
            self.cheatcodes.as_deref().is_some_and(Cheatcodes::is_storage_hook_active);

        if !storage_hook_active {
            call_inspectors!(
                #[ret]
                [&mut self.fuzzer],
                |inspector| {
                    let mut out = None;
                    if let Some(output) = inspector.call(ecx, call) {
                        out = Some(Some(output));
                    }
                    out
                }
            );
        }

        if self.tracer.is_some() {
            crate::utils::cold_path();
            let (output, trace_idx) = {
                let tracer = self.tracer.as_deref_mut().unwrap();
                let output = tracer.call(ecx, call);
                (output, tracer.traces().nodes().len() - 1)
            };
            self.pending_call_traces.push(PendingCallTrace { trace_idx, executed_address: None });
            if let Some(revert_diag) = self.revert_diag.as_deref_mut() {
                revert_diag.set_trace_node(trace_idx);
            }
            if output.is_some() {
                return output;
            }
        }

        call_inspectors!(
            #[ret]
            [
                &mut self.log_collector,
                &mut self.printer,
                &mut self.revert_diag,
                &mut self.tempo_labels
            ],
            |inspector| inspector.call(ecx, call).map(Some),
        );

        // Storage hook callbacks are instrumentation frames, not user calls. Let revm execute the
        // callback after tracing it, but do not apply mocks, pranks, broadcasts, or isolation.
        if storage_hook_callback {
            if let Some(pending) = self.pending_call_traces.last_mut() {
                pending.executed_address = Some(call.bytecode_address);
            }
            return None;
        }

        // The tracer records call inputs before cheatcodes apply caller overrides such as pranks
        // and broadcasts. Keep the trace lifecycle ordering, but remember the node so its caller
        // can be synchronized with the inputs that are actually executed.
        let trace_idx = self.tracer.as_ref().map(|tracer| tracer.traces().nodes().len() - 1);
        // Also isolate a synthetic `deployCode` create that was rewritten to a CREATE2 factory
        // call.
        let isolate = self.enable_isolation
            && !self.in_inner_context
            && (ecx.journal().depth() == 1
                || self.inner.synthetic_create_depth == Some(ecx.journal().depth()));
        let mut cheatcode_outcome = None;
        if let Some(cheatcodes) = self.cheatcodes.as_deref_mut() {
            apply_mocked_function(cheatcodes, ecx, call);

            let execution_disable_fee_charge = ecx.cfg_env().disable_fee_charge;
            if let Some(disable_fee_charge) = self.inner.outer_disable_fee_charge {
                ecx.cfg_env_mut().disable_fee_charge = disable_fee_charge;
            }
            cheatcode_outcome = cheatcodes.call_with_executor(
                ecx,
                call,
                self.inner,
                isolate && call.scheme.is_call(),
            );
            ecx.cfg_env_mut().disable_fee_charge = execution_disable_fee_charge;
        }

        if let Some(trace_idx) = trace_idx
            && let Some(tracer) = self.tracer.as_deref_mut()
        {
            let caller = match call.scheme {
                CallScheme::DelegateCall | CallScheme::CallCode => call.transfer_to(),
                CallScheme::Call | CallScheme::StaticCall => call.transfer_from(),
            };
            let node = &mut tracer.traces_mut().nodes_mut()[trace_idx];
            debug_assert_eq!(node.trace.depth, ecx.journal().depth());
            node.trace.caller = caller;
        }

        if let Some(output) = cheatcode_outcome {
            return Some(output);
        }

        if let Some(outcome) = handle_arbitrum_system_call::<FEN>(ecx, call) {
            return Some(outcome);
        }

        if let Some(pending) = self.pending_call_traces.last_mut() {
            pending.executed_address = Some(call.bytecode_address);
        }

        if isolate {
            match call.scheme {
                // Isolate CALLs
                CallScheme::Call => {
                    let input = call.input.bytes(ecx);
                    let precharged_state = call
                        .charged_new_account_state_gas
                        .then_some(ecx.cfg().gas_params().new_account_state_gas());
                    let (result, _, was_precompile_called) = self.transact_inner(
                        ecx,
                        TxKind::Call(call.transfer_to()),
                        call.transfer_from(),
                        input,
                        IsolatedGas {
                            regular_limit: call.gas_limit,
                            reservoir: call.reservoir,
                            precharged_state,
                        },
                        call.value.get(),
                    );
                    return Some(CallOutcome {
                        result,
                        memory_offset: call.return_memory_offset.clone(),
                        was_precompile_called,
                        precompile_call_logs: vec![],
                        charged_new_account_state_gas: call.charged_new_account_state_gas,
                    });
                }
                // Mark accounts and storage cold before STATICCALLs
                CallScheme::StaticCall => {
                    let (_, journal_inner) = ecx.db_journal_inner_mut();
                    let JournaledState { state, warm_addresses, .. } = journal_inner;
                    for (addr, acc_mut) in state {
                        // Do not mark accounts and storage cold accounts with arbitrary storage.
                        if let Some(cheatcodes) = &self.cheatcodes
                            && cheatcodes.has_arbitrary_storage(addr)
                        {
                            continue;
                        }

                        if warm_addresses.is_cold(addr) {
                            acc_mut.mark_cold();
                        }

                        for slot_mut in acc_mut.storage.values_mut() {
                            slot_mut.is_cold = true;
                        }
                    }
                }
                // Process other variants as usual
                CallScheme::CallCode | CallScheme::DelegateCall => {}
            }
        }

        None
    }

    fn call_end(
        &mut self,
        ecx: &mut FoundryContextFor<'_, FEN>,
        inputs: &CallInputs,
        outcome: &mut CallOutcome,
    ) {
        if self.cheatcodes.as_deref().is_some_and(|cheats| cheats.track_isolated_snapshots)
            && let Some(frame) = self.inner.isolated_frame_checkpoints.last_mut()
        {
            frame.failed |= !outcome.result.result.is_ok();
        }

        // We are processing inner context outputs in the outer context, so need to avoid processing
        // twice.
        if self.is_inner_context_root(ecx.journal().depth()) {
            self.isolated_call_was_precompile = Some(outcome.was_precompile_called);
            return;
        }

        if ecx.journal().depth() == 0 {
            self.inner.top_level_frame_failed_before_rewrite |= !outcome.result.result.is_ok();
        }

        if let Some(pending) = self.pending_call_traces.pop()
            && let Some(tracer) = self.tracer.as_deref_mut()
        {
            let trace = &mut tracer.traces_mut().nodes_mut()[pending.trace_idx].trace;
            if trace.address == P256_VERIFY {
                trace.maybe_precompile = Some(
                    pending.executed_address == Some(P256_VERIFY) && outcome.was_precompile_called,
                );
            }
        }

        self.do_call_end(ecx, inputs, outcome);

        if let Some(revert_diag) = self.revert_diag.as_deref_mut() {
            revert_diag.frame_end();
        }
    }

    fn create(
        &mut self,
        ecx: &mut FoundryContextFor<'_, FEN>,
        create: &mut CreateInputs,
    ) -> Option<CreateOutcome> {
        if self.is_inner_context_root(ecx.journal().depth()) {
            self.adjust_evm_data_for_inner_context(ecx);
            warm_arbitrum_system_contract::<FEN>(ecx);
            return None;
        }

        if ecx.journal().depth() == 0 {
            self.top_level_frame_start(ecx);
        }

        if let Some(revert_diag) = self.revert_diag.as_deref_mut() {
            revert_diag.frame_start();
        }

        if self.tracer.is_some() {
            crate::utils::cold_path();
            let (output, trace_idx) = {
                let tracer = self.tracer.as_deref_mut().unwrap();
                let output = tracer.create(ecx, create);
                (output, tracer.traces().nodes().len() - 1)
            };
            if let Some(revert_diag) = self.revert_diag.as_deref_mut() {
                revert_diag.set_trace_node(trace_idx);
            }
            if output.is_some() {
                return output;
            }
        }

        call_inspectors!(
            #[ret]
            [&mut self.line_coverage],
            |inspector| inspector.create(ecx, create).map(Some),
        );

        let trace_idx = self.tracer.as_ref().map(|tracer| tracer.traces().nodes().len() - 1);
        let mut cheatcode_outcome = None;
        if let Some(cheatcodes) = self.cheatcodes.as_deref_mut() {
            cheatcode_outcome = cheatcodes.create(ecx, create);
        }

        if let Some(trace_idx) = trace_idx
            && let Some(tracer) = self.tracer.as_deref_mut()
        {
            let node = &mut tracer.traces_mut().nodes_mut()[trace_idx];
            debug_assert_eq!(node.trace.depth, ecx.journal().depth());
            node.trace.caller = create.caller();
        }

        if let Some(output) = cheatcode_outcome {
            return Some(output);
        }

        // If frame_start detected an invalid CREATE2 deployer, return the error here
        // (after sub-inspectors have been notified) so tracing stays balanced.
        if let Some(error) = self.inner.pending_create2_error.take() {
            return Some(error);
        }

        if !matches!(create.scheme(), CreateScheme::Create2 { .. })
            && self.enable_isolation
            && !self.in_inner_context
            && (ecx.journal().depth() == 1
                || self.synthetic_create_depth == Some(ecx.journal().depth()))
        {
            // In isolation mode, transact_inner returns None for the address on revert; pre-compute
            // the would-be deployed address so create_end can enforce expected_revert reverter
            // checks.
            let precomputed_address = ecx
                .journal()
                .evm_state()
                .get(&create.caller())
                .map(|acc| create.caller().create(acc.info.nonce));
            let precharged_state = create
                .charged_create_state_gas()
                .then_some(ecx.cfg().gas_params().create_state_gas());

            let (result, address, _) = self.transact_inner(
                ecx,
                TxKind::Create,
                create.caller(),
                create.init_code().clone(),
                IsolatedGas {
                    regular_limit: create.gas_limit(),
                    reservoir: create.reservoir(),
                    precharged_state,
                },
                create.value(),
            );
            let address =
                address.or_else(|| if result.is_revert() { precomputed_address } else { None });
            return Some(CreateOutcome {
                result,
                address,
                charged_create_state_gas: create.charged_create_state_gas(),
            });
        }

        None
    }

    fn create_end(
        &mut self,
        ecx: &mut FoundryContextFor<'_, FEN>,
        call: &CreateInputs,
        outcome: &mut CreateOutcome,
    ) {
        if self.cheatcodes.as_deref().is_some_and(|cheats| cheats.track_isolated_snapshots)
            && let Some(frame) = self.inner.isolated_frame_checkpoints.last_mut()
        {
            frame.failed |= !outcome.result.result.is_ok();
        }

        if outcome.result.result.is_ok()
            && let Some(address) = outcome.address
        {
            self.locally_created_accounts.insert(address);

            if self.in_inner_context
                && let Some(inner_context) = &mut self.inner_context_data
            {
                inner_context.locally_created_accounts.insert(address);
            }
        }

        // We are processing inner context outputs in the outer context, so need to avoid processing
        // twice.
        if self.is_inner_context_root(ecx.journal().depth()) {
            return;
        }

        if ecx.journal().depth() == 0 {
            self.inner.top_level_frame_failed_before_rewrite |= !outcome.result.result.is_ok();
        }

        self.do_create_end(ecx, call, outcome);

        if let Some(revert_diag) = self.revert_diag.as_deref_mut() {
            revert_diag.frame_end();
        }
    }

    fn selfdestruct(&mut self, contract: Address, target: Address, value: U256) {
        call_inspectors!([&mut self.printer], |inspector| {
            Inspector::<FoundryContextFor<'_, FEN>>::selfdestruct(
                inspector, contract, target, value,
            )
        });
    }
}

fn warm_arbitrum_system_contract<FEN: FoundryEvmNetwork>(ecx: &mut FoundryContextFor<'_, FEN>) {
    if !arbitrum::is_arbitrum_chain(ecx.cfg().chain_id()) {
        return;
    }

    // Nitro warms ArbSys like a precompile. Use the access list so other selectors can still
    // execute code at the address.
    let mut access_list = ecx.journal_inner().warm_addresses.access_list().clone();
    access_list.entry(arbitrum::ARB_SYS_ADDRESS).or_default();
    ecx.journal_mut().warm_access_list(access_list);
}

fn handle_arbitrum_system_call<FEN: FoundryEvmNetwork>(
    ecx: &mut FoundryContextFor<'_, FEN>,
    call: &CallInputs,
) -> Option<CallOutcome> {
    if call.transfer_to() != arbitrum::ARB_SYS_ADDRESS
        || call.bytecode_address != arbitrum::ARB_SYS_ADDRESS
        || !arbitrum::is_arbitrum_chain(ecx.cfg().chain_id())
    {
        return None;
    }

    let input = call.input.bytes(ecx);
    if input.get(..4) != Some(&arbitrum::ARB_BLOCK_NUMBER_SELECTOR) {
        return None;
    }

    // Forks report their L2 block, which the block env lacks on Arbitrum because `NUMBER` returns
    // the L1 block there. Without a fork the block env is read here to follow `vm.roll`.
    let block_number = match ecx.db().active_fork_block_number() {
        Some(block_number) => block_number,
        None => ecx.block().number().saturating_to(),
    };
    let Some((gas_cost, output)) = arbitrum::arb_block_number_call(call.gas_limit, block_number)
    else {
        return Some(arbitrum_call_outcome(
            call,
            InstructionResult::PrecompileOOG,
            0,
            Bytes::new(),
        ));
    };

    Some(arbitrum_call_outcome(call, InstructionResult::Return, gas_cost, output))
}

fn arbitrum_call_outcome(
    call: &CallInputs,
    result: InstructionResult,
    gas_used: u64,
    output: Bytes,
) -> CallOutcome {
    let mut gas = Gas::new(call.gas_limit);
    if result.is_ok() {
        let _ = gas.record_regular_cost(gas_used);
    } else {
        gas.spend_all();
    }

    CallOutcome {
        result: InterpreterResult { result, output, gas },
        memory_offset: call.return_memory_offset.clone(),
        was_precompile_called: true,
        precompile_call_logs: vec![],
        charged_new_account_state_gas: call.charged_new_account_state_gas,
    }
}

impl<FEN: FoundryEvmNetwork> InspectorExt for InspectorStackRefMut<'_, FEN> {
    fn should_use_create2_factory(&mut self, depth: usize, inputs: &CreateInputs) -> bool {
        call_inspectors!(
            #[ret]
            [&mut self.cheatcodes],
            |inspector| { inspector.should_use_create2_factory(depth, inputs).then_some(true) },
        );

        false
    }

    fn console_log(&mut self, msg: &str) {
        call_inspectors!([&mut self.log_collector], |inspector| InspectorExt::console_log(
            inspector, msg
        ));
    }

    fn get_networks(&self) -> NetworkConfigs {
        self.inner.networks
    }

    fn create2_deployer(&self) -> Address {
        self.inner.create2_deployer
    }
}

impl<FEN: FoundryEvmNetwork> Inspector<FoundryContextFor<'_, FEN>> for InspectorStack<FEN> {
    #[inline(always)]
    fn step(&mut self, interpreter: &mut Interpreter, ecx: &mut FoundryContextFor<'_, FEN>) {
        self.as_mut().step_inlined(interpreter, ecx)
    }

    #[inline(always)]
    fn step_end(&mut self, interpreter: &mut Interpreter, ecx: &mut FoundryContextFor<'_, FEN>) {
        self.as_mut().step_end_inlined(interpreter, ecx)
    }

    fn call(
        &mut self,
        context: &mut FoundryContextFor<'_, FEN>,
        inputs: &mut CallInputs,
    ) -> Option<CallOutcome> {
        self.as_mut().call(context, inputs)
    }

    fn call_end(
        &mut self,
        context: &mut FoundryContextFor<'_, FEN>,
        inputs: &CallInputs,
        outcome: &mut CallOutcome,
    ) {
        self.as_mut().call_end(context, inputs, outcome)
    }

    fn create(
        &mut self,
        context: &mut FoundryContextFor<'_, FEN>,
        create: &mut CreateInputs,
    ) -> Option<CreateOutcome> {
        self.as_mut().create(context, create)
    }

    fn create_end(
        &mut self,
        context: &mut FoundryContextFor<'_, FEN>,
        call: &CreateInputs,
        outcome: &mut CreateOutcome,
    ) {
        self.as_mut().create_end(context, call, outcome)
    }

    fn initialize_interp(
        &mut self,
        interpreter: &mut Interpreter,
        ecx: &mut FoundryContextFor<'_, FEN>,
    ) {
        self.as_mut().initialize_interp(interpreter, ecx)
    }

    fn log(&mut self, ecx: &mut FoundryContextFor<'_, FEN>, log: Log) {
        self.as_mut().log(ecx, log)
    }

    fn log_full(
        &mut self,
        interpreter: &mut Interpreter,
        ecx: &mut FoundryContextFor<'_, FEN>,
        log: Log,
    ) {
        self.as_mut().log_full(interpreter, ecx, log)
    }

    fn frame_start(
        &mut self,
        context: &mut FoundryContextFor<'_, FEN>,
        frame_input: &mut FrameInput,
    ) -> Option<FrameResult> {
        self.as_mut().frame_start(context, frame_input)
    }

    fn frame_end(
        &mut self,
        context: &mut FoundryContextFor<'_, FEN>,
        frame_input: &FrameInput,
        frame_result: &mut FrameResult,
    ) {
        self.as_mut().frame_end(context, frame_input, frame_result)
    }

    fn selfdestruct(&mut self, contract: Address, target: Address, value: U256) {
        call_inspectors!([&mut self.inner.printer], |inspector| {
            Inspector::<FoundryContextFor<'_, FEN>>::selfdestruct(
                inspector, contract, target, value,
            )
        });
    }
}

impl<FEN: FoundryEvmNetwork> InspectorExt for InspectorStack<FEN> {
    fn should_use_create2_factory(&mut self, depth: usize, inputs: &CreateInputs) -> bool {
        self.as_mut().should_use_create2_factory(depth, inputs)
    }

    fn get_networks(&self) -> NetworkConfigs {
        self.networks
    }

    fn create2_deployer(&self) -> Address {
        self.create2_deployer
    }
}

impl<'a, FEN: FoundryEvmNetwork> Deref for InspectorStackRefMut<'a, FEN> {
    type Target = &'a mut InspectorStackInner;

    fn deref(&self) -> &Self::Target {
        &self.inner
    }
}

impl<FEN: FoundryEvmNetwork> DerefMut for InspectorStackRefMut<'_, FEN> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.inner
    }
}

impl<FEN: FoundryEvmNetwork> Deref for InspectorStack<FEN> {
    type Target = InspectorStackInner;

    fn deref(&self) -> &Self::Target {
        &self.inner
    }
}

impl<FEN: FoundryEvmNetwork> DerefMut for InspectorStack<FEN> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.inner
    }
}

impl InspectorStackInner {
    #[inline]
    const fn refresh_static_opcode_dispatch(&mut self) {
        self.refresh_static_step_dispatch();
        self.refresh_static_step_end_dispatch();
    }

    #[inline]
    const fn refresh_static_step_dispatch(&mut self) {
        self.static_step_dispatch = if self.edge_coverage.is_none()
            && self.line_coverage.is_none()
            && self.printer.is_none()
            && self.revert_diag.is_none()
            && self.script_execution_inspector.is_none()
            && self.tracer.is_none()
        {
            if self.fuzzer.is_some() {
                OpcodeStepDispatch::FuzzerOnly
            } else {
                OpcodeStepDispatch::None
            }
        } else {
            OpcodeStepDispatch::General
        };
    }

    #[inline]
    const fn refresh_static_step_end_dispatch(&mut self) {
        self.has_static_step_end_inspectors = self.chisel_state.is_some()
            || self.printer.is_some()
            || self.revert_diag.is_some()
            || self.tracer.is_some();
    }

    /// Derive the next `--batch` CREATE2 salt and advance the per-batch counter.
    /// The per-inspector random seed is lazily initialized on first use.
    fn next_batch_create_salt(&mut self, chain_id: u64, nonce: u64) -> U256 {
        let process_salt = *self.batch_rewrite_process_salt.get_or_insert_with(rand::random);
        let counter = self.batch_create_counter;
        self.batch_create_counter = counter.wrapping_add(1);
        compute_batch_create_salt(process_salt, chain_id, nonce, counter)
    }

    /// Whether this frame duplicates the outer frame that entered an isolated transaction.
    fn is_inner_context_root(&self, depth: usize) -> bool {
        self.in_inner_context
            && self.inner_context_data.as_ref().is_some_and(|inner| depth == inner.root_depth)
    }

    /// Gives a fresh transaction its own restore tracking, independent of the suspended parent.
    fn with_snapshot_tracking<FEN: FoundryEvmNetwork, R>(
        &mut self,
        cheats: &mut Cheatcodes<FEN>,
        f: impl FnOnce(&mut Self, &mut Cheatcodes<FEN>) -> R,
    ) -> R {
        let tracking = std::mem::replace(&mut cheats.track_isolated_snapshots, true);
        let isolation = std::mem::replace(&mut cheats.in_isolation_context, false);
        let capture = std::mem::replace(&mut cheats.capture_isolated_snapshot_restore, true);
        let restores = std::mem::take(&mut cheats.isolated_snapshot_restores);
        let pending = cheats.pending_isolated_snapshot_journal.take();
        let frames = std::mem::take(&mut self.isolated_frame_checkpoints);
        let result = f(self, cheats);
        self.isolated_frame_checkpoints = frames;
        cheats.pending_isolated_snapshot_journal = pending;
        cheats.isolated_snapshot_restores = restores;
        cheats.capture_isolated_snapshot_restore = capture;
        cheats.in_isolation_context = isolation;
        cheats.track_isolated_snapshots = tracking;
        result
    }
}

/// Derive the CREATE2 salt used by `--batch` CREATE rewrites.
///
/// Mixes a per-inspector random seed, the chain id, the caller nonce, and a per-batch counter
/// so that two simulations launched at the same on-chain state produce distinct salts and
/// do not collide at the Arachnid factory.
fn compute_batch_create_salt(process_salt: u64, chain_id: u64, nonce: u64, counter: u64) -> U256 {
    let mut buf = [0u8; 32];
    buf[0..8].copy_from_slice(&process_salt.to_be_bytes());
    buf[8..16].copy_from_slice(&chain_id.to_be_bytes());
    buf[16..24].copy_from_slice(&nonce.to_be_bytes());
    buf[24..32].copy_from_slice(&counter.to_be_bytes());
    keccak256(buf).into()
}

/// Redirects `call` to the implementation set with `vm.mockFunction`, if one matches.
fn apply_mocked_function<FEN: FoundryEvmNetwork>(
    cheatcodes: &Cheatcodes<FEN>,
    ecx: &mut FoundryContextFor<'_, FEN>,
    call: &mut CallInputs,
) {
    if let Some(mocks) = cheatcodes.mocked_functions.get(&call.bytecode_address) {
        let input_bytes = call.input.bytes(ecx);
        // Check if any mock function set for call data or if catch-all mock function set
        // for selector.
        if let Some(target) = mocks
            .get(&input_bytes)
            .or_else(|| input_bytes.get(..4).and_then(|selector| mocks.get(selector)))
        {
            call.bytecode_address = *target;

            let target =
                ecx.journal_mut().load_account_with_code(*target).expect("failed to load account");
            call.known_bytecode =
                (target.info.code_hash(), target.info.code.clone().unwrap_or_default());
        }
    }
}

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

    #[test]
    fn opcode_dispatch_defaults_to_no_static_inspectors() {
        let stack = InspectorStackInner::default();

        assert_eq!(stack.static_step_dispatch, OpcodeStepDispatch::None);
        assert!(!stack.has_static_step_end_inspectors);
    }

    #[test]
    fn opcode_dispatch_uses_fuzzer_fast_path_when_fuzzer_is_only_static_step_inspector() {
        let mut stack = InspectorStack::<EthEvmNetwork>::new();
        stack.set_fuzzer(Fuzzer::new(16, None));

        assert_eq!(stack.inner.static_step_dispatch, OpcodeStepDispatch::FuzzerOnly);
        assert!(!stack.inner.has_static_step_end_inspectors);

        stack.collect_line_coverage(true);
        assert_eq!(stack.inner.static_step_dispatch, OpcodeStepDispatch::General);

        stack.collect_line_coverage(false);
        assert_eq!(stack.inner.static_step_dispatch, OpcodeStepDispatch::FuzzerOnly);
    }

    #[test]
    fn opcode_dispatch_tracks_general_step_and_step_end_inspectors() {
        let mut stack = InspectorStack::<EthEvmNetwork>::new();

        stack.print(true);
        assert_eq!(stack.inner.static_step_dispatch, OpcodeStepDispatch::General);
        assert!(stack.inner.has_static_step_end_inspectors);

        stack.print(false);
        assert_eq!(stack.inner.static_step_dispatch, OpcodeStepDispatch::None);
        assert!(!stack.inner.has_static_step_end_inspectors);

        stack.tracing_requirements(TraceRequirements::none().with_calls(true));
        assert_eq!(stack.inner.static_step_dispatch, OpcodeStepDispatch::General);
        assert!(stack.inner.has_static_step_end_inspectors);

        stack.tracing_requirements(TraceRequirements::none());
        assert_eq!(stack.inner.static_step_dispatch, OpcodeStepDispatch::None);
        assert!(!stack.inner.has_static_step_end_inspectors);

        stack.set_chisel(0);
        assert_eq!(stack.inner.static_step_dispatch, OpcodeStepDispatch::None);
        assert!(stack.inner.has_static_step_end_inspectors);
    }

    #[test]
    fn opcode_dispatch_tracks_script_and_edge_coverage_inspectors() {
        let mut stack = InspectorStack::<EthEvmNetwork>::new();

        stack.script(Address::with_last_byte(1));
        assert_eq!(stack.inner.static_step_dispatch, OpcodeStepDispatch::General);
        assert!(!stack.inner.has_static_step_end_inspectors);

        let mut stack = InspectorStack::<EthEvmNetwork>::new();
        stack.collect_edge_coverage(true);
        assert_eq!(stack.inner.static_step_dispatch, OpcodeStepDispatch::General);
        stack.collect_edge_coverage(false);
        assert_eq!(stack.inner.static_step_dispatch, OpcodeStepDispatch::None);
    }

    #[test]
    fn revert_diagnostic_frames_remain_balanced() {
        let mut inspector = RevertDiagnostic::default();
        inspector.frame_start();
        inspector.set_trace_node(0);
        inspector.frame_start();
        inspector.set_trace_node(1);
        inspector.frame_end();
        inspector.frame_end();

        assert!(inspector.into_diagnostics().is_empty());
    }

    #[test]
    fn distinct_salts_across_simulations_at_same_nonce() {
        // Two "simulations" with different per-inspector seeds but identical on-chain state.
        let a = compute_batch_create_salt(0xabcd_ef01_2345_6789, 1, 5, 0);
        let b = compute_batch_create_salt(0x1122_3344_5566_7788, 1, 5, 0);
        assert_ne!(a, b);
    }

    #[test]
    fn counter_changes_salt() {
        let a = compute_batch_create_salt(1, 1, 5, 0);
        let b = compute_batch_create_salt(1, 1, 5, 1);
        assert_ne!(a, b);
    }

    #[test]
    fn chain_id_changes_salt() {
        let a = compute_batch_create_salt(1, 1, 5, 0);
        let b = compute_batch_create_salt(1, 2, 5, 0);
        assert_ne!(a, b);
    }

    #[test]
    fn deterministic_for_same_inputs() {
        let a = compute_batch_create_salt(42, 1, 5, 7);
        let b = compute_batch_create_salt(42, 1, 5, 7);
        assert_eq!(a, b);
    }

    #[test]
    fn distinct_create2_addresses_across_inspector_instances_at_same_onchain_state() {
        // Two fresh inspectors fed identical (chain_id, nonce) must produce CREATE2 addresses
        // that differ when routed through the same factory with the same init code.
        let factory = Address::with_last_byte(0x42);
        let init_code = b"\x60\x80\x60\x40".as_slice();

        let mut a = InspectorStackInner::default();
        let mut b = InspectorStackInner::default();
        let salt_a = a.next_batch_create_salt(1, 5).to_be_bytes::<32>();
        let salt_b = b.next_batch_create_salt(1, 5).to_be_bytes::<32>();

        let addr_a = factory.create2_from_code(salt_a, init_code);
        let addr_b = factory.create2_from_code(salt_b, init_code);
        assert_ne!(addr_a, addr_b);
    }
}