dojo.environments package

Environments package contains environment classes and logic.

class dojo.environments.BaseEnvironment(date_range: Tuple[datetime, datetime], agents: List[BaseAgent], backend_type: Literal['forked', 'local', 'live'] = 'forked', port: int | None = None, token_data: dict | None = None)

Bases: ABC

The BaseEnvironment class defines the template for all environments.

deploy_contract(contract_path: str, contract_name: str, constructor_args: list, compiler_version: str = 'latest') → None

Deploy and register a contract on the local network.

Parameters:

  • contract_path – path to the contract .sol file.

  • contract_name – lookup name of the contract to deploy.

  • constructor_args – list of contract constructor arguments.

  • compiler_version – solc compiler version to use.

disconnect() → None

Disconnect and close the connection to the local dojo network.

abstract initialize_state()

Initialize the state of the environment.

iter_block(batch_size: int = 0) → Generator[int, None, None]

Iterate over the simulation period one block at a time.

This also sets the date and block attributes of the environment.

Parameters:

batch_size – parameter for ethereumetl.export_blocks_and_transactions see https://ethereum-etl.readthedocs.io/en/latest/commands/. If set to 0, will NOT get the date information for each block.

Yield:

block number.

Raises:

Exception – batched no longer supported

market_actions(agents_actions: List[BaseAction]) → List[BaseAction]

Predict the market actions of the current block.

Parameters:

agents_actions – The actions from the policies of the other agents.

reset() → BaseObs

Reset the environment and agents before returning the observation object.

This method needs to be called before any simulation in order to setup the on- chain infrastructure.

abstract setup_contracts_forked() → List[str]

Register contracts on the forked network.

Returns:

a list of contracts to approve for ERC20 transfers.

abstract setup_contracts_local() → List[str]

Deploy and register contracts on the local network.

Returns:

a list of contracts to approve for ERC20 transfers.

step(actions: List[BaseAction]) → Tuple[BaseObs, ndarray, ndarray, dict]

Execute a sequence of actions in the environment in list order.

Parameters:

actions – in order sequence of actions to execute.

Return next_obs:

next observation.

Return rewards:

array of rewards for each agent.

Return dones:

array of done flags for each agent.

Return infos:

dict of info for each agent.

class dojo.environments.UniV3Env(agents: List[BaseAgent], date_range: Tuple[datetime, datetime], pools: List[str], market_impact: Literal['replay', 'no_market'] = 'replay', backend_type: Literal['forked', 'local', 'live'] = 'forked', dataloader: BaseLoader | Literal['auto'] | None = 'auto', port: int | None = None, token_data: dict | None = None)

Bases: BaseEnvironment

The UniV3Env environment models the UniswapV3 system dynamics.

It is responsible for updating both the protocol and agent states through time.

MAX_SQRT_RATIO = 1461446703485210103287273052203988822378723970342
MAX_TICK = 887272
MIN_SQRT_RATIO = 4295128739
MIN_TICK = -887272
POOL_SIZE = 2
burn(from_agent: BaseAgent, token_id: int, gas: int | None = None, max_fee_per_gas: int | None = None, max_priority_fee_per_gas: int | None = None) → TxReceipt

Burns a token ID, which deletes it from the NFT contract.

The token must have 0 liquidity and all tokens must be collected first.

Parameters:

  • from_agent – agent burning the token.

  • token_id – token ID to burn.

  • gas – The gas price of the action, if not set will be automatically calculated.

  • max_fee_per_gas – The max fee per gas of the action, if not set will be automatically calculated.

  • max_priority_fee_per_gas – The max priority fee per gas of the action, if not set will be automatically calculated.

collect(from_agent: BaseAgent, pool: str, collect: Tuple[int, int], tick_range: Tuple[int, int], gas: int | None = None, max_fee_per_gas: int | None = None, max_priority_fee_per_gas: int | None = None) → TxReceipt

Collect fees from a pool.

Parameters:

  • from_agent – agent collecting fees.

  • pool – pool to collect fees from.

  • collect – quantities of each token to collect.

  • tick_range – tick range of the position to collect from.

  • gas – The gas price of the action, if not set will be automatically calculated.

  • max_fee_per_gas – The max fee per gas of the action, if not set will be automatically calculated.

  • max_priority_fee_per_gas – The max priority fee per gas of the action, if not set will be automatically calculated.

Raises:

ValueError – if there is no position to collect from.

decrease_liquidity(from_agent: BaseAgent, pool: str, token_id: int, quote: Tuple[int, int], liquidity: int = -1, gas: int | None = None, max_fee_per_gas: int | None = None, max_priority_fee_per_gas: int | None = None) → TxReceipt

Decrease liquidity in an LP position.

Parameters:

  • from_agent – the agent that owns the position

  • token_id – the token id of the position

  • quote – the quote to decrease liquidity by

  • liquidity – the liquidity to decrease by, if not provided it will be calculated from the quote

  • gas – The gas price of the action, if not set will be automatically calculated.

  • max_fee_per_gas – The max fee per gas of the action, if not set will be automatically calculated.

  • max_priority_fee_per_gas – The max priority fee per gas of the action, if not set will be automatically calculated.

increase_liquidity(from_agent: BaseAgent, pool: str, token_id: int, quote: Tuple[int, int], gas: int | None = None, max_fee_per_gas: int | None = None, max_priority_fee_per_gas: int | None = None) → TxReceipt

Increase the liquidity in an already existing LP position.

Parameters:

  • from_agent – agent calling the mint.

  • pool – pool to mint liquidity in.

  • token_id – token id of the LP position to increase liquidity in.

  • quote – the quantities of assets being provided.

  • gas – The gas price of the action, if not set will be automatically calculated.

  • max_fee_per_gas – The max fee per gas of the action, if not set will be automatically calculated.

  • max_priority_fee_per_gas – The max priority fee per gas of the action, if not set will be automatically calculated.

initialize_state()

Initialize the state of the environment.

mint(from_agent: BaseAgent, pool: str, quote: Tuple[int, int], tick_range: Tuple[int, int], gas: int | None = None, max_fee_per_gas: int | None = None, max_priority_fee_per_gas: int | None = None) → TxReceipt

Mint a new LP position and receive an NFT token representing your position.

Parameters:

  • from_agent – agent calling the mint.

  • pool – pool to mint liquidity in.

  • quote – the quantities of assets being provided.

  • tick_range – tick range of the new LP position.

  • gas – The gas price of the action, if not set will be automatically calculated.

  • max_fee_per_gas – The max fee per gas of the action, if not set will be automatically calculated.

  • max_priority_fee_per_gas – The max priority fee per gas of the action, if not set will be automatically calculated.

quote(from_agent: BaseAgent, pool: str, quote: Tuple[int, int], tick_range: Tuple[int, int], gas: int | None = None, max_fee_per_gas: int | None = None, max_priority_fee_per_gas: int | None = None, liquidity: int = -1, owner: str = '0x0000000000000000000000000000000000000000') → TxReceipt

Provide or withdraw liquidity to a pool.

Parameters:

  • from_agent – agent providing liquidity.

  • pool – pool to provide liquidity to.

  • quote – quantities of each token to provide liquidity with.

  • tick_range – tick range of liquidity.

  • gas – The gas price of the action, if not set will be automatically calculated.

  • max_fee_per_gas – The max fee per gas of the action, if not set will be automatically calculated.

  • max_priority_fee_per_gas – The max priority fee per gas of the action, if not set will be automatically calculated.

  • liquidity – liquidity of quote, optionally needed when burning liquidity. By default -1, which means it will be calculated from the quote quantities.

  • owner – optional owner address of the quote, needed when the MarketAgent executes a burn.

Raises:

ValueError – if the quote contains mixed positive and negative values.

set_fee_protocol(pool: str, fees: Tuple[Decimal, Decimal], gas: int | None = None, max_fee_per_gas: int | None = None, max_priority_fee_per_gas: int | None = None) → TxReceipt

Set the fee protocol for a pool.

Parameters:

  • pool – pool to set the fee protocol for.

  • fees – fees to set.

  • gas – The gas price of the action, if not set will be automatically calculated.

  • max_fee_per_gas – The max fee per gas of the action, if not set will be automatically calculated.

  • max_priority_fee_per_gas – The max priority fee per gas of the action, if not set will be automatically calculated.

setup_contracts_forked() → List[str]

Register contracts on the forked network.

Returns:

a list of contracts to approve for ERC20 transfers.

setup_contracts_local() → List[str]

Deploy and register contracts on the local network.

Returns:

a list of contracts to approve for ERC20 transfers.

trade(from_agent: BaseAgent, pool: str, trade: Tuple[int, int], sqrt_price_limitX96: int | None = None, gas: int | None = None, max_fee_per_gas: int | None = None, max_priority_fee_per_gas: int | None = None) → TxReceipt | None

Submit a trade to a pool.

Parameters:

  • from_agent – agent submitting the trade.

  • pool – pool to submit the trade to.

  • trade – quantities of each token to trade.

  • sqrt_price_limitX96 – price limit for trade execution in sqrt x96 format.

  • gas – The gas price of the action, if not set will be automatically calculated.

  • max_fee_per_gas – The max fee per gas of the action, if not set will be automatically calculated.

  • max_priority_fee_per_gas – The max priority fee per gas of the action, if not set will be automatically calculated.

Raises:

ContractLogicError – if trade fails.

Submodules

Base Environments defines the template for all environments.

class dojo.environments.base_environments.BaseEnvironment(date_range: Tuple[datetime, datetime], agents: List[BaseAgent], backend_type: Literal['forked', 'local', 'live'] = 'forked', port: int | None = None, token_data: dict | None = None)

Bases: ABC

The BaseEnvironment class defines the template for all environments.

deploy_contract(contract_path: str, contract_name: str, constructor_args: list, compiler_version: str = 'latest') → None

Deploy and register a contract on the local network.

Parameters:

  • contract_path – path to the contract .sol file.

  • contract_name – lookup name of the contract to deploy.

  • constructor_args – list of contract constructor arguments.

  • compiler_version – solc compiler version to use.

disconnect() → None

Disconnect and close the connection to the local dojo network.

abstract initialize_state()

Initialize the state of the environment.

iter_block(batch_size: int = 0) → Generator[int, None, None]

Iterate over the simulation period one block at a time.

This also sets the date and block attributes of the environment.

Parameters:

batch_size – parameter for ethereumetl.export_blocks_and_transactions see https://ethereum-etl.readthedocs.io/en/latest/commands/. If set to 0, will NOT get the date information for each block.

Yield:

block number.

Raises:

Exception – batched no longer supported

market_actions(agents_actions: List[BaseAction]) → List[BaseAction]

Predict the market actions of the current block.

Parameters:

agents_actions – The actions from the policies of the other agents.

reset() → BaseObs

Reset the environment and agents before returning the observation object.

This method needs to be called before any simulation in order to setup the on- chain infrastructure.

abstract setup_contracts_forked() → List[str]

Register contracts on the forked network.

Returns:

a list of contracts to approve for ERC20 transfers.

abstract setup_contracts_local() → List[str]

Deploy and register contracts on the local network.

Returns:

a list of contracts to approve for ERC20 transfers.

step(actions: List[BaseAction]) → Tuple[BaseObs, ndarray, ndarray, dict]

Execute a sequence of actions in the environment in list order.

Parameters:

actions – in order sequence of actions to execute.

Return next_obs:

next observation.

Return rewards:

array of rewards for each agent.

Return dones:

array of done flags for each agent.

Return infos:

dict of info for each agent.

Uniswap V3 environment.

class dojo.environments.uniswapV3.UniV3Env(agents: List[BaseAgent], date_range: Tuple[datetime, datetime], pools: List[str], market_impact: Literal['replay', 'no_market'] = 'replay', backend_type: Literal['forked', 'local', 'live'] = 'forked', dataloader: BaseLoader | Literal['auto'] | None = 'auto', port: int | None = None, token_data: dict | None = None)

Bases: BaseEnvironment

The UniV3Env environment models the UniswapV3 system dynamics.

It is responsible for updating both the protocol and agent states through time.

MAX_SQRT_RATIO = 1461446703485210103287273052203988822378723970342
MAX_TICK = 887272
MIN_SQRT_RATIO = 4295128739
MIN_TICK = -887272
POOL_SIZE = 2
burn(from_agent: BaseAgent, token_id: int, gas: int | None = None, max_fee_per_gas: int | None = None, max_priority_fee_per_gas: int | None = None) → TxReceipt

Burns a token ID, which deletes it from the NFT contract.

The token must have 0 liquidity and all tokens must be collected first.

Parameters:

  • from_agent – agent burning the token.

  • token_id – token ID to burn.

  • gas – The gas price of the action, if not set will be automatically calculated.

  • max_fee_per_gas – The max fee per gas of the action, if not set will be automatically calculated.

  • max_priority_fee_per_gas – The max priority fee per gas of the action, if not set will be automatically calculated.

collect(from_agent: BaseAgent, pool: str, collect: Tuple[int, int], tick_range: Tuple[int, int], gas: int | None = None, max_fee_per_gas: int | None = None, max_priority_fee_per_gas: int | None = None) → TxReceipt

Collect fees from a pool.

Parameters:

  • from_agent – agent collecting fees.

  • pool – pool to collect fees from.

  • collect – quantities of each token to collect.

  • tick_range – tick range of the position to collect from.

  • gas – The gas price of the action, if not set will be automatically calculated.

  • max_fee_per_gas – The max fee per gas of the action, if not set will be automatically calculated.

  • max_priority_fee_per_gas – The max priority fee per gas of the action, if not set will be automatically calculated.

Raises:

ValueError – if there is no position to collect from.

decrease_liquidity(from_agent: BaseAgent, pool: str, token_id: int, quote: Tuple[int, int], liquidity: int = -1, gas: int | None = None, max_fee_per_gas: int | None = None, max_priority_fee_per_gas: int | None = None) → TxReceipt

Decrease liquidity in an LP position.

Parameters:

  • from_agent – the agent that owns the position

  • token_id – the token id of the position

  • quote – the quote to decrease liquidity by

  • liquidity – the liquidity to decrease by, if not provided it will be calculated from the quote

  • gas – The gas price of the action, if not set will be automatically calculated.

  • max_fee_per_gas – The max fee per gas of the action, if not set will be automatically calculated.

  • max_priority_fee_per_gas – The max priority fee per gas of the action, if not set will be automatically calculated.

increase_liquidity(from_agent: BaseAgent, pool: str, token_id: int, quote: Tuple[int, int], gas: int | None = None, max_fee_per_gas: int | None = None, max_priority_fee_per_gas: int | None = None) → TxReceipt

Increase the liquidity in an already existing LP position.

Parameters:

  • from_agent – agent calling the mint.

  • pool – pool to mint liquidity in.

  • token_id – token id of the LP position to increase liquidity in.

  • quote – the quantities of assets being provided.

  • gas – The gas price of the action, if not set will be automatically calculated.

  • max_fee_per_gas – The max fee per gas of the action, if not set will be automatically calculated.

  • max_priority_fee_per_gas – The max priority fee per gas of the action, if not set will be automatically calculated.

initialize_state()

Initialize the state of the environment.

market_model: BaseMarketModel
mint(from_agent: BaseAgent, pool: str, quote: Tuple[int, int], tick_range: Tuple[int, int], gas: int | None = None, max_fee_per_gas: int | None = None, max_priority_fee_per_gas: int | None = None) → TxReceipt

Mint a new LP position and receive an NFT token representing your position.

Parameters:

  • from_agent – agent calling the mint.

  • pool – pool to mint liquidity in.

  • quote – the quantities of assets being provided.

  • tick_range – tick range of the new LP position.

  • gas – The gas price of the action, if not set will be automatically calculated.

  • max_fee_per_gas – The max fee per gas of the action, if not set will be automatically calculated.

  • max_priority_fee_per_gas – The max priority fee per gas of the action, if not set will be automatically calculated.

quote(from_agent: BaseAgent, pool: str, quote: Tuple[int, int], tick_range: Tuple[int, int], gas: int | None = None, max_fee_per_gas: int | None = None, max_priority_fee_per_gas: int | None = None, liquidity: int = -1, owner: str = '0x0000000000000000000000000000000000000000') → TxReceipt

Provide or withdraw liquidity to a pool.

Parameters:

  • from_agent – agent providing liquidity.

  • pool – pool to provide liquidity to.

  • quote – quantities of each token to provide liquidity with.

  • tick_range – tick range of liquidity.

  • gas – The gas price of the action, if not set will be automatically calculated.

  • max_fee_per_gas – The max fee per gas of the action, if not set will be automatically calculated.

  • max_priority_fee_per_gas – The max priority fee per gas of the action, if not set will be automatically calculated.

  • liquidity – liquidity of quote, optionally needed when burning liquidity. By default -1, which means it will be calculated from the quote quantities.

  • owner – optional owner address of the quote, needed when the MarketAgent executes a burn.

Raises:

ValueError – if the quote contains mixed positive and negative values.

set_fee_protocol(pool: str, fees: Tuple[Decimal, Decimal], gas: int | None = None, max_fee_per_gas: int | None = None, max_priority_fee_per_gas: int | None = None) → TxReceipt

Set the fee protocol for a pool.

Parameters:

  • pool – pool to set the fee protocol for.

  • fees – fees to set.

  • gas – The gas price of the action, if not set will be automatically calculated.

  • max_fee_per_gas – The max fee per gas of the action, if not set will be automatically calculated.

  • max_priority_fee_per_gas – The max priority fee per gas of the action, if not set will be automatically calculated.

setup_contracts_forked() → List[str]

Register contracts on the forked network.

Returns:

a list of contracts to approve for ERC20 transfers.

setup_contracts_local() → List[str]

Deploy and register contracts on the local network.

Returns:

a list of contracts to approve for ERC20 transfers.

trade(from_agent: BaseAgent, pool: str, trade: Tuple[int, int], sqrt_price_limitX96: int | None = None, gas: int | None = None, max_fee_per_gas: int | None = None, max_priority_fee_per_gas: int | None = None) → TxReceipt | None

Submit a trade to a pool.

Parameters:

  • from_agent – agent submitting the trade.

  • pool – pool to submit the trade to.

  • trade – quantities of each token to trade.

  • sqrt_price_limitX96 – price limit for trade execution in sqrt x96 format.

  • gas – The gas price of the action, if not set will be automatically calculated.

  • max_fee_per_gas – The max fee per gas of the action, if not set will be automatically calculated.

  • max_priority_fee_per_gas – The max priority fee per gas of the action, if not set will be automatically calculated.

Raises:

ContractLogicError – if trade fails.

class dojo.environments.uniswapV3.UniV3MarketModelType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

This enum defines the types of market impact models available.

Attr NO_MARKET:

The no market impact model does nothing. :attr REPLAY: The replay

market impact model replays history.

NO_MARKET = 'no_market'
REPLAY = 'replay'