0xtrails 0.2.5 → 0.3.0

package/src/intentReceiptPoller.ts

@@ -0,0 +1,299 @@
+import type { TrailsClient } from "./trailsClient.js"
+import type {
+  IntentReceipt,
+  WaitIntentReceiptResponse,
+  TransactionStatus,
+} from "@0xsequence/trails-api"
+import { logger } from "./logger.js"
+
+const POLL_INTERVAL = 150 // 150 ms
+const MAX_WAIT_TIME = 5 * 60 * 1000 // 5 minutes
+
+/**
+ * Callback invoked when the deposit transaction hash is discovered (for gasless flows).
+ * @param txHash - The transaction hash of the deposit transaction
+ * @param receipt - The full IntentReceipt containing additional metadata
+ */
+export type OnDepositTransactionFound = (
+  txHash: string,
+  receipt: IntentReceipt,
+) => Promise<void>
+
+/**
+ * Callback invoked when the origin transaction hash is discovered.
+ * @param txHash - The transaction hash of the origin transaction
+ * @param receipt - The full IntentReceipt containing additional metadata
+ */
+export type OnOriginTransactionFound = (
+  txHash: string,
+  receipt: IntentReceipt,
+) => Promise<void>
+
+/**
+ * Callback invoked when the destination transaction hash is discovered.
+ * @param txHash - The transaction hash of the destination transaction
+ * @param receipt - The full IntentReceipt containing additional metadata
+ */
+export type OnDestinationTransactionFound = (
+  txHash: string,
+  receipt: IntentReceipt,
+) => Promise<void>
+
+/**
+ * Callback invoked when the intent receipt is updated (regardless of which field changed).
+ * @param receipt - The full IntentReceipt
+ * @param done - Whether the intent has reached a terminal status
+ */
+export type OnReceiptUpdate = (
+  receipt: IntentReceipt,
+  done: boolean,
+) => Promise<void>
+
+export interface IntentReceiptPollerCallbacks {
+  onDepositTransactionFound?: OnDepositTransactionFound
+  onOriginTransactionFound?: OnOriginTransactionFound
+  onDestinationTransactionFound?: OnDestinationTransactionFound
+  onReceiptUpdate?: OnReceiptUpdate
+}
+
+export interface IntentReceiptPollerOptions {
+  intentId: string
+  trailsClient: TrailsClient
+  callbacks?: IntentReceiptPollerCallbacks
+  maxWaitTime?: number
+  pollInterval?: number
+  abortSignal?: AbortSignal
+}
+
+/**
+ * Unified intent receipt poller that monitors a single intent ID and invokes callbacks
+ * as origin and destination transactions are discovered. This consolidates what was
+ * previously done via separate polling loops.
+ *
+ * @param options - Configuration for polling including intent ID, client, and callbacks
+ * @returns A promise that resolves when the intent reaches a terminal status or times out
+ *
+ * Usage:
+ * ```
+ * const poller = pollIntentReceipt({
+ *   intentId: intent.intentId,
+ *   trailsClient,
+ *   callbacks: {
+ *     onOriginTransactionFound: async (txHash, receipt) => {
+ *       // Handle origin transaction discovery
+ *     },
+ *     onDestinationTransactionFound: async (txHash, receipt) => {
+ *       // Handle destination transaction discovery
+ *     },
+ *     onReceiptUpdate: async (receipt, done) => {
+ *       // Handle any receipt update
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export async function pollIntentReceipt(
+  options: IntentReceiptPollerOptions,
+): Promise<IntentReceipt | null> {
+  const {
+    intentId,
+    trailsClient,
+    callbacks,
+    maxWaitTime = MAX_WAIT_TIME,
+    pollInterval = POLL_INTERVAL,
+    abortSignal,
+  } = options
+
+  const startTime = Date.now()
+  let lastDepositTxHash: string | undefined
+  let lastOriginTxHash: string | undefined
+  let lastDestinationTxHash: string | undefined
+  let lastReceipt: IntentReceipt | null = null
+  let lastReceiptStates: TransactionStatus[] = []
+
+  logger.console.log("[trails-sdk] Starting unified intent receipt polling", {
+    intentId,
+    maxWaitTime,
+    pollInterval,
+  })
+
+  try {
+    while (Date.now() - startTime < maxWaitTime) {
+      // Check abort signal
+      if (abortSignal?.aborted) {
+        logger.console.log(
+          "[trails-sdk] Intent receipt polling aborted via signal",
+          {
+            intentId,
+          },
+        )
+        return lastReceipt
+      }
+
+      try {
+        // Perform single waitIntentReceipt call
+        const response: WaitIntentReceiptResponse =
+          await trailsClient.waitIntentReceipt({
+            intentId,
+            lastReceiptStates,
+          })
+
+        const receipt = response.intentReceipt
+        lastReceipt = receipt
+        lastReceiptStates = response.receiptStates
+
+        logger.console.log("[trails-sdk] Unified intent receipt update", {
+          intentId,
+          status: receipt.status,
+          done: response.done,
+          depositTxHash: receipt.depositTransaction?.txnHash,
+          originTxHash: receipt.originTransaction?.txnHash,
+          destinationTxHash: receipt.destinationTransaction?.txnHash,
+        })
+
+        // Check if deposit transaction was discovered (and not already reported)
+        // This is used for gasless flows where the user's deposit is tracked separately
+        if (
+          receipt.depositTransaction?.txnHash &&
+          receipt.depositTransaction.txnHash !== lastDepositTxHash
+        ) {
+          lastDepositTxHash = receipt.depositTransaction.txnHash
+          logger.console.log(
+            "[trails-sdk] Deposit transaction discovered via unified poller",
+            {
+              intentId,
+              txHash: lastDepositTxHash,
+            },
+          )
+
+          if (callbacks?.onDepositTransactionFound) {
+            try {
+              await callbacks.onDepositTransactionFound(
+                lastDepositTxHash,
+                receipt,
+              )
+            } catch (error) {
+              logger.console.error(
+                "[trails-sdk] Error in onDepositTransactionFound callback",
+                {
+                  error: error instanceof Error ? error.message : String(error),
+                },
+              )
+            }
+          }
+        }
+
+        // Check if origin transaction was discovered (and not already reported)
+        if (
+          receipt.originTransaction?.txnHash &&
+          receipt.originTransaction.txnHash !== lastOriginTxHash
+        ) {
+          lastOriginTxHash = receipt.originTransaction.txnHash
+          logger.console.log(
+            "[trails-sdk] Origin transaction discovered via unified poller",
+            {
+              intentId,
+              txHash: lastOriginTxHash,
+            },
+          )
+
+          if (callbacks?.onOriginTransactionFound) {
+            try {
+              await callbacks.onOriginTransactionFound(
+                lastOriginTxHash,
+                receipt,
+              )
+            } catch (error) {
+              logger.console.error(
+                "[trails-sdk] Error in onOriginTransactionFound callback",
+                {
+                  error: error instanceof Error ? error.message : String(error),
+                },
+              )
+            }
+          }
+        }
+
+        // Check if destination transaction was discovered (and not already reported)
+        if (
+          receipt.destinationTransaction?.txnHash &&
+          receipt.destinationTransaction.txnHash !== lastDestinationTxHash
+        ) {
+          lastDestinationTxHash = receipt.destinationTransaction.txnHash
+          logger.console.log(
+            "[trails-sdk] Destination transaction discovered via unified poller",
+            {
+              intentId,
+              txHash: lastDestinationTxHash,
+            },
+          )
+
+          if (callbacks?.onDestinationTransactionFound) {
+            try {
+              await callbacks.onDestinationTransactionFound(
+                lastDestinationTxHash,
+                receipt,
+              )
+            } catch (error) {
+              logger.console.error(
+                "[trails-sdk] Error in onDestinationTransactionFound callback",
+                {
+                  error: error instanceof Error ? error.message : String(error),
+                },
+              )
+            }
+          }
+        }
+
+        // Invoke generic receipt update callback
+        if (callbacks?.onReceiptUpdate) {
+          try {
+            await callbacks.onReceiptUpdate(receipt, response.done)
+          } catch (error) {
+            logger.console.error(
+              "[trails-sdk] Error in onReceiptUpdate callback",
+              {
+                error: error instanceof Error ? error.message : String(error),
+              },
+            )
+          }
+        }
+
+        // If intent is done, stop polling
+        if (response.done) {
+          logger.console.log("[trails-sdk] Intent receipt polling complete", {
+            intentId,
+            status: receipt.status,
+          })
+          return receipt
+        }
+      } catch (error) {
+        logger.console.warn("[trails-sdk] Error polling intent receipt", {
+          intentId,
+          error: error instanceof Error ? error.message : String(error),
+        })
+        // Continue polling on error
+      }
+
+      // Wait a very short period of time before next poll.
+      // We do not want to wait long, as we want quick feedback to users
+      // on state changes.
+      await new Promise((resolve) => setTimeout(resolve, pollInterval))
+    }
+
+    logger.console.warn("[trails-sdk] Intent receipt polling timeout", {
+      intentId,
+      maxWaitTime,
+    })
+    return lastReceipt
+  } catch (error) {
+    logger.console.error(
+      "[trails-sdk] Unexpected error in intent receipt polling",
+      {
+        intentId,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    )
+    return lastReceipt
+  }
+}