@flashnet/sdk 0.5.5 → 0.5.7

package/dist/esm/src/client/FlashnetClient.js

@@ -1,4 +1,5 @@
 import sha256 from 'fast-sha256';
+import { decode } from 'light-bolt11-decoder';
 import { ApiClient } from '../api/client.js';
 import { TypedAmmApi } from '../api/typed-endpoints.js';
 import { getClientEnvironmentName, resolveClientNetworkConfig, getClientNetworkConfig, BTC_ASSET_PUBKEY } from '../config/index.js';
@@ -240,8 +241,10 @@ class FlashnetClient {
                 const tokenIdentifierHex = getHexFromUint8Array(info.rawTokenIdentifier);
                 const tokenAddress = encodeSparkHumanReadableTokenIdentifier(info.rawTokenIdentifier, this.sparkNetwork);
                 tokenBalances.set(tokenPubkey, {
-                    balance: FlashnetClient.safeBigInt(tokenData.ownedBalance),
-                    availableToSendBalance: FlashnetClient.safeBigInt(tokenData.availableToSendBalance),
+                    balance: safeBigInt(tokenData.ownedBalance ?? tokenData.balance),
+                    availableToSendBalance: safeBigInt(tokenData.availableToSendBalance ??
+                        tokenData.ownedBalance ??
+                        tokenData.balance),
                     tokenInfo: {
                         tokenIdentifier: tokenIdentifierHex,
                         tokenAddress,
@@ -254,7 +257,7 @@ class FlashnetClient {
             }
         }
         return {
-            balance: FlashnetClient.safeBigInt(balance.balance),
+            balance: safeBigInt(balance.balance),
             tokenBalances,
         };
     }
@@ -269,10 +272,10 @@ class FlashnetClient {
         };
         for (const balance of params.balancesToCheck) {
             if (balance.assetAddress === BTC_ASSET_PUBKEY) {
-                requirements.btc = FlashnetClient.safeBigInt(balance.amount);
+                requirements.btc = BigInt(balance.amount);
             }
             else {
-                requirements.tokens?.set(balance.assetAddress, FlashnetClient.safeBigInt(balance.amount));
+                requirements.tokens?.set(balance.assetAddress, BigInt(balance.amount));
             }
         }
         // Check BTC balance
@@ -286,10 +289,12 @@ class FlashnetClient {
         // Check token balances
         if (requirements.tokens) {
             for (const [tokenPubkey, requiredAmount,] of requirements.tokens.entries()) {
-                // If direct lookup fails (possible representation mismatch), try the human-readable form
+                // Support both hex and Bech32m token identifiers by trying all representations
                 const hrKey = this.toHumanReadableTokenIdentifier(tokenPubkey);
+                const hexKey = this.toHexTokenIdentifier(tokenPubkey);
                 const effectiveTokenBalance = balance.tokenBalances.get(tokenPubkey) ??
-                    balance.tokenBalances.get(hrKey);
+                    balance.tokenBalances.get(hrKey) ??
+                    balance.tokenBalances.get(hexKey);
                 const available = params.useAvailableBalance
                     ? (effectiveTokenBalance?.availableToSendBalance ?? 0n)
                     : (effectiveTokenBalance?.balance ?? 0n);
@@ -414,12 +419,6 @@ class FlashnetClient {
             throw new Error(`${name} must be positive integer`);
         }
     }
-    /**
-     * Safely convert a value to BigInt. Delegates to the shared `safeBigInt` utility.
-     */
-    static safeBigInt(value, fallback = 0n) {
-        return safeBigInt(value, fallback);
-    }
     /**
      * Calculates virtual reserves for a bonding curve AMM.
      *
@@ -440,7 +439,7 @@ class FlashnetClient {
         }
         const supply = FlashnetClient.parsePositiveIntegerToBigInt(params.initialTokenSupply, "Initial token supply");
         const targetB = FlashnetClient.parsePositiveIntegerToBigInt(params.targetRaise, "Target raise");
-        const graduationThresholdPct = FlashnetClient.safeBigInt(params.graduationThresholdPct);
+        const graduationThresholdPct = BigInt(params.graduationThresholdPct);
         // Align bounds with Rust AMM (20%..95%), then check feasibility for g=1 (requires >50%).
         const MIN_PCT = 20n;
         const MAX_PCT = 95n;
@@ -1755,7 +1754,7 @@ class FlashnetClient {
             else {
                 const transferId = await this._wallet.transferTokens({
                     tokenIdentifier: this.toHumanReadableTokenIdentifier(recipient.assetAddress),
-                    tokenAmount: FlashnetClient.safeBigInt(recipient.amount),
+                    tokenAmount: BigInt(recipient.amount),
                     receiverSparkAddress: recipient.receiverSparkAddress,
                 });
                 transferIds.push(transferId);
@@ -1862,8 +1861,7 @@ class FlashnetClient {
         const lightningFeeEstimate = await this.getLightningFeeEstimate(invoice);
         // Total BTC needed = invoice amount + lightning fee (unmasked).
         // Bitmasking for V2 pools is handled inside findBestPoolForTokenToBtc.
-        const baseBtcNeeded = FlashnetClient.safeBigInt(invoiceAmountSats) +
-            FlashnetClient.safeBigInt(lightningFeeEstimate);
+        const baseBtcNeeded = BigInt(invoiceAmountSats) + BigInt(lightningFeeEstimate);
         // Check Flashnet minimum amounts early to provide clear error messages
         const minAmounts = await this.getEnabledMinAmountsMap();
         // Check BTC minimum (output from swap)
@@ -1890,7 +1888,7 @@ class FlashnetClient {
         const tokenHex = this.toHexTokenIdentifier(tokenAddress).toLowerCase();
         const tokenMinAmount = minAmounts.get(tokenHex);
         if (tokenMinAmount &&
-            FlashnetClient.safeBigInt(poolQuote.tokenAmountRequired) < tokenMinAmount) {
+            safeBigInt(poolQuote.tokenAmountRequired) < tokenMinAmount) {
             const msg = `Token amount too small. Minimum input is ${tokenMinAmount} units, but calculated amount is only ${poolQuote.tokenAmountRequired} units.`;
             throw new FlashnetError(msg, {
                 response: {
@@ -1907,7 +1905,7 @@ class FlashnetClient {
         }
         // BTC variable fee adjustment: difference between what the pool targets and unmasked base.
         // For V3 pools this is 0 (no masking). For V2 it's the rounding overhead.
-        const btcVariableFeeAdjustment = Number(FlashnetClient.safeBigInt(poolQuote.btcAmountUsed) - baseBtcNeeded);
+        const btcVariableFeeAdjustment = Number(safeBigInt(poolQuote.btcAmountUsed) - baseBtcNeeded);
         return {
             poolId: poolQuote.poolId,
             tokenAddress: this.toHexTokenIdentifier(tokenAddress),
@@ -1979,7 +1977,7 @@ class FlashnetClient {
                     amountIn: tokenAmount,
                     integratorBps: options?.integratorFeeRateBps,
                 });
-                const btcOut = FlashnetClient.safeBigInt(simulation.amountOut);
+                const btcOut = safeBigInt(simulation.amountOut);
                 if (btcOut > bestBtcOut) {
                     bestBtcOut = btcOut;
                     bestResult = {
@@ -2095,8 +2093,16 @@ class FlashnetClient {
             const assetOutAddress = quote.tokenIsAssetA
                 ? pool.assetBAddress
                 : pool.assetAAddress;
-            // Calculate min amount out with slippage protection
-            const minBtcOut = this.calculateMinAmountOut(quote.btcAmountRequired, maxSlippageBps);
+            const effectiveMaxLightningFee = maxLightningFeeSats ?? quote.estimatedLightningFee;
+            // Floor minAmountOut at invoiceAmount + fee so the swap never returns
+            // less BTC than the lightning payment requires.
+            const slippageMin = this.calculateMinAmountOut(quote.btcAmountRequired, maxSlippageBps);
+            const baseBtcNeeded = !quote.isZeroAmountInvoice
+                ? BigInt(quote.invoiceAmountSats) + BigInt(effectiveMaxLightningFee)
+                : 0n;
+            const minBtcOut = BigInt(slippageMin) >= baseBtcNeeded
+                ? slippageMin
+                : baseBtcNeeded.toString();
             // Execute the swap
             const swapResponse = await this.executeSwap({
                 poolId: quote.poolId,
@@ -2121,139 +2127,158 @@ class FlashnetClient {
                     error: swapResponse.error || "Swap was not accepted",
                 };
             }
-            // Step 5: Wait for transfer (skip useExistingBtcBalance for zero-amount invoices)
-            let canPayImmediately = false;
-            if (!quote.isZeroAmountInvoice && useExistingBtcBalance) {
-                const invoiceAmountSats = await this.decodeInvoiceAmount(invoice);
-                const effectiveMaxLightningFee = maxLightningFeeSats ?? quote.estimatedLightningFee;
-                const btcNeededForPayment = invoiceAmountSats + effectiveMaxLightningFee;
-                const balance = await this.getBalance();
-                canPayImmediately =
-                    balance.balance >= FlashnetClient.safeBigInt(btcNeededForPayment);
-            }
-            if (!canPayImmediately) {
-                const transferComplete = await this.waitForTransferCompletion(swapResponse.outboundTransferId, transferTimeoutMs);
-                if (!transferComplete) {
-                    return {
-                        success: false,
-                        poolId: quote.poolId,
-                        tokenAmountSpent: quote.tokenAmountRequired,
-                        btcAmountReceived: swapResponse.amountOut || "0",
-                        swapTransferId: swapResponse.outboundTransferId,
-                        ammFeePaid: quote.estimatedAmmFee,
-                        sparkTokenTransferId: swapResponse.inboundSparkTransferId,
-                        error: "Transfer did not complete within timeout",
-                    };
-                }
-            }
-            // Step 6: Calculate Lightning fee and payment amount
-            const effectiveMaxLightningFee = maxLightningFeeSats ?? quote.estimatedLightningFee;
-            const btcReceived = swapResponse.amountOut || quote.btcAmountRequired;
-            // Step 7: Pay the Lightning invoice
+            // Step 5: Claim the swap output and refresh wallet state.
+            // Suppress leaf optimization for the entire claim-to-pay window so
+            // the SSP cannot swap away the leaves we need for lightning payment.
+            const restoreOptimization = this.suppressOptimization();
             try {
-                let lightningPayment;
-                let invoiceAmountPaid;
-                if (quote.isZeroAmountInvoice) {
-                    // Zero-amount invoice: pay whatever BTC we received minus lightning fee
-                    const actualBtc = FlashnetClient.safeBigInt(btcReceived);
-                    const lnFee = FlashnetClient.safeBigInt(effectiveMaxLightningFee);
-                    const amountToPay = actualBtc - lnFee;
-                    if (amountToPay <= 0n) {
+                let canPayImmediately = false;
+                if (!quote.isZeroAmountInvoice && useExistingBtcBalance) {
+                    const invoiceAmountSats = await this.decodeInvoiceAmount(invoice);
+                    const btcNeededForPayment = invoiceAmountSats + effectiveMaxLightningFee;
+                    const balance = await this.getBalance();
+                    canPayImmediately =
+                        balance.balance >= safeBigInt(btcNeededForPayment);
+                }
+                if (!canPayImmediately) {
+                    const claimed = await this.instaClaimTransfer(swapResponse.outboundTransferId, transferTimeoutMs);
+                    if (!claimed) {
                         return {
                             success: false,
                             poolId: quote.poolId,
                             tokenAmountSpent: quote.tokenAmountRequired,
-                            btcAmountReceived: btcReceived,
+                            btcAmountReceived: swapResponse.amountOut || "0",
                             swapTransferId: swapResponse.outboundTransferId,
                             ammFeePaid: quote.estimatedAmmFee,
                             sparkTokenTransferId: swapResponse.inboundSparkTransferId,
-                            error: `BTC received (${btcReceived} sats) is not enough to cover lightning fee (${effectiveMaxLightningFee} sats).`,
+                            error: "Transfer did not complete within timeout",
                         };
                     }
-                    invoiceAmountPaid = Number(amountToPay);
-                    lightningPayment = await this._wallet.payLightningInvoice({
-                        invoice,
-                        amountSats: invoiceAmountPaid,
-                        maxFeeSats: effectiveMaxLightningFee,
-                        preferSpark,
-                    });
                 }
-                else {
-                    // Standard invoice: pay the specified amount
-                    lightningPayment = await this._wallet.payLightningInvoice({
-                        invoice,
-                        maxFeeSats: effectiveMaxLightningFee,
-                        preferSpark,
-                    });
+                // Step 6: Calculate payment amount
+                const requestedMaxLightningFee = effectiveMaxLightningFee;
+                const btcReceived = swapResponse.amountOut || quote.btcAmountRequired;
+                // Cap the lightning fee budget to what the wallet can actually cover.
+                // The swap output may be slightly less than quoted due to rounding or
+                // price movement between quote and execution. The Spark SDK requires
+                // invoiceAmount + maxFeeSats <= balance, so we adjust maxFeeSats down
+                // when the actual BTC received is less than expected.
+                let cappedMaxLightningFee = requestedMaxLightningFee;
+                if (!quote.isZeroAmountInvoice) {
+                    const actualBtc = safeBigInt(btcReceived);
+                    const invoiceAmount = safeBigInt(quote.invoiceAmountSats);
+                    const available = actualBtc - invoiceAmount;
+                    if (available > 0n && available < safeBigInt(cappedMaxLightningFee)) {
+                        cappedMaxLightningFee = Number(available);
+                    }
                 }
-                // Extract the Spark transfer ID from the lightning payment result.
-                // payLightningInvoice returns LightningSendRequest | WalletTransfer:
-                //   - LightningSendRequest has .transfer?.sparkId (the Sparkscan-visible transfer ID)
-                //   - WalletTransfer (Spark-to-Spark) has .id directly as the transfer ID
-                // Note: lightningPayment.id (the SSP request ID) is already returned as lightningPaymentId
-                const sparkLightningTransferId = lightningPayment.transfer?.sparkId;
-                return {
-                    success: true,
-                    poolId: quote.poolId,
-                    tokenAmountSpent: quote.tokenAmountRequired,
-                    btcAmountReceived: btcReceived,
-                    swapTransferId: swapResponse.outboundTransferId,
-                    lightningPaymentId: lightningPayment.id,
-                    ammFeePaid: quote.estimatedAmmFee,
-                    lightningFeePaid: effectiveMaxLightningFee,
-                    invoiceAmountPaid,
-                    sparkTokenTransferId: swapResponse.inboundSparkTransferId,
-                    sparkLightningTransferId,
-                };
-            }
-            catch (lightningError) {
-                // Lightning payment failed after swap succeeded
-                const lightningErrorMessage = lightningError instanceof Error
-                    ? lightningError.message
-                    : String(lightningError);
-                // Attempt rollback if requested
-                if (rollbackOnFailure) {
-                    try {
-                        const rollbackResult = await this.rollbackSwap(quote.poolId, btcReceived, tokenAddress, maxSlippageBps);
-                        if (rollbackResult.success) {
+                // Step 7: Pay the Lightning invoice
+                try {
+                    let lightningPayment;
+                    let invoiceAmountPaid;
+                    if (quote.isZeroAmountInvoice) {
+                        const actualBtc = safeBigInt(btcReceived);
+                        const lnFee = safeBigInt(cappedMaxLightningFee);
+                        const amountToPay = actualBtc - lnFee;
+                        if (amountToPay <= 0n) {
                             return {
                                 success: false,
                                 poolId: quote.poolId,
-                                tokenAmountSpent: "0", // Rolled back
-                                btcAmountReceived: "0",
+                                tokenAmountSpent: quote.tokenAmountRequired,
+                                btcAmountReceived: btcReceived,
                                 swapTransferId: swapResponse.outboundTransferId,
                                 ammFeePaid: quote.estimatedAmmFee,
                                 sparkTokenTransferId: swapResponse.inboundSparkTransferId,
-                                error: `Lightning payment failed: ${lightningErrorMessage}. Funds rolled back to ${rollbackResult.tokenAmount} tokens.`,
+                                error: `BTC received (${btcReceived} sats) is not enough to cover lightning fee (${cappedMaxLightningFee} sats).`,
                             };
                         }
+                        invoiceAmountPaid = Number(amountToPay);
+                        lightningPayment = await this._wallet.payLightningInvoice({
+                            invoice,
+                            amountSats: invoiceAmountPaid,
+                            maxFeeSats: cappedMaxLightningFee,
+                            preferSpark,
+                        });
                     }
-                    catch (rollbackError) {
-                        const rollbackErrorMessage = rollbackError instanceof Error
-                            ? rollbackError.message
-                            : String(rollbackError);
-                        return {
-                            success: false,
-                            poolId: quote.poolId,
-                            tokenAmountSpent: quote.tokenAmountRequired,
-                            btcAmountReceived: btcReceived,
-                            swapTransferId: swapResponse.outboundTransferId,
-                            ammFeePaid: quote.estimatedAmmFee,
-                            sparkTokenTransferId: swapResponse.inboundSparkTransferId,
-                            error: `Lightning payment failed: ${lightningErrorMessage}. Rollback also failed: ${rollbackErrorMessage}. BTC remains in wallet.`,
-                        };
+                    else {
+                        lightningPayment = await this._wallet.payLightningInvoice({
+                            invoice,
+                            maxFeeSats: cappedMaxLightningFee,
+                            preferSpark,
+                        });
                     }
+                    // Extract the Spark transfer ID from the lightning payment result.
+                    // payLightningInvoice returns LightningSendRequest | WalletTransfer:
+                    //   - LightningSendRequest has .transfer?.sparkId (the Sparkscan-visible transfer ID)
+                    //   - WalletTransfer (Spark-to-Spark) has .id directly as the transfer ID
+                    // Note: lightningPayment.id (the SSP request ID) is already returned as lightningPaymentId
+                    const sparkLightningTransferId = lightningPayment.transfer?.sparkId;
+                    return {
+                        success: true,
+                        poolId: quote.poolId,
+                        tokenAmountSpent: quote.tokenAmountRequired,
+                        btcAmountReceived: btcReceived,
+                        swapTransferId: swapResponse.outboundTransferId,
+                        lightningPaymentId: lightningPayment.id,
+                        ammFeePaid: quote.estimatedAmmFee,
+                        lightningFeePaid: cappedMaxLightningFee,
+                        invoiceAmountPaid,
+                        sparkTokenTransferId: swapResponse.inboundSparkTransferId,
+                        sparkLightningTransferId,
+                    };
                 }
-                return {
-                    success: false,
-                    poolId: quote.poolId,
-                    tokenAmountSpent: quote.tokenAmountRequired,
-                    btcAmountReceived: btcReceived,
-                    swapTransferId: swapResponse.outboundTransferId,
-                    ammFeePaid: quote.estimatedAmmFee,
-                    sparkTokenTransferId: swapResponse.inboundSparkTransferId,
-                    error: `Lightning payment failed: ${lightningErrorMessage}. BTC (${btcReceived} sats) remains in wallet.`,
-                };
+                catch (lightningError) {
+                    // Lightning payment failed after swap succeeded
+                    const lightningErrorMessage = lightningError instanceof Error
+                        ? lightningError.message
+                        : String(lightningError);
+                    // Attempt rollback if requested
+                    if (rollbackOnFailure) {
+                        try {
+                            const rollbackResult = await this.rollbackSwap(quote.poolId, btcReceived, tokenAddress, maxSlippageBps);
+                            if (rollbackResult.success) {
+                                return {
+                                    success: false,
+                                    poolId: quote.poolId,
+                                    tokenAmountSpent: "0", // Rolled back
+                                    btcAmountReceived: "0",
+                                    swapTransferId: swapResponse.outboundTransferId,
+                                    ammFeePaid: quote.estimatedAmmFee,
+                                    sparkTokenTransferId: swapResponse.inboundSparkTransferId,
+                                    error: `Lightning payment failed: ${lightningErrorMessage}. Funds rolled back to ${rollbackResult.tokenAmount} tokens.`,
+                                };
+                            }
+                        }
+                        catch (rollbackError) {
+                            const rollbackErrorMessage = rollbackError instanceof Error
+                                ? rollbackError.message
+                                : String(rollbackError);
+                            return {
+                                success: false,
+                                poolId: quote.poolId,
+                                tokenAmountSpent: quote.tokenAmountRequired,
+                                btcAmountReceived: btcReceived,
+                                swapTransferId: swapResponse.outboundTransferId,
+                                ammFeePaid: quote.estimatedAmmFee,
+                                sparkTokenTransferId: swapResponse.inboundSparkTransferId,
+                                error: `Lightning payment failed: ${lightningErrorMessage}. Rollback also failed: ${rollbackErrorMessage}. BTC remains in wallet.`,
+                            };
+                        }
+                    }
+                    return {
+                        success: false,
+                        poolId: quote.poolId,
+                        tokenAmountSpent: quote.tokenAmountRequired,
+                        btcAmountReceived: btcReceived,
+                        swapTransferId: swapResponse.outboundTransferId,
+                        ammFeePaid: quote.estimatedAmmFee,
+                        sparkTokenTransferId: swapResponse.inboundSparkTransferId,
+                        error: `Lightning payment failed: ${lightningErrorMessage}. BTC (${btcReceived} sats) remains in wallet.`,
+                    };
+                }
+            }
+            finally {
+                restoreOptimization();
             }
         }
         catch (error) {
@@ -2414,7 +2439,7 @@ class FlashnetClient {
                         tokenIsAssetA: pool.tokenIsAssetA,
                         integratorBps: integratorFeeRateBps,
                     });
-                    tokenAmount = FlashnetClient.safeBigInt(v3Result.amountIn);
+                    tokenAmount = safeBigInt(v3Result.amountIn);
                     fee = v3Result.totalFee;
                     executionPrice = v3Result.simulation.executionPrice || "0";
                     priceImpactPct = v3Result.simulation.priceImpactPct || "0";
@@ -2423,7 +2448,7 @@ class FlashnetClient {
                 else {
                     // V2: constant product math + simulation verification
                     const calculation = this.calculateTokenAmountForBtcOutput(btcTarget.toString(), poolDetails.assetAReserve, poolDetails.assetBReserve, poolDetails.lpFeeBps, poolDetails.hostFeeBps, pool.tokenIsAssetA, integratorFeeRateBps);
-                    tokenAmount = FlashnetClient.safeBigInt(calculation.amountIn);
+                    tokenAmount = safeBigInt(calculation.amountIn);
                     // Verify with simulation
                     const simulation = await this.simulateSwap({
                         poolId: pool.lpPublicKey,
@@ -2432,7 +2457,7 @@ class FlashnetClient {
                         amountIn: calculation.amountIn,
                         integratorBps: integratorFeeRateBps,
                     });
-                    if (FlashnetClient.safeBigInt(simulation.amountOut) < btcTarget) {
+                    if (safeBigInt(simulation.amountOut) < btcTarget) {
                         const btcReserve = pool.tokenIsAssetA
                             ? poolDetails.assetBReserve
                             : poolDetails.assetAReserve;
@@ -2520,9 +2545,9 @@ class FlashnetClient {
      * @private
      */
     calculateTokenAmountForBtcOutput(btcAmountOut, reserveA, reserveB, lpFeeBps, hostFeeBps, tokenIsAssetA, integratorFeeBps) {
-        const amountOut = FlashnetClient.safeBigInt(btcAmountOut);
-        const resA = FlashnetClient.safeBigInt(reserveA);
-        const resB = FlashnetClient.safeBigInt(reserveB);
+        const amountOut = safeBigInt(btcAmountOut);
+        const resA = safeBigInt(reserveA);
+        const resB = safeBigInt(reserveB);
         const totalFeeBps = lpFeeBps + hostFeeBps + (integratorFeeBps || 0);
         const feeRate = Number(totalFeeBps) / 10000; // Convert bps to decimal
         // Token is the input asset
@@ -2620,7 +2645,7 @@ class FlashnetClient {
                 amountIn: upperBound.toString(),
                 integratorBps,
             });
-            if (FlashnetClient.safeBigInt(sim.amountOut) >= desiredBtcOut) {
+            if (safeBigInt(sim.amountOut) >= desiredBtcOut) {
                 upperSim = sim;
                 break;
             }
@@ -2631,7 +2656,7 @@ class FlashnetClient {
             throw new Error(`V3 pool ${poolId} has insufficient liquidity for ${desiredBtcOut} sats`);
         }
         // Step 3: Refine estimate via linear interpolation
-        const upperOut = FlashnetClient.safeBigInt(upperSim.amountOut);
+        const upperOut = safeBigInt(upperSim.amountOut);
         // Scale proportionally: if upperBound produced upperOut, we need roughly
         // (upperBound * desiredBtcOut / upperOut). Add +1 to avoid undershoot from truncation.
         let refined = (upperBound * desiredBtcOut) / upperOut + 1n;
@@ -2649,7 +2674,7 @@ class FlashnetClient {
                 amountIn: refined.toString(),
                 integratorBps,
             });
-            if (FlashnetClient.safeBigInt(refinedSim.amountOut) >= desiredBtcOut) {
+            if (safeBigInt(refinedSim.amountOut) >= desiredBtcOut) {
                 bestAmountIn = refined;
                 bestSim = refinedSim;
             }
@@ -2683,7 +2708,7 @@ class FlashnetClient {
                 amountIn: mid.toString(),
                 integratorBps,
             });
-            if (FlashnetClient.safeBigInt(midSim.amountOut) >= desiredBtcOut) {
+            if (safeBigInt(midSim.amountOut) >= desiredBtcOut) {
                 hi = mid;
                 bestAmountIn = mid;
                 bestSim = midSim;
@@ -2705,7 +2730,7 @@ class FlashnetClient {
      * @private
      */
     calculateMinAmountOut(expectedAmount, slippageBps) {
-        const amount = FlashnetClient.safeBigInt(expectedAmount);
+        const amount = BigInt(expectedAmount);
         const slippageFactor = BigInt(10000 - slippageBps);
         const minAmount = (amount * slippageFactor) / 10000n;
         return minAmount.toString();
@@ -2774,6 +2799,73 @@ class FlashnetClient {
         }
         return false;
     }
+    /**
+     * Suppress leaf optimization on the wallet. Sets the internal
+     * optimizationInProgress flag so optimizeLeaves() returns immediately.
+     * Returns a restore function that clears the flag.
+     * @private
+     */
+    suppressOptimization() {
+        const w = this._wallet;
+        const was = w.optimizationInProgress;
+        w.optimizationInProgress = true;
+        return () => {
+            w.optimizationInProgress = was;
+        };
+    }
+    /**
+     * Insta-claim: listen for the wallet's stream event that fires when
+     * the coordinator broadcasts the transfer. The stream auto-claims
+     * incoming transfers, so no polling is needed.
+     *
+     * After claim, refreshes the leaf cache from the coordinator to
+     * ensure the balance is current.
+     *
+     * Caller is responsible for suppressing optimization around this call
+     * if the claimed leaves must not be swapped before spending.
+     * @private
+     */
+    async instaClaimTransfer(transferId, timeoutMs) {
+        const w = this._wallet;
+        const claimed = await new Promise((resolve) => {
+            let done = false;
+            const finish = (value) => {
+                if (done) {
+                    return;
+                }
+                done = true;
+                clearTimeout(timer);
+                try {
+                    w.removeListener?.("transfer:claimed", handler);
+                }
+                catch {
+                    // Ignore
+                }
+                resolve(value);
+            };
+            const timer = setTimeout(() => finish(false), timeoutMs);
+            const handler = (claimedId) => {
+                if (claimedId === transferId) {
+                    finish(true);
+                }
+            };
+            // The wallet's background gRPC stream auto-claims transfers.
+            // We just listen for the event.
+            if (typeof w.on === "function") {
+                w.on("transfer:claimed", handler);
+            }
+            else {
+                // No event support, fall back to passive polling
+                clearTimeout(timer);
+                this.pollForTransferCompletion(transferId, timeoutMs).then(resolve);
+            }
+        });
+        if (claimed) {
+            const leaves = await this._wallet.getLeaves(true);
+            w.leaves = leaves;
+        }
+        return claimed;
+    }
     /**
      * Get Lightning fee estimate for an invoice
      * @private
@@ -2802,64 +2894,24 @@ class FlashnetClient {
     }
     /**
      * Decode the amount from a Lightning invoice (in sats)
+     * Uses light-bolt11-decoder (same library as Spark SDK) for reliable parsing.
      * @private
      */
     async decodeInvoiceAmount(invoice) {
-        // Extract amount from BOLT11 invoice
-        // Format: ln[network][amount][multiplier]...
-        // Amount multipliers: m = milli (0.001), u = micro (0.000001), n = nano, p = pico
-        const lowerInvoice = invoice.toLowerCase();
-        // Find where the amount starts (after network prefix)
-        let amountStart = 0;
-        if (lowerInvoice.startsWith("lnbc")) {
-            amountStart = 4;
-        }
-        else if (lowerInvoice.startsWith("lntb")) {
-            amountStart = 4;
-        }
-        else if (lowerInvoice.startsWith("lnbcrt")) {
-            amountStart = 6;
-        }
-        else if (lowerInvoice.startsWith("lntbs")) {
-            amountStart = 5;
+        try {
+            const decoded = decode(invoice);
+            const amountSection = decoded.sections.find((s) => s.name === "amount");
+            if (!amountSection?.value) {
+                return 0; // Zero-amount invoice
+            }
+            // The library returns amount in millisatoshis as a string
+            const amountMSats = BigInt(amountSection.value);
+            return Number(amountMSats / 1000n);
         }
-        else {
-            // Unknown format, try to find amount
-            const match = lowerInvoice.match(/^ln[a-z]+/);
-            if (match) {
-                amountStart = match[0].length;
-            }
-        }
-        // Extract amount and multiplier
-        const afterPrefix = lowerInvoice.substring(amountStart);
-        const amountMatch = afterPrefix.match(/^(\d+)([munp]?)/);
-        if (!amountMatch || !amountMatch[1]) {
-            return 0; // Zero-amount invoice
-        }
-        const amount = parseInt(amountMatch[1], 10);
-        const multiplier = amountMatch[2] ?? "";
-        // Convert to satoshis (1 BTC = 100,000,000 sats)
-        // Invoice amounts are in BTC by default
-        let btcAmount;
-        switch (multiplier) {
-            case "m": // milli-BTC (0.001 BTC)
-                btcAmount = amount * 0.001;
-                break;
-            case "u": // micro-BTC (0.000001 BTC)
-                btcAmount = amount * 0.000001;
-                break;
-            case "n": // nano-BTC (0.000000001 BTC)
-                btcAmount = amount * 0.000000001;
-                break;
-            case "p": // pico-BTC (0.000000000001 BTC)
-                btcAmount = amount * 0.000000000001;
-                break;
-            default: // BTC
-                btcAmount = amount;
-                break;
+        catch {
+            // Fallback: if library fails, return 0 (treated as zero-amount invoice)
+            return 0;
         }
-        // Convert BTC to sats
-        return Math.round(btcAmount * 100000000);
     }
     /**
      * Clean up wallet connections
@@ -2928,7 +2980,7 @@ class FlashnetClient {
                     continue;
                 }
                 const key = item.asset_identifier.toLowerCase();
-                const value = FlashnetClient.safeBigInt(item.min_amount);
+                const value = safeBigInt(item.min_amount);
                 map.set(key, value);
             }
         }
@@ -2950,8 +3002,8 @@ class FlashnetClient {
         const outHex = this.getHexAddress(params.assetOutAddress);
         const minIn = minMap.get(inHex);
         const minOut = minMap.get(outHex);
-        const amountIn = FlashnetClient.safeBigInt(params.amountIn);
-        const minAmountOut = FlashnetClient.safeBigInt(params.minAmountOut);
+        const amountIn = BigInt(params.amountIn);
+        const minAmountOut = BigInt(params.minAmountOut);
         if (minIn && minOut) {
             if (amountIn < minIn) {
                 throw new Error(`Minimum amount not met for input asset. Required \
@@ -2985,13 +3037,13 @@ ${relaxed.toString()} (50% relaxed), provided minAmountOut ${minAmountOut.toStri
         const aMin = minMap.get(aHex);
         const bMin = minMap.get(bHex);
         if (aMin) {
-            const aAmt = FlashnetClient.safeBigInt(params.assetAAmount);
+            const aAmt = BigInt(params.assetAAmount);
             if (aAmt < aMin) {
                 throw new Error(`Minimum amount not met for Asset A. Required ${aMin.toString()}, provided ${aAmt.toString()}`);
             }
         }
         if (bMin) {
-            const bAmt = FlashnetClient.safeBigInt(params.assetBAmount);
+            const bAmt = BigInt(params.assetBAmount);
             if (bAmt < bMin) {
                 throw new Error(`Minimum amount not met for Asset B. Required ${bMin.toString()}, provided ${bAmt.toString()}`);
             }
@@ -3013,14 +3065,14 @@ ${relaxed.toString()} (50% relaxed), provided minAmountOut ${minAmountOut.toStri
         const aMin = minMap.get(aHex);
         const bMin = minMap.get(bHex);
         if (aMin) {
-            const predictedAOut = FlashnetClient.safeBigInt(simulation.assetAAmount);
+            const predictedAOut = safeBigInt(simulation.assetAAmount);
             const relaxedA = aMin / 2n; // apply 50% relaxation for outputs
             if (predictedAOut < relaxedA) {
                 throw new Error(`Minimum amount not met for Asset A on withdrawal. Required at least ${relaxedA.toString()} (50% relaxed), predicted ${predictedAOut.toString()}`);
             }
         }
         if (bMin) {
-            const predictedBOut = FlashnetClient.safeBigInt(simulation.assetBAmount);
+            const predictedBOut = safeBigInt(simulation.assetBAmount);
             const relaxedB = bMin / 2n;
             if (predictedBOut < relaxedB) {
                 throw new Error(`Minimum amount not met for Asset B on withdrawal. Required at least ${relaxedB.toString()} (50% relaxed), predicted ${predictedBOut.toString()}`);
@@ -3133,7 +3185,7 @@ ${relaxed.toString()} (50% relaxed), provided minAmountOut ${minAmountOut.toStri
         const transferIds = [];
         // Transfer assets if not using free balance
         if (!params.useFreeBalance) {
-            if (FlashnetClient.safeBigInt(params.amountADesired) > 0n) {
+            if (BigInt(params.amountADesired) > 0n) {
                 assetATransferId = await this.transferAsset({
                     receiverSparkAddress: lpSparkAddress,
                     assetAddress: pool.assetAAddress,
@@ -3141,7 +3193,7 @@ ${relaxed.toString()} (50% relaxed), provided minAmountOut ${minAmountOut.toStri
                 }, "Insufficient balance for adding V3 liquidity (Asset A): ", params.useAvailableBalance);
                 transferIds.push(assetATransferId);
             }
-            if (FlashnetClient.safeBigInt(params.amountBDesired) > 0n) {
+            if (BigInt(params.amountBDesired) > 0n) {
                 assetBTransferId = await this.transferAsset({
                     receiverSparkAddress: lpSparkAddress,
                     assetAddress: pool.assetBAddress,
@@ -3538,7 +3590,7 @@ ${relaxed.toString()} (50% relaxed), provided minAmountOut ${minAmountOut.toStri
         let assetBTransferId = "";
         const transferIds = [];
         // Transfer assets to pool
-        if (FlashnetClient.safeBigInt(params.amountA) > 0n) {
+        if (BigInt(params.amountA) > 0n) {
             assetATransferId = await this.transferAsset({
                 receiverSparkAddress: lpSparkAddress,
                 assetAddress: pool.assetAAddress,
@@ -3546,7 +3598,7 @@ ${relaxed.toString()} (50% relaxed), provided minAmountOut ${minAmountOut.toStri
             }, "Insufficient balance for depositing to V3 pool (Asset A): ", params.useAvailableBalance);
             transferIds.push(assetATransferId);
         }
-        if (FlashnetClient.safeBigInt(params.amountB) > 0n) {
+        if (BigInt(params.amountB) > 0n) {
             assetBTransferId = await this.transferAsset({
                 receiverSparkAddress: lpSparkAddress,
                 assetAddress: pool.assetBAddress,