Struct Backend

Source

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

Expand description

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

check if account is already loaded (hot)
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

Struct BackendCopy item path

§1. Empty in-memory Database

§2. Forked Database

§Fork swapping

§Snapshotting

Fields§

Implementations§

impl Backend

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

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

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

pub fn clone_empty(&self) -> Self

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>

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

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

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

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

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

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

pub fn has_state_snapshot_failure(&self) -> bool

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

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

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

pub fn mem_db(&self) -> &FoundryEvmInMemoryDB

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

pub fn is_in_forking_mode(&self) -> bool

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

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

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

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

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

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

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

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

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

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

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

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

fn set_init_journaled_state(&mut self, journaled_state: JournaledState)

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

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

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

Trait Implementations§

impl Clone for Backend

fn clone(&self) -> Backend

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

impl Database for Backend

type Error = DatabaseError

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

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

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

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

impl DatabaseCommit for Backend

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

impl DatabaseExt for Backend

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

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

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

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

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

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

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

fn delete_state_snapshots(&mut self)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Struct Backend

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

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

impl<T> Any for T
where T: 'static + ?Sized,

impl<T> Borrow<T> for T
where T: ?Sized,

impl<T> BorrowMut<T> for T
where T: ?Sized,

impl<T> CloneToUninit for T
where T: Clone,

fn collect_and_apply<I, F>(iter: I, f: F) -> R
where I: Iterator<Item = T>, F: FnOnce(&[T]) -> R,

fn conv<T>(self) -> T
where Self: Into<T>,

impl<T> DynClone for T
where T: Clone,

fn fmt_binary(self) -> FmtBinary<Self>
where Self: Binary,

fn fmt_display(self) -> FmtDisplay<Self>
where Self: Display,

fn fmt_lower_exp(self) -> FmtLowerExp<Self>
where Self: LowerExp,

fn fmt_lower_hex(self) -> FmtLowerHex<Self>
where Self: LowerHex,

fn fmt_octal(self) -> FmtOctal<Self>
where Self: Octal,

fn fmt_pointer(self) -> FmtPointer<Self>
where Self: Pointer,

fn fmt_upper_exp(self) -> FmtUpperExp<Self>
where Self: UpperExp,

fn fmt_upper_hex(self) -> FmtUpperHex<Self>
where Self: UpperHex,

fn fmt_list(self) -> FmtList<Self>
where &'a Self: for<'a> IntoIterator,

impl<T, U> Into<U> for T
where U: From<T>,

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

impl<T> Paint for T
where T: ?Sized,