verbs.envs.EmptyEnvRandom#

class EmptyEnvRandom#

Simulation environment initialised with an empty in-memory database

Wraps an EVM and in-memory db along with additional functionality for simulation updates and event tracking. This environment can also be initialised from a snapshot to speed up simulation initialisation.

This environment randomly shuffles transactions for inclusion in the next block during a simulation.

Examples

# Initialise a completely empty db
env = EmptyEnvRandom(101)
# Or initialise from a snapshot
env = EmptyEnvRandom(101, snapshot=snapshot)
# Or load a cache from a previous forked run
env = EmptyEnvRandom(101, cache=cache)
...
env.submit_call(...)
__new__(**kwargs)#
call(sender: bytes, contract_address: bytes, encoded_args: bytes, value: int) → tuple[bytes, list, int]#

Directly call the EVM

Call the EVM and return the result and events. This does not update the state of the EVM.

Parameters:

  • sender (bytes) – Address of the transaction sender.

  • contract_address (bytes) – Address of the contract to call.

  • encoded_args (bytes) – ABI encoded function selector and arguments

  • value (int) – Value attached to this transaction.

Returns:

tuple[bytes, list[tuple], int] – Tuple containing optional, byte-encoded results of the transaction, and list of logs generated by the transaction.

Raises:

verbs.envs.RevertError – Raises an exception if the transaction is reverted.

create_account(address: bytes, start_balance: int)#

Create an account

Create a new account with balance of ETH.

Parameters:

  • address (bytes) – Address to deploy account to

  • start_balance (int) – Starting ETH balance of the account (in wei)

deploy_contract(deployer: bytes, contract_name: str, bytecode: bytes) → bytes#

Deploy a contract

Deploys a contract to the EVM by calling the constructor.

Parameters:

  • deployer (bytes) – Byte encoded address of the deployer.

  • contract_name (str) – Name of the contract to deploy, only used for logging/debugging purposes.

  • bytecode (bytes) – Contract deployment bytecode and ABI encoded constructor arguments.

Returns:

bytes – Byte encoded address that contract is deployed to.

execute(sender: bytes, contract_address: bytes, encoded_args: bytes, value: int) → tuple[bytes, list, int]#

Directly execute a transaction

Execute a transaction and return the result and events. This update the state of the EVM.

Parameters:

  • sender (bytes) – Address of the transaction sender.

  • contract_address (bytes) – Address of the contract to call.

  • encoded_args (bytes) – ABI encoded function selector and arguments

  • value (int) – Value attached to the transaction

Returns:

tuple[bytes, list[tuple]] – Tuple containing optional, byte-encoded results of the transaction, and list of logs generated by the transaction.

Raises:

verbs.envs.RevertError – Raises an exception if the transaction is reverted.

export_snapshot()#

Export a snap shot of the EVM state and block parameters

Creates a copy of the EVM storage and state of the current block in a format that can be exported to Python. This snapshot can then be used to initialise new simulation environments.

get_event_history()#

Returns a list of events/logs generated over the course of the simulation. Events are a tuple containing:

  • Boolean indicating if the transaction was successful

  • The selector of the function called

  • A vector of logs

  • The step the event was generated

  • The order the event was created inside a block

Returns:

list[tuple] – List of events

get_last_events()#

Get a list of events/logs generated in the last block

Returns a list of events/logs generated in the last block. Events are a tuple containing:

  • The selector of the function called

  • A vector of logs

  • The step the event was generated

  • The order the event was created inside a block

Returns:

list[tuple] – List of events

process_block()#

Process the next block in the simulation

Update the state of the simulation by processing the next simulated block. This performs several steps:

  • Update the simulated time and block number

  • Sort the queue of calls submitted by agents

  • Process the queue of calls, updating the state of the EVM

  • Store any events generated by the transactions in this block

step#

Current step (i.e. block) of the simulation

Returns:

int – Current step of the simulation.

submit_transaction(sender: bytes, transact_to: bytes, encoded_args: bytes, checked: bool, gas_priority_fee: int = None, nonce: int = None, value: int = None)#

Submit a transaction into the next block

Submit a transaction into the queue to be processed in the next block. Each simulation step agents submit calls which are then shuffled and processed to update the EVM state.Value, nonce and gas-priority-fee are optional values required for a transaction.

Parameters:

  • sender (bytes) – Byte encoded address of the transaction sender.

  • transact_to (bytes) – Byte encoded address of the contract to call.

  • encoded_args (bytes) – ABI encoded function selector and arguments.

  • checked (bool) – If True the simulation will halt if this transaction is reverted.

  • gas_priority_fee (int, optional) – Transaction priority fee, default value is None

  • nonce (int, optional) – Transaction nonce

  • value (int, optional) –

submit_transactions(transactions)#

submit_basic_transactions(transactions: list[tuple[bytes, bytes, bytes, bool, int, int, int]])

Submit a list of transactions into the next block

Submit a list of transaction into the queue to be processed in the next block. Each simulation step agents submit calls which are then shuffled and processed to update the EVM state.

Parameters:

transactions (list[tuple[bytes, bytes, bytes, bool]]) –

List of transactions, where a transaction is a tuple containing:

  • The byte encoded address of the sender

  • The byte encoded address of the contract

  • The ABI byte encoded arguments and function selector

  • Flag if True means the simulation will halt if this transaction fails

  • Gas-priority-fee, integer or a value of None means no fee provided

  • Transaction nonce, integer or a value of None is ignored

  • Value assigned to the transaction, integer or None is treated as 0