verbs.sim.Sim#

class Sim[source]#

Simulation state and execution class

This class wraps the environment, agents and seeded random number generation. A sim can be initialised from either an empty environment (i.e one with no deployed contracts/accounts) of from a backend that fetches data from a remote fork.

__init__(seed: int, env: EmptyEnvRandom | EmptyEnvGasPriority | ForkEnvRandom | ForkEnvGasPriority, agents: List[BaseAgent] | None = None)[source]#
Parameters:

  • seed (int) – Random seed to initialise the simulation and key for use during execution

  • network – Initialised simulation environment/network

  • agents (list[BaseAgent], optional) – List of agents to include in the simulation. Default value is an empty list, allowing agents to be pushed after the simulation is initialised.

classmethod empty(agents: List[BaseAgent] | None = None, snapshot=None, cache: Tuple[int, int, List[Tuple[bytes, Tuple[bytes, int, bytes, bytes]]], List[Tuple[bytes, bytes, bytes]]] | None = None, gas_priority: bool = False)[source]#

Initialise a simulation with an empty environment

Initialise a simulation, initialising a fresh environment (i.e. one that contains no accounts, contracts etc.).

Parameters:

  • seed (int) – Random seed to initialise the simulation and key for use during execution.

  • agents (list[BaseAgent], optional) – List of agents to include in the simulation. Default value is an empty list, allowing agents to be pushed after the simulation is initialised.

  • snapshot – Optional snapshot used to initialise the simulation environment.

  • cache – Optional cache used to initialise the simulation environment.

  • gas_priority (bool, optional) – If True gas-priority sorting will be used to order transactions in each new simulation step/block. Otherwise transactions will be randomly shuffled. Default value if False.

Returns:

Sim – Initialised empty simulation.

classmethod fork(block_number: int, seed: int, agents: List[BaseAgent] | None = None, gas_priority: bool = False)[source]#

Initialise a simulation from a fork

Initialise a simulation, initialising an environment using a forked backend. This backend can be used to fetch database values from a remote fork of the network state.

Note

Since the EVM in this simulation fetches data from a remote endpoint during execution, this simulation runner can be considerably slower than the purely in memory version.

Parameters:

  • node_url (str) – Url used to fetch data from, for example an alchemy API endpoint.

  • block_number (int) – Number of the block to fetch data from, a value of 0 will mean the latest block will be retrieved.

  • seed (int) – Random seed to initialise the simulation and key for use during execution.

  • agents (list[BaseAgent], optional) – List of agents to include in the simulation. Default value is an empty list, allowing agents to be pushed after the simulation is initialised.

  • gas_priority (bool, optional) – If True gas-priority sorting will be used to order transactions in each new simulation step/block. Otherwise transactions will be randomly shuffled. Default value if False.

Returns:

Sim – Initialised simulation with fork backend.

run(n_steps: int, show_progress: bool = True) → List[List[Any]][source]#

Run the simulation and return telemetry data

This updates the simulation in fixed steps, inside each step:

  • The update function is called for all the agents, collecting the calls they submit for processing.

  • The calls are shuffled and processed through the EVM.

  • Records are gathered for each agent and appended to the sequence of records over the course of the simulation.

Parameters:

  • n_steps (int) – Number of steps (i.e. blocks) to run the simulation for.

  • show_progress (bool, optional) – If False printing a simulation progress bar will be disabled, default True.

Returns:

list[list] – List of records collected from agents at each step of the simulation.