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

Parameters:
  • external_url – the node external url
  • internal_url – the node internal url
  • websocket_url – the node websocket url
  • force_compatibility – ignore node version compatibility check (default False)
  • **kwargs – see below
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
debug (bool):TODO

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
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_address)[source]

Get the next nonce to be used for a transaction for an account

Parameters:node – the node client
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_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_hash, max_retries=None, polling_interval=None)[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

Parameters:
  • tx_hash – the hash of the transaction to wait for
  • max_retries – the maximum number of retries to test for transaction
  • polling_interval – the interval between transaction polls
Returns:

the block height of the transaction if it has been found

wait_for_transaction(tx_hash, max_retries=None, polling_interval=None)[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

Parameters:
  • tx_hash – the hash of the transaction to wait for
  • max_retries – the maximum number of retries to test for transaction
  • polling_interval – 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