cashscript_py.transaction_builder module

TransactionBuilder for constructing, signing, serializing, and broadcasting BCH transactions.

class TransactionBuilder(provider: NetworkProvider, *, maximum_fee_satoshis: int | None = None, maximum_fee_sats_per_byte: float | None = None, allow_implicit_fungible_token_burn: bool = False)

Bases: object

Build, sign, and send BCH transactions via unlockers.

Supports multiple inputs/outputs, OP_RETURN, fee caps, and token burn checks.

add_input(utxo: Utxo, unlocker: Unlocker, sequence: int | None = None) → TransactionBuilder

Add a single input.

Parameters:

• utxo – UTXO to spend.

• unlocker – Unlocker capable of generating scripts/signatures.

• sequence – Optional sequence number for this input.

Returns:

This builder (for chaining).

add_inputs(utxos: list[Utxo] | list[UnlockableUtxo], unlocker: Unlocker | None = None, sequence: int | None = None) → TransactionBuilder

Add multiple inputs either with a shared unlocker or individually attached unlockers.

Parameters:

• utxos – List of UTXOs (or UnlockableUtxo instances).

• unlocker – Shared unlocker if utxos are plain UTXOs.

• sequence – Optional sequence number for all added inputs (when using a shared unlocker).

Returns:

This builder (for chaining).

Raises:

ValueError – If both or neither forms of unlockers are provided.

add_op_return_output(chunks: list[str]) → TransactionBuilder

Add an OP_RETURN output.

Parameters:

chunks – List of strings (UTF-8 or hex with 0x prefix) to push.

add_output(output: Output) → TransactionBuilder

Add a single output.

Parameters:

output – Recipient and amount, optionally with token details.

Returns:

This builder (for chaining).

add_outputs(outputs: list[Output]) → TransactionBuilder

Add multiple outputs (validated for dust, tokens, etc.).

Parameters:

outputs – Outputs to append.

Returns:

This builder (for chaining).

Raises:

• OutputAddressInvalid – If a provided address cannot be parsed.

• OutputSatoshisNonPositiveError – If amount <= 0.

• OutputSatoshisTooSmallError – If amount is below dust minimum.

• TokensToNonTokenAddressError – If sending tokens to a non-token address.

• OutputTokenAmountTooSmallError – If token amount is negative.

build() → str

Build the transaction, generate unlocking scripts, and return serialized hex.

Returns:

Hex-encoded transaction.

Raises:

ValueError – If fee caps are exceeded or implicit token burns are disallowed.

async get_tx_details(txid: str, raw: bool = False) → dict[str, str]

Poll for transaction details until available or timeout.

Parameters:

• txid – Transaction ID to fetch.

• raw – If True, return only hex (no decoded details).

Returns:

…} when raw=True or {‘txid’: …, ‘hex’: …}.

Return type:

A dict containing either {‘hex’

Raises:

Exception – If details cannot be retrieved in time.

async send(raw: bool = False) → dict[str, str]

Build and broadcast the transaction, retrying for details.

Parameters:

raw – If True, return only the raw hex when details are fetched.

Returns:

…} when raw=True or {‘txid’: …, ‘hex’: …}.

Return type:

A dict containing either {‘hex’

Raises:

Exception – If broadcasting fails.

set_locktime(locktime: int) → TransactionBuilder

Set the transaction locktime.

Parameters:

locktime – Block height or timestamp (per network rules).

Returns:

This builder (for chaining).