@lifi/sdk 3.0.2-beta.0 → 3.1.0-beta.0

package/src/core/EVM/parseEVMErrors.ts

@@ -0,0 +1,60 @@
+import { type LiFiStep, type Process } from '@lifi/types'
+import { TransactionError, UnknownError } from '../../errors/errors.js'
+import { SDKError } from '../../errors/SDKError.js'
+import { ErrorMessage, LiFiErrorCode } from '../../errors/constants.js'
+import { BaseError } from '../../utils/index.js'
+import { fetchTxErrorDetails } from '../../helpers.js'
+
+export const parseEVMErrors = 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 = await handleSpecificErrors(e, step, process)
+
+  return new SDKError(baseError, step, process)
+}
+
+const handleSpecificErrors = async (
+  e: any,
+  step?: LiFiStep,
+  process?: Process
+) => {
+  if (e.cause?.name === 'UserRejectedRequestError') {
+    return new TransactionError(LiFiErrorCode.SignatureRejected, e.message, e)
+  }
+
+  if (
+    step &&
+    process?.txHash &&
+    e.code === LiFiErrorCode.TransactionFailed &&
+    e.message === ErrorMessage.TransactionReverted
+  ) {
+    const response = await fetchTxErrorDetails(
+      process.txHash,
+      step.action.fromChainId
+    )
+
+    const errorMessage = response?.error_message
+
+    if (errorMessage?.toLowerCase().includes('out of gas')) {
+      return new TransactionError(
+        LiFiErrorCode.GasLimitError,
+        ErrorMessage.GasLimitLow,
+        e
+      )
+    }
+  }
+
+  if (e instanceof BaseError) {
+    return e
+  }
+
+  return new UnknownError(e.message || ErrorMessage.UnknownError, e)
+}

package/src/core/EVM/publicClient.ts

@@ -1,6 +1,6 @@
 import { ChainId } from '@lifi/types'
 import type { PublicClient } from 'viem'
-import { createPublicClient, fallback, http } from 'viem'
+import { createPublicClient, fallback, http, webSocket } from 'viem'
 import { mainnet, type Chain } from 'viem/chains'
 import { config } from '../../config.js'
 import { getRpcUrls } from '../rpc.js'
@@ -19,9 +19,11 @@ export const getPublicClient = async (
   if (!publicClients[chainId]) {
     const urls = await getRpcUrls(chainId)
     const fallbackTransports = urls.map((url) =>
-      http(url, {
-        batch: true,
-      })
+      url.startsWith('wss')
+        ? webSocket(url)
+        : http(url, {
+            batch: true,
+          })
     )
     const _chain = await config.getChainById(chainId)
     const chain: Chain = {
@@ -43,6 +45,9 @@ export const getPublicClient = async (
     publicClients[chainId] = createPublicClient({
       chain: chain,
       transport: fallback(fallbackTransports),
+      batch: {
+        multicall: true,
+      },
     })
   }
 

package/src/core/EVM/switchChain.ts

@@ -1,5 +1,6 @@
 import type { WalletClient } from 'viem'
-import { LiFiErrorCode, ProviderError } from '../../utils/errors.js'
+import { LiFiErrorCode } from '../../errors/constants.js'
+import { ProviderError } from '../../errors/errors.js'
 import type { StatusManager } from '../StatusManager.js'
 import type { LiFiStepExtended, SwitchChainHook } from '../types.js'
 

package/src/core/Solana/SolanaStepExecutor.ts

@@ -6,15 +6,13 @@ import {
   type SendOptions,
   type SignatureResult,
 } from '@solana/web3.js'
+import bs58 from 'bs58'
 import { config } from '../../config.js'
+import { LiFiErrorCode } from '../../errors/constants.js'
+import { TransactionError } from '../../errors/errors.js'
 import { getStepTransaction } from '../../services/api.js'
 import { base64ToUint8Array } from '../../utils/base64ToUint8Array.js'
-import {
-  LiFiErrorCode,
-  TransactionError,
-  getTransactionFailedMessage,
-  parseError,
-} from '../../utils/index.js'
+import { getTransactionFailedMessage } from '../../utils/index.js'
 import { BaseStepExecutor } from '../BaseStepExecutor.js'
 import { checkBalance } from '../checkBalance.js'
 import { getSubstatusMessage } from '../processMessages.js'
@@ -27,15 +25,12 @@ import type {
 import { sleep } from '../utils.js'
 import { waitForReceivingTransaction } from '../waitForReceivingTransaction.js'
 import { getSolanaConnection } from './connection.js'
+import { parseSolanaErrors } from './parseSolanaErrors.js'
 
 export interface SolanaStepExecutorOptions extends StepExecutorOptions {
   walletAdapter: SignerWalletAdapter
 }
 
-const TX_RETRY_INTERVAL = 1000
-// https://solana.com/docs/advanced/confirmation
-const TIMEOUT_PERIOD = 60_000
-
 export class SolanaStepExecutor extends BaseStepExecutor {
   private walletAdapter: SignerWalletAdapter
 
@@ -149,8 +144,23 @@ export class SolanaStepExecutor extends BaseStepExecutor {
 
         this.checkWalletAdapter(step)
 
-        const signedTx =
-          await this.walletAdapter.signTransaction(versionedTransaction)
+        const signedTxPromise =
+          this.walletAdapter.signTransaction(versionedTransaction)
+
+        // We give users 2 minutes to sign the transaction or it should be considered expired
+        const signedTx = await Promise.race([
+          signedTxPromise,
+          // https://solana.com/docs/advanced/confirmation#transaction-expiration
+          // Use 2 minutes to account for fluctuations
+          sleep(120_000),
+        ])
+
+        if (!signedTx) {
+          throw new TransactionError(
+            LiFiErrorCode.TransactionExpired,
+            'Transaction has expired: blockhash is no longer recent enough.'
+          )
+        }
 
         process = this.statusManager.updateProcess(
           step,
@@ -158,21 +168,31 @@ export class SolanaStepExecutor extends BaseStepExecutor {
           'PENDING'
         )
 
-        const rawTransactionOptions: SendOptions = {
-          // Skipping preflight i.e. tx simulation by RPC as we simulated the tx above
-          skipPreflight: true,
-          // Setting max retries to 0 as we are handling retries manually
-          // Set this manually so that the default is skipped
-          maxRetries: 0,
-          // https://solana.com/docs/advanced/confirmation#use-an-appropriate-preflight-commitment-level
-          preflightCommitment: 'confirmed',
-          // minContextSlot: blockhashResult.context.slot,
+        const simulationResult = await connection.simulateTransaction(
+          signedTx,
+          {
+            commitment: 'processed',
+            replaceRecentBlockhash: true,
+          }
+        )
+
+        if (simulationResult.value.err) {
+          throw new TransactionError(
+            LiFiErrorCode.TransactionSimulationFailed,
+            'Transaction simulation failed'
+          )
         }
 
-        const txSignature = await connection.sendRawTransaction(
-          signedTx.serialize(),
-          rawTransactionOptions
-        )
+        // Create transaction hash (signature)
+        const txSignature = bs58.encode(signedTx.signatures[0])
+
+        // A known weirdness - MAX_RECENT_BLOCKHASHES is 300
+        // https://github.com/solana-labs/solana/blob/master/sdk/program/src/clock.rs#L123
+        // but MAX_PROCESSING_AGE is 150
+        // https://github.com/solana-labs/solana/blob/master/sdk/program/src/clock.rs#L129
+        // the blockhash queue in the bank tells you 300 + current slot, but it won't be accepted 150 blocks later.
+        // https://solana.com/docs/advanced/confirmation#transaction-expiration
+        const lastValidBlockHeight = blockhashResult.lastValidBlockHeight - 150
 
         // In the following section, we wait and constantly check for the transaction to be confirmed
         // and resend the transaction if it is not confirmed within a certain time interval
@@ -183,7 +203,7 @@ export class SolanaStepExecutor extends BaseStepExecutor {
             {
               signature: txSignature,
               blockhash: blockhashResult.blockhash,
-              lastValidBlockHeight: blockhashResult.lastValidBlockHeight,
+              lastValidBlockHeight: lastValidBlockHeight,
               abortSignal: abortController.signal,
             },
             'confirmed'
@@ -191,20 +211,34 @@ export class SolanaStepExecutor extends BaseStepExecutor {
           .then((result) => result.value)
 
         let confirmedTx: SignatureResult | null = null
-        const startTime = Date.now()
+        let blockHeight = await connection.getBlockHeight()
+
+        const rawTransactionOptions: SendOptions = {
+          // We can skip preflight check after the first transaction has been sent
+          // https://solana.com/docs/advanced/retry#the-cost-of-skipping-preflight
+          skipPreflight: true,
+          // Setting max retries to 0 as we are handling retries manually
+          maxRetries: 0,
+          // https://solana.com/docs/advanced/confirmation#use-an-appropriate-preflight-commitment-level
+          preflightCommitment: 'confirmed',
+        }
+
+        const signedTxSerialized = signedTx.serialize()
 
-        while (!confirmedTx && Date.now() - startTime <= TIMEOUT_PERIOD) {
+        // https://solana.com/docs/advanced/retry#customizing-rebroadcast-logic
+        while (!confirmedTx && blockHeight < lastValidBlockHeight) {
           await connection.sendRawTransaction(
-            signedTx.serialize(),
+            signedTxSerialized,
             rawTransactionOptions
           )
           confirmedTx = await Promise.race([
             confirmTransactionPromise,
-            sleep(TX_RETRY_INTERVAL),
+            sleep(1000),
           ])
           if (confirmedTx) {
             break
           }
+          blockHeight = await connection.getBlockHeight()
         }
 
         // Stop waiting for tx confirmation
@@ -233,7 +267,7 @@ export class SolanaStepExecutor extends BaseStepExecutor {
         if (!confirmedTx) {
           throw new TransactionError(
             LiFiErrorCode.TransactionExpired,
-            'Failed to land the transaction'
+            'Transaction has expired: The block height has exceeded the maximum allowed limit.'
           )
         }
 
@@ -252,15 +286,14 @@ export class SolanaStepExecutor extends BaseStepExecutor {
           process = this.statusManager.updateProcess(step, process.type, 'DONE')
         }
       } catch (e: any) {
-        const error = await parseError(e, step, process)
+        const error = await parseSolanaErrors(e, step, process)
         process = this.statusManager.updateProcess(
           step,
           process.type,
           'FAILED',
           {
             error: {
-              message: error.message,
-              htmlMessage: error.htmlMessage,
+              message: error.cause.message,
               code: error.code,
             },
           }

package/src/core/Solana/connection.ts

@@ -5,9 +5,8 @@ import { getRpcUrl } from '../rpc.js'
 let connection: Connection | undefined = undefined
 
 /**
- * getSolanaConnection is just a thin wrapper around getting the
- * connection (rpc provider) for Solana
- * @returns - Solana rpc connection
+ * getSolanaConnection is just a thin wrapper around getting the connection (RPC provider) for Solana
+ * @returns - Solana RPC connection
  */
 export const getSolanaConnection = async (): Promise<Connection> => {
   if (!connection) {

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/checkBalance.ts

@@ -1,7 +1,7 @@
 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 (
@@ -40,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/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/waitForReceivingTransaction.ts

@@ -5,7 +5,7 @@ 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 './processMessages.js'

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