TransactionBalancing

cometa.transaction_builder.balancing.transaction_balancing.balance_transaction(unbalanced_tx, protocol_params, change_address, available_utxo, coin_selector, foreign_signature_count=0, reference_inputs=None, pre_selected_utxo=None, input_to_redeemer_map=None, available_collateral_utxo=None, collateral_change_address=None, evaluator=None)[source]

Balance a Cardano transaction by adding necessary inputs and calculating change.

This function balances an unbalanced transaction by: - Adding additional inputs if the transaction does not meet the required balance. - Computing the cost of script execution. - Calculating the change output to ensure the transaction has the correct total. - Adding collateral inputs if the transaction includes scripts.

Parameters:

  • unbalanced_tx (Transaction) – The transaction that needs balancing. Modified in-place.

  • protocol_params (ProtocolParameters) – Protocol parameters for fee calculation and balancing.

  • change_address (Address) – The address where any remaining balance (change) will be sent.

  • available_utxo (Union['UtxoList', List['Utxo']]) – Available UTXOs to select from if additional inputs are needed.

  • coin_selector (CoinSelector) – The coin selector used for choosing appropriate UTXOs.

  • foreign_signature_count (int) – Number of expected extra signatures not in the transaction.

  • reference_inputs (Optional[Union['UtxoList', List['Utxo']]]) – Resolved reference inputs already included in the transaction.

  • pre_selected_utxo (Optional[Union['UtxoList', List['Utxo']]]) – UTXOs that must be included in the transaction inputs.

  • input_to_redeemer_map (Optional['InputToRedeemerMap']) – Map of inputs to redeemers for proper index updates.

  • available_collateral_utxo (Optional[Union['UtxoList', List['Utxo']]]) – Available UTXOs for collateral if tx has scripts.

  • collateral_change_address (Optional['Address']) – Address for collateral change if applicable.

  • evaluator (Optional['TxEvaluator']) – Transaction evaluator for determining script execution costs.

Raises:

CardanoError – If balancing fails.

Return type:

None

Example

>>> from cometa.transaction_builder.balancing import balance_transaction
>>> from cometa.transaction_builder.coin_selection import LargeFirstCoinSelector
>>>
>>> selector = LargeFirstCoinSelector.new()
>>> balance_transaction(
...     unbalanced_tx=tx,
...     protocol_params=params,
...     change_address=my_address,
...     available_utxo=my_utxos,
...     coin_selector=selector,
... )
>>> # tx is now balanced