Class BlackjackSelector

Blackjack UTXO Selection Algorithm - Exact value matching optimization

The Blackjack algorithm is inspired by the card game where the goal is to get as close to a target value as possible without going over. This selector prioritizes finding UTXO combinations that exactly match the target amount plus fees, minimizing change outputs and transaction waste.

Remarks

The algorithm works in two phases:

Exact Match Phase: Systematically searches for combinations that create changeless transactions (total input = target + fee exactly)
Closest Match Phase: If no exact match exists, finds the combination closest to the target while still covering the required amount

Key features:

Prioritizes changeless transactions to minimize fees and UTXO set bloat
Uses combinatorial search with configurable limits (MAX_COMBINATIONS = 10,000)
Supports both single-output (no change) and dual-output (with change) transactions
Implements "exactness" scoring to measure how close combinations are to the target
Falls back to subset sum dynamic programming for optimization
Handles dust threshold validation to prevent unspendable outputs

Performance characteristics:

Excellent for small to medium UTXO sets (< 20 UTXOs)
May be slower for large UTXO sets due to combinatorial complexity
Optimal when exact matches are likely (e.g., consolidation scenarios)

Example

const selector = new BlackjackSelector();
const result = selector.select(utxos, {
  targetValue: 100000, // 100,000 satoshis
  feeRate: 10,        // 10 sat/vB
  maxInputs: 5,       // Limit search space
  dustThreshold: 546  // Bitcoin dust threshold
});

if (result.success) {
  console.log(`Selected ${result.inputCount} UTXOs`);
  console.log(`Change: ${result.change} satoshis`);
  console.log(`Fee: ${result.fee} satoshis`);
}

Hierarchy

BaseSelector
- BlackjackSelector

Constructors

constructor

new BlackjackSelector(): BlackjackSelector
Returns BlackjackSelector
Inherited from BaseSelector.constructor

Properties

`Protected` `Readonly`DUST_THRESHOLD

DUST_THRESHOLD: 546

`Protected` `Readonly`INPUT_SIZE

INPUT_SIZE: 148

`Protected` `Readonly`OUTPUT_SIZE

OUTPUT_SIZE: 34

`Protected` `Readonly`TRANSACTION_OVERHEAD

TRANSACTION_OVERHEAD: 10

Methods

`Protected`calculateChange

calculateChange(inputValue: number, targetValue: number, fee: number): number
Calculate change amount
Parameters
- inputValue: number
- targetValue: number
- fee: number
Returns number
Inherited from BaseSelector.calculateChange
- Defined in selectors/base-selector.ts:111

`Protected`calculateWaste

calculateWaste(
    inputs: UTXO[],
    targetValue: number,
    feeRate: number,
    longTermFeeRate?: number,
): number
Calculate waste metric for coin selection Lower waste is better
Parameters
- inputs: UTXO[]
- targetValue: number
- feeRate: number
- longTermFeeRate: number = 10
Returns number
Inherited from BaseSelector.calculateWaste
- Defined in selectors/base-selector.ts:202

`Protected`checkOptionsValidity

checkOptionsValidity(options: SelectionOptions): null | EnhancedSelectionResult
Check if options are valid and return failure result if not
Parameters
- options: SelectionOptions
Returns null | EnhancedSelectionResult
Inherited from BaseSelector.checkOptionsValidity
- Defined in selectors/base-selector.ts:167

`Protected`createResult

createResult(
    inputs: UTXO[],
    targetValue: number,
    feeRate: number,
    hasChange: boolean,
): SelectionSuccess
Create selection result
Parameters
- inputs: UTXO[]
- targetValue: number
- feeRate: number
- hasChange: boolean
Returns SelectionSuccess
Inherited from BaseSelector.createResult
- Defined in selectors/base-selector.ts:122

estimateFee

estimateFee(numInputs: number, numOutputs: number, feeRate: number): number
Estimate transaction fee
Parameters
- numInputs: number
- numOutputs: number
- feeRate: number
Returns number
Inherited from BaseSelector.estimateFee
- Defined in selectors/base-selector.ts:85

`Protected`estimateTransactionSize

estimateTransactionSize(numInputs: number, numOutputs: number): number
Estimate transaction size in vBytes
Parameters
- numInputs: number
- numOutputs: number
Returns number
Inherited from BaseSelector.estimateTransactionSize
- Defined in selectors/base-selector.ts:93

`Protected`filterEligibleUTXOs

filterEligibleUTXOs(utxos: UTXO[], options: SelectionOptions): UTXO[]
Filter UTXOs with protection and confirmation checks
Parameters
- utxos: UTXO[]
- options: SelectionOptions
Returns UTXO[]
Inherited from BaseSelector.filterEligibleUTXOs
- Defined in selectors/base-selector.ts:36

`Protected`filterUTXOs

filterUTXOs(utxos: UTXO[], minConfirmations?: number): UTXO[]
Filter UTXOs based on confirmation requirements
Parameters
- utxos: UTXO[]
- minConfirmations: number = 0
Returns UTXO[]
Inherited from BaseSelector.filterUTXOs
- Defined in selectors/base-selector.ts:29

getName

getName(): string
Returns string
Overrides BaseSelector.getName
- Defined in selectors/blackjack.ts:69

getStats

getStats(): { exactMatchTolerance: number; maxCombinations: number }
Get algorithm statistics

Returns { exactMatchTolerance: number; maxCombinations: number }
- Defined in selectors/blackjack.ts:655

`Protected`isDust

isDust(amount: number, dustThreshold?: number): boolean
Check if amount is dust
Parameters
- amount: number
- OptionaldustThreshold: number
Returns boolean
Inherited from BaseSelector.isDust
- Defined in selectors/base-selector.ts:104

select

select(utxos: UTXO[], options: SelectionOptions): EnhancedSelectionResult
Parameters
- utxos: UTXO[]
- options: SelectionOptions
Returns EnhancedSelectionResult
Overrides BaseSelector.select
- Defined in selectors/blackjack.ts:73

selectOptimized

selectOptimized(
utxos: UTXO[],
options: SelectionOptions,
): EnhancedSelectionResult
Optimized selection for specific target amounts Uses dynamic programming approach for better performance
Parameters
- utxos: UTXO[]
- options: SelectionOptions
Returns EnhancedSelectionResult
- Defined in selectors/blackjack.ts:554

`Protected`sortByConfirmations

sortByConfirmations(utxos: UTXO[]): UTXO[]
Sort UTXOs by confirmations (most confirmed first)
Parameters
- utxos: UTXO[]
Returns UTXO[]
Inherited from BaseSelector.sortByConfirmations
- Defined in selectors/base-selector.ts:71

`Protected`sortByValue

sortByValue(utxos: UTXO[], descending?: boolean): UTXO[]
Sort UTXOs by value (ascending)
Parameters
- utxos: UTXO[]
- descending: boolean = false
Returns UTXO[]
Inherited from BaseSelector.sortByValue
- Defined in selectors/base-selector.ts:61

`Protected`sumUTXOs

sumUTXOs(utxos: UTXO[]): number
Calculate total value of UTXOs
Parameters
- utxos: UTXO[]
Returns number
Inherited from BaseSelector.sumUTXOs
- Defined in selectors/base-selector.ts:78

`Protected`validateOptions

validateOptions(options: SelectionOptions): void
Validate selection options
Parameters
- options: SelectionOptions
Returns void
Inherited from BaseSelector.validateOptions
- Defined in selectors/base-selector.ts:150

Class BlackjackSelector

Remarks

Example

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Returns BlackjackSelector

Properties

Protected ReadonlyDUST_THRESHOLD

Protected ReadonlyINPUT_SIZE

Protected ReadonlyOUTPUT_SIZE

Protected ReadonlyTRANSACTION_OVERHEAD

Methods

ProtectedcalculateChange

Parameters

Returns number

ProtectedcalculateWaste

Parameters

Returns number

ProtectedcheckOptionsValidity

Parameters

Returns null | EnhancedSelectionResult

ProtectedcreateResult

Parameters

Returns SelectionSuccess

estimateFee

Parameters

Returns number

ProtectedestimateTransactionSize

Parameters

Returns number

ProtectedfilterEligibleUTXOs

Parameters

Returns UTXO[]

ProtectedfilterUTXOs

Parameters

Returns UTXO[]

getName

Returns string

getStats

Returns { exactMatchTolerance: number; maxCombinations: number }

ProtectedisDust

Parameters

Returns boolean

select

Parameters

Returns EnhancedSelectionResult

selectOptimized

Parameters

Returns EnhancedSelectionResult

ProtectedsortByConfirmations

Parameters

Returns UTXO[]

ProtectedsortByValue

Parameters

Returns UTXO[]

ProtectedsumUTXOs

Parameters

Returns number

ProtectedvalidateOptions

Parameters

Returns void

Settings

On This Page

`Protected` `Readonly`DUST_THRESHOLD

`Protected` `Readonly`INPUT_SIZE

`Protected` `Readonly`OUTPUT_SIZE

`Protected` `Readonly`TRANSACTION_OVERHEAD

`Protected`calculateChange

`Protected`calculateWaste

`Protected`checkOptionsValidity

`Protected`createResult

`Protected`estimateTransactionSize

`Protected`filterEligibleUTXOs

`Protected`filterUTXOs

`Protected`isDust

`Protected`sortByConfirmations

`Protected`sortByValue

`Protected`sumUTXOs

`Protected`validateOptions