0xtrails 0.2.6 → 0.4.0

package/src/fees.ts

@@ -1,4 +1,4 @@
-import type { GetIntentCallsPayloadsReturn } from "./intents.js"
+import type { Intent } from "@0xsequence/trails-api"
 import { getTokenInfo } from "./tokens.js"
 import { formatRawAmount, formatUsdAmountDisplay } from "./tokenBalances.js"
 import { zeroAddress } from "viem"
@@ -51,27 +51,21 @@ async function formatTokenAmount(
 
 // Extract fee breakdown from intent data
 export async function extractTrailsFeeBreakdown(
-  intent: GetIntentCallsPayloadsReturn,
+  intent: Intent,
 ): Promise<TrailsFeeBreakdown | null> {
-  const trailsFee = intent.payloads?.trailsFee
-  if (!trailsFee?.executeQuote?.chainQuotes) {
+  const fees = intent?.fees
+  if (!fees) {
     return null
   }
 
-  const chainQuotes = trailsFee.executeQuote.chainQuotes
-
   // Get chain IDs from the calls array to determine origin and destination chains
-  const calls = intent.payloads?.calls || []
-  const originChainId = calls[0]?.chainId // First call is origin chain
-  const destinationChainId = calls[1]?.chainId // Second call is destination chain
-
-  // Find quotes by chainId
-  const originChainQuote = chainQuotes.find(
-    (quote: any) => quote.chainId === originChainId,
-  )
-  const destinationChainQuote = chainQuotes.find(
-    (quote: any) => quote.chainId === destinationChainId,
-  )
+  const calls = intent?.calls || []
+  const originChainId: number | undefined = calls[0]?.chainId // First call is origin chain
+  const destinationChainId: number | undefined = calls[1]?.chainId // Second call is destination chain
+
+  // Use the origin and destination gas fees
+  const originChainQuote = fees.originGas
+  const destinationChainQuote = fees.destinationGas
 
   // If we can't find any chain quotes, return null
   if (!originChainQuote && !destinationChainQuote) {
@@ -80,7 +74,6 @@ export async function extractTrailsFeeBreakdown(
       {
         originChainId,
         destinationChainId,
-        availableChainIds: chainQuotes.map((q: any) => q.chainId),
       },
     )
     return null
@@ -89,52 +82,60 @@ export async function extractTrailsFeeBreakdown(
   const breakdown: TrailsFeeBreakdown = {}
 
   // Extract origin relay fee if available
-  if (originChainQuote) {
+  if (originChainQuote && originChainId !== undefined) {
     const originTokenSymbol = originChainQuote.nativeTokenSymbol || "ETH"
-    const originChainIdNum = parseInt(originChainId || "0", 10)
+    const originChainIdNum =
+      typeof originChainId === "bigint" ? Number(originChainId) : originChainId
     const nativeTokenAddress = zeroAddress
 
     breakdown.originRelayFee = {
       amount: await formatTokenAmount(
-        originChainQuote.totalFeeAmount,
+        originChainQuote.totalFeeAmount.toString(),
         nativeTokenAddress,
         originChainIdNum,
       ),
       tokenSymbol: originTokenSymbol,
       tokenAddress: nativeTokenAddress,
       chainId: originChainIdNum,
-      usdValue: formatUsdAmountDisplay(originChainQuote.totalFeeUSD),
+      usdValue: formatUsdAmountDisplay(originChainQuote.totalFeeUsd),
     }
     breakdown.originChainId = originChainIdNum
   }
 
   // Extract destination relay fee if available
-  if (destinationChainQuote) {
+  if (destinationChainQuote && destinationChainId !== undefined) {
     const destinationTokenSymbol =
       destinationChainQuote.nativeTokenSymbol || "ETH"
-    const destinationChainIdNum = parseInt(destinationChainId || "0", 10)
+    const destinationChainIdNum =
+      typeof destinationChainId === "bigint"
+        ? Number(destinationChainId)
+        : destinationChainId
     const nativeTokenAddress = zeroAddress
 
     breakdown.destinationRelayFee = {
       amount: await formatTokenAmount(
-        destinationChainQuote.totalFeeAmount,
+        destinationChainQuote.totalFeeAmount.toString(),
         nativeTokenAddress,
         destinationChainIdNum,
       ),
       tokenSymbol: destinationTokenSymbol,
       tokenAddress: nativeTokenAddress,
       chainId: destinationChainIdNum,
-      usdValue: formatUsdAmountDisplay(destinationChainQuote.totalFeeUSD),
+      usdValue: formatUsdAmountDisplay(destinationChainQuote.totalFeeUsd),
     }
     breakdown.destinationChainId = destinationChainIdNum
   }
 
-  // Extract provider fee from crossChainFee if available
-  const providerFeeAmount = trailsFee.crossChainFee?.providerFeeUSD
-  const providerFeeRawAmount = trailsFee.crossChainFee?.providerFee
-  if (providerFeeAmount !== undefined || providerFeeRawAmount !== undefined) {
-    const feeTokenAddress = trailsFee.feeToken || zeroAddress
-    const originChainIdNum = parseInt(originChainId || "0", 10)
+  // Extract provider fee from provider fees if available
+  const providerFeeAmount = fees.provider?.quoteProviderFeeUsd
+  const providerFeeRawAmount = fees.provider?.quoteProviderFee
+  if (
+    (providerFeeAmount !== undefined || providerFeeRawAmount !== undefined) &&
+    originChainId !== undefined
+  ) {
+    const feeTokenAddress = fees.feeTokenAddress || zeroAddress
+    const originChainIdNum =
+      typeof originChainId === "bigint" ? Number(originChainId) : originChainId
 
     // Get token info to determine the actual token symbol
     const feeTokenInfo = await getTokenInfo(originChainIdNum, feeTokenAddress)
@@ -146,7 +147,7 @@ export async function extractTrailsFeeBreakdown(
 
     breakdown.providerFee = {
       amount: await formatTokenAmount(
-        providerFeeRawAmount,
+        providerFeeRawAmount?.toString(),
         feeTokenAddress,
         originChainIdNum,
       ),
@@ -157,12 +158,16 @@ export async function extractTrailsFeeBreakdown(
     }
   }
 
-  // Extract Trails platform fee from crossChainFee if available
-  const trailsFeeAmount = trailsFee.crossChainFee?.trailsSwapFeeUSD
-  const trailsFeeRawAmount = trailsFee.crossChainFee?.trailsSwapFee
-  if (trailsFeeAmount !== undefined || trailsFeeRawAmount !== undefined) {
-    const feeTokenAddress = trailsFee.feeToken || zeroAddress
-    const originChainIdNum = parseInt(originChainId || "0", 10)
+  // Extract Trails platform fee from provider fees if available
+  const trailsFeeAmount = fees.provider?.trailsFeeUsd
+  const trailsFeeRawAmount = fees.provider?.trailsFee
+  if (
+    (trailsFeeAmount !== undefined || trailsFeeRawAmount !== undefined) &&
+    originChainId !== undefined
+  ) {
+    const feeTokenAddress = fees.feeTokenAddress || zeroAddress
+    const originChainIdNum =
+      typeof originChainId === "bigint" ? Number(originChainId) : originChainId
 
     // Get token info to determine the actual token symbol
     const feeTokenInfo = await getTokenInfo(originChainIdNum, feeTokenAddress)
@@ -174,7 +179,7 @@ export async function extractTrailsFeeBreakdown(
 
     breakdown.trailsFee = {
       amount: await formatTokenAmount(
-        trailsFeeRawAmount,
+        trailsFeeRawAmount?.toString(),
         feeTokenAddress,
         originChainIdNum,
       ),
@@ -186,8 +191,14 @@ export async function extractTrailsFeeBreakdown(
   }
 
   // Calculate total USD value from the actual data
-  const originUsd = parseFloat(originChainQuote?.totalFeeUSD || "0")
-  const destinationUsd = parseFloat(destinationChainQuote?.totalFeeUSD || "0")
+  const originUsd =
+    typeof originChainQuote?.totalFeeUsd === "string"
+      ? parseFloat(originChainQuote.totalFeeUsd)
+      : originChainQuote?.totalFeeUsd || 0
+  const destinationUsd =
+    typeof destinationChainQuote?.totalFeeUsd === "string"
+      ? parseFloat(destinationChainQuote.totalFeeUsd)
+      : destinationChainQuote?.totalFeeUsd || 0
   const providerUsd =
     typeof providerFeeAmount === "number" ? providerFeeAmount : 0
   const trailsUsd = typeof trailsFeeAmount === "number" ? trailsFeeAmount : 0

package/src/index.ts

@@ -1,6 +1,10 @@
 // Be explicit about what we export
 
-export { getAPIClient, useAPIClient } from "./apiClient.js"
+export {
+  InsufficientBalanceError,
+  UserRejectionError,
+  getIsUserRejectionError,
+} from "./error.js"
 export {
   getSupportedChains,
   useSupportedChains,
@@ -13,7 +17,6 @@ export {
   useIndexerGatewayClient,
 } from "./indexerClient.js"
 export type {
-  GetIntentCallsPayloadsReturn,
   OriginCallParams,
   QuoteProvider,
   TrailsFee,
@@ -21,15 +24,20 @@ export type {
 export {
   calculateIntentAddress,
   calculateOriginAndDestinationIntentAddresses,
-  commitIntentConfig,
-  getIntentCallsPayloads,
+  commitIntent,
+  getIntent,
   sendOriginTransaction,
 } from "./intents.js"
-export type {
-  MetaTxn,
-  MetaTxnStatus,
-} from "./metaTxnMonitor.js"
-export { useMetaTxnsMonitor } from "./metaTxnMonitor.js"
+export type { IntentReceiptStatus } from "./intentReceiptMonitor.js"
+export { useIntentReceiptMonitor } from "./intentReceiptMonitor.js"
+export {
+  pollIntentReceipt,
+  type IntentReceiptPollerOptions,
+  type IntentReceiptPollerCallbacks,
+  type OnOriginTransactionFound,
+  type OnDestinationTransactionFound,
+  type OnReceiptUpdate,
+} from "./intentReceiptPoller.js"
 export {
   prepareSend,
   useQuote,
@@ -82,20 +90,20 @@ export type { SupportedToken } from "./tokens.js"
 export { getTxTimeDiff } from "./transactions.js"
 export { useTrails } from "./trails.js"
 export type { WagmiAccount } from "./trails.js"
+export {
+  useCommitIntent,
+  useExecuteIntent,
+} from "./mutations.js"
 export type { Mode } from "./mode.js"
 export { TRAILS_ROUTER_PLACEHOLDER_AMOUNT } from "./trailsRouter.js"
 export { getERC20TransferData } from "./encoders.js"
-export { getRelayer, useRelayers } from "./relayer.js"
-export { relayerSendMetaTx, getMetaTxnReceipt } from "./metaTxns.js"
 export {
   declareSequenceEnv,
   getSequenceProjectAccessKey,
-  getSequenceApiUrl,
   getTrailsApiUrl,
   getSequenceIndexerUrl,
   getSequenceEnv,
   setSequenceProjectAccessKey,
-  setSequenceApiUrl,
   setTrailsApiUrl,
   setSequenceIndexerUrl,
   setSequenceNodeGatewayUrl,
@@ -115,3 +123,17 @@ export {
   useTrailsClient,
   TrailsClient,
 } from "./trailsClient.js"
+export type {
+  IntentReceipt,
+  IntentTransaction as IntentTransactionReceipt,
+  IntentStatus,
+  TransactionStatus,
+  WaitIntentReceiptRequest,
+  WaitIntentReceiptResponse,
+  GetIntentReceiptRequest,
+  GetIntentReceiptResponse,
+  QuoteIntentRequest,
+  Intent,
+  ExecuteIntentRequest,
+  ExecuteIntentResponse,
+} from "@0xsequence/trails-api"

package/src/intentReceiptMonitor.ts

@@ -0,0 +1,102 @@
+import type { TrailsClient } from "./trailsClient.js"
+import type {
+  IntentReceipt,
+  WaitIntentReceiptResponse,
+} from "@0xsequence/trails-api"
+import { type Query, useQuery } from "@tanstack/react-query"
+import { logger } from "./logger.js"
+
+const POLL_INTERVAL = 150 // 150 ms
+
+export type IntentReceiptStatus = {
+  intentReceipt: IntentReceipt | null
+  done: boolean
+  isLoading: boolean
+  isError: boolean
+  error: Error | null
+}
+
+/**
+ * Hook to monitor intent execution status using the WaitIntentReceipt API.
+ * This replaces the old useMetaTxnsMonitor approach which polled individual meta-transactions.
+ *
+ * The WaitIntentReceipt API is a long-polling endpoint that:
+ * - Blocks up to 28 seconds waiting for status changes
+ * - Returns unified status for both origin and destination transactions
+ * - Sets done=true when intent reaches terminal status (SUCCEEDED or FAILED)
+ *
+ * @param intentId - The intent ID to monitor (usually committedOriginIntentAddress)
+ * @param trailsClient - TrailsClient instance for API calls
+ * @returns IntentReceiptStatus with current receipt, done flag, and loading states
+ */
+export const useIntentReceiptMonitor = (
+  intentId: string | undefined,
+  trailsClient: TrailsClient,
+): IntentReceiptStatus => {
+  const queryResult = useQuery({
+    queryKey: ["waitIntentReceipt", intentId],
+    queryFn: async (): Promise<WaitIntentReceiptResponse> => {
+      if (!intentId) {
+        throw new Error("Intent ID is required for monitoring")
+      }
+
+      logger.console.log(
+        `[trails-sdk] 🔍 Monitoring intent receipt for ${intentId}`,
+      )
+
+      const response = await trailsClient.waitIntentReceipt({
+        intentId,
+      })
+
+      logger.console.log(
+        `[trails-sdk] 📊 Intent ${intentId} status: ${response.intentReceipt.status}, done: ${response.done}`,
+      )
+
+      return response
+    },
+    enabled: !!intentId,
+    refetchIntervalInBackground: true,
+    refetchInterval: (
+      query: Query<
+        WaitIntentReceiptResponse,
+        Error,
+        WaitIntentReceiptResponse,
+        ReadonlyArray<unknown>
+      >,
+    ) => {
+      const data = query.state.data
+
+      // If no data yet, continue polling
+      if (!data) return POLL_INTERVAL
+
+      // If done flag is true, stop polling
+      if (data.done) {
+        logger.console.log(
+          `[trails-sdk] ✅ Intent monitoring complete for ${intentId}`,
+        )
+        return false
+      }
+
+      // Otherwise continue polling
+      return POLL_INTERVAL
+    },
+    retry: (failureCount: number, error: Error) => {
+      if (failureCount >= 30) {
+        logger.console.error(
+          `[trails-sdk] ❌ Giving up on intent ${intentId} after 30 failed API attempts:`,
+          error,
+        )
+        return false
+      }
+      return true
+    },
+  })
+
+  return {
+    intentReceipt: queryResult.data?.intentReceipt ?? null,
+    done: queryResult.data?.done ?? false,
+    isLoading: queryResult.isLoading,
+    isError: queryResult.isError,
+    error: queryResult.error,
+  }
+}

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
+  }
+}