@btc-stamps/tx-builder/dist/selectors/index.d.ts

Transaction builder for Bitcoin Stamps and SRC-20 tokens with advanced UTXO selection

import { B as BaseSelector } from '../selector-factory-DfDGDWiU.js';
export { A as AccumulativeSelector, b as BlackjackSelector, a as BranchAndBoundSelector, K as KnapsackSelector, P as ProtectionAwareSelector, S as SelectorFactory, T as TaxOptimizedSelector, W as WasteOptimizedSelector } from '../selector-factory-DfDGDWiU.js';
import { U as UTXO } from '../provider.interface-53Rg30ZJ.js';
import { S as SelectionOptions, E as EnhancedSelectionResult } from '../selector.interface-vD2d-t2t.js';
export { I as IUTXOSelector, a as SelectionResult, b as SelectorAlgorithm } from '../selector.interface-vD2d-t2t.js';
import '../protection.interface-DWbXoL2W.js';
import 'bitcoinjs-lib';
import 'node:buffer';

/**
 * Output Group UTXO Selection Algorithm
 *
 * Privacy-focused selection algorithm that groups UTXOs by common characteristics
 * to prevent address clustering attacks and maintain transaction graph privacy.
 *
 * This is the modern approach used by Bitcoin Core since 2018.
 *
 * Groups UTXOs by:
 * - Address/Script type (P2PKH, P2WPKH, P2SH, P2WSH, P2TR)
 * - Transaction origin (same transaction)
 * - Value ranges (dust, small, medium, large)
 *
 * Selection strategies by privacy level:
 * - High: Only use complete groups (highest privacy)
 * - Medium: Prefer complete groups, mix if necessary
 * - Low: Optimize for fees while respecting grouping
 */
declare class OutputGroupSelector extends BaseSelector {
    private privacyLevel;
    private fallbackSelector?;
    constructor(privacyLevel?: 'high' | 'medium' | 'low', fallbackSelector?: BaseSelector);
    getName(): string;
    select(utxos: UTXO[], options: SelectionOptions): EnhancedSelectionResult;
    /**
     * Create output groups from UTXOs
     */
    private createOutputGroups;
    /**
     * Generate group key for UTXO classification
     */
    private getGroupKey;
    /**
     * Determine script type from UTXO
     */
    private getScriptType;
    /**
     * Categorize UTXO value for grouping
     */
    private getValueCategory;
    /**
     * Estimate cost to spend an input
     */
    private estimateInputCost;
    /**
     * Select complete groups only (highest privacy)
     */
    private selectCompleteGroups;
    /**
     * Select mixed groups (medium privacy)
     */
    private selectMixedGroups;
    /**
     * Select optimal groups (low privacy, optimized for fees)
     */
    private selectOptimalGroups;
    /**
     * Create a structured failure result
     */
    private createFailureResult;
    /**
     * Calculate waste metric
     */
    private computeWasteMetric;
    /**
     * Estimate transaction virtual size
     */
    private estimateVSize;
}

/**
 * Single Random Draw (SRD) UTXO Selection Algorithm
 *
 * Privacy-enhancing selection algorithm that randomly picks UTXOs
 * until the target amount is met. This avoids deterministic patterns
 * that could be used to fingerprint wallets or link transactions.
 *
 * Algorithm:
 * 1. Randomly shuffle all available UTXOs
 * 2. Accumulate UTXOs until target is met
 * 3. Always create change output for privacy
 *
 * Benefits:
 * - Enhanced privacy through randomization
 * - Breaks deterministic selection patterns
 * - Prevents wallet fingerprinting
 * - Simple and fast implementation
 *
 * Trade-offs:
 * - Not optimized for fees
 * - May select more UTXOs than necessary
 * - Can create unnecessary change outputs
 */
declare class SingleRandomDrawSelector extends BaseSelector {
    protected randomSeed?: number;
    protected changeThreshold: number;
    constructor(options?: {
        randomSeed?: number;
        changeThreshold?: number;
    });
    select(utxos: UTXO[], options: SelectionOptions): EnhancedSelectionResult;
    /**
     * Fisher-Yates shuffle algorithm for randomizing array
     */
    protected shuffleArray<T extends UTXO>(array: T[]): T[];
    /**
     * Create random number generator
     * Uses seed for testing, Math.random for production
     */
    protected createRandom(): () => number;
    getName(): string;
}

/**
 * Consolidation-Optimized UTXO Selection Algorithm
 *
 * Optimizes for reducing UTXO set size during low-fee periods by
 * preferring to spend multiple small inputs together. Uses Murch's
 * waste metric to determine when consolidation is economically beneficial.
 *
 * Algorithm:
 * 1. Calculate waste metric for current vs future fee rates
 * 2. Identify consolidation opportunities
 * 3. Prefer spending multiple small UTXOs when fees are low
 * 4. Avoid consolidation when fees are high
 *
 * Benefits:
 * - Reduces wallet UTXO fragmentation
 * - Optimizes future transaction costs
 * - Maintains healthy UTXO pool
 * - Saves fees in the long term
 *
 * Based on research by Mark "Murch" Erhardt
 */
declare class ConsolidationSelector extends BaseSelector {
    private consolidationThreshold;
    private minConsolidationCount;
    private targetUTXOCount;
    private longTermFeeRate;
    constructor(options?: {
        consolidationThreshold?: number;
        minConsolidationCount?: number;
        targetUTXOCount?: number;
        longTermFeeRate?: number;
    });
    select(utxos: UTXO[], options: SelectionOptions): EnhancedSelectionResult;
    /**
     * Determine if consolidation is beneficial using waste metric
     */
    private shouldConsolidate;
    /**
     * Select UTXOs optimized for consolidation or minimal usage based on fee conditions
     */
    private selectForConsolidation;
    /**
     * Select minimal inputs when fees are high - prioritize efficiency over consolidation
     */
    private selectMinimalInputs;
    /**
     * Add additional UTXOs for consolidation if beneficial
     */
    private addConsolidationUTXOs;
    /**
     * Optimize consolidation by finding best set to consolidate
     */
    private optimizeConsolidation;
    /**
     * Standard selection when not consolidating
     */
    private selectOptimal;
    /**
     * Calculate Murch's waste metric for a UTXO
     *
     * Waste = Cost to spend now - Cost to spend in future
     * Negative waste means it's beneficial to spend now
     */
    private calculateUtxoWaste;
    /**
     * Calculate consolidation metrics
     */
    private getConsolidationMetrics;
    /**
     * Calculate fee for selection
     */
    private calculateFee;
    /**
     * Estimate transaction size
     */
    estimateTransactionSize(inputs: number, outputs: number): number;
    getName(): string;
}

export { BaseSelector, ConsolidationSelector, OutputGroupSelector, SelectionOptions, SingleRandomDrawSelector, UTXO };