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

package/src/actions/getStepTransaction.ts

@@ -1,4 +1,5 @@
 import type { LiFiStep, RequestOptions, SignedLiFiStep } from '@lifi/types'
+import { ChainId } from '@lifi/types'
 import type { SDKClient } from '../types/core.js'
 import { isStep } from '../utils/isStep.js'
 import { request } from '../utils/request.js'
@@ -21,16 +22,23 @@ export const getStepTransaction = async (
     console.warn('SDK Validation: Invalid Step', step)
   }
 
-  return await request<LiFiStep>(
-    client.config,
-    `${client.config.apiUrl}/advanced/stepTransaction`,
-    {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify(step),
-      signal: options?.signal,
-    }
-  )
+  const { config } = client
+
+  let requestUrl = `${config.apiUrl}/advanced/stepTransaction`
+  const isJitoBundleEnabled = Boolean(config.routeOptions?.jitoBundle)
+
+  if (isJitoBundleEnabled && step.action.fromChainId === ChainId.SOL) {
+    // add jitoBundle param to url if from chain is SVM and jitoBundle is enabled in config
+    const queryParams = new URLSearchParams({ jitoBundle: 'true' })
+    requestUrl = `${requestUrl}?${queryParams}`
+  }
+
+  return await request<LiFiStep>(config, requestUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(step),
+    signal: options?.signal,
+  })
 }

package/src/actions/index.ts

@@ -10,6 +10,7 @@ import type {
   GasRecommendationRequest,
   GasRecommendationResponse,
   LiFiStep,
+  PatchCallDataRequest,
   RelayRequest,
   RelayResponseData,
   RelayStatusRequest,
@@ -55,6 +56,10 @@ import { getTokens } from './getTokens.js'
 import { getTools } from './getTools.js'
 import { getTransactionHistory } from './getTransactionHistory.js'
 import { getWalletBalances } from './getWalletBalances.js'
+import {
+  type PatchContractCallsResponse,
+  patchContractCalls,
+} from './patchContractCalls.js'
 import { relayTransaction } from './relayTransaction.js'
 
 export type Actions = {
@@ -287,6 +292,17 @@ export type Actions = {
     params: RelayRequest,
     options?: RequestOptions
   ) => Promise<RelayResponseData>
+
+  /**
+   * Patch contract calls
+   * @param params - The configuration for the patch contract calls request
+   * @param options - Request options
+   * @returns Patched contract calls
+   */
+  patchContractCalls: (
+    params: PatchCallDataRequest,
+    options?: RequestOptions
+  ) => Promise<PatchContractCallsResponse[]>
 }
 
 export function actions(client: SDKClient): Actions {
@@ -325,5 +341,7 @@ export function actions(client: SDKClient): Actions {
       getWalletBalances(client, walletAddress, options),
     relayTransaction: (params, options) =>
       relayTransaction(client, params, options),
+    patchContractCalls: (params, options) =>
+      patchContractCalls(client, params, options),
   }
 }

package/src/actions/patchContractCalls.ts

@@ -0,0 +1,30 @@
+import type { PatchCallDataRequest, RequestOptions } from '@lifi/types'
+import type { SDKClient } from '../types/core.js'
+import { request } from '../utils/request.js'
+
+export interface PatchContractCallsResponse {
+  target: string
+  value: bigint
+  callData: string
+  allowFailure: boolean
+  isDelegateCall: boolean
+}
+
+export const patchContractCalls = async (
+  client: SDKClient,
+  params: PatchCallDataRequest,
+  options?: RequestOptions
+): Promise<PatchContractCallsResponse[]> => {
+  return await request<PatchContractCallsResponse[]>(
+    client.config,
+    `${client.config.apiUrl}/patcher`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(params),
+      signal: options?.signal,
+    }
+  )
+}

package/src/client/createClient.ts

@@ -1,4 +1,4 @@
-import type { ChainId, ChainType } from '@lifi/types'
+import type { ChainId, ChainType, ExtendedChain } from '@lifi/types'
 import type {
   SDKBaseConfig,
   SDKClient,
@@ -25,6 +25,7 @@ export function createClient(options: SDKConfig): SDKClient {
     apiUrl: options?.apiUrl ?? 'https://li.quest/v1',
     rpcUrls: options?.rpcUrls ?? {},
     debug: options?.debug ?? false,
+    preloadChains: options?.preloadChains ?? true,
     integrator: options?.integrator ?? 'lifi-sdk',
   }
 
@@ -50,6 +51,9 @@ export function createClient(options: SDKConfig): SDKClient {
       }
       _providers = Array.from(providerMap.values())
     },
+    setChains(chains: ExtendedChain[]) {
+      _storage.setChains(chains)
+    },
     async getChains() {
       return await _storage.getChains()
     },

package/src/client/getClientStorage.ts

@@ -1,39 +1,57 @@
 import { ChainId, ChainType, type ExtendedChain } from '@lifi/types'
-import { getChainsFromConfig } from '../actions/getChains.js'
+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 const getClientStorage = (config: SDKBaseConfig) => {
   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 >= 1000 * 60 * 60 * 24
+        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 getChainsFromConfig(config, {
+        _chains = await _getChains(config, {
           chainTypes: [
             ChainType.EVM,
             ChainType.SVM,
             ChainType.UTXO,
             ChainType.MVM,
+            ChainType.TVM,
           ],
         })
         _chainsUpdatedAt = Date.now()
+        updateRpcUrls()
       }
       return _chains
     },
     async getRpcUrls() {
-      if (this.needReset || !Object.keys(_rpcUrls).length) {
-        const chains = await this.getChains()
-        _rpcUrls = getRpcUrlsFromChains(_rpcUrls, chains, [ChainId.SOL])
-      }
+      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

@@ -1,12 +1,21 @@
-import type { LiFiStep } from '@lifi/types'
+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 = {
@@ -37,5 +46,85 @@ export abstract class BaseStepExecutor implements StepExecutor {
     this.allowExecution = interactionSettings.allowExecution
   }
 
-  abstract executeStep(client: SDKClient, step: LiFiStep): Promise<LiFiStep>
+  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) {
+      const action = step.execution?.lastActionType
+        ? this.statusManager.findAction(step, step.execution.lastActionType)
+        : undefined
+      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

@@ -1,27 +1,23 @@
 import type { ChainId, LiFiStep } from '@lifi/types'
 import type {
   Execution,
-  ExecutionStatus,
+  ExecutionAction,
+  ExecutionActionStatus,
+  ExecutionActionType,
   LiFiStepExtended,
-  Process,
-  ProcessStatus,
-  ProcessType,
 } from '../types/core.js'
+import { getActionMessage } from './actionMessages.js'
 import { executionState } from './executionState.js'
-import { getProcessMessage } from './processMessages.js'
 
-type FindOrCreateProcessProps = {
+type ActionProps = {
   step: LiFiStepExtended
-  type: ProcessType
-  chainId?: ChainId
-  status?: ProcessStatus
-  startedAt?: number
+  type: ExecutionActionType
+  chainId: ChainId
+  status: ExecutionActionStatus
 }
 
 /**
- * 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.
+ * Manages status updates of a route and provides various functions for tracking actions.
  */
 export class StatusManager {
   private readonly routeId: string
@@ -33,15 +29,15 @@ export class StatusManager {
 
   /**
    * 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
+   * @param step The current step in execution
+   * @returns The initialized execution object for this step
    */
-  initExecutionObject = (step: LiFiStepExtended): Execution => {
+  initializeExecution = (step: LiFiStepExtended): Execution => {
     if (!step.execution) {
       step.execution = {
-        status: 'PENDING',
-        process: [],
         startedAt: Date.now(),
+        status: 'PENDING',
+        actions: [],
       }
       this.updateStepInRoute(step)
     }
@@ -50,6 +46,9 @@ export class StatusManager {
     if (step.execution.status === 'FAILED') {
       step.execution.startedAt = Date.now()
       step.execution.status = 'PENDING'
+      step.execution.signedAt = undefined
+      step.execution.lastActionType = undefined
+      step.execution.error = undefined
       this.updateStepInRoute(step)
     }
 
@@ -58,170 +57,166 @@ export class StatusManager {
 
   /**
    * 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
+   * @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,
-    status: ExecutionStatus,
-    execution?: Partial<Execution>
+    execution: Partial<Execution>
   ): LiFiStep {
     if (!step.execution) {
       throw Error("Can't update empty execution.")
     }
-    step.execution.status = status
-    if (status === 'DONE') {
-      step.execution.doneAt = Date.now()
-    }
-    if (execution) {
-      step.execution = {
-        ...step.execution,
-        ...execution,
-      }
+    step.execution = {
+      ...step.execution,
+      ...execution,
     }
     this.updateStepInRoute(step)
     return step
   }
 
   /**
-   * Finds a process of the specified type in the step's execution
+   * Finds an action of the specified type in the step's execution
    * @param step The step to search in
-   * @param type The process type to find
-   * @param status Optional status to update the process with if found
-   * @returns The found process or undefined if not found
+   * @param type The action type to find
+   * @returns The found action or undefined if not found
    */
-  findProcess(
+  findAction(
     step: LiFiStepExtended,
-    type: ProcessType,
-    status?: ProcessStatus
-  ): Process | undefined {
-    if (!step.execution?.process) {
+    type: ExecutionActionType
+  ): ExecutionAction | undefined {
+    if (!step.execution?.actions) {
       throw new Error("Execution hasn't been initialized.")
     }
 
-    const process = step.execution.process.find((p) => p.type === type)
-
-    if (process && status && process.status !== status) {
-      process.status = status
-      this.updateStepInRoute(step)
-    }
+    const action = step.execution.actions.find((p) => p.type === type)
 
-    return process
+    return action
   }
 
   /**
-   * 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 chainId Chain Id of the process.
-   * @param status By default created process is set to the STARTED status. We can override new process with the needed status.
-   * @returns Returns process.
+   * 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.
    */
-  findOrCreateProcess = ({
+  createAction = ({
     step,
     type,
     chainId,
     status,
-    startedAt,
-  }: FindOrCreateProcessProps): Process => {
-    const process = this.findProcess(step, type, status)
-
-    if (process) {
-      return process
+  }: ActionProps): ExecutionAction => {
+    if (!step.execution) {
+      throw new Error("Execution hasn't been initialized.")
     }
 
-    const newProcess: Process = {
-      type: type,
-      startedAt: startedAt ?? Date.now(),
-      message: getProcessMessage(type, status ?? 'STARTED'),
-      status: status ?? 'STARTED',
-      chainId: chainId,
+    const newAction: ExecutionAction = {
+      type,
+      message: getActionMessage(type, status),
+      status,
+      chainId,
     }
 
-    step.execution!.process.push(newProcess)
+    step.execution.actions.push(newAction)
+    step.execution.lastActionType = type
     this.updateStepInRoute(step)
-    return newProcess
+    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 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
+   * 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
    */
-  updateProcess = (
+  updateAction = (
     step: LiFiStepExtended,
-    type: ProcessType,
-    status: ProcessStatus,
-    params?: Partial<Process>
-  ): Process => {
+    type: ExecutionActionType,
+    status: ExecutionActionStatus,
+    params?: Partial<ExecutionAction & { signedAt?: number }>
+  ): ExecutionAction => {
     if (!step.execution) {
       throw new Error("Can't update an empty step execution.")
     }
-    const currentProcess = this.findProcess(step, type)
+    const currentAction = this.findAction(step, type)
 
-    if (!currentProcess) {
-      throw new Error("Can't find a process for the given type.")
+    if (!currentAction) {
+      throw new Error("Can't find an action for the given type.")
     }
 
     switch (status) {
       case 'CANCELLED':
-        currentProcess.doneAt = Date.now()
         break
       case 'FAILED':
-        currentProcess.doneAt = Date.now()
         step.execution.status = 'FAILED'
+        if (params?.error) {
+          step.execution.error = params.error
+        }
         break
       case 'DONE':
-        currentProcess.doneAt = Date.now()
         break
       case 'PENDING':
         step.execution.status = 'PENDING'
-        currentProcess.pendingAt = Date.now()
+        if (params?.signedAt) {
+          step.execution.signedAt = params.signedAt
+        }
         break
       case 'RESET_REQUIRED':
       case 'MESSAGE_REQUIRED':
       case 'ACTION_REQUIRED':
         step.execution.status = 'ACTION_REQUIRED'
-        currentProcess.actionRequiredAt = Date.now()
         break
       default:
         break
     }
 
-    currentProcess.status = status
-    currentProcess.message = getProcessMessage(type, status)
-    // set extra parameters or overwritte the standard params set in the switch statement
+    step.execution.lastActionType = type
+
+    currentAction.status = status
+    currentAction.message = getActionMessage(type, status)
+    // set extra parameters or overwrite the standard params set in the switch statement
     if (params) {
-      for (const [key, value] of Object.entries(params)) {
-        currentProcess[key] = value
-      }
+      const { signedAt: _signedAt, ...rest } = params
+      Object.assign(currentAction, rest)
     }
-    // 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'),
+    // 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 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)
+    return currentAction
   }
 
   updateStepInRoute = (step: LiFiStep): LiFiStep => {

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