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:
-
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: Raises: - InvalidSeed – If the seed is invalid
- ValueError – If the index isn’t an integer
Returns: Account private key as a 64-character hex string
Return type:
-
nanolib.accounts.
generate_account_key_pair
(seed, index)¶ Generate an account key pair from a 32-byte seed and index
Parameters: Raises: - InvalidSeed – If the seed is invalid
- ValueError – If the index isn’t an integer
Returns: Account public and private key pair
Return type:
-
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: - public_key (str) – Public key as a 64-character hex string
- private_key (str) – Private key as a 64-character hex string
- prefix (str) – (optional) Prefix to use for the account ID. Can be either
AccountIDPrefix.NANO
orAccountIDPrefix.XRB
. Defaults toAccountIDPrefix.XRB
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: 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:
-
nanolib.accounts.
generate_account_id
(seed, index)¶ Derive an account ID from a seed and an index
Parameters: Returns: Account ID
Return type:
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 itsBlock.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()
andBlock.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 dictionaryParameters: Returns: Block
Return type:
-
classmethod
from_json
(json, verify=True, difficulty=None)¶ Create a
Block
instance from a JSON-formatted stringParameters: Returns: Block
Return type:
-
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
orBlock.account
is missing, or if the signature was found to be invalidReturn 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 difficultyReturn 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: Returns: True if the work was solved in the given time, False otherwise
Return type:
-
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
andBlock.signature
need to be set to verify the signatureRaises: - ValueError –
Block.account
orBlock.signature
isn’t set - InvalidSignature – Signature was verified and found to be invalid
- ValueError –
-
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
-
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: 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:
-
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: 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:
-
nanolib.work.
derive_work_multiplier
(difficulty, base_difficulty=None)¶ Derive the work multiplier from a difficulty and a base difficulty.
Parameters: 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:
-
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:
-
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:
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: - amount (decimal.Decimal or int) – Amount to convert
- source (NanoDenomination) – The denomination to convert from
- target (NanoDenomination) – The denomination to convert to
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:
-
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.