Skip to main content

Module lifecycle

Module lifecycle 

Source
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§

DestructedAccount
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.
ExecutedNested
The outcome of a PreparedTx, to store with ExecutionLifecycle::store_executed.
ExecutionLifecycle
Fork, snapshot and nested-execution lifecycle for one EVM network family.
PreparedTx
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§

ExecutionPhase
Whether a lifecycle operation runs between transactions or inside one, such as from a cheatcode.
PersistentWrite
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 Replay mode says otherwise.
Replay
How a balance or nonce PersistentWrite replays, ordered by precedence when combined.

Functions§

apply_account 🔒
Sets the account at address in state to info, or to no account, and writes slots to its storage after wiping it if wiped, as journaled writes, also recorded in persistent if given. Fields that already hold their value are left alone; code is only built when the code hash changes.
cold_account_warm_slots 🔒
Returns the warm slots of the persistent accounts the running transaction in state loaded but holds cold, such as the test contract after an isolated static call cooled it.
destructed_accounts
Returns the accounts the running transaction in state self-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 state loaded with their loaded slots.
merge_changes 🔒
Applies a nested transaction’s changes to the accounts selected by filter to state as journaled writes, also recorded in persistent if given.
merge_pending_changes
Applies the changes of a nested transaction detached into pending to the running transaction’s state as journaled writes, so they revert with the enclosing call.
merge_untracked_nested_changes
Applies a nested transaction’s changes to the running transaction’s state as journaled writes and returns them as PersistentWrites, for the caller to replay when an enclosing call reverts, such as for broadcastRawTransaction.
merge_untracked_pending_changes_with_warmth
Applies the changes of a nested transaction that child ran and detached into pending to the running transaction’s state like merge_untracked_nested_changes, and also warms the accounts and slots the nested transaction left warm, such as for executeTransaction.
put_transient
Writes transient storage taken with take_transient into the running transaction in state.
rebase_loaded_accounts 🔒
Replaces the accounts the running transaction in state loaded, except persistent ones, with their accepted state in source, 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 state gained since checkpoint, keeping all other warmth, including unjournaled changes made since.
restore_originals 🔒
Turns the accepted values of the slots of originals in the fresh state back 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 changes to accounts and storage slots the running transaction in state has 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 state loaded 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§

ForkCursor
A fork’s canonical position and the network state retaining its block cursor.