Skip to content

Class BSV::Wallet::CoinSelector

Inherits: Object

Selects UTXOs from an available pool to fund a transaction.

Given a target amount and a fee model, the selector chooses the minimum set of UTXOs needed to cover target + fee. It supports two strategies:

  • :standard — tries an exact match, then smallest-sufficient, then falls back to largest-first accumulation.
  • :largest_first — skips exact/smallest checks and goes straight to largest-first accumulation.

Fee estimation uses {BSV::Wallet::FeeEstimator} with P2PKH size constants. During accumulation a potential change output is included in the fee estimate, so the caller can always produce change if needed.

@example 

estimator = BSV::Wallet::FeeEstimator.new(sats_per_kb: 1)
selector  = BSV::Wallet::CoinSelector.new(fee_estimator: estimator)
result    = selector.select(available: utxos, target_satoshis: 1000, num_outputs: 1)
# => { inputs: [...], fee: 1, total_satoshis: 1001, excess: 0 }

Constants

VALID_STRATEGIES

Not documented.

Public Instance Methods

initialize(fee_estimator: = nil, fee_model: = nil, strategy: = :standard)

  • @param fee_estimator [BSV::Wallet::FeeEstimator] fee estimation model (also accepted as +fee_model:+ for backwards compatibility)
  • @param strategy [Symbol] selection strategy — :standard or :largest_first
  • @raise [ArgumentError] if strategy is not recognised
  • @return [CoinSelector] a new instance of CoinSelector

select(available:, target_satoshis:, num_outputs:)

Selects UTXOs to cover target_satoshis plus estimated fees. - @param available [Array] pool of UTXOs; each hash must have a +:satoshis+ key - @param target_satoshis [Integer] amount to fund (excluding fee) - @param num_outputs [Integer] number of recipient outputs in the transaction - @raise [BSV::Wallet::InsufficientFundsError] when the pool cannot cover target + fees - @return [Hash] with keys +:inputs+, +:fee+, +:total_satoshis+, +:excess+