0xtrails 0.12.2 → 0.13.0

package/src/transactionIntent/handlers/intentHandler.ts

@@ -22,7 +22,11 @@ import {
   IntentStatus,
 } from "@0xtrails/api"
 import type { PrepareSendReturn, SendReturn, FundMethod } from "../types.js"
-import { TradeType, toApiFundMethod } from "../types.js"
+import {
+  isExternalFundingMethod,
+  TradeType,
+  toApiFundMethod,
+} from "../types.js"
 import type { QueryClient } from "@tanstack/react-query"
 import type { TransactionState } from "../../transactions.js"
 import type { CheckoutOnHandlers } from "../../widget/hooks/useCheckout.js"
@@ -35,6 +39,7 @@ import {
   quoteIntent,
   commitIntent,
   sendOriginTransaction,
+  executeIntent as executeIntentRequest,
 } from "../../intents.js"
 import {
   decodeTokenSweeperEvents,
@@ -65,12 +70,15 @@ import { isNativeToken } from "../../utils/address.js"
 import { ensureErc20Approval } from "../utils/erc20Approval.js"
 import { HOUR_MS } from "../../utils/time.js"
 import { attemptSwitchChain } from "../../chainSwitch.js"
+import { getDoGasless } from "../deposits/gaslessDeposit.js"
 import {
+  applyIntentReceiptToTransactionStates,
   getNormalizedTransactionStates,
-  updateTransactionStateWithDecodedEvents,
   insertRefundTransactionState,
+  updateTransactionStateWithDecodedEvents,
 } from "../helpers/transactionStateHelpers.js"
 import { isSameChain, isSameToken } from "../validators.js"
+import { isSyntheticTransactionHash } from "../../transactions.js"
 
 /**
  * Parameters for the unified intent handler.
@@ -293,6 +301,16 @@ async function executePassthrough(
   // Wait for transaction receipt
   const receipt = await effectivePublicClient.waitForTransactionReceipt({
     hash: finalDepositTransactionHash,
+    onReplaced: (replacement) => {
+      logger.console.log(
+        "[trails-sdk] Passthrough deposit transaction replaced",
+        {
+          reason: replacement.reason,
+          replacedHash: replacement.replacedTransaction.hash,
+          replacementHash: replacement.transaction.hash,
+        },
+      )
+    },
   })
   logger.console.log("[trails-sdk] Passthrough receipt:", receipt)
 
@@ -391,8 +409,6 @@ async function executeIntent(
     selectedFeeOption?: FeeOption | null
     depositTransactionHash?: string
     skipCommit?: boolean
-    commitOnly?: boolean
-    skipIntentMonitoring?: boolean
   },
 ): Promise<SendReturn> {
   const {
@@ -427,7 +443,6 @@ async function executeIntent(
     onOriginSend,
     selectedFeeOption: runtimeSelectedFeeOption,
     depositTransactionHash,
-    commitOnly,
   } = options
 
   const effectiveSelectedFeeOption = runtimeSelectedFeeOption
@@ -466,23 +481,81 @@ async function executeIntent(
   let depositUserTxnReceipt: TransactionReceipt | null = null
   let originIntentTransaction: IntentTransaction | null = null
   let destinationIntentTransaction: IntentTransaction | null = null
+  let hasExecutedIntentEarly = false
 
   // Create destination public client for cross-chain polling
   const destinationPublicClient = getChainRpcClient(params.destinationChainId)
 
-  if (commitOnly) {
-    logger.console.log("[trails-sdk] Commit only mode, returning early")
-    return {
-      depositUserTxnReceipt: null,
-      originIntentTransaction: null,
-      destinationIntentTransaction: null,
+  const shouldUseGaslessFlow =
+    fundMethod === "wallet" &&
+    (getDoGasless(
+      effectiveOriginTokenAddress,
+      gasFeeOptions,
+      effectiveSelectedFeeOption,
+      walletId,
+    ) ||
+      Boolean(paymasterUrl))
+
+  // Signal executeIntent immediately after commit for all funding flows.
+  if (intent.intentId && !shouldUseGaslessFlow) {
+    try {
+      if (executeIntentFn) {
+        await executeIntentFn({
+          intentId: intent.intentId,
+        })
+      } else {
+        await executeIntentRequest(trailsClient, intent.intentId, undefined)
+      }
+      hasExecutedIntentEarly = true
+      logger.console.log(
+        "[trails-sdk] executeIntent called immediately after commit",
+        {
+          intentId: intent.intentId,
+          fundMethod,
+          depositTransactionHash,
+        },
+      )
+    } catch (executeError: unknown) {
+      if (getIsAlreadyExecutingError(executeError)) {
+        hasExecutedIntentEarly = true
+        logger.console.log(
+          "[trails-sdk] Intent already executing after early executeIntent call",
+        )
+      } else {
+        throw executeError
+      }
+    }
+  } else if (intent.intentId && shouldUseGaslessFlow) {
+    logger.console.log(
+      "[trails-sdk] Skipping early executeIntent for gasless flow, waiting for deposit signature",
+      {
+        intentId: intent.intentId,
+        fundMethod,
+        hasPaymasterUrl: Boolean(paymasterUrl),
+        hasSelectedFeeOption: effectiveSelectedFeeOption !== undefined,
+      },
+    )
+  }
+
+  // External funding flows without a client-provided deposit hash should return
+  // immediately after commit/early execute. Their UI will monitor balance at the
+  // origin intent address and continue independently of this send() call.
+  const publishTransactionStates = (states: TransactionState[]) => {
+    onTransactionStateChange(states)
+    if (checkoutOnHandlers?.triggerCheckoutStatusUpdate) {
+      checkoutOnHandlers.triggerCheckoutStatusUpdate(states)
     }
   }
 
-  // For onramp-meld flow without depositTransactionHash, just return after commit
-  if (fundMethod === "onramp-meld" && !depositTransactionHash) {
+  if (isExternalFundingMethod(fundMethod) && !depositTransactionHash) {
+    publishTransactionStates(localTransactionStates)
+
     logger.console.log(
-      "[trails-sdk] Onramp-meld: Intent committed, returning early",
+      "[trails-sdk] External funding flow: intent committed, returning early",
+      {
+        fundMethod,
+        intentId: intent.intentId,
+      },
     )
     return {
       depositUserTxnReceipt: null,
@@ -513,10 +586,7 @@ async function executeIntent(
   })
 
   // Set up transaction state tracking
-  onTransactionStateChange(localTransactionStates)
-  if (checkoutOnHandlers?.triggerCheckoutStatusUpdate) {
-    checkoutOnHandlers.triggerCheckoutStatusUpdate(localTransactionStates)
-  }
+  publishTransactionStates(localTransactionStates)
 
   if (!intent.intentProtocolVersion) {
     logger.console.log(
@@ -540,8 +610,32 @@ async function executeIntent(
   // Execute deposit transaction
   if (depositTransactionHash && fundMethod !== "wallet") {
     // External deposit with provided hash (onramp-meld, direct-transfer, etc.)
-    depositUserTxnReceipt = await effectivePublicClient.getTransactionReceipt({
-      hash: depositTransactionHash as `0x${string}`,
+    let resolvedDepositTransactionHash = depositTransactionHash as `0x${string}`
+    depositUserTxnReceipt =
+      await effectivePublicClient.waitForTransactionReceipt({
+        hash: depositTransactionHash as `0x${string}`,
+        onReplaced: (replacement) => {
+          resolvedDepositTransactionHash = replacement.transaction.hash
+          logger.console.log(
+            "[trails-sdk] External deposit transaction replaced",
+            {
+              reason: replacement.reason,
+              replacedHash: replacement.replacedTransaction.hash,
+              replacementHash: replacement.transaction.hash,
+            },
+          )
+        },
+      })
+
+    if (depositUserTxnReceipt?.transactionHash) {
+      resolvedDepositTransactionHash =
+        depositUserTxnReceipt.transactionHash as `0x${string}`
+    }
+
+    logger.console.log("[trails-sdk] External deposit receipt resolved", {
+      providedHash: depositTransactionHash,
+      resolvedHash: resolvedDepositTransactionHash,
+      status: depositUserTxnReceipt.status,
     })
 
     // Update transaction state with receipt
@@ -551,14 +645,11 @@ async function executeIntent(
         effectiveOriginChainId,
         localTransactionStates[0]?.label,
       )
-      onTransactionStateChange(localTransactionStates)
-      if (checkoutOnHandlers?.triggerCheckoutStatusUpdate) {
-        checkoutOnHandlers.triggerCheckoutStatusUpdate(localTransactionStates)
-      }
+      publishTransactionStates(localTransactionStates)
     }
 
     if (depositUserTxnReceipt.status === "success" && intent.intentId) {
-      // Call onOriginSend to signal deposit was processed (navigates to pending screen)
+      // Always signal external deposit success so UI can navigate to pending.
       if (onOriginSend) {
         logger.console.log(
           "[trails-sdk] Calling onOriginSend for external deposit",
@@ -566,23 +657,28 @@ async function executeIntent(
         onOriginSend()
       }
 
-      // Try to execute the intent, but handle the case where it's already executing
-      // (the system may have auto-started execution when funds were deposited)
-      try {
-        const executeIntentFnToUse =
-          executeIntentFn || trailsClient.executeIntent.bind(trailsClient)
-        await executeIntentFnToUse({
-          intentId: intent.intentId,
-          depositTransactionHash,
-        })
-      } catch (executeError: unknown) {
-        // If intent is already executing, that's fine - it means the system picked it up
-        if (getIsAlreadyExecutingError(executeError)) {
-          logger.console.log(
-            "[trails-sdk] Intent already executing, continuing...",
-          )
-        } else {
-          throw executeError
+      if (hasExecutedIntentEarly) {
+        // Intent execution was already triggered immediately after commit.
+        // Skip the duplicate executeIntent call, but continue into receipt polling.
+      } else {
+        // Try to execute the intent if early execution didn't run.
+        try {
+          if (executeIntentFn) {
+            await executeIntentFn({
+              intentId: intent.intentId,
+            })
+          } else {
+            await executeIntentRequest(trailsClient, intent.intentId, undefined)
+          }
+        } catch (executeError: unknown) {
+          // If intent is already executing, that's fine - it means the system picked it up
+          if (getIsAlreadyExecutingError(executeError)) {
+            logger.console.log(
+              "[trails-sdk] Intent already executing, continuing...",
+            )
+          } else {
+            throw executeError
+          }
         }
       }
     }
@@ -651,38 +747,12 @@ async function executeIntent(
         )
       }
 
-      onTransactionStateChange(localTransactionStates)
-      if (checkoutOnHandlers?.triggerCheckoutStatusUpdate) {
-        checkoutOnHandlers.triggerCheckoutStatusUpdate(localTransactionStates)
-      }
-
-      // Call executeIntent
-      if (depositUserTxnReceipt.status === "success" && intent.intentId) {
-        try {
-          const executeIntentFnToUse =
-            executeIntentFn || trailsClient.executeIntent.bind(trailsClient)
-          await executeIntentFnToUse({
-            intentId: intent.intentId,
-            depositTransactionHash: depositUserTxnReceipt.transactionHash,
-          })
-        } catch (executeError: unknown) {
-          // If intent is already executing (e.g. from early executeIntent call), that's fine
-          if (getIsAlreadyExecutingError(executeError)) {
-            logger.console.log(
-              "[trails-sdk] Intent already executing after deposit, continuing...",
-            )
-          } else {
-            logger.console.error(
-              "[trails-sdk] Error calling executeIntent:",
-              executeError,
-            )
-          }
-        }
-      }
+      publishTransactionStates(localTransactionStates)
     }
   }
   // Start polling for intent completion to update transaction states
   let finalReceipt: Awaited<ReturnType<typeof pollIntentReceipt>> = null
+  let pollStartMs = 0
   if (intent.intentId) {
     // Determine max wait time based on route provider.
     // OFT routes (LayerZero OFT) can take 5-10+ minutes to complete.
@@ -695,18 +765,43 @@ async function executeIntent(
       routeProviders: intent.quote?.routeProviders,
     })
     try {
+      pollStartMs = Date.now()
       finalReceipt = await pollIntentReceipt({
         intentId: intent.intentId,
         trailsClient,
         abortSignal,
         callbacks: {
-          onDepositTransactionFound: async (txHash) => {
+          onDepositTransactionFound: async (txHash, receipt) => {
             logger.console.log(
               "[trails-sdk] Deposit transaction found:",
               txHash,
             )
 
             if (localTransactionStates[0]) {
+              if (isSyntheticTransactionHash(txHash)) {
+                logger.console.log(
+                  "[trails-sdk] Deposit transaction hash is synthetic, marking deposit from status",
+                  {
+                    txHash,
+                    status: receipt.depositTransaction?.status,
+                  },
+                )
+
+                if (receipt.depositTransaction?.status === "SUCCEEDED") {
+                  localTransactionStates[0] = {
+                    ...localTransactionStates[0],
+                    state: "confirmed",
+                    transactionHash: "",
+                    explorerUrl: "",
+                    txnMinedAt:
+                      receipt.depositTransaction?.txnMinedAt || undefined,
+                  }
+
+                  publishTransactionStates(localTransactionStates)
+                }
+                return
+              }
+
               try {
                 const depositTxReceipt =
                   await effectivePublicClient.getTransactionReceipt({
@@ -725,12 +820,7 @@ async function executeIntent(
                 localTransactionStates[0].decodedGuestModuleEvents =
                   decodeGuestModuleEvents(depositTxReceipt)
 
-                onTransactionStateChange(localTransactionStates)
-                if (checkoutOnHandlers?.triggerCheckoutStatusUpdate) {
-                  checkoutOnHandlers.triggerCheckoutStatusUpdate(
-                    localTransactionStates,
-                  )
-                }
+                publishTransactionStates(localTransactionStates)
               } catch (error) {
                 logger.console.error(
                   "[trails-sdk] Error fetching deposit receipt:",
@@ -739,7 +829,7 @@ async function executeIntent(
               }
             }
           },
-          onOriginTransactionFound: async (txHash) => {
+          onOriginTransactionFound: async (txHash, receipt) => {
             logger.console.log("[trails-sdk] Origin transaction found:", txHash)
 
             originIntentTransaction = { txnHash: txHash } as IntentTransaction
@@ -770,12 +860,27 @@ async function executeIntent(
                 ].decodedGuestModuleEvents =
                   decodeGuestModuleEvents(originTxReceipt)
 
-                onTransactionStateChange(localTransactionStates)
-                if (checkoutOnHandlers?.triggerCheckoutStatusUpdate) {
-                  checkoutOnHandlers.triggerCheckoutStatusUpdate(
-                    localTransactionStates,
+                // Some external funding flows do not surface a distinct
+                // depositTransaction in the receipt. In those cases the origin
+                // transaction implicitly covers the deposit step as well.
+                if (
+                  !receipt.depositTransaction?.txnHash &&
+                  !receipt.depositTransaction?.status &&
+                  localTransactionStates.length > 1 &&
+                  localTransactionStates[0]
+                ) {
+                  localTransactionStates[0] = getTransactionStateFromReceipt(
+                    originTxReceipt,
+                    effectiveOriginChainId,
+                    localTransactionStates[0]?.label,
                   )
+                  localTransactionStates[0].decodedTokenSweeperEvents =
+                    decodeTokenSweeperEvents(originTxReceipt)
+                  localTransactionStates[0].decodedGuestModuleEvents =
+                    decodeGuestModuleEvents(originTxReceipt)
                 }
+
+                publishTransactionStates(localTransactionStates)
               }
             } catch (error) {
               logger.console.error(
@@ -820,12 +925,7 @@ async function executeIntent(
                 ].decodedGuestModuleEvents =
                   decodeGuestModuleEvents(destinationTxReceipt)
 
-                onTransactionStateChange(localTransactionStates)
-                if (checkoutOnHandlers?.triggerCheckoutStatusUpdate) {
-                  checkoutOnHandlers.triggerCheckoutStatusUpdate(
-                    localTransactionStates,
-                  )
-                }
+                publishTransactionStates(localTransactionStates)
               }
             } catch (error) {
               logger.console.error(
@@ -844,6 +944,15 @@ async function executeIntent(
               hasRefund: !!receipt.refundTransaction,
             })
 
+            const reconciledStates = applyIntentReceiptToTransactionStates({
+              currentStates: localTransactionStates,
+              receipt,
+            })
+            if (reconciledStates.changed) {
+              localTransactionStates = reconciledStates.transactionStates
+              publishTransactionStates(localTransactionStates)
+            }
+
             // Handle terminal status - mark pending steps as aborted/failed
             if (
               done &&
@@ -863,12 +972,7 @@ async function executeIntent(
                 }
               }
 
-              onTransactionStateChange(localTransactionStates)
-              if (checkoutOnHandlers?.triggerCheckoutStatusUpdate) {
-                checkoutOnHandlers.triggerCheckoutStatusUpdate(
-                  localTransactionStates,
-                )
-              }
+              publishTransactionStates(localTransactionStates)
             }
 
             // Handle deposit tx revert - mark all txs as failed
@@ -883,12 +987,7 @@ async function executeIntent(
                 }
               }
 
-              onTransactionStateChange(localTransactionStates)
-              if (checkoutOnHandlers?.triggerCheckoutStatusUpdate) {
-                checkoutOnHandlers.triggerCheckoutStatusUpdate(
-                  localTransactionStates,
-                )
-              }
+              publishTransactionStates(localTransactionStates)
             }
 
             // Insert refund transaction state if refund exists
@@ -911,12 +1010,7 @@ async function executeIntent(
               if (statesChanged) {
                 localTransactionStates.length = 0
                 localTransactionStates.push(...updatedStates)
-                onTransactionStateChange(localTransactionStates)
-                if (checkoutOnHandlers?.triggerCheckoutStatusUpdate) {
-                  checkoutOnHandlers.triggerCheckoutStatusUpdate(
-                    localTransactionStates,
-                  )
-                }
+                publishTransactionStates(localTransactionStates)
               }
             }
           },
@@ -931,22 +1025,43 @@ async function executeIntent(
         IntentStatus.REFUNDED,
         IntentStatus.ABORTED,
       ]
+      const summary = (
+        finalReceipt as unknown as { summary?: { finishedAt?: string | null } }
+      )?.summary
+      const hasFinishedMarker = Boolean(
+        summary?.finishedAt ||
+          finalReceipt?.destinationTransaction?.txnMinedAt ||
+          finalReceipt?.destinationTransaction?.txnHash,
+      )
+      const destinationSucceeded =
+        finalReceipt?.destinationTransaction?.status === "SUCCEEDED"
+      const completeViaDestinationFallback =
+        !!finalReceipt && destinationSucceeded && hasFinishedMarker
       const isComplete =
-        finalReceipt && terminalStatuses.includes(finalReceipt.status)
+        !!finalReceipt &&
+        (terminalStatuses.includes(finalReceipt.status) ||
+          completeViaDestinationFallback)
 
       if (!isComplete) {
-        // Intent still executing after timeout - don't report success
+        const elapsedMs = pollStartMs > 0 ? Date.now() - pollStartMs : 0
+        const timedOut = elapsedMs >= maxWaitTime
+        const reason = timedOut
+          ? `Intent execution timed out after ${Math.round(maxWaitTime / 60000)} minutes.`
+          : "Unable to confirm final intent status from receipt polling."
+
         logger.console.warn(
-          "[trails-sdk] Intent polling timed out before reaching terminal status",
+          "[trails-sdk] Intent polling ended without terminal status",
           {
             intentId: intent.intentId,
             status: finalReceipt?.status,
             maxWaitTime,
+            elapsedMs,
+            timedOut,
           },
         )
 
         trackPaymentError({
-          error: `Transaction still in progress after ${Math.round(maxWaitTime / 60000)} minutes - please check transaction history`,
+          error: `${reason} Please check transaction history or query GetIntentReceipt.`,
           userAddress: account.address,
           mode,
           fundMethod,
@@ -957,12 +1072,12 @@ async function executeIntent(
 
         if (checkoutOnHandlers?.triggerCheckoutError) {
           checkoutOnHandlers.triggerCheckoutError(
-            "Transaction still in progress - please check your transaction history for the final status",
+            "Unable to confirm final transaction status",
           )
         }
 
         throw new Error(
-          `Intent execution timed out after ${Math.round(maxWaitTime / 60000)} minutes - transaction still in progress. Please check your transaction history for the final status.`,
+          `${reason} Please check transaction history or query GetIntentReceipt with this intent ID.`,
         )
       }
     } catch (error) {
@@ -1375,7 +1490,7 @@ export async function handleIntent(
     quote,
     feeOptions: gasFeeOptions,
     send: async (options) => {
-      const { skipCommit, commitOnly, skipIntentMonitoring } = options
+      const { skipCommit } = options
 
       try {
         // Recalculate passthrough decision at send time based on fee option.
@@ -1426,19 +1541,12 @@ export async function handleIntent(
 
             const commitIntentFnToUse =
               commitIntentFn ||
-              ((intent: Intent, options?: { skipIntentMonitoring?: boolean }) =>
-                commitIntent(
-                  trailsClient,
-                  intent,
-                  {
-                    originTokenSymbol,
-                    destinationTokenSymbol,
-                  },
-                  {
-                    skipIntentMonitoring: options?.skipIntentMonitoring,
-                  },
-                ))
-            await commitIntentFnToUse(intent, { skipIntentMonitoring })
+              ((intent: Intent) =>
+                commitIntent(trailsClient, intent, {
+                  originTokenSymbol,
+                  destinationTokenSymbol,
+                }))
+            await commitIntentFnToUse(intent)
 
             logger.console.log("[trails-sdk] Intent committed successfully")
           } catch (error) {
@@ -1447,18 +1555,6 @@ export async function handleIntent(
           }
         }
 
-        if (commitOnly) {
-          // Handle commit-only case
-          if (!sendUsePassthrough) {
-            await commitIntentIfNeeded()
-          }
-          return {
-            depositUserTxnReceipt: null,
-            originIntentTransaction: null,
-            destinationIntentTransaction: null,
-          }
-        }
-
         if (sendUsePassthrough && sendDepositTransaction) {
           return executePassthrough(
             params,