@xchainjs/xchain-bitcoin 2.0.9 → 2.1.0

package/lib/client.d.ts

@@ -1,6 +1,6 @@
 import { AssetInfo, FeeRate } from '@xchainjs/xchain-client';
 import { Address } from '@xchainjs/xchain-util';
-import { Client as UTXOClient, PreparedTx, TxParams, UTXO, UtxoClientParams } from '@xchainjs/xchain-utxo';
+import { Client as UTXOClient, PreparedTx, TxParams, UTXO, UtxoClientParams, UtxoSelectionPreferences } from '@xchainjs/xchain-utxo';
 import * as Bitcoin from 'bitcoinjs-lib';
 import { AddressFormat } from './types';
 export declare const defaultBTCParams: UtxoClientParams;
@@ -43,9 +43,24 @@ declare abstract class Client extends UTXOClient {
      */
     protected getFeeFromUtxos(inputs: UTXO[], feeRate: FeeRate, data?: Buffer | null): number;
     /**
-     * Build a Bitcoin transaction.*
+     * Enhanced Bitcoin transaction builder with comprehensive validation and optimal UTXO selection
+     * @param params Transaction parameters
+     * @returns Enhanced transaction build result with PSBT, UTXOs, and inputs
+     */
+    buildTxEnhanced({ amount, recipient, memo, feeRate, sender, spendPendingUTXO, utxoSelectionPreferences, }: TxParams & {
+        feeRate: FeeRate;
+        sender: Address;
+        spendPendingUTXO?: boolean;
+        utxoSelectionPreferences?: UtxoSelectionPreferences;
+    }): Promise<{
+        psbt: Bitcoin.Psbt;
+        utxos: UTXO[];
+        inputs: UTXO[];
+    }>;
+    /**
+     * Build a Bitcoin transaction with enhanced validation and performance.
+     * Now uses the enhanced logic internally while maintaining the same API.
      * @param param0
-     * @deprecated
      */
     buildTx({ amount, recipient, memo, feeRate, sender, spendPendingUTXO, }: TxParams & {
         feeRate: FeeRate;
@@ -58,8 +73,57 @@ declare abstract class Client extends UTXOClient {
         inputs: UTXO[];
     }>;
     /**
-     * Prepare transfer.
+     * Send maximum possible amount (sweep) with optimal fee calculation
+     * @param params Send max parameters
+     * @returns Transaction details with maximum sendable amount
+     */
+    sendMax({ sender, recipient, memo, feeRate, spendPendingUTXO, utxoSelectionPreferences, }: {
+        sender: Address;
+        recipient: Address;
+        memo?: string;
+        feeRate: FeeRate;
+        spendPendingUTXO?: boolean;
+        utxoSelectionPreferences?: UtxoSelectionPreferences;
+    }): Promise<{
+        psbt: Bitcoin.Psbt;
+        utxos: UTXO[];
+        inputs: UTXO[];
+        maxAmount: number;
+        fee: number;
+    }>;
+    /**
+     * 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;
+    }>;
+    /**
+     * Enhanced prepare transfer with comprehensive validation and optimal UTXO selection.
+     *
+     * @param params The transfer options with enhanced UTXO selection preferences.
+     * @returns The raw unsigned transaction with enhanced error handling.
+     */
+    prepareTxEnhanced({ sender, memo, amount, recipient, spendPendingUTXO, feeRate, utxoSelectionPreferences, }: TxParams & {
+        sender: Address;
+        feeRate: FeeRate;
+        spendPendingUTXO?: boolean;
+        utxoSelectionPreferences?: UtxoSelectionPreferences;
+    }): Promise<PreparedTx>;
+    /**
+     * Prepare transfer with enhanced validation and performance.
+     * Now uses the enhanced logic internally while maintaining the same API.
      *
+     * @deprecated Use `prepareTxEnhanced` directly for explicit enhanced UTXO selection.
      * @param {TxParams&Address&FeeRate&boolean} params The transfer options.
      * @returns {PreparedTx} The raw unsigned transaction.
      */

package/lib/clientKeystore.d.ts

@@ -1,6 +1,6 @@
 import { FeeRate, TxHash } from '@xchainjs/xchain-client';
 import { Address } from '@xchainjs/xchain-util';
-import { TxParams, UtxoClientParams } from '@xchainjs/xchain-utxo';
+import { TxParams, UtxoClientParams, UtxoSelectionPreferences } from '@xchainjs/xchain-utxo';
 import { Client } from './client';
 import { AddressFormat } from './types';
 /**
@@ -41,11 +41,35 @@ declare class ClientKeystore extends Client {
      * Transfer BTC.
      *
      * @param {TxParams&FeeRate} params The transfer options including the fee rate.
-     * @returns {Promise<TxHash|string>} A promise that resolves to the transaction hash or an error message.
+     * @returns {Promise<TxHash>} A promise that resolves to the transaction hash.
      * @throws {"memo too long"} Thrown if the memo is longer than 80 characters.
      */
     transfer(params: TxParams & {
         feeRate?: FeeRate;
+        utxoSelectionPreferences?: UtxoSelectionPreferences;
     }): Promise<TxHash>;
+    /**
+     * Transfer the maximum amount of Bitcoin (sweep).
+     *
+     * Calculates the maximum sendable amount after fees, signs, and broadcasts the transaction.
+     * @param {Object} params The transfer parameters.
+     * @param {string} params.recipient The recipient address.
+     * @param {string} [params.memo] Optional memo for the transaction.
+     * @param {FeeRate} [params.feeRate] Optional fee rate. Defaults to 'fast' rate.
+     * @param {number} [params.walletIndex] Optional wallet index. Defaults to 0.
+     * @param {UtxoSelectionPreferences} [params.utxoSelectionPreferences] Optional UTXO selection preferences.
+     * @returns {Promise<{ hash: TxHash; maxAmount: number; fee: number }>} The transaction hash, amount sent, and fee.
+     */
+    transferMax(params: {
+        recipient: Address;
+        memo?: string;
+        feeRate?: FeeRate;
+        walletIndex?: number;
+        utxoSelectionPreferences?: UtxoSelectionPreferences;
+    }): Promise<{
+        hash: TxHash;
+        maxAmount: number;
+        fee: number;
+    }>;
 }
 export { ClientKeystore };

package/lib/clientLedger.d.ts

@@ -1,7 +1,7 @@
 import AppBtc from '@ledgerhq/hw-app-btc';
 import { FeeRate, TxHash } from '@xchainjs/xchain-client';
 import { Address } from '@xchainjs/xchain-util';
-import { TxParams, UtxoClientParams } from '@xchainjs/xchain-utxo';
+import { TxParams, UtxoClientParams, UtxoSelectionPreferences } from '@xchainjs/xchain-utxo';
 import { Client } from './client';
 import { AddressFormat } from './types';
 /**
@@ -19,6 +19,7 @@ declare class ClientLedger extends Client {
     getAddressAsync(index?: number, verify?: boolean): Promise<Address>;
     transfer(params: TxParams & {
         feeRate?: FeeRate;
+        utxoSelectionPreferences?: UtxoSelectionPreferences;
     }): Promise<TxHash>;
 }
 export { ClientLedger };

package/lib/index.esm.js

@@ -4,8 +4,7 @@ import { getSeed } from '@xchainjs/xchain-crypto';
 import { HDKey } from '@scure/bip32';
 import * as Bitcoin from 'bitcoinjs-lib';
 import { ECPairFactory } from 'ecpair';
-import { Client as Client$1 } from '@xchainjs/xchain-utxo';
-import accumulative from 'coinselect/accumulative.js';
+import { Client as Client$1, UtxoError } from '@xchainjs/xchain-utxo';
 import { AssetType } from '@xchainjs/xchain-util';
 import { SochainProvider, SochainNetwork, HaskoinProvider, HaskoinNetwork, BlockcypherProvider, BlockcypherNetwork, BitgoProvider } from '@xchainjs/xchain-utxo-providers';
 import AppBtc from '@ledgerhq/hw-app-btc';
@@ -160,7 +159,7 @@ const validateAddress = (address, network) => {
         Bitcoin.address.toOutputScript(address, btcNetwork(network)); // Try to convert the address to an output script using the specified network
         return true; // If successful, the address is valid
     }
-    catch (_error) {
+    catch (_a) {
         return false; // If an error occurs, the address is invalid
     }
 };
@@ -285,98 +284,242 @@ class Client extends Client$1 {
         return fee > MIN_TX_FEE ? fee : MIN_TX_FEE;
     }
     /**
-     * Build a Bitcoin transaction.*
+     * Enhanced Bitcoin transaction builder with comprehensive validation and optimal UTXO selection
+     * @param params Transaction parameters
+     * @returns Enhanced transaction build result with PSBT, UTXOs, and inputs
+     */
+    buildTxEnhanced(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ amount, recipient, memo, feeRate, sender, spendPendingUTXO = true, utxoSelectionPreferences, }) {
+            try {
+                // Comprehensive input validation
+                this.validateTransactionInputs({
+                    amount,
+                    recipient,
+                    memo,
+                    sender,
+                    feeRate,
+                });
+                // Get validated UTXOs
+                const confirmedOnly = !spendPendingUTXO;
+                const utxos = yield this.getValidatedUtxos(sender, confirmedOnly);
+                const compiledMemo = memo ? this.compileMemo(memo) : null;
+                const targetValue = amount.amount().toNumber();
+                const extraOutputs = 1 + (compiledMemo ? 1 : 0); // recipient + optional memo (change calculated separately)
+                // Enhanced UTXO selection
+                const selectionResult = this.selectUtxosForTransaction(utxos, targetValue, Math.ceil(feeRate), extraOutputs, utxoSelectionPreferences);
+                const psbt = new Bitcoin.Psbt({ network: btcNetwork(this.network) });
+                // Add inputs based on selection
+                if (this.addressFormat === AddressFormat.P2WPKH) {
+                    selectionResult.inputs.forEach((utxo) => {
+                        if (!utxo.witnessUtxo) {
+                            throw UtxoError.fromUnknown(new Error(`Missing witnessUtxo for UTXO ${utxo.hash}:${utxo.index}`), 'buildTxPsbt');
+                        }
+                        psbt.addInput({
+                            hash: utxo.hash,
+                            index: utxo.index,
+                            witnessUtxo: utxo.witnessUtxo,
+                        });
+                    });
+                }
+                else {
+                    const { pubkey, output } = Bitcoin.payments.p2tr({
+                        address: sender,
+                    });
+                    selectionResult.inputs.forEach((utxo) => psbt.addInput({
+                        hash: utxo.hash,
+                        index: utxo.index,
+                        witnessUtxo: { value: utxo.value, script: output },
+                        tapInternalKey: pubkey,
+                    }));
+                }
+                // Add recipient output
+                psbt.addOutput({
+                    address: recipient,
+                    value: targetValue,
+                });
+                // Add change output if needed
+                if (selectionResult.changeAmount > 0) {
+                    psbt.addOutput({
+                        address: sender,
+                        value: selectionResult.changeAmount,
+                    });
+                }
+                // Add memo output if present
+                if (compiledMemo) {
+                    psbt.addOutput({ script: compiledMemo, value: 0 });
+                }
+                return { psbt, utxos, inputs: selectionResult.inputs };
+            }
+            catch (error) {
+                if (UtxoError.isUtxoError(error)) {
+                    throw error;
+                }
+                throw UtxoError.fromUnknown(error, 'buildTxEnhanced');
+            }
+        });
+    }
+    /**
+     * Build a Bitcoin transaction with enhanced validation and performance.
+     * Now uses the enhanced logic internally while maintaining the same API.
      * @param param0
-     * @deprecated
      */
     buildTx(_a) {
         return __awaiter(this, arguments, void 0, function* ({ amount, recipient, memo, feeRate, sender, spendPendingUTXO = true, }) {
-            // Check memo length
-            if (memo && memo.length > 80) {
-                throw new Error('memo too long, must not be longer than 80 chars.');
-            }
-            // This section of the code is responsible for preparing a transaction by building a Bitcoin PSBT (Partially Signed Bitcoin Transaction).
-            if (!this.validateAddress(recipient))
-                throw new Error('Invalid address');
-            // Determine whether to only use confirmed UTXOs or include pending UTXOs based on the spendPendingUTXO flag.
-            const confirmedOnly = !spendPendingUTXO;
-            // Scan UTXOs associated with the sender's address.
-            const utxos = yield this.scanUTXOs(sender, confirmedOnly);
-            // Throw an error if there are no available UTXOs to cover the transaction.
-            if (utxos.length === 0)
-                throw new Error('Insufficient Balance for transaction');
-            // Round up the fee rate to the nearest integer.
-            const feeRateWhole = Math.ceil(feeRate);
-            // Compile the memo into a Buffer if provided.
-            const compiledMemo = memo ? this.compileMemo(memo) : null;
-            // Initialize an array to store the target outputs of the transaction.
-            const targetOutputs = [];
-            // 1. Add the recipient address and amount to the target outputs.
-            targetOutputs.push({
-                address: recipient,
-                value: amount.amount().toNumber(),
+            // Use the enhanced logic internally while maintaining the same API
+            return this.buildTxEnhanced({
+                amount,
+                recipient,
+                memo,
+                feeRate,
+                sender,
+                spendPendingUTXO,
             });
-            // 2. Add the compiled memo to the target outputs if it exists.
-            if (compiledMemo) {
-                targetOutputs.push({ script: compiledMemo, value: 0 });
+        });
+    }
+    /**
+     * Send maximum possible amount (sweep) with optimal fee calculation
+     * @param params Send max parameters
+     * @returns Transaction details with maximum sendable amount
+     */
+    sendMax(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ sender, recipient, memo, feeRate, spendPendingUTXO = true, utxoSelectionPreferences, }) {
+            try {
+                // Basic validation (skip amount validation since we're calculating max)
+                if (!(recipient === null || recipient === void 0 ? void 0 : recipient.trim())) {
+                    throw UtxoError.invalidAddress(recipient, this.network);
+                }
+                if (!this.validateAddress(recipient)) {
+                    throw UtxoError.invalidAddress(recipient, this.network);
+                }
+                if (!this.validateAddress(sender)) {
+                    throw UtxoError.invalidAddress(sender, this.network);
+                }
+                // Memo validation is handled by validateTransactionInputs
+                // Get validated UTXOs
+                const confirmedOnly = !spendPendingUTXO;
+                const utxos = yield this.getValidatedUtxos(sender, confirmedOnly);
+                // Calculate maximum sendable amount
+                const maxCalc = this.calculateMaxSendableAmount(utxos, Math.ceil(feeRate), !!memo, utxoSelectionPreferences);
+                const compiledMemo = memo ? this.compileMemo(memo) : null;
+                const psbt = new Bitcoin.Psbt({ network: btcNetwork(this.network) });
+                // Add inputs
+                if (this.addressFormat === AddressFormat.P2WPKH) {
+                    maxCalc.inputs.forEach((utxo) => psbt.addInput({
+                        hash: utxo.hash,
+                        index: utxo.index,
+                        witnessUtxo: utxo.witnessUtxo,
+                    }));
+                }
+                else {
+                    const { pubkey, output } = Bitcoin.payments.p2tr({
+                        address: sender,
+                    });
+                    maxCalc.inputs.forEach((utxo) => psbt.addInput({
+                        hash: utxo.hash,
+                        index: utxo.index,
+                        witnessUtxo: { value: utxo.value, script: output },
+                        tapInternalKey: pubkey,
+                    }));
+                }
+                // Add recipient output (max amount - no change)
+                psbt.addOutput({
+                    address: recipient,
+                    value: maxCalc.amount,
+                });
+                // Add memo output if present
+                if (compiledMemo) {
+                    psbt.addOutput({ script: compiledMemo, value: 0 });
+                }
+                return {
+                    psbt,
+                    utxos,
+                    inputs: maxCalc.inputs,
+                    maxAmount: maxCalc.amount,
+                    fee: maxCalc.fee,
+                };
             }
-            // Use the coinselect library to determine the inputs and outputs for the transaction.
-            const { inputs, outputs } = accumulative(utxos, targetOutputs, feeRateWhole);
-            // If no suitable inputs or outputs are found, throw an error indicating insufficient balance.
-            if (!inputs || !outputs)
-                throw new Error('Insufficient Balance for transaction');
-            // Initialize a new Bitcoin PSBT object.
-            const psbt = new Bitcoin.Psbt({ network: btcNetwork(this.network) }); // Network-specific
-            if (this.addressFormat === AddressFormat.P2WPKH) {
-                // Add inputs to the PSBT from the accumulated inputs.
-                inputs.forEach((utxo) => psbt.addInput({
-                    hash: utxo.hash,
-                    index: utxo.index,
-                    witnessUtxo: utxo.witnessUtxo,
-                }));
+            catch (error) {
+                if (UtxoError.isUtxoError(error)) {
+                    throw error;
+                }
+                throw UtxoError.fromUnknown(error, 'sendMax');
             }
-            else {
-                const { pubkey, output } = Bitcoin.payments.p2tr({
-                    address: sender,
+        });
+    }
+    /**
+     * Prepare maximum amount transfer (sweep transaction)
+     * @param params Send max parameters
+     * @returns Prepared transaction with maximum sendable amount
+     */
+    prepareMaxTx(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ sender, recipient, memo, feeRate, spendPendingUTXO = true, utxoSelectionPreferences, }) {
+            try {
+                const { psbt, utxos, inputs, maxAmount, fee } = yield this.sendMax({
+                    sender,
+                    recipient,
+                    memo,
+                    feeRate,
+                    spendPendingUTXO,
+                    utxoSelectionPreferences,
                 });
-                inputs.forEach((utxo) => psbt.addInput({
-                    hash: utxo.hash,
-                    index: utxo.index,
-                    witnessUtxo: { value: utxo.value, script: output },
-                    tapInternalKey: pubkey,
-                }));
+                return {
+                    rawUnsignedTx: psbt.toBase64(),
+                    utxos,
+                    inputs,
+                    maxAmount,
+                    fee,
+                };
             }
-            // Add outputs to the PSBT from the accumulated outputs.
-            outputs.forEach((output) => {
-                // If the output address is not specified, it's considered a change address and set to the sender's address.
-                if (!output.address) {
-                    //an empty address means this is the change address
-                    output.address = sender;
-                }
-                // Add the output to the PSBT.
-                if (!output.script) {
-                    psbt.addOutput(output);
+            catch (error) {
+                if (UtxoError.isUtxoError(error)) {
+                    console.error('Bitcoin max transaction preparation failed:', error.toJSON());
+                    throw error;
                 }
-                else {
-                    // If the output is a memo, add it to the PSBT to avoid dust error.
-                    if (compiledMemo) {
-                        psbt.addOutput({ script: compiledMemo, value: 0 });
-                    }
+                throw UtxoError.fromUnknown(error, 'prepareMaxTx');
+            }
+        });
+    }
+    /**
+     * Enhanced prepare transfer with comprehensive validation and optimal UTXO selection.
+     *
+     * @param params The transfer options with enhanced UTXO selection preferences.
+     * @returns The raw unsigned transaction with enhanced error handling.
+     */
+    prepareTxEnhanced(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ sender, memo, amount, recipient, spendPendingUTXO = true, feeRate, utxoSelectionPreferences, }) {
+            try {
+                const { psbt, utxos, inputs } = yield this.buildTxEnhanced({
+                    sender,
+                    recipient,
+                    amount,
+                    feeRate,
+                    memo,
+                    spendPendingUTXO,
+                    utxoSelectionPreferences,
+                });
+                return { rawUnsignedTx: psbt.toBase64(), utxos, inputs };
+            }
+            catch (error) {
+                if (UtxoError.isUtxoError(error)) {
+                    console.error('Enhanced Bitcoin transaction preparation failed:', error.toJSON());
+                    throw error;
                 }
-            });
-            return { psbt, utxos, inputs };
+                throw UtxoError.fromUnknown(error, 'prepareTxEnhanced');
+            }
         });
     }
     /**
-     * Prepare transfer.
+     * Prepare transfer with enhanced validation and performance.
+     * Now uses the enhanced logic internally while maintaining the same API.
      *
+     * @deprecated Use `prepareTxEnhanced` directly for explicit enhanced UTXO selection.
      * @param {TxParams&Address&FeeRate&boolean} params The transfer options.
      * @returns {PreparedTx} The raw unsigned transaction.
      */
     prepareTx(_a) {
         return __awaiter(this, arguments, void 0, function* ({ sender, memo, amount, recipient, spendPendingUTXO = true, feeRate, }) {
-            // Build the transaction using the provided parameters.
-            const { psbt, utxos, inputs } = yield this.buildTx({
+            // Use the enhanced logic internally while maintaining the same API
+            return this.prepareTxEnhanced({
                 sender,
                 recipient,
                 amount,
@@ -384,8 +527,6 @@ class Client extends Client$1 {
                 memo,
                 spendPendingUTXO,
             });
-            // Return the raw unsigned transaction (PSBT) and associated UTXOs.
-            return { rawUnsignedTx: psbt.toBase64(), utxos, inputs };
         });
     }
 }
@@ -471,7 +612,7 @@ class ClientKeystore extends Client {
      * Transfer BTC.
      *
      * @param {TxParams&FeeRate} params The transfer options including the fee rate.
-     * @returns {Promise<TxHash|string>} A promise that resolves to the transaction hash or an error message.
+     * @returns {Promise<TxHash>} A promise that resolves to the transaction hash.
      * @throws {"memo too long"} Thrown if the memo is longer than 80 characters.
      */
     transfer(params) {
@@ -484,8 +625,10 @@ class ClientKeystore extends Client {
             const fromAddressIndex = (params === null || params === void 0 ? void 0 : params.walletIndex) || 0;
             // Get the Bitcoin keys
             const btcKeys = this.getBtcKeys(this.phrase, fromAddressIndex);
+            // Merge default preferences with caller-provided preferences
+            const mergedUtxoSelectionPreferences = Object.assign({ minimizeFee: true, avoidDust: true, minimizeInputs: false }, params.utxoSelectionPreferences);
             // Prepare the transaction
-            const { rawUnsignedTx } = yield this.prepareTx(Object.assign(Object.assign({}, params), { sender: this.getAddress(fromAddressIndex), feeRate }));
+            const { rawUnsignedTx } = yield this.prepareTxEnhanced(Object.assign(Object.assign({}, params), { sender: this.getAddress(fromAddressIndex), feeRate, utxoSelectionPreferences: mergedUtxoSelectionPreferences }));
             // Build the PSBT
             const psbt = Bitcoin.Psbt.fromBase64(rawUnsignedTx);
             // Sign all inputs
@@ -496,18 +639,43 @@ class ClientKeystore extends Client {
             psbt.finalizeAllInputs();
             // Extract the transaction hex
             const txHex = psbt.extractTransaction().toHex();
-            // Extract the transaction hash
-            const txHash = psbt.extractTransaction().getId();
-            try {
-                // Broadcast the transaction and return the transaction hash
-                const txId = yield this.roundRobinBroadcastTx(txHex);
-                return txId;
-            }
-            catch (_err) {
-                // If broadcasting fails, return an error message with a link to the explorer
-                const error = `Server error, please check explorer for tx confirmation ${this.explorerProviders[this.network].getExplorerTxUrl(txHash)}`;
-                return error;
-            }
+            // Broadcast the transaction and return the transaction hash
+            return yield this.roundRobinBroadcastTx(txHex);
+        });
+    }
+    /**
+     * Transfer the maximum amount of Bitcoin (sweep).
+     *
+     * Calculates the maximum sendable amount after fees, signs, and broadcasts the transaction.
+     * @param {Object} params The transfer parameters.
+     * @param {string} params.recipient The recipient address.
+     * @param {string} [params.memo] Optional memo for the transaction.
+     * @param {FeeRate} [params.feeRate] Optional fee rate. Defaults to 'fast' rate.
+     * @param {number} [params.walletIndex] Optional wallet index. Defaults to 0.
+     * @param {UtxoSelectionPreferences} [params.utxoSelectionPreferences] Optional UTXO selection preferences.
+     * @returns {Promise<{ hash: TxHash; maxAmount: number; fee: number }>} The transaction hash, amount sent, and fee.
+     */
+    transferMax(params) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const feeRate = params.feeRate || (yield this.getFeeRates())[FeeOption.Fast];
+            checkFeeBounds(this.feeBounds, feeRate);
+            const fromAddressIndex = params.walletIndex || 0;
+            const sender = yield this.getAddressAsync(fromAddressIndex);
+            const { psbt, maxAmount, fee } = yield this.sendMax({
+                sender,
+                recipient: params.recipient,
+                memo: params.memo,
+                feeRate,
+                utxoSelectionPreferences: params.utxoSelectionPreferences,
+            });
+            const btcKeys = this.getBtcKeys(this.phrase, fromAddressIndex);
+            psbt.signAllInputs(this.addressFormat === AddressFormat.P2WPKH
+                ? btcKeys
+                : btcKeys.tweak(Bitcoin.crypto.taggedHash('TapTweak', toXOnly(btcKeys.publicKey))));
+            psbt.finalizeAllInputs();
+            const txHex = psbt.extractTransaction().toHex();
+            const hash = yield this.roundRobinBroadcastTx(txHex);
+            return { hash, maxAmount, fee };
         });
     }
 }
@@ -558,8 +726,16 @@ class ClientLedger extends Client {
             checkFeeBounds(this.feeBounds, feeRate);
             // Get sender address
             const sender = yield this.getAddressAsync(fromAddressIndex);
-            // Prepare transaction
-            const { rawUnsignedTx, inputs } = yield this.prepareTx(Object.assign(Object.assign({}, params), { sender, feeRate }));
+            // Create defaults and merge with caller-provided preferences
+            const defaults = {
+                minimizeFee: true,
+                avoidDust: true,
+                minimizeInputs: false,
+            };
+            const mergedUtxoSelectionPreferences = Object.assign(Object.assign({}, defaults), params.utxoSelectionPreferences);
+            // Prepare transaction using enhanced method with optimal UTXO selection
+            const { rawUnsignedTx, inputs } = yield this.prepareTxEnhanced(Object.assign(Object.assign({}, params), { sender,
+                feeRate, utxoSelectionPreferences: mergedUtxoSelectionPreferences }));
             const psbt = Bitcoin.Psbt.fromBase64(rawUnsignedTx);
             // Prepare Ledger inputs
             const ledgerInputs = inputs.map(({ txHex, hash, index }) => {

package/lib/index.js

@@ -7,7 +7,6 @@ var bip32 = require('@scure/bip32');
 var Bitcoin = require('bitcoinjs-lib');
 var ecpair = require('ecpair');
 var xchainUtxo = require('@xchainjs/xchain-utxo');
-var accumulative = require('coinselect/accumulative.js');
 var xchainUtil = require('@xchainjs/xchain-util');
 var xchainUtxoProviders = require('@xchainjs/xchain-utxo-providers');
 var AppBtc = require('@ledgerhq/hw-app-btc');
@@ -34,7 +33,6 @@ function _interopNamespace(e) {
 
 var ecc__namespace = /*#__PURE__*/_interopNamespace(ecc);
 var Bitcoin__namespace = /*#__PURE__*/_interopNamespace(Bitcoin);
-var accumulative__default = /*#__PURE__*/_interopDefault(accumulative);
 var AppBtc__default = /*#__PURE__*/_interopDefault(AppBtc);
 
 exports.AddressFormat = void 0;
@@ -187,7 +185,7 @@ const validateAddress = (address, network) => {
         Bitcoin__namespace.address.toOutputScript(address, btcNetwork(network)); // Try to convert the address to an output script using the specified network
         return true; // If successful, the address is valid
     }
-    catch (_error) {
+    catch (_a) {
         return false; // If an error occurs, the address is invalid
     }
 };
@@ -312,98 +310,242 @@ class Client extends xchainUtxo.Client {
         return fee > MIN_TX_FEE ? fee : MIN_TX_FEE;
     }
     /**
-     * Build a Bitcoin transaction.*
+     * Enhanced Bitcoin transaction builder with comprehensive validation and optimal UTXO selection
+     * @param params Transaction parameters
+     * @returns Enhanced transaction build result with PSBT, UTXOs, and inputs
+     */
+    buildTxEnhanced(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ amount, recipient, memo, feeRate, sender, spendPendingUTXO = true, utxoSelectionPreferences, }) {
+            try {
+                // Comprehensive input validation
+                this.validateTransactionInputs({
+                    amount,
+                    recipient,
+                    memo,
+                    sender,
+                    feeRate,
+                });
+                // Get validated UTXOs
+                const confirmedOnly = !spendPendingUTXO;
+                const utxos = yield this.getValidatedUtxos(sender, confirmedOnly);
+                const compiledMemo = memo ? this.compileMemo(memo) : null;
+                const targetValue = amount.amount().toNumber();
+                const extraOutputs = 1 + (compiledMemo ? 1 : 0); // recipient + optional memo (change calculated separately)
+                // Enhanced UTXO selection
+                const selectionResult = this.selectUtxosForTransaction(utxos, targetValue, Math.ceil(feeRate), extraOutputs, utxoSelectionPreferences);
+                const psbt = new Bitcoin__namespace.Psbt({ network: btcNetwork(this.network) });
+                // Add inputs based on selection
+                if (this.addressFormat === exports.AddressFormat.P2WPKH) {
+                    selectionResult.inputs.forEach((utxo) => {
+                        if (!utxo.witnessUtxo) {
+                            throw xchainUtxo.UtxoError.fromUnknown(new Error(`Missing witnessUtxo for UTXO ${utxo.hash}:${utxo.index}`), 'buildTxPsbt');
+                        }
+                        psbt.addInput({
+                            hash: utxo.hash,
+                            index: utxo.index,
+                            witnessUtxo: utxo.witnessUtxo,
+                        });
+                    });
+                }
+                else {
+                    const { pubkey, output } = Bitcoin__namespace.payments.p2tr({
+                        address: sender,
+                    });
+                    selectionResult.inputs.forEach((utxo) => psbt.addInput({
+                        hash: utxo.hash,
+                        index: utxo.index,
+                        witnessUtxo: { value: utxo.value, script: output },
+                        tapInternalKey: pubkey,
+                    }));
+                }
+                // Add recipient output
+                psbt.addOutput({
+                    address: recipient,
+                    value: targetValue,
+                });
+                // Add change output if needed
+                if (selectionResult.changeAmount > 0) {
+                    psbt.addOutput({
+                        address: sender,
+                        value: selectionResult.changeAmount,
+                    });
+                }
+                // Add memo output if present
+                if (compiledMemo) {
+                    psbt.addOutput({ script: compiledMemo, value: 0 });
+                }
+                return { psbt, utxos, inputs: selectionResult.inputs };
+            }
+            catch (error) {
+                if (xchainUtxo.UtxoError.isUtxoError(error)) {
+                    throw error;
+                }
+                throw xchainUtxo.UtxoError.fromUnknown(error, 'buildTxEnhanced');
+            }
+        });
+    }
+    /**
+     * Build a Bitcoin transaction with enhanced validation and performance.
+     * Now uses the enhanced logic internally while maintaining the same API.
      * @param param0
-     * @deprecated
      */
     buildTx(_a) {
         return __awaiter(this, arguments, void 0, function* ({ amount, recipient, memo, feeRate, sender, spendPendingUTXO = true, }) {
-            // Check memo length
-            if (memo && memo.length > 80) {
-                throw new Error('memo too long, must not be longer than 80 chars.');
-            }
-            // This section of the code is responsible for preparing a transaction by building a Bitcoin PSBT (Partially Signed Bitcoin Transaction).
-            if (!this.validateAddress(recipient))
-                throw new Error('Invalid address');
-            // Determine whether to only use confirmed UTXOs or include pending UTXOs based on the spendPendingUTXO flag.
-            const confirmedOnly = !spendPendingUTXO;
-            // Scan UTXOs associated with the sender's address.
-            const utxos = yield this.scanUTXOs(sender, confirmedOnly);
-            // Throw an error if there are no available UTXOs to cover the transaction.
-            if (utxos.length === 0)
-                throw new Error('Insufficient Balance for transaction');
-            // Round up the fee rate to the nearest integer.
-            const feeRateWhole = Math.ceil(feeRate);
-            // Compile the memo into a Buffer if provided.
-            const compiledMemo = memo ? this.compileMemo(memo) : null;
-            // Initialize an array to store the target outputs of the transaction.
-            const targetOutputs = [];
-            // 1. Add the recipient address and amount to the target outputs.
-            targetOutputs.push({
-                address: recipient,
-                value: amount.amount().toNumber(),
+            // Use the enhanced logic internally while maintaining the same API
+            return this.buildTxEnhanced({
+                amount,
+                recipient,
+                memo,
+                feeRate,
+                sender,
+                spendPendingUTXO,
             });
-            // 2. Add the compiled memo to the target outputs if it exists.
-            if (compiledMemo) {
-                targetOutputs.push({ script: compiledMemo, value: 0 });
+        });
+    }
+    /**
+     * Send maximum possible amount (sweep) with optimal fee calculation
+     * @param params Send max parameters
+     * @returns Transaction details with maximum sendable amount
+     */
+    sendMax(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ sender, recipient, memo, feeRate, spendPendingUTXO = true, utxoSelectionPreferences, }) {
+            try {
+                // Basic validation (skip amount validation since we're calculating max)
+                if (!(recipient === null || recipient === void 0 ? void 0 : recipient.trim())) {
+                    throw xchainUtxo.UtxoError.invalidAddress(recipient, this.network);
+                }
+                if (!this.validateAddress(recipient)) {
+                    throw xchainUtxo.UtxoError.invalidAddress(recipient, this.network);
+                }
+                if (!this.validateAddress(sender)) {
+                    throw xchainUtxo.UtxoError.invalidAddress(sender, this.network);
+                }
+                // Memo validation is handled by validateTransactionInputs
+                // Get validated UTXOs
+                const confirmedOnly = !spendPendingUTXO;
+                const utxos = yield this.getValidatedUtxos(sender, confirmedOnly);
+                // Calculate maximum sendable amount
+                const maxCalc = this.calculateMaxSendableAmount(utxos, Math.ceil(feeRate), !!memo, utxoSelectionPreferences);
+                const compiledMemo = memo ? this.compileMemo(memo) : null;
+                const psbt = new Bitcoin__namespace.Psbt({ network: btcNetwork(this.network) });
+                // Add inputs
+                if (this.addressFormat === exports.AddressFormat.P2WPKH) {
+                    maxCalc.inputs.forEach((utxo) => psbt.addInput({
+                        hash: utxo.hash,
+                        index: utxo.index,
+                        witnessUtxo: utxo.witnessUtxo,
+                    }));
+                }
+                else {
+                    const { pubkey, output } = Bitcoin__namespace.payments.p2tr({
+                        address: sender,
+                    });
+                    maxCalc.inputs.forEach((utxo) => psbt.addInput({
+                        hash: utxo.hash,
+                        index: utxo.index,
+                        witnessUtxo: { value: utxo.value, script: output },
+                        tapInternalKey: pubkey,
+                    }));
+                }
+                // Add recipient output (max amount - no change)
+                psbt.addOutput({
+                    address: recipient,
+                    value: maxCalc.amount,
+                });
+                // Add memo output if present
+                if (compiledMemo) {
+                    psbt.addOutput({ script: compiledMemo, value: 0 });
+                }
+                return {
+                    psbt,
+                    utxos,
+                    inputs: maxCalc.inputs,
+                    maxAmount: maxCalc.amount,
+                    fee: maxCalc.fee,
+                };
             }
-            // Use the coinselect library to determine the inputs and outputs for the transaction.
-            const { inputs, outputs } = accumulative__default.default(utxos, targetOutputs, feeRateWhole);
-            // If no suitable inputs or outputs are found, throw an error indicating insufficient balance.
-            if (!inputs || !outputs)
-                throw new Error('Insufficient Balance for transaction');
-            // Initialize a new Bitcoin PSBT object.
-            const psbt = new Bitcoin__namespace.Psbt({ network: btcNetwork(this.network) }); // Network-specific
-            if (this.addressFormat === exports.AddressFormat.P2WPKH) {
-                // Add inputs to the PSBT from the accumulated inputs.
-                inputs.forEach((utxo) => psbt.addInput({
-                    hash: utxo.hash,
-                    index: utxo.index,
-                    witnessUtxo: utxo.witnessUtxo,
-                }));
+            catch (error) {
+                if (xchainUtxo.UtxoError.isUtxoError(error)) {
+                    throw error;
+                }
+                throw xchainUtxo.UtxoError.fromUnknown(error, 'sendMax');
             }
-            else {
-                const { pubkey, output } = Bitcoin__namespace.payments.p2tr({
-                    address: sender,
+        });
+    }
+    /**
+     * Prepare maximum amount transfer (sweep transaction)
+     * @param params Send max parameters
+     * @returns Prepared transaction with maximum sendable amount
+     */
+    prepareMaxTx(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ sender, recipient, memo, feeRate, spendPendingUTXO = true, utxoSelectionPreferences, }) {
+            try {
+                const { psbt, utxos, inputs, maxAmount, fee } = yield this.sendMax({
+                    sender,
+                    recipient,
+                    memo,
+                    feeRate,
+                    spendPendingUTXO,
+                    utxoSelectionPreferences,
                 });
-                inputs.forEach((utxo) => psbt.addInput({
-                    hash: utxo.hash,
-                    index: utxo.index,
-                    witnessUtxo: { value: utxo.value, script: output },
-                    tapInternalKey: pubkey,
-                }));
+                return {
+                    rawUnsignedTx: psbt.toBase64(),
+                    utxos,
+                    inputs,
+                    maxAmount,
+                    fee,
+                };
             }
-            // Add outputs to the PSBT from the accumulated outputs.
-            outputs.forEach((output) => {
-                // If the output address is not specified, it's considered a change address and set to the sender's address.
-                if (!output.address) {
-                    //an empty address means this is the change address
-                    output.address = sender;
-                }
-                // Add the output to the PSBT.
-                if (!output.script) {
-                    psbt.addOutput(output);
+            catch (error) {
+                if (xchainUtxo.UtxoError.isUtxoError(error)) {
+                    console.error('Bitcoin max transaction preparation failed:', error.toJSON());
+                    throw error;
                 }
-                else {
-                    // If the output is a memo, add it to the PSBT to avoid dust error.
-                    if (compiledMemo) {
-                        psbt.addOutput({ script: compiledMemo, value: 0 });
-                    }
+                throw xchainUtxo.UtxoError.fromUnknown(error, 'prepareMaxTx');
+            }
+        });
+    }
+    /**
+     * Enhanced prepare transfer with comprehensive validation and optimal UTXO selection.
+     *
+     * @param params The transfer options with enhanced UTXO selection preferences.
+     * @returns The raw unsigned transaction with enhanced error handling.
+     */
+    prepareTxEnhanced(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ sender, memo, amount, recipient, spendPendingUTXO = true, feeRate, utxoSelectionPreferences, }) {
+            try {
+                const { psbt, utxos, inputs } = yield this.buildTxEnhanced({
+                    sender,
+                    recipient,
+                    amount,
+                    feeRate,
+                    memo,
+                    spendPendingUTXO,
+                    utxoSelectionPreferences,
+                });
+                return { rawUnsignedTx: psbt.toBase64(), utxos, inputs };
+            }
+            catch (error) {
+                if (xchainUtxo.UtxoError.isUtxoError(error)) {
+                    console.error('Enhanced Bitcoin transaction preparation failed:', error.toJSON());
+                    throw error;
                 }
-            });
-            return { psbt, utxos, inputs };
+                throw xchainUtxo.UtxoError.fromUnknown(error, 'prepareTxEnhanced');
+            }
         });
     }
     /**
-     * Prepare transfer.
+     * Prepare transfer with enhanced validation and performance.
+     * Now uses the enhanced logic internally while maintaining the same API.
      *
+     * @deprecated Use `prepareTxEnhanced` directly for explicit enhanced UTXO selection.
      * @param {TxParams&Address&FeeRate&boolean} params The transfer options.
      * @returns {PreparedTx} The raw unsigned transaction.
      */
     prepareTx(_a) {
         return __awaiter(this, arguments, void 0, function* ({ sender, memo, amount, recipient, spendPendingUTXO = true, feeRate, }) {
-            // Build the transaction using the provided parameters.
-            const { psbt, utxos, inputs } = yield this.buildTx({
+            // Use the enhanced logic internally while maintaining the same API
+            return this.prepareTxEnhanced({
                 sender,
                 recipient,
                 amount,
@@ -411,8 +553,6 @@ class Client extends xchainUtxo.Client {
                 memo,
                 spendPendingUTXO,
             });
-            // Return the raw unsigned transaction (PSBT) and associated UTXOs.
-            return { rawUnsignedTx: psbt.toBase64(), utxos, inputs };
         });
     }
 }
@@ -498,7 +638,7 @@ class ClientKeystore extends Client {
      * Transfer BTC.
      *
      * @param {TxParams&FeeRate} params The transfer options including the fee rate.
-     * @returns {Promise<TxHash|string>} A promise that resolves to the transaction hash or an error message.
+     * @returns {Promise<TxHash>} A promise that resolves to the transaction hash.
      * @throws {"memo too long"} Thrown if the memo is longer than 80 characters.
      */
     transfer(params) {
@@ -511,8 +651,10 @@ class ClientKeystore extends Client {
             const fromAddressIndex = (params === null || params === void 0 ? void 0 : params.walletIndex) || 0;
             // Get the Bitcoin keys
             const btcKeys = this.getBtcKeys(this.phrase, fromAddressIndex);
+            // Merge default preferences with caller-provided preferences
+            const mergedUtxoSelectionPreferences = Object.assign({ minimizeFee: true, avoidDust: true, minimizeInputs: false }, params.utxoSelectionPreferences);
             // Prepare the transaction
-            const { rawUnsignedTx } = yield this.prepareTx(Object.assign(Object.assign({}, params), { sender: this.getAddress(fromAddressIndex), feeRate }));
+            const { rawUnsignedTx } = yield this.prepareTxEnhanced(Object.assign(Object.assign({}, params), { sender: this.getAddress(fromAddressIndex), feeRate, utxoSelectionPreferences: mergedUtxoSelectionPreferences }));
             // Build the PSBT
             const psbt = Bitcoin__namespace.Psbt.fromBase64(rawUnsignedTx);
             // Sign all inputs
@@ -523,18 +665,43 @@ class ClientKeystore extends Client {
             psbt.finalizeAllInputs();
             // Extract the transaction hex
             const txHex = psbt.extractTransaction().toHex();
-            // Extract the transaction hash
-            const txHash = psbt.extractTransaction().getId();
-            try {
-                // Broadcast the transaction and return the transaction hash
-                const txId = yield this.roundRobinBroadcastTx(txHex);
-                return txId;
-            }
-            catch (_err) {
-                // If broadcasting fails, return an error message with a link to the explorer
-                const error = `Server error, please check explorer for tx confirmation ${this.explorerProviders[this.network].getExplorerTxUrl(txHash)}`;
-                return error;
-            }
+            // Broadcast the transaction and return the transaction hash
+            return yield this.roundRobinBroadcastTx(txHex);
+        });
+    }
+    /**
+     * Transfer the maximum amount of Bitcoin (sweep).
+     *
+     * Calculates the maximum sendable amount after fees, signs, and broadcasts the transaction.
+     * @param {Object} params The transfer parameters.
+     * @param {string} params.recipient The recipient address.
+     * @param {string} [params.memo] Optional memo for the transaction.
+     * @param {FeeRate} [params.feeRate] Optional fee rate. Defaults to 'fast' rate.
+     * @param {number} [params.walletIndex] Optional wallet index. Defaults to 0.
+     * @param {UtxoSelectionPreferences} [params.utxoSelectionPreferences] Optional UTXO selection preferences.
+     * @returns {Promise<{ hash: TxHash; maxAmount: number; fee: number }>} The transaction hash, amount sent, and fee.
+     */
+    transferMax(params) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const feeRate = params.feeRate || (yield this.getFeeRates())[xchainClient.FeeOption.Fast];
+            xchainClient.checkFeeBounds(this.feeBounds, feeRate);
+            const fromAddressIndex = params.walletIndex || 0;
+            const sender = yield this.getAddressAsync(fromAddressIndex);
+            const { psbt, maxAmount, fee } = yield this.sendMax({
+                sender,
+                recipient: params.recipient,
+                memo: params.memo,
+                feeRate,
+                utxoSelectionPreferences: params.utxoSelectionPreferences,
+            });
+            const btcKeys = this.getBtcKeys(this.phrase, fromAddressIndex);
+            psbt.signAllInputs(this.addressFormat === exports.AddressFormat.P2WPKH
+                ? btcKeys
+                : btcKeys.tweak(Bitcoin__namespace.crypto.taggedHash('TapTweak', toXOnly(btcKeys.publicKey))));
+            psbt.finalizeAllInputs();
+            const txHex = psbt.extractTransaction().toHex();
+            const hash = yield this.roundRobinBroadcastTx(txHex);
+            return { hash, maxAmount, fee };
         });
     }
 }
@@ -585,8 +752,16 @@ class ClientLedger extends Client {
             xchainClient.checkFeeBounds(this.feeBounds, feeRate);
             // Get sender address
             const sender = yield this.getAddressAsync(fromAddressIndex);
-            // Prepare transaction
-            const { rawUnsignedTx, inputs } = yield this.prepareTx(Object.assign(Object.assign({}, params), { sender, feeRate }));
+            // Create defaults and merge with caller-provided preferences
+            const defaults = {
+                minimizeFee: true,
+                avoidDust: true,
+                minimizeInputs: false,
+            };
+            const mergedUtxoSelectionPreferences = Object.assign(Object.assign({}, defaults), params.utxoSelectionPreferences);
+            // Prepare transaction using enhanced method with optimal UTXO selection
+            const { rawUnsignedTx, inputs } = yield this.prepareTxEnhanced(Object.assign(Object.assign({}, params), { sender,
+                feeRate, utxoSelectionPreferences: mergedUtxoSelectionPreferences }));
             const psbt = Bitcoin__namespace.Psbt.fromBase64(rawUnsignedTx);
             // Prepare Ledger inputs
             const ledgerInputs = inputs.map(({ txHex, hash, index }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xchainjs/xchain-bitcoin",
-  "version": "2.0.9",
+  "version": "2.1.0",
   "description": "Custom Bitcoin client and utilities used by XChainJS clients",
   "keywords": [
     "XChain",
@@ -36,18 +36,18 @@
     "@bitcoin-js/tiny-secp256k1-asmjs": "^2.2.3",
     "@ledgerhq/hw-app-btc": "^10.9.0",
     "@scure/bip32": "^1.7.0",
-    "@xchainjs/xchain-client": "2.0.9",
+    "@xchainjs/xchain-client": "2.0.10",
     "@xchainjs/xchain-crypto": "1.0.6",
     "@xchainjs/xchain-util": "2.0.5",
-    "@xchainjs/xchain-utxo": "2.0.9",
-    "@xchainjs/xchain-utxo-providers": "2.0.9",
+    "@xchainjs/xchain-utxo": "2.1.0",
+    "@xchainjs/xchain-utxo-providers": "2.0.10",
     "bitcoinjs-lib": "^6.1.7",
     "coinselect": "3.1.12",
     "ecpair": "2.1.0"
   },
   "devDependencies": {
     "@ledgerhq/hw-transport-node-hid": "^6.28.6",
-    "axios": "1.12.1",
+    "axios": "1.13.5",
     "axios-mock-adapter": "^2.1.0"
   },
   "publishConfig": {