Client#

Base class for clients interacting with Starknet. Implemented by FullNodeClient.

class starknet_py.net.client.Client#

Call the contract with given instance of InvokeTransaction

Parameters:

call – Call
block_hash – Block’s hash or literals “l1_accepted”, “pre_confirmed” or “latest”
block_number – Block’s number or literals “l1_accepted”, “pre_confirmed” or “latest”

Returns:

List of integers representing contract’s function output (structured like calldata)

abstract call_contract_sync(call: Call, block_hash: int | str | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, block_number: int | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None) → List[int]#: Synchronous version of the method.

abstract async declare(transaction: DeclareV3) → DeclareTransactionResponse#

Send a declare transaction

Parameters:: transaction – Declare transaction
Returns:: SentTransactionResponse object

abstract declare_sync(transaction: DeclareV3) → DeclareTransactionResponse#: Synchronous version of the method.

abstract async deploy_account(transaction: DeployAccountV3) → DeployAccountTransactionResponse#

Deploy a pre-funded account contract to the network

Parameters:: transaction – DeployAccount transaction
Returns:: SentTransactionResponse object

abstract deploy_account_sync(transaction: DeployAccountV3) → DeployAccountTransactionResponse#: Synchronous version of the method.

Estimates the resources required by a given sequence of transactions when applied on a given state. If one of the transactions reverts or fails due to any reason (e.g. validation failure or an internal error), a TRANSACTION_EXECUTION_ERROR is returned. For v0-2 transactions the estimate is given in Wei, and for v3 transactions it is given in Fri.

Parameters:

tx – Transaction to estimate
skip_validate – Flag checking whether the validation part of the transaction should be executed.
block_hash – Block’s hash or literals “l1_accepted”, “pre_confirmed” or “latest”.
block_number – Block’s number or literals “l1_accepted”, “pre_confirmed” or “latest”.

Returns:

Estimated amount of Wei executing specified transaction will cost.

abstract estimate_fee_sync(tx: AccountTransaction | List[AccountTransaction], skip_validate: bool = False, block_hash: int | str | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, block_number: int | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None) → EstimatedFee | List[EstimatedFee]#: Synchronous version of the method.

Retrieve the block’s data by its number or hash

Alias of get_block_with_txs().

Parameters:

block_hash – Block’s hash or literals “l1_accepted”, “pre_confirmed” or “latest”
block_number – Block’s number or literals “l1_accepted”, “pre_confirmed” or “latest”

Returns:

StarknetBlock object representing retrieved block

abstract get_block_sync(block_hash: int | str | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, block_number: int | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None) → StarknetBlock | PreConfirmedStarknetBlock#: Synchronous version of the method.

abstract async get_block_with_receipts(block_hash: int | str | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, block_number: int | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, response_flags: List[TransactionResponseFlag] | None = None) → StarknetBlockWithReceipts | PreConfirmedStarknetBlockWithReceipts#

Retrieve the block’s data with a list of receipts for contained transactions.

Parameters:

block_hash – Block’s hash or literals “l1_accepted”, “pre_confirmed” or “latest”
block_number – Block’s number or literals “l1_accepted”, “pre_confirmed” or “latest”
response_flags – Flags that control what additional fields are included in transaction responses

Returns:

StarknetBlockWithReceipts object representing retrieved block with transactions.

abstract get_block_with_receipts_sync(block_hash: int | str | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, block_number: int | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, response_flags: List[TransactionResponseFlag] | None = None) → StarknetBlockWithReceipts | PreConfirmedStarknetBlockWithReceipts#: Synchronous version of the method.

Retrieve the block’s data with a list of contained transaction hashes.

Parameters:

block_hash – Block’s hash or literals “l1_accepted”, “pre_confirmed” or “latest”
block_number – Block’s number or literals “l1_accepted”, “pre_confirmed” or “latest”

Returns:

StarknetBlockWithTxHashes object representing retrieved block with transactions.

abstract get_block_with_tx_hashes_sync(block_hash: int | str | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, block_number: int | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None) → StarknetBlockWithTxHashes | PreConfirmedStarknetBlockWithTxHashes#: Synchronous version of the method.

Retrieve the block’s data by its number or hash.

Parameters:

block_hash – Block’s hash or literals “l1_accepted”, “pre_confirmed” or “latest”
block_number – Block’s number or literals “l1_accepted”, “pre_confirmed” or “latest”
response_flags – Flags that control what additional fields are included in transaction responses

Returns:

StarknetBlock object representing retrieved block with transactions.

abstract get_block_with_txs_sync(block_hash: int | str | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, block_number: int | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, response_flags: List[TransactionResponseFlag] | None = None) → StarknetBlock | PreConfirmedStarknetBlock#: Synchronous version of the method.

abstract async get_chain_id() → str#: Return the currently configured Starknet chain id

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

abstract async get_class_by_hash(class_hash: int | str) → DeprecatedContractClass | SierraContractClass#

Get the contract class for given class hash

Parameters:: class_hash – Class hash
Returns:: ContractClass object

abstract get_class_by_hash_sync(class_hash: int | str) → DeprecatedContractClass | SierraContractClass#: Synchronous version of the method.

Get the contract class hash for the contract deployed at the given address

Parameters:

contract_address – Address of the contract whose class hash is to be returned
block_hash – Block’s hash or literals “l1_accepted”, “pre_confirmed” or “latest”
block_number – Block’s number or literals “l1_accepted”, “pre_confirmed” or “latest”

Returns:

Class hash

abstract get_class_hash_at_sync(contract_address: int | str, block_hash: int | str | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, block_number: int | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None) → int#: Synchronous version of the method.

abstract async get_compiled_casm(class_hash: int) → CasmClass#

Get the contract class definition in the given block associated with the given hash.

Parameters:: class_hash – Hash of the contract class whose CASM will be returned
Returns:: CasmClass object

abstract get_compiled_casm_sync(class_hash: int) → CasmClass#: Synchronous version of the method.

Get the latest nonce associated with the given address

Parameters:

contract_address – Get the latest nonce associated with the given address
block_hash – Block’s hash or literals “l1_accepted”, “pre_confirmed” or “latest”
block_number – Block’s number or literals “l1_accepted”, “pre_confirmed” or “latest”

Returns:

The last nonce used for the given contract

abstract get_contract_nonce_sync(contract_address: int, block_hash: int | str | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, block_number: int | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None) → int#: Synchronous version of the method.

abstract async get_messages_status(transaction_hash: int | str) → List[MessageStatus]#

Get L1 handler transaction data for all L1 to L2 messages sent by the given L1 transaction.

Parameters:: transaction_hash – Hash of the L1 transaction
Returns:: Status of the messages

abstract get_messages_status_sync(transaction_hash: int | str) → List[MessageStatus]#: Synchronous version of the method.

Get the information about the result of executing the requested block

Parameters:

block_hash – Block’s hash or literals “l1_accepted”, “pre_confirmed” or “latest”
block_number – Block’s number or literals “l1_accepted”, “pre_confirmed” or “latest”
contract_addresses – If specified, only state diffs related to these contract addresses will be returned. Class declarations are unaffected by this filter. If omitted, the full state diff is returned.

Returns:

BlockStateUpdate object representing changes in the requested block

abstract get_state_update_sync(block_hash: int | str | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, block_number: int | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, contract_addresses: List[int | str] | None = None) → BlockStateUpdate | PreConfirmedBlockStateUpdate#: Synchronous version of the method.

Parameters:

contract_address – Contract’s address on Starknet
key – An address of the storage variable inside the contract.
block_hash – Block’s hash or literals “l1_accepted”, “pre_confirmed” or “latest”
block_number – Block’s number or literals “l1_accepted”, “pre_confirmed” or “latest”
response_flags – When INCLUDE_LAST_UPDATE_BLOCK is set, returns a StorageResult with value and last_update_block instead of a plain int.

Returns:

Storage value of given contract, or StorageResult when response_flags are set

abstract get_storage_at_sync(contract_address: int | str, key: int, block_hash: int | str | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, block_number: int | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, response_flags: List[StorageResponseFlag] | None = None) → int | StorageResult#: Synchronous version of the method.

Get merkle paths in one of the state tries: global state, classes, individual contract.

Parameters:

block_hash – Block’s hash or literals “l1_accepted”, “pre_confirmed” or “latest”
block_number – Block’s number or literals “l1_accepted”, “pre_confirmed” or “latest”
class_hashes – List of the class hashes for which we want to prove membership in the classes trie.
contract_addresses – List of the contract addresses for which we want to prove membership in the contracts trie.
contracts_storage_keys – List of the contract address and storage keys pairs.

Returns:

StorageProofResponse object.

abstract get_storage_proof_sync(block_hash: int | str | Literal['latest'] | None = None, block_number: int | Literal['latest'] | None = None, class_hashes: List[int] | None = None, contract_addresses: List[int] | None = None, contracts_storage_keys: List[ContractsStorageKeys] | None = None) → StorageProofResponse#: Synchronous version of the method.

abstract async get_transaction(tx_hash: int | str, response_flags: List[TransactionResponseFlag] | None = None) → Transaction#

Get the details and status of a submitted transaction

Parameters:: tx_hash – Transaction’s hash
Returns:: Transaction object

abstract async get_transaction_receipt(tx_hash: int | str) → TransactionReceiptWithBlockInfo#

Get the transaction receipt

Parameters:: tx_hash – Transaction’s hash
Returns:: Transaction receipt object on Starknet

abstract get_transaction_receipt_sync(tx_hash: int | str) → TransactionReceiptWithBlockInfo#: Synchronous version of the method.

abstract async get_transaction_status(tx_hash: int | str) → TransactionStatusResponse#

Gets the transaction status (possibly reflecting that the transaction is still in the mempool, or dropped from it).

Parameters:: tx_hash – Hash of the executed transaction.
Returns:: Finality and execution status of a transaction.

abstract get_transaction_status_sync(tx_hash: int | str) → TransactionStatusResponse#: Synchronous version of the method.

abstract get_transaction_sync(tx_hash: int | str, response_flags: List[TransactionResponseFlag] | None = None) → Transaction#: Synchronous version of the method.

abstract async send_transaction(transaction: InvokeV3) → SentTransactionResponse#

Send a transaction to the network

Parameters:: transaction – Transaction object (i.e. Invoke).
Returns:: SentTransactionResponse object

abstract send_transaction_sync(transaction: InvokeV3) → SentTransactionResponse#: Synchronous version of the method.

abstract async spec_version() → str#

Returns the version of the Starknet JSON-RPC specification being used.

Returns:: String with version of the Starknet JSON-RPC specification.

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

Receive the traces of all the transactions within specified block

Parameters:

block_hash – Block’s hash
block_number – Block’s number or “pre_confirmed” for pre_confirmed block
trace_flags – Flags that indicate when additional information should be included in the trace

Returns:

BlockTransactionTraces object representing received traces

abstract trace_block_transactions_sync(block_hash: int | str | Literal['latest'] | None = None, block_number: int | Literal['latest'] | None = None, trace_flags: List[TraceFlag] | None = None) → List[BlockTransactionTrace] | BlockTransactionTracesWithInitialReads#: Synchronous version of the method.

async wait_for_tx(tx_hash: int | str, check_interval: float = 2, retries: int = 500) → TransactionReceiptWithBlockInfo#

Awaits the transaction until its status is either ACCEPTED_ON_L2 or ACCEPTED_ON_L1 and its receipt can be fetched.

Parameters:

tx_hash – Transaction’s hash.
check_interval – Defines the interval between checks.
retries – Defines how many times the transaction is checked until an error is thrown.

Raises:

TransactionRevertedError – If the transaction execution status is REVERTED.
TransactionNotReceivedError – If the transaction is not received within the given number of checks, i.e., its status never reaches ACCEPTED_ON_L2 or ACCEPTED_ON_L1.

Returns:

Transaction receipt.

wait_for_tx_sync(tx_hash: int | str, check_interval: float = 2, retries: int = 500) → TransactionReceiptWithBlockInfo#: Synchronous version of the method.