@lifi/sdk 0.0.0-preview-f5cf9f8

package/src/core/actionMessages.ts

@@ -0,0 +1,103 @@
+import type { StatusMessage, Substatus } from '@lifi/types'
+import type {
+  ExecutionActionStatus,
+  ExecutionActionType,
+} from '../types/core.js'
+
+const actionMessages: Record<
+  ExecutionActionType,
+  Partial<Record<ExecutionActionStatus, string>>
+> = {
+  CHECK_ALLOWANCE: {
+    STARTED: 'Checking token allowance',
+    PENDING: 'Waiting for token allowance check',
+    DONE: 'Token allowance checked',
+  },
+  RESET_ALLOWANCE: {
+    STARTED: 'Resetting token allowance',
+    RESET_REQUIRED: 'Resetting token allowance',
+    PENDING: 'Waiting for token allowance reset',
+    DONE: 'Token allowance reset',
+  },
+  SET_ALLOWANCE: {
+    STARTED: 'Setting token allowance',
+    ACTION_REQUIRED: 'Set token allowance',
+    PENDING: 'Waiting for token allowance',
+    DONE: 'Token allowance set',
+  },
+  SWAP: {
+    STARTED: 'Preparing swap transaction',
+    ACTION_REQUIRED: 'Sign swap transaction',
+    MESSAGE_REQUIRED: 'Sign swap message',
+    PENDING: 'Waiting for swap transaction',
+    DONE: 'Swap completed',
+  },
+  CROSS_CHAIN: {
+    STARTED: 'Preparing bridge transaction',
+    ACTION_REQUIRED: 'Sign bridge transaction',
+    MESSAGE_REQUIRED: 'Sign bridge message',
+    PENDING: 'Waiting for bridge transaction',
+    DONE: 'Bridge transaction confirmed',
+  },
+  RECEIVING_CHAIN: {
+    STARTED: 'Waiting for destination chain',
+    PENDING: 'Waiting for destination chain',
+    DONE: 'Bridge completed',
+  },
+  PERMIT: {
+    STARTED: 'Preparing transaction',
+    ACTION_REQUIRED: 'Sign permit message',
+    PENDING: 'Waiting for permit message',
+    DONE: 'Permit message signed',
+  },
+  NATIVE_PERMIT: {
+    STARTED: 'Preparing transaction',
+    ACTION_REQUIRED: 'Sign permit message',
+    PENDING: 'Waiting for permit message',
+    DONE: 'Permit message signed',
+  },
+}
+
+const substatusMessages: Record<
+  StatusMessage,
+  Partial<Record<Substatus, string>>
+> = {
+  PENDING: {
+    BRIDGE_NOT_AVAILABLE: 'Bridge communication is temporarily unavailable.',
+    CHAIN_NOT_AVAILABLE: 'RPC communication is temporarily unavailable.',
+    UNKNOWN_ERROR:
+      'An unexpected error occurred. Please seek assistance in the LI.FI discord server.',
+    WAIT_SOURCE_CONFIRMATIONS:
+      'The bridge deposit has been received. The bridge is waiting for more confirmations to start the off-chain logic.',
+    WAIT_DESTINATION_TRANSACTION:
+      'The bridge off-chain logic is being executed. Wait for the transaction to appear on the destination chain.',
+  },
+  DONE: {
+    PARTIAL:
+      'Some of the received tokens are not the requested destination tokens.',
+    REFUNDED: 'The tokens were refunded to the sender address.',
+    COMPLETED: 'The transfer is complete.',
+  },
+  FAILED: {},
+  INVALID: {},
+  NOT_FOUND: {},
+}
+
+export function getActionMessage(
+  type: ExecutionActionType,
+  status: ExecutionActionStatus
+): string | undefined {
+  const actionMessage = actionMessages[type][status]
+  return actionMessage
+}
+
+export function getSubstatusMessage(
+  status: StatusMessage,
+  substatus?: Substatus
+): string | undefined {
+  if (!substatus) {
+    return
+  }
+  const message = substatusMessages[status][substatus]
+  return message
+}

package/src/core/execution.ts

@@ -0,0 +1,243 @@
+import type { Route } from '@lifi/types'
+import { LiFiErrorCode } from '../errors/constants.js'
+import { ExecuteStepRetryError, ProviderError } from '../errors/errors.js'
+import type {
+  ExecutionOptions,
+  LiFiStepExtended,
+  RouteExtended,
+  SDKClient,
+  SDKProvider,
+} from '../types/core.js'
+import { executionState } from './executionState.js'
+import { prepareRestart } from './prepareRestart.js'
+
+/**
+ * Execute a route.
+ * @param client - The SDK client.
+ * @param route - The route that should be executed. Cannot be an active route.
+ * @param executionOptions - An object containing settings and callbacks.
+ * @returns The executed route.
+ * @throws {LiFiError} Throws a LiFiError if the execution fails.
+ */
+export const executeRoute = async (
+  client: SDKClient,
+  route: Route,
+  executionOptions?: ExecutionOptions
+): Promise<RouteExtended> => {
+  // Deep clone to prevent side effects
+  const clonedRoute = structuredClone<Route>(route)
+
+  let executionPromise = executionState.get(clonedRoute.id)?.promise
+  // Check if route is already running
+  if (executionPromise) {
+    return executionPromise
+  }
+
+  executionState.create({ route: clonedRoute, executionOptions })
+  executionPromise = executeSteps(client, clonedRoute)
+  executionState.update({
+    route: clonedRoute,
+    promise: executionPromise,
+  })
+
+  return executionPromise
+}
+
+/**
+ * Resume the execution of a route that has been stopped or had an error while executing.
+ * @param client - The SDK client.
+ * @param route - The route that is to be executed. Cannot be an active route.
+ * @param executionOptions - An object containing settings and callbacks.
+ * @returns The executed route.
+ * @throws {LiFiError} Throws a LiFiError if the execution fails.
+ */
+export const resumeRoute = async (
+  client: SDKClient,
+  route: Route,
+  executionOptions?: ExecutionOptions
+): Promise<RouteExtended> => {
+  const execution = executionState.get(route.id)
+
+  if (execution) {
+    const executionHalted = execution.executors.some(
+      (executor) => !executor.allowExecution
+    )
+    if (!executionHalted) {
+      // Check if we want to resume route execution in the background
+      updateRouteExecution(route, {
+        executeInBackground: executionOptions?.executeInBackground,
+      })
+      if (!execution.promise) {
+        // We should never reach this point if we do clean-up properly
+        throw new Error('Route execution promise not found.')
+      }
+      return execution.promise
+    }
+  }
+
+  prepareRestart(route)
+
+  return executeRoute(client, route, executionOptions)
+}
+
+const executeSteps = async (
+  client: SDKClient,
+  route: RouteExtended
+): Promise<RouteExtended> => {
+  // Loop over steps and execute them
+  for (let index = 0; index < route.steps.length; index++) {
+    const execution = executionState.get(route.id)
+    // Check if execution has stopped in the meantime
+    if (!execution) {
+      break
+    }
+
+    const step = route.steps[index]
+    const previousStep = route.steps[index - 1]
+    // Check if the step is already done
+    if (step.execution?.status === 'DONE') {
+      continue
+    }
+
+    // Update step fromAmount using output of the previous step execution. In the future this should be handled by calling `updateRoute`
+    if (previousStep?.execution?.toAmount) {
+      step.action.fromAmount = previousStep.execution.toAmount
+      if (step.includedSteps?.length) {
+        step.includedSteps[0].action.fromAmount =
+          previousStep.execution.toAmount
+      }
+    }
+
+    try {
+      const fromAddress = step.action.fromAddress
+      if (!fromAddress) {
+        throw new Error('Action fromAddress is not specified.')
+      }
+
+      const provider = client.providers.find((provider: SDKProvider) =>
+        provider.isAddress(fromAddress)
+      )
+
+      if (!provider) {
+        throw new ProviderError(
+          LiFiErrorCode.ProviderUnavailable,
+          'SDK Execution Provider not found.'
+        )
+      }
+
+      const stepExecutor = await provider.getStepExecutor({
+        routeId: route.id,
+        executionOptions: execution.executionOptions,
+      })
+      execution.executors.push(stepExecutor)
+
+      // Check if we want to execute this step in the background
+      if (execution.executionOptions) {
+        updateRouteExecution(route, execution.executionOptions)
+      }
+
+      let executedStep: LiFiStepExtended
+      try {
+        executedStep = await stepExecutor.executeStep(client, step)
+      } catch (e) {
+        if (e instanceof ExecuteStepRetryError) {
+          step.execution = undefined
+          executedStep = await stepExecutor.executeStep(
+            client,
+            step,
+            e.retryParams
+          )
+        } else {
+          throw e
+        }
+      }
+
+      // We may reach this point if user interaction isn't allowed. We want to stop execution until we resume it
+      if (executedStep.execution?.status !== 'DONE') {
+        stopRouteExecution(route)
+      }
+
+      // Execution stopped during the current step, we don't want to continue to the next step so we return already
+      if (!stepExecutor.allowExecution) {
+        return route
+      }
+    } catch (e) {
+      stopRouteExecution(route)
+      throw e
+    }
+  }
+
+  // Clean up after the execution
+  executionState.delete(route.id)
+  return route
+}
+
+/**
+ * Updates route execution to background or foreground state.
+ * @param route - A route that is currently in execution.
+ * @param options - An object with execution settings.
+ */
+export const updateRouteExecution = (
+  route: Route,
+  options: ExecutionOptions
+): void => {
+  const execution = executionState.get(route.id)
+  if (!execution) {
+    return
+  }
+
+  if ('executeInBackground' in options) {
+    for (const executor of execution.executors) {
+      executor.setInteraction({
+        allowInteraction: !options?.executeInBackground,
+        allowUpdates: true,
+      })
+    }
+  }
+  // Update active route settings so we know what the current state of execution is
+  execution.executionOptions = {
+    ...execution.executionOptions,
+    ...options,
+  }
+}
+
+/**
+ * Stops the execution of an active route.
+ * @param route - A route that is currently in execution.
+ * @returns The stopped route.
+ */
+export const stopRouteExecution = (route: Route): Route => {
+  const execution = executionState.get(route.id)
+  if (!execution) {
+    return route
+  }
+
+  for (const executor of execution.executors) {
+    executor.setInteraction({
+      allowInteraction: false,
+      allowUpdates: false,
+      allowExecution: false,
+    })
+  }
+  executionState.delete(route.id)
+  return execution.route
+}
+
+/**
+ * Get the list of active routes.
+ * @returns A list of routes.
+ */
+export const getActiveRoutes = (): RouteExtended[] => {
+  return Object.values(executionState.state)
+    .map((dict) => dict?.route)
+    .filter(Boolean) as RouteExtended[]
+}
+
+/**
+ * Return the current route information for given route. The route has to be active.
+ * @param routeId - A route id.
+ * @returns The updated route.
+ */
+export const getActiveRoute = (routeId: string): RouteExtended | undefined => {
+  return executionState.get(routeId)?.route
+}

package/src/core/executionState.ts

@@ -0,0 +1,48 @@
+import type {
+  ExecutionOptions,
+  RouteExtended,
+  StepExecutor,
+} from '../types/core.js'
+
+interface ExecutionData {
+  route: RouteExtended
+  executors: StepExecutor[]
+  executionOptions?: ExecutionOptions
+  promise?: Promise<RouteExtended>
+}
+
+type ExecutionStateParams = Omit<ExecutionData, 'executors'>
+
+interface ExecutionState {
+  state: Partial<Record<string, ExecutionData>>
+  get(routeId: string): ExecutionData | undefined
+  create(params: ExecutionStateParams): ExecutionData
+  update(params: ExecutionStateParams): void
+  delete(routeId: string): void
+}
+
+export const executionState: ExecutionState = {
+  state: {},
+  get(routeId: string) {
+    return this.state[routeId]
+  },
+  create(params) {
+    this.state[params.route.id] = {
+      ...this.state[params.route.id],
+      ...params,
+      executors: this.state[params.route.id]?.executors ?? [],
+    }
+    return this.state[params.route.id]!
+  },
+  update(state) {
+    if (this.state[state.route.id]) {
+      this.state[state.route.id] = {
+        ...this.state[state.route.id]!,
+        ...state,
+      }
+    }
+  },
+  delete(routeId) {
+    delete this.state[routeId]
+  },
+}

package/src/core/prepareRestart.ts

@@ -0,0 +1,28 @@
+import type { RouteExtended } from '../types/core.js'
+
+export const prepareRestart = (route: RouteExtended): void => {
+  for (let index = 0; index < route.steps.length; index++) {
+    const step = route.steps[index]
+    if (step.execution) {
+      // Find the index of the last action that has tx hash, taskId, or signed messages
+      const lastValidIndex = step.execution.actions.findLastIndex(
+        (action) =>
+          ['SWAP', 'CROSS_CHAIN', 'RECEIVING_CHAIN'].includes(action.type) &&
+          (!!action.txHash || !!action.taskId) &&
+          action.status !== 'FAILED'
+      )
+
+      // Keep all actions up to the one with tx hash
+      if (lastValidIndex >= 0) {
+        step.execution.actions = step.execution.actions.slice(
+          0,
+          lastValidIndex + 1
+        )
+      } else {
+        // If no tx hash exists, reset the actions array
+        step.execution.actions = []
+      }
+    }
+    step.transactionRequest = undefined
+  }
+}

package/src/core/storage.ts

@@ -0,0 +1,42 @@
+export interface SDKStorage {
+  get(key: string): string | null | Promise<string | null>
+  set(key: string, value: string): void | Promise<void>
+  remove(key: string): void | Promise<void>
+}
+
+export class LocalStorageAdapter implements SDKStorage {
+  get(key: string): string | null {
+    return window.localStorage.getItem(key)
+  }
+
+  set(key: string, value: string): void {
+    window.localStorage.setItem(key, value)
+  }
+
+  remove(key: string): void {
+    window.localStorage.removeItem(key)
+  }
+}
+
+export class InMemoryStorage implements SDKStorage {
+  private store = new Map<string, string>()
+
+  get(key: string): string | null {
+    return this.store.get(key) ?? null
+  }
+
+  set(key: string, value: string): void {
+    this.store.set(key, value)
+  }
+
+  remove(key: string): void {
+    this.store.delete(key)
+  }
+}
+
+export function createDefaultStorage(): SDKStorage {
+  if (typeof window !== 'undefined' && window.localStorage) {
+    return new LocalStorageAdapter()
+  }
+  return new InMemoryStorage()
+}

package/src/core/tasks/CheckBalanceTask.ts

@@ -0,0 +1,46 @@
+import { LiFiErrorCode } from '../../errors/constants.js'
+import { TransactionError } from '../../errors/errors.js'
+import type { StepExecutorContext, TaskResult } from '../../types/execution.js'
+import { BaseStepExecutionTask } from '../BaseStepExecutionTask.js'
+import {
+  type CheckBalanceOptions,
+  checkBalance,
+} from './helpers/checkBalance.js'
+
+export class CheckBalanceTask extends BaseStepExecutionTask {
+  /**
+   * Per-step options hook for chain-specific subclasses (e.g. skip the
+   * gas check for smart-contract wallets or relayed steps). Default `{}`
+   * keeps behavior unchanged for every provider that doesn't override.
+   * Resolved lazily inside `run()` — pipelines that resume past
+   * `CheckBalance` pay no cost.
+   */
+  protected getCheckBalanceOptions(
+    _context: StepExecutorContext
+  ): Promise<CheckBalanceOptions> {
+    return Promise.resolve({})
+  }
+
+  async run(context: StepExecutorContext): Promise<TaskResult> {
+    const { client, step, statusManager, isBridgeExecution } = context
+
+    statusManager.initializeAction({
+      step,
+      type: isBridgeExecution ? 'CROSS_CHAIN' : 'SWAP',
+      chainId: step.action.fromChainId,
+      status: 'STARTED',
+    })
+
+    const walletAddress = step.action.fromAddress
+    if (!walletAddress) {
+      throw new TransactionError(
+        LiFiErrorCode.InternalError,
+        'The wallet address is undefined.'
+      )
+    }
+
+    const options = await this.getCheckBalanceOptions(context)
+    await checkBalance(client, walletAddress, step, options)
+    return { status: 'COMPLETED' }
+  }
+}

package/src/core/tasks/PrepareTransactionTask.ts

@@ -0,0 +1,62 @@
+import { getStepTransaction } from '../../actions/getStepTransaction.js'
+import { LiFiErrorCode } from '../../errors/constants.js'
+import { TransactionError } from '../../errors/errors.js'
+import type { StepExecutorContext, TaskResult } from '../../types/execution.js'
+import { BaseStepExecutionTask } from '../BaseStepExecutionTask.js'
+import { stepComparison } from './helpers/stepComparison.js'
+
+export class PrepareTransactionTask extends BaseStepExecutionTask {
+  async run(context: StepExecutorContext): Promise<TaskResult> {
+    const {
+      client,
+      step,
+      statusManager,
+      allowUserInteraction,
+      executionOptions,
+      isBridgeExecution,
+    } = context
+
+    const action = statusManager.findAction(
+      step,
+      isBridgeExecution ? 'CROSS_CHAIN' : 'SWAP'
+    )
+
+    if (!action) {
+      throw new TransactionError(
+        LiFiErrorCode.TransactionUnprepared,
+        'Unable to prepare transaction. Action not found.'
+      )
+    }
+
+    if (!step.transactionRequest) {
+      const { execution, ...stepBase } = step
+      const updatedStep = await getStepTransaction(client, stepBase)
+      const comparedStep = await stepComparison(
+        statusManager,
+        step,
+        updatedStep,
+        allowUserInteraction,
+        executionOptions
+      )
+      Object.assign(step, {
+        ...comparedStep,
+        execution: step.execution,
+      })
+    }
+
+    if (!step.transactionRequest?.data) {
+      throw new TransactionError(
+        LiFiErrorCode.TransactionUnprepared,
+        'Unable to prepare transaction. Transaction request data is not found.'
+      )
+    }
+
+    statusManager.updateAction(step, action.type, 'ACTION_REQUIRED')
+
+    if (!allowUserInteraction) {
+      return { status: 'PAUSED' }
+    }
+
+    return { status: 'COMPLETED' }
+  }
+}

package/src/core/tasks/WaitForTransactionStatusTask.ts

@@ -0,0 +1,114 @@
+import type { ExtendedTransactionInfo, FullStatusData } from '@lifi/types'
+import { LiFiErrorCode } from '../../errors/constants.js'
+import { TransactionError } from '../../errors/errors.js'
+import type { ExecutionActionType } from '../../types/core.js'
+import type { StepExecutorContext, TaskResult } from '../../types/execution.js'
+import { getTransactionFailedMessage } from '../../utils/getTransactionMessage.js'
+import { BaseStepExecutionTask } from '../BaseStepExecutionTask.js'
+import { waitForTransactionStatus } from './helpers/waitForTransactionStatus.js'
+
+export class WaitForTransactionStatusTask extends BaseStepExecutionTask {
+  readonly actionType: ExecutionActionType
+
+  constructor(actionType: ExecutionActionType) {
+    super()
+    this.actionType = actionType
+  }
+
+  async run(context: StepExecutorContext): Promise<TaskResult> {
+    const {
+      client,
+      step,
+      statusManager,
+      pollingIntervalMs,
+      toChain,
+      isBridgeExecution,
+    } = context
+
+    // At this point, we should have a txHash or taskId
+    // taskId is used for custom integrations that don't use the standard transaction hash
+    let transactionHash: string | undefined
+    try {
+      const swapOrBridgeAction = statusManager.findAction(
+        step,
+        isBridgeExecution ? 'CROSS_CHAIN' : 'SWAP'
+      )
+      transactionHash = swapOrBridgeAction?.txHash || swapOrBridgeAction?.taskId
+
+      // Wait for the transaction status on the destination chain
+      if (!transactionHash) {
+        throw new Error('Transaction hash is undefined.')
+      }
+
+      const action = statusManager.initializeAction({
+        step,
+        type: this.actionType,
+        chainId:
+          this.actionType === 'RECEIVING_CHAIN'
+            ? step.action.toChainId
+            : step.action.fromChainId,
+        status: 'PENDING',
+      })
+
+      const statusResponse = (await waitForTransactionStatus(
+        client,
+        statusManager,
+        transactionHash,
+        step,
+        action.type,
+        pollingIntervalMs
+      )) as FullStatusData
+
+      const statusReceiving =
+        statusResponse.receiving as ExtendedTransactionInfo
+
+      // Update action status
+      statusManager.updateAction(step, action.type, 'DONE', {
+        chainId: statusReceiving?.chainId || toChain.id,
+        substatus: statusResponse.substatus,
+        substatusMessage: statusResponse.substatusMessage,
+        txHash: statusReceiving?.txHash,
+        txLink:
+          statusReceiving?.txLink ||
+          `${toChain.metamask.blockExplorerUrls[0]}tx/${statusReceiving?.txHash}`,
+      })
+
+      // Update execution status
+      statusManager.updateExecution(step, {
+        status: 'DONE',
+        ...(statusResponse.sending.amount && {
+          fromAmount: statusResponse.sending.amount,
+        }),
+        ...(statusReceiving?.amount && { toAmount: statusReceiving.amount }),
+        ...(statusReceiving?.token && { toToken: statusReceiving.token }),
+        internalTxLink: statusResponse?.lifiExplorerLink,
+        externalTxLink: statusResponse?.bridgeExplorerLink,
+        gasCosts: [
+          {
+            amount: statusResponse.sending.gasAmount,
+            amountUSD: statusResponse.sending.gasAmountUSD,
+            token: statusResponse.sending.gasToken,
+            estimate: statusResponse.sending.gasUsed,
+            limit: statusResponse.sending.gasUsed,
+            price: statusResponse.sending.gasPrice,
+            type: 'SEND',
+          },
+        ],
+      })
+
+      return { status: 'COMPLETED' }
+    } catch (e: any) {
+      const htmlMessage = await getTransactionFailedMessage(
+        client,
+        step,
+        `${toChain.metamask.blockExplorerUrls[0]}tx/${transactionHash}`
+      )
+      throw new TransactionError(
+        LiFiErrorCode.TransactionFailed,
+        htmlMessage ??
+          'Failed while waiting for status of destination chain transaction.',
+        e
+      )
+    }
+  }
+}