@flashnet/sdk 0.3.39 → 0.4.0

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

@@ -10,6 +10,7 @@ var hex = require('../utils/hex.js');
 var intents = require('../utils/intents.js');
 var sparkAddress = require('../utils/spark-address.js');
 var tokenAddress = require('../utils/tokenAddress.js');
+var errors = require('../types/errors.js');
 
 /**
  * FlashnetClient - A comprehensive client for interacting with Flashnet AMM
@@ -527,10 +528,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;
     }
     /**
@@ -577,6 +582,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();
@@ -598,11 +606,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();
@@ -649,10 +657,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 errors.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;
     }
@@ -669,6 +694,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();
@@ -705,68 +733,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 = index$2.generateNonce();
-        const intentMessage = intents.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: hex.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 = index$2.generateNonce();
+            const intentMessage = intents.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: hex.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 errors.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 =====
     /**
@@ -779,6 +824,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();
@@ -808,44 +856,61 @@ class FlashnetClient {
                 amount: params.assetBAmount,
             },
         ], "Insufficient balance for adding liquidity: ");
-        // Generate add liquidity intent
-        const nonce = index$2.generateNonce();
-        const intentMessage = intents.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: hex.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 = index$2.generateNonce();
+            const intentMessage = intents.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: hex.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 errors.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
@@ -1260,6 +1325,272 @@ class FlashnetClient {
         };
         return this.typedApi.checkClawbackEligibility(request);
     }
+    /**
+     * List transfers eligible for clawback
+     *
+     * Returns a paginated list of transfers that the authenticated user
+     * can potentially clawback. Filters based on:
+     * - Transfers sent by the authenticated user
+     * - Transfers to pools the user has interacted with
+     * - Not already spent or reserved
+     * - Less than 10 days old
+     *
+     * @param query - Optional pagination parameters (limit, offset)
+     * @returns List of eligible transfers with IDs and timestamps
+     */
+    async listClawbackableTransfers(query) {
+        await this.ensureInitialized();
+        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 = errors.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 errors.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