@flashnet/sdk 0.5.6 → 0.5.8

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

@@ -1002,6 +1002,53 @@ class FlashnetClient {
         }
         return response;
     }
+    // LP Lock & Transfer Operations
+    /**
+     * Lock an LP position to prevent withdrawal until expiry.
+     * Locks can only be set or extended, never shortened.
+     * @param poolId Pool ID (LP identity public key)
+     * @param lockUntilTimestamp Unix timestamp (seconds). "0" = indefinite lock.
+     */
+    async lockPosition(poolId, lockUntilTimestamp, opts) {
+        await this.ensureInitialized();
+        await this.ensurePingOk();
+        const nonce = index$2.generateNonce();
+        const intentMessage = intents.generateLockPositionIntentMessage({
+            userPublicKey: this.publicKey,
+            lpIdentityPublicKey: poolId,
+            lockUntilTimestamp,
+            tickLower: opts?.tickLower,
+            tickUpper: opts?.tickUpper,
+            nonce,
+        });
+        const messageHash = sha256__default.default(intentMessage);
+        const signature = await this._wallet.config.signer.signMessageWithIdentityKey(messageHash, true);
+        const request = {
+            userPublicKey: this.publicKey,
+            poolId,
+            lockUntilTimestamp,
+            tickLower: opts?.tickLower,
+            tickUpper: opts?.tickUpper,
+            nonce,
+            signature: hex.getHexFromUint8Array(signature),
+        };
+        const response = await this.typedApi.lockPosition(request);
+        if (!response.accepted) {
+            const errorMessage = response.error || "Lock position rejected by the AMM";
+            throw new Error(errorMessage);
+        }
+        return response;
+    }
+    /**
+     * List LP position locks for a pool. Read-only, no signature required.
+     * @param poolId Pool ID (LP identity public key)
+     * @param ownerPublicKey Optional filter by owner
+     */
+    async getPositionLocks(poolId, ownerPublicKey) {
+        await this.ensureInitialized();
+        const response = await this.typedApi.getPositionLocks(poolId, ownerPublicKey);
+        return response.locks;
+    }
     // Host Operations
     /**
      * Register as a host
@@ -2099,8 +2146,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,
@@ -2125,138 +2180,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 >= bigint.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 = bigint.safeBigInt(btcReceived);
-                    const lnFee = bigint.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 >= bigint.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 = bigint.safeBigInt(btcReceived);
+                    const invoiceAmount = bigint.safeBigInt(quote.invoiceAmountSats);
+                    const available = actualBtc - invoiceAmount;
+                    if (available > 0n && available < bigint.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 = bigint.safeBigInt(btcReceived);
+                        const lnFee = bigint.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,
+                    };
+                }
+                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.`,
+                    };
                 }
-                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) {
@@ -2777,6 +2852,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