fix(checkout): resume wallet routes by right identifier and re-attach

- Poll relayer/gasless routes by taskId, not as a txHash (distinct keys in
  the SDK status API), so they no longer hang on NOT_FOUND
- Resume an unfinished wallet route (in flight or failed) on the execution
  page so the SDK re-prompts/retries, instead of the poll-only status page
- Re-seed an evicted route from the 24h snapshot before resuming

Author: tomiiide

.changeset/checkout-resume-identifier-and-execution.md

@@ -0,0 +1,10 @@
+---
+"@lifi/widget-checkout": minor
+"@lifi/widget": minor
+---
+
+Fix wallet-flow resume to poll the correct status identifier and re-attach in-flight routes.
+
+A resumed wallet payment now polls by the right identifier: relayer/gasless routes carry a `taskId`, which is distinct from a `txHash` in the SDK status API and was previously polled as a hash (so it never resolved). A still-executing wallet route is now resumed through the SDK on the transaction page, so it prompts for any remaining user action (a second source-chain signature, a destination-chain claim) instead of sitting on a status page it cannot advance. Routes evicted from the route store are re-seeded from the persisted snapshot before resuming.
+
+`@lifi/widget` exports `isRouteActive`, `isRouteDone`, `isRouteFailed`, and the route-execution store accessors from `@lifi/widget/shared`.

packages/widget-checkout/src/hooks/useCheckoutPendingRecords.test.tsx

@@ -5,7 +5,12 @@ import { renderHook, waitFor } from '@testing-library/react'
 import type { ReactNode } from 'react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
-vi.mock('@lifi/widget/shared', () => ({ useSDKClient: () => ({}) }))
+vi.mock('@lifi/widget/shared', () => ({
+  useSDKClient: () => ({}),
+  useRouteExecutionStore: (selector: (s: { routes: object }) => unknown) =>
+    selector({ routes: {} }),
+  isRouteFailed: () => false,
+}))
 vi.mock('@lifi/widget-provider/checkout', () => ({
   useCheckoutConfig: () => ({ integrator: 'int' }),
 }))

packages/widget-checkout/src/hooks/useCheckoutPendingRecords.ts

@@ -1,6 +1,10 @@
 'use client'
 import { getStatus, type StatusResponse } from '@lifi/sdk'
-import { useSDKClient } from '@lifi/widget/shared'
+import {
+  isRouteFailed,
+  useRouteExecutionStore,
+  useSDKClient,
+} from '@lifi/widget/shared'
 import { useCheckoutConfig } from '@lifi/widget-provider/checkout'
 import { useQueries } from '@tanstack/react-query'
 import { useEffect, useMemo } from 'react'
@@ -14,6 +18,7 @@ import { extractStatusHints } from '../utils/statusHints.js'
 import {
   computeBackoffInterval,
   depositAddressQueryKey,
+  taskIdQueryKey,
   txHashQueryKey,
 } from '../utils/statusPolling.js'
 
@@ -39,6 +44,7 @@ export function useCheckoutPendingRecords(): PendingActivityItem[] {
   const records = usePendingCheckoutStore((s) => s.records)
   const clearForKey = usePendingCheckoutStore((s) => s.clearForKey)
   const markFailed = usePendingCheckoutStore((s) => s.markFailed)
+  const storedRoutes = useRouteExecutionStore((s) => s.routes)
 
   const entries = useMemo(() => {
     const now = Date.now()
@@ -63,6 +69,11 @@ export function useCheckoutPendingRecords(): PendingActivityItem[] {
         !canPollByDeposit &&
         !!record.transactionHash &&
         record.status !== 'failed'
+      const canPollByTaskId =
+        !canPollByDeposit &&
+        !canPollByHash &&
+        !!record.taskId &&
+        record.status !== 'failed'
       let queryKey: readonly unknown[]
       if (canPollByDeposit) {
         queryKey = depositAddressQueryKey(
@@ -71,6 +82,8 @@ export function useCheckoutPendingRecords(): PendingActivityItem[] {
         )
       } else if (canPollByHash) {
         queryKey = txHashQueryKey(record.transactionHash)
+      } else if (canPollByTaskId) {
+        queryKey = taskIdQueryKey(record.taskId)
       } else {
         queryKey = ['checkout-activity-idle', key]
       }
@@ -89,6 +102,16 @@ export function useCheckoutPendingRecords(): PendingActivityItem[] {
               signal,
             })
           }
+          if (canPollByTaskId) {
+            return getStatus(
+              sdkClient,
+              {
+                taskId: record.taskId as string,
+                ...extractStatusHints(record.frozenQuote?.route),
+              },
+              { signal }
+            )
+          }
           return getStatus(
             sdkClient,
             {
@@ -98,7 +121,7 @@ export function useCheckoutPendingRecords(): PendingActivityItem[] {
             { signal }
           )
         },
-        enabled: canPollByDeposit || canPollByHash,
+        enabled: canPollByDeposit || canPollByHash || canPollByTaskId,
         refetchInterval: () => computeBackoffInterval(record.createdAt),
       }
     }),
@@ -138,13 +161,20 @@ export function useCheckoutPendingRecords(): PendingActivityItem[] {
   return entries.map(([key, record], i) => {
     const data = results[i]?.data
     const depositDetected = Boolean(data && data.status !== 'NOT_FOUND')
+    // A wallet route can fail locally (e.g. a rejected signature) with no
+    // pollable status — use the route store's verdict so the card isn't stuck.
+    const storedRoute =
+      record.fundingSource === 'wallet' && record.frozenRouteId
+        ? storedRoutes[record.frozenRouteId]?.route
+        : undefined
     let state: PendingActivityState
     if (data?.substatus === 'REFUND_IN_PROGRESS') {
       state = 'refund'
     } else if (
       data?.status === 'FAILED' ||
       data?.status === 'INVALID' ||
-      record.status === 'failed'
+      record.status === 'failed' ||
+      (storedRoute && isRouteFailed(storedRoute))
     ) {
       state = 'failed'
     } else {

packages/widget-checkout/src/hooks/useCheckoutTransactionStatus.ts

@@ -8,6 +8,7 @@ import type { HashStatusHints } from '../utils/statusHints.js'
 import {
   computeBackoffInterval,
   depositAddressQueryKey,
+  taskIdQueryKey,
   txHashQueryKey,
 } from '../utils/statusPolling.js'
 
@@ -22,6 +23,8 @@ export interface CheckoutTransactionStatus {
 
 export interface UseCheckoutTransactionStatusArgs {
   transactionHash?: string | null
+  /** Relayer/gasless task id; distinct from transactionHash in the status API. */
+  taskId?: string | null
   depositAddress?: string | null
   fromChain?: number | null
   /**
@@ -40,24 +43,28 @@ export interface UseCheckoutTransactionStatusArgs {
 
 export const useCheckoutTransactionStatus = ({
   transactionHash,
+  taskId,
   depositAddress,
   fromChain,
   pauseDepositPoll,
   statusHints,
 }: UseCheckoutTransactionStatusArgs): CheckoutTransactionStatus => {
   const sdkClient = useSDKClient()
-  // Deposit-funded flows (and IF wallet routes) poll by deposit address; the tx
-  // hash is a display/details supplement there. A wallet payment on a non-IF
-  // route has no deposit address, so it polls status by hash instead.
+  // Deposit-funded flows poll by deposit address (hash/taskId are display-only
+  // there). A non-IF wallet payment has no deposit address, so it polls by hash,
+  // or by taskId for a relayer route — distinct keys in the SDK status API.
   const canPollByDeposit = !!depositAddress && !!fromChain && !pauseDepositPoll
   const canPollByHash = !!transactionHash && !canPollByDeposit
-  const enabled = canPollByHash || canPollByDeposit
+  const canPollByTaskId = !!taskId && !canPollByDeposit && !canPollByHash
+  const enabled = canPollByDeposit || canPollByHash || canPollByTaskId
 
   // Same key as the QR-page poll when we're polling by deposit address —
   // react-query shares the cache entry so the handoff is instant.
   const queryKey = canPollByDeposit
     ? depositAddressQueryKey(depositAddress, fromChain)
-    : txHashQueryKey(transactionHash)
+    : canPollByHash
+      ? txHashQueryKey(transactionHash)
+      : taskIdQueryKey(taskId)
 
   // Lazy so the fast-poll backoff window starts when polling actually begins,
   // not when the page mounts (polling may be paused at mount).
@@ -72,20 +79,27 @@ export const useCheckoutTransactionStatus = ({
   const { data, isLoading } = useQuery({
     queryKey,
     queryFn: async ({ signal }) => {
+      if (canPollByDeposit) {
+        return getDepositAddressStatus({
+          sdkClient,
+          depositAddress: depositAddress!,
+          fromChain: fromChain!,
+          signal,
+        })
+      }
       if (canPollByHash) {
         return getStatus(
           sdkClient,
           { txHash: transactionHash!, ...statusHints },
           { signal }
         )
       }
-      if (canPollByDeposit) {
-        return getDepositAddressStatus({
+      if (canPollByTaskId) {
+        return getStatus(
           sdkClient,
-          depositAddress: depositAddress!,
-          fromChain: fromChain!,
-          signal,
-        })
+          { taskId: taskId!, ...statusHints },
+          { signal }
+        )
       }
       return undefined
     },

packages/widget-checkout/src/hooks/usePendingCheckoutWriter.test.tsx

@@ -54,7 +54,7 @@ describe('usePendingCheckoutWriter — resumePending gate', () => {
     })
     act(() => {
       result.current.writeWallet({
-        transactionHash: '0xhash',
+        identifier: { value: '0xhash', kind: 'txHash' },
         fromChain: 1,
         frozenQuote: frozenQuote('route-1'),
       })
@@ -69,7 +69,7 @@ describe('usePendingCheckoutWriter — resumePending gate', () => {
     })
     act(() => {
       result.current.writeWallet({
-        transactionHash: '0xhash',
+        identifier: { value: '0xhash', kind: 'txHash' },
         fromChain: 1,
         depositAddress: '0xdep',
         frozenQuote: frozenQuote('route-3'),
@@ -80,12 +80,34 @@ describe('usePendingCheckoutWriter — resumePending gate', () => {
     expect(record.fundingSource).toBe('wallet')
     expect(record.depositAddress).toBe('0xdep')
     expect(record.depositId).toBe('0xdep')
+    expect(record.transactionHash).toBe('0xhash')
+    expect(record.taskId).toBeUndefined()
+    // Carries the route id so resume can re-attach to the in-flight route.
+    expect(record.frozenRouteId).toBe('route-3')
     expect(record.frozenQuote?.id).toBe('route-3')
     expect(record.fromAmount).toBe('100000000')
     expect(record.tokenSymbol).toBe('USDC')
     expect(record.tokenDecimals).toBe(6)
   })
 
+  it('writeWallet stores a relayer route under taskId, not transactionHash', () => {
+    const { result } = renderHook(() => usePendingCheckoutWriter(), {
+      wrapper: wrap(true),
+    })
+    act(() => {
+      result.current.writeWallet({
+        identifier: { value: 'task-123', kind: 'taskId' },
+        fromChain: 1,
+        frozenQuote: frozenQuote('route-task'),
+      })
+    })
+    const key = buildResumeKey('int', 'task-123')
+    const record = usePendingCheckoutStore.getState().records[key]
+    expect(record.taskId).toBe('task-123')
+    expect(record.transactionHash).toBeUndefined()
+    expect(record.frozenRouteId).toBe('route-task')
+  })
+
   it('writes when resumePending is explicitly true', () => {
     const { result } = renderHook(() => usePendingCheckoutWriter(), {
       wrapper: wrap(true),
@@ -127,7 +149,7 @@ describe('usePendingCheckoutWriter — resumePending gate', () => {
     })
     act(() => {
       result.current.writeWallet({
-        transactionHash: '0xhash',
+        identifier: { value: '0xhash', kind: 'txHash' },
         fromChain: 1,
         frozenQuote: frozenQuote('route-1'),
       })
@@ -153,7 +175,7 @@ describe('usePendingCheckoutWriter — resumePending gate', () => {
     })
     act(() => {
       result.current.writeWallet({
-        transactionHash: '0xhash',
+        identifier: { value: '0xhash', kind: 'txHash' },
         fromChain: 1,
         frozenQuote: frozenQuote('route-1'),
       })
@@ -181,12 +203,12 @@ describe('usePendingCheckoutWriter — frozen deposit key', () => {
       // First write has only the tx hash; a later write of the same deposit
       // also carries the deposit address. Both must land on one record.
       result.current.writeWallet({
-        transactionHash: '0xhash',
+        identifier: { value: '0xhash', kind: 'txHash' },
         fromChain: 1,
         frozenQuote: frozenQuote('route-1'),
       })
       result.current.writeWallet({
-        transactionHash: '0xhash',
+        identifier: { value: '0xhash', kind: 'txHash' },
         fromChain: 1,
         depositAddress: '0xdep',
         frozenQuote: frozenQuote('route-1'),
@@ -206,7 +228,7 @@ describe('usePendingCheckoutWriter — frozen deposit key', () => {
     })
     act(() => {
       flowA.result.current.writeWallet({
-        transactionHash: '0xAAA',
+        identifier: { value: '0xAAA', kind: 'txHash' },
         fromChain: 1,
         frozenQuote: frozenQuote('route-a'),
       })
@@ -216,7 +238,7 @@ describe('usePendingCheckoutWriter — frozen deposit key', () => {
     })
     act(() => {
       flowB.result.current.writeWallet({
-        transactionHash: '0xBBB',
+        identifier: { value: '0xBBB', kind: 'txHash' },
         fromChain: 1,
         frozenQuote: frozenQuote('route-b'),
       })

packages/widget-checkout/src/hooks/usePendingCheckoutWriter.ts

@@ -9,13 +9,14 @@ import {
   type PersistedFrozenQuote,
   usePendingCheckoutStore,
 } from '../stores/usePendingCheckoutStore.js'
+import type { SourceTxIdentifier } from '../utils/getSourceTxIdentifier.js'
 
 interface WalletWriteArgs {
-  transactionHash: string
+  identifier: SourceTxIdentifier
   fromChain: number
   depositAddress?: string
-  // Required: the activity list and resume derive cross-chain status hints
-  // (bridge/toChain) from this route, so a wallet record must always carry it.
+  // Resume reads cross-chain status hints from this route and uses it to
+  // re-attach the in-flight route, so a wallet record must always carry it.
   frozenQuote: PersistedFrozenQuote
 }
 
@@ -84,23 +85,29 @@ export function usePendingCheckoutWriter(): PendingCheckoutWriter {
 
   const writeWallet = useCallback(
     ({
-      transactionHash,
+      identifier,
       fromChain,
       depositAddress,
       frozenQuote,
     }: WalletWriteArgs) => {
       if (!enabled) {
         return
       }
-      const depositId = resolveDepositId(depositAddress ?? transactionHash)
+      const transactionHash =
+        identifier.kind === 'txHash' ? identifier.value : undefined
+      const taskId = identifier.kind === 'taskId' ? identifier.value : undefined
+      const depositId = resolveDepositId(depositAddress ?? identifier.value)
       write(
         buildResumeKey(integrator, depositId),
         buildPendingRecord({
           depositId,
           fundingSource: 'wallet',
           transactionHash,
+          taskId,
           fromChain,
           depositAddress,
+          // Route id resume uses to re-attach the in-flight route.
+          frozenRouteId: frozenQuote.id,
           frozenQuote,
           ...displayFields(frozenQuote),
           status: 'pending',