Random Improve Coin Selector¶

cardano_error_t cardano_random_improve_coin_selector_new(cardano_coin_selector_t **coin_selector)¶

Creates a new Round-Robin Random-Improve coin selector.

This selector is a port of the multi-asset coin selection algorithm used by cardano-wallet (Round-Robin Random-Improve, a generalization of CIP-2 Random-Improve). It works in two phases:

1. Selection: one sub-selector per required asset (plus one for ada, which runs last) is processed in round-robin order. On each turn a sub-selector picks a single UTXO at random, preferring UTXOs that contain only its asset, then UTXOs that pair its asset with one other, then any UTXO containing the asset. While a sub-selector’s minimum is not yet covered, any selection is accepted; once covered, additional selections are accepted only while they move the selected quantity closer to twice the minimum. This headroom is what allows change outputs to resemble the user’s payments.

2. Change generation: one change output is created per user-specified output (see the outputs_to_cover parameter of cardano_coin_selector_select). The excess of each user-specified asset is partitioned across the change outputs in proportion to the user’s output quantities; assets that were selected incidentally are distributed in a way that preserves the granularity of the selected inputs. Every change output is min-ADA compliant; if the selected ada is insufficient to build the change outputs, additional ada-only UTXOs are selected at random until change can be constructed.

Compared to largest-first selection, this algorithm keeps the wallet’s UTXO distribution healthy over time (improving transaction parallelism and privacy) at the cost of potentially selecting more inputs.

Usage Example:

cardano_coin_selector_t* coin_selector = NULL;
cardano_error_t result = cardano_random_improve_coin_selector_new(&coin_selector);

if (result == CARDANO_SUCCESS)
{
  cardano_tx_builder_set_coin_selector(tx_builder, coin_selector);
}

cardano_coin_selector_unref(&coin_selector);

Note

The selector is seeded from a cryptographically secure entropy source. Use cardano_random_improve_coin_selector_new_with_seed for deterministic behavior.

Parameters:¶

cardano_coin_selector_t **coin_selector¶

[out] A pointer to store the address of the newly created coin selector object.

Returns:¶

A cardano_error_t indicating success or failure of the operation.

cardano_error_t cardano_random_improve_coin_selector_new_with_seed(uint64_t seed, cardano_coin_selector_t **coin_selector)¶

Creates a new Round-Robin Random-Improve coin selector with a deterministic seed.

Behaves exactly like cardano_random_improve_coin_selector_new, but the internal random number generator is seeded with the given value, making the selection fully deterministic and reproducible. This is primarily useful for testing.

Usage Example:

cardano_coin_selector_t* coin_selector = NULL;
cardano_error_t result = cardano_random_improve_coin_selector_new_with_seed(42, &coin_selector);

// ... use the selector; selections are reproducible for the same seed and inputs ...

cardano_coin_selector_unref(&coin_selector);

Parameters:¶

uint64_t seed¶

[in] The seed for the internal random number generator.

cardano_coin_selector_t **coin_selector¶

[out] A pointer to store the address of the newly created coin selector object.

Returns:¶

A cardano_error_t indicating success or failure of the operation.

cardano_error_t cardano_random_improve_coin_selector_new_with_options(uint64_t seed, cardano_selection_strategy_t strategy, cardano_coin_selector_t **coin_selector)¶

Creates a new Round-Robin Random-Improve coin selector with a deterministic seed and an explicit selection strategy.

Behaves like cardano_random_improve_coin_selector_new_with_seed, but additionally allows the selection strategy to be chosen. See cardano_selection_strategy_t.

Usage Example:

cardano_coin_selector_t* coin_selector = NULL;
cardano_error_t result = cardano_random_improve_coin_selector_new_with_options(
  42, CARDANO_SELECTION_STRATEGY_MINIMAL, &coin_selector);

// ... the selector now selects just enough of each asset to cover the target ...

cardano_coin_selector_unref(&coin_selector);

Parameters:¶

uint64_t seed¶

[in] The seed for the internal random number generator.

cardano_selection_strategy_t strategy¶

[in] The selection strategy to use.

cardano_coin_selector_t **coin_selector¶

[out] A pointer to store the address of the newly created coin selector object.

Returns:¶

A cardano_error_t indicating success or failure of the operation.