Node Client¶
The Config
class is used to intialized the NodeClient
-
class
aeternity.node.
Config
(external_url='http://localhost:3013', internal_url='http://localhost:3113', websocket_url='http://localhost:3014', force_compatibility=False, **kwargs)[source]¶ -
__init__
(external_url='http://localhost:3013', internal_url='http://localhost:3113', websocket_url='http://localhost:3014', force_compatibility=False, **kwargs)[source]¶ Initialize a configuration object to be used with the NodeClient
- Args:
external_url (str): the node external url internal_url (str): the node internal url websocket_url (str): the node websocket url force_compatibility (bool): ignore node version compatibility check (default False)
- Kwargs:
- blocking_mode (bool)
whenever to block the execution when broadcasting a transaction until the transaction is mined in the chain, default: False
- tx_gas_per_byte (int)
the amount of gas per byte used to calculate the transaction fees, [optional, default: defaults.GAS_PER_BYTE]
- tx_base_gas (int)
the amount of gas per byte used to calculate the transaction fees, [optional, default: defaults.BASE_GAS]
- tx_gas_price (int)
the gas price used to calculate the transaction fees, it is set by consensus but can be increased by miners [optional, default: defaults.GAS_PRICE]
- network_id (str)
the id of the network that is the target for the transactions, if not provided it will be automatically selected by the client
- contract_gas (int)
default gas limit to be used for contract calls, [optional, default: defaults.CONTRACT_GAS]
- contract_gas_price (int)
default gas price used for contract calls, [optional, default: defaults.CONTRACT_GAS_PRICE]
- oracle_ttl_type (int)
default oracle ttl type
- key_block_interval (int)
the key block interval in minutes
- key_block_confirmation_num (int)
the number of key blocks to consider a transaction confirmed
- poll_tx_max_retries (int)
max poll retries when checking if a transaction has been included
- poll_tx_retries_interval (int)
the interval in seconds between retries
- poll_block_max_retries (int)
TODO
- poll_block_retries_interval (int)
TODO
- offline (bool)
whenever the node should not contact the node for any information
- debug (bool)
enable debug logging for api calls
-
The NodeClient
is the main object to interact with an Aeternity node.
-
class
aeternity.node.
NodeClient
(config=<aeternity.node.Config object>)[source]¶ -
account_basic_to_ga
(account: aeternity.signing.Account, ga_contract: str, calldata: str, auth_fun: str = 'authorize', fee=0, tx_ttl: int = 0, gas: int = 10000, gas_price=1000000000) → aeternity.transactions.TxObject[source]¶ Transform a Basic to a GA (Generalized Account)
- Parameters
account – the account to transform
ga_contract – the compiled contract associated to the GA
calldata – the calldata for the authentication function
auth_fun – the name of the contract function to use for authorization (default: authorize)
gas – the gas limit for the authorization function execution
gas_price – the gas price for the contract execution
fee – TODO
ttl – TODO
- Returns
the TxObject of the transaction
- Raises
TypeError – if the auth_fun is missing
TypeError – if the auth_fun is no found in the contract
-
broadcast_transaction
(tx: aeternity.transactions.TxObject)[source]¶ Post a transaction to the chain and verify that the hash match the local calculated hash It blocks for a period of time to wait for the transaction to be included if in blocking_mode
- Parameters
tx – the transaction to broadcast
- Returns
the transaction hash of the transaction
- Raises
TransactionHashMismatch – if the transaction hash returned by the node is different from the one calculated
-
compute_absolute_ttl
(relative_ttl)[source]¶ Compute the absolute ttl by adding the ttl to the current height of the chain
- Parameters
relative_ttl – the relative ttl, if 0 will set the ttl to 0
-
delegate_name_claim_signature
(account: aeternity.signing.Account, contract_id: str, name: str)[source]¶ Helper to generate a signature to delegate a name claim to a contract.
- Args:
account: the account authorizing the transaction contract_id: the if of the contract executing the transaction name: the name being claimed
- Returns:
the signature to use for delegation
-
delegate_name_preclaim_signature
(account: aeternity.signing.Account, contract_id: str)[source]¶ Helper to generate a signature to delegate a name preclaim to a contract.
- Args:
account: the account authorizing the transaction contract_id: the if of the contract executing the transaction
- Returns:
the signature to use for delegation
-
delegate_name_revoke_signature
(account: aeternity.signing.Account, contract_id: str, name: str)[source]¶ Helper to generate a signature to delegate a name revoke to a contract.
- Args:
account: the account authorizing the transaction contract_id: the if of the contract executing the transaction name: the name being revoked
- Returns:
the signature to use for delegation
-
delegate_name_transfer_signature
(account: aeternity.signing.Account, contract_id: str, name: str)[source]¶ Helper to generate a signature to delegate a name tranfer to a contract.
- Args:
account: the account authorizing the transaction contract_id: the if of the contract executing the transaction name: the name being transferred
- Returns:
the signature to use for delegation
-
get_account
(address: str) → aeternity.signing.Account[source]¶ : Retrieve an account by it’s public key
-
get_balance
(account) → int[source]¶ Retrieve the balance of an account, return 0 if the account has not balance
- Parameters
account – either an account address or a signing.Account object
- Returns
the account balance or 0 if the account is not known to the network
-
get_block_by_hash
(hash=None)[source]¶ Retrieve a key block or a micro block header based on the block hash_prefix
- Parameters
block_hash – either a key block or micro block hash
- Returns
the block matching the hash
-
get_consensus_protocol_version
(height: int = None) → int[source]¶ Get the consensus protocol version number :param height: the height to get the protocol version for, if None the current height will be used :return: the version
-
get_next_nonce
(account, use_cached=True)[source]¶ Get the next nonce to be used for a transaction for an account. If account is an instance Account, the cached value of the account.nonce will be used unless the parameter use_cached is set to False
- Args:
account: the account instance or account address of get the nonce for use_cached: use the cached value in the account.nonce property in case of an account object (default True)
- Returns:
the next nonce for an account
-
get_top_block
()[source]¶ Override the native method to transform the get top block response object to a Block
- Returns
a block (either key block or micro block)
-
get_transaction
(transaction_hash: str) → aeternity.transactions.TxObject[source]¶ Retrieve a transaction by it’s hash.
- Args:
transaction_hash: the hash of the transaction to retrieve
- Returns:
the TxObject of the transaction
- Raises:
ValueError: if the transaction hash is not a valid hash for transactions
-
get_vm_abi_versions
()[source]¶ Check the version of the node and retrieve the correct values for abi and vm version
-
sign_transaction
(account: aeternity.signing.Account, tx: aeternity.transactions.TxObject, metadata: dict = {}, **kwargs) → aeternity.transactions.TxObject[source]¶ The function sign a transaction to be broadcast to the chain. It automatically detect if the account is Basic or GA and return the correct transaction to be broadcast.
- Parameters
account – the account signing the transaction
tx – the transaction to be signed
metadata – additional metadata to maintain in the TxObject
**kwargs – for GA accounts, see below
- Kwargs:
- auth_data (str)
the encoded calldata for the GA auth function
- gas (int)
the gas limit for the GA auth function [optional]
- gas_price (int)
the gas price for the GA auth function [optional]
- fee (int)
the fee for the GA transaction [optional, automatically calculated]
- abi_version (int)
the abi_version to select FATE or AEVM [optional, default 3/FATE]
- ttl (str)
the transaction ttl expressed in relative number of blocks [optional, default 0/max_ttl]:
- Returns
a TxObject of the signed transaction or metat transaction for GA
- Raises
TypeError – if the auth_data is missing and the account is GA
TypeError – if the gas for auth_func is gt defaults.GA_MAX_AUTH_FUN_GAS
-
spend
(account: aeternity.signing.Account, recipient_id: str, amount, payload: str = '', fee: int = 0, tx_ttl: int = 0) → aeternity.transactions.TxObject[source]¶ Create and execute a spend transaction, automatically retrieve the nonce for the siging account and calculate the absolut ttl.
- Parameters
account – the account signing the spend transaction (sender)
recipient_id – the recipient address or name_id
amount – the amount to spend
payload – the payload for the transaction
fee – the fee for the transaction (automatically calculated if not provided)
tx_ttl – the transaction ttl expressed in relative number of blocks
- Returns
the TxObject of the transaction
- Raises
TypeError – if the recipient_id is not a valid name_id or address
-
transfer_funds
(account: aeternity.signing.Account, recipient_id: str, percentage: float, payload: str = '', tx_ttl: int = 0, fee: int = 0, include_fee=True)[source]¶ Create and execute a spend transaction
-
verify
(encoded_tx: str) → aeternity.transactions.TxObject[source]¶ Unpack and verify an encoded transaction
-
wait_for_confirmation
(tx, max_retries=None, polling_interval=None) → int[source]¶ Wait for a transaction to be confirmed by at least “key_block_confirmation_num” blocks (default 3) The amount of blocks can be configured in the Config object using key_block_confirmation_num parameter
- Args:
tx (TxObject|str): the TxObject or transaction hash of the transaction to wait for max_retries (int): the maximum number of retries to test for transaction polling_interval (int): the interval between transaction polls
- Returns:
the block height of the transaction if it has been found
- Raises:
TransactionWaitTimeoutExpired: if the transaction hasn’t been found
-
wait_for_transaction
(tx, max_retries=None, polling_interval=None) → int[source]¶ Wait for a transaction to be mined for an account The method will wait for a specific transaction to be included in the chain, it will return False if one of the following conditions are met: - the chain reply with a 404 not found (the transaction was expunged) - the account nonce is >= of the transaction nonce (transaction is in an illegal state) - the ttl of the transaction or the one passed as parameter has been reached
- Args:
tx (TxObject|str): the TxObject or transaction hash of the transaction to wait for max_retries (int): the maximum number of retries to test for transaction polling_interval (int): the interval between transaction polls
- Returns:
the block height of the transaction if it has been found
- Raises:
TransactionWaitTimeoutExpired: if the transaction hasn’t been found
-