@lifi/sdk 4.0.0-alpha.2 → 4.0.0-alpha.20

package/src/core/{processMessages.ts → actionMessages.ts}

@@ -1,15 +1,27 @@
 import type { StatusMessage, Substatus } from '@lifi/types'
-import type { ProcessStatus, ProcessType } from '../types/core.js'
+import type {
+  ExecutionActionStatus,
+  ExecutionActionType,
+} from '../types/core.js'
 
-const processMessages: Record<
-  ProcessType,
-  Partial<Record<ProcessStatus, string>>
+const actionMessages: Record<
+  ExecutionActionType,
+  Partial<Record<ExecutionActionStatus, string>>
 > = {
-  TOKEN_ALLOWANCE: {
+  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',
-    RESET_REQUIRED: 'Resetting token allowance',
-    MESSAGE_REQUIRED: 'Sign token allowance message',
     PENDING: 'Waiting for token allowance',
     DONE: 'Token allowance set',
   },
@@ -28,6 +40,7 @@ const processMessages: Record<
     DONE: 'Bridge transaction confirmed',
   },
   RECEIVING_CHAIN: {
+    STARTED: 'Waiting for destination chain',
     PENDING: 'Waiting for destination chain',
     DONE: 'Bridge completed',
   },
@@ -37,7 +50,14 @@ const processMessages: Record<
     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>>
@@ -63,12 +83,12 @@ const substatusMessages: Record<
   NOT_FOUND: {},
 }
 
-export function getProcessMessage(
-  type: ProcessType,
-  status: ProcessStatus
+export function getActionMessage(
+  type: ExecutionActionType,
+  status: ExecutionActionStatus
 ): string | undefined {
-  const processMessage = processMessages[type][status]
-  return processMessage
+  const actionMessage = actionMessages[type][status]
+  return actionMessage
 }
 
 export function getSubstatusMessage(

package/src/core/execution.ts

@@ -1,8 +1,9 @@
 import type { Route } from '@lifi/types'
 import { LiFiErrorCode } from '../errors/constants.js'
-import { ProviderError } from '../errors/errors.js'
+import { ExecuteStepRetryError, ProviderError } from '../errors/errors.js'
 import type {
   ExecutionOptions,
+  LiFiStepExtended,
   RouteExtended,
   SDKClient,
   SDKProvider,
@@ -94,7 +95,6 @@ const executeSteps = async (
     const step = route.steps[index]
     const previousStep = route.steps[index - 1]
     // Check if the step is already done
-    //
     if (step.execution?.status === 'DONE') {
       continue
     }
@@ -136,7 +136,21 @@ const executeSteps = async (
         updateRouteExecution(route, execution.executionOptions)
       }
 
-      const executedStep = await stepExecutor.executeStep(client, step)
+      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') {

package/src/core/prepareRestart.ts

@@ -4,25 +4,26 @@ export const prepareRestart = (route: RouteExtended) => {
   for (let index = 0; index < route.steps.length; index++) {
     const step = route.steps[index]
     if (step.execution) {
-      // Find the index of the last process that has tx hash, taskId, or signed messages
-      const lastValidIndex = step.execution.process.findLastIndex(
-        (process) =>
-          (!!process.txHash ||
-            !!process.taskId ||
-            !!process.signedTypedData?.length) &&
-          process.status !== 'FAILED'
+      // 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 processes up to the one with tx hash
+      // Keep all actions up to the one with tx hash
       if (lastValidIndex >= 0) {
-        step.execution.process = step.execution.process.slice(
+        step.execution.actions = step.execution.actions.slice(
           0,
           lastValidIndex + 1
         )
       } else {
-        // If no tx hash exists, reset the process array
-        step.execution.process = []
+        // If no tx hash exists, reset the actions array
+        step.execution.actions = []
       }
+      // Reset the last action type
+      step.execution.lastActionType = undefined
     }
     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,29 @@
+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 { checkBalance } from './helpers/checkBalance.js'
+
+export class CheckBalanceTask extends BaseStepExecutionTask {
+  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.'
+      )
+    }
+
+    await checkBalance(client, walletAddress, step)
+    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
+      )
+    }
+  }
+}

package/src/core/{checkBalance.ts → tasks/helpers/checkBalance.ts}

@@ -1,9 +1,9 @@
 import type { LiFiStep } from '@lifi/types'
-import { formatUnits } from 'viem'
-import { getTokenBalance } from '../actions/getTokenBalance.js'
-import { BalanceError } from '../errors/errors.js'
-import type { SDKClient } from '../types/core.js'
-import { sleep } from '../utils/sleep.js'
+import { getTokenBalance } from '../../../actions/getTokenBalance.js'
+import { BalanceError } from '../../../errors/errors.js'
+import type { SDKClient } from '../../../types/core.js'
+import { formatUnits } from '../../../utils/formatUnits.js'
+import { sleep } from '../../../utils/sleep.js'
 
 export const checkBalance = async (
   client: SDKClient,

package/src/core/tasks/helpers/getTransactionRequestData.ts

@@ -0,0 +1,47 @@
+import { LiFiErrorCode } from '../../../errors/constants.js'
+import { TransactionError } from '../../../errors/errors.js'
+import type {
+  ExecutionOptions,
+  LiFiStepExtended,
+  TransactionParameters,
+} from '../../../types/core.js'
+
+export const getTransactionRequestData = async (
+  step: LiFiStepExtended,
+  executionOptions?: ExecutionOptions
+): Promise<string> => {
+  if (!step.transactionRequest?.data) {
+    throw new TransactionError(
+      LiFiErrorCode.TransactionUnprepared,
+      'Unable to prepare transaction. Transaction request data is not found.'
+    )
+  }
+
+  let transactionRequest: TransactionParameters = {
+    data: step.transactionRequest.data,
+  }
+
+  if (executionOptions?.updateTransactionRequestHook) {
+    const customizedTransactionRequest: TransactionParameters =
+      await executionOptions.updateTransactionRequestHook({
+        requestType: 'transaction',
+        ...transactionRequest,
+      })
+
+    transactionRequest = {
+      ...transactionRequest,
+      ...customizedTransactionRequest,
+    }
+  }
+
+  const transactionRequestData = transactionRequest.data
+
+  if (!transactionRequestData) {
+    throw new TransactionError(
+      LiFiErrorCode.TransactionUnprepared,
+      'Unable to prepare transaction. Transaction request data is not found.'
+    )
+  }
+
+  return transactionRequestData
+}

package/src/core/{stepComparison.ts → tasks/helpers/stepComparison.ts}

@@ -1,9 +1,9 @@
 import type { LiFiStep } from '@lifi/types'
-import { LiFiErrorCode } from '../errors/constants.js'
-import { TransactionError } from '../errors/errors.js'
-import type { ExecutionOptions } from '../types/core.js'
-import type { StatusManager } from './StatusManager.js'
-import { checkStepSlippageThreshold } from './utils.js'
+import type { StatusManager } from '../../../core/StatusManager.js'
+import { checkStepSlippageThreshold } from '../../../core/utils.js'
+import { LiFiErrorCode } from '../../../errors/constants.js'
+import { TransactionError } from '../../../errors/errors.js'
+import type { ExecutionOptions } from '../../../types/core.js'
 
 /**
  * This method checks whether the new and updated Step meets the required exchange rate conditions.

package/src/core/{waitForTransactionStatus.ts → tasks/helpers/waitForTransactionStatus.ts}

@@ -1,10 +1,10 @@
 import type { FullStatusData, LiFiStep, StatusResponse } from '@lifi/types'
-import { getStatus } from '../actions/getStatus.js'
-import { ServerError } from '../errors/errors.js'
-import type { ProcessType, SDKClient } from '../types/core.js'
-import { waitForResult } from '../utils/waitForResult.js'
-import { getSubstatusMessage } from './processMessages.js'
-import type { StatusManager } from './StatusManager.js'
+import { getStatus } from '../../../actions/getStatus.js'
+import { ServerError } from '../../../errors/errors.js'
+import type { ExecutionActionType, SDKClient } from '../../../types/core.js'
+import { waitForResult } from '../../../utils/waitForResult.js'
+import { getSubstatusMessage } from '../../actionMessages.js'
+import type { StatusManager } from '../../StatusManager.js'
 
 const TRANSACTION_HASH_OBSERVERS: Record<string, Promise<StatusResponse>> = {}
 
@@ -13,7 +13,7 @@ export async function waitForTransactionStatus(
   statusManager: StatusManager,
   txHash: string,
   step: LiFiStep,
-  processType: ProcessType,
+  actionType: ExecutionActionType,
   interval = 5_000
 ): Promise<StatusResponse> {
   const _getStatus = (): Promise<StatusResponse | undefined> => {
@@ -29,7 +29,7 @@ export async function waitForTransactionStatus(
           case 'DONE':
             return statusResponse
           case 'PENDING':
-            statusManager?.updateProcess(step, processType, 'PENDING', {
+            statusManager?.updateAction(step, actionType, 'PENDING', {
               substatus: statusResponse.substatus,
               substatusMessage:
                 statusResponse.substatusMessage ||
@@ -57,7 +57,9 @@ export async function waitForTransactionStatus(
   let status = TRANSACTION_HASH_OBSERVERS[txHash]
 
   if (!status) {
-    status = waitForResult(_getStatus, interval)
+    status = waitForResult(_getStatus, interval).finally(() => {
+      delete TRANSACTION_HASH_OBSERVERS[txHash]
+    })
     TRANSACTION_HASH_OBSERVERS[txHash] = status
   }
 

package/src/core/utils.ts

@@ -1,4 +1,4 @@
-import type { ChainId, ExtendedChain, LiFiStep, Token } from '@lifi/types'
+import type { ChainId, ExtendedChain, LiFiStep } from '@lifi/types'
 import type { RPCUrls } from '../types/core.js'
 
 // Standard threshold for destination amount difference (0.5%)
@@ -57,15 +57,3 @@ export function getRpcUrlsFromChains(
   }
   return result
 }
-
-/**
- * Checks whether a given token is eligible for message signing.
- * Tokens with '₮' symbol in their name are disallowed,
- * since such tokens may have non-standard signing requirements or compatibility issues with hardware wallets.
- *
- * @param token - The token object to check.
- * @returns true if the token is allowed for message signing, false otherwise.
- */
-export const isTokenMessageSigningAllowed = (token: Token): boolean => {
-  return !token.name?.includes('₮') && !token.symbol?.includes('₮')
-}

package/src/errors/SDKError.ts

@@ -1,24 +1,24 @@
 import type { LiFiStep } from '@lifi/types'
-import type { Process } from '../types/core.js'
+import type { ExecutionAction } from '../types/core.js'
 import { version } from '../version.js'
 import type { BaseError } from './baseError.js'
 import type { ErrorCode } from './constants.js'
 
 // Note: SDKError is used to wrapper and present errors at the top level
-// Where opportunity allows we also add the step and the process related to the error
+// Where opportunity allows we also add the step and the action related to the error
 export class SDKError extends Error {
   step?: LiFiStep
-  process?: Process
+  action?: ExecutionAction
   code: ErrorCode
   override name = 'SDKError'
   override cause: BaseError
 
-  constructor(cause: BaseError, step?: LiFiStep, process?: Process) {
+  constructor(cause: BaseError, step?: LiFiStep, action?: ExecutionAction) {
     const errorMessage = `${cause.message ? `[${cause.name}] ${cause.message}` : 'Unknown error occurred'}\nLI.FI SDK version: ${version}`
     super(errorMessage)
     this.name = 'SDKError'
     this.step = step
-    this.process = process
+    this.action = action
     this.cause = cause
     this.stack = this.cause.stack
     this.code = cause.code

package/src/errors/constants.ts

@@ -9,6 +9,8 @@ export enum ErrorName {
   UnknownError = 'UnknownError',
   SlippageError = 'SlippageError',
   HTTPError = 'HTTPError',
+  ConfigError = 'ConfigError',
+  ExecuteStepRetryError = 'ExecuteStepRetryError',
 }
 
 export type ErrorCode = LiFiErrorCode
@@ -40,6 +42,7 @@ export enum LiFiErrorCode {
   RateLimitExceeded = 1023,
   ThirdPartyError = 1024,
   InsufficientGas = 1025,
+  ConfigError = 1026,
 }
 
 export enum ErrorMessage {

package/src/errors/errors.ts

@@ -1,3 +1,4 @@
+import type { ExecuteStepRetryParams } from '../types/core.js'
 import { BaseError } from './baseError.js'
 import { ErrorName, LiFiErrorCode } from './constants.js'
 
@@ -42,3 +43,26 @@ export class ValidationError extends BaseError {
     super(ErrorName.ValidationError, LiFiErrorCode.ValidationError, message)
   }
 }
+
+/**
+ * Thrown by a step executor when executeStep should be retried with the given params
+ * (e.g. wallet rejected 7702 upgrade → retry with atomicityNotReady).
+ * The execution layer catches this and retries executeStep(client, step, retryParams).
+ */
+export class ExecuteStepRetryError extends BaseError {
+  readonly retryParams: ExecuteStepRetryParams
+
+  constructor(
+    message: string,
+    retryParams: ExecuteStepRetryParams,
+    cause?: Error
+  ) {
+    super(
+      ErrorName.ExecuteStepRetryError,
+      LiFiErrorCode.InternalError,
+      message,
+      cause
+    )
+    this.retryParams = retryParams
+  }
+}