Skip to content
module

neo3.api.noderpc

NEO RPC Node client and response classes.

Classes
dataclass

neo3.api.noderpc.ApplicationExecution(state, gas_consumed, exception, stack, trigger, notifications)

Bases
neo3.api.noderpc.ExecutionResult

Specialised ExecutionResult with additional notification and trigger information.

dataclass

neo3.api.noderpc.BlockApplicationLogResponse(block_hash, executions)

Data log for processing of a block on chain.

Does not include the data log for its transactions.

dataclass

neo3.api.noderpc.BlockValidator(public_key, votes)

Activate consensus member.

dataclass

neo3.api.noderpc.Candidate(public_key, votes, active)

Bases
neo3.api.noderpc.BlockValidator

Candidate consensus member.

dataclass

neo3.api.noderpc.ExecutionResult(state, gas_consumed, exception, stack)

Execution result data.

dataclass

neo3.api.noderpc.ExecutionResultResponse(state, gas_consumed, exception, stack, script, notifications)

Bases
neo3.api.noderpc.ExecutionResult

Response to invokecontractverify, invokefunction or invokescript RPC call.

dataclass

neo3.api.noderpc.GetPeersResponse(connected, bad, unconnected)

Response to getpeers RPC call.

dataclass

neo3.api.noderpc.GetVersionResponse(tcp_port, ws_port, nonce, user_agent, protocol)

Response to getversion RPC call.

class

neo3.api.noderpc.JsonRpcError(code, message, data=None)

Bases
Exception BaseException

Common base class for all non-exit exceptions.

class

neo3.api.noderpc.JsonRpcTimeoutError(message=None)

Bases
neo3.api.noderpc.JsonRpcError Exception BaseException

Common base class for all non-exit exceptions.

dataclass

neo3.api.noderpc.MapStackItem(type, value)

Bases
neo3.api.noderpc.StackItem

Virtual machine stack item.

Methods
method

as_address() → str

Unwrap as NEO3 address.

method

as_bool() → bool

Unwrap as bool.

Raises
  • ValueError — if internal item type does not match required.
method

as_bytes() → bytes

Unwrap as bool.

Raises
  • ValueError — if internal item type does not match required.
method

as_dict() → dict

Unwrap as dict.

Raises
  • ValueError — if internal item type does not match required.
method

as_int() → int

Unwrap as int.

Raises
  • ValueError — if internal item type does not match required.
method

as_list() → list

Unwrap as list.

Raises
  • ValueError — if internal item type does not match required.
method

as_none()

Unwrap as None.

Raises
  • ValueError — if internal item type does not match required.
method

as_public_key() → ECPoint

Unwrap as ECPoint.

Raises
  • ValueError — if internal item type does not match required.
method

as_str() → str

Unwrap as str.

Raises
  • ValueError — if internal item type does not match required.
method

as_uint160() → UInt160

Unwrap as UInt160.

Raises
  • ValueError — if internal item type does not match required.
method

as_uint256() → UInt256

Unwrap as UInt256.

Raises
  • ValueError — if internal item type does not match required.
dataclass

neo3.api.noderpc.MempoolResponse(verified, unverified)

Response to getrawmempool RPC call.

A verified transaction in the memory pool is a transaction which has had:

  • - basic structural validation (e.g. max tx size)
  • - signature validation
  • - state validation
      - block validity expiration check
      - available balance vs network and system fees
      - etc

class

neo3.api.noderpc.NeoRpcClient(host, **kwargs)

Bases
neo3.api.noderpc.RPCClient

Specialised RPC client for NEO's Node RPC API.

Methods
  • calculate_network_fee(tx) (int) — Obtain the cost of verifying the transaction and including it in a block (a.k.a network fee).
  • close() — Close the client session.
  • find_states(contract_hash, prefix) (AsyncGenerator) — Fetch the smart contract storage state.
  • get_application_log_block(block_hash) (BlockApplicationLogResponse) — Fetch the system event logs for a given block.
  • get_application_log_transaction(tx_hash) (TransactionApplicationLogResponse) — Fetch the smart contract event logs for a given transaction.
  • get_best_block_hash() (UInt256) — Fetch the hash of the highest block in the chain.
  • get_block(index_or_hash) (Block) — Fetch the block by its index or block hash.
  • get_block_count() (int) — Fetch the current height of the blockchain.
  • get_block_hash(index) (UInt256) — Fetch the block hash by the block's index.
  • get_block_header(index_or_hash) (Header) — Fetch the block header by its index or block hash.
  • get_candidates() (Sequence) — Fetch list of consensus candidates.
  • get_committee() (tuple) — Fetch the public keys of the current NEO committee.
  • get_connection_count() (int) — Fetch the number of peers connected to the node.
  • get_contract_state(contract_hash_or_name) (ContractState) — Fetch smart contract state information.
  • get_nep17_balances(address) (Nep17BalancesResponse) — Fetch the balance of all NEP17 assets for the specified address.
  • get_nep17_transfers(address, start_time, end_time) (Nep17TransfersResponse) — Fetch NEP17 transfers for a given address. Defaults to the last 7 days on the server side.
  • get_next_blockvalidators() (NextBlockValidatorsResponse) — Fetch the list of next block validators.
  • get_peers() (GetPeersResponse) — Fetch peer information.
  • get_raw_mempool() (MempoolResponse) — Fetch the transaction hashes currently in the memory pool waiting to be added to the next produced block.
  • get_storage(script_hash, key) (bytes) — Fetch a value from a smart contracts storage by its key.
  • get_transaction(tx_hash) (Transaction) — Fetch a transaction by its hash.
  • get_transaction_height(tx_hash) (int) — Fetch the height of the block the transaction is included in.
  • get_transaction_receipt(tx_hash) (Receipt) — Fetch a transaction receipt.
  • get_unclaimed_gas(address) (int) — Fetch the amount of unclaimed gas for the given address.
  • get_version() (GetVersionResponse) — Fetch the node client version, network protocol properties and network ports.
  • invoke_contract_verify(contract_hash, function_params, signers) (ExecutionResultResponse) — Invoke the verify method on the contract.
  • invoke_function(contract_hash, name, function_params, signers) (ExecutionResultResponse) — Invoke a smart contract function.
  • invoke_script(script, signers) (ExecutionResultResponse) — Execute a script in the virtual machine.
  • print_contract_methods(contract_hash_or_name) — Helper to fetch all public methods of a smart contract, print their signatures in Python syntax asto help determine the right native argument types.
  • send_block(block_) (UInt256) — Broadcast a transaction to the network.
  • send_transaction(tx) (UInt256) — Broadcast a transaction to the network.
  • validate_address(address) (bool) — Verify if the given address is valid for the network the node is running on.
  • wait_for_transaction_receipt(tx_hash, timeout, retry_delay) (Receipt) — Try to fetch a transaction.
method

calculate_network_fee(tx) → int

Obtain the cost of verifying the transaction and including it in a block (a.k.a network fee).

method

find_states(contract_hash, prefix=None)

Fetch the smart contract storage state.

Parameters
  • contract_hash (neo3.core.types.uint.uint160 | str) — the hash of the smart contract to call.
  • prefix (Optional, optional) — storage prefix to search for. If omitted will return all storage
Returns (AsyncGenerator)

a storage key/value pair

Examples

prints all deployed

prefix_contract_hash = b" " async with api.NeoRpcClient("https://testnet1.neo.coz.io:443") as client: async for k, v in client.find_states(CONTRACT_HASHES.MANAGEMENT, prefix_contract_hash): print(k, v)

method

get_application_log_block(block_hash) → BlockApplicationLogResponse

Fetch the system event logs for a given block.

Parameters
  • block_hash (neo3.core.types.uint.uint256 | str) — the hash of the block to query for.
method

get_application_log_transaction(tx_hash) → TransactionApplicationLogResponse

Fetch the smart contract event logs for a given transaction.

Commonly used to verify that a transaction sent via send_transaction() was executed succesfully on chain.

Parameters
  • tx_hash (neo3.core.types.uint.uint256 | str) — the hash of the transaction to query for.
method

get_best_block_hash() → UInt256

Fetch the hash of the highest block in the chain.

method

get_block(index_or_hash) → Block

Fetch the block by its index or block hash.

method

get_block_count() → int

Fetch the current height of the blockchain.

method

get_block_hash(index) → UInt256

Fetch the block hash by the block's index.

method

get_block_header(index_or_hash) → Header

Fetch the block header by its index or block hash.

method

get_candidates() → Sequence

Fetch list of consensus candidates.

method

get_committee() → tuple

Fetch the public keys of the current NEO committee.

method

get_connection_count() → int

Fetch the number of peers connected to the node.

method

get_contract_state(contract_hash_or_name) → ContractState

Fetch smart contract state information.

Note

Only native contracts can be queried by their name. Name is case-insensitive.

method

get_nep17_balances(address) → Nep17BalancesResponse

Fetch the balance of all NEP17 assets for the specified address.

method

get_nep17_transfers(address, start_time=None, end_time=None) → Nep17TransfersResponse

Fetch NEP17 transfers for a given address. Defaults to the last 7 days on the server side.

Parameters
  • address (str) — account to get transfer for.
  • start_time (Optional, optional) — if given the start of the requested range. Must be in UTC and time aware not naïve.
  • end_time (Optional, optional) — if given the end of the requested range.
Example

Fetch transfers of the last 14 days

start = datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=14) await get_nep17_transfers(, start)

method

get_next_blockvalidators() → NextBlockValidatorsResponse

Fetch the list of next block validators.

method

get_peers() → GetPeersResponse

Fetch peer information.

method

get_raw_mempool() → MempoolResponse

Fetch the transaction hashes currently in the memory pool waiting to be added to the next produced block.

method

get_storage(script_hash, key) → bytes

Fetch a value from a smart contracts storage by its key.

Args: script_hash: contract script hash. key: the storage key to fetch the data for.

Example: # fetch the fee per byte from the Policy native contract key_fee_per_byte = b'

await client.get_storage(contracts.PolicyContract().hash, key_fee_per_byte)
method

get_transaction(tx_hash) → Transaction

Fetch a transaction by its hash.

method

get_transaction_height(tx_hash) → int

Fetch the height of the block the transaction is included in.

method

get_transaction_receipt(tx_hash) → Receipt

Fetch a transaction receipt.

Parameters
  • tx_hash (UInt256) — unique identifier of the transaction to fetch receipt for.
method

get_unclaimed_gas(address) → int

Fetch the amount of unclaimed gas for the given address.

Parameters
  • address (str) — a NEO address.
method

get_version() → GetVersionResponse

Fetch the node client version, network protocol properties and network ports.

method

invoke_contract_verify(contract_hash, function_params=None, signers=None) → ExecutionResultResponse

Invoke the verify method on the contract.

Note

Calling smart contracts through this function does not alter the blockchain state. The smart contract will be called using the Verification trigger (unlike the invoke_function method which uses the Application trigger).

Parameters
  • contract_hash (neo3.core.types.uint.uint160 | str) — the hash of the smart contract to call.
  • function_params (Optional, optional) — the arguments required by the smart contract function.
  • signers (Optional, optional) — additional signers (e.g. for checkwitness passing).
method

invoke_function(contract_hash, name, function_params=None, signers=None) → ExecutionResultResponse

Invoke a smart contract function.

Note

Calling smart contracts through this function does not alter the blockchain state. To alter the blockchain state use the send_transaction method instead.

Parameters
  • contract_hash (neo3.core.types.uint.uint160 | str) — the hash of the smart contract to call.
  • name (str) — the name of the function to call on the smart contract.
  • function_params (Optional, optional) — the arguments required by the smart contract function.
  • signers (Optional, optional) — additional signers (e.g. for checkwitness passing).
Example

check if an account is blocked using the Policy native contract

policy_contract = "cc5e4edd9f5f8dba8bb65734541df7a1c081c67b" account_to_check = types.UInt160.from_string("86df72a6b4ab5335d506294f9ce993722253b6e2") signer_account = types.UInt160.from_string("f621168b1fce3a89c33a5f6bcf7e774b4657031c") signer = verification.Signer(signer_account, payloads.WitnessScope.CALLED_BY_ENTRY) await client.invoke_function(contract_hash=policy_contract, name="isBlocked", function_params=[account_to_check], signers=[signer])

method

invoke_script(script, signers=None)

Execute a script in the virtual machine.

Note

Executing VM scripts through this function does not alter the blockchain state.

Parameters
  • script (bytes) — an array of VM opcodes.
  • signers (Optional, optional) — additional signers (e.g. for checkwitness passing).
Returns (ExecutionResultResponse)

The results of executing the script in the VM.

method

print_contract_methods(contract_hash_or_name)

Helper to fetch all public methods of a smart contract, print their signatures in Python syntax asto help determine the right native argument types.

Note

Only native contracts can be queried by their name. Name is case-insensitive.

method

send_block(block_)

Broadcast a transaction to the network.

Parameters
  • block_ (neo3.network.payloads.block.block | bytes) — either a Block object or a serialized Block.
Returns (UInt256)

a block hash if successful.

method

send_transaction(tx)

Broadcast a transaction to the network.

Note

uses the sendrawtransaction RPC method internally.

Parameters
  • tx (neo3.network.payloads.transaction.transaction | bytes) — either a Transaction object or a serialized Transaction. Must be signed.
Returns (UInt256)

a transaction hash if successful.

method

validate_address(address) → bool

Verify if the given address is valid for the network the node is running on.

Parameters
  • address (str) — a NEO address.
method

wait_for_transaction_receipt(tx_hash, timeout=20, retry_delay=5) → Receipt

Try to fetch a transaction.

Parameters
  • tx_hash (UInt256) — unique identifier of the transaction to fetch the receipt for.
  • timeout (float, optional) — maximum time to wait to find the transaction on chain in seconds.
  • retry_delay (float, optional) — interval between querying the chain for the transaction in seconds.
Raises
  • JsonRpcError — for other errors that might occur.
  • JsonRpcTimeoutError — if timeout threshold is exceeded
method

close()

Close the client session.

dataclass

neo3.api.noderpc.Nep17Balance(asset_hash, amount, last_updated_block)

NEP-17 balance entry.

dataclass

neo3.api.noderpc.Nep17BalancesResponse(balances, address)

Response to getnep17balances RPC call.

dataclass

neo3.api.noderpc.Nep17Transfer(time, asset_hash, transfer_address, amount, block_index, transfer_notify_index, tx_hash)

NEP-17 transfer record.

dataclass

neo3.api.noderpc.Nep17TransfersResponse(sent, received, address)

Response to getnep17transfer RPC call.

dataclass

neo3.api.noderpc.NextBlockValidatorsResponse(validators)

Response to getnextblockvalidators RPC call.

dataclass

neo3.api.noderpc.Notification(contract, event_name, state)

Smart contract notification entry.

dataclass

neo3.api.noderpc.Peer(address, port)

P2P peer information.

class

neo3.api.noderpc.RPCClient(url, timeout=3.0)

RPC Client base.

Methods
  • close() — Close the client session.
method

close()

Close the client session.

dataclass

neo3.api.noderpc.Receipt(tx_hash, included_in_block, confirmations, execution)

Transaction receipt containing data regarding chain state and events happening as a result of executing the transaction.

dataclass

neo3.api.noderpc.StackItem(type, value)

Virtual machine stack item.

Methods
method

as_address() → str

Unwrap as NEO3 address.

method

as_bool() → bool

Unwrap as bool.

Raises
  • ValueError — if internal item type does not match required.
method

as_bytes() → bytes

Unwrap as bool.

Raises
  • ValueError — if internal item type does not match required.
method

as_dict() → dict

Unwrap as dict.

Raises
  • ValueError — if internal item type does not match required.
method

as_int() → int

Unwrap as int.

Raises
  • ValueError — if internal item type does not match required.
method

as_list() → list

Unwrap as list.

Raises
  • ValueError — if internal item type does not match required.
method

as_none()

Unwrap as None.

Raises
  • ValueError — if internal item type does not match required.
method

as_public_key() → ECPoint

Unwrap as ECPoint.

Raises
  • ValueError — if internal item type does not match required.
method

as_str() → str

Unwrap as str.

Raises
  • ValueError — if internal item type does not match required.
method

as_uint160() → UInt160

Unwrap as UInt160.

Raises
  • ValueError — if internal item type does not match required.
method

as_uint256() → UInt256

Unwrap as UInt256.

Raises
  • ValueError — if internal item type does not match required.
enum

neo3.api.noderpc.StackItemType()

Bases
enum.Enum

Virtual machine item types that can be found in the stack property of responses when executing a script or transactions.

Members
  • ANY (str) — Any
  • ARRAY (str) — Array
  • BOOL (str) — Boolean
  • BUFFER (str) — Buffer
  • BYTE_STRING (str) — ByteString
  • INTEGER (str) — Integer
  • INTEROP_INTERFACE (str) — InteropInterface
  • MAP (str) — Map
  • POINTER (str) — Pointer
  • STRUCT (str) — Struct
dataclass

neo3.api.noderpc.TransactionApplicationLogResponse(tx_hash, execution)

Data log for processing of a transaction on chain.

dataclass

neo3.api.noderpc.VersionProtocol(address_version, network, validators_count, ms_per_block, max_traceable_blocks, max_transactions_per_block, max_valid_until_block_increment, memorypool_max_transactions, initial_gas_distribution)

Partial response of getversion RPC call.