Struct Cheatcodes

pub struct Cheatcodes {

    pub block: Option<BlockEnv>,
    pub active_delegation: Option<SignedAuthorization>,
    pub gas_price: Option<U256>,
    pub labels: AddressHashMap<String>,
    pub prank: Option<Prank>,
    pub expected_revert: Option<ExpectedRevert>,
    pub assume_no_revert: Option<AssumeNoRevert>,
    pub fork_revert_diagnostic: Option<RevertDiagnostic>,
    pub accesses: Option<RecordAccess>,
    pub recorded_account_diffs_stack: Option<Vec<Vec<AccountAccess>>>,
    pub record_debug_steps_info: Option<RecordDebugStepInfo>,
    pub recorded_logs: Option<Vec<Log>>,
    pub mocked_calls: HashMap<Address, BTreeMap<MockCallDataContext, VecDeque<MockCallReturnData>>>,
    pub mocked_functions: HashMap<Address, HashMap<Bytes, Address>>,
    pub expected_calls: ExpectedCallTracker,
    pub expected_emits: VecDeque<(ExpectedEmit, AddressHashMap<LogCountMap>)>,
    pub allowed_mem_writes: HashMap<u64, Vec<Range<u64>>>,
    pub broadcast: Option<Broadcast>,
    pub broadcastable_transactions: BroadcastableTransactions,
    pub config: Arc<CheatsConfig>,
    pub context: Context,
    pub fs_commit: bool,
    pub serialized_jsons: BTreeMap<String, BTreeMap<String, Value>>,
    pub eth_deals: Vec<DealRecord>,
    pub gas_metering: GasMetering,
    pub gas_snapshots: BTreeMap<String, BTreeMap<String, String>>,
    pub mapping_slots: Option<AddressHashMap<MappingSlots>>,
    pub pc: usize,
    pub breakpoints: Breakpoints,
    test_runner: Option<TestRunner>,
    pub ignored_traces: IgnoredTraces,
    pub arbitrary_storage: Option<ArbitraryStorage>,
    pub deprecated: HashMap<&'static str, Option<&'static str>>,
    pub wallets: Option<Wallets>,
}

An EVM inspector that handles calls to various cheatcodes, each with their own behavior.

Cheatcodes can be called by contracts during execution to modify the VM environment, such as mocking addresses, signatures and altering call reverts.

Executing cheatcodes can be very powerful. Most cheatcodes are limited to evm internals, but there are also cheatcodes like ffi which can execute arbitrary commands or writeFile and readFile which can manipulate files of the filesystem. Therefore, several restrictions are implemented for these cheatcodes:

• ffi, and file cheatcodes are always opt-in (via foundry config) and never enabled by default: all respective cheatcode handlers implement the appropriate checks
• File cheatcodes require explicit permissions which paths are allowed for which operation, see Config.fs_permission
• Only permitted accounts are allowed to execute cheatcodes in forking mode, this ensures no contract deployed on the live network is able to execute cheatcodes by simply calling the cheatcode address: by default, the caller, test contract and newly deployed contracts are allowed to execute cheatcodes

Fields

block: Option<BlockEnv>

The block environment

Used in the cheatcode handler to overwrite the block environment separately from the execution block environment.

active_delegation: Option<SignedAuthorization>

Currently active EIP-7702 delegation that will be consumed when building the next transaction. Set by vm.attachDelegation() and consumed via .take() during transaction construction.

gas_price: Option<U256>

The gas price.

Used in the cheatcode handler to overwrite the gas price separately from the gas price in the execution environment.

labels: AddressHashMap<String>

Address labels

prank: Option<Prank>

Prank information

expected_revert: Option<ExpectedRevert>

Expected revert information

assume_no_revert: Option<AssumeNoRevert>

Assume next call can revert and discard fuzz run if it does.

fork_revert_diagnostic: Option<RevertDiagnostic>

Additional diagnostic for reverts

accesses: Option<RecordAccess>

Recorded storage reads and writes

recorded_account_diffs_stack: Option<Vec<Vec<AccountAccess>>>

Recorded account accesses (calls, creates) organized by relative call depth, where the topmost vector corresponds to accesses at the depth at which account access recording began. Each vector in the matrix represents a list of accesses at a specific call depth. Once that call context has ended, the last vector is removed from the matrix and merged into the previous vector.

record_debug_steps_info: Option<RecordDebugStepInfo>

The information of the debug step recording.

recorded_logs: Option<Vec<Log>>

Recorded logs

mocked_calls: HashMap<Address, BTreeMap<MockCallDataContext, VecDeque<MockCallReturnData>>>

Mocked calls

mocked_functions: HashMap<Address, HashMap<Bytes, Address>>

Mocked functions. Maps target address to be mocked to pair of (calldata, mock address).

expected_calls: ExpectedCallTracker

Expected calls

expected_emits: VecDeque<(ExpectedEmit, AddressHashMap<LogCountMap>)>

Expected emits

allowed_mem_writes: HashMap<u64, Vec<Range<u64>>>

Map of context depths to memory offset ranges that may be written to within the call depth.

broadcast: Option<Broadcast>

Current broadcasting information

broadcastable_transactions: BroadcastableTransactions

Scripting based transactions

config: Arc<CheatsConfig>

Additional, user configurable context this Inspector has access to when inspecting a call.

context: Context

Test-scoped context holding data that needs to be reset every test run

fs_commit: bool

Whether to commit FS changes such as file creations, writes and deletes. Used to prevent duplicate changes file executing non-committing calls.

serialized_jsons: BTreeMap<String, BTreeMap<String, Value>>

Serialized JSON values.

eth_deals: Vec<DealRecord>

All recorded ETH deals.

gas_metering: GasMetering

Gas metering state.

gas_snapshots: BTreeMap<String, BTreeMap<String, String>>

Contains gas snapshots made over the course of a test suite.

mapping_slots: Option<AddressHashMap<MappingSlots>>

Mapping slots.

pc: usize

The current program counter.

breakpoints: Breakpoints

Breakpoints supplied by the breakpoint cheatcode. char -> (address, pc)

test_runner: Option<TestRunner>

Optional cheatcodes TestRunner. Used for generating random values from uint and int strategies.

ignored_traces: IgnoredTraces

Ignored traces.

arbitrary_storage: Option<ArbitraryStorage>

Addresses with arbitrary storage.

deprecated: HashMap<&'static str, Option<&'static str>>

Deprecated cheatcodes mapped to the reason. Used to report warnings on test results.

wallets: Option<Wallets>

Unlocked wallets used in scripts and testing of scripts.

Implementations

impl Cheatcodes

pub fn new(config: Arc<CheatsConfig>) -> Self

Creates a new Cheatcodes with the given settings.

pub fn wallets(&mut self) -> &Wallets

Returns the configured wallets if available, else creates a new instance.

pub fn set_wallets(&mut self, wallets: Wallets)

Sets the unlocked wallets.

fn apply_cheatcode( &mut self, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, call: &CallInputs, executor: &mut dyn CheatcodesExecutor, ) -> Result

Decodes the input data and applies the cheatcode.

fn allow_cheatcodes_on_create( &self, ecx: &'_ mut InnerEvmContext<&'_ mut (dyn DatabaseExt + '_)>, caller: Address, created_address: Address, )

Grants cheat code access for new contracts if the caller also has cheatcode access or the new contract is created in top most call.

There may be cheatcodes in the constructor of the new contract, in order to allow them automatically we need to determine the new address.

pub fn on_revert( &mut self, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, )

Called when there was a revert.

Cleanup any previously applied cheatcodes that altered the state in such a way that revm’s revert would run into issues.

fn create_common<Input>( &mut self, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, input: Input, ) -> Option<CreateOutcome>

where Input: CommonCreateInput,

fn create_end_common( &mut self, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, outcome: CreateOutcome, ) -> CreateOutcome

pub fn call_with_executor( &mut self, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, call: &mut CallInputs, executor: &mut impl CheatcodesExecutor, ) -> Option<CallOutcome>

pub fn rng(&mut self) -> &mut impl Rng

pub fn test_runner(&mut self) -> &mut TestRunner

pub fn arbitrary_storage(&mut self) -> &mut ArbitraryStorage

Returns existing or set a default ArbitraryStorage option. Used by setArbitraryStorage cheatcode to track addresses with arbitrary storage.

pub fn has_arbitrary_storage(&self, address: &Address) -> bool

Whether the given address has arbitrary storage.

pub fn is_arbitrary_storage_copy(&self, address: &Address) -> bool

Whether the given address is a copy of an address with arbitrary storage.

impl Cheatcodes

fn meter_gas(&mut self, interpreter: &mut Interpreter)

fn meter_gas_record( &mut self, interpreter: &mut Interpreter, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, )

fn meter_gas_end(&mut self, interpreter: &mut Interpreter)

fn meter_gas_reset(&mut self, interpreter: &mut Interpreter)

fn meter_gas_check(&mut self, interpreter: &mut Interpreter)

fn arbitrary_storage_end( &mut self, interpreter: &mut Interpreter, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, )

Generates or copies arbitrary values for storage slots. Invoked in inspector step_end (when the current opcode is not executed), if current opcode to execute is SLOAD and storage slot is cold. Ensures that in next step (when SLOAD opcode is executed) an arbitrary value is returned:

• copies the existing arbitrary storage value (or the new generated one if no value in cache) from mapped source address to the target address.
• generates arbitrary value and saves it in target address storage.

fn record_accesses(&mut self, interpreter: &mut Interpreter)

Records storage slots reads and writes.

fn record_state_diffs( &mut self, interpreter: &mut Interpreter, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, )

fn check_mem_opcodes(&self, interpreter: &mut Interpreter, depth: u64)

Checks to see if the current opcode can either mutate directly or expand memory.

If the opcode at the current program counter is a match, check if the modified memory lies within the allowed ranges. If not, revert and fail the test.

Trait Implementations

impl Clone for Cheatcodes

fn clone(&self) -> Cheatcodes

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Cheatcodes

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

Formats the value using the given formatter.

impl Default for Cheatcodes

fn default() -> Self

Returns the “default value” for a type.

impl Inspector<&mut dyn DatabaseExt<Error = DatabaseError>> for Cheatcodes

fn initialize_interp( &mut self, interpreter: &mut Interpreter, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, )

Called before the interpreter is initialized.

fn step( &mut self, interpreter: &mut Interpreter, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, )

Called on each step of the interpreter.

fn step_end( &mut self, interpreter: &mut Interpreter, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, )

Called after step when the instruction has been executed.

fn log( &mut self, interpreter: &mut Interpreter, _ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, log: &Log, )

Called when a log is emitted.

fn call( &mut self, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, inputs: &mut CallInputs, ) -> Option<CallOutcome>

Called whenever a call to a contract is about to start.

fn call_end( &mut self, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, call: &CallInputs, outcome: CallOutcome, ) -> CallOutcome

Called when a call to a contract has concluded.

fn create( &mut self, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, call: &mut CreateInputs, ) -> Option<CreateOutcome>

Called when a contract is about to be created.

fn create_end( &mut self, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, _call: &CreateInputs, outcome: CreateOutcome, ) -> CreateOutcome

Called when a contract has been created.

fn eofcreate( &mut self, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, call: &mut EOFCreateInputs, ) -> Option<CreateOutcome>

Called when EOF creating is called.

fn eofcreate_end( &mut self, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, _call: &EOFCreateInputs, outcome: CreateOutcome, ) -> CreateOutcome

Called when eof creating has ended.

fn selfdestruct( &mut self, contract: Address, target: Address, value: Uint<256, 4>, )

Called when a contract has been self-destructed with funds transferred to target.

impl InspectorExt for Cheatcodes

fn should_use_create2_factory( &mut self, ecx: &'_ mut EvmContext<&'_ mut (dyn DatabaseExt + '_)>, inputs: &mut CreateInputs, ) -> bool

Determines whether the DEFAULT_CREATE2_DEPLOYER should be used for a CREATE2 frame.

fn create2_deployer(&self) -> Address

Returns the CREATE2 deployer address.

fn console_log(&mut self, _input: String)

Simulates console.log invocation.

fn is_odyssey(&self) -> bool

Returns true if the current network is Odyssey.

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