Expand description
Foundry’s execution lifecycle over evm2: fork switching, snapshots and nested execution.
evm2’s [State] owns transaction scratch, journaling, warmth, transient storage, logs and the
accepted overlay of the running context. This module owns everything Foundry layers on top:
which backing database is active, the accepted state of every inactive fork, user-visible
snapshots, and nested transactions.
§Executions
ExecutionLifecycle::create_evm builds an EVM over the active context without copying its
accepted state: the EVM reads it through a shared view and its overlay only collects what the
execution reads and writes. ExecutionLifecycle::park accepts the EVM’s state back into the
active context, after a commit; dropping the EVM instead discards it, as for calls. Lifecycle
operations that capture or replace the running state (fork switches, snapshots, nested
transactions) first materialize the view into the EVM’s overlay, once.
§Execution phases
evm2 allows replacing state and the block environment while a transaction runs, but not the
spec or runtime Version, which also carries the chain ID. Operations that
need a different spec or chain ID while a transaction is in flight apply everything else at
once and record the rest as the pending environment (ExecutionLifecycle::pending_env);
ExecutionLifecycle::begin_transaction then applies it at the next transaction boundary.
Until then, the inspector stack runs frames started after the change on a frame EVM built with
the pending environment (ExecutionLifecycle::begin_frame_evm).
Suspending a context accepts its in-flight writes, so a fork switch is not undone when an enclosing call reverts.
Re-exports§
use super::AcceptedView;🔒use super::BackingDb;🔒use super::EvmEnv;🔒use super::ForkInfo;🔒use super::ForkPosition;🔒use super::ForkRegistry;🔒use super::FoundryEvmExt;🔒use super::FoundryEvmFactory;🔒use super::FoundryExecutionHooks;🔒use super::LifecycleSnapshot;🔒use super::Parked;🔒use super::StoredExt;🔒use super::evm_env;🔒use crate::backend::RevertStateSnapshotAction;🔒use crate::backend::transaction_error;🔒use crate::state_snapshot::StateSnapshots;🔒use alloy_consensus::Typed2718;🔒use alloy_consensus::transaction::Recovered;🔒use alloy_eips::eip2930::AccessList;🔒use alloy_primitives::Address;🔒use alloy_primitives::B256;🔒use alloy_primitives::KECCAK256_EMPTY;🔒use alloy_primitives::Log;🔒use alloy_primitives::U256;🔒use alloy_primitives::U512;🔒use alloy_primitives::aliases::I512;🔒use alloy_primitives::map::AddressMap;🔒use alloy_primitives::map::AddressSet;🔒use alloy_primitives::map::Entry;🔒use alloy_primitives::map::HashMap;🔒use alloy_primitives::map::HashSet;🔒use evm2::Evm;🔒use evm2::EvmFeatures;🔒use evm2::EvmTypes;🔒use evm2::ExecutedTx;🔒use evm2::Inspector;🔒use evm2::TxResult;🔒use evm2::TxResultWithState;🔒use evm2::bytecode::Bytecode;🔒use evm2::evm::AccountChanges;🔒use evm2::evm::AccountFlags;🔒use evm2::evm::AccountHandle;🔒use evm2::evm::AccountInfo;🔒use evm2::evm::Cache;🔒use evm2::evm::CacheDB;🔒use evm2::evm::DbResult;🔒use evm2::evm::DynDatabase;🔒use evm2::evm::EmptyDB;🔒use evm2::evm::JournalEntry;🔒use evm2::evm::PendingState;🔒use evm2::evm::PrewarmSet;🔒use evm2::evm::State;🔒use evm2::evm::StateCheckpoint;🔒use evm2::evm::StateSnapshot;🔒use std::iter;🔒use std::mem;🔒use std::sync::Arc;🔒
Structs§
- Destructed
Account - The state a nested transaction left an account in before the transaction ended and destroyed it, which the running transaction keeps until it ends itself.
- Executed
Nested - The outcome of a
PreparedTx, to store withExecutionLifecycle::store_executed. - Execution
Lifecycle - Fork, snapshot and nested-execution lifecycle for one EVM network family.
- Prepared
Tx - A transaction prepared to execute as a nested transaction of the running one, such as for
vm.transact, whose inspector may hold the lifecycle’s owner while it runs. - Suspended 🔒
- What a running transaction carries from a suspended context into the next one.
Enums§
- Execution
Phase - Whether a lifecycle operation runs between transactions or inside one, such as from a cheatcode.
- Persistent
Write - A write that must survive reverts of the enclosing calls, such as a cheatcode’s state edit. It
is applied as a journaled write, and the owner replays it after each enclosing call that
reverts. Balance and nonce writes replay as deltas, so they compose with value transfers and
nonce bumps undone by the revert, saturating at their bounds, unless their
Replaymode says otherwise. - Replay
- How a balance or nonce
PersistentWritereplays, ordered by precedence when combined.
Functions§
- apply_
account 🔒 - Sets the account at
addressinstatetoinfo, or to no account, and writesslotsto its storage after wiping it ifwiped, as journaled writes, also recorded inpersistentif given. Fields that already hold their value are left alone;codeis only built when the code hash changes. - cold_
account_ 🔒warm_ slots - Returns the warm slots of the
persistentaccounts the running transaction instateloaded but holds cold, such as the test contract after an isolated static call cooled it. - destructed_
accounts - Returns the accounts the running transaction in
stateself-destructed, with their state before the transaction ends and destroys them, such as at the end of the root frame of a nested transaction. - loaded_
slots 🔒 - Returns the accounts
stateloaded with their loaded slots. - merge_
changes 🔒 - Applies a nested transaction’s
changesto the accounts selected byfiltertostateas journaled writes, also recorded inpersistentif given. - merge_
pending_ changes - Applies the changes of a nested transaction detached into
pendingto the running transaction’sstateas journaled writes, so they revert with the enclosing call. - merge_
untracked_ nested_ changes - Applies a nested transaction’s changes to the running transaction’s
stateas journaled writes and returns them asPersistentWrites, for the caller to replay when an enclosing call reverts, such as forbroadcastRawTransaction. - merge_
untracked_ pending_ changes_ with_ warmth - Applies the changes of a nested transaction that
childran and detached intopendingto the running transaction’sstatelikemerge_untracked_nested_changes, and also warms the accounts and slots the nested transaction left warm, such as forexecuteTransaction. - put_
transient - Writes
transientstorage taken withtake_transientinto the running transaction instate. - rebase_
loaded_ 🔒accounts - Replaces the accounts the running transaction in
stateloaded, except persistent ones, with their accepted state insource, as journaled writes: info and loaded storage slots. - release_
inspector ⚠ - Clears
evm’s inspector and returns the EVM without the borrows the inspector held, such as to park an EVM whose inspector borrowed the lifecycle’s owner. - restore_
access_ warmth - Undoes, without journaling, the warmth that the running transaction in
stategained sincecheckpoint, keeping all other warmth, including unjournaled changes made since. - restore_
originals 🔒 - Turns the accepted values of the slots of
originalsin the freshstateback into pending writes of the running transaction over their transaction-start values. - take_
transient - Removes and returns the transient storage of the running transaction in
state, as address, key and value, sorted so writing it back is deterministic. - unloaded_
changes 🔒 - Returns the
changesto accounts and storage slots the running transaction instatehas not loaded, as a pending state to accept. Accounts that were created, self-destructed, wiped or given code are left out. - warm_
accounts - Returns the accounts the running transaction in
stateloaded and that are warm, with their warm slots. - warm_
set - Returns the warmth of the running transaction in
state: its base warm set and the accounts and slots it warmed, for a transaction that continues in a replaced state.
Type Aliases§
- Fork
Cursor - A fork’s canonical position and the network state retaining its block cursor.