Struct Executor

pub struct Executor {
    backend: Backend,
    env: EnvWithHandlerCfg,
    inspector: InspectorStack,
    gas_limit: u64,
    legacy_assertions: bool,
}

EVM executor.

The executor can be configured with various revm::Inspectors, like Cheatcodes.

There are multiple ways of interacting the EVM:

• call: executes a transaction, but does not persist any state changes; similar to eth_call, where the EVM state is unchanged after the call.
• transact: executes a transaction and persists the state changes
• deploy: a special case of transact, specialized for persisting the state of a contract deployment
• setup: a special case of transact, used to set up the environment for a test

Fields

backend: Backend

The underlying revm::Database that contains the EVM storage.

env: EnvWithHandlerCfg

The EVM environment.

inspector: InspectorStack

The Revm inspector stack.

gas_limit: u64

The gas limit for calls and deployments.

legacy_assertions: bool

Whether failed() should be called on the test contract to determine if the test failed.

Implementations

impl Executor

pub fn builder() -> ExecutorBuilder

Creates a new ExecutorBuilder.

pub fn new( backend: Backend, env: EnvWithHandlerCfg, inspector: InspectorStack, gas_limit: u64, legacy_assertions: bool, ) -> Self

Creates a new Executor with the given arguments.

fn clone_with_backend(&self, backend: Backend) -> Self

pub fn backend(&self) -> &Backend

Returns a reference to the EVM backend.

pub fn backend_mut(&mut self) -> &mut Backend

Returns a mutable reference to the EVM backend.

pub fn env(&self) -> &Env

Returns a reference to the EVM environment.

pub fn env_mut(&mut self) -> &mut Env

Returns a mutable reference to the EVM environment.

pub fn inspector(&self) -> &InspectorStack

Returns a reference to the EVM inspector.

pub fn inspector_mut(&mut self) -> &mut InspectorStack

Returns a mutable reference to the EVM inspector.

pub fn spec_id(&self) -> SpecId

Returns the EVM spec ID.

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

Sets the EVM spec ID.

pub fn gas_limit(&self) -> u64

Returns the gas limit for calls and deployments.

This is different from the gas limit imposed by the passed in environment, as those limits are used by the EVM for certain opcodes like gaslimit.

pub fn set_gas_limit(&mut self, gas_limit: u64)

Sets the gas limit for calls and deployments.

pub fn legacy_assertions(&self) -> bool

Returns whether failed() should be called on the test contract to determine if the test failed.

pub fn set_legacy_assertions(&mut self, legacy_assertions: bool)

Sets whether failed() should be called on the test contract to determine if the test failed.

pub fn deploy_create2_deployer(&mut self) -> Result<()>

Creates the default CREATE2 Contract Deployer for local tests and scripts.

pub fn set_balance( &mut self, address: Address, amount: U256, ) -> BackendResult<()>

Set the balance of an account.

pub fn get_balance(&self, address: Address) -> BackendResult<U256>

Gets the balance of an account

pub fn set_nonce(&mut self, address: Address, nonce: u64) -> BackendResult<()>

Set the nonce of an account.

pub fn get_nonce(&self, address: Address) -> BackendResult<u64>

Returns the nonce of an account.

pub fn is_empty_code(&self, address: Address) -> BackendResult<bool>

Returns true if the account has no code.

pub fn set_tracing(&mut self, mode: TraceMode) -> &mut Self

pub fn set_trace_printer(&mut self, trace_printer: bool) -> &mut Self

pub fn create2_deployer(&self) -> Address

pub fn deploy( &mut self, from: Address, code: Bytes, value: U256, rd: Option<&RevertDecoder>, ) -> Result<DeployResult, EvmError>

Deploys a contract and commits the new state to the underlying database.

Executes a CREATE transaction with the contract code and persistent database state modifications.

pub fn deploy_with_env( &mut self, env: EnvWithHandlerCfg, rd: Option<&RevertDecoder>, ) -> Result<DeployResult, EvmError>

Deploys a contract using the given env and commits the new state to the underlying database.

Panics

Panics if env.tx.transact_to is not TxKind::Create(_).

pub fn setup( &mut self, from: Option<Address>, to: Address, rd: Option<&RevertDecoder>, ) -> Result<RawCallResult, EvmError>

Calls the setUp() function on a contract.

This will commit any state changes to the underlying database.

Ayn changes made during the setup call to env’s block environment are persistent, for example vm.chainId() will change the block.chainId for all subsequent test calls.

pub fn call( &self, from: Address, to: Address, func: &Function, args: &[DynSolValue], value: U256, rd: Option<&RevertDecoder>, ) -> Result<CallResult, EvmError>

Performs a call to an account on the current state of the VM.

pub fn call_sol<C: SolCall>( &self, from: Address, to: Address, args: &C, value: U256, rd: Option<&RevertDecoder>, ) -> Result<CallResult<C::Return>, EvmError>

Performs a call to an account on the current state of the VM.

pub fn transact( &mut self, from: Address, to: Address, func: &Function, args: &[DynSolValue], value: U256, rd: Option<&RevertDecoder>, ) -> Result<CallResult, EvmError>

Performs a call to an account on the current state of the VM.

pub fn call_raw( &self, from: Address, to: Address, calldata: Bytes, value: U256, ) -> Result<RawCallResult>

Performs a raw call to an account on the current state of the VM.

pub fn call_raw_with_authorization( &mut self, from: Address, to: Address, calldata: Bytes, value: U256, authorization_list: Vec<SignedAuthorization>, ) -> Result<RawCallResult>

Performs a raw call to an account on the current state of the VM with an EIP-7702 authorization list.

pub fn transact_raw( &mut self, from: Address, to: Address, calldata: Bytes, value: U256, ) -> Result<RawCallResult>

Performs a raw call to an account on the current state of the VM.

pub fn call_with_env(&self, env: EnvWithHandlerCfg) -> Result<RawCallResult>

Execute the transaction configured in env.tx.

The state after the call is not persisted.

pub fn transact_with_env( &mut self, env: EnvWithHandlerCfg, ) -> Result<RawCallResult>

Execute the transaction configured in env.tx.

fn commit(&mut self, result: &mut RawCallResult)

Commit the changeset to the database and adjust self.inspector_config values according to the executed call result.

This should not be exposed to the user, as it should be called only by transact*.

pub fn is_raw_call_mut_success( &self, address: Address, call_result: &mut RawCallResult, should_fail: bool, ) -> bool

Returns true if a test can be considered successful.

This is the same as Self::is_success, but will consume the state_changeset map to use internally when calling failed().

pub fn is_raw_call_success( &self, address: Address, state_changeset: Cow<'_, StateChangeset>, call_result: &RawCallResult, should_fail: bool, ) -> bool

Returns true if a test can be considered successful.

This is the same as Self::is_success, but intended for outcomes of Self::call_raw.

pub fn is_success( &self, address: Address, reverted: bool, state_changeset: Cow<'_, StateChangeset>, should_fail: bool, ) -> bool

Returns true if a test can be considered successful.

If the call succeeded, we also have to check the global and local failure flags.

These are set by the test contract itself when an assertion fails, using the internal fail function. The global flag is located in CHEATCODE_ADDRESS at slot GLOBAL_FAIL_SLOT, and the local flag is located in the test contract at an unspecified slot.

This behavior is inherited from Dapptools, where initially only a public failed variable was used to track test failures, and later, a global failure flag was introduced to track failures across multiple contracts in ds-test#30.

The assumption is that the test runner calls failed on the test contract to determine if it failed. However, we want to avoid this as much as possible, as it is relatively expensive to set up an EVM call just for checking a single boolean flag.

See:

• Newer DSTest: https://github.com/dapphub/ds-test/blob/e282159d5170298eb2455a6c05280ab5a73a4ef0/src/test.sol#L47-L63
• Older DSTest: https://github.com/dapphub/ds-test/blob/9ca4ecd48862b40d7b0197b600713f64d337af12/src/test.sol#L38-L49
• forge-std: https://github.com/foundry-rs/forge-std/blob/19891e6a0b5474b9ea6827ddb90bb9388f7acfc0/src/StdAssertions.sol#L38-L44

fn is_success_raw( &self, address: Address, reverted: bool, state_changeset: Cow<'_, StateChangeset>, ) -> bool

fn build_test_env( &self, caller: Address, transact_to: TxKind, data: Bytes, value: U256, ) -> EnvWithHandlerCfg

Creates the environment to use when executing a transaction in a test context

If using a backend with cheatcodes, tx.gas_price and block.number will be overwritten by the cheatcode state in between calls.

pub fn call_sol_default<C: SolCall>(&self, to: Address, args: &C) -> C::Return

where C::Return: Default,

Trait Implementations

impl Clone for Executor

fn clone(&self) -> Executor

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Executor

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: 3728 bytes