@xchainjs/xchain-utxo 2.0.10 → 2.1.0

package/lib/client.d.ts

@@ -1,7 +1,8 @@
 import { BaseXChainClient, ExplorerProviders, FeeEstimateOptions, FeeRate, FeeRates, Fees, FeesWithRates, Protocol, TxHash, TxHistoryParams } from '@xchainjs/xchain-client';
 import { Address, Asset, Chain } from '@xchainjs/xchain-util';
 import { UtxoOnlineDataProviders } from '@xchainjs/xchain-utxo-providers';
-import { Balance, Tx, TxParams, TxsPage, UTXO, UtxoClientParams } from './types';
+import { Balance, PreparedTx, Tx, TxParams, TxsPage, UTXO, UtxoClientParams } from './types';
+import { UtxoSelectionPreferences, UtxoSelectionResult } from './strategies';
 /**
  * Abstract base class for creating blockchain clients in the UTXO model.
  */
@@ -139,18 +140,117 @@ export declare abstract class Client extends BaseXChainClient {
      * @throws {Error} Throws an error if no provider is able to broadcast the transaction.
      */
     protected roundRobinBroadcastTx(txHex: string): Promise<string>;
+    /**
+     * Enhanced UTXO selection using the UtxoSelector with multiple strategies.
+     * This method is available to all UTXO chain implementations.
+     *
+     * @param utxos Available UTXOs to select from
+     * @param targetValue Target amount in satoshis
+     * @param feeRate Fee rate in satoshis per byte
+     * @param extraOutputs Number of extra outputs (default: 2 for recipient + change)
+     * @param preferences Selection preferences
+     * @returns Selection result with inputs, change, and fee
+     */
+    protected selectUtxosForTransaction(utxos: UTXO[], targetValue: number, feeRate: number, extraOutputs?: number, preferences?: UtxoSelectionPreferences): UtxoSelectionResult;
+    /**
+     * Validate transaction inputs using comprehensive validation.
+     * Chain implementations can override to add chain-specific validation.
+     *
+     * @param params Transaction parameters including sender and feeRate
+     */
+    protected validateTransactionInputs(params: TxParams & {
+        sender: Address;
+        feeRate: FeeRate;
+    }): void;
+    /**
+     * Calculate maximum sendable amount by using ALL available UTXOs.
+     *
+     * For a true sweep operation, we use all UTXOs to maximize the sent amount.
+     * This is simpler and more correct than binary search with UTXO selection.
+     *
+     * @param utxos Available UTXOs
+     * @param feeRate Fee rate in satoshis per byte
+     * @param hasMemo Whether transaction has a memo
+     * @param preferences UTXO selection preferences
+     * @returns Maximum sendable amount, fee, and selected inputs
+     */
+    protected calculateMaxSendableAmount(utxos: UTXO[], feeRate: number, hasMemo: boolean, preferences?: UtxoSelectionPreferences): {
+        amount: number;
+        fee: number;
+        inputs: UTXO[];
+    };
+    /**
+     * Get and validate UTXOs for transaction building.
+     *
+     * @param sender Sender address
+     * @param confirmedOnly Whether to only use confirmed UTXOs
+     * @returns Validated UTXO array
+     */
+    protected getValidatedUtxos(sender: Address, confirmedOnly: boolean): Promise<UTXO[]>;
+    /**
+     * Prepare transaction with enhanced UTXO selection.
+     * Chain implementations should override buildTxPsbt to provide chain-specific PSBT construction.
+     *
+     * @param params Transaction parameters
+     * @returns Prepared transaction with UTXO details
+     */
+    prepareTxEnhanced({ sender, memo, amount, recipient, spendPendingUTXO, feeRate, utxoSelectionPreferences, }: TxParams & {
+        sender: Address;
+        feeRate: FeeRate;
+        spendPendingUTXO?: boolean;
+        utxoSelectionPreferences?: UtxoSelectionPreferences;
+    }): Promise<PreparedTx>;
+    /**
+     * Prepare maximum amount transfer (sweep transaction).
+     *
+     * @param params Send max parameters
+     * @returns Prepared transaction with maximum sendable amount
+     */
+    prepareMaxTx({ sender, recipient, memo, feeRate, spendPendingUTXO, utxoSelectionPreferences, }: {
+        sender: Address;
+        recipient: Address;
+        memo?: string;
+        feeRate: FeeRate;
+        spendPendingUTXO?: boolean;
+        utxoSelectionPreferences?: UtxoSelectionPreferences;
+    }): Promise<PreparedTx & {
+        maxAmount: number;
+        fee: number;
+    }>;
+    /**
+     * Abstract method to validate an address for this chain.
+     * @param address The address to validate
+     * @returns true if valid, false otherwise
+     */
+    abstract validateAddress(address: string): boolean;
     /**
      * Abstract method to compile a memo.
-     * @param {string} memo The memo string to compile.
-     * @returns {Buffer} The compiled memo.
+     * @param memo The memo string to compile.
+     * @returns The compiled memo.
      */
     protected abstract compileMemo(memo: string): Buffer;
+    /**
+     * Build a PSBT for this chain.
+     * Chain implementations should override this to provide chain-specific PSBT construction.
+     * Default implementation throws - override in chain client to enable enhanced methods.
+     *
+     * @param params PSBT build parameters
+     * @returns Base64-encoded PSBT string
+     */
+    protected buildTxPsbt(_params: {
+        inputs: UTXO[];
+        recipient: Address;
+        amount: number;
+        changeAmount: number;
+        changeAddress: Address;
+        memo: Buffer | null;
+    }): Promise<string>;
     /**
      * Abstract method to calculate the fee from a list of UTXOs.
-     * @param {UTXO[]} inputs The list of UTXOs.
-     * @param {FeeRate} feeRate The fee rate.
-     * @param {Buffer | null} data Optional data buffer.
-     * @returns {number} The calculated fee.
+     * @param inputs The list of UTXOs.
+     * @param feeRate The fee rate.
+     * @param data Optional data buffer.
+     * @returns The calculated fee.
      */
     protected abstract getFeeFromUtxos(inputs: UTXO[], feeRate: FeeRate, data: Buffer | null): number;
     /**

package/lib/constants.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Standard UTXO constants used across the library
+ */
+/**
+ * Bitcoin's standard dust threshold (546 satoshis)
+ *
+ * This is the minimum value for a UTXO to be considered economically spendable.
+ * The value comes from Bitcoin Core's calculation:
+ * - P2PKH output size: 34 bytes
+ * - Cost to spend: 34 bytes × 3 sat/byte = 102 satoshis
+ * - Dust threshold: 102 × 3 = 306 satoshis (theoretical)
+ * - Bitcoin Core uses 546 for safety margin and worst-case scenarios
+ *
+ * Note: Different UTXO chains may have different dust thresholds
+ */
+export declare const DUST_THRESHOLD = 546;
+/**
+ * Transaction size constants for fee calculation
+ */
+export declare const TX_SIZE_CONSTANTS: {
+    /** Base transaction overhead in virtual bytes */
+    readonly BASE_TX_SIZE: 10;
+    /** Approximate virtual bytes per P2WPKH input */
+    readonly BYTES_PER_INPUT: 68;
+    /** Virtual bytes per P2WPKH output */
+    readonly BYTES_PER_OUTPUT: 31;
+};
+/**
+ * Maximum reasonable amount (21M BTC equivalent in satoshis)
+ * Used as a sanity check for transaction amounts
+ */
+export declare const MAX_REASONABLE_AMOUNT = "2100000000000000";
+/**
+ * Maximum decimal precision for UTXO-based cryptocurrencies
+ *
+ * Most UTXO chains (Bitcoin, Litecoin, Dogecoin, etc.) use 8 decimal places:
+ * - 1 BTC = 100,000,000 satoshis (10^8)
+ * - 1 LTC = 100,000,000 litoshi (10^8)
+ * - 1 DOGE = 100,000,000 koinu (10^8)
+ *
+ * This differs from Ethereum tokens which can have up to 18 decimals
+ */
+export declare const MAX_UTXO_DECIMALS = 8;

package/lib/errors.d.ts

@@ -0,0 +1,91 @@
+/**
+ * UTXO-specific error codes for better error handling and debugging
+ */
+export declare enum UtxoErrorCode {
+    INSUFFICIENT_BALANCE = "INSUFFICIENT_BALANCE",
+    INVALID_ADDRESS = "INVALID_ADDRESS",
+    INVALID_AMOUNT = "INVALID_AMOUNT",
+    INVALID_FEE_RATE = "INVALID_FEE_RATE",
+    INVALID_MEMO = "INVALID_MEMO",
+    INVALID_UTXO = "INVALID_UTXO",
+    PROVIDER_ERROR = "PROVIDER_ERROR",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    TRANSACTION_TOO_LARGE = "TRANSACTION_TOO_LARGE",
+    UTXO_SELECTION_FAILED = "UTXO_SELECTION_FAILED",
+    BROADCAST_ERROR = "BROADCAST_ERROR",
+    SIGNING_ERROR = "SIGNING_ERROR"
+}
+/**
+ * Enhanced error class for UTXO operations with detailed context
+ */
+export declare class UtxoError extends Error {
+    readonly code: UtxoErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    readonly isUtxoError = true;
+    constructor(code: UtxoErrorCode, message: string, details?: Record<string, unknown> | undefined);
+    /**
+     * Create an insufficient balance error
+     */
+    static insufficientBalance(required: string, available: string, chain?: string): UtxoError;
+    /**
+     * Create an invalid address error
+     */
+    static invalidAddress(address: string, network?: string): UtxoError;
+    /**
+     * Create an invalid amount error
+     */
+    static invalidAmount(amount: string | number, reason?: string): UtxoError;
+    /**
+     * Create an invalid fee rate error
+     */
+    static invalidFeeRate(feeRate: number, reason?: string): UtxoError;
+    /**
+     * Create an invalid memo error
+     */
+    static invalidMemo(memo: string, reason: string): UtxoError;
+    /**
+     * Create a provider error
+     */
+    static providerError(providerName: string, originalError: Error): UtxoError;
+    /**
+     * Create a network error
+     */
+    static networkError(operation: string, originalError: Error): UtxoError;
+    /**
+     * Create a validation error
+     */
+    static validationError(message: string, details?: Record<string, unknown>): UtxoError;
+    /**
+     * Create a transaction too large error
+     */
+    static transactionTooLarge(currentSize: number, maxSize: number): UtxoError;
+    /**
+     * Create a UTXO selection failed error
+     */
+    static utxoSelectionFailed(targetAmount: number, availableAmount: number, strategy?: string): UtxoError;
+    /**
+     * Create a broadcast error
+     */
+    static broadcastError(txHash: string, originalError: Error): UtxoError;
+    /**
+     * Create a signing error
+     */
+    static signingError(reason: string, details?: Record<string, unknown>): UtxoError;
+    /**
+     * Convert unknown errors to typed UTXO errors
+     */
+    static fromUnknown(error: unknown, context?: string): UtxoError;
+    /**
+     * Check if an error is a UTXO error
+     */
+    static isUtxoError(error: unknown): error is UtxoError;
+    /**
+     * Get a user-friendly error message
+     */
+    getUserFriendlyMessage(): string;
+    /**
+     * Convert to JSON for logging
+     */
+    toJSON(): Record<string, unknown>;
+}

package/lib/index.d.ts

@@ -6,3 +6,8 @@ import { Balance, PreparedTx, Tx, TxFrom, TxParams, TxTo, TxsPage, UTXO, UtxoCli
  */
 export { Client, toBitcoinJS };
 export type { UTXO, UtxoClientParams, Witness, PreparedTx, Balance, Tx, TxsPage, TxParams, TxTo, TxFrom };
+export { UtxoError, UtxoErrorCode } from './errors';
+export { UtxoTransactionValidator } from './validators';
+export { UtxoSelector } from './utxo-selector';
+export * from './strategies';
+export * from './constants';