@lifi/sdk 3.0.1 → 3.1.0-beta.0

package/src/core/Solana/getSolanaBalance.ts

@@ -1,6 +1,6 @@
 import type { ChainId, Token, TokenAmount } from '@lifi/types'
 import { PublicKey } from '@solana/web3.js'
-import { wrappedSolAddress } from '../../constants.js'
+import { SolSystemProgram } from '../../constants.js'
 import { getSolanaConnection } from './connection.js'
 import { TokenProgramAddress } from './types.js'
 
@@ -53,8 +53,7 @@ const getSolanaBalanceDefault = async (
           {} as Record<string, bigint>
         )
       : {}
-  walletTokenAmounts[wrappedSolAddress] ??= 0n
-  walletTokenAmounts[wrappedSolAddress] += solBalance
+  walletTokenAmounts[SolSystemProgram] = solBalance
   const tokenAmounts: TokenAmount[] = tokens.map((token) => {
     if (walletTokenAmounts[token.address]) {
       return {

package/src/core/Solana/parseSolanaErrors.ts

@@ -0,0 +1,45 @@
+import type { LiFiStep, Process } from '@lifi/types'
+import { BaseError } from '../../errors/baseError.js'
+import { ErrorMessage, LiFiErrorCode } from '../../errors/constants.js'
+import { TransactionError, UnknownError } from '../../errors/errors.js'
+import { SDKError } from '../../errors/SDKError.js'
+
+export const parseSolanaErrors = async (
+  e: Error,
+  step?: LiFiStep,
+  process?: Process
+): Promise<SDKError> => {
+  if (e instanceof SDKError) {
+    e.step = e.step ?? step
+    e.process = e.process ?? process
+    return e
+  }
+
+  const baseError = handleSpecificErrors(e)
+
+  return new SDKError(baseError, step, process)
+}
+
+const handleSpecificErrors = (e: any) => {
+  if (e.name === 'WalletSignTransactionError') {
+    return new TransactionError(LiFiErrorCode.SignatureRejected, e.message, e)
+  }
+
+  if (e.name === 'SendTransactionError') {
+    return new TransactionError(LiFiErrorCode.TransactionFailed, e.message, e)
+  }
+
+  if (e.message?.includes('simulate')) {
+    return new TransactionError(
+      LiFiErrorCode.TransactionSimulationFailed,
+      e.message,
+      e
+    )
+  }
+
+  if (e instanceof BaseError) {
+    return e
+  }
+
+  return new UnknownError(e.message || ErrorMessage.UnknownError, e)
+}

package/src/core/StatusManager.ts

@@ -7,8 +7,8 @@ import type {
   ProcessType,
 } from '@lifi/types'
 import { executionState } from './executionState.js'
+import { getProcessMessage } from './processMessages.js'
 import type { LiFiStepExtended } from './types.js'
-import { getProcessMessage } from './utils.js'
 
 type OptionalParameters = Partial<
   Pick<

package/src/core/checkBalance.ts

@@ -1,7 +1,8 @@
 import type { LiFiStep } from '@lifi/types'
 import { formatUnits } from 'viem'
 import { getTokenBalance } from '../services/balance.js'
-import { BalanceError } from '../utils/errors.js'
+import { BalanceError } from '../errors/errors.js'
+import { sleep } from './utils.js'
 
 export const checkBalance = async (
   walletAddress: string,
@@ -15,9 +16,7 @@ export const checkBalance = async (
 
     if (currentBalance < neededBalance) {
       if (depth <= 3) {
-        await new Promise((resolve) => {
-          setTimeout(resolve, 200)
-        })
+        await sleep(200)
         await checkBalance(walletAddress, step, depth + 1)
       } else if (
         (neededBalance * BigInt((1 - step.action.slippage) * 1_000_000_000)) /
@@ -41,7 +40,7 @@ export const checkBalance = async (
             `start a new one with a maximum of ${current} ${token.symbol}.`
         }
 
-        throw new BalanceError('The balance is too low.', errorMessage)
+        throw new BalanceError('The balance is too low.')
       }
     }
   }

package/src/core/processMessages.ts

@@ -0,0 +1,81 @@
+import {
+  type ProcessStatus,
+  type ProcessType,
+  type StatusMessage,
+  type Substatus,
+} from '@lifi/types'
+
+const processMessages: Record<
+  ProcessType,
+  Partial<Record<ProcessStatus, 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.',
+    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: ProcessStatus
+): 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
+}

package/src/core/stepComparison.ts

@@ -1,5 +1,6 @@
 import type { LiFiStep } from '@lifi/types'
-import { LiFiErrorCode, TransactionError } from '../utils/errors.js'
+import { LiFiErrorCode } from '../errors/constants.js'
+import { TransactionError } from '../errors/errors.js'
 import type { StatusManager } from './StatusManager.js'
 import type { ExecutionOptions } from './types.js'
 import { checkStepSlippageThreshold } from './utils.js'
@@ -41,9 +42,7 @@ export const stepComparison = async (
     // 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.`
+      `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.`
     )
   }
 

package/src/core/utils.ts

@@ -1,92 +1,11 @@
-import {
-  type LiFiStep,
-  type ProcessStatus,
-  type ProcessType,
-  type StatusMessage,
-  type Substatus,
-} from '@lifi/types'
-
-const processMessages: Record<
-  ProcessType,
-  Partial<Record<ProcessStatus, 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.',
-    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: ProcessStatus
-): 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
-}
+import { type LiFiStep } from '@lifi/types'
 
 /**
  * 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
+ * @param oldStep - old step
+ * @param newStep - new step
  * @returns Boolean
  */
 export function checkStepSlippageThreshold(
@@ -106,3 +25,9 @@ export function checkStepSlippageThreshold(
   }
   return actualSlippage <= setSlippage
 }
+
+export function sleep(ms: number): Promise<null> {
+  return new Promise((resolve) => {
+    setTimeout(() => resolve(null), ms)
+  })
+}

package/src/core/waitForReceivingTransaction.ts

@@ -5,10 +5,10 @@ import type {
   StatusResponse,
 } from '@lifi/types'
 import { getStatus } from '../services/api.js'
-import { ServerError } from '../utils/errors.js'
+import { ServerError } from '../errors/errors.js'
 import { repeatUntilDone } from '../utils/utils.js'
 import type { StatusManager } from './StatusManager.js'
-import { getSubstatusMessage } from './utils.js'
+import { getSubstatusMessage } from './processMessages.js'
 
 const TRANSACTION_HASH_OBSERVERS: Record<string, Promise<StatusResponse>> = {}
 

package/src/errors/SDKError.ts

@@ -0,0 +1,25 @@
+import type { LiFiStep, Process } from '@lifi/types'
+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 process related to the error
+export class SDKError extends Error {
+  step?: LiFiStep
+  process?: Process
+  code: ErrorCode
+  override name = 'SDKError'
+  override cause: BaseError
+
+  constructor(cause: BaseError, step?: LiFiStep, process?: Process) {
+    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.process = process
+    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 && rootCause.stack) {
+      this.stack = rootCause.stack
+    }
+  }
+}

package/src/errors/constants.ts

@@ -0,0 +1,45 @@
+export enum ErrorName {
+  RPCError = 'RPCError',
+  ProviderError = 'ProviderError',
+  ServerError = 'ServerError',
+  TransactionError = 'TransactionError',
+  ValidationError = 'ValidationError',
+  BalanceError = 'BalanceError',
+  NotFoundError = 'NotFoundError',
+  UnknownError = 'UnknownError',
+  SlippageError = 'SlippageError',
+  HTTPError = 'HTTPError',
+}
+
+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,
+}
+
+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,44 @@
+import { ErrorName, LiFiErrorCode } from './constants.js'
+import { BaseError } from './baseError.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)
+  }
+}

package/src/errors/httpError.ts

@@ -0,0 +1,93 @@
+import type { UnavailableRoutes } from '@lifi/types'
+import { LiFiErrorCode } from './constants.js'
+import { BaseError } from './baseError.js'
+import type { ExtendedRequestInit } from '../types/request.js'
+import { ErrorName, ErrorMessage } from './constants.js'
+
+interface ServerErrorResponseBody {
+  code: number
+  message: string
+  errors?: UnavailableRoutes
+}
+
+const statusCodeToErrorClassificationMap = new Map([
+  [
+    400,
+    { type: ErrorName.ValidationError, code: LiFiErrorCode.ValidationError },
+  ],
+  [404, { type: ErrorName.NotFoundError, code: LiFiErrorCode.NotFound }],
+  [
+    409,
+    {
+      type: ErrorName.SlippageError,
+      code: LiFiErrorCode.SlippageError,
+      message: ErrorMessage.SlippageError,
+    },
+  ],
+  [500, { type: ErrorName.ServerError, code: LiFiErrorCode.InternalError }],
+])
+
+const getErrorClassificationFromStatusCode = (code: number) =>
+  statusCodeToErrorClassificationMap.get(code) ?? {
+    type: ErrorName.ServerError,
+    code: LiFiErrorCode.InternalError,
+  }
+
+const createInitialMessage = (response: Response) => {
+  const statusCode =
+    response.status || response.status === 0 ? response.status : ''
+  const title = response.statusText || ''
+  const status = `${statusCode} ${title}`.trim()
+  const reason = status ? `status code ${status}` : 'an unknown error'
+  return `Request failed with ${reason}`
+}
+
+export class HTTPError extends BaseError {
+  public response: Response
+  public status: number
+  public url: RequestInfo | URL
+  public fetchOptions: ExtendedRequestInit
+  public type?: ErrorName
+  public responseBody?: ServerErrorResponseBody
+
+  constructor(
+    response: Response,
+    url: RequestInfo | URL,
+    options: ExtendedRequestInit
+  ) {
+    const errorClassification = getErrorClassificationFromStatusCode(
+      response.status
+    )
+    const additionalMessage = errorClassification?.message
+      ? `\n${errorClassification.message}`
+      : ''
+    const message = createInitialMessage(response) + additionalMessage
+
+    super(ErrorName.HTTPError, errorClassification.code, message)
+
+    this.type = errorClassification.type
+    this.response = response
+    this.status = response.status
+    this.message = message
+    this.url = url
+    this.fetchOptions = options
+  }
+
+  async buildAdditionalDetails() {
+    if (this.type) {
+      this.message = `[${this.type}] ${this.message}`
+    }
+
+    try {
+      this.responseBody = await this.response.json()
+
+      const spacer = '\n        '
+
+      if (this.responseBody) {
+        this.message += `${spacer}responseMessage: ${this.responseBody?.message.toString().replaceAll('\n', spacer)}`
+      }
+    } catch {}
+
+    return this
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,7 @@
+export * from './baseError.js'
+export * from './constants.js'
+export * from './errors.js'
+export * from './httpError.js'
+export * from './SDKError.js'
+export * from './utils/rootCause.js'
+export * from './utils/baseErrorRootCause.js'

package/src/errors/utils/baseErrorRootCause.ts

@@ -0,0 +1,18 @@
+import { BaseError } from '../baseError.js'
+import { HTTPError } from '../httpError.js'
+
+export const getRootCauseBaseError = (e: Error) => {
+  let rootCause = e
+  while (rootCause.cause && rootCause.cause instanceof BaseError) {
+    rootCause = rootCause.cause as BaseError
+  }
+  return rootCause as BaseError
+}
+
+export const getRootCauseBaseErrorMessage = (e: Error) => {
+  const rootCause = getRootCauseBaseError(e)
+
+  return rootCause instanceof HTTPError
+    ? (rootCause as HTTPError).responseBody?.message || rootCause.message
+    : rootCause.message
+}

package/src/errors/utils/rootCause.ts

@@ -0,0 +1,7 @@
+export const getRootCause = (e: Error | undefined) => {
+  let rootCause = e
+  while (rootCause?.cause) {
+    rootCause = rootCause.cause as Error
+  }
+  return rootCause
+}

package/src/helpers.ts

@@ -1,8 +1,7 @@
-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'
+import { ValidationError } from './errors/errors.js'
+import { SDKError } from './errors/SDKError.js'
+import type { Route, LiFiStep } from '@lifi/types'
 
 export const checkPackageUpdates = async (
   packageName?: string,
@@ -10,12 +9,11 @@ export const checkPackageUpdates = async (
 ) => {
   try {
     const pkgName = packageName ?? name
-    const response = await request<{ version: string }>(
-      `https://registry.npmjs.org/${pkgName}/latest`,
-      { skipTrackingHeaders: true }
-    )
-    const latestVersion = response.version
+    const response = await fetch(`https://registry.npmjs.org/${pkgName}/latest`)
+    const reponseBody = await response.json()
+    const latestVersion = reponseBody.version
     const currentVersion = packageVersion ?? version
+
     if (latestVersion > currentVersion) {
       console.warn(
         // eslint-disable-next-line max-len
@@ -30,16 +28,22 @@ export const checkPackageUpdates = async (
 /**
  * Converts a quote to Route
  * @param step - Step returned from the quote endpoint.
+ * @param txHash
+ * @param chainId
  * @returns - The route to be executed.
- * @throws {ValidationError} Throws a ValidationError if the step has missing values.
+ * @throws {BaseError} 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.")
+    throw new SDKError(
+      new ValidationError("Missing 'fromAmountUSD' in step estimate.")
+    )
   }
 
   if (!step.estimate.toAmountUSD) {
-    throw new ValidationError("Missing 'toAmountUSD' in step estimate.")
+    throw new SDKError(
+      new ValidationError("Missing 'toAmountUSD' in step estimate.")
+    )
   }
 
   const route: Route = {
@@ -61,9 +65,12 @@ export const convertQuoteToRoute = (step: LiFiStep): 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}`
-  )
+  try {
+    const response = await fetch(
+      `https://api.tenderly.co/api/v1/public-contract/${chainId}/tx/${txHash}`
+    )
+    const reponseBody = await response.json()
 
-  return response
+    return reponseBody
+  } catch (_) {}
 }

package/src/index.ts

@@ -26,5 +26,5 @@ export * from './services/api.js'
 export * from './services/balance.js'
 export * from './services/getNameServiceAddress.js'
 export * from './types/index.js'
-export * from './utils/errors.js'
-export { LiFiError, type ErrorCode } from './utils/errors.js'
+export * from './errors/index.js'
+export { type ErrorCode } from './errors/index.js'