UtxoSelector

UTXO coin selection algorithm.

Strategy: Smallest-First (Privacy Optimization)

Source: Based on midnight-wallet coin selection File: midnight-wallet/packages/capabilities/src/balancer/Balancer.ts:143

Why Smallest-First (Not Largest-First)? Privacy optimization - Using smallest coins first:

• Reduces UTXO fragmentation over time

• Makes transaction amounts less predictable

• Better long-term privacy vs largest-first

Algorithm:

1. Sort available UTXOs by value (ascending - smallest first)

2. Accumulate UTXOs until sum >= required amount

3. Return selected UTXOs

Multi-Token Support: Selection is performed per token type (each token selected independently).

Usage in Transaction Building:

val selector = UtxoSelector()

// Select UTXOs for 100 NIGHT
val result = selector.selectUtxos(
    availableUtxos = availableNightUtxos,
    requiredAmount = BigInteger("100000000")  // 100.0 NIGHT
)

when (result) {
    is SelectionResult.Success -> {
        // Use result.selectedUtxos for transaction inputs
        // Use result.totalSelected - requiredAmount for change output
    }
    is SelectionResult.InsufficientFunds -> {
        // Show error: "Need ${result.required} but only have ${result.available}"
    }
}

Important:

• UTXOs must be AVAILABLE (not PENDING or SPENT)

• UTXOs must be sorted by value before passing to selectUtxos()

• Selected UTXOs must be marked PENDING immediately after selection