@flashnet/sdk 0.3.40 → 0.4.1

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

@@ -8,6 +8,7 @@ import { getHexFromUint8Array } from '../utils/hex.js';
 import { generateConstantProductPoolInitializationIntentMessage, generatePoolInitializationIntentMessage, generatePoolConfirmInitialDepositIntentMessage, generatePoolSwapIntentMessage, generateRouteSwapIntentMessage, generateAddLiquidityIntentMessage, generateRemoveLiquidityIntentMessage, generateRegisterHostIntentMessage, generateWithdrawHostFeesIntentMessage, generateWithdrawIntegratorFeesIntentMessage, generateCreateEscrowIntentMessage, generateFundEscrowIntentMessage, generateClaimEscrowIntentMessage, generateClawbackIntentMessage } from '../utils/intents.js';
 import { getSparkNetworkFromAddress, encodeSparkAddressNew } from '../utils/spark-address.js';
 import { encodeSparkHumanReadableTokenIdentifier, decodeSparkHumanReadableTokenIdentifier } from '../utils/tokenAddress.js';
+import { FlashnetError } from '../types/errors.js';
 
 /**
  * FlashnetClient - A comprehensive client for interacting with Flashnet AMM
@@ -525,10 +526,14 @@ class FlashnetClient {
             assetAddress: params.assetAAddress,
             amount: assetAInitialReserve,
         });
-        const confirmResponse = await this.confirmInitialDeposit(createResponse.poolId, assetATransferId, poolOwnerPublicKey);
-        if (!confirmResponse.confirmed) {
-            throw new Error(`Failed to confirm initial deposit: ${confirmResponse.message}`);
-        }
+        // Execute confirm with auto-clawback on failure
+        await this.executeWithAutoClawback(async () => {
+            const confirmResponse = await this.confirmInitialDeposit(createResponse.poolId, assetATransferId, poolOwnerPublicKey);
+            if (!confirmResponse.confirmed) {
+                throw new Error(`Failed to confirm initial deposit: ${confirmResponse.message}`);
+            }
+            return confirmResponse;
+        }, [assetATransferId], createResponse.poolId);
         return createResponse;
     }
     /**
@@ -575,6 +580,9 @@ class FlashnetClient {
     }
     /**
      * Execute a swap
+     *
+     * If the swap fails with a clawbackable error, the SDK will automatically
+     * attempt to recover the transferred funds via clawback.
      */
     async executeSwap(params) {
         await this.ensureInitialized();
@@ -596,11 +604,11 @@ class FlashnetClient {
             assetAddress: params.assetInAddress,
             amount: params.amountIn,
         }, "Insufficient balance for swap: ");
-        const response = await this.executeSwapIntent({
+        // Execute with auto-clawback on failure
+        return this.executeWithAutoClawback(() => this.executeSwapIntent({
             ...params,
             transferId,
-        });
-        return response;
+        }), [transferId], params.poolId);
     }
     async executeSwapIntent(params) {
         await this.ensureInitialized();
@@ -647,10 +655,27 @@ class FlashnetClient {
         // Check if the swap was accepted
         if (!response.accepted) {
             const errorMessage = response.error || "Swap rejected by the AMM";
-            const refundInfo = response.refundedAmount
+            const hasRefund = !!response.refundedAmount;
+            const refundInfo = hasRefund
                 ? ` Refunded ${response.refundedAmount} of ${response.refundedAssetAddress} via transfer ${response.refundTransferId}`
                 : "";
-            throw new Error(`${errorMessage}.${refundInfo}`);
+            // If refund was provided, funds are safe - use auto_refund recovery
+            // If no refund, funds may need clawback
+            throw new FlashnetError(`${errorMessage}.${refundInfo}`, {
+                response: {
+                    errorCode: hasRefund ? "FSAG-4202" : "UNKNOWN", // Slippage if refunded
+                    errorCategory: hasRefund ? "Business" : "System",
+                    message: `${errorMessage}.${refundInfo}`,
+                    requestId: "",
+                    timestamp: new Date().toISOString(),
+                    service: "amm-gateway",
+                    severity: "Error",
+                },
+                httpStatus: 400,
+                // Don't include transferIds if refunded - no clawback needed
+                transferIds: hasRefund ? [] : [params.transferId],
+                lpIdentityPublicKey: params.poolId,
+            });
         }
         return response;
     }
@@ -667,6 +692,9 @@ class FlashnetClient {
     }
     /**
      * Execute a route swap (multi-hop swap)
+     *
+     * If the route swap fails with a clawbackable error, the SDK will automatically
+     * attempt to recover the transferred funds via clawback.
      */
     async executeRouteSwap(params) {
         await this.ensureInitialized();
@@ -703,68 +731,85 @@ class FlashnetClient {
             assetAddress: params.initialAssetAddress,
             amount: params.inputAmount,
         }, "Insufficient balance for route swap: ");
-        // Prepare hops for validation
-        const hops = params.hops.map((hop) => ({
-            lpIdentityPublicKey: hop.poolId,
-            inputAssetAddress: this.toHexTokenIdentifier(hop.assetInAddress),
-            outputAssetAddress: this.toHexTokenIdentifier(hop.assetOutAddress),
-            hopIntegratorFeeRateBps: hop.hopIntegratorFeeRateBps !== undefined &&
-                hop.hopIntegratorFeeRateBps !== null
-                ? hop.hopIntegratorFeeRateBps.toString()
-                : "0",
-        }));
-        // Convert hops and ensure integrator fee is always present
-        const requestHops = params.hops.map((hop) => ({
-            poolId: hop.poolId,
-            assetInAddress: this.toHexTokenIdentifier(hop.assetInAddress),
-            assetOutAddress: this.toHexTokenIdentifier(hop.assetOutAddress),
-            hopIntegratorFeeRateBps: hop.hopIntegratorFeeRateBps !== undefined &&
-                hop.hopIntegratorFeeRateBps !== null
-                ? hop.hopIntegratorFeeRateBps.toString()
-                : "0",
-        }));
-        // Generate route swap intent
-        const nonce = generateNonce();
-        const intentMessage = generateRouteSwapIntentMessage({
-            userPublicKey: this.publicKey,
-            hops: hops.map((hop) => ({
-                lpIdentityPublicKey: hop.lpIdentityPublicKey,
-                inputAssetAddress: hop.inputAssetAddress,
-                outputAssetAddress: hop.outputAssetAddress,
-                hopIntegratorFeeRateBps: hop.hopIntegratorFeeRateBps,
-            })),
-            initialSparkTransferId: initialTransferId,
-            inputAmount: params.inputAmount.toString(),
-            maxRouteSlippageBps: params.maxRouteSlippageBps.toString(),
-            minAmountOut: params.minAmountOut,
-            nonce,
-            defaultIntegratorFeeRateBps: params.integratorFeeRateBps?.toString(),
-        });
-        // Sign intent
-        const messageHash = new Uint8Array(await crypto.subtle.digest("SHA-256", intentMessage));
-        const signature = await this._wallet.config.signer.signMessageWithIdentityKey(messageHash, true);
-        const request = {
-            userPublicKey: this.publicKey,
-            hops: requestHops,
-            initialSparkTransferId: initialTransferId,
-            inputAmount: params.inputAmount.toString(),
-            maxRouteSlippageBps: params.maxRouteSlippageBps.toString(),
-            minAmountOut: params.minAmountOut,
-            nonce,
-            signature: getHexFromUint8Array(signature),
-            integratorFeeRateBps: params.integratorFeeRateBps?.toString() || "0",
-            integratorPublicKey: params.integratorPublicKey || "",
-        };
-        const response = await this.typedApi.executeRouteSwap(request);
-        // Check if the route swap was accepted
-        if (!response.accepted) {
-            const errorMessage = response.error || "Route swap rejected by the AMM";
-            const refundInfo = response.refundedAmount
-                ? ` Refunded ${response.refundedAmount} of ${response.refundedAssetPublicKey} via transfer ${response.refundTransferId}`
-                : "";
-            throw new Error(`${errorMessage}.${refundInfo}`);
-        }
-        return response;
+        // Execute with auto-clawback on failure
+        return this.executeWithAutoClawback(async () => {
+            // Prepare hops for validation
+            const hops = params.hops.map((hop) => ({
+                lpIdentityPublicKey: hop.poolId,
+                inputAssetAddress: this.toHexTokenIdentifier(hop.assetInAddress),
+                outputAssetAddress: this.toHexTokenIdentifier(hop.assetOutAddress),
+                hopIntegratorFeeRateBps: hop.hopIntegratorFeeRateBps !== undefined &&
+                    hop.hopIntegratorFeeRateBps !== null
+                    ? hop.hopIntegratorFeeRateBps.toString()
+                    : "0",
+            }));
+            // Convert hops and ensure integrator fee is always present
+            const requestHops = params.hops.map((hop) => ({
+                poolId: hop.poolId,
+                assetInAddress: this.toHexTokenIdentifier(hop.assetInAddress),
+                assetOutAddress: this.toHexTokenIdentifier(hop.assetOutAddress),
+                hopIntegratorFeeRateBps: hop.hopIntegratorFeeRateBps !== undefined &&
+                    hop.hopIntegratorFeeRateBps !== null
+                    ? hop.hopIntegratorFeeRateBps.toString()
+                    : "0",
+            }));
+            // Generate route swap intent
+            const nonce = generateNonce();
+            const intentMessage = generateRouteSwapIntentMessage({
+                userPublicKey: this.publicKey,
+                hops: hops.map((hop) => ({
+                    lpIdentityPublicKey: hop.lpIdentityPublicKey,
+                    inputAssetAddress: hop.inputAssetAddress,
+                    outputAssetAddress: hop.outputAssetAddress,
+                    hopIntegratorFeeRateBps: hop.hopIntegratorFeeRateBps,
+                })),
+                initialSparkTransferId: initialTransferId,
+                inputAmount: params.inputAmount.toString(),
+                maxRouteSlippageBps: params.maxRouteSlippageBps.toString(),
+                minAmountOut: params.minAmountOut,
+                nonce,
+                defaultIntegratorFeeRateBps: params.integratorFeeRateBps?.toString(),
+            });
+            // Sign intent
+            const messageHash = new Uint8Array(await crypto.subtle.digest("SHA-256", intentMessage));
+            const signature = await this._wallet.config.signer.signMessageWithIdentityKey(messageHash, true);
+            const request = {
+                userPublicKey: this.publicKey,
+                hops: requestHops,
+                initialSparkTransferId: initialTransferId,
+                inputAmount: params.inputAmount.toString(),
+                maxRouteSlippageBps: params.maxRouteSlippageBps.toString(),
+                minAmountOut: params.minAmountOut,
+                nonce,
+                signature: getHexFromUint8Array(signature),
+                integratorFeeRateBps: params.integratorFeeRateBps?.toString() || "0",
+                integratorPublicKey: params.integratorPublicKey || "",
+            };
+            const response = await this.typedApi.executeRouteSwap(request);
+            // Check if the route swap was accepted
+            if (!response.accepted) {
+                const errorMessage = response.error || "Route swap rejected by the AMM";
+                const hasRefund = !!response.refundedAmount;
+                const refundInfo = hasRefund
+                    ? ` Refunded ${response.refundedAmount} of ${response.refundedAssetPublicKey} via transfer ${response.refundTransferId}`
+                    : "";
+                throw new FlashnetError(`${errorMessage}.${refundInfo}`, {
+                    response: {
+                        errorCode: hasRefund ? "FSAG-4202" : "UNKNOWN",
+                        errorCategory: hasRefund ? "Business" : "System",
+                        message: `${errorMessage}.${refundInfo}`,
+                        requestId: "",
+                        timestamp: new Date().toISOString(),
+                        service: "amm-gateway",
+                        severity: "Error",
+                    },
+                    httpStatus: 400,
+                    transferIds: hasRefund ? [] : [initialTransferId],
+                    lpIdentityPublicKey: firstPoolId,
+                });
+            }
+            return response;
+        }, [initialTransferId], firstPoolId);
     }
     // ===== Liquidity Operations =====
     /**
@@ -777,6 +822,9 @@ class FlashnetClient {
     }
     /**
      * Add liquidity to a pool
+     *
+     * If adding liquidity fails with a clawbackable error, the SDK will automatically
+     * attempt to recover the transferred funds via clawback.
      */
     async addLiquidity(params) {
         await this.ensureInitialized();
@@ -806,44 +854,61 @@ class FlashnetClient {
                 amount: params.assetBAmount,
             },
         ], "Insufficient balance for adding liquidity: ");
-        // Generate add liquidity intent
-        const nonce = generateNonce();
-        const intentMessage = generateAddLiquidityIntentMessage({
-            userPublicKey: this.publicKey,
-            lpIdentityPublicKey: params.poolId,
-            assetASparkTransferId: assetATransferId,
-            assetBSparkTransferId: assetBTransferId,
-            assetAAmount: params.assetAAmount.toString(),
-            assetBAmount: params.assetBAmount.toString(),
-            assetAMinAmountIn: params.assetAMinAmountIn.toString(),
-            assetBMinAmountIn: params.assetBMinAmountIn.toString(),
-            nonce,
-        });
-        // Sign intent
-        const messageHash = new Uint8Array(await crypto.subtle.digest("SHA-256", intentMessage));
-        const signature = await this._wallet.config.signer.signMessageWithIdentityKey(messageHash, true);
-        const request = {
-            userPublicKey: this.publicKey,
-            poolId: params.poolId,
-            assetASparkTransferId: assetATransferId,
-            assetBSparkTransferId: assetBTransferId,
-            assetAAmountToAdd: params.assetAAmount.toString(),
-            assetBAmountToAdd: params.assetBAmount.toString(),
-            assetAMinAmountIn: params.assetAMinAmountIn.toString(),
-            assetBMinAmountIn: params.assetBMinAmountIn.toString(),
-            nonce,
-            signature: getHexFromUint8Array(signature),
-        };
-        const response = await this.typedApi.addLiquidity(request);
-        // Check if the liquidity addition was accepted
-        if (!response.accepted) {
-            const errorMessage = response.error || "Add liquidity rejected by the AMM";
-            const refundInfo = response.refund
-                ? ` Refunds: Asset A: ${response.refund.assetAAmount || 0}, Asset B: ${response.refund.assetBAmount || 0}`
-                : "";
-            throw new Error(`${errorMessage}.${refundInfo}`);
-        }
-        return response;
+        // Execute with auto-clawback on failure
+        return this.executeWithAutoClawback(async () => {
+            // Generate add liquidity intent
+            const nonce = generateNonce();
+            const intentMessage = generateAddLiquidityIntentMessage({
+                userPublicKey: this.publicKey,
+                lpIdentityPublicKey: params.poolId,
+                assetASparkTransferId: assetATransferId,
+                assetBSparkTransferId: assetBTransferId,
+                assetAAmount: params.assetAAmount.toString(),
+                assetBAmount: params.assetBAmount.toString(),
+                assetAMinAmountIn: params.assetAMinAmountIn.toString(),
+                assetBMinAmountIn: params.assetBMinAmountIn.toString(),
+                nonce,
+            });
+            // Sign intent
+            const messageHash = new Uint8Array(await crypto.subtle.digest("SHA-256", intentMessage));
+            const signature = await this._wallet.config.signer.signMessageWithIdentityKey(messageHash, true);
+            const request = {
+                userPublicKey: this.publicKey,
+                poolId: params.poolId,
+                assetASparkTransferId: assetATransferId,
+                assetBSparkTransferId: assetBTransferId,
+                assetAAmountToAdd: params.assetAAmount.toString(),
+                assetBAmountToAdd: params.assetBAmount.toString(),
+                assetAMinAmountIn: params.assetAMinAmountIn.toString(),
+                assetBMinAmountIn: params.assetBMinAmountIn.toString(),
+                nonce,
+                signature: getHexFromUint8Array(signature),
+            };
+            const response = await this.typedApi.addLiquidity(request);
+            // Check if the liquidity addition was accepted
+            if (!response.accepted) {
+                const errorMessage = response.error || "Add liquidity rejected by the AMM";
+                const hasRefund = !!(response.refund?.assetAAmount || response.refund?.assetBAmount);
+                const refundInfo = response.refund
+                    ? ` Refunds: Asset A: ${response.refund.assetAAmount || 0}, Asset B: ${response.refund.assetBAmount || 0}`
+                    : "";
+                throw new FlashnetError(`${errorMessage}.${refundInfo}`, {
+                    response: {
+                        errorCode: hasRefund ? "FSAG-4203" : "UNKNOWN", // Phase error if refunded
+                        errorCategory: hasRefund ? "Business" : "System",
+                        message: `${errorMessage}.${refundInfo}`,
+                        requestId: "",
+                        timestamp: new Date().toISOString(),
+                        service: "amm-gateway",
+                        severity: "Error",
+                    },
+                    httpStatus: 400,
+                    transferIds: hasRefund ? [] : [assetATransferId, assetBTransferId],
+                    lpIdentityPublicKey: params.poolId,
+                });
+            }
+            return response;
+        }, [assetATransferId, assetBTransferId], params.poolId);
     }
     /**
      * Simulate removing liquidity
@@ -1276,6 +1341,254 @@ class FlashnetClient {
         await this.ensurePingOk();
         return this.typedApi.listClawbackableTransfers(query);
     }
+    /**
+     * Attempt to clawback multiple transfers
+     *
+     * @param transferIds - Array of transfer IDs to clawback
+     * @param lpIdentityPublicKey - The LP wallet public key
+     * @returns Array of results for each clawback attempt
+     */
+    async clawbackMultiple(transferIds, lpIdentityPublicKey) {
+        const results = [];
+        for (const transferId of transferIds) {
+            try {
+                const response = await this.clawback({
+                    sparkTransferId: transferId,
+                    lpIdentityPublicKey,
+                });
+                results.push({
+                    transferId,
+                    success: true,
+                    response,
+                });
+            }
+            catch (err) {
+                results.push({
+                    transferId,
+                    success: false,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Internal helper to execute an operation with automatic clawback on failure
+     *
+     * @param operation - The async operation to execute
+     * @param transferIds - Transfer IDs that were sent and may need clawback
+     * @param lpIdentityPublicKey - The LP wallet public key for clawback
+     * @returns The result of the operation
+     * @throws FlashnetError with typed clawbackSummary attached
+     */
+    async executeWithAutoClawback(operation, transferIds, lpIdentityPublicKey) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            // Convert to FlashnetError if not already
+            const flashnetError = FlashnetError.fromUnknown(error, {
+                transferIds,
+                lpIdentityPublicKey,
+            });
+            // Check if we should attempt clawback
+            if (flashnetError.shouldClawback() && transferIds.length > 0) {
+                // Attempt to clawback all transfers
+                const clawbackResults = await this.clawbackMultiple(transferIds, lpIdentityPublicKey);
+                // Separate successful and failed clawbacks
+                const successfulClawbacks = clawbackResults.filter((r) => r.success);
+                const failedClawbacks = clawbackResults.filter((r) => !r.success);
+                // Build typed clawback summary
+                const clawbackSummary = {
+                    attempted: true,
+                    totalTransfers: transferIds.length,
+                    successCount: successfulClawbacks.length,
+                    failureCount: failedClawbacks.length,
+                    results: clawbackResults,
+                    recoveredTransferIds: successfulClawbacks.map((r) => r.transferId),
+                    unrecoveredTransferIds: failedClawbacks.map((r) => r.transferId),
+                };
+                // Create enhanced error message
+                let enhancedMessage = flashnetError.message;
+                if (successfulClawbacks.length > 0) {
+                    enhancedMessage += ` [Auto-clawback: ${successfulClawbacks.length}/${transferIds.length} transfers recovered]`;
+                }
+                if (failedClawbacks.length > 0) {
+                    const failedIds = failedClawbacks.map((r) => r.transferId).join(", ");
+                    enhancedMessage += ` [Clawback failed for: ${failedIds}]`;
+                }
+                // Determine remediation based on clawback results
+                let remediation;
+                if (clawbackSummary.failureCount === 0) {
+                    remediation =
+                        "Your funds have been automatically recovered. No action needed.";
+                }
+                else if (clawbackSummary.successCount > 0) {
+                    remediation = `${clawbackSummary.successCount} transfer(s) recovered. Manual clawback needed for remaining transfers.`;
+                }
+                else {
+                    remediation =
+                        flashnetError.remediation ??
+                            "Automatic recovery failed. Please initiate a manual clawback.";
+                }
+                // Throw new error with typed clawback summary
+                const errorWithClawback = new FlashnetError(enhancedMessage, {
+                    response: {
+                        errorCode: flashnetError.errorCode,
+                        errorCategory: flashnetError.category,
+                        message: enhancedMessage,
+                        details: flashnetError.details,
+                        requestId: flashnetError.requestId,
+                        timestamp: flashnetError.timestamp,
+                        service: flashnetError.service,
+                        severity: flashnetError.severity,
+                        remediation,
+                    },
+                    httpStatus: flashnetError.httpStatus,
+                    transferIds: clawbackSummary.unrecoveredTransferIds,
+                    lpIdentityPublicKey,
+                    clawbackSummary,
+                });
+                throw errorWithClawback;
+            }
+            // Not a clawbackable error, just re-throw
+            throw flashnetError;
+        }
+    }
+    // ===== Clawback Monitor =====
+    /**
+     * Start a background job that periodically polls for clawbackable transfers
+     * and automatically claws them back.
+     *
+     * @param options - Monitor configuration options
+     * @returns ClawbackMonitorHandle to control the monitor
+     *
+     * @example
+     * ```typescript
+     * const monitor = client.startClawbackMonitor({
+     *   intervalMs: 60000, // Poll every 60 seconds
+     *   onClawbackSuccess: (result) => console.log('Recovered:', result.transferId),
+     *   onClawbackError: (transferId, error) => console.error('Failed:', transferId, error),
+     * });
+     *
+     * // Later, to stop:
+     * monitor.stop();
+     * ```
+     */
+    startClawbackMonitor(options = {}) {
+        const { intervalMs = 60000, // Default: 1 minute
+        batchSize = 2, // Default: 2 clawbacks per batch (rate limit safe)
+        batchDelayMs = 500, // Default: 500ms between batches
+        maxTransfersPerPoll = 100, // Default: max 100 transfers per poll
+        onClawbackSuccess, onClawbackError, onPollComplete, onPollError, } = options;
+        let isRunning = true;
+        let timeoutId = null;
+        let currentPollPromise = null;
+        const poll = async () => {
+            const result = {
+                transfersFound: 0,
+                clawbacksAttempted: 0,
+                clawbacksSucceeded: 0,
+                clawbacksFailed: 0,
+                results: [],
+            };
+            try {
+                // Fetch clawbackable transfers
+                const response = await this.listClawbackableTransfers({
+                    limit: maxTransfersPerPoll,
+                });
+                result.transfersFound = response.transfers.length;
+                if (response.transfers.length === 0) {
+                    return result;
+                }
+                // Process in batches to respect rate limits
+                for (let i = 0; i < response.transfers.length; i += batchSize) {
+                    if (!isRunning) {
+                        break;
+                    }
+                    const batch = response.transfers.slice(i, i + batchSize);
+                    // Process batch concurrently
+                    const batchResults = await Promise.all(batch.map(async (transfer) => {
+                        result.clawbacksAttempted++;
+                        try {
+                            const clawbackResponse = await this.clawback({
+                                sparkTransferId: transfer.id,
+                                lpIdentityPublicKey: transfer.lpIdentityPublicKey,
+                            });
+                            const attemptResult = {
+                                transferId: transfer.id,
+                                success: true,
+                                response: clawbackResponse,
+                            };
+                            result.clawbacksSucceeded++;
+                            onClawbackSuccess?.(attemptResult);
+                            return attemptResult;
+                        }
+                        catch (err) {
+                            const attemptResult = {
+                                transferId: transfer.id,
+                                success: false,
+                                error: err instanceof Error ? err.message : String(err),
+                            };
+                            result.clawbacksFailed++;
+                            onClawbackError?.(transfer.id, err);
+                            return attemptResult;
+                        }
+                    }));
+                    result.results.push(...batchResults);
+                    // Wait between batches if there are more to process
+                    if (i + batchSize < response.transfers.length && isRunning) {
+                        await new Promise((resolve) => setTimeout(resolve, batchDelayMs));
+                    }
+                }
+            }
+            catch (err) {
+                onPollError?.(err);
+            }
+            return result;
+        };
+        const scheduleNextPoll = () => {
+            if (!isRunning) {
+                return;
+            }
+            timeoutId = setTimeout(async () => {
+                if (!isRunning) {
+                    return;
+                }
+                currentPollPromise = (async () => {
+                    const result = await poll();
+                    onPollComplete?.(result);
+                    scheduleNextPoll();
+                })();
+            }, intervalMs);
+        };
+        // Start first poll immediately
+        currentPollPromise = (async () => {
+            const result = await poll();
+            onPollComplete?.(result);
+            scheduleNextPoll();
+        })();
+        return {
+            isRunning: () => isRunning,
+            stop: async () => {
+                isRunning = false;
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                    timeoutId = null;
+                }
+                // Wait for current poll to complete
+                if (currentPollPromise) {
+                    await currentPollPromise.catch(() => { });
+                }
+            },
+            pollNow: async () => {
+                if (!isRunning) {
+                    throw new Error("Monitor is stopped");
+                }
+                return poll();
+            },
+        };
+    }
     // ===== Token Address Operations =====
     /**
      * Encode a token identifier into a human-readable token address using the client's Spark network
@@ -1473,6 +1786,489 @@ class FlashnetClient {
             throw new Error(errorMessage);
         }
     }
+    // ===== Lightning Payment with Token =====
+    /**
+     * Get a quote for paying a Lightning invoice with a token.
+     * This calculates the optimal pool and token amount needed.
+     *
+     * @param invoice - BOLT11-encoded Lightning invoice
+     * @param tokenAddress - Token identifier to use for payment
+     * @param options - Optional configuration (slippage, integrator fees, etc.)
+     * @returns Quote with pricing details
+     * @throws Error if invoice amount or token amount is below Flashnet minimums
+     */
+    async getPayLightningWithTokenQuote(invoice, tokenAddress, options) {
+        await this.ensureInitialized();
+        // Decode the invoice to get the amount
+        const invoiceAmountSats = await this.decodeInvoiceAmount(invoice);
+        if (!invoiceAmountSats || invoiceAmountSats <= 0) {
+            throw new Error("Unable to decode invoice amount. Zero-amount invoices are not supported for token payments.");
+        }
+        // Get Lightning fee estimate
+        const lightningFeeEstimate = await this.getLightningFeeEstimate(invoice);
+        // Total BTC needed = invoice amount + lightning fee
+        const baseBtcNeeded = BigInt(invoiceAmountSats) + BigInt(lightningFeeEstimate);
+        // Round up to next multiple of 64 (2^6) to account for BTC variable fee bit masking.
+        // The AMM zeroes the lowest 6 bits of BTC output, so we need to request enough
+        // that after masking we still have the required amount.
+        // Example: 5014 -> masked to 4992, but if we request 5056, masked stays 5056
+        const BTC_VARIABLE_FEE_BITS = 6n;
+        const BTC_VARIABLE_FEE_MASK = 1n << BTC_VARIABLE_FEE_BITS; // 64
+        const totalBtcNeeded = ((baseBtcNeeded + BTC_VARIABLE_FEE_MASK - 1n) / BTC_VARIABLE_FEE_MASK) *
+            BTC_VARIABLE_FEE_MASK;
+        // Check Flashnet minimum amounts early to provide clear error messages
+        const minAmounts = await this.getEnabledMinAmountsMap();
+        // Check BTC minimum (output from swap)
+        const btcMinAmount = minAmounts.get(BTC_ASSET_PUBKEY.toLowerCase());
+        if (btcMinAmount && totalBtcNeeded < btcMinAmount) {
+            throw new Error(`Invoice amount too small. Flashnet minimum BTC output is ${btcMinAmount} sats, ` +
+                `but invoice + lightning fee totals only ${totalBtcNeeded} sats. ` +
+                `Please use an invoice of at least ${btcMinAmount} sats.`);
+        }
+        // Find the best pool to swap token -> BTC
+        const poolQuote = await this.findBestPoolForTokenToBtc(tokenAddress, totalBtcNeeded.toString(), options?.integratorFeeRateBps);
+        // Check token minimum (input to swap)
+        const tokenHex = this.toHexTokenIdentifier(tokenAddress).toLowerCase();
+        const tokenMinAmount = minAmounts.get(tokenHex);
+        if (tokenMinAmount &&
+            BigInt(poolQuote.tokenAmountRequired) < tokenMinAmount) {
+            throw new Error(`Token amount too small. Flashnet minimum input is ${tokenMinAmount} units, ` +
+                `but calculated amount is only ${poolQuote.tokenAmountRequired} units. ` +
+                `Please use a larger invoice amount.`);
+        }
+        // Calculate the BTC variable fee adjustment (how much extra we're requesting)
+        const btcVariableFeeAdjustment = Number(totalBtcNeeded - baseBtcNeeded);
+        return {
+            poolId: poolQuote.poolId,
+            tokenAddress: this.toHexTokenIdentifier(tokenAddress),
+            tokenAmountRequired: poolQuote.tokenAmountRequired,
+            btcAmountRequired: totalBtcNeeded.toString(),
+            invoiceAmountSats: invoiceAmountSats,
+            estimatedAmmFee: poolQuote.estimatedAmmFee,
+            estimatedLightningFee: lightningFeeEstimate,
+            btcVariableFeeAdjustment,
+            executionPrice: poolQuote.executionPrice,
+            priceImpactPct: poolQuote.priceImpactPct,
+            tokenIsAssetA: poolQuote.tokenIsAssetA,
+            poolReserves: poolQuote.poolReserves,
+            warningMessage: poolQuote.warningMessage,
+        };
+    }
+    /**
+     * Pay a Lightning invoice using a token.
+     * This swaps the token to BTC on Flashnet and uses the BTC to pay the invoice.
+     *
+     * @param options - Payment options including invoice and token address
+     * @returns Payment result with transaction details
+     */
+    async payLightningWithToken(options) {
+        await this.ensureInitialized();
+        const { invoice, tokenAddress, maxSlippageBps = 100, // 1% default
+        maxLightningFeeSats, preferSpark = true, integratorFeeRateBps, integratorPublicKey, transferTimeoutMs = 10000, } = options;
+        try {
+            // Step 1: Get a quote for the payment
+            const quote = await this.getPayLightningWithTokenQuote(invoice, tokenAddress, {
+                maxSlippageBps,
+                integratorFeeRateBps,
+            });
+            // Step 2: Check balance
+            await this.checkBalance({
+                balancesToCheck: [
+                    {
+                        assetAddress: tokenAddress,
+                        amount: quote.tokenAmountRequired,
+                    },
+                ],
+                errorPrefix: "Insufficient token balance for Lightning payment: ",
+            });
+            // Step 3: Get pool details
+            const pool = await this.getPool(quote.poolId);
+            // Step 4: Determine swap direction and execute
+            const assetInAddress = quote.tokenIsAssetA
+                ? pool.assetAAddress
+                : pool.assetBAddress;
+            const assetOutAddress = quote.tokenIsAssetA
+                ? pool.assetBAddress
+                : pool.assetAAddress;
+            // Calculate min amount out with slippage protection
+            const minBtcOut = this.calculateMinAmountOut(quote.btcAmountRequired, maxSlippageBps);
+            // Execute the swap
+            const swapResponse = await this.executeSwap({
+                poolId: quote.poolId,
+                assetInAddress,
+                assetOutAddress,
+                amountIn: quote.tokenAmountRequired,
+                maxSlippageBps,
+                minAmountOut: minBtcOut,
+                integratorFeeRateBps,
+                integratorPublicKey,
+            });
+            if (!swapResponse.accepted || !swapResponse.outboundTransferId) {
+                return {
+                    success: false,
+                    poolId: quote.poolId,
+                    tokenAmountSpent: quote.tokenAmountRequired,
+                    btcAmountReceived: "0",
+                    swapTransferId: swapResponse.outboundTransferId || "",
+                    ammFeePaid: quote.estimatedAmmFee,
+                    error: swapResponse.error || "Swap was not accepted",
+                };
+            }
+            // Step 5: Wait for the transfer to complete
+            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,
+                    error: "Transfer did not complete within timeout",
+                };
+            }
+            // Step 6: Calculate Lightning fee limit
+            const invoiceAmountSats = await this.decodeInvoiceAmount(invoice);
+            const effectiveMaxLightningFee = maxLightningFeeSats ??
+                Math.max(5, Math.ceil(invoiceAmountSats * 0.0017)); // 17 bps or 5 sats minimum
+            // Step 7: Pay the Lightning invoice
+            const lightningPayment = await this._wallet.payLightningInvoice({
+                invoice,
+                maxFeeSats: effectiveMaxLightningFee,
+                preferSpark,
+            });
+            return {
+                success: true,
+                poolId: quote.poolId,
+                tokenAmountSpent: quote.tokenAmountRequired,
+                btcAmountReceived: swapResponse.amountOut || quote.btcAmountRequired,
+                swapTransferId: swapResponse.outboundTransferId,
+                lightningPaymentId: lightningPayment.id,
+                ammFeePaid: quote.estimatedAmmFee,
+                lightningFeePaid: effectiveMaxLightningFee,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                success: false,
+                poolId: "",
+                tokenAmountSpent: "0",
+                btcAmountReceived: "0",
+                swapTransferId: "",
+                ammFeePaid: "0",
+                error: errorMessage,
+            };
+        }
+    }
+    /**
+     * Find the best pool for swapping a token to BTC
+     * @private
+     */
+    async findBestPoolForTokenToBtc(tokenAddress, btcAmountNeeded, integratorFeeRateBps) {
+        const tokenHex = this.toHexTokenIdentifier(tokenAddress);
+        const btcHex = BTC_ASSET_PUBKEY;
+        // Find all pools that have this token paired with BTC
+        const poolsWithTokenAsA = await this.listPools({
+            assetAAddress: tokenHex,
+            assetBAddress: btcHex,
+        });
+        const poolsWithTokenAsB = await this.listPools({
+            assetAAddress: btcHex,
+            assetBAddress: tokenHex,
+        });
+        const allPools = [
+            ...poolsWithTokenAsA.pools.map((p) => ({ ...p, tokenIsAssetA: true })),
+            ...poolsWithTokenAsB.pools.map((p) => ({ ...p, tokenIsAssetA: false })),
+        ];
+        if (allPools.length === 0) {
+            throw new Error(`No liquidity pool found for token ${tokenAddress} paired with BTC`);
+        }
+        // Find the best pool (lowest token cost for the required BTC)
+        let bestPool = null;
+        let bestTokenAmount = BigInt(Number.MAX_SAFE_INTEGER);
+        let bestSimulation = null;
+        for (const pool of allPools) {
+            try {
+                // Get pool details for reserves
+                const poolDetails = await this.getPool(pool.lpPublicKey);
+                // Calculate the token amount needed using AMM math
+                const calculation = this.calculateTokenAmountForBtcOutput(btcAmountNeeded, poolDetails.assetAReserve, poolDetails.assetBReserve, poolDetails.lpFeeBps, poolDetails.hostFeeBps, pool.tokenIsAssetA, integratorFeeRateBps);
+                const tokenAmount = BigInt(calculation.amountIn);
+                // Check if this is better than our current best
+                if (tokenAmount < bestTokenAmount) {
+                    // Verify with simulation
+                    const simulation = await this.simulateSwap({
+                        poolId: pool.lpPublicKey,
+                        assetInAddress: pool.tokenIsAssetA
+                            ? poolDetails.assetAAddress
+                            : poolDetails.assetBAddress,
+                        assetOutAddress: pool.tokenIsAssetA
+                            ? poolDetails.assetBAddress
+                            : poolDetails.assetAAddress,
+                        amountIn: calculation.amountIn,
+                        integratorBps: integratorFeeRateBps,
+                    });
+                    // Verify the output is sufficient
+                    if (BigInt(simulation.amountOut) >= BigInt(btcAmountNeeded)) {
+                        bestPool = pool;
+                        bestTokenAmount = tokenAmount;
+                        bestSimulation = {
+                            amountIn: calculation.amountIn,
+                            fee: calculation.totalFee,
+                            executionPrice: simulation.executionPrice || "0",
+                            priceImpactPct: simulation.priceImpactPct || "0",
+                            warningMessage: simulation.warningMessage,
+                        };
+                    }
+                }
+            }
+            catch { }
+        }
+        if (!bestPool || !bestSimulation) {
+            throw new Error(`No pool has sufficient liquidity for ${btcAmountNeeded} sats`);
+        }
+        const poolDetails = await this.getPool(bestPool.lpPublicKey);
+        return {
+            poolId: bestPool.lpPublicKey,
+            tokenAmountRequired: bestSimulation.amountIn,
+            estimatedAmmFee: bestSimulation.fee,
+            executionPrice: bestSimulation.executionPrice,
+            priceImpactPct: bestSimulation.priceImpactPct,
+            tokenIsAssetA: bestPool.tokenIsAssetA,
+            poolReserves: {
+                assetAReserve: poolDetails.assetAReserve,
+                assetBReserve: poolDetails.assetBReserve,
+            },
+            warningMessage: bestSimulation.warningMessage,
+        };
+    }
+    /**
+     * Calculate the token amount needed to get a specific BTC output.
+     * Implements the AMM fee-inclusive model.
+     * @private
+     */
+    calculateTokenAmountForBtcOutput(btcAmountOut, reserveA, reserveB, lpFeeBps, hostFeeBps, tokenIsAssetA, integratorFeeBps) {
+        const amountOut = BigInt(btcAmountOut);
+        const resA = BigInt(reserveA);
+        const resB = BigInt(reserveB);
+        const totalFeeBps = lpFeeBps + hostFeeBps + (integratorFeeBps || 0);
+        const feeRate = Number(totalFeeBps) / 10000; // Convert bps to decimal
+        // Token is the input asset
+        // BTC is the output asset
+        if (tokenIsAssetA) {
+            // Token is asset A, BTC is asset B
+            // A → B swap: we want BTC out (asset B)
+            // reserve_in = reserveA (token), reserve_out = reserveB (BTC)
+            // Constant product formula for amount_in given amount_out:
+            // amount_in_effective = (reserve_in * amount_out) / (reserve_out - amount_out)
+            const reserveIn = resA;
+            const reserveOut = resB;
+            if (amountOut >= reserveOut) {
+                throw new Error("Insufficient liquidity: requested BTC amount exceeds reserve");
+            }
+            // Calculate effective amount in (before fees)
+            const amountInEffective = (reserveIn * amountOut) / (reserveOut - amountOut) + 1n; // +1 for rounding up
+            // A→B swap: LP fee deducted from input A, integrator fee from output B
+            // amount_in = amount_in_effective * (1 + lp_fee_rate)
+            // Then integrator fee is deducted from output, so we need slightly more input
+            const lpFeeRate = Number(lpFeeBps) / 10000;
+            const integratorFeeRate = Number(integratorFeeBps || 0) / 10000;
+            // Account for LP fee on input
+            const amountInWithLpFee = BigInt(Math.ceil(Number(amountInEffective) * (1 + lpFeeRate)));
+            // Account for integrator fee on output (need more input to get same output after fee)
+            const amountIn = integratorFeeRate > 0
+                ? BigInt(Math.ceil(Number(amountInWithLpFee) * (1 + integratorFeeRate)))
+                : amountInWithLpFee;
+            const totalFee = amountIn - amountInEffective;
+            return {
+                amountIn: amountIn.toString(),
+                totalFee: totalFee.toString(),
+            };
+        }
+        else {
+            // Token is asset B, BTC is asset A
+            // B → A swap: we want BTC out (asset A)
+            // reserve_in = reserveB (token), reserve_out = reserveA (BTC)
+            const reserveIn = resB;
+            const reserveOut = resA;
+            if (amountOut >= reserveOut) {
+                throw new Error("Insufficient liquidity: requested BTC amount exceeds reserve");
+            }
+            // Calculate effective amount in (before fees)
+            const amountInEffective = (reserveIn * amountOut) / (reserveOut - amountOut) + 1n; // +1 for rounding up
+            // B→A swap: ALL fees (LP + integrator) deducted from input B
+            // amount_in = amount_in_effective * (1 + total_fee_rate)
+            const amountIn = BigInt(Math.ceil(Number(amountInEffective) * (1 + feeRate)));
+            // Fee calculation: fee = amount_in * fee_rate / (1 + fee_rate)
+            const totalFee = BigInt(Math.ceil((Number(amountIn) * feeRate) / (1 + feeRate)));
+            return {
+                amountIn: amountIn.toString(),
+                totalFee: totalFee.toString(),
+            };
+        }
+    }
+    /**
+     * Calculate minimum amount out with slippage protection
+     * @private
+     */
+    calculateMinAmountOut(expectedAmount, slippageBps) {
+        const amount = BigInt(expectedAmount);
+        const slippageFactor = BigInt(10000 - slippageBps);
+        const minAmount = (amount * slippageFactor) / 10000n;
+        return minAmount.toString();
+    }
+    /**
+     * Wait for a transfer to be claimed using wallet events.
+     * This is more efficient than polling as it uses the wallet's event stream.
+     * @private
+     */
+    async waitForTransferCompletion(transferId, timeoutMs) {
+        return new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                // Remove listener on timeout
+                try {
+                    this._wallet.removeListener?.("transfer:claimed", handler);
+                }
+                catch {
+                    // Ignore if removeListener doesn't exist
+                }
+                resolve(false);
+            }, timeoutMs);
+            const handler = (claimedTransferId, _balance) => {
+                if (claimedTransferId === transferId) {
+                    clearTimeout(timeout);
+                    try {
+                        this._wallet.removeListener?.("transfer:claimed", handler);
+                    }
+                    catch {
+                        // Ignore if removeListener doesn't exist
+                    }
+                    resolve(true);
+                }
+            };
+            // Subscribe to transfer claimed events
+            // The wallet's RPC stream will automatically claim incoming transfers
+            try {
+                this._wallet.on?.("transfer:claimed", handler);
+            }
+            catch {
+                // If event subscription fails, fall back to polling
+                clearTimeout(timeout);
+                this.pollForTransferCompletion(transferId, timeoutMs).then(resolve);
+            }
+        });
+    }
+    /**
+     * Fallback polling method for transfer completion
+     * @private
+     */
+    async pollForTransferCompletion(transferId, timeoutMs) {
+        const startTime = Date.now();
+        const pollIntervalMs = 500;
+        while (Date.now() - startTime < timeoutMs) {
+            try {
+                const transfer = await this._wallet.getTransfer(transferId);
+                if (transfer) {
+                    if (transfer.status === "TRANSFER_STATUS_COMPLETED") {
+                        return true;
+                    }
+                }
+            }
+            catch {
+                // Ignore errors and continue polling
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        }
+        return false;
+    }
+    /**
+     * Get Lightning fee estimate for an invoice
+     * @private
+     */
+    async getLightningFeeEstimate(invoice) {
+        try {
+            const feeEstimate = await this._wallet.getLightningSendFeeEstimate({
+                encodedInvoice: invoice,
+            });
+            // The fee estimate might be returned as a number or an object
+            if (typeof feeEstimate === "number") {
+                return feeEstimate;
+            }
+            if (feeEstimate?.fee || feeEstimate?.feeEstimate) {
+                return Number(feeEstimate.fee || feeEstimate.feeEstimate);
+            }
+            // Fallback to invoice amount-based estimate
+            const invoiceAmount = await this.decodeInvoiceAmount(invoice);
+            return Math.max(5, Math.ceil(invoiceAmount * 0.0017)); // 17 bps or 5 sats minimum
+        }
+        catch {
+            // Fallback to invoice amount-based estimate
+            const invoiceAmount = await this.decodeInvoiceAmount(invoice);
+            return Math.max(5, Math.ceil(invoiceAmount * 0.0017));
+        }
+    }
+    /**
+     * Decode the amount from a Lightning invoice (in sats)
+     * @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;
+        }
+        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;
+        }
+        // Convert BTC to sats
+        return Math.round(btcAmount * 100000000);
+    }
     /**
      * Clean up wallet connections
      */