nanoblocks.node package

Submodules

nanoblocks.node.nanonode module

Module contents

The nanoblocks.node module implements Nano node wrapper.

class nanoblocks.node.NodeFailover(nodes_list, timezone='Etc/UTC')

Bases: nanoblocks.node.node_remote.NodeRemote

Interface access to a Node.

A Node Failover is node class that forwards its requests to the first healthy node in a list of failover nodes. The first healthy node found in the list is the one used for performing the requests.

When a node fails in providing a response, the next node in the list is taken instead. It is transparent to the user, ensuring that an answer is retrieved.

add_failover_node(failover_node)

property failover_nodes

find_healthy()

Seeks for a healthy node in the list of nodes. When a node is found, it is set as the target node of this instance. :return:

property http_url

remove_failover_node(failover_node)

property ws

property ws_url

class nanoblocks.node.NodeRemote(http_url, ws_url=None, timezone='Etc/UTC')

Bases: nanoblocks.node.node_interface.NodeInterface

Interface access to a Node.

account_history(*args, **kwargs)

Reports send/receive information for an account. Returns only send & receive blocks by default (unless raw is set to true - see optional parameters below): change, state change & state epoch blocks are skipped, open & state open blocks will appear as receive, state receive/send blocks will appear as receive/send entries.

Response will start with the latest block for the account (the frontier), and will list all blocks back to the open block of this account when “count” is set to “-1”.

Note: “local_timestamp” returned since version 18.0, “height” field returned since version 19.0.

Source: https://docs.nano.org/commands/rpc-protocol/#account_history

Parameters

• nano_address – Address of the account with format “NANO_…”.

• raw –

  Boolean, False by default. if set to true, instead of outputting a simplified send or receive explanation of blocks (intended for wallets), output all parameters of the block itself as seen in block_create or other APIs returning blocks.

  It still includes the “account” and “amount” properties you’d see without this option. State/universal blocks in the raw history will also have a subtype field indicating their equivalent “old” block. Unfortunately, the “account” parameter for open blocks is the account of the source block, not the account of the open block, to preserve similarity with the non-raw history.

• count – Number of blocks to retrieve in a single call to the node. By default, it is 10 blocks.

• head – head (64 hexadecimal digits string, 256 bit). Default is the latest block. Use this block as the head of the account instead. Useful for pagination.

• offset – offset (decimal integer). Skips a number of blocks starting from head (if given). Not often used. Available since version 11.0

• reverse –

  Boolean, False by default. If set to True, the response starts from head (if given, otherwise the first block of the account), and lists blocks up to the frontier (limited by “count”).

  Note: the field previous in the response changes to next. Available since version 19.0

• account_filter –

  List of public addresses. If set, results will be filtered to only show sends/receives connected to the provided account(s).

  Available since version 19.0. Note: In v19.0, this option does not handle receive blocks; fixed in v20.0.

account_info(*args, **kwargs)

Returns frontier, open block, change representative block, balance, last modified timestamp from local database & block count for account.

WARNING: Only works for accounts that have received their first transaction and have an entry on the ledger, will return “Account not found” otherwise.

Source: https://docs.nano.org/commands/rpc-protocol/#account_info

Parameters

• nano_address – Address of the account with format “NANO_…”.

• representative – Boolean, false by default. Additionally, returns representative for account.

• weight – Boolean, false by default. Additionally, returns voting weight for account.

• pending – Boolean, false by default. Additionally, returns receivable balance for account.

• include_confirmed –

  Boolean, false by default. Adds new return fields with prefix of confirmed_ for consistency:

  • confirmed_balance: balance for only blocks on this account that have already been confirmed

  • confirmed_height: matches confirmation_height value

  • confirmed_frontier: matches confirmation_height_frontier value

  If representative option also true,

  • confirmed_representative included (representative account from the confirmed frontier block)

  If receivable option also true,

  • confirmed_receivable included (balance of all receivable amounts where the matching incoming send

  blocks have been confirmed on their account)

accounts_balances(*args, **kwargs)

Returns how much RAW is owned and how many have not yet been received by accounts list.

Source: https://docs.nano.org/commands/rpc-protocol/#accounts_balances

Parameters

addresses – List of “NANO_…” addresses.

accounts_frontiers(*args, **kwargs)

Returns a list of pairs of account and block hash representing the head block for accounts list.

Source: https://docs.nano.org/commands/rpc-protocol/#accounts_frontiers

Parameters

addresses – List of “NANO_…” addresses.

accounts_pending(*args, **kwargs)

Returns a list of confirmed block hashes which have not yet been received by these accounts

source: https://docs.nano.org/commands/rpc-protocol/#accounts_pending

Parameters

• accounts – List of accounts [”nano_…”, “nano_…”] to check for pending blocks.

• threshold – Number (128 bit, decimal), default None. Returns a list of receivable block hashes with amount more or equal to threshold.

• source – Boolean, False by default. Returns a list of receivable block hashes with amount and source accounts.

• count – Number, 1 by default. Specifies the number of pending blocks to be retrieved.

• include_active – Boolean, false by default. Include active (not confirmed) blocks.

• sorting – Boolean, false by default. Additionally, sorts each account’s blocks by their amounts in descending order.

• include_only_confirmed – Boolean, true by default. Only returns blocks which have their confirmation height set or are undergoing confirmation height processing. If false, unconfirmed blocks will also be returned.

active_difficulty(*args, **kwargs)

Returns the difficulty values (16 hexadecimal digits string, 64 bit) and related multiplier from base difficulty. [DEPRECATED as of V22]

Source: https://docs.nano.org/commands/rpc-protocol/#active_difficulty

Parameters

include_trend – Boolean, false by default. Also returns the trend of difficulty seen on the network as a list of multipliers.

available_supply(*args, **kwargs)

Returns how many raw are in the public supply.

Source: https://docs.nano.org/commands/rpc-protocol/#available_supply

block_confirm(block_hash)

Request asynchronous confirmation for block from known online representative nodes. Once the confirmation is requested to the node, a confirmation process starts.

It is required to peek for confirmation results at confirmation history.

Source: https://docs.nano.org/commands/rpc-protocol/#block_confirm

NOTE: Unless there was an error encountered during the command execution, the response will always return “started”: “1”.

This response does not indicate the block was successfully confirmed, only that an error did not occur.

This response happens even if the block has already been confirmed previously and notifications will be triggered for this block (via HTTP callbacks or WebSockets) in all cases. This behavior may change in a future release.

Parameters

block_hash – Hash of the block to check.

block_count(*args, **kwargs)

Reports the number of blocks in the ledger and unchecked synchronizing blocks.

Source: https://docs.nano.org/commands/rpc-protocol/#block_count

Parameters

include_cemented – Default True. If True, “cemented” in the response will contain the number of cemented blocks.

block_info(*args, **kwargs)

Retrieves a json representation of the block in contents along with:

• since version 18.0: block_account, transaction amount, block balance, block height in account chain, block local modification timestamp.

• since version 19.0: Whether block was confirmed, subtype (for state blocks) of send, receive, change or epoch.

Source: https://docs.nano.org/commands/rpc-protocol/#block_info

Parameters

• block_hash – Hash of the block to check.

• json_block – Default False. If True, “contents” will contain a JSON subtree instead of a JSON string.

blocks_info(*args, **kwargs)

Retrieves a json representations of blocks in contents along with:

• since version 18.0: block_account, transaction amount, block balance, block height in account chain,

  block local modification timestamp.

• since version 19.0: Whether block was confirmed, subtype (for state blocks) of send, receive, change or

  epoch.

• since version 23.0: successor returned.

Using the optional json_block is recommended since v19.0.

Source: https://docs.nano.org/commands/rpc-protocol/#blocks_info

Parameters

• blocks_hashes – List of blocks hashes to retrieve

• json_block – Default False. If True, “contents” will contain a JSON subtree instead of a JSON string.

• include_not_found – Default False. If True, an additional key “blocks_not_found” is provided in the response, containing a list of the block hashes that were not found in the local database. Previously to this version an error would be produced if any block was not found.

healthy()

Checks the health status for this node.

Returns

True if node can be used, False otherwise.

property http_url

peers(*args, **kwargs)

Returns a list of pairs of online peer IPv6:port and its node protocol network version.

Source: https://docs.nano.org/commands/rpc-protocol/#peers

process(block_definition, subtype=None)

Publish a block to the network.

https://docs.nano.org/commands/rpc-protocol/#process

Parameters

• block_definition – A JSON block definition of the block to be published.

• subtype – A subtype string defining the type of block.

representatives(*args, **kwargs)

Returns a list of pairs of representative and their voting weight.

Source: https://docs.nano.org/commands/rpc-protocol/#representatives

Parameters

• count – Number. Returns a list of pairs of representative and their voting weight up to count.

• sorting – Boolean, false by default. Additional sorting representatives in descending order. NOTE: The “count” option is ignored if “sorting” is specified

representatives_online(*args, **kwargs)

Returns a list of online representative accounts that have voted recently.

Source: https://docs.nano.org/commands/rpc-protocol/#representatives_online

Parameters

• weight – Boolean, false by default. Returns voting weight for each representative.

• accounts – Array of accounts. Returned list is filtered for only these accounts.

snapshot(accounts_list, blocks_list=None, shallow_history=True, max_pending=100, pending_threshold=None, missing='raise')

Exports the network information of the given accounts and blocks list up to the current date. The network information can be used as a snapshot to be loaded in an offline environment, under a NodeVirtual class object.

Parameters

• accounts_list – List of ‘NANO_…’ accounts to be exported. This includes their internal blocks.

• blocks_list – List of individual blocks to be exported.

• shallow_history – If True, Only the frontier (the latest block) of every account is included in the snapshot. Otherwise, all blocks are exported.

• max_pending – Maximum number of pending blocks to be stored in the snapshot for each account.

• pending_threshold – Minimum amount threshold of pending blocks (to filter).

• missing –

  Action to be done in case a missing account/block in the network is detected. The following values are accepted:

  • ’raise’ raises a KeyError exception.

  • ’skip’ ignores the error and skips the account/block.

Returns

Snapshot object that can be exported to a file or loaded into a VirtualNode.

telemetry(*args, **kwargs)

Return metrics from other nodes on the network. By default, returns a summarized view of the whole network.

Source: https://docs.nano.org/commands/rpc-protocol/#telemetry

property version

Returns the node information and version.

Source: https://docs.nano.org/commands/rpc-protocol/#version

property ws

property ws_url

class nanoblocks.node.NodeVirtual(timezone='Etc/UTC', internal_accounts=None, internal_accounts_history=None, internal_accounts_pending=None, internal_blocks=None)

Bases: nanoblocks.node.node_interface.NodeInterface

Interface access to a Node.

account_history(nano_address, raw=False, count=10, previous=None, head=None, reverse=None, offset=None, account_filter=None)

Reports send/receive information for an account. Returns only send & receive blocks by default (unless raw is set to true - see optional parameters below): change, state change & state epoch blocks are skipped, open & state open blocks will appear as receive, state receive/send blocks will appear as receive/send entries.

Response will start with the latest block for the account (the frontier), and will list all blocks back to the open block of this account when “count” is set to “-1”.

Note: “local_timestamp” returned since version 18.0, “height” field returned since version 19.0.

Source: https://docs.nano.org/commands/rpc-protocol/#account_history

Parameters

• nano_address – Address of the account with format “NANO_…”.

• raw –

  Boolean, False by default. if set to true, instead of outputting a simplified send or receive explanation of blocks (intended for wallets), output all parameters of the block itself as seen in block_create or other APIs returning blocks.

  It still includes the “account” and “amount” properties you’d see without this option. State/universal blocks in the raw history will also have a subtype field indicating their equivalent “old” block. Unfortunately, the “account” parameter for open blocks is the account of the source block, not the account of the open block, to preserve similarity with the non-raw history.

• count – Number of blocks to retrieve in a single call to the node. By default, it is 10 blocks.

• head – head (64 hexadecimal digits string, 256 bit). Default is the latest block. Use this block as the head of the account instead. Useful for pagination.

• offset – offset (decimal integer). Skips a number of blocks starting from head (if given). Not often used. Available since version 11.0

• reverse –

  Boolean, False by default. If set to True, the response starts from head (if given, otherwise the first block of the account), and lists blocks up to the frontier (limited by “count”).

  Note: the field previous in the response changes to next. Available since version 19.0

• account_filter –

  List of public addresses. If set, results will be filtered to only show sends/receives connected to the provided account(s).

  Available since version 19.0. Note: In v19.0, this option does not handle receive blocks; fixed in v20.0.

account_info(nano_address, representative=False, weight=False, pending=True, include_confirmed=False)

Returns frontier, open block, change representative block, balance, last modified timestamp from local database & block count for account.

WARNING: Only works for accounts that have received their first transaction and have an entry on the ledger, will return “Account not found” otherwise.

Source: https://docs.nano.org/commands/rpc-protocol/#account_info

Parameters

• nano_address – Address of the account with format “NANO_…”.

• representative – Boolean, false by default. Additionally, returns representative for account.

• weight – Boolean, false by default. Additionally, returns voting weight for account.

• pending – Boolean, false by default. Additionally, returns receivable balance for account.

• include_confirmed –

  Boolean, false by default. Adds new return fields with prefix of confirmed_ for consistency:

  • confirmed_balance: balance for only blocks on this account that have already been confirmed

  • confirmed_height: matches confirmation_height value

  • confirmed_frontier: matches confirmation_height_frontier value

  If representative option also true,

  • confirmed_representative included (representative account from the confirmed frontier block)

  If receivable option also true,

  • confirmed_receivable included (balance of all receivable amounts where the matching incoming send

  blocks have been confirmed on their account)

accounts_balances(addresses)

Returns how much RAW is owned and how many have not yet been received by accounts list.

Source: https://docs.nano.org/commands/rpc-protocol/#accounts_balances

Parameters

addresses – List of “NANO_…” addresses.

accounts_frontiers(addresses)

Returns a list of pairs of account and block hash representing the head block for accounts list.

Source: https://docs.nano.org/commands/rpc-protocol/#accounts_frontiers

Parameters

addresses – List of “NANO_…” addresses.

accounts_pending(accounts, threshold=None, source=False, count=1, include_active=False, sorting=True, include_only_confirmed=True)

Returns a list of confirmed block hashes which have not yet been received by these accounts

source: https://docs.nano.org/commands/rpc-protocol/#accounts_pending

Parameters

• accounts – List of accounts [”nano_…”, “nano_…”] to check for pending blocks.

• threshold – Number (128 bit, decimal), default None. Returns a list of receivable block hashes with amount more or equal to threshold.

• source – Boolean, False by default. Returns a list of receivable block hashes with amount and source accounts.

• count – Number, 1 by default. Specifies the number of pending blocks to be retrieved.

• include_active – Boolean, false by default. Include active (not confirmed) blocks.

• sorting – Boolean, false by default. Additionally, sorts each account’s blocks by their amounts in descending order.

• include_only_confirmed – Boolean, true by default. Only returns blocks which have their confirmation height set or are undergoing confirmation height processing. If false, unconfirmed blocks will also be returned.

active_difficulty(include_trend=False)

Returns the difficulty values (16 hexadecimal digits string, 64 bit) and related multiplier from base difficulty. [DEPRECATED as of V22]

Source: https://docs.nano.org/commands/rpc-protocol/#active_difficulty

Parameters

include_trend – Boolean, false by default. Also returns the trend of difficulty seen on the network as a list of multipliers.

available_supply()

Returns how many raw are in the public supply.

Source: https://docs.nano.org/commands/rpc-protocol/#available_supply

block_confirm(block_hash)

Request asynchronous confirmation for block from known online representative nodes. Once the confirmation is requested to the node, a confirmation process starts.

It is required to peek for confirmation results at confirmation history.

Source: https://docs.nano.org/commands/rpc-protocol/#block_confirm

NOTE: Unless there was an error encountered during the command execution, the response will always return “started”: “1”.

This response does not indicate the block was successfully confirmed, only that an error did not occur.

This response happens even if the block has already been confirmed previously and notifications will be triggered for this block (via HTTP callbacks or WebSockets) in all cases. This behavior may change in a future release.

Parameters

block_hash – Hash of the block to check.

block_count(include_cemented=True)

Reports the number of blocks in the ledger and unchecked synchronizing blocks.

Source: https://docs.nano.org/commands/rpc-protocol/#block_count

Parameters

include_cemented – Default True. If True, “cemented” in the response will contain the number of cemented blocks.

block_info(block_hash, json_block=True)

Retrieves a json representation of the block in contents along with:

• since version 18.0: block_account, transaction amount, block balance, block height in account chain, block local modification timestamp.

• since version 19.0: Whether block was confirmed, subtype (for state blocks) of send, receive, change or epoch.

Source: https://docs.nano.org/commands/rpc-protocol/#block_info

Parameters

• block_hash – Hash of the block to check.

• json_block – Default False. If True, “contents” will contain a JSON subtree instead of a JSON string.

blocks_info(blocks_hashes, json_block=True, include_not_found=False)

Retrieves a json representations of blocks in contents along with:

• since version 18.0: block_account, transaction amount, block balance, block height in account chain,

  block local modification timestamp.

• since version 19.0: Whether block was confirmed, subtype (for state blocks) of send, receive, change or

  epoch.

• since version 23.0: successor returned.

Using the optional json_block is recommended since v19.0.

Source: https://docs.nano.org/commands/rpc-protocol/#blocks_info

Parameters

• blocks_hashes – List of blocks hashes to retrieve

• json_block – Default False. If True, “contents” will contain a JSON subtree instead of a JSON string.

• include_not_found – Default False. If True, an additional key “blocks_not_found” is provided in the response, containing a list of the block hashes that were not found in the local database. Previously to this version an error would be produced if any block was not found.

healthy()

Checks the health status for this node.

Returns

True if node can be used, False otherwise.

property http_url

load_snapshot(snapshot)

Loads a node snapshot into this virtual instance. A snapshot contains all the required information to make offline operations on certain accounts.

Incremental updates are supported by default, meaning that the internal state of this virtual node can be updated with sequential loads of snapshots.

Parameters

snapshot – snapshot of accounts, blocks and transactions history from a real node.

peers()

Returns a list of pairs of online peer IPv6:port and its node protocol network version.

Source: https://docs.nano.org/commands/rpc-protocol/#peers

process(block_definition, subtype=None)

Virtual process – No signatures are checked, no correctness is checked.

Operates the accounts referenced by the block_definition without ensuring its correctness.

representatives(count=10, sorting=False)

Returns a list of pairs of representative and their voting weight.

Source: https://docs.nano.org/commands/rpc-protocol/#representatives

Parameters

• count – Number. Returns a list of pairs of representative and their voting weight up to count.

• sorting – Boolean, false by default. Additional sorting representatives in descending order. NOTE: The “count” option is ignored if “sorting” is specified

representatives_online(weight=True, accounts=None)

Returns a list of online representative accounts that have voted recently.

Source: https://docs.nano.org/commands/rpc-protocol/#representatives_online

Parameters

• weight – Boolean, false by default. Returns voting weight for each representative.

• accounts – Array of accounts. Returned list is filtered for only these accounts.

telemetry()

Return metrics from other nodes on the network. By default, returns a summarized view of the whole network.

Source: https://docs.nano.org/commands/rpc-protocol/#telemetry

property version

Returns the node information and version.

Source: https://docs.nano.org/commands/rpc-protocol/#version

property ws

property ws_url