@lifi/sdk 0.0.0-preview-f5cf9f8

package/src/actions/relayTransaction.ts

@@ -0,0 +1,74 @@
+import type {
+  RelayRequest,
+  RelayResponse,
+  RelayResponseData,
+  RequestOptions,
+} from '@lifi/types'
+import { BaseError } from '../errors/baseError.js'
+import { ErrorName } from '../errors/constants.js'
+import { ValidationError } from '../errors/errors.js'
+import { SDKError } from '../errors/SDKError.js'
+import type { SDKClient } from '../types/core.js'
+import { request } from '../utils/request.js'
+
+/**
+ * Relay a transaction through the relayer service
+ * @param client - The SDK client
+ * @param params - The configuration for the relay request
+ * @param options - Request options
+ * @throws {LiFiError} - Throws a LiFiError if request fails
+ * @returns Task ID and transaction link for the relayed transaction
+ */
+export const relayTransaction = async (
+  client: SDKClient,
+  params: RelayRequest,
+  options?: RequestOptions
+): Promise<RelayResponseData> => {
+  const requiredParameters: Array<keyof RelayRequest> = ['typedData']
+
+  for (const requiredParameter of requiredParameters) {
+    if (!params[requiredParameter]) {
+      throw new SDKError(
+        new ValidationError(
+          `Required parameter "${requiredParameter}" is missing.`
+        )
+      )
+    }
+  }
+
+  // Determine if the request is for a gasless relayer service or advanced relayer service
+  // We will use the same endpoint for both after the gasless relayer service is deprecated
+  const relayerPath = params.typedData.some(
+    (t) => t.primaryType === 'PermitWitnessTransferFrom'
+  )
+    ? '/relayer/relay'
+    : '/advanced/relay'
+
+  const result = await request<RelayResponse>(
+    client.config,
+    `${client.config.apiUrl}${relayerPath}`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(params, (_, value) => {
+        if (typeof value === 'bigint') {
+          return value.toString()
+        }
+        return value
+      }),
+      signal: options?.signal,
+    }
+  )
+
+  if (result.status === 'error') {
+    throw new BaseError(
+      ErrorName.ServerError,
+      result.data.code,
+      result.data.message
+    )
+  }
+
+  return result.data
+}

package/src/client/createClient.ts

@@ -0,0 +1,100 @@
+import type { ChainId, ChainType, ExtendedChain } from '@lifi/types'
+import type {
+  SDKBaseConfig,
+  SDKClient,
+  SDKConfig,
+  SDKProvider,
+} from '../types/core.js'
+import { checkPackageUpdates } from '../utils/checkPackageUpdates.js'
+import { name, version } from '../version.js'
+import { getClientStorage } from './getClientStorage.js'
+
+export function createClient(options: SDKConfig): SDKClient {
+  if (!options.integrator) {
+    throw new Error(
+      'Integrator not found. Please see documentation https://docs.li.fi/integrate-li.fi-js-sdk/set-up-the-sdk'
+    )
+  }
+
+  if (!options.disableVersionCheck && process.env.NODE_ENV === 'development') {
+    checkPackageUpdates(name, version)
+  }
+
+  const { providers, ...configOptions } = options
+
+  const _config: SDKBaseConfig = {
+    ...configOptions,
+    apiUrl: configOptions?.apiUrl ?? 'https://li.quest/v1',
+    rpcUrls: configOptions?.rpcUrls ?? {},
+    debug: configOptions?.debug ?? false,
+    preloadChains: configOptions?.preloadChains ?? true,
+    integrator: configOptions?.integrator ?? 'lifi-sdk',
+  }
+
+  let _providers: SDKProvider[] = providers ?? []
+  const _storage = getClientStorage(_config)
+
+  const client: SDKClient = {
+    get config() {
+      return _config
+    },
+    get providers() {
+      return _providers
+    },
+    getProvider(type: ChainType) {
+      return this.providers.find((provider) => provider.type === type)
+    },
+    setProviders(newProviders: SDKProvider[]) {
+      const providerMap = new Map(
+        this.providers.map((provider) => [provider.type, provider])
+      )
+      for (const provider of newProviders) {
+        providerMap.set(provider.type, provider)
+      }
+      _providers = Array.from(providerMap.values())
+    },
+    setChains(chains: ExtendedChain[]) {
+      _storage.setChains(chains)
+    },
+    async getChains() {
+      return await _storage.getChains()
+    },
+    async getChainById(chainId: ChainId) {
+      const chains = await this.getChains()
+      const chain = chains?.find((chain) => chain.id === chainId)
+      if (!chain) {
+        throw new Error(`ChainId ${chainId} not found`)
+      }
+      return chain
+    },
+    async getRpcUrls() {
+      return await _storage.getRpcUrls()
+    },
+    async getRpcUrlsByChainId(chainId: ChainId) {
+      const rpcUrls = await this.getRpcUrls()
+      const chainRpcUrls = rpcUrls[chainId]
+      if (!chainRpcUrls?.length) {
+        throw new Error(`RPC URL not found for chainId: ${chainId}`)
+      }
+      return chainRpcUrls
+    },
+  }
+
+  function extend<TClient extends SDKClient>(
+    base: TClient
+  ): <TExtensions extends Record<string, any>>(
+    extendFn: (client: TClient) => TExtensions
+  ) => TClient & TExtensions {
+    return (extendFn) => {
+      const extensions = extendFn(base)
+      const extended = { ...base, ...extensions } as TClient & typeof extensions
+
+      // Preserve the extend function for further extensions
+      return Object.assign(extended, {
+        extend: extend(extended),
+      })
+    }
+  }
+
+  return Object.assign(client, { extend: extend(client) })
+}

package/src/client/getClientStorage.ts

@@ -0,0 +1,65 @@
+import { ChainId, ChainType, type ExtendedChain } from '@lifi/types'
+import { _getChains } from '../actions/getChains.js'
+import { getRpcUrlsFromChains } from '../core/utils.js'
+import type { RPCUrls, SDKBaseConfig } from '../types/core.js'
+
+// 6 hours in milliseconds
+const chainsRefreshInterval = 1000 * 60 * 60 * 6
+
+export interface ClientStorage {
+  readonly needReset: boolean
+  setChains(chains: ExtendedChain[]): void
+  getChains(): Promise<ExtendedChain[]>
+  getRpcUrls(): Promise<RPCUrls>
+}
+
+export const getClientStorage = (config: SDKBaseConfig): ClientStorage => {
+  let _chains = [] as ExtendedChain[]
+  let _rpcUrls = { ...config.rpcUrls } as RPCUrls
+  let _chainsUpdatedAt: number | undefined
+
+  const updateRpcUrls = () => {
+    _rpcUrls = { ...config.rpcUrls }
+    _rpcUrls = getRpcUrlsFromChains(_rpcUrls, _chains, [ChainId.SOL])
+  }
+
+  return {
+    get needReset() {
+      return (
+        !_chainsUpdatedAt ||
+        Date.now() - _chainsUpdatedAt >= chainsRefreshInterval
+      )
+    },
+    setChains(chains: ExtendedChain[]) {
+      _chains = chains
+      _chainsUpdatedAt = Date.now()
+      updateRpcUrls()
+    },
+    async getChains() {
+      // When preloadChains is false, SDK does not auto-fetch chains
+      // External consumer is responsible for calling setChains
+      if (!config.preloadChains) {
+        return _chains
+      }
+
+      if (this.needReset || !_chains.length) {
+        _chains = await _getChains(config, {
+          chainTypes: [
+            ChainType.EVM,
+            ChainType.SVM,
+            ChainType.UTXO,
+            ChainType.MVM,
+            ChainType.TVM,
+          ],
+        })
+        _chainsUpdatedAt = Date.now()
+        updateRpcUrls()
+      }
+      return _chains
+    },
+    async getRpcUrls() {
+      await this.getChains() // _rpcUrls is updated when needed
+      return _rpcUrls
+    },
+  }
+}

package/src/core/BaseStepExecutionTask.ts

@@ -0,0 +1,9 @@
+import type { StepExecutorContext, TaskResult } from '../types/execution.js'
+
+export abstract class BaseStepExecutionTask {
+  shouldRun(_context: StepExecutorContext): Promise<boolean> {
+    return Promise.resolve(true)
+  }
+
+  abstract run(context: StepExecutorContext): Promise<TaskResult>
+}

package/src/core/BaseStepExecutor.ts

@@ -0,0 +1,129 @@
+import { ExecuteStepRetryError } from '../errors/errors.js'
+import type { SDKError } from '../errors/SDKError.js'
+import type {
+  ExecuteStepRetryParams,
+  ExecutionAction,
+  ExecutionOptions,
+  InteractionSettings,
+  LiFiStepExtended,
+  SDKClient,
+  StepExecutor,
+  StepExecutorOptions,
+} from '../types/core.js'
+import type {
+  StepExecutorBaseContext,
+  StepExecutorContext,
+} from '../types/execution.js'
+import { StatusManager } from './StatusManager.js'
+import type { TaskPipeline } from './TaskPipeline.js'
+
+// Please be careful when changing the defaults as it may break the behavior (e.g., background execution)
+const defaultInteractionSettings = {
+  allowInteraction: true,
+  allowUpdates: true,
+  allowExecution: true,
+}
+
+export abstract class BaseStepExecutor implements StepExecutor {
+  protected executionOptions?: ExecutionOptions
+  protected statusManager: StatusManager
+
+  public allowUserInteraction = true
+  public allowExecution = true
+
+  constructor(options: StepExecutorOptions) {
+    this.statusManager = new StatusManager(options.routeId)
+    this.executionOptions = options.executionOptions
+  }
+
+  setInteraction = (settings?: InteractionSettings): void => {
+    const interactionSettings = {
+      ...defaultInteractionSettings,
+      ...settings,
+    }
+    this.allowUserInteraction = interactionSettings.allowInteraction
+    this.statusManager.allowUpdates(interactionSettings.allowUpdates)
+    this.allowExecution = interactionSettings.allowExecution
+  }
+
+  private createBaseContext = async (
+    client: SDKClient,
+    step: LiFiStepExtended,
+    retryParams?: ExecuteStepRetryParams
+  ): Promise<StepExecutorBaseContext> => {
+    const fromChain = await client.getChainById(step.action.fromChainId)
+    const toChain = await client.getChainById(step.action.toChainId)
+
+    const isBridgeExecution = fromChain.id !== toChain.id
+
+    return {
+      client,
+      step,
+      fromChain,
+      toChain,
+      isBridgeExecution,
+      retryParams,
+      statusManager: this.statusManager,
+      executionOptions: this.executionOptions,
+      allowUserInteraction: this.allowUserInteraction,
+    }
+  }
+
+  abstract createContext(
+    baseContext: StepExecutorBaseContext
+  ): Promise<StepExecutorContext>
+
+  abstract createPipeline(context: StepExecutorContext): TaskPipeline
+
+  abstract parseErrors(
+    error: Error,
+    step?: LiFiStepExtended,
+    action?: ExecutionAction,
+    retryParams?: ExecuteStepRetryParams
+  ): Promise<SDKError | ExecuteStepRetryError>
+
+  executeStep = async (
+    client: SDKClient,
+    step: LiFiStepExtended,
+    retryParams?: ExecuteStepRetryParams
+  ): Promise<LiFiStepExtended> => {
+    try {
+      step.execution = this.statusManager.initializeExecution(step)
+
+      const baseContext = await this.createBaseContext(
+        client,
+        step,
+        retryParams
+      )
+      const context = await this.createContext(baseContext)
+      const pipeline = this.createPipeline(context)
+
+      await pipeline.run(context)
+
+      return step
+    } catch (error: any) {
+      // Derive failing action from last in execution.actions
+      const action = step.execution?.actions?.at(-1)
+      const parsed = await this.parseErrors(error, step, action, retryParams)
+      if (!(parsed instanceof ExecuteStepRetryError)) {
+        if (action) {
+          this.statusManager.updateAction(step, action.type, 'FAILED', {
+            error: {
+              message: parsed.cause?.message,
+              code: parsed.code,
+            },
+          })
+        } else {
+          this.statusManager.updateExecution(step, {
+            status: 'FAILED',
+            error: {
+              message: parsed.cause?.message,
+              code: parsed.code,
+            },
+          })
+        }
+      }
+      throw parsed
+    }
+  }
+}

package/src/core/StatusManager.ts

@@ -0,0 +1,245 @@
+import type { ChainId, LiFiStep } from '@lifi/types'
+import type {
+  Execution,
+  ExecutionAction,
+  ExecutionActionStatus,
+  ExecutionActionType,
+  LiFiStepExtended,
+} from '../types/core.js'
+import { getActionMessage } from './actionMessages.js'
+import { executionState } from './executionState.js'
+
+type ActionProps = {
+  step: LiFiStepExtended
+  type: ExecutionActionType
+  chainId: ChainId
+  status: ExecutionActionStatus
+}
+
+/**
+ * Manages status updates of a route and provides various functions for tracking actions.
+ */
+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
+   */
+  initializeExecution = (step: LiFiStepExtended): Execution => {
+    if (!step.execution) {
+      step.execution = {
+        startedAt: Date.now(),
+        status: 'PENDING',
+        actions: [],
+      }
+      this.updateStepInRoute(step)
+    }
+
+    // Change status to PENDING after resuming from FAILED
+    if (step.execution.status === 'FAILED') {
+      step.execution.startedAt = Date.now()
+      step.execution.status = 'PENDING'
+      step.execution.signedAt = undefined
+      step.execution.error = undefined
+      this.updateStepInRoute(step)
+    }
+
+    return step.execution
+  }
+
+  /**
+   * Updates the execution object of a Step.
+   * @param step The current step in execution
+   * @param execution Partial execution data to merge
+   * @returns The step with the updated execution object
+   */
+  updateExecution(
+    step: LiFiStepExtended,
+    execution: Partial<Execution>
+  ): LiFiStep {
+    if (!step.execution) {
+      throw Error("Can't update empty execution.")
+    }
+    step.execution = {
+      ...step.execution,
+      ...execution,
+    }
+    this.updateStepInRoute(step)
+    return step
+  }
+
+  /**
+   * Finds an action of the specified type in the step's execution
+   * @param step The step to search in
+   * @param type The action type to find
+   * @returns The found action or undefined if not found
+   */
+  findAction(
+    step: LiFiStepExtended,
+    type: ExecutionActionType
+  ): ExecutionAction | undefined {
+    if (!step.execution?.actions) {
+      throw new Error("Execution hasn't been initialized.")
+    }
+
+    const action = step.execution.actions.find((p) => p.type === type)
+
+    return action
+  }
+
+  /**
+   * Create and push a new action into the execution.
+   * Caller is responsible for ensuring an action of this type does not already exist.
+   * @param step The step that should contain the new action.
+   * @param type Type of the action.
+   * @param chainId Chain Id of the action.
+   * @param status The initial status for the new action.
+   * @returns The created action.
+   */
+  createAction = ({
+    step,
+    type,
+    chainId,
+    status,
+  }: ActionProps): ExecutionAction => {
+    if (!step.execution) {
+      throw new Error("Execution hasn't been initialized.")
+    }
+
+    const newAction: ExecutionAction = {
+      type,
+      message: getActionMessage(type, status),
+      status,
+      chainId,
+    }
+
+    step.execution.actions.push(newAction)
+    this.updateStepInRoute(step)
+    return newAction
+  }
+
+  /**
+   * Find an existing action by type and update it, or create a new one if none exists.
+   * @param step The step that should contain the action.
+   * @param type Type of the action. Used to identify already existing actions.
+   * @param chainId Chain Id of the action (used when creating).
+   * @param status The status to set on the found or newly created action.
+   * @returns The updated or newly created action.
+   */
+  initializeAction = ({
+    step,
+    type,
+    chainId,
+    status,
+  }: ActionProps): ExecutionAction => {
+    const action = this.findAction(step, type)
+
+    if (action) {
+      return this.updateAction(step, type, status, {
+        error: undefined,
+      })
+    }
+
+    return this.createAction({ step, type, chainId, status })
+  }
+
+  /**
+   * Update an action object.
+   * @param step The step where the action should be updated
+   * @param type  The action type to update
+   * @param status The status the action gets.
+   * @param [params] Additional parameters to append to the action.
+   * @returns The updated action
+   */
+  updateAction = (
+    step: LiFiStepExtended,
+    type: ExecutionActionType,
+    status: ExecutionActionStatus,
+    params?: Partial<ExecutionAction & { signedAt?: number }>
+  ): ExecutionAction => {
+    if (!step.execution) {
+      throw new Error("Can't update an empty step execution.")
+    }
+    const currentAction = this.findAction(step, type)
+
+    if (!currentAction) {
+      throw new Error("Can't find an action for the given type.")
+    }
+
+    switch (status) {
+      case 'CANCELLED':
+        break
+      case 'FAILED':
+        step.execution.status = 'FAILED'
+        if (params?.error) {
+          step.execution.error = params.error
+        }
+        break
+      case 'DONE':
+        break
+      case 'PENDING':
+        step.execution.status = 'PENDING'
+        if (params?.signedAt) {
+          step.execution.signedAt = params.signedAt
+        }
+        break
+      case 'RESET_REQUIRED':
+      case 'MESSAGE_REQUIRED':
+      case 'ACTION_REQUIRED':
+        step.execution.status = 'ACTION_REQUIRED'
+        break
+      default:
+        break
+    }
+
+    currentAction.status = status
+    currentAction.message = getActionMessage(type, status)
+    // set extra parameters or overwrite the standard params set in the switch statement
+    if (params) {
+      const { signedAt: _signedAt, ...rest } = params
+      Object.assign(currentAction, rest)
+    }
+    // Sort actions, the ones with DONE status go first
+    step.execution.actions = [
+      ...step.execution.actions.filter((action) => action.status === 'DONE'),
+      ...step.execution.actions.filter((action) => action.status !== 'DONE'),
+    ]
+    this.updateStepInRoute(step) // updates the step in the route
+    return currentAction
+  }
+
+  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/TaskPipeline.ts

@@ -0,0 +1,28 @@
+import type { StepExecutorContext, TaskResult } from '../types/execution.js'
+import type { BaseStepExecutionTask } from './BaseStepExecutionTask.js'
+
+export class TaskPipeline {
+  private readonly tasks: BaseStepExecutionTask[]
+
+  constructor(tasks: BaseStepExecutionTask[]) {
+    this.tasks = tasks
+  }
+
+  async run(context: StepExecutorContext): Promise<TaskResult> {
+    for (const task of this.tasks) {
+      const shouldRun = await task.shouldRun(context)
+      if (!shouldRun) {
+        continue
+      }
+      const result = await task.run(context)
+      if (result.status === 'PAUSED') {
+        return { status: 'PAUSED' }
+      }
+      if (result.context && typeof result.context === 'object') {
+        Object.assign(context, result.context)
+      }
+    }
+
+    return { status: 'COMPLETED' }
+  }
+}