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

package/dist/core/types.ts

@@ -0,0 +1,103 @@
+import type {
+  ChainType,
+  LiFiStep,
+  Route,
+  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: LiFiStep): Promise<LiFiStep>
+}
+
+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/dist/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
+}

package/dist/core/waitForReceivingTransaction.ts

@@ -0,0 +1,73 @@
+import type {
+  FullStatusData,
+  LiFiStep,
+  ProcessType,
+  StatusResponse,
+} from '@lifi/types'
+import { getStatus } from '../services/api.js'
+import { ServerError } from '../utils/errors.js'
+import { repeatUntilDone } from '../utils/utils.js'
+import type { StatusManager } from './StatusManager.js'
+import { getSubstatusMessage } from './utils.js'
+
+const TRANSACTION_HASH_OBSERVERS: Record<string, Promise<StatusResponse>> = {}
+
+export async function waitForReceivingTransaction(
+  txHash: string,
+  statusManager: StatusManager,
+  processType: ProcessType,
+  step: LiFiStep
+): Promise<StatusResponse> {
+  const _getStatus = (): Promise<StatusResponse | undefined> =>
+    new Promise(async (resolve, reject) => {
+      let statusResponse: StatusResponse
+      try {
+        statusResponse = await getStatus({
+          bridge: step.tool,
+          fromChain: step.action.fromChainId,
+          toChain: step.action.toChainId,
+          txHash,
+        })
+      } catch (e: any) {
+        console.debug('Fetching status from backend failed.', e)
+        return resolve(undefined)
+      }
+
+      switch (statusResponse.status) {
+        case 'DONE':
+          return resolve(statusResponse)
+        case 'PENDING':
+          statusManager?.updateProcess(step, processType, 'PENDING', {
+            substatus: statusResponse.substatus,
+            substatusMessage:
+              statusResponse.substatusMessage ||
+              getSubstatusMessage(
+                statusResponse.status,
+                statusResponse.substatus
+              ),
+            txLink: (statusResponse as FullStatusData).bridgeExplorerLink,
+          })
+          return resolve(undefined)
+        case 'NOT_FOUND':
+          return resolve(undefined)
+        case 'FAILED':
+        default:
+          return reject()
+      }
+    })
+
+  let status
+
+  if (txHash in TRANSACTION_HASH_OBSERVERS) {
+    status = await TRANSACTION_HASH_OBSERVERS[txHash]
+  } else {
+    TRANSACTION_HASH_OBSERVERS[txHash] = repeatUntilDone(_getStatus, 5_000)
+    status = await TRANSACTION_HASH_OBSERVERS[txHash]
+  }
+
+  if (!status.receiving) {
+    throw new ServerError("Status doesn't contain receiving information.")
+  }
+
+  return status
+}

package/dist/createConfig.ts

@@ -0,0 +1,54 @@
+/* eslint-disable @typescript-eslint/no-empty-function */
+import type { ChainId } from '@lifi/types'
+import { config } from './config.js'
+import { isEVM } from './core/EVM/types.js'
+import { checkPackageUpdates } from './helpers.js'
+import { getChains } from './services/api.js'
+import type { SDKOptions } from './types/index.js'
+import { name, version } from './version.js'
+
+function createBaseConfig(options: SDKOptions) {
+  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'
+    )
+  }
+  config.set(options)
+  checkPackageUpdates(name, version, options.disableVersionCheck)
+}
+
+export async function createChainsConfig() {
+  const _config = config.get()
+  const chainTypes = _config.providers?.map((provider) => provider.type)
+  config.loading = getChains({ chainTypes: chainTypes }).then((chains) => {
+    config.chains = chains
+    const evmProvider = _config.providers?.find(isEVM)
+    const multicallAddresses: Partial<Record<ChainId, string>> = {}
+    for (const chain of chains) {
+      const chainId = chain.id as ChainId
+
+      // set RPCs if they were not configured by the user before
+      if (!_config.rpcUrls[chainId]?.length) {
+        _config.rpcUrls[chainId] = chain.metamask.rpcUrls
+      }
+
+      // set multicall addresses if they exist and were not configured by the user before
+      if (chain.multicallAddress && !evmProvider?.multicall?.[chainId]) {
+        multicallAddresses[chainId] = chain.multicallAddress
+      }
+    }
+    evmProvider?.setOptions({
+      multicall: multicallAddresses,
+    })
+  })
+  await config.loading
+}
+
+export function createConfig(options: SDKOptions) {
+  createBaseConfig(options)
+  createChainsConfig()
+  return {
+    set: config.set,
+    get: config.get,
+  }
+}

package/dist/helpers.ts

@@ -0,0 +1,97 @@
+import type { LiFiStep, Route } from '@lifi/types'
+import { request } from './request.js'
+import type { TenderlyResponse } from './types/index.js'
+import { ValidationError } from './utils/errors.js'
+import { name, version } from './version.js'
+
+/**
+ * Returns a random number between min (inclusive) and max (inclusive)
+ * @param min - minimum number.
+ * @param max - maximum number.
+ * @returns - random number.
+ */
+export const getRandomNumber = (min: number, max: number): number => {
+  return Math.floor(Math.random() * (max - min + 1) + min)
+}
+
+function semverCompare(a: string, b: string) {
+  if (a.startsWith(b + '-')) {
+    return -1
+  }
+  if (b.startsWith(a + '-')) {
+    return 1
+  }
+  return a.localeCompare(b, undefined, {
+    numeric: true,
+    sensitivity: 'case',
+    caseFirst: 'upper',
+  })
+}
+
+export const checkPackageUpdates = async (
+  packageName?: string,
+  packageVersion?: string,
+  disableCheck?: boolean
+) => {
+  if (disableCheck || process.env.NODE_ENV !== 'development') {
+    return
+  }
+  try {
+    const pkgName = packageName ?? name
+    const response = await request<{ version: string }>(
+      `https://registry.npmjs.org/${pkgName}/latest`,
+      { skipTrackingHeaders: true }
+    )
+    const latestVersion = response.version
+    const currentVersion = packageVersion ?? version
+    if (semverCompare(latestVersion, currentVersion)) {
+      console.warn(
+        // eslint-disable-next-line max-len
+        `${pkgName}: new package version is available. Please update as soon as possible to enjoy the newest features. Current version: ${currentVersion}. Latest version: ${latestVersion}.`
+      )
+    }
+  } catch (error) {
+    // Cannot verify version, might be network error etc. We don't bother showing anything in that case
+  }
+}
+
+/**
+ * Converts a quote to Route
+ * @param step - Step returned from the quote endpoint.
+ * @returns - The route to be executed.
+ * @throws {ValidationError} Throws a ValidationError if the step has missing values.
+ */
+export const convertQuoteToRoute = (step: LiFiStep): Route => {
+  if (!step.estimate.fromAmountUSD) {
+    throw new ValidationError("Missing 'fromAmountUSD' in step estimate.")
+  }
+
+  if (!step.estimate.toAmountUSD) {
+    throw new ValidationError("Missing 'toAmountUSD' in step estimate.")
+  }
+
+  const route: Route = {
+    fromToken: step.action.fromToken,
+    toToken: step.action.toToken,
+    fromAmount: step.action.fromAmount,
+    toAmount: step.estimate.toAmount,
+    id: step.id,
+    fromChainId: step.action.fromToken.chainId,
+    toChainId: step.action.toToken.chainId,
+    fromAmountUSD: step.estimate.fromAmountUSD,
+    toAmountUSD: step.estimate.toAmountUSD,
+    steps: [step],
+    toAmountMin: step.estimate.toAmountMin,
+    insurance: { state: 'NOT_INSURABLE', feeAmountUsd: '0' },
+  }
+
+  return route
+}
+
+export const fetchTxErrorDetails = async (txHash: string, chainId: number) => {
+  const response = await request<TenderlyResponse>(
+    `https://api.tenderly.co/api/v1/public-contract/${chainId}/tx/${txHash}`
+  )
+
+  return response
+}

package/dist/index.ts

@@ -0,0 +1,11 @@
+export * from '@lifi/types'
+export { EVM } from './core/EVM/EVM.js'
+export { Solana } from './core/Solana/Solana.js'
+export * from './core/index.js'
+export { createConfig } from './createConfig.js'
+export * from './helpers.js'
+export * from './services/api.js'
+export * from './services/balance.js'
+export * from './types/index.js'
+export * from './utils/errors.js'
+export { LiFiError, type ErrorCode } from './utils/errors.js'

package/dist/request.ts

@@ -0,0 +1,79 @@
+import { config } from './config.js'
+import { HTTPError } from './utils/errors.js'
+import { wait } from './utils/utils.js'
+import { version } from './version.js'
+
+export const requestSettings = {
+  retries: 1,
+}
+
+interface ExtendedRequestInit extends RequestInit {
+  retries?: number
+  skipTrackingHeaders?: boolean
+}
+
+export const request = async <T = Response>(
+  url: RequestInfo | URL,
+  options: ExtendedRequestInit = {
+    retries: requestSettings.retries,
+  }
+): Promise<T> => {
+  const { userId, integrator, widgetVersion, apiKey } = config.get()
+  if (!integrator) {
+    throw new Error(
+      'Integrator not found. Please see documentation https://docs.li.fi/integrate-li.fi-js-sdk/set-up-the-sdk'
+    )
+  }
+  options.retries = options.retries ?? requestSettings.retries
+  try {
+    if (!options.skipTrackingHeaders) {
+      if (apiKey) {
+        options.headers = {
+          ...options?.headers,
+          'x-lifi-api-key': apiKey,
+        }
+      }
+
+      if (userId) {
+        options.headers = {
+          ...options?.headers,
+          'x-lifi-userid': userId,
+        }
+      }
+
+      if (widgetVersion) {
+        options.headers = {
+          ...options?.headers,
+          'x-lifi-widget': widgetVersion,
+        }
+      }
+
+      if (version) {
+        options.headers = {
+          ...options?.headers,
+          'x-lifi-sdk': version,
+        }
+      }
+
+      // integrator is mandatory during SDK initialization
+      options.headers = {
+        ...options?.headers,
+        'x-lifi-integrator': integrator,
+      }
+    }
+
+    const response: Response = await fetch(url, options)
+    if (!response.ok) {
+      throw new HTTPError(response)
+    }
+
+    const data: T = await response.json()
+    return data
+  } catch (error) {
+    if (options.retries > 0 && (error as HTTPError)?.status === 500) {
+      await wait(500)
+      return request<T>(url, { ...options, retries: options.retries - 1 })
+    }
+    throw error
+  }
+}