@xchainjs/xchain-utxo 2.0.10 → 2.2.0

package/lib/strategies/accumulative.d.ts

@@ -0,0 +1,17 @@
+import { UTXO } from '../types';
+import { UtxoSelectionStrategy, UtxoSelectionResult } from './types';
+/**
+ * Accumulative strategy - simple and reliable fallback
+ */
+export declare class AccumulativeStrategy implements UtxoSelectionStrategy {
+    name: string;
+    private static readonly DUST_THRESHOLD;
+    private static readonly BYTES_PER_INPUT;
+    private static readonly BYTES_PER_OUTPUT;
+    private static readonly BASE_TX_SIZE;
+    select(utxos: UTXO[], targetValue: number, feeRate: number, extraOutputs?: number): UtxoSelectionResult | null;
+    /**
+     * Calculate estimated transaction fee
+     */
+    private calculateFee;
+}

package/lib/strategies/branch-and-bound.d.ts

@@ -0,0 +1,21 @@
+import { UTXO } from '../types';
+import { UtxoSelectionStrategy, UtxoSelectionResult } from './types';
+/**
+ * Branch and Bound strategy - optimal for minimizing fees and change
+ */
+export declare class BranchAndBoundStrategy implements UtxoSelectionStrategy {
+    name: string;
+    private static readonly MAX_TRIES;
+    private static readonly DUST_THRESHOLD;
+    private static readonly BYTES_PER_INPUT;
+    private static readonly BYTES_PER_OUTPUT;
+    private static readonly BASE_TX_SIZE;
+    select(utxos: UTXO[], targetValue: number, feeRate: number, extraOutputs?: number): UtxoSelectionResult | null;
+    private findExactMatch;
+    private branchAndBound;
+    private calculateEfficiency;
+    /**
+     * Calculate estimated transaction fee
+     */
+    private calculateFee;
+}

package/lib/strategies/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './branch-and-bound';
+export * from './single-random-draw';
+export * from './accumulative';
+export * from './largest-first';
+export * from './small-first';

package/lib/strategies/largest-first.d.ts

@@ -0,0 +1,9 @@
+import { UTXO } from '../types';
+import { UtxoSelectionStrategy, UtxoSelectionResult } from './types';
+/**
+ * Largest First strategy - good for consolidation
+ */
+export declare class LargestFirstStrategy implements UtxoSelectionStrategy {
+    name: string;
+    select(utxos: UTXO[], targetValue: number, feeRate: number, extraOutputs?: number): UtxoSelectionResult | null;
+}

package/lib/strategies/single-random-draw.d.ts

@@ -0,0 +1,17 @@
+import { UTXO } from '../types';
+import { UtxoSelectionStrategy, UtxoSelectionResult } from './types';
+/**
+ * Single Random Draw strategy - good for privacy
+ */
+export declare class SingleRandomDrawStrategy implements UtxoSelectionStrategy {
+    name: string;
+    private static readonly DUST_THRESHOLD;
+    private static readonly BYTES_PER_INPUT;
+    private static readonly BYTES_PER_OUTPUT;
+    private static readonly BASE_TX_SIZE;
+    select(utxos: UTXO[], targetValue: number, feeRate: number, extraOutputs?: number): UtxoSelectionResult | null;
+    /**
+     * Calculate estimated transaction fee
+     */
+    private calculateFee;
+}

package/lib/strategies/small-first.d.ts

@@ -0,0 +1,17 @@
+import { UTXO } from '../types';
+import { UtxoSelectionStrategy, UtxoSelectionResult } from './types';
+/**
+ * Small First strategy - good for consolidating many small UTXOs
+ */
+export declare class SmallFirstStrategy implements UtxoSelectionStrategy {
+    name: string;
+    private static readonly DUST_THRESHOLD;
+    private static readonly BYTES_PER_INPUT;
+    private static readonly BYTES_PER_OUTPUT;
+    private static readonly BASE_TX_SIZE;
+    select(utxos: UTXO[], targetValue: number, feeRate: number, extraOutputs?: number): UtxoSelectionResult | null;
+    /**
+     * Calculate estimated transaction fee
+     */
+    private calculateFee;
+}

package/lib/strategies/types.d.ts

@@ -0,0 +1,28 @@
+import { UTXO } from '../types';
+/**
+ * Interface for UTXO selection strategies
+ */
+export interface UtxoSelectionStrategy {
+    name: string;
+    select(utxos: UTXO[], targetValue: number, feeRate: number, extraOutputs?: number): UtxoSelectionResult | null;
+}
+/**
+ * Result of UTXO selection
+ */
+export interface UtxoSelectionResult {
+    inputs: UTXO[];
+    changeAmount: number;
+    fee: number;
+    efficiency: number;
+    strategy: string;
+}
+/**
+ * UTXO selection preferences
+ */
+export interface UtxoSelectionPreferences {
+    minimizeFee?: boolean;
+    minimizeInputs?: boolean;
+    minimizeChange?: boolean;
+    avoidDust?: boolean;
+    consolidateSmallUtxos?: boolean;
+}

package/lib/utxo-selector.d.ts

@@ -0,0 +1,37 @@
+import { UTXO } from './types';
+import { UtxoSelectionResult, UtxoSelectionPreferences } from './strategies';
+/**
+ * Enhanced UTXO selector with multiple strategies
+ */
+export declare class UtxoSelector {
+    private strategies;
+    constructor();
+    static readonly DUST_THRESHOLD = 546;
+    static readonly BYTES_PER_INPUT: 68;
+    static readonly BYTES_PER_OUTPUT: 31;
+    static readonly BASE_TX_SIZE: 10;
+    /**
+     * Select optimal UTXOs for a transaction
+     */
+    selectOptimal(utxos: UTXO[], targetValue: number, feeRate: number, preferences?: UtxoSelectionPreferences, extraOutputs?: number): UtxoSelectionResult;
+    /**
+     * Select the best result based on preferences
+     */
+    private selectBestResult;
+    /**
+     * Calculate a score for a result based on preferences
+     */
+    private calculateScore;
+    /**
+     * Validate inputs for UTXO selection
+     */
+    private validateInputs;
+    /**
+     * Validate that a result is correct
+     */
+    private isValidResult;
+    /**
+     * Calculate estimated transaction fee
+     */
+    static calculateFee(inputCount: number, outputCount: number, feeRate: number): number;
+}

package/lib/validators.d.ts

@@ -0,0 +1,38 @@
+import { Address } from '@xchainjs/xchain-util';
+import { FeeBounds } from '@xchainjs/xchain-client';
+import { TxParams, UTXO } from './types';
+/**
+ * Comprehensive input validation for UTXO transactions
+ */
+export declare class UtxoTransactionValidator {
+    /**
+     * Validate transaction parameters
+     */
+    static validateTransferParams(params: TxParams & {
+        sender?: Address;
+        feeRate?: number;
+    }, feeBounds?: FeeBounds): void;
+    /**
+     * Validate UTXO set for consistency and correctness
+     */
+    static validateUtxoSet(utxos: UTXO[]): void;
+    /**
+     * Basic address validation - checks for null/empty and basic format
+     * NOTE: Chain-specific validation should be done by the respective client packages
+     */
+    static validateAddressBasic(address: string): void;
+    /**
+     * Validate fee rate against network conditions
+     */
+    static validateFeeRate(feeRate: number, networkConditions?: {
+        minFeeRate?: number;
+        maxFeeRate?: number;
+        recommendedRange?: [number, number];
+    }): void;
+    /**
+     * Validate transaction size limits
+     */
+    static validateTransactionSize(estimatedSize: number, maxSize?: number): void;
+    private static containsControlCharacters;
+    private static sanitizeParamsForLogging;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xchainjs/xchain-utxo",
-  "version": "2.0.10",
+  "version": "2.2.0",
   "description": "Genereic UTXO client for XChainJS",
   "keywords": [
     "XChain",