@lifi/widget 0.0.0-preview-6cc63bac

package/src/hooks/usePacedRouteExecution.ts

@@ -0,0 +1,45 @@
+import type { ExchangeRateUpdateParams, RouteExtended } from '@lifi/sdk'
+import { useMemo } from 'react'
+import { RouteExecutionStatus } from '../stores/routes/types.js'
+import { usePacedValue } from './usePacedValue.js'
+import { useRouteExecution } from './useRouteExecution.js'
+
+interface PacedRouteExecutionProps {
+  routeId: string
+  onAcceptExchangeRateUpdate?(
+    resolver: (value: boolean) => void,
+    data: ExchangeRateUpdateParams
+  ): void
+}
+
+/**
+ * Wraps {@link useRouteExecution} and paces `route`/`status` so the
+ * `ExecutionStatusCard` animation has time to play between updates. Only the
+ * display is paced — events and store writes happen at the SDK's real speed.
+ */
+export function usePacedRouteExecution({
+  routeId,
+  onAcceptExchangeRateUpdate,
+}: PacedRouteExecutionProps): {
+  executeRoute: () => void
+  restartRoute: () => void
+  deleteRoute: () => void
+  route: RouteExtended | undefined
+  status: RouteExecutionStatus | undefined
+} {
+  const { executeRoute, restartRoute, deleteRoute, route, status } =
+    useRouteExecution({ routeId, onAcceptExchangeRateUpdate })
+
+  // Pace route and status as one value so they always match. Skip pacing while
+  // Idle, so the review screen shows live data.
+  const live = useMemo(() => ({ route, status }), [route, status])
+  const display = usePacedValue(live, status !== RouteExecutionStatus.Idle)
+
+  return {
+    executeRoute,
+    restartRoute,
+    deleteRoute,
+    route: display.route,
+    status: display.status,
+  }
+}

package/src/hooks/usePacedValue.ts

@@ -0,0 +1,45 @@
+import { useEffect, useRef, useState } from 'react'
+
+/** Smallest gap between UI updates, in milliseconds. */
+const DISPLAY_INTERVAL = 1200
+
+/**
+ * Returns `live`, but changes it at most once every {@link DISPLAY_INTERVAL}
+ * milliseconds. If `live` changes several times within that window, only the
+ * newest value is shown.
+ *
+ * Set `paced` to `false` to turn this off and update on every change.
+ */
+export function usePacedValue<T>(live: T, paced = true): T {
+  const [value, setValue] = useState(live)
+
+  const shown = useRef(live)
+  // 0 so the first update shows immediately, then throttles.
+  const windowStart = useRef(0)
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+
+  useEffect(() => {
+    if (live === shown.current) {
+      return
+    }
+    if (!paced) {
+      shown.current = live
+      setValue(live)
+      return
+    }
+    const show = () => {
+      windowStart.current = Date.now()
+      shown.current = live
+      setValue(live)
+    }
+    const remaining = windowStart.current + DISPLAY_INTERVAL - Date.now()
+    if (remaining <= 0) {
+      show()
+      return
+    }
+    timer.current = setTimeout(show, remaining)
+    return () => clearTimeout(timer.current)
+  }, [live, paced])
+
+  return value
+}

package/src/hooks/useRouteExecution.ts

@@ -0,0 +1,246 @@
+import type { ExchangeRateUpdateParams, Route, RouteExtended } from '@lifi/sdk'
+import { executeRoute, resumeRoute, updateRouteExecution } from '@lifi/sdk'
+import { useAccount } from '@lifi/wallet-management'
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { useCallback, useEffect, useRef } from 'react'
+import { useSDKClient } from '../providers/SDKClientProvider.js'
+import { useWidgetConfig } from '../providers/WidgetProvider/WidgetProvider.js'
+import {
+  useRouteExecutionStore,
+  useRouteExecutionStoreContext,
+} from '../stores/routes/RouteExecutionStore.js'
+import type { RouteExecutionStatus } from '../stores/routes/types.js'
+import {
+  getUpdatedAction,
+  isRouteActive,
+  isRouteDone,
+  isRouteFailed,
+} from '../stores/routes/utils.js'
+import { WidgetEvent } from '../types/events.js'
+import { getQueryKey } from '../utils/queries.js'
+import { useWidgetEvents } from './useWidgetEvents.js'
+
+interface RouteExecutionProps {
+  routeId: string
+  executeInBackground?: boolean
+  onAcceptExchangeRateUpdate?(
+    resolver: (value: boolean) => void,
+    data: ExchangeRateUpdateParams
+  ): void
+}
+
+export const useRouteExecution = ({
+  routeId,
+  executeInBackground,
+  onAcceptExchangeRateUpdate,
+}: RouteExecutionProps): {
+  executeRoute: () => void
+  restartRoute: () => void
+  deleteRoute: () => void
+  route: RouteExtended | undefined
+  status: RouteExecutionStatus | undefined
+} => {
+  const queryClient = useQueryClient()
+  const { account } = useAccount()
+  const resumedAfterMount = useRef(false)
+  const { keyPrefix } = useWidgetConfig()
+  const sdkClient = useSDKClient()
+  const emitter = useWidgetEvents()
+  const routeExecutionStoreContext = useRouteExecutionStoreContext()
+  const routeExecution = useRouteExecutionStore(
+    (state) => state.routes[routeId]
+  )
+  const [updateRoute, deleteRoute] = useRouteExecutionStore((state) => [
+    state.updateRoute,
+    state.deleteRoute,
+  ])
+
+  const updateRouteHook = (updatedRoute: Route) => {
+    const routeExecution =
+      routeExecutionStoreContext.getState().routes[updatedRoute.id]
+    if (!routeExecution) {
+      return
+    }
+    const clonedUpdatedRoute = structuredClone(updatedRoute)
+    updateRoute(clonedUpdatedRoute)
+    const action = getUpdatedAction(routeExecution.route, clonedUpdatedRoute)
+    if (action) {
+      emitter.emit(WidgetEvent.RouteExecutionUpdated, {
+        route: clonedUpdatedRoute,
+        action,
+      })
+    }
+    const executionCompleted = isRouteDone(clonedUpdatedRoute)
+    const executionFailed = isRouteFailed(clonedUpdatedRoute)
+    if (executionCompleted) {
+      emitter.emit(WidgetEvent.RouteExecutionCompleted, clonedUpdatedRoute)
+    }
+    if (executionFailed && action) {
+      emitter.emit(WidgetEvent.RouteExecutionFailed, {
+        route: clonedUpdatedRoute,
+        action,
+      })
+    }
+    if (executionCompleted || executionFailed) {
+      const invalidateKeys = [
+        [
+          getQueryKey('token-balances', keyPrefix),
+          clonedUpdatedRoute.fromAddress,
+          clonedUpdatedRoute.fromChainId,
+        ],
+        [
+          getQueryKey('token-balances', keyPrefix),
+          clonedUpdatedRoute.toAddress,
+          clonedUpdatedRoute.toChainId,
+        ],
+        [getQueryKey('transaction-history', keyPrefix)],
+      ]
+      for (const key of invalidateKeys) {
+        queryClient.invalidateQueries(
+          {
+            queryKey: key,
+            exact: false,
+            refetchType: 'all',
+          },
+          { cancelRefetch: false }
+        )
+      }
+    }
+    // biome-ignore lint/suspicious/noConsole: logs route information
+    console.log('Route updated.', clonedUpdatedRoute)
+  }
+
+  const acceptExchangeRateUpdateHook = async (
+    params: ExchangeRateUpdateParams
+  ) => {
+    if (!onAcceptExchangeRateUpdate) {
+      return false
+    }
+
+    const accepted = await new Promise<boolean>((resolve) =>
+      onAcceptExchangeRateUpdate(resolve, params)
+    )
+
+    return accepted
+  }
+
+  const executeRouteMutation = useMutation({
+    mutationFn: () => {
+      if (!account.isConnected) {
+        throw new Error('Account is not connected.')
+      }
+      if (!routeExecution?.route) {
+        throw new Error('Execution route not found.')
+      }
+      queryClient.removeQueries({
+        queryKey: [getQueryKey('routes', keyPrefix)],
+        exact: false,
+      })
+      return executeRoute(sdkClient, routeExecution.route, {
+        updateRouteHook,
+        acceptExchangeRateUpdateHook,
+        executeInBackground,
+        ...sdkClient.config?.executionOptions,
+      })
+    },
+    onMutate: () => {
+      // biome-ignore lint/suspicious/noConsole: logs route information
+      console.log('Execution started.', routeId)
+      if (routeExecution) {
+        emitter.emit(WidgetEvent.RouteExecutionStarted, routeExecution.route)
+      }
+    },
+    onError: (error) => {
+      console.warn('Execution failed!', routeId, error)
+    },
+    onSuccess: (route: Route) => {
+      // biome-ignore lint/suspicious/noConsole: logs route information
+      console.log('Executed successfully!', route)
+    },
+  })
+
+  const resumeRouteMutation = useMutation({
+    mutationFn: (args?: { route?: Route; executeInBackground?: boolean }) => {
+      if (!account.isConnected) {
+        throw new Error('Account is not connected.')
+      }
+      if (!routeExecution?.route) {
+        throw new Error('Execution route not found.')
+      }
+      return resumeRoute(sdkClient, args?.route ?? routeExecution.route, {
+        updateRouteHook,
+        acceptExchangeRateUpdateHook,
+        executeInBackground: args?.executeInBackground ?? executeInBackground,
+      })
+    },
+    onMutate: () => {
+      // biome-ignore lint/suspicious/noConsole: logs route information
+      console.log('Resumed to execution.', routeId)
+    },
+    onError: (error) => {
+      console.warn('Resumed execution failed.', routeId, error)
+    },
+    onSuccess: (route) => {
+      // biome-ignore lint/suspicious/noConsole: logs route information
+      console.log('Resumed execution successful.', route)
+    },
+  })
+
+  const _executeRoute = useCallback(() => {
+    executeRouteMutation.mutateAsync(undefined)
+  }, [executeRouteMutation])
+
+  const _resumeRoute = useCallback(
+    (route?: Route) => {
+      resumeRouteMutation.mutateAsync({ route })
+    },
+    [resumeRouteMutation]
+  )
+
+  const restartRouteMutation = useCallback(() => {
+    resumeRouteMutation.mutateAsync({
+      route: routeExecution?.route,
+      executeInBackground: false,
+    })
+  }, [resumeRouteMutation, routeExecution?.route])
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: run only when routeId changes
+  const deleteRouteMutation = useCallback(() => {
+    deleteRoute(routeId)
+  }, [routeId])
+
+  // Resume route execution after page reload
+  // biome-ignore lint/correctness/useExhaustiveDependencies: run only when routeId changes
+  useEffect(() => {
+    // Check if route is eligible for automatic resuming
+    const route = routeExecutionStoreContext.getState().routes[routeId]?.route
+    if (
+      isRouteActive(route) &&
+      account.isConnected &&
+      !resumedAfterMount.current
+    ) {
+      resumedAfterMount.current = true
+      _resumeRoute()
+    }
+
+    // Move execution to background on unmount
+    return () => {
+      const route = routeExecutionStoreContext.getState().routes[routeId]?.route
+      if (!route || !isRouteActive(route)) {
+        return
+      }
+      updateRouteExecution(route, { executeInBackground: true })
+      // biome-ignore lint/suspicious/noConsole: logs route information
+      console.log('Move route execution to background.', routeId)
+      resumedAfterMount.current = false
+    }
+  }, [account.isConnected, routeExecutionStoreContext, routeId])
+
+  return {
+    executeRoute: _executeRoute,
+    restartRoute: restartRouteMutation,
+    deleteRoute: deleteRouteMutation,
+    route: routeExecution?.route,
+    status: routeExecution?.status,
+  }
+}

package/src/hooks/useRouteExecutionMessage.ts

@@ -0,0 +1,100 @@
+import type { ExecutionActionType, RouteExtended } from '@lifi/sdk'
+import { useTranslation } from 'react-i18next'
+import { useWidgetConfig } from '../providers/WidgetProvider/WidgetProvider.js'
+import { RouteExecutionStatus } from '../stores/routes/types.js'
+import { getActionMessage } from '../utils/getActionMessage.js'
+import { getErrorMessage } from '../utils/getErrorMessage.js'
+import { useAvailableChains } from './useAvailableChains.js'
+
+export const useRouteExecutionMessage = (
+  route: RouteExtended,
+  status: RouteExecutionStatus
+): { title: string | undefined; message: string | undefined } => {
+  const { mode, modeOptions } = useWidgetConfig()
+  const { t } = useTranslation()
+  const { getChainById } = useAvailableChains()
+
+  const transactionType =
+    route.fromChainId === route.toChainId ? 'swap' : 'bridge'
+
+  let title: string | undefined
+  let message: string | undefined
+
+  switch (status) {
+    case RouteExecutionStatus.Pending: {
+      // Use the first executing step, not the last one — in a multi-step route
+      // the active step is often not the last.
+      const activeStep =
+        route.steps.find(
+          (s) =>
+            s.execution?.status === 'PENDING' ||
+            s.execution?.status === 'ACTION_REQUIRED'
+        ) ?? route.steps.at(-1)
+      const lastAction = activeStep?.execution?.actions?.at(-1)
+      const actionMessage =
+        activeStep && lastAction
+          ? getActionMessage(
+              t,
+              activeStep,
+              lastAction.type,
+              lastAction.status,
+              lastAction.substatus,
+              mode,
+              modeOptions
+            )
+          : undefined
+      // Fall back to a generic title when the step has no action to describe yet
+      // (just after a restart, or before the first action exists).
+      title =
+        actionMessage?.title ?? t(`main.process.${transactionType}.pending`)
+      message = actionMessage?.message
+      break
+    }
+    case RouteExecutionStatus.Done: {
+      title =
+        mode === 'custom'
+          ? t(
+              `success.title.${modeOptions?.custom?.type ?? 'checkout'}Successful`
+            )
+          : t(`success.title.${transactionType}Successful`)
+      break
+    }
+    case RouteExecutionStatus.Done | RouteExecutionStatus.Partial: {
+      title = t(`success.title.${transactionType}PartiallySuccessful`)
+      message = t('success.message.exchangePartiallySuccessful', {
+        tool: route.steps.at(-1)?.toolDetails.name,
+        tokenSymbol: route.steps.at(-1)?.action.toToken.symbol,
+      })
+      break
+    }
+    case RouteExecutionStatus.Done | RouteExecutionStatus.Refunded: {
+      title = t('success.title.refundIssued')
+      message = t('success.message.exchangePartiallySuccessful', {
+        tool: route.steps.at(-1)?.toolDetails.name,
+        tokenSymbol: route.steps.at(-1)?.action.toToken.symbol,
+      })
+      break
+    }
+    case RouteExecutionStatus.Failed: {
+      const step = route.steps.find(
+        (step) => step.execution?.status === 'FAILED'
+      )
+      if (!step) {
+        break
+      }
+      const action = step.execution?.actions?.find(
+        (action) => action.status === 'FAILED'
+      ) || {
+        status: 'FAILED',
+        type: 'EXECUTION' as ExecutionActionType,
+        error: step.execution?.error,
+      } // synthetic action to represent a failed execution with no actions
+      const actionMessage = getErrorMessage(t, getChainById, step, action)
+      title = actionMessage.title
+      message = actionMessage.message
+      break
+    }
+  }
+
+  return { title, message }
+}

package/src/hooks/useRouteRequiredAccountConnection.ts

@@ -0,0 +1,62 @@
+import type { ExtendedChain, Route } from '@lifi/sdk'
+import { useAccount } from '@lifi/wallet-management'
+import { useMemo } from 'react'
+import { useFieldValues } from '../stores/form/useFieldValues.js'
+import { useChain } from './useChain.js'
+
+export const useRouteRequiredAccountConnection = (
+  route?: Route,
+  chain?: ExtendedChain
+): {
+  connected: boolean
+  missingChain?: ExtendedChain
+  missingAccountAddress?: string
+} => {
+  const { account, accounts } = useAccount({ chainType: chain?.chainType })
+  const [toAddress] = useFieldValues('toAddress')
+  const { getChainById } = useChain()
+
+  return useMemo(() => {
+    if (!route?.steps.length) {
+      return {
+        connected: account.isConnected,
+      }
+    }
+
+    const connectedChainTypes = new Map(
+      accounts
+        .filter((account) => account.isConnected && account.address)
+        .map((account) => [account.chainType, account])
+    )
+
+    if (!connectedChainTypes.size) {
+      return {
+        connected: false,
+      }
+    }
+
+    for (const step of route.steps) {
+      const chain = getChainById(step.action.fromChainId)
+      if (!chain) {
+        continue
+      }
+
+      const connectedAccount = connectedChainTypes.get(chain.chainType)
+      const isToAddressSatisfied = toAddress
+        ? connectedAccount?.address === step.action.fromAddress
+        : true
+
+      if (!connectedAccount || !isToAddressSatisfied) {
+        return {
+          connected: false,
+          missingChain: chain,
+          missingAccountAddress: !isToAddressSatisfied
+            ? step.action.fromAddress
+            : undefined,
+        }
+      }
+    }
+
+    return { connected: true }
+  }, [account.isConnected, route, accounts, getChainById, toAddress])
+}