DevnetClient#

class starknet_py.devnet_utils.devnet_client.DevnetClient#

__init__(node_url: str = 'http://127.0.0.1:5050', session: ClientSession | None = None)#

Client for interacting with Starknet devnet json-rpc interface.

Based on https://0xspaceshard.github.io/starknet-devnet-rs/docs/intro

Parameters:

node_url – Url of the node providing rpc interface
session – Aiohttp session to be used for request. If not provided, client will create a session for every request. When using a custom session, user is responsible for closing it manually.

Example

client = DevnetClient(node_url="https://your.node.url")

This functionality allows simulating block abortion that can occur on mainnet. It is supported in the –state-archive-capacity full mode.

Parameters:

block_number – Number of the block which the state of Devnet will be reverted to or literals “pending” or “latest”.
block_hash – Hash of the block which the state of Devnet will be reverted to or literals “pending” or “latest”

abort_block_sync(block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) → List[str]#: Synchronous version of the method.

async auto_impersonate()#: Enables automatic account impersonation. Every account that does not exist in the local state will be impersonated. For impersonation to work, Devnet needs to be run in forking mode.

auto_impersonate_sync()#: Synchronous version of the method.

async consume_message_from_l2(from_address: int | str, to_address: int | str, payload: List[int | str]) → str#

Sending mock transactions from L2 to L1. Deployed L2 contract address l2_contract_address and l1_contract_address must be valid.

Parameters:

from_address – Address of the L2 contract.
to_address – Address of the L1 contract.
payload – List of felts.

Returns:

Message hash.

Warning

A running L1 node is required for this operation.

consume_message_from_l2_sync(from_address: int | str, to_address: int | str, payload: List[int | str]) → str#: Synchronous version of the method.

async create_block() → str#: Create a new block.

create_block_sync() → str#: Synchronous version of the method.

async dump(path: str)#

Dump the state of the devnet to a file. Dumping on request requires providing –dump-on mode on the startup.

Parameters:: path – Path to the file.

dump_sync(path: str)#: Synchronous version of the method.

async get_account_balance(address: int | str, unit: PriceUnit | str = PriceUnit.WEI, block_tag: str = 'latest') → BalanceRecord#

Get the balance of the given account.

Parameters:

address – Address of the account contract.
unit – Literals “FRI” or “WEI” defaults to “WEI”.
block_tag – Literals “pending” or “latest”, defaults to “latest”.

get_account_balance_sync(address: int | str, unit: PriceUnit | str = PriceUnit.WEI, block_tag: str = 'latest') → BalanceRecord#: Synchronous version of the method.

async get_config() → Config#: Get the devnet configuration.

get_config_sync() → Config#: Synchronous version of the method.

async get_predeployed_accounts(with_balance: bool = False) → List[PredeployedAccount]#

Get the predeployed accounts.

Parameters:: with_balance – If True the balance of the accounts will be included, default to False.

get_predeployed_accounts_sync(with_balance: bool = False) → List[PredeployedAccount]#: Synchronous version of the method.

async impersonate_account(address: int | str)#

Impersonate the given account. For impersonation to work, Devnet needs to be run in forking mode.

Parameters:: address – Address of the account contract.

impersonate_account_sync(address: int | str)#: Synchronous version of the method.

async increase_time(time: int) → IncreaseTimeResponse#

(Only possible if there are no pending transactions) Increases the block timestamp by the provided amount and generates a new block. All subsequent blocks will keep this increment.

Parameters:: time – Time to increase in seconds.

increase_time_sync(time: int) → IncreaseTimeResponse#: Synchronous version of the method.

async load(path: str)#

Load the state of the devnet from a file.

Parameters:: path – Path to the file.

load_sync(path: str)#: Synchronous version of the method.

async mint(address: int | str, amount: int, unit: PriceUnit | str = PriceUnit.WEI) → MintResponse#

Mint tokens to the given address.

Parameters:

address – Address of the account contract.
amount – Amount of tokens to mint. Must be integer.
unit – Literals “FRI” or “WEI”, default to “WEI”.

mint_sync(address: int | str, amount: int, unit: PriceUnit | str = PriceUnit.WEI) → MintResponse#: Synchronous version of the method.

async postman_flush(dry_run: bool = False) → PostmanFlushResponse#

Goes through the newly enqueued messages, sending them from L1 to L2 and from L2 to L1. Requires no body.

Parameters:: dry_run – Optional, If True the result of flushing will be shown without actually triggering it.

Warning

A running L1 node is required if dry_run is not set.

postman_flush_sync(dry_run: bool = False) → PostmanFlushResponse#: Synchronous version of the method.

async postman_load(network_url: str, address: str | None = None) → str#

Loads a MockStarknetMessaging contract. The address parameter is optional; if provided, the MockStarknetMessaging contract will be fetched from that address, otherwise a new one will be deployed.

Parameters:: network_url – is the URL of the JSON-RPC API of the L1 node you’ve run locally or that already exists
Returns:: The address of the messaging contract.

postman_load_sync(network_url: str, address: str | None = None) → str#: Synchronous version of the method.

async restart()#: Restart the devnet.

restart_sync()#: Synchronous version of the method.

Sending mock transactions from L1 to L2 without the need for running L1. Deployed L2 contract address l2_contract_address and entry_point_selector must be valid otherwise new block will not be created. Normally nonce is calculated by L1 StarknetContract and it’s used in L1 and L2. In this case, we need to provide it manually.

A running L1 node is not required for this operation.

Parameters:

l2_contract_address – Address of the L2 contract.
entry_point_selector – Selector of the entry point.
l1_contract_address – Address of the L1 contract.
payload – List of felts.
nonce – Nonce.
paid_fee_on_l1 – Paid fee on L1.

Returns:

Transaction hash.

send_message_to_l2_sync(l2_contract_address: int | str, entry_point_selector: int | str, l1_contract_address: int | str, payload: List[int | str], nonce: int | str, paid_fee_on_l1: int | str) → str#: Synchronous version of the method.

async set_time(time: int, generate_block: bool = False) → SetTimeResponse#

Set the time of the devnet. Only available when there is no pending transaction. Warning: block time can be set in the past and lead to unexpected behaviour!

Parameters:

time – Time to set in seconds. (Unix time)
generate_block – If True a new block will be generated, default to False.

set_time_sync(time: int, generate_block: bool = False) → SetTimeResponse#: Synchronous version of the method.

stop_auto_impersonate_sync()#: Synchronous version of the method.

async stop_impersonate_account(address: int | str)#

Stop impersonating the given account.

Parameters:: address – Address of the account contract.

stop_impersonate_account_sync(address: int | str)#: Synchronous version of the method.