@dynamic-labs/bitcoin 4.53.1 → 4.54.0

package/src/services/PsbtBuilderService.cjs

@@ -24,104 +24,234 @@ class PsbtBuilderService {
     constructor(mempoolApiService) {
         this.mempoolApiService = mempoolApiService;
     }
+    /**
+     * Filters out Taproot (P2TR) UTXOs to prevent accidental spending of Ordinals/Runes
+     * Since we only support Native SegWit (P2WPKH), we ensure the account address is not Taproot
+     * @param accountAddress - The account address to check
+     * @param utxos - Array of UTXOs to filter
+     * @returns Filtered array of UTXOs (only P2WPKH compatible)
+     */
+    filterTaprootUTXOs(accountAddress, utxos) {
+        // Safety check: Ensure account address is not Taproot (bc1p...)
+        if (accountAddress.toLowerCase().startsWith('bc1p') ||
+            accountAddress.toLowerCase().startsWith('tb1p')) {
+            logger.warn(`Account address ${accountAddress} appears to be Taproot. Only Native SegWit (P2WPKH) is supported.`);
+            throw new utils.DynamicError('Taproot addresses are not supported. Only Native SegWit (P2WPKH) addresses are allowed.');
+        }
+        return utxos;
+    }
+    /**
+     * Selects UTXOs using Largest-First (Accumulator) strategy
+     * Sorts UTXOs by value (descending) and selects until we have enough to cover amount + fees
+     * @param utxos - Available UTXOs
+     * @param targetAmount - Target amount including fees and dust limit
+     * @returns Selected UTXOs
+     */
+    selectUTXOsLargestFirst(utxos, targetAmount) {
+        // Sort UTXOs by value (largest first)
+        const sortedUTXOs = [...utxos].sort((a, b) => b.value - a.value);
+        // Accumulate UTXOs until we have enough
+        const selected = [];
+        let total = 0;
+        for (const utxo of sortedUTXOs) {
+            selected.push(utxo);
+            total += utxo.value;
+            // Stop when we have enough to cover the target amount
+            if (total >= targetAmount) {
+                break;
+            }
+        }
+        return selected;
+    }
+    /**
+     * Calculates the total value of UTXOs
+     * @param utxos - Array of UTXOs
+     * @returns Total value in satoshis
+     */
+    calculateUTXOTotal(utxos) {
+        return utxos.reduce((total, utxo) => total + utxo.value, 0);
+    }
+    /**
+     * Validates and ensures sufficient funds for the transaction
+     * @param selectedUTXOs - Initially selected UTXOs
+     * @param allUTXOs - All available UTXOs
+     * @param selectedTotal - Total value of selected UTXOs
+     * @param amountInSatoshisNumber - Transaction amount
+     * @param feeEstimate - Estimated fee
+     * @returns Validated selected UTXOs
+     * @throws {DynamicError} If insufficient funds
+     */
+    validateAndSelectUTXOs(selectedUTXOs, allUTXOs, selectedTotal, amountInSatoshisNumber, feeEstimate) {
+        const requiredAmount = amountInSatoshisNumber + feeEstimate;
+        if (selectedTotal >= requiredAmount) {
+            return selectedUTXOs;
+        }
+        // Try with all UTXOs if selection wasn't enough
+        if (selectedUTXOs.length < allUTXOs.length) {
+            const allTotal = this.calculateUTXOTotal(allUTXOs);
+            if (allTotal < requiredAmount) {
+                throw new utils.DynamicError(`Insufficient funds. Available: ${allTotal / _const.SATOSHIS_PER_BTC} BTC (${allTotal} satoshis), Required: ${amountInSatoshisNumber / _const.SATOSHIS_PER_BTC} BTC (${amountInSatoshisNumber} satoshis) + fees`);
+            }
+            return allUTXOs;
+        }
+        throw new utils.DynamicError(`Insufficient funds. Available: ${selectedTotal / _const.SATOSHIS_PER_BTC} BTC (${selectedTotal} satoshis), Required: ${amountInSatoshisNumber / _const.SATOSHIS_PER_BTC} BTC (${amountInSatoshisNumber} satoshis) + fees`);
+    }
+    /**
+     * Calculates fee estimate and change amount, handling dust limit
+     * @param accountAddress - Account address for fee estimation
+     * @param selectedUTXOs - Selected UTXOs
+     * @param selectedTotalValue - Total value of selected UTXOs
+     * @param amountInSatoshis - Transaction amount
+     * @param feePriority - Fee priority level
+     * @returns Object with feeEstimate, changeAmount, changeAmountNumber, and hasChangeOutput
+     */
+    calculateFeeAndChange(accountAddress, selectedUTXOs, selectedTotalValue, amountInSatoshis, feePriority) {
+        return _tslib.__awaiter(this, void 0, void 0, function* () {
+            // Re-estimate fee with actual number of inputs
+            let feeEstimate = yield this.mempoolApiService.estimateTransactionFee(accountAddress, selectedUTXOs.length, 1, // Start with 1 output (recipient only)
+            feePriority);
+            let maxToSpend = selectedTotalValue - feeEstimate;
+            let changeAmount = BigInt(maxToSpend) - amountInSatoshis;
+            // If change will be above dust limit, re-estimate fees for 2 outputs
+            const changeAmountNumber = Number(changeAmount);
+            if (changeAmount > 0 && changeAmountNumber >= _const.DUST_LIMIT) {
+                feeEstimate = yield this.mempoolApiService.estimateTransactionFee(accountAddress, selectedUTXOs.length, 2, // recipient + change output
+                feePriority);
+                maxToSpend = selectedTotalValue - feeEstimate;
+                changeAmount = BigInt(maxToSpend) - amountInSatoshis;
+            }
+            const finalChangeAmountNumber = Number(changeAmount);
+            const hasChangeOutput = changeAmount > 0 && finalChangeAmountNumber >= _const.DUST_LIMIT;
+            // Final fee adjustment: if change < dust limit, add it to fee
+            if (changeAmount > 0 && finalChangeAmountNumber < _const.DUST_LIMIT) {
+                feeEstimate += finalChangeAmountNumber;
+            }
+            return {
+                changeAmount,
+                changeAmountNumber: finalChangeAmountNumber,
+                feeEstimate,
+                hasChangeOutput,
+            };
+        });
+    }
+    /**
+     * Adds inputs to PSBT from selected UTXOs
+     * @param psbt - PSBT to add inputs to
+     * @param selectedUTXOs - Selected UTXOs
+     * @param publicKeyPair - ECPair public key pair
+     * @param network - Bitcoin network
+     */
+    addInputsToPsbt(psbt, selectedUTXOs, publicKeyPair, network) {
+        for (const utxo of selectedUTXOs) {
+            const outputScript = bitcoinjsLib.payments.p2wpkh({
+                network,
+                pubkey: publicKeyPair.publicKey,
+            }).output;
+            if (!outputScript) {
+                throw new utils.DynamicError('Failed to create segwit output script');
+            }
+            // Convert txid from hex string to Buffer and reverse it (Bitcoin uses little-endian)
+            // The txid from the API is in big-endian format, but bitcoinjs-lib expects little-endian
+            const txidBuffer = Buffer.from(utxo.txid, 'hex').reverse();
+            psbt.addInput({
+                hash: txidBuffer,
+                index: utxo.vout,
+                sequence: _const.RBF_SEQUENCE, // Enable RBF (Replace-By-Fee)
+                witnessUtxo: {
+                    script: outputScript,
+                    value: utxo.value,
+                },
+            });
+        }
+    }
+    /**
+     * Adds outputs to PSBT (recipient and optionally change)
+     * @param psbt - PSBT to add outputs to
+     * @param recipientAddress - Recipient address
+     * @param accountAddress - Account address for change
+     * @param amountInSatoshisNumber - Transaction amount
+     * @param changeAmountNumber - Change amount
+     * @param hasChangeOutput - Whether to include change output
+     * @param network - Bitcoin network
+     */
+    addOutputsToPsbt(psbt, recipientAddress, accountAddress, amountInSatoshisNumber, changeAmountNumber, hasChangeOutput, network) {
+        if (amountInSatoshisNumber < _const.DUST_LIMIT) {
+            throw new utils.DynamicError(`Amount is below dust limit of ${_const.DUST_LIMIT} satoshis (${_const.DUST_LIMIT / _const.SATOSHIS_PER_BTC} BTC)`);
+        }
+        psbt.addOutput({
+            script: bitcoinjsLib.address.toOutputScript(recipientAddress, network),
+            value: amountInSatoshisNumber,
+        });
+        if (hasChangeOutput) {
+            psbt.addOutput({
+                script: bitcoinjsLib.address.toOutputScript(accountAddress, network),
+                value: changeAmountNumber,
+            });
+        }
+    }
     /**
      * Builds a PSBT for a Bitcoin transaction with real UTXOs
+     * Uses Largest-First UTXO selection strategy with accurate vSize fee estimation
      * @param options - Options for building the PSBT
      * @returns A PSBT in Base64 format
      * @throws {DynamicError} If insufficient funds, no UTXOs, or other errors
      */
     buildPsbt(options) {
         return _tslib.__awaiter(this, void 0, void 0, function* () {
-            const { accountAddress, recipientAddress, amountInSatoshis, publicKeyHex, network, } = options;
+            const { accountAddress, recipientAddress, amountInSatoshis, publicKeyHex, network, feePriority = 'medium', } = options;
+            logger.debug(`buildPsbt called with feePriority: ${feePriority}, amount: ${amountInSatoshis} satoshis`);
             if (amountInSatoshis <= BigInt(0)) {
                 throw new utils.DynamicError('Amount must be greater than 0');
             }
-            // Get UTXOs for the account address
-            const utxos = yield this.mempoolApiService.getUTXOs(accountAddress);
-            if (utxos.length === 0) {
+            const allUTXOs = yield this.mempoolApiService.getUTXOs(accountAddress);
+            if (allUTXOs.length === 0) {
                 throw new utils.DynamicError('No UTXOs found for this address');
             }
-            // Get public key for creating output scripts
+            const utxos = this.filterTaprootUTXOs(accountAddress, allUTXOs);
             const publicKeyBuffer = Buffer.from(publicKeyHex, 'hex');
-            // Use ECPair to ensure the public key is properly formatted for bitcoinjs-lib
             const ECPair = ecpair.ECPairFactory(ecc__default["default"]);
             const publicKeyPair = ECPair.fromPublicKey(publicKeyBuffer, {
                 compressed: true,
             });
-            // Calculate total available
-            const totalToSpend = utxos.reduce((total, utxo) => total + utxo.value, 0);
-            // Initial fee estimate with 1 output (recipient only)
-            let feeEstimate = yield this.mempoolApiService.estimateTransactionFee(accountAddress, utxos.length, 1);
-            // Calculate change amount with 1-output fee estimate
-            let maxToSpend = totalToSpend - feeEstimate;
-            let changeAmount = BigInt(maxToSpend) - amountInSatoshis;
-            // If change will be above dust limit, re-estimate fees for 2 outputs
-            if (changeAmount > 0 && Number(changeAmount) >= _const.DUST_LIMIT) {
-                feeEstimate = yield this.mempoolApiService.estimateTransactionFee(accountAddress, utxos.length, 2);
-                maxToSpend = totalToSpend - feeEstimate;
-                changeAmount = BigInt(maxToSpend) - amountInSatoshis;
-            }
-            if (maxToSpend < Number(amountInSatoshis)) {
-                const amountInSatoshisNumber = Number(amountInSatoshis);
+            const amountInSatoshisNumber = Number(amountInSatoshis);
+            // Initial fee estimate with 1 input and 1 output
+            const initialFeeEstimate = yield this.mempoolApiService.estimateTransactionFee(accountAddress, 1, 1, feePriority);
+            // Target amount: transaction amount + fee + dust limit (for change output safety)
+            const targetAmount = amountInSatoshisNumber + initialFeeEstimate + _const.DUST_LIMIT;
+            // Select UTXOs using Largest-First strategy
+            let selectedUTXOs = this.selectUTXOsLargestFirst(utxos, targetAmount);
+            const selectedTotal = this.calculateUTXOTotal(selectedUTXOs);
+            // Validate and ensure sufficient funds
+            selectedUTXOs = this.validateAndSelectUTXOs(selectedUTXOs, utxos, selectedTotal, amountInSatoshisNumber, initialFeeEstimate);
+            const selectedTotalValue = this.calculateUTXOTotal(selectedUTXOs);
+            // Calculate fee and change with proper dust limit handling
+            const { feeEstimate, changeAmountNumber, hasChangeOutput } = yield this.calculateFeeAndChange(accountAddress, selectedUTXOs, selectedTotalValue, amountInSatoshis, feePriority);
+            // Final check: ensure we have enough after final fee calculation
+            const maxToSpend = selectedTotalValue - feeEstimate;
+            if (maxToSpend < amountInSatoshisNumber) {
                 throw new utils.DynamicError(`Insufficient funds. Available: ${maxToSpend / _const.SATOSHIS_PER_BTC} BTC (${maxToSpend} satoshis), Required: ${amountInSatoshisNumber / _const.SATOSHIS_PER_BTC} BTC (${amountInSatoshisNumber} satoshis)`);
             }
-            // Create PSBT
+            // Create PSBT and add inputs/outputs
             const psbt = new bitcoinjsLib.Psbt({ network });
-            // Add inputs from UTXOs (only supporting native SegWit P2WPKH)
-            for (const utxo of utxos) {
-                // SegWit (P2WPKH) addresses
-                // For SegWit, we need the public key to construct the witness output script
-                const outputScript = bitcoinjsLib.payments.p2wpkh({
-                    network,
-                    pubkey: publicKeyPair.publicKey,
-                }).output;
-                if (!outputScript) {
-                    throw new utils.DynamicError('Failed to create segwit output script');
-                }
-                // Convert txid from hex string to Buffer and reverse it (Bitcoin uses little-endian)
-                // The txid from the API is in big-endian format, but bitcoinjs-lib expects little-endian
-                const txidBuffer = Buffer.from(utxo.txid, 'hex').reverse();
-                psbt.addInput({
-                    hash: txidBuffer,
-                    index: utxo.vout,
-                    witnessUtxo: {
-                        script: outputScript,
-                        value: utxo.value,
-                    },
-                });
-            }
-            // Add recipient output
-            const amountInSatoshisNumber = Number(amountInSatoshis);
-            if (amountInSatoshisNumber < _const.DUST_LIMIT) {
-                throw new utils.DynamicError(`Amount is below dust limit of ${_const.DUST_LIMIT} satoshis (${_const.DUST_LIMIT / _const.SATOSHIS_PER_BTC} BTC)`);
-            }
-            psbt.addOutput({
-                script: bitcoinjsLib.address.toOutputScript(recipientAddress, network),
-                value: amountInSatoshisNumber,
-            });
-            // Add change output if needed
-            const changeAmountNumber = Number(changeAmount);
-            if (changeAmount > 0 && changeAmountNumber >= _const.DUST_LIMIT) {
-                psbt.addOutput({
-                    script: bitcoinjsLib.address.toOutputScript(accountAddress, network),
-                    value: changeAmountNumber,
-                });
-            }
-            logger.debug(`buildPsbt created PSBT for recipientAddress: ${recipientAddress}, amount: ${amountInSatoshisNumber} satoshis (${amountInSatoshisNumber / _const.SATOSHIS_PER_BTC} BTC), change: ${changeAmountNumber} satoshis`);
+            this.addInputsToPsbt(psbt, selectedUTXOs, publicKeyPair, network);
+            this.addOutputsToPsbt(psbt, recipientAddress, accountAddress, amountInSatoshisNumber, changeAmountNumber, hasChangeOutput, network);
+            logger.debug(`buildPsbt created PSBT for recipientAddress: ${recipientAddress}, amount: ${amountInSatoshisNumber} satoshis (${amountInSatoshisNumber / _const.SATOSHIS_PER_BTC} BTC), change: ${changeAmountNumber} satoshis, estimated fee: ${feeEstimate} satoshis, feePriority: ${feePriority}, inputs: ${selectedUTXOs.length}`);
             return psbt.toBase64();
         });
     }
     /**
      * Helper method to create BuildPsbtOptions from transaction and account details
      * @param accountAddress - The account address
-     * @param transaction - The Bitcoin transaction
+     * @param transaction - The Bitcoin transaction (must have amount and recipientAddress)
      * @param publicKeyHex - The public key in hex format
+     * @param feePriority - Optional fee priority (defaults to 'medium')
      * @returns BuildPsbtOptions
      */
-    static createBuildOptions(accountAddress, transaction, publicKeyHex) {
+    static createBuildOptions(accountAddress, transaction, publicKeyHex, feePriority = 'medium') {
         return {
             accountAddress,
             amountInSatoshis: transaction.amount,
+            feePriority,
             network: getBitcoinNetwork.getBitcoinNetwork(accountAddress),
             publicKeyHex,
             recipientAddress: transaction.recipientAddress,

package/src/services/PsbtBuilderService.d.ts

@@ -6,8 +6,71 @@ import { MempoolApiService } from './MempoolApiService';
 export declare class PsbtBuilderService {
     private mempoolApiService;
     constructor(mempoolApiService: MempoolApiService);
+    /**
+     * Filters out Taproot (P2TR) UTXOs to prevent accidental spending of Ordinals/Runes
+     * Since we only support Native SegWit (P2WPKH), we ensure the account address is not Taproot
+     * @param accountAddress - The account address to check
+     * @param utxos - Array of UTXOs to filter
+     * @returns Filtered array of UTXOs (only P2WPKH compatible)
+     */
+    private filterTaprootUTXOs;
+    /**
+     * Selects UTXOs using Largest-First (Accumulator) strategy
+     * Sorts UTXOs by value (descending) and selects until we have enough to cover amount + fees
+     * @param utxos - Available UTXOs
+     * @param targetAmount - Target amount including fees and dust limit
+     * @returns Selected UTXOs
+     */
+    private selectUTXOsLargestFirst;
+    /**
+     * Calculates the total value of UTXOs
+     * @param utxos - Array of UTXOs
+     * @returns Total value in satoshis
+     */
+    private calculateUTXOTotal;
+    /**
+     * Validates and ensures sufficient funds for the transaction
+     * @param selectedUTXOs - Initially selected UTXOs
+     * @param allUTXOs - All available UTXOs
+     * @param selectedTotal - Total value of selected UTXOs
+     * @param amountInSatoshisNumber - Transaction amount
+     * @param feeEstimate - Estimated fee
+     * @returns Validated selected UTXOs
+     * @throws {DynamicError} If insufficient funds
+     */
+    private validateAndSelectUTXOs;
+    /**
+     * Calculates fee estimate and change amount, handling dust limit
+     * @param accountAddress - Account address for fee estimation
+     * @param selectedUTXOs - Selected UTXOs
+     * @param selectedTotalValue - Total value of selected UTXOs
+     * @param amountInSatoshis - Transaction amount
+     * @param feePriority - Fee priority level
+     * @returns Object with feeEstimate, changeAmount, changeAmountNumber, and hasChangeOutput
+     */
+    private calculateFeeAndChange;
+    /**
+     * Adds inputs to PSBT from selected UTXOs
+     * @param psbt - PSBT to add inputs to
+     * @param selectedUTXOs - Selected UTXOs
+     * @param publicKeyPair - ECPair public key pair
+     * @param network - Bitcoin network
+     */
+    private addInputsToPsbt;
+    /**
+     * Adds outputs to PSBT (recipient and optionally change)
+     * @param psbt - PSBT to add outputs to
+     * @param recipientAddress - Recipient address
+     * @param accountAddress - Account address for change
+     * @param amountInSatoshisNumber - Transaction amount
+     * @param changeAmountNumber - Change amount
+     * @param hasChangeOutput - Whether to include change output
+     * @param network - Bitcoin network
+     */
+    private addOutputsToPsbt;
     /**
      * Builds a PSBT for a Bitcoin transaction with real UTXOs
+     * Uses Largest-First UTXO selection strategy with accurate vSize fee estimation
      * @param options - Options for building the PSBT
      * @returns A PSBT in Base64 format
      * @throws {DynamicError} If insufficient funds, no UTXOs, or other errors
@@ -16,12 +79,13 @@ export declare class PsbtBuilderService {
     /**
      * Helper method to create BuildPsbtOptions from transaction and account details
      * @param accountAddress - The account address
-     * @param transaction - The Bitcoin transaction
+     * @param transaction - The Bitcoin transaction (must have amount and recipientAddress)
      * @param publicKeyHex - The public key in hex format
+     * @param feePriority - Optional fee priority (defaults to 'medium')
      * @returns BuildPsbtOptions
      */
     static createBuildOptions(accountAddress: string, transaction: {
         amount: bigint;
         recipientAddress: string;
-    }, publicKeyHex: string): BuildPsbtOptions;
+    }, publicKeyHex: string, feePriority?: 'high' | 'medium' | 'low'): BuildPsbtOptions;
 }