FullNodeClient#

class starknet_py.net.full_node_client.FullNodeClient#

__init__(node_url: str, session: ClientSession | None = None)#

Client for interacting with Starknet json-rpc interface.

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 = FullNodeClient(node_url="https://your.node.url")
# or with custom client session
session = ClientSession()
client = FullNodeClient(node_url="https://your.node.url", session=session)
# perform operations...
# close the session
await session.close()

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)

Example

response = await client.call_contract(
    call=Call(
        to_addr=contract_address,
        selector=get_selector_from_name("increase_balance"),
        calldata=[123],
    ),
    block_number="latest",
)

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.

async declare(transaction: DeclareV3) → DeclareTransactionResponse#

Send a declare transaction

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

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

async deploy_account(transaction: DeployAccountV3) → DeployAccountTransactionResponse#

Deploy a pre-funded account contract to the network

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

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.

Example

# a single transaction
estimated_fee = await client.estimate_fee(tx=transaction)
# or a list of transactions
estimated_fee = await client.estimate_fee(tx=[transaction])

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.

Parameters:

from_address – The address of the L1 (Ethereum) contract sending the message.
to_address – The target L2 (Starknet) address the message is sent to.
entry_point_selector – The selector of the l1_handler in invoke in the target contract.
payload – Payload of the message.
block_hash – Hash of the requested block or literals “l1_accepted”, “pre_confirmed” or “latest”. Mutually exclusive with block_number parameter. If not provided, queries block “pre_confirmed”.
block_number – Number (height) of the requested block or literals “l1_accepted”, “pre_confirmed” or “latest”. Mutually exclusive with block_hash parameter. If not provided, queries block “pre_confirmed”.

estimate_message_fee_sync(from_address: str, to_address: int | str, entry_point_selector: int | str, payload: List[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) → 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

Example

block = await client.get_block(block_number="latest")
block = await client.get_block(block_number=0)
# or
block_hash = "0x0"
block = await client.get_block(block_hash=block_hash)

async get_block_hash_and_number() → BlockHashAndNumber#: Get the most recent accepted block hash and number

get_block_hash_and_number_sync() → BlockHashAndNumber#: Synchronous version of the method.

async get_block_number() → int#: Get the most recent accepted block number

get_block_number_sync() → int#: Synchronous version of the method.

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.

Get the number of transactions in a block given a block id

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:

Number of transactions in the designated block

Example

num_of_transactions = await client.get_block_transaction_count(
    block_number="latest"
)

get_block_transaction_count_sync(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.

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.

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.

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.

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.

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

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

Get the contract class definition in the given block at the given address

Parameters:

contract_address – The address of the contract whose class definition will 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:

Contract declared to Starknet

Example

address = 0x1 or 1 or "0x1"
contract_class = await client.get_class_at(
    contract_address=address, block_number="latest"
)

get_class_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) → SierraContractClass | DeprecatedContractClass#: Synchronous version of the method.

Get the contract class for given class hash

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

Example

hash_ = 0x1 or 1 or "0x1"
contract_class = await client.get_class_by_hash(class_hash=hash_)

get_class_by_hash_sync(class_hash: 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) → SierraContractClass | DeprecatedContractClass#: 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

Example

address = 0x1 or 1 or "0x1"
class_hash = await client.get_class_hash_at(
    contract_address=address, block_number="latest"
)

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.

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

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

Example

address = 0x1 or 1 or "0x1"
nonce = await client.get_contract_nonce(
    contract_address=address, block_number="latest"
)

get_contract_nonce_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.

Parameters:

address – A contract address or a list of addresses from which events should originate.
keys – List consisting lists of keys by which the events are filtered. They match the keys by position, e.g. given an event with 3 keys, [[1,2],[],[3]] which should return events that have either 1 or 2 in the first key, any value for their second key and 3 for their third key.
from_block_number – Number of the block from which events searched for starts or literals “l1_accepted”, “pre_confirmed” or “latest”. Mutually exclusive with from_block_hash parameter. If not provided, query starts from block 0.
from_block_hash – Hash of the block from which events searched for starts or literals “l1_accepted”, “pre_confirmed” or “latest”. Mutually exclusive with from_block_number parameter. If not provided, query starts from block 0.
to_block_number – Number of the block to which events searched for end or literals “l1_accepted”, “pre_confirmed” or “latest”. Mutually exclusive with to_block_hash parameter. If not provided, query ends at block “pre_confirmed”.
to_block_hash – Hash of the block to which events searched for end or literals “l1_accepted”, “pre_confirmed” or “latest”. Mutually exclusive with to_block_number parameter. If not provided, query ends at block “pre_confirmed”.
follow_continuation_token – Flag deciding whether all events should be collected during one function call, defaults to False.
continuation_token – Continuation token from which the returned events start.
chunk_size – Size of chunk of events returned by one get_events call, defaults to 1 (minimum).

Returns:

EventsResponse dataclass containing events and optional continuation token.

Example

address = 0x1 or 1 or "0x1"
events_response = await client.get_events(
    address=address,
    keys=[[1, 2], [], [3]],
    from_block_number=0,
    to_block_number="latest",
    follow_continuation_token=True,
    chunk_size=47,
)

get_events_sync(address: int | str | List[int | str] | None = None, keys: List[List[int | str]] | None = None, *, from_block_number: int | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, from_block_hash: int | str | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, to_block_number: int | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, to_block_hash: int | str | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, follow_continuation_token: bool = False, continuation_token: str | None = None, chunk_size: int = 1) → EventsChunk#: Synchronous version of the method.

async get_l1_message_hash(tx_hash: int | str) → int | str#

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

get_l1_message_hash_sync(tx_hash: int | str) → int | str#: Synchronous version of the method.

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

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

Example

state_update = await client.get_state_update(block_number="latest")
state_update = await client.get_state_update(block_number=1)
# or
block_hash = "0x0"
state_update = await client.get_state_update(block_hash=block_hash)

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

Example

storage_value = await client.get_storage_at(
    contract_address=address,
    key=get_storage_var_address("storage_var name"),
    block_number="latest",
)

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.

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.

async get_syncing_status() → bool | SyncStatus#: Returns an object about the sync status, or false if the node is not syncing

get_syncing_status_sync() → bool | SyncStatus#: Synchronous version of the method.

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

Example

transaction_hash = 0x1 or 1 or "0x1"
transaction = await client.get_transaction(tx_hash=transaction_hash)

async get_transaction_by_block_id(index: 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[TransactionResponseFlag] | None = None) → Transaction#

Get the details of transaction in block identified by block_hash and transaction index.

Parameters:

index – Index of the transaction
block_hash – Hash of the block
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:

Transaction object

Example

transaction = await client.get_transaction_by_block_id(
    index=0, block_number="latest"
)

get_transaction_by_block_id_sync(index: 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[TransactionResponseFlag] | None = None) → Transaction#: Synchronous version of the method.

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

Example

transaction_receipt = await client.get_transaction_receipt(tx_hash=transaction_hash)

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

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.

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

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

async send_transaction(transaction: InvokeV3) → SentTransactionResponse#

Send a transaction to the network

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

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

async simulate_transactions(transactions: List[AccountTransaction], skip_validate: bool = False, skip_fee_charge: bool = False, return_initial_reads: 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) → List[SimulatedTransaction] | SimulatedTransactionsWithInitialReads#

Simulates a given sequence of transactions on the requested state, and generates the execution traces. Note the following:

A transaction may revert. If this occurs, no error is thrown. Instead, revert details are visible in the returned trace object.
If a transaction reverts, this will be reflected by the revert_error property in the trace.
Other types of failures (e.g. unexpected error or failure in the validation phase) will result in TRANSACTION_EXECUTION_ERROR.

Parameters:

transactions – Transactions to be traced.
skip_validate – Flag checking whether the validation part of the transaction should be executed.
skip_fee_charge – Flag deciding whether fee should be deducted from the balance before the simulation of the next transaction.
return_initial_reads – When True, include the set of state values read during execution. Returns SimulatedTransactionsWithInitialReads instead of a plain list.
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 execution trace and consumed resources for each transaction.

Example

call = Call(
    to_addr=contract_address,
    selector=get_selector_from_name("method_name"),
    calldata=[0xCA11DA7A],
)
first_transaction = await account.sign_invoke_v3(
    calls=call, resource_bounds=MAX_RESOURCE_BOUNDS
)
# one transaction
simulated_txs = await account.client.simulate_transactions(
    transactions=[first_transaction], block_number="latest"
)
# or multiple
simulated_txs = await account.client.simulate_transactions(
    transactions=[first_transaction, second_transaction], block_number="latest"
)

simulate_transactions_sync(transactions: List[AccountTransaction], skip_validate: bool = False, skip_fee_charge: bool = False, return_initial_reads: 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) → List[SimulatedTransaction] | SimulatedTransactionsWithInitialReads#: Synchronous version of the method.

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.

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

Retrieve traces for all transactions in the given block.

Parameters:

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

Returns:

List of execution traces of all transactions included in the given block with transaction hashes.

Example

block_number = 800002
block_transaction_traces = await client.trace_block_transactions(
    block_number=block_number
)

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 trace_transaction(tx_hash: int | str) → InvokeTransactionTrace | DeclareTransactionTrace | DeployAccountTransactionTrace | L1HandlerTransactionTrace#

For a given executed transaction, returns the trace of its execution, including internal calls.

Parameters:: tx_hash – Hash of the executed transaction.
Returns:: Trace of the transaction.

Example

transaction_hash = "0x123"
transaction_trace = await client.trace_transaction(tx_hash=transaction_hash)

trace_transaction_sync(tx_hash: int | str) → InvokeTransactionTrace | DeclareTransactionTrace | DeployAccountTransactionTrace | L1HandlerTransactionTrace#: Synchronous version of the method.