siliqua.wallet package

Submodules

siliqua.wallet.accounts module

class siliqua.wallet.accounts.AccountSource

Bases: enum.Enum

An enumeration.

PRIVATE_KEY = 'private'
SEED = 'seed'
WATCHING = 'watching'
class siliqua.wallet.accounts.BlockProxy

Bases: object

Allow an object containing ‘block’ Block instance to access underlying RawBlock fields directly.

Eg. instead of block.block.account, you can access block.account

property account
property account_id
property balance
property block_hash
property block_type
property complete
property destination
property difficulty
property has_valid_signature
property has_valid_work
property json
property previous
property representative
property sign
property signature
property solve_work
property source
property tx_type
property verify_signature
property verify_work
property work
property work_block_hash
property work_value
class siliqua.wallet.accounts.Account(*args, **kwargs)

Bases: siliqua.wallet.util.WalletSerializable

Wallet account that can be spendable or reading-only. The account object also contains the entire account blockchain.

SERIALIZE_PROPS = {'account_id': {'required': True, 'secret': False, 'type': <class 'str'>}, 'blocks': {'list': True, 'secret': False, 'type': <class 'siliqua.wallet.accounts.Block'>}, 'name': {'type': <class 'str'>}, 'precomputed_work': {'type': <class 'siliqua.wallet.accounts.PrecomputedWork'>}, 'private_key': {'required': False, 'secret': True, 'type': <class 'str'>}, 'representative': {'type': <class 'str'>}, 'seed_index': {'type': <class 'int'>}, 'source': {'required': True, 'secret': False, 'type': <enum 'AccountSource'>}}
property account_id
add_block(block, callbacks=None)
attach_precomputed_work(block)

Add the precomputed work to a new block if it is available and valid. In either case, discard the precomputed work afterwards.

balance
block_map
property blocks
change_representative(representative, callbacks=None)

Change the account representative. A new block is also appended to the blockchain unless the account is empty.

Parameters
Returns

Block instance if block was created, otherwise True

Return type

siliqua.wallet.accounts.Block or None

confirm_block(block, callbacks=None)

Confirm the given block. Confirmed blocks cannot be rejected anymore.

Parameters

block (siliqua.wallet.accounts.Block) – Block to confirm

confirmed_head
property name
property precomputed_work
property private_key
property public_key
receive_block(link_block, callbacks=None)

Pocket a link block by creating a new block in the blockchain

received_block_hashes
reject_block(block, error, callbacks=None)

Remove a rejected non-confirmed block from the account blockchain.

This can happen if we’re trying to pocket a block before the node we’re connected to has finished syncing the account blockchain. In this case, remove the generated receive block and try pocketing the pending block later.

remove_block(block, callbacks=None)

Remove a block from the account blockchain including any of its successors.

Most of the time this shouldn’t be called directly. Instead, Block.reject_block() can be used to remove non-confirmed blocks that were not accepted by the network.

property representative
property representative_to_add

Return the account representative, representative of the newest block or the fallback representative (burn account), whichever is available first

This ensures that some representative can be used for new blocks

property seed_index
send(account_id, amount, callbacks=None)

Create a send block and add it to the blockchain

Parameters
Returns

Created block

Return type

siliqua.wallet.accounts.Block

set_account_id(account_id)
set_blocks(blocks)
set_name(name)
set_precomputed_work(precomputed_work)
set_private_key(private_key, is_secret)
set_representative(representative)
set_seed_index(seed_index)
set_source(source)
property source
update_confirmed_head()

Check if the latest confirmed block has changed and update the confirmed_head property accordingly

class siliqua.wallet.accounts.LinkBlock(amount, block=None, block_data=None, timestamp=None, verify=False)

Bases: siliqua.wallet.util.WalletSerializable, siliqua.util.BlockProxy

Link block is a pocketed block that’s included with Block.link_block when applicable.

This allows the pocketed block to be timestamped separately from the account block that pockets the block

SERIALIZE_PROPS = {'amount': {'required': True, 'serialize': <class 'str'>, 'type': <class 'str'>}, 'block_data': {'required': True, 'type': <class 'dict'>}, 'timestamp': {'type': <class 'siliqua.wallet.util.Timestamp'>}}
property amount
property block

Underlying nanolib.Block instance

property block_data
property recipient

Recipient of NANO sent in this block

Returns

Account ID

Return type

str

set_amount(amount)
set_block_data(block_data)
set_timestamp(timestamp)
property timestamp
class siliqua.wallet.accounts.Block(block_data=None, block=None, link_block=None, description=None, timestamp=None, confirmed=True)

Bases: siliqua.wallet.util.WalletSerializable, siliqua.util.BlockProxy

Block associated with wallet account.

In addition to the block data itself, Block instances also contain a timestamp, the pocketed block (if applicable) and an optional description field

SERIALIZE_PROPS = {'block_data': {'required': True, 'type': <class 'dict'>}, 'confirmed': {'type': <class 'bool'>}, 'description': {'type': <class 'str'>}, 'link_block': {'type': <class 'siliqua.wallet.accounts.LinkBlock'>}, 'timestamp': {'type': <class 'siliqua.wallet.util.Timestamp'>}}
property amount

The amount transacted in this block.

Returns

Amount transacted

Return type

int

property balance

Account balance as of this block

Returns

Balance

Return type

int

property block

The underlying nanolib.Block instance

Returns

Block

Return type

nanolib.Block

property block_data
property confirmed
property description
next
prev
set_block_data(block_data)
set_confirmed(confirmed)
set_description(description)
set_timestamp(timestamp)
property timestamp
property tx_type

The transaction type for this block.

Possible values are identical as with nanolib.blocks.Block.tx_type except that send or receive is returned instead of send/receive when applicable.

siliqua.wallet.exceptions module

exception siliqua.wallet.exceptions.AccountAlreadyExists

Bases: ValueError

Account already exists.

exception siliqua.wallet.exceptions.AccountNotSpendable

Bases: ValueError

Account is watching-only when an account with a private key is required

exception siliqua.wallet.exceptions.InsufficientBalance

Bases: ValueError

Insufficient balance to send the block.

exception siliqua.wallet.exceptions.InvalidAccountBlock

Bases: ValueError

The account-specific block is invalid.

exception siliqua.wallet.exceptions.InvalidEncryptionKey

Bases: ValueError

The encryption key is invalid.

exception siliqua.wallet.exceptions.TransactionAlreadyExists

Bases: ValueError

Wallet transaction already exists.

exception siliqua.wallet.exceptions.UnsupportedWalletVersion(wallet_version, required_version)

Bases: ValueError

Wallet has a newer version than what is supported by the current installation

exception siliqua.wallet.exceptions.ValueEncrypted

Bases: Exception

The value to read is encrypted.

exception siliqua.wallet.exceptions.WalletDecryptionError

Bases: ValueError

Wallet couldn’t be decrypted.

exception siliqua.wallet.exceptions.WalletFileInvalid

Bases: Exception

The wallet file is invalid.

exception siliqua.wallet.exceptions.WalletLocked

Bases: Exception

The wallet is locked.

exception siliqua.wallet.exceptions.WalletMigrationRequired(wallet_version, required_version)

Bases: ValueError

Wallet has older version and will need to be migrated first before use

siliqua.wallet.secret module

class siliqua.wallet.secret.Secret(enc_payload=None, val=None, secret_key=None, algorithm=<SecretAlgorithm.DEFAULT: 'fernet'>)

Bases: object

An object containing a value that is always stored in an encrypted format.

The secret can be serialized into and deserialized from JSON.

algorithm
enc_payload
get(secret_key)

Decrypt and return a copy of the decrypted value

Parameters

secret_key (str) – Secret key

Returns

Decrypted value

json()

Return a dict of the encrypted payload which can be later deserialized

Returns

Encrypted payload

Return type

dict

set(val, secret_key)

Replace the encrypted value

Parameters

  • val – Value to encrypt

  • secret_key (str) – Secret key

class siliqua.wallet.secret.SecretAlgorithm

Bases: enum.Enum

Algorithm used to encrypt a secret.

Only Fernet is supported for now.

DEFAULT = 'fernet'
FERNET = 'fernet'
class siliqua.wallet.secret.KeyType

Bases: enum.Enum

The type of key used for encryption.

A different key is derived from the same passphrase: one for encrypting secrets and another for encrypting the wallet itself

SECRET = 'secrets'
WALLET = 'wallet'
siliqua.wallet.secret.calculate_key_iteration_count(seconds=1)

Calculate the amount of iterations that can be performed in the given timespan.

This amount can be used to determine the amount of iterations used for key derivation.

Returns

Key iteration count

Return type

int

siliqua.wallet.secret.get_secret_key(passphrase=None, key_type=None, iterations=500000)

Derive a secret key using a passphrase, key type and iteration count

Parameters

  • passphrase (str) – Passphrase

  • key_type (KeyType) – Key type used to derive the secret key

  • iterations (int) – Key iteration count. Higher values increase security at the cost of more work required to derive the secret key.

Returns

URL safe Base64 encoded secret key

Return type

str

siliqua.wallet.secret.encrypt(val, secret_key, algorithm)

Encrypt a value with a secret key and algorithm

Parameters

  • val – Value to encrypt. Multiple types (dict, str, bytes, list) are supported.

  • secret_key (str) – URL safe Base64 encoded secret key

  • algorithm (SecretAlgorithm) – Algorithm used for encryption

Returns

Encrypted payload as a dict

Return type

dict

siliqua.wallet.secret.decrypt(payload, secret_key)

Decrypt a payload with a secret key

Parameters

  • val – Dict to decrypt

  • secret_key (str) – URL safe Base64 encoded secret key

Returns

Decrypted value

siliqua.wallet.secret.validate_encryption_key(key)

Check that the given encryption key is formatted in a valid way

Raises

InvalidEncryptionKey – If the encryption key is invalid

siliqua.wallet.util module

class siliqua.wallet.util.WalletSerializable

Bases: object

WalletSerializable allows deserialization/serialization of an object with encryption for selected fields

SERIALIZE_PROPS = {}
decrypt_secrets(secret_key)

Decrypt and remove encryption recursively from all secret properties

Parameters

secret_key (str) – Secret key

encrypt_secrets(secret_key)

Encrypt all properties recursively

Parameters

secret_key (str) – Secret key

classmethod from_dict(d=None, secret_key=None)

Deserialize the original object from a dict

get_secret(name, secret_key=None)

Get the value of a property that is possibly encrypted

set_secret(name, val, secret_key=None)

Set the value of a property that is possibly encrypted

Parameters

  • name (str) – Name of the field

  • val – Value for the field

  • secret_key (str) – Optional secret key for encrypting secret fields

to_dict(secret_key=None)
class siliqua.wallet.util.Timestamp(date, source)

Bases: siliqua.wallet.util.WalletSerializable

Timestamp consisting of the actual date and the source of information. This allows timestamps to be updated to be more accurate later.

SERIALIZE_PROPS = {'date': {'required': True, 'serialize': <function Timestamp.<lambda>>, 'type': <class 'str'>}, 'source': {'required': True, 'type': <enum 'TimestampSource'>}}
date
source
class siliqua.wallet.util.TimestampSource

Bases: enum.Enum

Timestamp source.

Attaching a source to a timestamp means that the accuracy of the timestamp can be determined and possibly improved later (eg. by using a third party service)

BROADCAST = 'broadcast'
NODE = 'node'
WALLET = 'wallet'
siliqua.wallet.util.wallet_parameter(setter)

Decorator to set error handling for setters for serializable fields in WalletSerializable instances

siliqua.wallet.util.get_current_timestamp()

Get the current timestamp. The source is set as the wallet.

class siliqua.wallet.util.HexDict(**kwargs)

Bases: collections.UserDict

A dictionary that accepts only hex-formatted key names. The key names are converted internally to bytes in order to save memory.

keys() → a set-like object providing a view on D's keys
values() → an object providing a view on D's values

siliqua.wallet.wallet module

class siliqua.wallet.wallet.WalletSeedAlgorithm

Bases: enum.Enum

Algorithm used for generating accounts from a seed

NANO = 'nano'
class siliqua.wallet.wallet.WalletProperties(*args, **kwargs)

Bases: siliqua.wallet.util.WalletSerializable

Contains miscellaneous properties related to the wallet, such as account generation seed, encryption status and such

Variables

  • seed_algorithm – Algorithm used to derive accounts from the seed

  • seed (str) – Wallet seed for generating accounts

  • gap_limit (int) – Minimum amount of unused accounts to generate from the seed

  • representative (str) – Representative account ID used as a default for new accounts

SERIALIZE_PROPS = {'gap_limit': {'type': <class 'int'>}, 'representative': {'type': <class 'str'>}, 'seed': {'secret': True, 'type': <class 'str'>}, 'seed_algorithm': {'secret': False, 'type': <enum 'WalletSeedAlgorithm'>}, 'version': {'type': <class 'int'>}}
property gap_limit
property representative
property seed
property seed_algorithm
set_gap_limit(gap_limit)
set_representative(representative)
set_seed(seed, is_secret)
set_seed_algorithm(algorithm)
set_version(version)
property version
class siliqua.wallet.wallet.Transaction(**kwargs)

Bases: siliqua.wallet.util.WalletSerializable

Transaction object used internally by the wallet to track unique transactions.

Only one transaction with the same txid can exist. Each transaction correponds to one block.

Variables
SERIALIZE_PROPS = {'account_id': {'required': True, 'type': <class 'str'>}, 'block_hash': {'required': True, 'type': <class 'str'>}, 'txid': {'required': True, 'type': <class 'str'>}}
property account_id
property block_hash
set_account_id(account_id)
set_block_hash(block_hash)
set_txid(txid)
property txid
class siliqua.wallet.wallet.Wallet(*args, **kwargs)

Bases: siliqua.wallet.util.WalletSerializable

Main wallet instance that can contain secret fields and be serialized into JSON.

A single wallet consists of wallet properties, accounts (spendable or watching-only), an address book and a transaction list.

SERIALIZE_PROPS = {'accounts': {'list': True, 'type': <class 'siliqua.wallet.accounts.Account'>}, 'address_book': {'serialize': <function Wallet.<lambda>>, 'type': <class 'dict'>}, 'encryption': {'type': <class 'siliqua.wallet.wallet.WalletEncryption'>}, 'properties': {'type': <class 'siliqua.wallet.wallet.WalletProperties'>}, 'transactions': {'list': True, 'type': <class 'siliqua.wallet.wallet.Transaction'>}}
account_map
property accounts
add_account(account)

Add Account instance to the wallet.

Note

Instead of calling this method directly, add_account_from_private_key() and add_account_from_account_id() can be used for convenience.

Parameters

account (siliqua.wallet.accounts.Account) – Account to add

Raises

TypeError – If account is not an Account instance

Returns

Account to add

Return type

siliqua.wallet.accounts.Account

add_account_from_account_id(account_id)

Add watching-only account with an account ID.

Parameters

account_id (str) – Account ID

Raises

AccountAlreadyExists – Account already exists

Returns

Created account

Return type

siliqua.wallet.accounts.Acconut

add_account_from_private_key(private_key)

Add a new account from a private key. If the account already exists as a watching-only account, private key will only be added instead.

Parameters

private_key (str) – Private key to add

Raises

  • AccountAlreadyExists – Account already exists with this private key

  • nanolib.exceptions.InvalidPrivateKey – Private key is invalid

Returns

Created account

Return type

siliqua.wallet.accounts.Account

add_to_address_book(account_id, name)

Add an account ID to the address book

Parameters

  • account_id (str) – Account ID

  • name (str) – Name for the account ID in the address book

Raises

nanolib.InvalidAccount – If the account ID is invalid

add_transaction(transaction)

Add transaction to the wallet

Parameters

transaction – Transaction to add

Type

siliqua.wallet.wallet.Transaction

Raises
Returns

Transaction

Return type

siliqua.wallet.wallet.Transaction

property address_book
property balance

Get the total balance of all accounts in the wallet

Returns

Balance

Return type

int

callbacks
change_passphrase(passphrase, encrypt_wallet, encrypt_secrets, key_iteration_count=None)

Change the wallet’s passphrase or remove encryption.

If passphrase is provided, all wallet secrets will be re-encrypted. If not, encryption is removed entirely.

Parameters

passphrase (str) – Passphrase to encrypt the wallet with

classmethod check_wallet_version(data)

Check whether the wallet data has the correct version and can be loaded directly

property encryption
generate_seed_account()

Generate a new account from the wallet’s seed

Raises

ValueError – If the wallet doesn’t have a seed

get_block(block_hash)

Get a block in the wallet by its block hash

Parameters

block_hash (str) – Block hash

Returns

Block if found, None otherwise

Type

siliqua.wallet.accounts.Block, siliqua.wallet.accounts.LinkBlock or None

get_blocks_to_broadcast()

Return a list of Block instances that haven’t been confirmed yet

Returns

Unconfirmed blocks

get_work_units_to_solve(work_difficulty, precompute_work=True)

Return a list of blocks that need to be solved in this wallet

classmethod is_wallet_data_valid(data)

Check if the given wallet data dictionary is valid

Parameters

data (dict) – Wallet data as a dict

Returns

True if valid, False otherwise

Return type

bool

classmethod is_wallet_file_encrypted(path)

Check if the given wallet file either has encrypted secrets or is encrypted entirely

classmethod is_wallet_file_valid(path)

Check if the given wallet file is valid.

Note

This method only continues reading the file until its validity can be determined, and should be preferred instead of is_wallet_data_valid() when checking a file.

Parameters

path (str) – Path to the wallet file

Returns

True if valid, False otherwise

Return type

bool

classmethod load(path, passphrase=None)

Load wallet from the given path. If the wallet file is encrypted, passphrase has to be provided.

Parameters

  • path (str) – Path to the wallet file

  • passphrase (str) – Optional passphrase. If the wallet file itself is encrypted, this is mandatory.

Raises
Returns

Wallet

Return type

siliqua.wallet.wallet.Wallet

lock()

Lock the wallet and stop access to secret properties

property properties
refill_accounts()

If the wallet has a seed and a valid gap limit, ensure that a correct amount of free accounts exist

Raises

ValueError – If the wallet doesn’t have a seed

Returns

Generated accounts as a list, if any

remove_account(account)

Remove Account instance from a wallet

Parameters

account (siliqua.wallet.accounts.Account) – Account to remove

Raises

  • TypeError – If account is not a valid Account

  • KeyError – If account is not in the wallet

Returns

True

remove_encryption()

Remove all encryption from the wallet. Essentially an alias for Wallet.change_passphrase(None, False, False)

remove_from_address_book(account_id)

Remove an account ID from the address book

Parameters

account_id (str) – Account ID

Raises

  • nanolib.InvalidAccount – If the account ID is invalid

  • KeyError – If the account ID is not in the address book

remove_secret_encryption()

Remove encryption from all secrets in the wallet

remove_transaction(transaction)

Remove a transaction from the wallet

Parameters

transaction (siliqua.wallet.wallet.Transaction) – Transaction to remove

Raises

  • TypeError – If the parameter isn’t a Transaction

  • KeyError – If the transactoin doesn’t exist

remove_wallet_encryption()

Remove encryption from the wallet

save(path)

Save wallet to the given path. The wallet will be saved with a temporary name, and that file is renamed to (potentially) replace the existing file.

Parameters

path (str) – Path to the wallet file

secret_key
property secrets_unlocked

Return True if secrets are readable on this wallet

send(source, destination, amount, txid=None, description=None)

Send NANO from a source account to a destination account

Parameters

  • source (str) – Source account ID

  • destination (str) – Destination account ID

  • amount (int) – Amount in raw

  • txid (str) – Optional transaction ID. If the same transaction ID already exists in the wallet, the operation will fail.

  • description (str) – Optional description for the block

Returns

Created block

Return type

siliqua.wallet.accounts.Block

set_accounts(accounts)
set_address_book(address_book)
set_encryption(encryption)
set_properties(properties)
set_secret_encryption(secret_key)

Encrypt the secret values in the wallet

Parameters

secret_key (str) – Secret key for encryption

set_transactions(transactions)
set_wallet_encryption(wallet_key)

Encrypt the wallet with the given key

sign_blocks()

Sign all blocks that haven’t been signed yet.

Returns

List of newly signed blocks

transaction_map
property transactions
unlock(passphrase)

Unlock the wallet and allow access to secret properties until the wallet is locked again with lock()

update_broadcast_blocks(blocks)

Update blocks that have been broadcast

Parameters

blocks – List of confirmed blocks

update_pocketable_blocks(blocks)

Create new receive blocks from a list of pocketable blocks.

Parameters

blocks – List of siliqua.wallet.accounts.LinkBlock instances

Returns

List of received blocks, excluding those belonging to watching-only accounts

Return type

List[siliqua.wallet.accounts.LinkBlock]

update_processed_blocks(block_results)

Process received block results. This may involve adding new blocks into accounts’ blockchains or removing rejected non-confirmed blocks.

Parameters

block_results – List of siliqua.network.BlockSyncResult instances

update_solved_blocks(work_units)

Update solved blocks by adding work from received work units

Parameters

work_units (list) – List of siliqua.work.WorkUnit instances

wallet_key

Module contents