Struct Backend

pub struct Backend {
    forks: MultiFork,
    mem_db: FoundryEvmInMemoryDB,
    fork_init_journaled_state: JournaledState,
    active_fork_ids: Option<(LocalForkId, usize)>,
    inner: BackendInner,
}

Provides the underlying revm::Database implementation.

A Backend can be initialised in two forms:

1. Empty in-memory Database

This is the default variant: an empty revm::Database

2. Forked Database

A revm::Database that forks off a remote client

In addition to that we support forking manually on the fly. Additional forks can be created. Each unique fork is identified by its unique ForkId. We treat forks as unique if they have the same (endpoint, block number) pair.

When it comes to testing, it’s intended that each contract will use its own Backend (Backend::clone). This way each contract uses its own encapsulated evm state. For in-memory testing, the database is just an owned revm::InMemoryDB.

Each Fork, identified by a unique id, uses completely separate storage, write operations are performed only in the fork’s own database, ForkDB.

A ForkDB consists of 2 halves:

• everything fetched from the remote is readonly
• all local changes (instructed by the contract) are written to the backend’s db and don’t alter the state of the remote client.

Fork swapping

Multiple “forks” can be created Backend::create_fork(), however only 1 can be used by the db. However, their state can be hot-swapped by swapping the read half of db from one fork to another. When swapping forks (Backend::select_fork()) we also update the current Env of the EVM accordingly, so that all block.* config values match

When another for is selected DatabaseExt::select_fork() the entire storage, including JournaledState is swapped, but the storage of the caller’s and the test contract account is always cloned. This way a fork has entirely separate storage but data can still be shared across fork boundaries via stack and contract variables.

Snapshotting

A snapshot of the current overall state can be taken at any point in time. A snapshot is identified by a unique id that’s returned when a snapshot is created. A snapshot can only be reverted once. After a successful revert, the same snapshot id cannot be used again. Reverting a snapshot replaces the current active state with the snapshot state, the snapshot is deleted afterwards, as well as any snapshots taken after the reverted snapshot, (e.g.: reverting to id 0x1 will delete snapshots with ids 0x1, 0x2, etc.)

Note: State snapshots work across fork-swaps, e.g. if fork A is currently active, then a snapshot is created before fork B is selected, then fork A will be the active fork again after reverting the snapshot.

Fields

forks: MultiFork

The access point for managing forks

mem_db: FoundryEvmInMemoryDB

fork_init_journaled_state: JournaledState

The journaled_state to use to initialize new forks with

The way [revm::JournaledState] works is, that it holds the “hot” accounts loaded from the underlying Database that feeds the Account and State data to the journaled_state so it can apply changes to the state while the EVM executes.

In a way the JournaledState is something like a cache that

1. check if account is already loaded (hot)
2. if not load from the Database (this will then retrieve the account via RPC in forking mode)

To properly initialize we store the JournaledState before the first fork is selected (DatabaseExt::select_fork).

This will be an empty JournaledState, which will be populated with persistent accounts, See Self::update_fork_db().

active_fork_ids: Option<(LocalForkId, usize)>

The currently active fork database

If this is set, then the Backend is currently in forking mode

inner: BackendInner

holds additional Backend data

Implementations

impl Backend

pub fn spawn(fork: Option<CreateFork>) -> Self

Creates a new Backend with a spawned multi fork thread.

If fork is Some this will use a fork database, otherwise with an in-memory database.

pub fn new(forks: MultiFork, fork: Option<CreateFork>) -> Self

Creates a new instance of Backend

If fork is Some this will use a fork database, otherwise with an in-memory database.

Prefer using spawn instead.

pub(crate) fn new_with_fork( id: &ForkId, fork: Fork, journaled_state: JournaledState, ) -> Self

Creates a new instance of Backend with fork added to the fork database and sets the fork as active

pub fn clone_empty(&self) -> Self

Creates a new instance with a BackendDatabase::InMemory cache layer for the CacheDB

pub fn insert_account_info(&mut self, address: Address, account: AccountInfo)

pub fn insert_account_storage( &mut self, address: Address, slot: U256, value: U256, ) -> Result<(), DatabaseError>

Inserts a value on an account’s storage without overriding account info

pub fn replace_account_storage( &mut self, address: Address, storage: Map<U256, U256>, ) -> Result<(), DatabaseError>

Completely replace an account’s storage without overriding account info.

When forking, this causes the backend to assume a 0 value for all unset storage slots instead of trying to fetch it.

pub fn state_snapshots( &self, ) -> &StateSnapshots<BackendStateSnapshot<BackendDatabaseSnapshot>>

Returns all snapshots created in this backend

pub fn set_test_contract(&mut self, acc: Address) -> &mut Self

Sets the address of the DSTest contract that is being executed

This will also mark the caller as persistent and remove the persistent status from the previous test contract address

This will also grant cheatcode access to the test account

pub fn set_caller(&mut self, acc: Address) -> &mut Self

Sets the caller address

pub fn set_spec_id(&mut self, spec_id: SpecId) -> &mut Self

Sets the current spec id

pub fn caller_address(&self) -> Option<Address>

Returns the set caller address

pub fn has_state_snapshot_failure(&self) -> bool

Failures occurred in state snapshots are tracked when the state snapshot is reverted.

If an error occurs in a restored state snapshot, the test is considered failed.

This returns whether there was a reverted state snapshot that recorded an error.

pub fn set_state_snapshot_failure(&mut self, has_state_snapshot_failure: bool)

Sets the state snapshot failure flag.

pub(crate) fn update_fork_db( &self, active_journaled_state: &mut JournaledState, target_fork: &mut Fork, )

When creating or switching forks, we update the AccountInfo of the contract

pub(crate) fn update_fork_db_contracts( &self, accounts: impl IntoIterator<Item = Address>, active_journaled_state: &mut JournaledState, target_fork: &mut Fork, )

Merges the state of all accounts from the currently active db into the given fork

pub fn mem_db(&self) -> &FoundryEvmInMemoryDB

Returns the memory db used if not in forking mode

pub fn is_active_fork(&self, id: LocalForkId) -> bool

Returns true if the id is currently active

pub fn is_in_forking_mode(&self) -> bool

Returns true if the Backend is currently in forking mode

pub fn active_fork(&self) -> Option<&Fork>

Returns the currently active Fork, if any

pub fn active_fork_mut(&mut self) -> Option<&mut Fork>

Returns the currently active Fork, if any

pub fn active_fork_db(&self) -> Option<&CacheDB<SharedBackend>>

Returns the currently active ForkDB, if any

pub fn active_fork_db_mut(&mut self) -> Option<&mut CacheDB<SharedBackend>>

Returns the currently active ForkDB, if any

pub fn db(&self) -> &dyn Database<Error = DatabaseError>

Returns the current database implementation as a &dyn value.

pub fn db_mut(&mut self) -> &mut dyn Database<Error = DatabaseError>

Returns the current database implementation as a &mut dyn value.

pub(crate) fn create_db_snapshot(&self) -> BackendDatabaseSnapshot

Creates a snapshot of the currently active database

pub fn merged_logs(&self, logs: Vec<Log>) -> Vec<Log>

Since each Fork tracks logs separately, we need to merge them to get all of them

pub(crate) fn initialize(&mut self, env: &EnvWithHandlerCfg)

Initializes settings we need to keep track of.

We need to track these mainly to prevent issues when switching between different evms

fn env_with_handler_cfg(&self, env: Env) -> EnvWithHandlerCfg

Returns the EnvWithHandlerCfg with the current spec_id set.

pub fn inspect<I: InspectorExt>( &mut self, env: &mut EnvWithHandlerCfg, inspector: &mut I, ) -> Result<ResultAndState>

Executes the configured test call of the env without committing state changes.

Note: in case there are any cheatcodes executed that modify the environment, this will update the given env with the new values.

pub fn is_existing_precompile(&self, addr: &Address) -> bool

Returns true if the address is a precompile

fn set_init_journaled_state(&mut self, journaled_state: JournaledState)

Sets the initial journaled state to use when initializing forks

fn prepare_init_journal_state(&mut self) -> Result<(), BackendError>

Cleans up already loaded accounts that would be initialized without the correct data from the fork.

It can happen that an account is loaded before the first fork is selected, like getNonce(addr), which will load an empty account by default.

This account data then would not match the account data of a fork if it exists. So when the first fork is initialized we replace these accounts with the actual account as it exists on the fork.

fn get_block_number_and_block_for_transaction( &self, id: LocalForkId, transaction: B256, ) -> Result<(u64, Block<WithOtherFields<Transaction>>)>

Returns the block numbers required for replaying a transaction

pub fn replay_until( &mut self, id: LocalForkId, env: Env, tx_hash: B256, journaled_state: &mut JournaledState, ) -> Result<Option<Transaction>>

Replays all the transactions at the forks current block that were mined before the tx

Returns the unmined transaction that corresponds to the given tx_hash

Trait Implementations

impl Clone for Backend

fn clone(&self) -> Backend

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Database for Backend

type Error = DatabaseError

The database error type.

fn basic( &mut self, address: Address, ) -> Result<Option<AccountInfo>, Self::Error>

Get basic account information.

fn code_by_hash(&mut self, code_hash: B256) -> Result<Bytecode, Self::Error>

Get account code by its hash.

fn storage( &mut self, address: Address, index: U256, ) -> Result<U256, Self::Error>

Get storage value of address at index.

fn block_hash(&mut self, number: u64) -> Result<B256, Self::Error>

Get block hash by block number.

impl DatabaseCommit for Backend

fn commit(&mut self, changes: Map<Address, Account>)

Commit changes to the database.

impl DatabaseExt for Backend

fn select_fork( &mut self, id: LocalForkId, env: &mut Env, active_journaled_state: &mut JournaledState, ) -> Result<()>

Select an existing fork by id. When switching forks we copy the shared state

fn roll_fork( &mut self, id: Option<LocalForkId>, block_number: u64, env: &mut Env, journaled_state: &mut JournaledState, ) -> Result<()>

This is effectively the same as Self::create_select_fork() but updating an existing ForkId that is mapped to the LocalForkId

fn load_allocs( &mut self, allocs: &BTreeMap<Address, GenesisAccount>, journaled_state: &mut JournaledState, ) -> Result<(), BackendError>

Loads the account allocs from the given allocs map into the passed [JournaledState].

Returns Ok if all accounts were successfully inserted into the journal, Err otherwise.

fn clone_account( &mut self, source: &GenesisAccount, target: &Address, journaled_state: &mut JournaledState, ) -> Result<(), BackendError>

Copies bytecode, storage, nonce and balance from the given genesis account to the target address.

Returns Ok if data was successfully inserted into the journal, Err otherwise.

fn snapshot_state( &mut self, journaled_state: &JournaledState, env: &Env, ) -> U256

Creates a new state snapshot at the current point of execution.

fn revert_state( &mut self, id: U256, current_state: &JournaledState, current: &mut Env, action: RevertStateSnapshotAction, ) -> Option<JournaledState>

Reverts the snapshot if it exists

fn delete_state_snapshot(&mut self, id: U256) -> bool

Deletes the state snapshot with the given id

fn delete_state_snapshots(&mut self)

Deletes all state snapshots.

fn create_fork(&mut self, create_fork: CreateFork) -> Result<LocalForkId>

Creates a new fork but does not select it

fn create_fork_at_transaction( &mut self, fork: CreateFork, transaction: B256, ) -> Result<LocalForkId>

Creates a new fork but does not select it

fn roll_fork_to_transaction( &mut self, id: Option<LocalForkId>, transaction: B256, env: &mut Env, journaled_state: &mut JournaledState, ) -> Result<()>

Updates the fork to given transaction hash

fn transact( &mut self, maybe_id: Option<LocalForkId>, transaction: B256, env: Env, journaled_state: &mut JournaledState, inspector: &mut dyn InspectorExt, ) -> Result<()>

Fetches the given transaction for the fork and executes it, committing the state in the DB

fn transact_from_tx( &mut self, tx: &TransactionRequest, env: Env, journaled_state: &mut JournaledState, inspector: &mut dyn InspectorExt, ) -> Result<()>

Executes a given TransactionRequest, commits the new state to the DB

fn active_fork_id(&self) -> Option<LocalForkId>

Returns the ForkId that’s currently used in the database, if fork mode is on

fn active_fork_url(&self) -> Option<String>

Returns the Fork url that’s currently used in the database, if fork mode is on

fn ensure_fork(&self, id: Option<LocalForkId>) -> Result<LocalForkId>

Ensures that an appropriate fork exists

fn ensure_fork_id(&self, id: LocalForkId) -> Result<&ForkId>

Ensures that a corresponding ForkId exists for the given local id

fn diagnose_revert( &self, callee: Address, journaled_state: &JournaledState, ) -> Option<RevertDiagnostic>

Handling multiple accounts/new contracts in a multifork environment can be challenging since every fork has its own standalone storage section. So this can be a common error to run into:

fn add_persistent_account(&mut self, account: Address) -> bool

Marks the given account as persistent.

fn remove_persistent_account(&mut self, account: &Address) -> bool

Revokes persistent status from the given account.

fn is_persistent(&self, acc: &Address) -> bool

Returns true if the given account is currently marked as persistent.

fn allow_cheatcode_access(&mut self, account: Address) -> bool

Grants cheatcode access for the given account

fn revoke_cheatcode_access(&mut self, account: &Address) -> bool

Revokes cheatcode access for the given account

fn has_cheatcode_access(&self, account: &Address) -> bool

Returns true if the given account is allowed to execute cheatcodes

fn set_blockhash(&mut self, block_number: U256, block_hash: B256)

Set the blockhash for a given block number.

fn create_select_fork( &mut self, fork: CreateFork, env: &mut Env, journaled_state: &mut JournaledState, ) -> Result<LocalForkId>

Creates and also selects a new fork

fn create_select_fork_at_transaction( &mut self, fork: CreateFork, env: &mut Env, journaled_state: &mut JournaledState, transaction: B256, ) -> Result<LocalForkId>

Creates and also selects a new fork

fn is_forked_mode(&self) -> bool

Whether the database is currently in forked mode.

fn remove_persistent_accounts( &mut self, accounts: impl IntoIterator<Item = Address>, )

where Self: Sized,

Removes persistent status from all given accounts.

fn extend_persistent_accounts( &mut self, accounts: impl IntoIterator<Item = Address>, )

where Self: Sized,

Extends the persistent accounts with the accounts the iterator yields.

fn ensure_cheatcode_access(&self, account: &Address) -> Result<(), BackendError>

Ensures that account is allowed to execute cheatcodes

fn ensure_cheatcode_access_forking_mode( &self, account: &Address, ) -> Result<(), BackendError>

Same as Self::ensure_cheatcode_access() but only enforces it if the backend is currently in forking mode

impl DatabaseRef for Backend

type Error = DatabaseError

The database error type.

fn basic_ref( &self, address: Address, ) -> Result<Option<AccountInfo>, Self::Error>

Get basic account information.

fn code_by_hash_ref(&self, code_hash: B256) -> Result<Bytecode, Self::Error>

Get account code by its hash.

fn storage_ref( &self, address: Address, index: U256, ) -> Result<U256, Self::Error>

Get storage value of address at index.

fn block_hash_ref(&self, number: u64) -> Result<B256, Self::Error>

Get block hash by block number.

impl Debug for Backend

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 816 bytes