@lifi/sdk 0.0.0-preview-f5cf9f8

package/src/core/tasks/helpers/checkBalance.ts

@@ -0,0 +1,218 @@
+import type { LiFiStep, Token, TokenAmount } from '@lifi/types'
+import { BalanceError } from '../../../errors/errors.js'
+import type { SDKClient } from '../../../types/core.js'
+import { formatUnits } from '../../../utils/formatUnits.js'
+import { sleep } from '../../../utils/sleep.js'
+import { withTimeout } from '../../../utils/withTimeout.js'
+
+const MAX_ATTEMPTS = 6
+// Exponential backoff: 150, 300, 600, 1200, 2400 → ≈4.65s of sleep total.
+const BACKOFF_BASE_MS = 150
+const OVERALL_TIMEOUT_MS = 10_000
+const SLIPPAGE_PRECISION = 1_000_000_000n
+
+type Bucket = 'source' | 'gas' | 'fee'
+
+type Requirement = {
+  token: Token
+  sourcePart: bigint // step.action.fromAmount
+  gasPart: bigint // step.estimate.gasCosts in this token
+  feePart: bigint // non-included step.estimate.feeCosts in this token
+}
+
+export type CheckBalanceOptions = {
+  /**
+   * Set to `false` when outer-tx gas is paid by something other than
+   * `walletAddress` (SCA executor, 4337 bundler / paymaster, relayer):
+   * `gasPart` is excluded from the sufficiency check and slippage rescue.
+   * Source amount and non-included fees (e.g. LZ `msg.value`) are still
+   * verified. Defaults to `true` (strict, today's behavior).
+   */
+  walletPaysGas?: boolean
+}
+
+/**
+ * Verifies that the wallet holds enough of every token required to execute
+ * the step on its source chain — the source-token amount, any gas costs, and
+ * any non-included fee costs. Reads all balances in one batched provider
+ * call, retries within a bounded budget to absorb transient RPC failures and
+ * post-confirmation propagation lag, and applies slippage to the source-token
+ * portion only as a last resort (overhead is never trimmed).
+ *
+ * Throws BalanceError("The balance is too low.") on a genuine shortfall, or
+ * BalanceError("Could not read wallet balance.") if the balance can't be read
+ * after retries.
+ */
+export const checkBalance = async (
+  client: SDKClient,
+  walletAddress: string,
+  step: LiFiStep,
+  options: CheckBalanceOptions = {}
+): Promise<void> => {
+  const fromChainId = step.action.fromChainId
+  // Chains with non-standard native decimals (e.g. Tempo, Stable) report
+  // gas costs in units that don't align with wallet balances — drop the
+  // gas portion of the check on those chains.
+  const fromChain = await client.getChainById(fromChainId)
+  const walletPaysGas =
+    (options.walletPaysGas ?? true) && !fromChain.nonStandardNativeDecimals
+  const requirements = new Map<string, Requirement>()
+  const add = (token: Token, amount: bigint, bucket: Bucket): void => {
+    if (token.chainId !== fromChainId || amount === 0n) {
+      return
+    }
+    const key = token.address.toLowerCase()
+    const req = requirements.get(key) ?? {
+      token,
+      sourcePart: 0n,
+      gasPart: 0n,
+      feePart: 0n,
+    }
+    if (bucket === 'source') {
+      req.sourcePart += amount
+    } else if (bucket === 'gas') {
+      req.gasPart += amount
+    } else {
+      req.feePart += amount
+    }
+    requirements.set(key, req)
+  }
+  add(step.action.fromToken, BigInt(step.action.fromAmount), 'source')
+  for (const gas of step.estimate?.gasCosts ?? []) {
+    add(gas.token, BigInt(gas.amount), 'gas')
+  }
+  for (const fee of step.estimate?.feeCosts ?? []) {
+    // Included fees are already part of fromAmount — don't count twice.
+    if (!fee.included) {
+      add(fee.token, BigInt(fee.amount), 'fee')
+    }
+  }
+
+  const reservedOverhead = (r: Requirement): bigint =>
+    r.feePart + (walletPaysGas ? r.gasPart : 0n)
+  const need = (r: Requirement): bigint => r.sourcePart + reservedOverhead(r)
+
+  // Drop pure-gas entries when `walletPaysGas` is false (e.g. native ETH
+  // on Safe Apps with only `gasPart`) — saves one balance read each.
+  for (const [key, req] of requirements) {
+    if (need(req) === 0n) {
+      requirements.delete(key)
+    }
+  }
+
+  if (requirements.size === 0) {
+    return
+  }
+
+  // Provider is dispatched by wallet address; all requirements share the
+  // source chain, which matches this provider by virtue of the address.
+  const provider = client.providers.find((p) => p.isAddress(walletAddress))
+  if (!provider) {
+    throw new Error(`SDK Token Provider for ${walletAddress} is not found.`)
+  }
+
+  const reqs = Array.from(requirements.values())
+  const tokens = reqs.map((r) => r.token)
+  const slippage = step.action.slippage ?? 0
+  const slippageScaled = BigInt(
+    Math.floor((1 - slippage) * Number(SLIPPAGE_PRECISION))
+  )
+
+  await withTimeout(
+    async () => {
+      for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        const isFinal = attempt === MAX_ATTEMPTS - 1
+
+        let balances: TokenAmount[]
+        try {
+          balances = await provider.getBalance(client, walletAddress, tokens)
+        } catch (error) {
+          if (isFinal) {
+            throw new BalanceError(
+              'Could not read wallet balance.',
+              error as Error
+            )
+          }
+          await sleep(BACKOFF_BASE_MS * 2 ** attempt)
+          continue
+        }
+
+        const balanceByAddress = new Map(
+          balances.map((b) => [b.address.toLowerCase(), b.amount] as const)
+        )
+
+        const unknown: Token[] = []
+        const insufficient: { req: Requirement; have: bigint }[] = []
+        for (const req of reqs) {
+          const have = balanceByAddress.get(req.token.address.toLowerCase())
+          if (have === undefined) {
+            unknown.push(req.token)
+          } else if (have < need(req)) {
+            insufficient.push({ req, have })
+          }
+        }
+
+        if (unknown.length === 0 && insufficient.length === 0) {
+          return
+        }
+
+        // Final-attempt slippage rescue: only when the sole shortfall is
+        // the source-token portion. Trim source to (balance − reserved
+        // overhead) so the overhead reserve is preserved.
+        if (
+          isFinal &&
+          unknown.length === 0 &&
+          insufficient.length === 1 &&
+          insufficient[0].req.sourcePart > 0n
+        ) {
+          const { req, have } = insufficient[0]
+          const reserved = reservedOverhead(req)
+          const minAcceptable =
+            (req.sourcePart * slippageScaled) / SLIPPAGE_PRECISION + reserved
+          if (have >= minAcceptable) {
+            const newFromAmount = (have - reserved).toString()
+            step.action.fromAmount = newFromAmount
+            if (step.includedSteps?.length) {
+              step.includedSteps[0].action.fromAmount = newFromAmount
+            }
+            return
+          }
+        }
+
+        if (isFinal) {
+          if (unknown.length > 0) {
+            throw new BalanceError(
+              'Could not read wallet balance.',
+              new Error(
+                `Could not read balance for: ${unknown
+                  .map((t) => t.symbol || t.address)
+                  .join(', ')}.`
+              )
+            )
+          }
+          const lines = insufficient.map(({ req, have }) => {
+            const needed = formatUnits(need(req), req.token.decimals)
+            const current = formatUnits(have, req.token.decimals)
+            const symbol = req.token.symbol
+            // The "fees" branch covers pure-overhead tokens; with
+            // walletPaysGas=false, gas is excluded from `need(req)` so it
+            // only fires for genuine fee shortfalls.
+            return req.sourcePart > 0n
+              ? `Your ${symbol} balance is too low, you try to transfer ${needed} ${symbol}, but your wallet only holds ${current} ${symbol}.`
+              : `Insufficient ${symbol} for fees: need ${needed} ${symbol}, have ${current} ${symbol}.`
+          })
+          throw new BalanceError(
+            'The balance is too low.',
+            new Error(`${lines.join(' ')} No funds have been sent.`)
+          )
+        }
+
+        await sleep(BACKOFF_BASE_MS * 2 ** attempt)
+      }
+    },
+    {
+      timeout: OVERALL_TIMEOUT_MS,
+      errorInstance: new BalanceError('Could not read wallet balance.'),
+    }
+  )
+}

package/src/core/tasks/helpers/getTransactionRequestData.ts

@@ -0,0 +1,47 @@
+import { LiFiErrorCode } from '../../../errors/constants.js'
+import { TransactionError } from '../../../errors/errors.js'
+import type {
+  ExecutionOptions,
+  LiFiStepExtended,
+  TransactionParameters,
+} from '../../../types/core.js'
+
+export const getTransactionRequestData = async (
+  step: LiFiStepExtended,
+  executionOptions?: ExecutionOptions
+): Promise<string> => {
+  if (!step.transactionRequest?.data) {
+    throw new TransactionError(
+      LiFiErrorCode.TransactionUnprepared,
+      'Unable to prepare transaction. Transaction request data is not found.'
+    )
+  }
+
+  let transactionRequest: TransactionParameters = {
+    data: step.transactionRequest.data,
+  }
+
+  if (executionOptions?.updateTransactionRequestHook) {
+    const customizedTransactionRequest: TransactionParameters =
+      await executionOptions.updateTransactionRequestHook({
+        requestType: 'transaction',
+        ...transactionRequest,
+      })
+
+    transactionRequest = {
+      ...transactionRequest,
+      ...customizedTransactionRequest,
+    }
+  }
+
+  const transactionRequestData = transactionRequest.data
+
+  if (!transactionRequestData) {
+    throw new TransactionError(
+      LiFiErrorCode.TransactionUnprepared,
+      'Unable to prepare transaction. Transaction request data is not found.'
+    )
+  }
+
+  return transactionRequestData
+}

package/src/core/tasks/helpers/stepComparison.ts

@@ -0,0 +1,50 @@
+import type { LiFiStep } from '@lifi/types'
+import type { StatusManager } from '../../../core/StatusManager.js'
+import { checkStepSlippageThreshold } from '../../../core/utils.js'
+import { LiFiErrorCode } from '../../../errors/constants.js'
+import { TransactionError } from '../../../errors/errors.js'
+import type { ExecutionOptions } from '../../../types/core.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!\nTransaction was not sent, your funds are still in your wallet.\nThe exchange rate has changed and the previous estimation can not be fulfilled due to value loss.'
+    )
+  }
+
+  return statusManager.updateStepInRoute(newStep)
+}

package/src/core/tasks/helpers/waitForTransactionStatus.ts

@@ -0,0 +1,76 @@
+import type { FullStatusData, LiFiStep, StatusResponse } from '@lifi/types'
+import { getStatus } from '../../../actions/getStatus.js'
+import { ServerError } from '../../../errors/errors.js'
+import type { ExecutionActionType, SDKClient } from '../../../types/core.js'
+import { waitForResult } from '../../../utils/waitForResult.js'
+import { getSubstatusMessage } from '../../actionMessages.js'
+import type { StatusManager } from '../../StatusManager.js'
+
+const TRANSACTION_HASH_OBSERVERS: Record<string, Promise<StatusResponse>> = {}
+
+export async function waitForTransactionStatus(
+  client: SDKClient,
+  statusManager: StatusManager,
+  txHash: string,
+  step: LiFiStep,
+  actionType: ExecutionActionType,
+  interval = 5_000
+): Promise<StatusResponse> {
+  const _getStatus = (): Promise<StatusResponse | undefined> => {
+    return getStatus(client, {
+      fromChain: step.action.fromChainId,
+      fromAddress: step.action.fromAddress,
+      toChain: step.action.toChainId,
+      txHash,
+      ...(step.tool !== 'custom' && { bridge: step.tool }),
+      ...(step.transactionId && { transactionId: step.transactionId }),
+    })
+      .then((statusResponse) => {
+        switch (statusResponse.status) {
+          case 'DONE':
+            return statusResponse
+          case 'PENDING':
+            statusManager?.updateAction(step, actionType, 'PENDING', {
+              substatus: statusResponse.substatus,
+              substatusMessage:
+                statusResponse.substatusMessage ||
+                getSubstatusMessage(
+                  statusResponse.status,
+                  statusResponse.substatus
+                ),
+              txLink: (statusResponse as FullStatusData).bridgeExplorerLink,
+            })
+            return undefined
+          case 'NOT_FOUND':
+            return undefined
+          default:
+            return Promise.reject()
+        }
+      })
+      .catch((e) => {
+        if (process.env.NODE_ENV === 'development') {
+          console.debug('Fetching status from backend failed.', e)
+        }
+        return undefined
+      })
+  }
+
+  let status = TRANSACTION_HASH_OBSERVERS[txHash]
+
+  if (!status) {
+    status = waitForResult(_getStatus, interval).finally(() => {
+      delete TRANSACTION_HASH_OBSERVERS[txHash]
+    })
+    TRANSACTION_HASH_OBSERVERS[txHash] = status
+  }
+
+  const resolvedStatus = await status
+
+  if (!('receiving' in resolvedStatus)) {
+    throw new ServerError(
+      "Status doesn't contain destination chain information."
+    )
+  }
+
+  return resolvedStatus
+}

package/src/core/utils.ts

@@ -0,0 +1,59 @@
+import type { ChainId, ExtendedChain, LiFiStep } from '@lifi/types'
+import type { RPCUrls } from '../types/core.js'
+
+// Standard threshold for destination amount difference (0.5%)
+const standardThreshold = 0.005
+
+/**
+ * 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 - old step
+ * @param newStep - new step
+ * @returns Boolean
+ */
+export function checkStepSlippageThreshold(
+  oldStep: LiFiStep,
+  newStep: LiFiStep
+): boolean {
+  const setSlippage = oldStep.action.slippage || standardThreshold
+  const oldEstimatedToAmount = BigInt(oldStep.estimate.toAmountMin)
+  const newEstimatedToAmount = BigInt(newStep.estimate.toAmountMin)
+  const amountDifference = oldEstimatedToAmount - newEstimatedToAmount
+  // oldEstimatedToAmount can be 0 when we use contract calls
+  let actualSlippage = 0
+  if (oldEstimatedToAmount > 0) {
+    actualSlippage =
+      Number((amountDifference * 1_000_000_000n) / oldEstimatedToAmount) /
+      1_000_000_000
+  }
+  return actualSlippage <= setSlippage
+}
+
+export function getRpcUrlsFromChains(
+  existingRpcUrls: RPCUrls,
+  chains: ExtendedChain[],
+  skipChains?: ChainId[]
+): RPCUrls {
+  const rpcUrlsFromChains = chains.reduce((rpcUrls, chain) => {
+    if (chain.metamask?.rpcUrls?.length) {
+      rpcUrls[chain.id as ChainId] = chain.metamask.rpcUrls
+    }
+    return rpcUrls
+  }, {} as RPCUrls)
+  const result = { ...existingRpcUrls }
+  for (const rpcUrlsKey in rpcUrlsFromChains) {
+    const chainId = Number(rpcUrlsKey) as ChainId
+    const urls = rpcUrlsFromChains[chainId]
+    if (!urls?.length) {
+      continue
+    }
+    if (!result[chainId]?.length) {
+      result[chainId] = Array.from(urls)
+    } else if (!skipChains?.includes(chainId)) {
+      const filteredUrls = urls.filter((url) => !result[chainId]?.includes(url))
+      result[chainId].push(...filteredUrls)
+    }
+  }
+  return result
+}

package/src/errors/SDKError.ts

@@ -0,0 +1,26 @@
+import type { LiFiStep } from '@lifi/types'
+import type { ExecutionAction } from '../types/core.js'
+import { version } from '../version.js'
+import type { BaseError } from './baseError.js'
+import type { ErrorCode } from './constants.js'
+
+// Note: SDKError is used to wrapper and present errors at the top level
+// Where opportunity allows we also add the step and the action related to the error
+export class SDKError extends Error {
+  step?: LiFiStep
+  action?: ExecutionAction
+  code: ErrorCode
+  override name = 'SDKError'
+  override cause: BaseError
+
+  constructor(cause: BaseError, step?: LiFiStep, action?: ExecutionAction) {
+    const errorMessage = `${cause.message ? `[${cause.name}] ${cause.message}` : 'Unknown error occurred'}\nLI.FI SDK version: ${version}`
+    super(errorMessage)
+    this.name = 'SDKError'
+    this.step = step
+    this.action = action
+    this.cause = cause
+    this.stack = this.cause.stack
+    this.code = cause.code
+  }
+}

package/src/errors/baseError.ts

@@ -0,0 +1,22 @@
+import type { ErrorCode, ErrorName } from './constants.js'
+import { getRootCause } from './utils/rootCause.js'
+
+// Note: we use the BaseErrors to capture errors at specific points in the code
+// they can carry addition to help give more context
+export class BaseError extends Error {
+  code: ErrorCode
+  override cause?: Error
+
+  constructor(name: ErrorName, code: number, message: string, cause?: Error) {
+    super(message)
+
+    this.name = name
+    this.code = code
+    this.cause = cause
+
+    const rootCause = getRootCause(this.cause)
+    if (rootCause?.stack) {
+      this.stack = rootCause.stack
+    }
+  }
+}

package/src/errors/constants.ts

@@ -0,0 +1,54 @@
+export enum ErrorName {
+  RPCError = 'RPCError',
+  ProviderError = 'ProviderError',
+  ServerError = 'ServerError',
+  TransactionError = 'TransactionError',
+  ValidationError = 'ValidationError',
+  BalanceError = 'BalanceError',
+  NotFoundError = 'NotFoundError',
+  UnknownError = 'UnknownError',
+  SlippageError = 'SlippageError',
+  HTTPError = 'HTTPError',
+  ConfigError = 'ConfigError',
+  ExecuteStepRetryError = 'ExecuteStepRetryError',
+}
+
+export type ErrorCode = LiFiErrorCode
+
+export enum LiFiErrorCode {
+  InternalError = 1000,
+  ValidationError = 1001,
+  TransactionUnderpriced = 1002,
+  TransactionFailed = 1003,
+  Timeout = 1004,
+  ProviderUnavailable = 1005,
+  NotFound = 1006,
+  ChainSwitchError = 1007,
+  TransactionUnprepared = 1008,
+  GasLimitError = 1009,
+  TransactionCanceled = 1010,
+  SlippageError = 1011,
+  SignatureRejected = 1012,
+  BalanceError = 1013,
+  AllowanceRequired = 1014,
+  InsufficientFunds = 1015,
+  ExchangeRateUpdateCanceled = 1016,
+  WalletChangedDuringExecution = 1017,
+  TransactionExpired = 1018,
+  TransactionSimulationFailed = 1019,
+  TransactionConflict = 1020,
+  TransactionNotFound = 1021,
+  TransactionRejected = 1022,
+  RateLimitExceeded = 1023,
+  ThirdPartyError = 1024,
+  InsufficientGas = 1025,
+  ConfigError = 1026,
+}
+
+export enum ErrorMessage {
+  UnknownError = 'Unknown error occurred.',
+  SlippageError = 'The slippage is larger than the defined threshold. Please request a new route to get a fresh quote.',
+  GasLimitLow = 'Gas limit is too low.',
+  TransactionUnderpriced = 'Transaction is underpriced.',
+  TransactionReverted = 'Transaction was reverted.',
+}

package/src/errors/errors.ts

@@ -0,0 +1,68 @@
+import type { ExecuteStepRetryParams } from '../types/core.js'
+import { BaseError } from './baseError.js'
+import { ErrorName, LiFiErrorCode } from './constants.js'
+
+export class RPCError extends BaseError {
+  constructor(code: LiFiErrorCode, message: string, cause?: Error) {
+    super(ErrorName.RPCError, code, message, cause)
+  }
+}
+
+export class ProviderError extends BaseError {
+  constructor(code: LiFiErrorCode, message: string, cause?: Error) {
+    super(ErrorName.ProviderError, code, message, cause)
+  }
+}
+
+export class TransactionError extends BaseError {
+  constructor(code: LiFiErrorCode, message: string, cause?: Error) {
+    super(ErrorName.TransactionError, code, message, cause)
+  }
+}
+
+export class UnknownError extends BaseError {
+  constructor(message: string, cause?: Error) {
+    super(ErrorName.UnknownError, LiFiErrorCode.InternalError, message, cause)
+  }
+}
+
+export class BalanceError extends BaseError {
+  constructor(message: string, cause?: Error) {
+    super(ErrorName.BalanceError, LiFiErrorCode.BalanceError, message, cause)
+  }
+}
+
+export class ServerError extends BaseError {
+  constructor(message: string) {
+    super(ErrorName.ServerError, LiFiErrorCode.InternalError, message)
+  }
+}
+
+export class ValidationError extends BaseError {
+  constructor(message: string) {
+    super(ErrorName.ValidationError, LiFiErrorCode.ValidationError, message)
+  }
+}
+
+/**
+ * Thrown by a step executor when executeStep should be retried with the given params
+ * (e.g. wallet rejected 7702 upgrade → retry with atomicityNotReady).
+ * The execution layer catches this and retries executeStep(client, step, retryParams).
+ */
+export class ExecuteStepRetryError extends BaseError {
+  readonly retryParams: ExecuteStepRetryParams
+
+  constructor(
+    message: string,
+    retryParams: ExecuteStepRetryParams,
+    cause?: Error
+  ) {
+    super(
+      ErrorName.ExecuteStepRetryError,
+      LiFiErrorCode.InternalError,
+      message,
+      cause
+    )
+    this.retryParams = retryParams
+  }
+}