Coin Selector Implementation

typedef struct cardano_coin_selector_impl_t cardano_coin_selector_impl_t

Opaque structure representing the coin selection implementation.

The cardano_coin_selector_impl_t is an opaque structure that implements coin selection logic. It abstracts away the internal details of coin selection.

typedef cardano_error_t (*cardano_coin_select_func_t)(cardano_coin_selector_impl_t *coin_selector, const cardano_coin_selection_request_t *request, cardano_utxo_list_t **selection, cardano_utxo_list_t **remaining_utxo, cardano_transaction_output_list_t **change_outputs)

Callback function type for performing coin selection.

The cardano_coin_select_func_t typedef defines the signature for a callback function responsible for selecting a set of UTXOs (Unspent Transaction Outputs) from an available list to meet a specific target value, and for producing the change outputs that return any excess value to the change address.

This function is expected to:

  • Use the request’s available_utxo list and optionally its pre_selected_utxo list to select UTXOs that meet the required target value.

  • Store the selected UTXOs in the selection list, ensuring the selection covers the target value.

  • Store any remaining UTXOs that were not selected in the remaining_utxo list.

  • Produce one or more change outputs in the change_outputs list such that the selection is locally balanced: sum(selection) = target + sum(change_outputs).

  • Ensure every change output is min-ADA compliant as per the protocol parameters (selecting additional UTXOs from the available pool if necessary to top up the change).

The selector must not attempt fee calculation or global transaction balancing; those remain the responsibility of the balancer.

Note

The caller is responsible for managing the memory of the selection, remaining_utxo and change_outputs lists, ensuring they are properly freed when no longer needed.

Param coin_selector:

[in] A pointer to the cardano_coin_selector_impl_t object implementing the coin selection strategy.

Param request:

[in] The selection request. See cardano_coin_selection_request_t. The wrapper guarantees that the request pointer and its required fields are not NULL.

Param selection:

[out] A pointer to the list of UTXOs that were selected to meet the target value.

Param remaining_utxo:

[out] A pointer to the list of UTXOs that were not selected and remain available for future transactions.

Param change_outputs:

[out] A pointer to the list of change outputs produced by the selection. The list may be empty if the selection matches the target exactly.

Return:

CARDANO_SUCCESS if the coin selection was successful and UTXOs were selected to meet the target, or an appropriate error code indicating failure.