@lifi/sdk 3.0.0-alpha.9 → 3.0.0-beta.1

package/src/core/StatusManager.ts

@@ -0,0 +1,233 @@
+import type {
+  Execution,
+  ExecutionStatus,
+  LiFiStep,
+  Process,
+  ProcessStatus,
+  ProcessType,
+} from '@lifi/types'
+import { executionState } from './executionState.js'
+import type { LiFiStepExtended } from './types.js'
+import { getProcessMessage } from './utils.js'
+
+type OptionalParameters = Partial<
+  Pick<
+    Process,
+    | 'doneAt'
+    | 'failedAt'
+    | 'txHash'
+    | 'txLink'
+    | 'error'
+    | 'substatus'
+    | 'substatusMessage'
+    | 'multisigTxHash'
+  >
+>
+
+/**
+ * Manages status updates of a route and provides various functions for tracking processes
+ * @param {string} routeId The route dd this StatusManger belongs to.
+ * @returns {StatusManager} An instance of StatusManager.
+ */
+export class StatusManager {
+  private readonly routeId: string
+  private shouldUpdate = true
+
+  constructor(routeId: string) {
+    this.routeId = routeId
+  }
+
+  /**
+   * Initializes the execution object of a Step.
+   * @param step  The current step in execution
+   * @returns The initialized execution object for this step and a function to update this step
+   */
+  initExecutionObject = (step: LiFiStepExtended): Execution => {
+    if (!step.execution) {
+      step.execution = {
+        status: 'PENDING',
+        process: [],
+      }
+      this.updateStepInRoute(step)
+    }
+
+    // Change status to PENDING after resuming from FAILED
+    if (step.execution.status === 'FAILED') {
+      step.execution.status = 'PENDING'
+      this.updateStepInRoute(step)
+    }
+
+    return step.execution
+  }
+
+  /**
+   * Updates the execution object of a Step.
+   * @param step  The current step in execution
+   * @param status  The status for the execution
+   * @param execution Optional. Information about received tokens
+   * @returns The step with the updated execution object
+   */
+  updateExecution(
+    step: LiFiStepExtended,
+    status: ExecutionStatus,
+    execution?: Partial<Execution>
+  ): LiFiStep {
+    if (!step.execution) {
+      throw Error("Can't update empty execution.")
+    }
+    step.execution.status = status
+    if (execution) {
+      step.execution = {
+        ...step.execution,
+        ...execution,
+      }
+    }
+    this.updateStepInRoute(step)
+    return step
+  }
+
+  /**
+   * Create and push a new process into the execution.
+   * @param step The step that should contain the new process.
+   * @param type Type of the process. Used to identify already existing processes.
+   * @param status By default created procces is set to the STARTED status. We can override new process with the needed status.
+   * @returns Returns process.
+   */
+  findOrCreateProcess = (
+    step: LiFiStepExtended,
+    type: ProcessType,
+    status?: ProcessStatus
+  ): Process => {
+    if (!step.execution?.process) {
+      throw new Error("Execution hasn't been initialized.")
+    }
+
+    const process = step.execution.process.find((p) => p.type === type)
+
+    if (process) {
+      if (status && process.status !== status) {
+        process.status = status
+        this.updateStepInRoute(step)
+      }
+      return process
+    }
+
+    const newProcess: Process = {
+      type: type,
+      startedAt: Date.now(),
+      message: getProcessMessage(type, status ?? 'STARTED'),
+      status: status ?? 'STARTED',
+    }
+
+    step.execution.process.push(newProcess)
+    this.updateStepInRoute(step)
+    return newProcess
+  }
+
+  /**
+   * Update a process object.
+   * @param step The step where the process should be updated
+   * @param type  The process type to update
+   * @param status The status the process gets.
+   * @param [params] Additional parameters to append to the process.
+   * @returns The update process
+   */
+  updateProcess = (
+    step: LiFiStepExtended,
+    type: ProcessType,
+    status: ProcessStatus,
+    params?: OptionalParameters
+  ): Process => {
+    if (!step.execution) {
+      throw new Error("Can't update an empty step execution.")
+    }
+    const currentProcess = step?.execution?.process.find((p) => p.type === type)
+
+    if (!currentProcess) {
+      throw new Error("Can't find a process for the given type.")
+    }
+
+    switch (status) {
+      case 'CANCELLED':
+        currentProcess.doneAt = Date.now()
+        break
+      case 'FAILED':
+        currentProcess.doneAt = Date.now()
+        step.execution.status = 'FAILED'
+        break
+      case 'DONE':
+        currentProcess.doneAt = Date.now()
+        break
+      case 'PENDING':
+        step.execution.status = 'PENDING'
+        break
+      case 'ACTION_REQUIRED':
+        step.execution.status = 'ACTION_REQUIRED'
+        break
+      default:
+        break
+    }
+
+    currentProcess.status = status
+    currentProcess.message = getProcessMessage(type, status)
+    // set extra parameters or overwritte the standard params set in the switch statement
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        currentProcess[key] = value
+      }
+    }
+    // Sort processes, the ones with DONE status go first
+    step.execution.process = [
+      ...step?.execution?.process.filter(
+        (process) => process.status === 'DONE'
+      ),
+      ...step?.execution?.process.filter(
+        (process) => process.status !== 'DONE'
+      ),
+    ]
+    this.updateStepInRoute(step) // updates the step in the route
+    return currentProcess
+  }
+
+  /**
+   * Remove a process from the execution
+   * @param step The step where the process should be removed from
+   * @param type  The process type to remove
+   */
+  removeProcess = (step: LiFiStepExtended, type: ProcessType): void => {
+    if (!step.execution) {
+      throw new Error("Execution hasn't been initialized.")
+    }
+    const index = step.execution.process.findIndex((p) => p.type === type)
+    step.execution.process.splice(index, 1)
+    this.updateStepInRoute(step)
+  }
+
+  updateStepInRoute = (step: LiFiStep): LiFiStep => {
+    if (!this.shouldUpdate) {
+      return step
+    }
+    const data = executionState.get(this.routeId)
+
+    if (!data) {
+      throw new Error('Execution data not found.')
+    }
+
+    const stepIndex = data.route.steps.findIndex(
+      (routeStep) => routeStep.id === step.id
+    )
+
+    if (stepIndex === -1) {
+      throw new Error("Couldn't find a step to update.")
+    }
+
+    data.route.steps[stepIndex] = { ...data.route.steps[stepIndex], ...step }
+
+    data.executionOptions?.updateRouteHook?.(data.route)
+    return data.route.steps[stepIndex]
+  }
+
+  allowUpdates(value: boolean): void {
+    this.shouldUpdate = value
+  }
+}

package/src/core/checkBalance.ts

@@ -0,0 +1,48 @@
+import type { LiFiStep } from '@lifi/types'
+import { formatUnits } from 'viem'
+import { getTokenBalance } from '../services/balance.js'
+import { BalanceError } from '../utils/errors.js'
+
+export const checkBalance = async (
+  walletAddress: string,
+  step: LiFiStep,
+  depth = 0
+): Promise<void> => {
+  const token = await getTokenBalance(walletAddress, step.action.fromToken)
+  if (token) {
+    const currentBalance = token.amount ?? 0n
+    const neededBalance = BigInt(step.action.fromAmount)
+
+    if (currentBalance < neededBalance) {
+      if (depth <= 3) {
+        await new Promise((resolve) => {
+          setTimeout(resolve, 200)
+        })
+        await checkBalance(walletAddress, step, depth + 1)
+      } else if (
+        (neededBalance * BigInt((1 - step.action.slippage) * 1_000_000_000)) /
+          1_000_000_000n <=
+        currentBalance
+      ) {
+        // adjust amount in slippage limits
+        step.action.fromAmount = currentBalance.toString()
+      } else {
+        const neeeded = formatUnits(neededBalance, token.decimals)
+        const current = formatUnits(currentBalance, token.decimals)
+        let errorMessage =
+          `Your ${token.symbol} balance is too low, ` +
+          `you try to transfer ${neeeded} ${token.symbol}, ` +
+          `but your wallet only holds ${current} ${token.symbol}. ` +
+          `No funds have been sent.`
+
+        if (currentBalance !== 0n) {
+          errorMessage +=
+            `If the problem consists, please delete this transfer and ` +
+            `start a new one with a maximum of ${current} ${token.symbol}.`
+        }
+
+        throw new BalanceError('The balance is too low.', errorMessage)
+      }
+    }
+  }
+}

package/src/core/execution.ts

@@ -0,0 +1,214 @@
+/* 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
+  }
+
+  executionState.create({ route: clonedRoute, executionOptions })
+  executionPromise = executeSteps(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 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> => {
+  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
+    }
+  }
+
+  await prepareRestart(route)
+
+  return executeRoute(route, executionOptions)
+}
+
+const executeSteps = async (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 = 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,44 @@
+import type { ExecutionOptions, RouteExtended, StepExecutor } from './types.js'
+
+export interface ExecutionData {
+  route: RouteExtended
+  executors: StepExecutor[]
+  executionOptions?: ExecutionOptions
+  promise?: Promise<RouteExtended>
+}
+
+export type ExecutionStateParams = Omit<ExecutionData, 'executors'>
+
+export 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/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,26 @@
+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) {
+      deleteFailedProcesses(step)
+      deleteTransactionData(step)
+    }
+  }
+}
+
+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/rpc.ts

@@ -0,0 +1,15 @@
+import { type ChainId } 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
+}

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)
+}