TxBuilder

class cometa.transaction_builder.tx_builder.TxBuilder(protocol_params, slot_config)[source]

Bases: object

High-level transaction builder for the Cardano blockchain.

The TxBuilder provides a fluent, Pythonic interface for constructing Cardano transactions. It encapsulates the complexities of transaction assembly, balancing, fee calculation, and UTXO management.

Key Concepts:

UTXOs: Cardano uses an Unspent Transaction Output model. Each output from a previous transaction becomes an input for future transactions.
Coin Selection: The builder automatically selects UTXOs to cover the transaction’s outputs and fees using configurable strategies.
Balancing: The builder ensures inputs equal outputs + fees, sending any excess to the change address.
Plutus Scripts: Smart contracts that validate spending, minting, or staking operations. They require redeemers (arguments) and consume execution units (CPU/memory).

Basic Usage:

Example

>>> from cometa import TxBuilder, SlotConfig
>>>
>>> # Initialize with protocol parameters and slot configuration
>>> slot_config = SlotConfig.mainnet()
>>> builder = TxBuilder(protocol_params, slot_config)
>>>
>>> # Configure and build a simple transfer
>>> tx = builder \
...     .set_change_address(my_address) \
...     .set_utxos(my_utxos) \
...     .send_lovelace(recipient, 5_000_000) \
...     .expires_in(3600) \
...     .build()
>>>
>>> # Sign and submit
>>> signed_tx = wallet.sign_transaction(tx)
>>> tx_hash = provider.submit_transaction(signed_tx)

Note

All configuration and validation errors are deferred until build() is called. This allows for flexible, incremental transaction construction.

See also

Transaction: The resulting transaction object
ProtocolParameters: Required protocol configuration
SlotConfig: Network timing configuration
CoinSelector: Customizable UTXO selection strategies
TxEvaluator: Customizable Plutus script evaluation strategies

Parameters:

protocol_params (ProtocolParameters)
slot_config (SlotConfig)

__init__(protocol_params, slot_config)[source]

Create a new transaction builder. …

Parameters:

protocol_params (ProtocolParameters)
slot_config (SlotConfig)

Return type:

None

__enter__()[source]

Return type:: TxBuilder

__exit__(exc_type, exc_val, exc_tb)[source]

Return type:: None

__repr__()[source]

Return repr(self).

Return type:: str

set_coin_selector(coin_selector)[source]

Set the coin selection strategy for UTXO selection.

The coin selector determines how UTXOs are chosen to cover the transaction’s required value. Different strategies optimize for different goals:

Large First: Minimizes number of inputs by using largest UTXOs first
Random Improve: Balances between reducing fragmentation and privacy

If not set, defaults to the Large First strategy.

Parameters:: coin_selector (CoinSelectorProtocol) – The coin selection strategy to use.
Returns:: Self for method chaining.
Return type:: TxBuilder

Example

>>> class MySelector:
...     def get_name(self) -> str:
...         return "MySelector"
...     def select(self, pre_selected, available, target):
...         return selected, remaining
>>> builder.set_coin_selector(MySelector())

set_evaluator(evaluator)[source]

Set the transaction evaluator for Plutus script execution.

The evaluator computes execution units (CPU and memory) required for Plutus scripts. This is essential for accurate fee calculation when transactions contain smart contracts.

If not set, defaults to using the provider’s built-in evaluator.

Parameters:: evaluator (TxEvaluatorProtocol) – The transaction evaluator to use.`
Returns:: Self for method chaining.
Return type:: TxBuilder

Example

>>> class MyEvaluator:
...     def get_name(self) -> str:
...         return "MyEvaluator"
...     def evaluate(self, transaction, additional_utxos):
...         return redeemers
>>> builder.set_evaluator(MyEvaluator())

set_network_id(network_id)[source]

Set the target network for this transaction.

The network ID is included in the transaction body and ensures the transaction can only be submitted to the intended network.

Parameters:: network_id (NetworkId) – The network identifier.
Returns:: Self for method chaining.
Return type:: TxBuilder

Example

>>> builder.set_network_id(NetworkId.TESTNET)  # Testnet
>>> builder.set_network_id(NetworkId.MAINNET)  # Mainnet

set_change_address(address)[source]

Set the address for receiving change.

After covering outputs and fees, any remaining value from inputs is sent to this address. This is typically your own wallet address.

Parameters:: address (Union['Address', str]) – The change address. Can be an Address object or a bech32-encoded address string (e.g., “addr_test1…”).
Returns:: Self for method chaining.
Return type:: TxBuilder

Example

>>> builder.set_change_address("addr_test1qz2fxv2umyhttkxyxp8x0dlpdt3k...")
>>> # Or with Address object
>>> builder.set_change_address(my_address)

set_collateral_change_address(address)[source]

Set the address for receiving collateral change.

When a transaction includes Plutus scripts, collateral is required as a guarantee. If the collateral inputs exceed the required amount, the excess is sent to this address.

If not set, defaults to the regular change address.

Parameters:: address (Union['Address', str]) – The collateral change address. Can be an Address object or a bech32-encoded address string.
Returns:: Self for method chaining.
Return type:: TxBuilder

Example

>>> builder.set_collateral_change_address("addr_test1...")

set_minimum_fee(fee)[source]

Set a minimum fee for the transaction.

This overrides the calculated fee if it’s higher. Useful when you need to ensure a specific fee amount regardless of transaction size.

Parameters:: fee (int) – The minimum fee in lovelace (1 ADA = 1,000,000 lovelace).
Returns:: Self for method chaining.
Return type:: TxBuilder

Example

>>> builder.set_minimum_fee(200_000)  # At least 0.2 ADA

set_donation(amount)[source]

Set a treasury donation amount.

This Conway-era feature allows contributing ADA directly to the Cardano treasury as part of a transaction.

Parameters:: amount (int) – The donation amount in lovelace.
Returns:: Self for method chaining.
Return type:: TxBuilder

Example

>>> builder.set_donation(1_000_000)  # Donate 1 ADA to treasury

set_utxos(utxos)[source]

Set the available UTXOs for coin selection.

These UTXOs will be used by the coin selector to cover the transaction’s required inputs. Typically, these are all spendable UTXOs from your wallet.

Parameters:: utxos (Union['UtxoList', List['Utxo']]) – List of available UTXOs. Can be a UtxoList or a Python list of Utxo objects.
Returns:: Self for method chaining.
Return type:: TxBuilder

Example

>>> # Get UTXOs from provider
>>> my_utxos = provider.get_utxos_at_address(my_address)
>>> builder.set_utxos(my_utxos)

set_collateral_utxos(utxos)[source]

Set UTXOs to use for script collateral.

Collateral is required when a transaction includes Plutus scripts. It serves as a guarantee that gets forfeited if script validation fails.

Collateral UTXOs should: - Contain only ADA (no native tokens) - Be from a key-based address (not a script address) - Have sufficient value to cover the collateral requirement

If not set, the builder will try to use UTXOs from set_utxos().

Parameters:: utxos (Union['UtxoList', List['Utxo']]) – List of UTXOs designated for collateral.
Returns:: Self for method chaining.
Return type:: TxBuilder

Example

>>> # Use specific UTXOs for collateral
>>> builder.set_collateral_utxos(ada_only_utxos)

set_valid_until(*, slot=None, unix_time=None)[source]

Set when the transaction expires (invalid_hereafter).

The transaction will be rejected if not included in a block before this point. You must specify either slot or unix_time, not both.

Parameters:

slot (int | None) – The slot number after which the transaction becomes invalid.
unix_time (int | None) – Unix timestamp (seconds since epoch) after which the transaction becomes invalid.

Returns:

Self for method chaining.

Raises:

ValueError – If neither or both parameters are provided.

Return type:

TxBuilder

Example

>>> # Expire after specific slot
>>> builder.set_valid_until(slot=12345678)
>>>
>>> # Expire 2 hours from now
>>> import time
>>> builder.set_valid_until(unix_time=int(time.time()) + 7200)

set_valid_from(*, slot=None, unix_time=None)[source]

Set when the transaction becomes valid (invalid_before).

The transaction will be rejected if included in a block before this point. Useful for time-locked contracts.

You must specify either slot or unix_time, not both.

Parameters:

slot (int | None) – The slot number before which the transaction is invalid.
unix_time (int | None) – Unix timestamp (seconds since epoch) before which the transaction is invalid.

Returns:

Self for method chaining.

Raises:

ValueError – If neither or both parameters are provided.

Return type:

TxBuilder

Example

>>> # Valid starting from specific slot
>>> builder.set_valid_from(slot=12345000)
>>>
>>> # Valid starting 1 hour from now
>>> import time
>>> builder.set_valid_from(unix_time=int(time.time()) + 3600)

expires_in(seconds)[source]

Sets the transaction to be valid for a specific duration from now.

This is a convenience method that calculates a future expiration date and sets it. The transaction will be marked as invalid if it is not included in a block within the specified duration.

Parameters:: seconds (int) – The number of seconds from now that the transaction should remain valid.
Returns:: Self for method chaining.
Return type:: TxBuilder

Example

>>> # Set the transaction to expire in 3 minutes (180 seconds) from now.
>>> builder.expires_in(180)

expires_after(date)[source]

Sets the transaction’s expiration to a specific, absolute date and time.

This function marks the transaction as invalid if it is not included in a block before the specified date.

Parameters:: date (datetime) – The absolute date and time after which the transaction will be invalid.
Returns:: Self for method chaining.
Return type:: TxBuilder

Example

>>> # Set the transaction to expire on New Year's Day, 2026.
>>> from datetime import datetime, timezone
>>> expiry_date = datetime(2026, 1, 1, tzinfo=timezone.utc)
>>> builder.expires_after(expiry_date)

set_invalid_before(slot)[source]

Sets the transaction’s validity start time using an absolute slot number.

This function marks the transaction as invalid if it is included in a block created before the specified slot.

Parameters:: slot (int) – The absolute slot number before which this transaction is invalid.
Returns:: Self for method chaining.
Return type:: TxBuilder

valid_from_date(date)[source]

Sets the transaction’s validity start time to a specific, absolute date and time. The transaction will be invalid if processed before this date.

Parameters:: date (datetime) – The absolute date and time from which the transaction will be valid.
Returns:: Self for method chaining.
Return type:: TxBuilder

Example

>>> # Make the transaction valid starting on New Year's Day, 2026.
>>> from datetime import datetime, timezone
>>> start_date = datetime(2026, 1, 1, tzinfo=timezone.utc)
>>> builder.valid_from_date(start_date)

valid_after(seconds)[source]

Sets the transaction to become valid only after a specified duration from now. This is a convenience method that calculates a future start date.

Parameters:: seconds (int) – The number of seconds from now to wait before the transaction becomes valid.
Returns:: Self for method chaining.
Return type:: TxBuilder

Example

>>> # Make the transaction valid only after 1 hour (3600 seconds) has passed.
>>> builder.valid_after(3600)

send_lovelace(address, amount)[source]

Send ADA to an address.

Creates an output that sends the specified amount of lovelace to the given address. This is the simplest way to transfer ADA.

Parameters:

address (Union['Address', str]) – The recipient address. Can be an Address object or a bech32-encoded address string.
amount (int) – The amount to send in lovelace (1 ADA = 1,000,000 lovelace).

Returns:

Self for method chaining.

Return type: