nanoblocks.account subpackage

The account subpackage contains classes to manage the accounts in the Nano network.

This subpackage is indirectly handled by the nanoblocks.network.NanoNetwork class and should not be instantiated manually.

Account

class nanoblocks.account.account.Account(nano_address, nano_network, initial_update=True)

Bases: nanoblocks.base.nanoblocks_class.NanoblocksClass

Handles a single account in the Nano network.

Contains all the methods that allows to interact with accounts, like reading the state, sending/receiving amounts or reading the blockchain of the account.

By default every account is read-only, unless a private key is available.

Parameters

nano_address – Nano address of the account. E.g “nano_3pyz..”.
nano_network – The nano network owning this account.
initial_update – Flag to determine if the account should be updated at start or not. Updating an account requires querying the backend node.

property address: Provides the account nanoblocks address of this account. E.g. “nano_3pyz…”

property balance

Provides the total balance for this account.

Note: a call to update() or offline_update() before balance is highly encouraged!!

property block_count

Provides the number of block counts for this account.

Note: a call to update() or offline_update() before block_count is highly encouraged!!

build_change_representative_block(new_representative, work_hash=None)

Build the state block for changing the representative for this account and returns it.

Parameters

new_representative – Account or string for the new representative
work_hash – Work hash for changing the representative. If no work_hash is provided, the change will be local and not propagated through the nodes.

build_receive_block(pending_block, work_hash=None, new_representative=None)

Builds and signs the receive transaction block for the specified pending block and returns it.

Note that this method does not broadcast the block, but returns it wrapped in a nanoblocks.block.BlockReceive class.

The returned block object can be broadcasted using the method broadcast() from the property blocks of the class nanoblocks.network.NanoNetwork.

A pending block can be obtained by iterating over the pending_transactions property of the class nanoblocks.account.Account.

Parameters

pending_block – Pending block to receive from.
work_hash – work hash for the receive transaction.
new_representative – Representative account object to set in this transaction (can be changed on any transaction). None to set the same representative.

build_send_block(account_target, nano_amount, work_hash=None, new_representative=None)

Builds and signs the send transaction block and returns it.

Note that this method does not broadcast the block, but returns it wrapped in a nanoblocks.block.BlockSend class.

The returned block object can be broadcasted using the method broadcast() from the property blocks of the class nanoblocks.network.NanoNetwork.

Parameters

account_target – Account target for the send. It can be either an Account object or a string with the public address.
nano_amount – Amount of nanoblocks to send. It can be an Amount() object or an amount in “Nano” units.
work_hash – Hash result of work for this transaction. A WorkServer can be used to build the hash for an account. If None, it will try to use a local work server.
new_representative – Representative account to set in this transaction (can be changed on any transaction). None to set the same representative.

Returns

Returns the send block, signed, ready to broadcast to the network.

change_representative(new_account_representative, wait_confirmation=True, confirmation_timeout_secs=30)

Easy interface for changing the representative. Builds, signs and broadcasts the change block to the network.

Example:
account.change_representative(”nano_..”) # Changes the representative to “nano_…”

Parameters

new_account_representative – Nano account (string “nano_…” or Account object) destination.
wait_confirmation – Boolean flag to wait for the network to confirm the block.
confirmation_timeout_secs – Number of seconds to wait for confirmation of the block.

Returns

Returns the published block.

property confirmed_balance

Provides the confirmed balance for this account.

Note: a call to update() or offline_update() before confirmed_balance is highly encouraged!!

fill_account_info(account_info)

Fills the internal account info cached data. This is useful if signing is required and no node is available to query (e.g. under offline computers).

When an account info is filled within the account object, you are then able to send or receive blocks

account_info_example = {
    "frontier": "FF84533A571D953A596EA401FD41743AC85D04F406E76FDE4408EAED50B473C5",
    "open_block": "991CF190094C00F0B68E2E5F75F6BEE95A2E0BD93CEAA4A6734DB9F19B728948",
    "representative_block": "991CF190094C00F0B68E2E5F75F6BEE95A2E0BD93CEAA4A6734DB9F19B728948",
    "balance": "235580100176034320859259343606608761791",
    "modified_timestamp": "1501793775",
    "block_count": "33",
    "confirmation_height" : "28",
    "confirmation_height_frontier" : "34C70FCA0952E29ADC7BEE6F20381466AE42BD1CFBA4B7DFFE8BD69DF95449EB",
    "account_version": "1"
}

classmethod from_priv_key(private_key, nano_network)

Tries to access an account from the specified private key.

No addresses or public keys are required, as they can be derived from the private key itself.

Parameters

private_key – private key to derive the account from.
nano_network – The nano network owning this account.

classmethod from_pub_key(pub_key, nano_network)

Gives access to the specified account by its public key.

This method is read-only unless the account is unlocked() with the private key.

Parameters

pub_key – Public key for the nanoblocks account.
nano_network – The nano network owning this account.

property frontier: Provides the frontier block hash for this account. In case of a new account, this frontier is 0.

property history

property is_virtual

Retrieves whether this account exists or not in the network.

A new account does not exist until a “receive” block is emitted in its blockchain.

property last_update

Returns

Datetime of the last update of this account.

property last_update_elapsed_seconds

property modified_date

Provides the last modified date for this account.

Note: a call to update() or offline_update() before modified_date is highly encouraged!!

offline_update(account_info)

Performs an offline update with the given account_info. This method does not interact with a node and can be executed offline to update the information of an account object (for example, taking this info from a local json file).

Parameters: account_info – Dictionary containing information of the account (frontier, block_count, representative, weight, status, balance, pending, modified_timestamp, …).

offline_update_by_block(block_state)

Updates the account with the provided block state.

The block state must be crafted for the current account.

Parameters: block_state – BlockState object signed, with work.

offline_update_representative(new_representative)

Sets the representative for this account locally, useful under offline environments or for local updates.

Parameters: new_representative – Account or string for the new representative

property pending_balance

Provides the pending balance for this account.

Note: a call to update() or offline_update() before pending_balance is highly encouraged!!

property pending_transactions: Retrieves the pending transactions for the account.

property private_key: Provides the private key of this account, if unlocked.

property public_key: Provides the public key of this account.

property qr_code

Generates a QR code representation of this account in PIL format.

If a payment is desired, use the .request_payment(…).qr_code method instead.

Returns: QR code representation of the account

receive_nano(block_to_receive=None, wait_confirmation=True, confirmation_timeout_secs=30)

Easy interface for receiving a transaction. Builds, signs and broadcasts the receive block to the network.

Example:: account.receive_nano() # Receives the next pending transaction (if any)

Parameters

block_to_receive – Pending transaction to receive (can be obtained from account.pending_transactions list). In case of None, the method automatically peeks for the next pending transaction.
wait_confirmation – Boolean flag to wait for the network to confirm the block.
confirmation_timeout_secs – Number of seconds to wait for confirmation of the block.

Returns

Returns the published block. None if no pending transactions.

refcount(): Retrieves how many references to this account are active. :return: the number of active references to this account.

property representative

Provides the representative for this account.

Note: a call to update() or offline_update() before representative is highly encouraged!!

request_payment(nano_units_amount=None)

Generates the payment object which contains payment handle for the given amount

Parameters: nano_units_amount – Amount of NANO to hook payment for. If a different unit measure is required, wrap it into an Amount() class. If no amount is required, set it to None.

send_nano(account_target, nano_amount, wait_confirmation=True, confirmation_timeout_secs=30)

Easy interface for sending a transaction. Builds, signs and broadcasts the send block to the network.

Example:: account.send_nano(”nano_..”, “0.01”) # Sends 0.01 Nano to the account ‘nano_’

Parameters

account_target – Nano account (string “nano_…” or Account object) destination.
nano_amount – Amount of Nano to send (string or Amount object).
wait_confirmation – Boolean flag to wait for the network to confirm the block.
confirmation_timeout_secs – Number of seconds to wait for confirmation of the block.

Returns

Returns the published block.

to_dict(): Retrieves the cached account information. Note: a call to update() before info() is highly encouraged!!

unlock(private_key)

Tries to unlock this account with the given private key.

If the specified private key does not derive the public key of the account, an exception is raised.

Note that a private key that does not belong to the account’s public key can’t be used to sign the blocks, as the network is going to reject them.

Parameters: private_key – String hexadecimal representing the private key of the account.

property unlocked: Retrieves whether this account is unlocked with the private key or not.

update(): Retrieves the account information from the node (if available) and caches it inside the object.

property weight

Provides the weight for this account.

Note: a call to update() or offline_update() before weight is highly encouraged!!