API

Accounts

nanolib.accounts

Methods for creating keys and IDs for NANO accounts and dealing with wallet seeds

class nanolib.accounts.AccountKeyPair

NANO key pair

Variables:
  • private (str) – Private key as a 64-character hex string
  • public (str) – Public key as a 64-character hex string
class nanolib.accounts.AccountIDPrefix

Prefixes used for NANO account IDs

NANO = 'nano_'

NANO prefix. Newer prefix, may not be supported by all endpoints.

XRB = 'xrb_'

XRB prefix. Recognized universally.

nanolib.accounts.validate_private_key(private_key)

Validate the given private key and raise an exception on failure

Parameters:private_key (str) – Private key as a 64-character hex string
Raises:InvalidPrivateKey – If the private key is invalid
Returns:The private key
Return type:str
nanolib.accounts.validate_public_key(public_key)

Validate the given public key and raise an exception on failure

Parameters:public_key (str) – Public key as a 64-character hex string
Raises:InvalidPublicKey – If the public key is invalid
Returns:The public key
Return type:str
nanolib.accounts.is_account_id_valid(account_id)

Check if the account ID is valid

Parameters:account_id (str) – Account ID as a string
Returns:True if the account ID is valid, False otherwise
Return type:bool
nanolib.accounts.validate_account_id(account_id)

Validate a NANO account ID and raise an exception on failure

Parameters:account_id (str) – Account ID as a string
Raises:InvalidAccount – If the account ID is invalid
Returns:The account ID
Return type:str
nanolib.accounts.validate_seed(seed)

Validate a NANO seed and raise an exception on failure

Parameters:seed (str) – Seed as a 64-character hex string
Raises:InvalidSeed – If the seed is invalid
Returns:The seed
Return type:str
nanolib.accounts.get_account_key_pair(private_key)

Generate a public key from a private key and return the key pair

Parameters:private_key – Private key as a 64-character hex string
Raises:InvalidPrivateKey – If the private key is invalid
Returns:Return the key pair
Return type:AccountKeyPair
nanolib.accounts.generate_account_private_key(seed, index)

Generate account’s private key from a 32-byte seed and index

Parameters:
  • seed (str) – Seed as a 64-character hex string
  • index (int) – Index of the account private key to generate
Raises:
Returns:

Account private key as a 64-character hex string
Return type:

str
nanolib.accounts.generate_account_key_pair(seed, index)

Generate an account key pair from a 32-byte seed and index

Parameters:
  • seed (str) – Seed as a 64-character hex string
  • index (int) – Index of the account key pair to generate
Raises:
Returns:

Account public and private key pair
Return type:

AccountKeyPair
nanolib.accounts.get_account_id(*, public_key=None, private_key=None, prefix=None)

Get NANO account ID by using either a public key or a private key

Note

Parameters public_key and private_key are mutually exclusive and have to be given as keyword arguments

Parameters:
Raises:
  • ValueError – If the given prefix isn’t either XRB or NANO
  • TypeError – If both private and public keys are given, or if none are given as named parameter
  • InvalidPublicKey – If the given public key is invalid
  • InvalidPrivateKey – If the given private key is invalid
Returns:

Account ID
Return type:

str

Usage:

>>> from nanolib.accounts import get_account_id, AccountIDPrefix
>>> get_account_id(private_key="2"*64)
'xrb_1iwamgozb5ckj9zzojbnb79485dfiw8jegedzwzuzy5b4a19cbs8b4tsdzo3'
>>> get_account_id(public_key="2"*64)
'xrb_1aj46aj46aj46aj46aj46aj46aj46aj46aj46aj46aj46aj46aj4ykus34mi'
>>> get_account_id(public_key="2"*64, prefix=AccountIDPrefix.NANO)
'nano_1aj46aj46aj46aj46aj46aj46aj46aj46aj46aj46aj46aj46aj4ykus34mi'
>>> get_account_id(public_key="2"*64, prefix="nano_")
'nano_1aj46aj46aj46aj46aj46aj46aj46aj46aj46aj46aj46aj46aj4ykus34mi'

nanolib.accounts.get_account_public_key(*, account_id=None, private_key=None)

Get a NANO public key using either an account ID or a private key

Note

Parameters account_id and private_key are mutually exclusive and have to be given as keyword arguments

Parameters:
  • account_id (str) – Account ID
  • private_key (str) – Private key as a 64-character hex string
Raises:
  • TypeError – If both account ID and private key are given, or if none are given as keyword arguments
  • InvalidAccount – If the given account ID is invalid
  • InvalidPrivateKey – If the given private key is invalid
Returns:

Public key as a 64-character hex string
Return type:

str
nanolib.accounts.generate_account_id(seed, index)

Derive an account ID from a seed and an index

Parameters:
  • seed (str) – Seed as a 64-character hex string
  • index (int) – Index of the account ID to generate
Returns:

Account ID
Return type:

str
nanolib.accounts.generate_seed()

Generate a secure random 64-character hexadecimal seed for use in generating NANO accounts

Returns:Seed as a 64-character hex string
Return type:str

Blocks

nanolib.blocks

Methods to work with NANO blocks and a Block class to construct (either manually or from JSON) and process NANO blocks

nanolib.blocks.balance_to_hex(balance)

Convert a NANO balance to a 16-character hex string used in serialized legacy send blocks

Parameters:balance – Balance to convert
Returns:Balance as a 16-character hex string with necessary padding
Return type:str
nanolib.blocks.parse_hex_balance(balance)

Parse and return given hex-formatted balance as an integer. Hex-formatted balance is used in legacy send blocks

Parameters:balance (str) – Hex-formatted balance to convert
Returns:Converted balance
Return type:int
nanolib.blocks.parse_signature(signature)

Parse a signature and return it if it’s syntactically valid

Note

This method only checks that the signature’s format is correct. To verify a signature, create a Block and use its Block.verify_signature()

Parameters:signature (str) – Signature as a 128-character hex string
Raises:ValueError – Signature is invalid
Returns:Signature in uppercase
Return type:str
nanolib.blocks.validate_balance(balance)

Validate the balance

Parameters:balance (int) – Balance
Raises:InvalidBalance – If the balance is less than 0 or higher than the maximum possible balance (2^128 - 1)
Returns:Balance
Return type:int
nanolib.blocks.validate_block_hash(h)

Validate the block hash

Parameters:h (str) – Block hash as a 64-character hex string
Raises:InvalidBlockHash – If the block hash is invalid
Returns:Block hash in uppercase
Return type:str
class nanolib.blocks.Block(block_type, verify=True, difficulty=None, **kwargs)

A NANO block.

Can be constructed manually or from a JSON string

Note

For deserializing existing blocks, see Block.from_json() and Block.from_dict()

block_hash

BLAKE2b hash for the block used to identify the block

Raises:InvalidBlock – If the block hash can’t be calculated for the block
Returns:Block hash as a 64-character hex string
Return type:str
complete

Check if the block has a valid signature and valid work

Returns:True if both the signature and work are included and both were verified to be correct, False otherwise
Return type:bool
classmethod from_dict(d, verify=True, difficulty=None)

Create a Block instance from a dictionary

Parameters:
  • d (dict) – The block fields to deserialize
  • verify (bool) – If True, signature and/or the proof-of-work will be verified
  • difficulty (str) – Work difficulty used to check PoW’s validity. Default is NANO main net’s default work difficulty.
Returns:

Block
Return type:

Block
classmethod from_json(json, verify=True, difficulty=None)

Create a Block instance from a JSON-formatted string

Parameters:
  • json (str) – A JSON-formatted block to deserialize
  • verify (bool) – If True, signature and/or the proof-of-work will be verified
  • difficulty (str) – Work difficulty used to check PoW’s validity. Default is NANO main net’s default work difficulty.
Returns:

Block
Return type:

Block
has_valid_signature

Check if the block has a valid signature

Returns:True if the block has a valid signature, False if either Block.signature or Block.account is missing, or if the signature was found to be invalid
Return type:bool
has_valid_work

Check if the block has valid work.

Note

This method assumes that NANO mainnet difficulty is used. In any other case use nanolib.blocks.Block.verify_work() instead.

Returns:True if the block has valid work that meets the difficulty, False if Block.work is missing or the work was found to be below the required difficulty
Return type:bool
json()

Return a JSON-formatted string of the block that can be broadcast to the NANO network

Returns:A JSON-formatted string
Return type:str
sign(private_key)

Sign the block and set the value for Block.signature

Raises:ValueError – If the block already has a signature
Returns:True if the signature was added successfully
Return type:bool
solve_work(difficulty=None, timeout=None)

Solve the work contained in this block and update the Block instance to include the work

Raises:

ValueError – If the block already has valid proof-of-work meeting the difficulty
Parameters:
  • difficulty (str) – The difficulty for the proof-of-work. NANO mainnet difficulty is used by default.
  • timeout (int, float or None) – Timeout in seconds. If provided, None will be returned if the work can’t be solved in the given time. If None, the function will block until the work is solved.
Returns:

True if the work was solved in the given time, False otherwise
Return type:

bool
to_dict()

Return a :type:`dict` consisting of items used in the block that can be broadcast to the NANO network

Note

The :ivar:`Block.block_type` has the key name type in the created :type:`dict`

Returns:A dictionary of block items
Return type:dict
tx_type

Return the transaction type of this block

For blocks besides ‘state’, this is the same as ‘block_type’. For ‘state’, the type is derived from the value of ‘link’ field

Returns:For legacy blocks, the transaction type can be open, change, receive or send. For state blocks, the transaction type can be change, open, send/receive or epoch
verify_signature()

Verify the signature in the block

Note

Block.account and Block.signature need to be set to verify the signature

Raises:
verify_work(difficulty=None)

Verify the work in the block

Parameters:

difficulty (str) – The difficulty for the proof-of-work. NANO mainnet difficulty is used by default.
Raises:
  • ValueError – If work isn’t included in the block
  • InvalidWork – If included work doesn’t meet the difficulty
work_block_hash

BLAKE2b hash that requires a valid PoW

For open blocks this is the public key derived from nanolib.blocks.Block.account. For other types of blocks, nanolib.blocks.Block.previous is used as the hash.

Returns:BLAKE2b hash used to generate a PoW
Return type:str
work_value

The work value attached to this block. The value must be equal to or higher than nanolib.blocks.Block.difficulty in order to be valid.

Returns:64-bit integer or None if this block doesn’t include work
Return type:int or None

Proof-of-work

nanolib.work.parse_work(work)

Parses a proof-of-work (PoW) value and returns it if it’s syntactically valid.

Note

This method only checks that the work’s format is correct. To validate a proof-of-work, use nanolib.work.validate_work()

Parameters:work (str) – Work as a 16-character hex string
Raises:InvalidWork – If the work is invalid
Returns:Work as a 16-character hex string
Return type:str
nanolib.work.validate_work(block_hash, work, difficulty='fffffff800000000')

Validate the proof-of-work.

Parameters:
  • block_hash (str) – Block hash as a 64-character hex string
  • work (str) – Work as a 16-character hex string
  • difficulty (str) – The difficulty for the proof-of-work as a 16-character hex string. NANO network’s difficulty is used by default.
Raises:

InvalidWork – If the work doesn’t meet the difficulty or isn’t a 16-character hex string
Returns:

The work as a 16-character hex string
Return type:

str
nanolib.work.validate_difficulty(difficulty)

Validate the work difficulty.

Parameters:difficulty (str) – Work difficulty as a 16-character hex string
Raises:InvalidDifficulty – If the difficulty isn’t a 16-character hex value
Returns:The work difficulty as a 16-character hex string
Return type:str
nanolib.work.derive_work_difficulty(multiplier, base_difficulty=None)

Derive the work difficulty from a provided multiplier and a base difficulty

Parameters:
  • multiplier (float) – Work multiplier as a float. Work difficulty with a multiplier of 2 requires on average twice as much work compared to the base difficulty.
  • base_difficulty (str) – Base difficulty as a 16-character hex string. NANO network’s difficulty is used by default.
Raises:
  • InvalidDifficulty – If the difficulty isn’t a 16-character hex string
  • ValueError – If the resulting difficulty is larger than \(2^{64}-1\)
Returns:

The adjusted work difficulty as a 16-character hex string
Return type:

str
nanolib.work.derive_work_multiplier(difficulty, base_difficulty=None)

Derive the work multiplier from a difficulty and a base difficulty.

Parameters:
  • difficulty (str) – Work difficulty as a 16-character hex string
  • base_difficulty (str) – Base work difficulty as a 16-character hex string. NANO network’s difficulty is used by default.
Raises:

InvalidDifficulty – If difficulty isn’t a 16-character hex string
Returns:

The work multiplier as a float. Work difficulty with a multiplier of 2 requires on average twice as much work compared to the base difficulty.
Return type:

float
nanolib.work.get_work_value(block_hash, work, as_hex=False)

Get the proof-of-work value. The work value must be equal to or higher than the work difficulty to be considered valid.

Parameters:
  • block_hash (str) – Block hash as a 64-character hex string
  • work (str) – Work as a 16-character hex string
  • as_hex (bool) – Whether to return the work value as a hex string or an integer. If True, a 16-character hex string is returned. If False, a 64-bit integer is returned. A 64-bit integer is returned by default.
Raises:
  • InvalidWork – If the work isn’t a 16-character hex string
  • InvalidBlockHash – If the block hash isn’t a 64-character hex string
Returns:

A 16-character hex string or a 64-bit integer depending on as_hex
Return type:

int or str
nanolib.work.solve_work(block_hash, difficulty='fffffff800000000', timeout=None)

Solve the work for the corresponding block hash.

Parameters:
  • block_hash (str) – Block hash as a 64-character hex string
  • difficulty (str) – The difficulty for the proof-of-work as a 16-character hex string. NANO network’s difficulty is used by default.
  • timeout (int, float or None) – Timeout in seconds. If provided, None will be returned if the work can’t be solved in the given time. If None, the function will block until the work is solved.
Returns:

The solved work as a 64-character hex string or None couldn’t be solved in time
Return type:

str or None

Units

nanolib.units

Methods for converting between different NANO denominations.

The smallest possible denomination is known as raw. The other common denominations are:

  • 1 nano = \(10^{24}\) raw
  • 1 knano = \(10^{27}\) raw
  • 1 Mnano/NANO = \(10^{30}\) raw

Or in other words:

  • 1 NANO = 1 000 000 nano
  • 1 000 knano = 1 NANO
  • 1 Mnano = 1 000 knano
  • 1 Mnano = 1 000 000 nano
  • 1 Mnano = 1 NANO

Warning

Note that nano and NANO are not interchangeable! If you are using the denominations in a context where they may cause confusion, consider using nano and Mnano instead.

Note

Denominations XRB/Mrai, Krai and xrb/rai were used before RaiBlocks’ rebranding as NANO. The corresponding old names for these denominations are:

  • Mnano/NANO = Mrai/XRB
  • knano = kRAI
  • Mnano = Mrai
  • nano = xrb/rai

Note

Consider storing all NANO values as integers using the raw denomination and only converting the value to another denomination when presenting a human-readable amount. nanolib uses Python’s Decimal library and increases precision on startup to account for precision loss. This precision can be changed during runtime by another library.

nanolib.units.convert(amount, source, target)

Convert an amount from one denomination to another

Parameters:
Raises:
  • ValueError – If the amount is higher than the NANO coin cap (\(2^{128} - 1\) raw)
  • TypeError" – If amount is not an int or a decimal.Decimal
Returns:

Converted amount
Return type:

decimal.Decimal
class nanolib.units.NanoDenomination

Denominations used in NANO

GIGANANO = 'Gnano'

1 Gnano = \(10^{33}\) raw

KILONANO = 'knano'

1 knano = \(10^{27}\) raw

MEGANANO = 'Mnano'

1 Mnano = \(10^{30}\) raw

MICRONANO = 'unano'

1 unano = \(10^{18}\) raw

MILLINANO = 'millinano'

1 mnano = \(10^{21}\) raw

NANO = 'nano'

1 nano = \(10^{24}\) raw

RAW = 'raw'

Smallest division used in NANO

Exceptions

exception nanolib.exceptions.InvalidBlock

The block is invalid.

exception nanolib.exceptions.InvalidWork

The given work is invalid.

exception nanolib.exceptions.InvalidDifficulty

The given work difficulty is invalid.

exception nanolib.exceptions.InvalidMultiplier

The given work multiplier is invalid.

exception nanolib.exceptions.InvalidSignature

The given signature is invalid.

exception nanolib.exceptions.InvalidBlockHash

The given block hash is invalid.

exception nanolib.exceptions.InvalidBalance

The given balance is invalid.

exception nanolib.exceptions.InvalidSeed

The seed is invalid.

exception nanolib.exceptions.InvalidAccount

The NANO account ID is invalid.

exception nanolib.exceptions.InvalidPrivateKey

The NANO private key is invalid.

exception nanolib.exceptions.InvalidPublicKey

The NANO public key is invalid.