@btc-stamps/tx-builder - v0.1.7
    Preparing search index...

    Class WasteOptimizedSelector

    Waste-Optimized UTXO Selection Algorithm - Multi-algorithm optimization with waste scoring

    The Waste-Optimized selector is a meta-algorithm that runs multiple UTXO selection algorithms in parallel and chooses the result with the lowest "waste" score. This approach combines the strengths of different algorithms to find the most efficient UTXO selection for any given scenario.

    The algorithm works by executing multiple selection strategies simultaneously:

    1. Branch-and-Bound: Optimal for small UTXO sets, finds mathematically best solutions
    2. Accumulative: Fast greedy approach, good for consolidation and large transactions
    3. Blackjack: Excels at finding exact matches and minimizing change outputs

    Each result is scored using a comprehensive waste metric that considers:

    • Change Cost: Fee cost of creating change outputs (34 * feeRate per output)
    • Excess Cost: Penalty for selecting more value than needed (encourages precision)
    • Input Cost: Fee overhead from using multiple inputs (68 * feeRate per input * 0.1)

    The selector uses configurable weighting factors to balance these costs based on use case. Advanced features include timeout protection, detailed error categorization, and comprehensive performance tracking.

    Key features:

    • Parallel execution of multiple algorithms with timeout protection (default 5s)
    • Sophisticated waste scoring with configurable weighting factors
    • Detailed UTXO filtering with categorization (dust, low confirmations, protected)
    • Adaptive algorithm selection based on UTXO set characteristics
    • Performance benchmarking and algorithm usage statistics
    • Graceful fallback handling when algorithms fail
    • Rich error reporting with failure reason categorization

    Performance characteristics:

    • Slower than individual algorithms due to parallel execution overhead
    • Provides best overall results across diverse scenarios
    • Excellent for production systems where optimal selection is critical
    • Configurable execution time limits prevent hanging on large UTXO sets
    const selector = new WasteOptimizedSelector({
      algorithms: ['branch-and-bound', 'blackjack', 'accumulative'],
      maxExecutionTime: 3000, // 3 second timeout
      wasteWeighting: {
        changeCost: 1.0,   // Full penalty for change outputs
        excessCost: 0.5,   // Moderate penalty for excess value
        inputCost: 0.1     // Light penalty for multiple inputs
      }
    });

    const result = selector.select(utxos, {
      targetValue: 500000,
      feeRate: 15,
      maxInputs: 10,
      dustThreshold: 546
    });

    if (result.success) {
      console.log(`Best algorithm: ${result.metadata.selectedAlgorithm}`);
      console.log(`Waste score: ${result.wasteMetric}`);
      console.log(`Execution time: ${result.metadata.executionTime}ms`);
    }

    Hierarchy

    • BaseSelector
      • WasteOptimizedSelector
    Index

    Constructors

    constructor

    Properties

    DUST_THRESHOLD INPUT_SIZE OUTPUT_SIZE TRANSACTION_OVERHEAD

    Methods

    addAlgorithm benchmark calculateChange calculateWaste checkOptionsValidity configure createResult estimateFee estimateTransactionSize filterEligibleUTXOs filterUTXOs getConfiguration getName getOptimalAlgorithm getPerformanceStats isDust removeAlgorithm select selectAdaptive sortByConfirmations sortByValue sumUTXOs validateOptions

    Constructors

    Properties

    DUST_THRESHOLD: 546
    INPUT_SIZE: 148
    OUTPUT_SIZE: 34
    TRANSACTION_OVERHEAD: 10

    Methods

    • Add a custom algorithm

      Parameters

      • name: string
      • algorithm: BaseSelector

      Returns void

    • Benchmark algorithms against test data

      Parameters

      Returns {
          algorithm: string;
          avgExecutionTime: number;
          avgWaste: number;
          results: { executionTime: number; success: boolean; wasteScore: number }[];
          successRate: number;
      }[]

    • Calculate change amount

      Parameters

      • inputValue: number
      • targetValue: number
      • fee: number

      Returns number

    • Calculate waste metric for coin selection Lower waste is better

      Parameters

      • inputs: UTXO[]
      • targetValue: number
      • feeRate: number
      • longTermFeeRate: number = 10

      Returns number

    • Configure the waste optimized selector

      Parameters

      • newConfig: Partial<WasteOptimizationConfig>

      Returns void

    • Create selection result

      Parameters

      • inputs: UTXO[]
      • targetValue: number
      • feeRate: number
      • hasChange: boolean

      Returns SelectionSuccess

    • Estimate transaction fee

      Parameters

      • numInputs: number
      • numOutputs: number
      • feeRate: number

      Returns number

    • Estimate transaction size in vBytes

      Parameters

      • numInputs: number
      • numOutputs: number

      Returns number

    • Filter UTXOs based on confirmation requirements

      Parameters

      • utxos: UTXO[]
      • minConfirmations: number = 0

      Returns UTXO[]

    • Get performance statistics

      Returns {
          algorithmsCount: number;
          averageExecutionTime: number;
          maxExecutionTime: number;
          parallelExecution: boolean;
          successRate: number;
          totalExecutions: number;
      }

    • Check if amount is dust

      Parameters

      • amount: number
      • OptionaldustThreshold: number

      Returns boolean

    • Sort UTXOs by value (ascending)

      Parameters

      • utxos: UTXO[]
      • descending: boolean = false

      Returns UTXO[]

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods