@lifi/sdk 3.0.0-alpha.3 → 3.0.0-alpha.30

package/src/core/execution.ts

@@ -0,0 +1,218 @@
+/* eslint-disable @typescript-eslint/no-empty-function */
+import type { Route } from '@lifi/types'
+import { config } from '../config.js'
+import { executionState } from './executionState.js'
+import { prepareRestart } from './prepareRestart.js'
+import type { ExecutionOptions, RouteExtended } from './types.js'
+
+/**
+ * Execute a route.
+ * @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 (
+  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
+  }
+
+  executionPromise = executeSteps(clonedRoute, executionOptions)
+
+  executionState.create(route, executionOptions, executionPromise)
+
+  return executionPromise
+}
+
+/**
+ * Resume the execution of a route that has been stopped or had an error while executing.
+ * @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 (
+  route: Route,
+  executionOptions?: ExecutionOptions
+): Promise<RouteExtended> => {
+  // Deep clone to prevent side effects
+  const clonedRoute = structuredClone<Route>(route)
+
+  const execution = executionState.get(clonedRoute.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
+    }
+  }
+
+  await prepareRestart(clonedRoute)
+
+  const executionPromise = executeSteps(clonedRoute, executionOptions)
+  executionState.create(route, executionOptions, executionPromise)
+
+  return executionPromise
+}
+
+const executeSteps = async (
+  route: RouteExtended,
+  executionOptions?: ExecutionOptions
+): Promise<RouteExtended> => {
+  executionState.create(route, executionOptions)
+
+  // 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 amount using output of previous execution. In the future this should be handled by calling `updateRoute`
+    if (previousStep?.execution?.toAmount) {
+      step.action.fromAmount = previousStep.execution.toAmount
+    }
+
+    try {
+      const fromAddress = step.action.fromAddress
+      if (!fromAddress) {
+        throw new Error('Action fromAddress is not specified.')
+      }
+
+      const provider = config
+        .get()
+        .providers?.find((provider) => provider.isAddress(fromAddress))
+
+      if (!provider) {
+        throw new Error('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)
+      }
+
+      const executedStep = await stepExecutor.executeStep(step)
+
+      // 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,39 @@
+import type { ExecutionOptions, RouteExtended, StepExecutor } from './types.js'
+
+export interface ExecutionData {
+  route: RouteExtended
+  executors: StepExecutor[]
+  executionOptions?: ExecutionOptions
+  promise?: Promise<RouteExtended>
+}
+
+export interface ExecutionState {
+  state: Partial<Record<string, ExecutionData>>
+  get(routeId: string): ExecutionData | undefined
+  create(
+    route: RouteExtended,
+    executionOptions?: ExecutionOptions,
+    promise?: Promise<RouteExtended>
+  ): ExecutionData
+  delete(routeId: string): void
+}
+
+export const executionState: ExecutionState = {
+  state: {},
+  get(routeId: string) {
+    return this.state[routeId]
+  },
+  create(route, executionOptions, promise) {
+    this.state[route.id] = {
+      ...this.state[route.id],
+      route,
+      executionOptions,
+      promise,
+      executors: [],
+    }
+    return this.state[route.id]!
+  },
+  delete(routeId) {
+    delete this.state[routeId]
+  },
+}

package/src/core/index.ts

@@ -0,0 +1,3 @@
+export * from './StatusManager.js'
+export * from './execution.js'
+export * from './types.js'

package/src/core/prepareRestart.ts

@@ -0,0 +1,82 @@
+import type { LiFiStep } from '@lifi/types'
+import type { LiFiStepExtended, RouteExtended } from './types.js'
+
+export const prepareRestart = async (route: RouteExtended) => {
+  for (let index = 0; index < route.steps.length; index++) {
+    const step = route.steps[index]
+    const stepHasFailed = step.execution?.status === 'FAILED'
+
+    if (stepHasFailed) {
+      // await handleErrorType(walletClient, step)
+      deleteFailedProcesses(step)
+      deleteTransactionData(step)
+    }
+  }
+}
+
+// const handleErrorType = async (walletClient: WalletClient, step: LiFiStep) => {
+//   const client = walletClient.extend(publicActions)
+
+//   const isGasLimitError = step.execution?.process.some(
+//     (p) => p.error?.code === LiFiErrorCode.GasLimitError
+//   )
+//   const isGasPriceError = step.execution?.process.some(
+//     (p) => p.error?.code === LiFiErrorCode.TransactionUnderpriced
+//   )
+
+//   const { transactionRequest } = step
+
+// if (isGasLimitError) {
+//   if (transactionRequest) {
+//     let gasLimit = transactionRequest.gasLimit
+
+//     try {
+//       gasLimit = await client.estimateGas(transactionRequest)
+//     } catch (error) {}
+
+//     if (gasLimit) {
+//       transactionRequest.gasLimit = BigNumber.from(
+//         `${(BigInt(gasLimit.toString()) * 125n) / 100n}`
+//       )
+//     }
+//   }
+
+//   step.estimate.gasCosts?.forEach(
+//     (gasCost) =>
+//       (gasCost.limit = `${Math.round(Number(gasCost.limit) * 1.25)}`)
+//   )
+// }
+
+// if (isGasPriceError) {
+//   if (transactionRequest) {
+//     let gasPrice = transactionRequest.gasPrice
+
+//     try {
+//       gasPrice = await client.getGasPrice()
+//     } catch (error) {}
+
+//     if (gasPrice) {
+//       transactionRequest.gasPrice = BigNumber.from(
+//         `${(BigInt(gasPrice.toString()) * 125n) / 100n}`
+//       )
+//     }
+//   }
+
+//   step.estimate.gasCosts?.forEach(
+//     (gasCost) =>
+//       (gasCost.price = `${Math.round(Number(gasCost.price) * 1.25)}`)
+//   )
+// }
+// }
+
+const deleteFailedProcesses = (step: LiFiStepExtended) => {
+  if (step.execution) {
+    step.execution.process = step.execution.process.filter(
+      (process) => process.status === 'DONE'
+    )
+  }
+}
+
+const deleteTransactionData = (step: LiFiStep) => {
+  step.transactionRequest = undefined
+}

package/src/core/provider.ts

@@ -0,0 +1,12 @@
+import type { ChainType } from '@lifi/types'
+import { config } from '../config.js'
+
+export const getProvider = <T>(type: ChainType): T => {
+  const provider = config
+    .get()
+    .providers?.find((provider) => provider.type === type) as T
+  if (!provider) {
+    throw new Error(`${type} provider not found.`)
+  }
+  return provider
+}

package/src/core/stepComparison.ts

@@ -0,0 +1,51 @@
+import type { LiFiStep } from '@lifi/types'
+import { LiFiErrorCode, TransactionError } from '../utils/errors.js'
+import type { StatusManager } from './StatusManager.js'
+import type { ExecutionOptions } from './types.js'
+import { checkStepSlippageThreshold } from './utils.js'
+
+/**
+ * This method checks whether the new and updated Step meets the required exchange rate conditions.
+ * If yes it returns the updated Step.
+ * If no and if user interaction is allowed it triggers the acceptExchangeRateUpdateHook. If no user interaction is allowed it aborts.
+ * @param statusManager
+ * @param oldStep
+ * @param newStep
+ * @param settings
+ * @param allowUserInteraction
+ * @param executionOptions
+ * @returns Return LiFiStep
+ */
+export const stepComparison = async (
+  statusManager: StatusManager,
+  oldStep: LiFiStep,
+  newStep: LiFiStep,
+  allowUserInteraction: boolean,
+  executionOptions?: ExecutionOptions
+): Promise<LiFiStep> => {
+  // Check if changed exchange rate is in the range of slippage threshold
+  if (checkStepSlippageThreshold(oldStep, newStep)) {
+    return statusManager.updateStepInRoute(newStep)
+  }
+
+  let allowStepUpdate: boolean | undefined
+  if (allowUserInteraction) {
+    allowStepUpdate = await executionOptions?.acceptExchangeRateUpdateHook?.({
+      oldToAmount: oldStep.estimate.toAmount,
+      newToAmount: newStep.estimate.toAmount,
+      toToken: newStep.action.toToken,
+    })
+  }
+
+  if (!allowStepUpdate) {
+    // The user declined the new exchange rate, so we are not going to proceed
+    throw new TransactionError(
+      LiFiErrorCode.ExchangeRateUpdateCanceled,
+      'Exchange rate has changed!',
+      `Transaction was not sent, your funds are still in your wallet.
+      The exchange rate has changed and the previous estimation can not be fulfilled due to value loss.`
+    )
+  }
+
+  return statusManager.updateStepInRoute(newStep)
+}

package/src/core/types.ts

@@ -0,0 +1,117 @@
+import type {
+  ChainType,
+  Execution,
+  LiFiStep,
+  Route,
+  Step,
+  Token,
+  TokenAmount,
+} from '@lifi/types'
+import type { WalletClient } from 'viem'
+
+export interface SDKProvider {
+  readonly type: ChainType
+  isAddress(address: string): boolean
+  getStepExecutor(options: StepExecutorOptions): Promise<StepExecutor>
+  getBalance(walletAddress: string, tokens: Token[]): Promise<TokenAmount[]>
+}
+
+export interface StepExecutorOptions {
+  routeId: string
+  executionOptions?: ExecutionOptions
+}
+
+export interface InteractionSettings {
+  allowInteraction?: boolean
+  allowUpdates?: boolean
+  allowExecution?: boolean
+}
+
+export interface StepExecutor {
+  allowUserInteraction: boolean
+  allowExecution: boolean
+  setInteraction(settings?: InteractionSettings): void
+  executeStep(step: LiFiStepExtended): Promise<LiFiStepExtended>
+}
+
+export interface RouteExtended extends Omit<Route, 'steps'> {
+  steps: LiFiStepExtended[]
+}
+
+export interface LiFiStepExtended extends LiFiStep {
+  execution?: Execution
+}
+
+export type StepExtended = Step & {
+  execution?: Execution
+}
+
+export type TransactionParameters = {
+  chainId?: number
+  to?: string
+  from?: string
+  nonce?: number
+  data?: string
+  value?: bigint
+  gas?: bigint
+  gasPrice?: bigint
+  maxFeePerGas?: bigint
+  maxPriorityFeePerGas?: bigint
+}
+
+export interface RouteExecutionData {
+  route: Route
+  executors: StepExecutor[]
+  executionOptions?: ExecutionOptions
+}
+
+export type RouteExecutionDataDictionary = Partial<
+  Record<string, RouteExecutionData>
+>
+
+export type RouteExecutionDictionary = Partial<Record<string, Promise<Route>>>
+
+export type UpdateRouteHook = (updatedRoute: Route) => void
+
+export interface TransactionRequestParameters extends TransactionParameters {
+  requestType: 'approve' | 'transaction'
+}
+
+export type TransactionRequestUpdateHook = (
+  updatedTxRequest: TransactionRequestParameters
+) => Promise<TransactionParameters>
+
+export type SwitchChainHook = (
+  chainId: number
+) => Promise<WalletClient | undefined>
+
+export interface AcceptSlippageUpdateHookParams {
+  toToken: Token
+  oldToAmount: string
+  newToAmount: string
+  oldSlippage: number
+  newSlippage: number
+}
+
+export type AcceptSlippageUpdateHook = (
+  params: AcceptSlippageUpdateHookParams
+) => Promise<boolean | undefined>
+
+export interface ExchangeRateUpdateParams {
+  toToken: Token
+  oldToAmount: string
+  newToAmount: string
+}
+
+export type AcceptExchangeRateUpdateHook = (
+  params: ExchangeRateUpdateParams
+) => Promise<boolean | undefined>
+
+export interface ExecutionOptions {
+  acceptExchangeRateUpdateHook?: AcceptExchangeRateUpdateHook
+  switchChainHook?: SwitchChainHook
+  updateRouteHook?: UpdateRouteHook
+  updateTransactionRequestHook?: TransactionRequestUpdateHook
+  executeInBackground?: boolean
+  infiniteApproval?: boolean
+}

package/src/core/utils.ts

@@ -0,0 +1,122 @@
+import {
+  type ChainId,
+  type LiFiStep,
+  type ProcessType,
+  type Status,
+  type StatusMessage,
+  type Substatus,
+} from '@lifi/types'
+import { config } from '../config.js'
+
+export const getRpcUrl = async (chainId: ChainId): Promise<string> => {
+  const rpcUrls = await getRpcUrls(chainId)
+  return rpcUrls[0]
+}
+
+export const getRpcUrls = async (chainId: ChainId): Promise<string[]> => {
+  const rpcUrls = (await config.getRPCUrls())[chainId]
+  if (!rpcUrls?.length) {
+    throw new Error('RPC URL not found')
+  }
+  return rpcUrls
+}
+
+const processMessages: Record<ProcessType, Partial<Record<Status, string>>> = {
+  TOKEN_ALLOWANCE: {
+    STARTED: 'Setting token allowance.',
+    PENDING: 'Waiting for token allowance.',
+    DONE: 'Token allowance set.',
+  },
+  SWITCH_CHAIN: {
+    PENDING: 'Chain switch required.',
+    DONE: 'Chain switched successfully.',
+  },
+  SWAP: {
+    STARTED: 'Preparing swap transaction.',
+    ACTION_REQUIRED: 'Please sign the transaction.',
+    PENDING: 'Waiting for swap transaction.',
+    DONE: 'Swap completed.',
+  },
+  CROSS_CHAIN: {
+    STARTED: 'Preparing bridge transaction.',
+    ACTION_REQUIRED: 'Please sign the transaction.',
+    PENDING: 'Waiting for bridge transaction.',
+    DONE: 'Bridge transaction confirmed.',
+  },
+  RECEIVING_CHAIN: {
+    PENDING: 'Waiting for destination chain.',
+    DONE: 'Bridge completed.',
+  },
+  TRANSACTION: {},
+}
+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.',
+    NOT_PROCESSABLE_REFUND_NEEDED:
+      'The transfer cannot be completed successfully. A refund operation is required.',
+    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 getProcessMessage(
+  type: ProcessType,
+  status: Status
+): string | undefined {
+  const processMessage = processMessages[type][status]
+  return processMessage
+}
+
+export function getSubstatusMessage(
+  status: StatusMessage,
+  substatus?: Substatus
+): string | undefined {
+  if (!substatus) {
+    return
+  }
+  const message = substatusMessages[status][substatus]
+  return message
+}
+
+/**
+ * Used to check if changed exchange rate is in the range of slippage threshold.
+ * We use a slippage value as a threshold to trigger the rate change hook.
+ * This can result in almost doubled slippage for the user and need to be revisited.
+ * @param oldStep
+ * @param newStep
+ * @returns Boolean
+ */
+export function checkStepSlippageThreshold(
+  oldStep: LiFiStep,
+  newStep: LiFiStep
+): boolean {
+  const setSlippage = oldStep.action.slippage
+  const oldEstimatedToAmount = BigInt(oldStep.estimate.toAmountMin)
+  const newEstimatedToAmount = BigInt(newStep.estimate.toAmountMin)
+  const amountDifference = oldEstimatedToAmount - newEstimatedToAmount
+  // oldEstimatedToAmount can be 0 when we use conract calls
+  let actualSlippage = 0
+  if (oldEstimatedToAmount > 0) {
+    actualSlippage =
+      Number((amountDifference * 1_000_000_000n) / oldEstimatedToAmount) /
+      1_000_000_000
+  }
+  return actualSlippage <= setSlippage
+}