nectar.transactionbuilder module

class nectar.transactionbuilder.TransactionBuilder(tx=None, blockchain_instance=None, **kwargs)

Bases: dict

This class simplifies the creation of transactions by adding operations and signers. To build your own transactions and sign them

Parameters:

tx (dict) – transaction (Optional). If not set, the new transaction is created.
expiration (int) – Delay in seconds until transactions are supposed to expire (optional) (default is 300)
blockchain_instance (Hive) – If not set, shared_blockchain_instance() is used

from nectar.transactionbuilder import TransactionBuilder
from nectarbase.operations import Transfer
from nectar import Hive
wif = "5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3"
hive = Hive(nobroadcast=True, keys={'active': wif})
tx = TransactionBuilder(blockchain_instance=hive)
transfer = {"from": "test", "to": "test1", "amount": "1 HIVE", "memo": ""}
tx.appendOps(Transfer(transfer))
tx.appendSigner("test", "active") # or tx.appendWif(wif)
signed_tx = tx.sign()
broadcast_tx = tx.broadcast()

addSigningInformation(account, permission, reconstruct_tx=False)

This is a private method that adds side information to a unsigned/partial transaction in order to simplify later signing (e.g. for multisig or coldstorage)

Not needed when “appendWif” was already or is going to be used

FIXME: Does not work with owner keys!

Parameters:: reconstruct_tx (bool) – when set to False and tx is already contructed, it will not reconstructed and already added signatures remain

appendMissingSignatures()

Store which accounts/keys are supposed to sign the transaction

This method is used for an offline-signer!

appendOps(ops, append_to=None)

Append op(s) to the transaction builder

Parameters:: ops (list) – One or a list of operations

appendSigner(account, permission)

Register an account as a signer for this transaction by locating or assigning the needed signing keys.

Attempts to resolve signing credentials for account at the requested permission and attaches them to the builder state. Behavior varies by signing mode: - Ledger mode: verifies that the ledger-derived public key for the currently selected path is authorized for the account/permission (raises AssertionError if not). - Wallet mode: fetches private keys from the local wallet and stores corresponding WIFs; if the account argument is a PublicKey, the matching WIF is retrieved and added.

Parameters:: account (str | Account | PublicKey): account name, Account instance, or public key identifying the signer. permission (str): permission level to use (“active”, “owner”, or “posting”).
Raises:: WalletLocked: if the local wallet is locked when wallet keys are required. AssertionError: for invalid permission values, if the requested permission cannot be accessed, or if a ledger public key is not found in the account authorities.

appendWif(wif)

Add a wif that should be used for signing of the transaction.

Parameters:: wif (string) – One wif key to use for signing a transaction.

broadcast(max_block_age=-1, trx_id=True)

Broadcast the built transaction to the Hive network and clear the builder state.

If the transaction is not yet signed this method will attempt to sign it first. If no operations are present the call returns None. When broadcasting is disabled (nobroadcast) the constructed transaction dict is returned and the builder is cleared.

Parameters:

max_block_age (int): Passed to appbase/network_broadcast calls to constrain: acceptable block age; ignored for condenser API paths. Default -1.
trx_id (bool): If True and a signing step produced a transaction id, attach: it to the returned result when the RPC response lacks a trx_id. Default True.

Returns:

dict or whatever the underlying broadcast method returns, or None if there are no operations to broadcast.

Side effects:

Clears internal transaction state on successful broadcast or on errors.
May raise exceptions from the signing or RPC broadcast calls.

clear(): Clear the transaction builder and start from scratch

clearWifs(): Clear all stored wifs

constructTx(ref_block_num=None, ref_block_prefix=None): Construct the actual transaction and store it in the class’s dict store

get_block_params(use_head_block=False): Auxiliary method to obtain ref_block_num and ref_block_prefix. Requires a connection to a node!

get_parent(): TransactionBuilders don’t have parents, they are their own parent

get_potential_signatures(): Returns public key from signature

get_required_signatures(available_keys=[])

Return the subset of public keys required to sign this transaction from a set of available keys.

This method requires an active RPC connection and delegates to the node’s get_required_signatures API to determine which of the provided available_keys are necessary to satisfy the transaction’s authority requirements.

Parameters:

available_keys (list): Iterable of public key strings to consider when: determining required signers.

Returns:

list: Public key strings that the node reports are required to sign the transaction.

Raises:

OfflineHasNoRPCException: If called while offline (no RPC available).

get_transaction_hex(): Returns a hex value of the transaction

is_empty(): Check if ops is empty

json(with_prefix=False): Show the transaction as plain json

list_operations(): List all ops

searchPath(account, perm)

setPath(path)

set_expiration(p): Set expiration date

sign(reconstruct_tx=True)

Sign the built transaction using a Ledger device or local WIFs and attach signatures to the builder.

If the transaction is not constructed (or if reconstruct_tx is True) the transaction will be reconstructed before signing. The method attempts signing in this order: 1. Ledger (if ledger mode is active) — signs with the Ledger device and appends signatures. 2. Local WIFs from the builder — uses stored WIFs to sign the transaction and appends signatures.

Parameters:

reconstruct_tx (bool): If False and the transaction is already constructed, existing signatures are preserved and the transaction will not be rebuilt before signing. Defaults to True.

Returns:

The object returned by the signing step:

Ledger_Transaction when signed via Ledger,
Signed_Transaction when signed locally with WIFs.

Returns None if there are no operations to sign.

Raises:

MissingKeyError: If local signing is attempted but no WIFs are available.

verify_authority(): Verify the authority of the signed transaction