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
net – Starknet network identifier
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")
- async call_contract(call: Call, block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) List[int] #
Call the contract with given instance of InvokeTransaction
- Parameters:
call – Call
block_hash – Block’s hash or literals “pending” or “latest”
block_number – Block’s number or literals “pending” 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['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) List[int] #
Synchronous version of the method.
- async declare(transaction: DeclareV1 | DeclareV2 | DeclareV3) DeclareTransactionResponse #
Send a declare transaction
- Parameters:
transaction – Declare transaction
- Returns:
SentTransactionResponse object
- declare_sync(transaction: DeclareV1 | DeclareV2 | DeclareV3) DeclareTransactionResponse #
Synchronous version of the method.
- async deploy_account(transaction: DeployAccountV1 | DeployAccountV3) DeployAccountTransactionResponse #
Deploy a pre-funded account contract to the network
- Parameters:
transaction – DeployAccount transaction
- Returns:
SentTransactionResponse object
- deploy_account_sync(transaction: DeployAccountV1 | DeployAccountV3) DeployAccountTransactionResponse #
Synchronous version of the method.
- async estimate_fee(tx: AccountTransaction | List[AccountTransaction], skip_validate: bool = False, block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) EstimatedFee | List[EstimatedFee] #
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 “pending” or “latest”.
block_number – Block’s number or literals “pending” 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['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) EstimatedFee | List[EstimatedFee] #
Synchronous version of the method.
- async estimate_message_fee(from_address: str, to_address: int | str, entry_point_selector: int | str, payload: List[int | str], block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) EstimatedFee #
- 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 “pending” or “latest”. Mutually exclusive with
block_number
parameter. If not provided, queries block “pending”.block_number – Number (height) of the requested block or literals “pending” or “latest”. Mutually exclusive with
block_hash
parameter. If not provided, queries block “pending”.
- 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['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) EstimatedFee #
Synchronous version of the method.
- async get_block(block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) StarknetBlock | PendingStarknetBlock #
Retrieve the block’s data by its number or hash
- Parameters:
block_hash – Block’s hash or literals “pending” or “latest”
block_number – Block’s number or literals “pending” 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['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) StarknetBlock | PendingStarknetBlock #
Synchronous version of the method.
- async get_block_transaction_count(block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) int #
Get the number of transactions in a block given a block id
- Parameters:
block_hash – Block’s hash or literals “pending” or “latest”
block_number – Block’s number or literals “pending” 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['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) int #
Synchronous version of the method.
- get_block_with_receipts_sync(block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None)#
Synchronous version of the method.
- get_block_with_tx_hashes_sync(block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) StarknetBlockWithTxHashes | PendingStarknetBlockWithTxHashes #
Synchronous version of the method.
- get_block_with_txs_sync(block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) StarknetBlock | PendingStarknetBlock #
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.
- async get_class_at(contract_address: int | str, block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) SierraContractClass | ContractClass #
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 “pending” or “latest”
block_number – Block’s number or literals “pending” 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['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) SierraContractClass | ContractClass #
Synchronous version of the method.
- async get_class_by_hash(class_hash: int | str, block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) SierraContractClass | ContractClass #
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['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) SierraContractClass | ContractClass #
Synchronous version of the method.
- async get_class_hash_at(contract_address: int | str, block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) int #
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 “pending” or “latest”
block_number – Block’s number or literals “pending” 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['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) int #
Synchronous version of the method.
- async get_contract_nonce(contract_address: int | str, block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) int #
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 “pending” or “latest”
block_number – Block’s number or literals “pending” 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['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) int #
Synchronous version of the method.
- async get_events(address: int | str | None = None, keys: List[List[int | str]] | None = None, *, from_block_number: int | Literal['pending', 'latest'] | None = None, from_block_hash: int | str | Literal['pending', 'latest'] | None = None, to_block_number: int | Literal['pending', 'latest'] | None = None, to_block_hash: int | str | Literal['pending', 'latest'] | None = None, follow_continuation_token: bool = False, continuation_token: str | None = None, chunk_size: int = 1) EventsChunk #
- Parameters:
address – The address of the contract that emitted the event.
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 “pending” 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 “pending” 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 “pending” or “latest”. Mutually exclusive with
to_block_hash
parameter. If not provided, query ends at block “pending”.to_block_hash – Hash of the block to which events searched for end or literals “pending” or “latest”. Mutually exclusive with
to_block_number
parameter. If not provided, query ends at block “pending”.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 | None = None, keys: List[List[int | str]] | None = None, *, from_block_number: int | Literal['pending', 'latest'] | None = None, from_block_hash: int | str | Literal['pending', 'latest'] | None = None, to_block_number: int | Literal['pending', 'latest'] | None = None, to_block_hash: int | str | Literal['pending', '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_state_update(block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) BlockStateUpdate | PendingBlockStateUpdate #
Get the information about the result of executing the requested block
- Parameters:
block_hash – Block’s hash or literals “pending” or “latest”
block_number – Block’s number or literals “pending” or “latest”
- 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['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) BlockStateUpdate | PendingBlockStateUpdate #
Synchronous version of the method.
- async get_storage_at(contract_address: int | str, key: int, block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) int #
- 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 “pending” or “latest”
block_number – Block’s number or literals “pending” or “latest”
- Returns:
Storage value of given contract
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['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) int #
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) 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['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | 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 “pending” or “latest”
- 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['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) Transaction #
Synchronous version of the method.
- async get_transaction_receipt(tx_hash: int | str) TransactionReceipt #
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) TransactionReceipt #
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) Transaction #
Synchronous version of the method.
- async send_transaction(transaction: InvokeV1 | InvokeV3) SentTransactionResponse #
Send a transaction to the network
- Parameters:
transaction – Transaction object (i.e. Invoke).
- Returns:
SentTransactionResponse object
- send_transaction_sync(transaction: InvokeV1 | InvokeV3) SentTransactionResponse #
Synchronous version of the method.
- async simulate_transactions(transactions: List[AccountTransaction], skip_validate: bool = False, skip_fee_charge: bool = False, block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) List[SimulatedTransaction] #
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.
block_hash – Block’s hash or literals “pending” or “latest”
block_number – Block’s number or literals “pending” 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_v1(calls=call, max_fee=int(1e16)) # 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, block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) List[SimulatedTransaction] #
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.
- async trace_block_transactions(block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) List[BlockTransactionTrace] #
Retrieve traces for all transactions in the given block.
- Parameters:
block_hash – Block’s hash or literals “pending” or “latest”
block_number – Block’s number or literals “pending” or “latest”
- 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['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) List[BlockTransactionTrace] #
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.