nimiqclient.nimiq_client.NimiqClient

class nimiqclient.nimiq_client.NimiqClient(scheme='http', user='', password='', host='127.0.0.1', port=8648, url_suffix='')

Bases: object

Methods

accounts	Returns a list of addresses owned by client.
batch_number	Returns the batch number.
block_number	Returns the height of most( recent block.)['data']
consensus	Returns information on the current consensus state.
create_account	Creates a new account and stores its private key in the client store.
create_remove_stake_transaction	Creates (but do not send) a remove stake transaction
create_retire_stake_transaction	Creates (but do not send) a retire stake transaction
create_update_staker_transaction	Creates (but do not send) an update staker transaction
epoch_number	Returns the epoch number.
get_account_by_address	Returns details for the account of given address.
get_accounts	Returns details for all of the the accounts in the accounts tree.
get_active_validators	Returns a dictionary with the set of the current active validators.
get_block_by_hash	Returns information about a block by hash.
get_block_by_number	Returns information about a block by block number.
get_block_transaction_count_by_hash	Returns the number of transactions in a block from a block matching the given block hash.
get_block_transaction_count_by_number	Returns the number of transactions in a block matching the given block number.
get_callbacks	Returns a dictionary containing all callbacks that the client can call when an RPC request is received.
get_current_slashed_slots	Returns the current slashed slots.
get_inherents_by_batch_number	Returns information about inherents by batch number.
get_inherents_by_block_number	Returns information about inherents by block number.
get_latest_block	Returns information the latest block.
get_parked_validators	Returns the set of current parked validators.
get_previous_slashed_slots	Returns the previous slashed slots.
get_raw_transaction_info	Deserializes hex-encoded transaction and returns a transaction object.
get_slot_at	Returns the slot at a specific block number
get_staker_by_address	Gets a staker using its address
get_stakers_by_validator_address	Gets the stakers for a validator given its address
get_subscriptions	Returns a dictionary containing all RPC subscription IDs the client has subscribed to.
get_transaction_by_hash	Returns the information about a transaction requested by transaction hash.
get_transaction_hashes_by_address	Returns the hashes of the latest transactions successfully performed by or for an address.
get_transactions_by_address	Returns the latest transactions successfully performed by or for an address.
get_transactions_by_batch_number	Returns information about transactions by batch number.
get_transactions_by_block_number	Returns information about transactions by block number.
get_validator_address	Returns the address of the current validator.
get_validator_by_address	Returns a validator given its address
get_validator_signing_key	Returns the signing key of the current validator.
get_validator_voting_key	Returns the voting key of the current validator.
get_validators	Returns a all validators in the staking contract
importRawKey	Imports a raw key into the wallet.
is_account_imported	Returns wether an account has been imported into the wallet.
is_account_unlocked	Returns wether an account has been unlocked in the wallet.
lock_account	Locks an account in the wallet
mempool	Returns information on the current mempool situation.
mempool_content	Returns transactions that are currently in the mempool.
min_fee_per_byte	Returns the minimum fee per byte.
peer_count	Returns number of peers currently connected to the client.
peer_id	Returns the peer ID of the running client.
peer_list	Returns list of peers known to the client.
peer_state	Returns the state of the peer.
send_basic_transaction	Creates and send a new basic transaction
send_raw_transaction	Sends a signed message call transaction or a contract creation, if the data field contains code.
send_set_active_stake_transaction	Creates and sends a set active stake transaction to set a new value for the active stake
send_stake_transaction	Creates and sends a stake transaction to add stake to an existing staker
set_peer_state	Returns the state of the peer.
subscribe_for_head_block	Subscribes to blocks produced by the server and calls a callback on each of the block.
subscribe_for_head_block_hash	Subscribes to blocks produced by the server and calls a callback on each of the hash of the block.
subscribe_for_logs_by_addresses_and_types	Subscribes to block logs by type and addresses produced by the server and calls a callback on each each of the logs.
subscribe_for_validator_election_by_address	Subscribes to validator election events and calls a callback on each each of the validators received.
unlock_account	Unlocks a wallet account

Attributes

WS_RESPONSE_TIMEOUT

API client for the Nimiq JSON RPC server.

WS_RESPONSE_TIMEOUT = 5

API client for the Nimiq JSON RPC server.

Parameters:

• scheme (str, optional) – Protocol scheme, “http” or “https” or “ws”.

• user (str, optional) – Authorized user.

• password (str, optional) – Password for the authorized user.

• host (str, optional) – Host IP address.

• port (int, optional) – Host port.

async accounts()

Returns a list of addresses owned by client.

Returns:

List of Accounts owned by the client.

Return type:

list of (str)

async batch_number()

Returns the batch number.

Returns:

The current batch number the client is on.

Return type:

int

async block_number()

Returns the height of most( recent block.)[‘data’]

Returns:

The current block height the client is on.

Return type:

int

async consensus()

Returns information on the current consensus state.

Returns:

Consensus state. “established” is the value for a good state, other values indicate bad.

Return type:

bool

async create_account(passphrase=None)

Creates a new account and stores its private key in the client store.

Parameters:

passphrase (str) – Private Key passphrase to add to the account.

Returns:

Information on the wallet that was created using the command.

Return type:

WalletAccount

async create_remove_stake_transaction(address, recipient, value, fee, validityStartHeight)

Creates (but do not send) a remove stake transaction

Parameters:

• address (str) – The sender address.

• recipient (str) – The recipient of the funds.

• value (int) – The value.

• fee (int) – The fee of the transaction.

• validityStartHeight (str) – The validity start height for the transaction. Could be a string containing a block number (e.g.”1000”) or an offset (e.g. “+10”).

Returns:

The Hex-encoded transaction hash.

Return type:

str

async create_retire_stake_transaction(address, staker, retire_stake, fee, validityStartHeight)

Creates (but do not send) a retire stake transaction

Parameters:

• address (str) – The sender address.

• staker (str) – The staker address.

• retire_stake (int) – The stake to be retired

• fee (int) – The fee of the transaction.

• validityStartHeight (str) – The validity start height for the transaction. Could be a string containing a block number (e.g.”1000”) or an offset (e.g. “+10”).

Returns:

The Hex-encoded transaction hash.

Return type:

str

async create_update_staker_transaction(address, staker, new_delegation, reactivate_all_stake, fee, validityStartHeight)

Creates (but do not send) an update staker transaction

Parameters:

• address (str) – The sender address.

• staker (str) – The staker address.

• new_delegation (str) – The new delegation address

• reactivate_all_stake (bool) – Indicates if the stake is reactivated

• fee (int) – The fee of the transaction.

• validityStartHeight (str) – The validity start height for the transaction. Could be a string containing a block number (e.g.”1000”) or an offset (e.g. “+10”).

Returns:

The Hex-encoded transaction hash.

Return type:

str

async epoch_number()

Returns the epoch number.

Returns:

The current epoch number the client is on.

Return type:

int

async get_account_by_address(address)

Returns details for the account of given address.

Parameters:

address (str) – Address to get account details.

Returns:

Details about the account. Returns the default empty basic account for non-existing accounts.

Return type:

StateData[Account or VestingContract or HTLC]

async get_accounts()

Returns details for all of the the accounts in the accounts tree.

Returns:

Details for all of the the accounts in the accounts tree.

Return type:

StateData[list of (Account or VestingContract or HTLC)]

async get_active_validators()

Returns a dictionary with the set of the current active validators.

Returns:

The current set of active validators using a dictionary with the validator address as key (str) and the balance as value (int).

Return type:

StateData[List of (Validator)]

async get_block_by_hash(hash, include_transactions=None)

Returns information about a block by hash.

Parameters:

• hash (str) – Hash of the block to gather information on.

• include_transactions (bool, optional) – If True it returns the full transaction objects, if False only the hashes of the transactions.

Returns:

A block object or None when no block was found.

Return type:

Block or None

async get_block_by_number(height, include_transactions=None)

Returns information about a block by block number.

Parameters:

• height (int) – The height of the block to gather information on.

• include_transactions (bool, optional) – If True it returns the full transaction objects, if False only the hashes of the transactions.

Returns:

A block object or None when no block was found.

Return type:

Block or None

async get_block_transaction_count_by_hash(hash)

Returns the number of transactions in a block from a block matching the given block hash.

Parameters:

hash (str) – Hash of the block.

Returns:

Number of transactions in the block found, or None, when no block was found.

Return type:

int or None

async get_block_transaction_count_by_number(height)

Returns the number of transactions in a block matching the given block number.

Parameters:

height (int) – Height of the block.

Returns:

Number of transactions in the block found, or None, when no block was found.

Return type:

int or None

get_callbacks()

Returns a dictionary containing all callbacks that the client can call when an RPC request is received.

Returns:

Dictionary containing all RPC subscription IDs.

Return type:

dict

async get_current_slashed_slots()

Returns the current slashed slots.

Returns:

Current slashed slots.

Return type:

StateData[SlashedSlots]

async get_inherents_by_batch_number(batch_number)

Returns information about inherents by batch number.

Parameters:

batch_number (int) – Batch number for which the inherents are going to be gathered.

Returns:

A list of inherent objects.

Return type:

List of (Inherent)

async get_inherents_by_block_number(height)

Returns information about inherents by block number.

Parameters:

height (int) – Height of the block containing the inherents.

Returns:

A list of inherent objects.

Return type:

List of (Inherent)

async get_latest_block(include_body=None)

Returns information the latest block.

Returns:

The latest block in the chain.

Return type:

Block

async get_parked_validators()

Returns the set of current parked validators.

Returns:

Set of current parked validators.

Return type:

ParkedValidators

async get_previous_slashed_slots()

Returns the previous slashed slots.

Returns:

Previous slashed slots.

Return type:

StateData[SlashedSlots]

async get_raw_transaction_info(transaction)

Deserializes hex-encoded transaction and returns a transaction object.

Parameters:

transaction (str) – The hex encoded signed transaction.

Returns:

The transaction object.

Return type:

Transaction

async get_slot_at(block_number, offset=None)

Returns the slot at a specific block number

Parameters:

• block_number (int) – Block number for which the slot is queried.

• offset – Optional block number offset.

:type int, optional :return: The slot at the specified block number. :rtype: StateData[Slot]

async get_staker_by_address(address)

Gets a staker using its address

Parameters:

address (str) – Address of the staker.

Returns:

The staker object.

Return type:

StateData[Staker]

async get_stakers_by_validator_address(address)

Gets the stakers for a validator given its address

Parameters:

address (str) – Address of the validator.

Returns:

The staker object.

Return type:

StateData[list of (Staker)]

get_subscriptions()

Returns a dictionary containing all RPC subscription IDs the client has subscribed to.

Returns:

Dictionary containing all RPC subscription IDs.

Return type:

dict

async get_transaction_by_hash(hash)

Returns the information about a transaction requested by transaction hash.

Parameters:

hash (str) – Hash of a transaction.

Returns:

A transaction object or None when no transaction was found.

Return type:

Transaction or None

async get_transaction_hashes_by_address(address, number_of_transactions=None)

Returns the hashes of the latest transactions successfully performed by or for an address. Note that this information might change when blocks are reverted on the local state due to forks.

Parameters:

• address (str) – Address of which transactions should be gathered.

• number_of_transactions (int, optional) – Maximum number of transactions that shall be returned.

Returns:

List of hashes of transactions linked to the requested address.

Return type:

list of (str)

async get_transactions_by_address(address, number_of_transactions=None)

Returns the latest transactions successfully performed by or for an address. Note that this information might change when blocks are reverted on the local state due to forks.

Parameters:

• address (str) – Address of which transactions should be gathered.

• number_of_transactions (int, optional) – Maximum number of transactions that shall be returned.

Returns:

List of transactions linked to the requested address.

Return type:

list of (Transaction)

async get_transactions_by_batch_number(batch_number)

Returns information about transactions by batch number.

Parameters:

batch_number (int) – Batch number for which the transactions are going to be gathered.

Returns:

A list of transaction objects.

Return type:

List of (Transaction)

async get_transactions_by_block_number(height)

Returns information about transactions by block number.

Parameters:

height (int) – Height of the block containing the transactions.

Returns:

A list of transaction objects.

Return type:

List of (Transaction)

async get_validator_address()

Returns the address of the current validator.

Returns:

Address of the current validator.

Return type:

str or None

async get_validator_by_address(address)

Returns a validator given its address

Parameters:

• address (str) – Address for which a validator should be gathered.

• include_stakers – Set to true to include stakers in the Validator object to be returned.

Returns:

Validator for the corresponding address

Return type:

StateData[Validator]

async get_validator_signing_key()

Returns the signing key of the current validator.

Returns:

Signing key of the current validator.

Return type:

str or None

async get_validator_voting_key()

Returns the voting key of the current validator.

Returns:

Voting key of the current validator.

Return type:

str or None

async get_validators()

Returns a all validators in the staking contract

Returns:

Validator for the corresponding address

Return type:

StateData[List of (Validator)]

async importRawKey(private_key, passphrase=None)

Imports a raw key into the wallet.

Parameters:

• private_key (str) – Private key to be imported.

• passphrase (str) – Optional passphrase to add to the private key.

Returns:

Address of the imported raw key.

Return type:

str

async is_account_imported(address)

Returns wether an account has been imported into the wallet.

Parameters:

address (str) – Address of the account that is going to be checked.

Returns:

Bool indicating wether the account has been imported.

Return type:

bool

async is_account_unlocked(address)

Returns wether an account has been unlocked in the wallet.

Parameters:

address (str) – Address of the account that is going to be checked.

Returns:

Bool indicating wether the account has been unlocked.

Return type:

bool

async lock_account(address)

Locks an account in the wallet

Parameters:

address (sre) – Address of the account to be locked.

async mempool()

Returns information on the current mempool situation. This will provide an overview of the number of transactions sorted into buckets based on their fee per byte (in smallest unit).

Returns:

Mempool information.

Return type:

MempoolInfo

async mempool_content(include_transactions=None)

Returns transactions that are currently in the mempool.

Parameters:

include_transactions (bool, optional) – If True includes full transactions, if False includes only transaction hashes.

Returns:

List of transactions(either represented by the transaction hash or a transaction object).

Return type:

list of(Transaction or str)

async min_fee_per_byte()

Returns the minimum fee per byte.

Returns:

The new minimum fee per byte.

Return type:

int

async peer_count()

Returns number of peers currently connected to the client.

Returns:

Number of connected peers.

Return type:

int

async peer_id()

Returns the peer ID of the running client.

Returns:

Peer ID of the running client.

Return type:

string

async peer_list()

Returns list of peers known to the client.

Returns:

The list of peers.

Return type:

list of(Peer)

async peer_state(address)

Returns the state of the peer.

Parameters:

address (str) – The address of the peer.

Returns:

The current state of the peer.

Return type:

Peer

async send_basic_transaction(address, recipient, value, fee, validityStartHeight)

Creates and send a new basic transaction

Parameters:

• address (str) – The sender address.

• recipient (str) – The recipient address.

• value (int) – The value of the transaction.

• fee (int) – The fee of the transaction.

• validityStartHeight (str) – The validity start height for the transaction. Could be a string containing a block number (e.g.”1000”) or an offset (e.g. “+10”).

Returns:

The Hex-encoded transaction hash.

Return type:

str

async send_raw_transaction(transaction)

Sends a signed message call transaction or a contract creation, if the data field contains code.

Parameters:

transaction (str) – The hex encoded signed transaction

Returns:

The Hex-encoded transaction hash.

Return type:

str

async send_set_active_stake_transaction(address, staker, new_active_balance, fee, validityStartHeight)

Creates and sends a set active stake transaction to set a new value for the active stake

Parameters:

• address (str) – The sender address.

• staker (str) – The staker address.

• new_active_balance (int) – The new value for the active stake

• fee (int) – The fee of the transaction.

• validityStartHeight (str) – The validity start height for the transaction. Could be a string containing a block number (e.g.”1000”) or an offset (e.g. “+10”).

Returns:

The Hex-encoded transaction hash.

Return type:

str

async send_stake_transaction(address, staker, value, fee, validityStartHeight)

Creates and sends a stake transaction to add stake to an existing staker

Parameters:

• address (str) – The sender address.

• staker (str) – The staker address.

• value (int) – The value of the transaction.

• fee (int) – The fee of the transaction.

• validityStartHeight (str) – The validity start height for the transaction. Could be a string containing a block number (e.g.”1000”) or an offset (e.g. “+10”).

Returns:

The Hex-encoded transaction hash.

Return type:

str

async set_peer_state(address, command=None)

Returns the state of the peer.

Parameters:

• address (str) – The address of the peer.

• command (PeerStateCommand) – The command to send.

Returns:

The new state of the peer.

Return type:

Peer

async subscribe_for_head_block(callback, include_transactions=None, **kwargs)

Subscribes to blocks produced by the server and calls a callback on each of the block.

Parameters:

• callback (Callable[[NimiqClient, Block, Dict], Awaitable[None]]) – Callback to be called on each block.

• kwargs (dict) – Callback extra arguments that will be passed when the callback is called

async subscribe_for_head_block_hash(callback, **kwargs)

Subscribes to blocks produced by the server and calls a callback on each of the hash of the block.

Parameters:

• callback (Callable[[NimiqClient, str, Dict], Awaitable[None]]) – Callback to be called on each block.

• kwargs (dict) – Callback extra arguments that will be passed when the callback is called

async subscribe_for_logs_by_addresses_and_types(addresses, log_types, callback, **kwargs)

Subscribes to block logs by type and addresses produced by the server and calls a callback on each each of the logs.

Parameters:

• addresses (List of (str)) – List of addresses to subscribe to.

• log_types (List of (str)) – List of log types to subscribe to.

• callback (Callable[[NimiqClient, BlockLog, Dict], Awaitable[None]]) – Callback to be called on each block log.

• kwargs (dict) – Callback extra arguments that will be passed when the callback is called

async subscribe_for_validator_election_by_address(address, callback, **kwargs)

Subscribes to validator election events and calls a callback on each each of the validators received.

Parameters:

• address (str) – Validator address to subscribe for.

• callback (Callable[[Any, Validator, Dict], Awaitable[None]]) – Callback to be called on each validator.

• kwargs (dict) – Callback extra arguments that will be passed when the callback is called

async unlock_account(address, passphrase=None, duration=None)

Unlocks a wallet account

Parameters:

• address (str) – The account address.

• passphrase (str) – Optional passphrase if the accounts requires it.

• duration (int) – Optional duration in which the account is unlocked.