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, cardano_utxo_list_t *pre_selected_utxo, cardano_utxo_list_t *available_utxo, cardano_value_t *target, cardano_utxo_list_t **selection, cardano_utxo_list_t **remaining_utxo)¶

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.

This function is expected to:

Use the provided available_utxo list and optionally a 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.

Usage Example:

cardano_utxo_list_t* pre_selected_utxo = ...;  // Optional pre-selected UTXOs
cardano_utxo_list_t* available_utxo = ...;     // Available UTXOs for selection
cardano_value_t* target_value = ...;           // The target value to cover
cardano_utxo_list_t* selected_utxo = NULL;
cardano_utxo_list_t* remaining_utxo = NULL;

cardano_error_t result = coin_select_function(coin_selector, pre_selected_utxo, available_utxo, target_value, &selected_utxo, &remaining_utxo);

if (result == CARDANO_SUCCESS)
{
  // UTXOs were successfully selected
}

// Free the selected and remaining UTXO lists when done
cardano_utxo_list_unref(&selected_utxo);
cardano_utxo_list_unref(&remaining_utxo);

Note

The caller is responsible for managing the memory of both the selection and remaining_utxo 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 pre_selected_utxo:¶: [in] A list of UTXOs that have already been pre-selected (optional). These UTXOs must be included in the final selection.
Param available_utxo:¶: [in] A list of available UTXOs to select from.
Param target:¶: [in] A pointer to a cardano_value_t object that defines the target amount of ADA and/or other tokens to be covered by the selected UTXOs.
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.
Return:¶: CARDANO_SUCCESS if the coin selection was successful and UTXOs were selected to meet the target, or an appropriate error code indicating failure.