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)

__init__(external_url='http://localhost:3013', internal_url='http://localhost:3113', websocket_url='http://localhost:3014', force_compatibility=False, **kwargs)

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>)

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

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)

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)

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)

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)

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)

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)

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

: Retrieve an account by it’s public key

get_balance(account) → int

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)

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

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)

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()

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

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()

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

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

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)

Create and execute a spend transaction

verify(encoded_tx: str) → aeternity.transactions.TxObject

Unpack and verify an encoded transaction

wait_for_confirmation(tx, max_retries=None, polling_interval=None) → int

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

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