verbs.envs.ForkEnvGasPriority#

class ForkEnvGasPriority#

Simulation environment initialised with a fork backend

Wraps an EVM and in-memory with a fork backend. This allows the EVM to retrieve data from a remote endpoint, to run simulation on forks of actual networks.

This environment sorts transactions by nonce and gas-priority, i.e. each step the queue queue of transactions is:

  • Grouped by transaction sender

  • Each group sorted by nonce

  • Groups sorted by the gas-priority fee of the first transaction

  • The sorted groups are flattened into a vector processing

Notes

Due to requests made by the backend this environment is a lot slower than a purely in memory deployment. One use-case is to run a simulation to retrieve storage values and contracts required for a simulation, then use the cache from this environment to initialise other in memory simulations.

Examples

# Here alchemy_url is url string to the alchemy API
env = verbs.envs.ForkEnvGasPriority(alchemy_url, 101, block_number=12345)
...
env.submit_call(...)

To then use the cache from this simulation to run subsequent simulations

cache = env.export_cache()

new_env = verbs.envs.EmptyEnv(101, cache=cache)
__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_cache()#

Export a cache of calls made by the DB

Exports a cache of requests made to the remote endpoint, i.e. requests for account data and storage values. This data can then be used to initialise the db for a purely local database for use in other simulations.

Examples

env = verbs.envs.ForkEnv(alchemy_url, 101, block_number=12345)
# Run simulation from fork
...
# Get cache of requests
cache = env.export_cache()
# Directly initialise a new environment from the cache
new_env = verbs.envs.EmptyEnv(101, cache=cache)
Returns:

list[tuple] – Tuple containing:

  • Env block timestamp

  • Env block number

  • List of account info requests

  • List of storage value requests

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