@lifi/sdk 3.13.5 → 4.0.0-alpha.1

package/src/errors/utils/baseErrorRootCause.unit.spec.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest'
+import { BaseError } from '../baseError.js'
+import { ErrorName, LiFiErrorCode } from '../constants.js'
+import { HTTPError } from '../httpError.js'
+import { SDKError } from '../SDKError.js'
+import {
+  getRootCauseBaseError,
+  getRootCauseBaseErrorMessage,
+} from './baseErrorRootCause.js'
+
+const getErrorChain = () => {
+  const NonLiFiErrorChain = new Error('non lifi error')
+  NonLiFiErrorChain.cause = new Error('root cause')
+  return new SDKError(
+    new BaseError(
+      ErrorName.ValidationError,
+      LiFiErrorCode.ValidationError,
+      'something happened',
+      NonLiFiErrorChain
+    )
+  )
+}
+
+describe('getRootCauseBaseError', () => {
+  it('should return the top level error when there is no root cause', () => {
+    const error = new Error('top level')
+
+    expect(getRootCauseBaseError(error).message).toEqual('top level')
+  })
+
+  it('should return the lowest BaseError in the cause chain', () => {
+    const errorChain = getErrorChain()
+
+    expect(getRootCauseBaseError(errorChain).message).toEqual(
+      'something happened'
+    )
+  })
+})
+
+describe('getRootCauseBaseErrorMessage', () => {
+  describe('when root cause is HTTP Error', () => {
+    it('should return the HTTP response message if present', async () => {
+      const mockResponse = {
+        status: 400,
+        statusText: 'Bad Request',
+        json: () =>
+          Promise.resolve({ message: 'something went wrong on the server' }),
+      } as Response
+
+      const httpError = new HTTPError(mockResponse, 'http://some.where', {})
+
+      await httpError.buildAdditionalDetails()
+
+      const errorChain = new SDKError(httpError)
+
+      expect(getRootCauseBaseErrorMessage(errorChain)).toEqual(
+        'something went wrong on the server'
+      )
+    })
+
+    it('should return the HTTP error message if response message not present', async () => {
+      const mockResponse = {
+        status: 400,
+        statusText: 'Bad Request',
+        json: () => Promise.resolve({}),
+      } as Response
+
+      const httpError = new HTTPError(mockResponse, 'http://some.where', {})
+
+      await httpError.buildAdditionalDetails()
+
+      const errorChain = new SDKError(httpError)
+
+      expect(getRootCauseBaseErrorMessage(errorChain)).toEqual(
+        '[ValidationError] Request failed with status code 400 Bad Request'
+      )
+    })
+  })
+
+  describe('when root cause is base Error', () => {
+    it('should return the BaseError message', () => {
+      const errorChain = getErrorChain()
+
+      expect(getRootCauseBaseErrorMessage(errorChain)).toEqual(
+        'something happened'
+      )
+    })
+  })
+})

package/src/errors/utils/rootCause.unit.spec.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest'
+import { BaseError } from '../baseError.js'
+import { ErrorName, LiFiErrorCode } from '../constants.js'
+import { SDKError } from '../SDKError.js'
+import { getRootCause } from './rootCause.js'
+
+const getErrorChain = () => {
+  const NonLiFiErrorChain = new Error('non lifi error')
+  NonLiFiErrorChain.cause = new Error('root cause')
+  return new SDKError(
+    new BaseError(
+      ErrorName.ValidationError,
+      LiFiErrorCode.ValidationError,
+      'something happened',
+      NonLiFiErrorChain
+    )
+  )
+}
+
+describe('getRootCause', () => {
+  it('should return the top level error when there is no root cause', () => {
+    const error = new Error('top level')
+
+    expect(getRootCause(error)!.message).toEqual('top level')
+  })
+
+  it('should return the root cause', () => {
+    const errorChain = getErrorChain()
+
+    expect(getRootCause(errorChain)!.message).toEqual('root cause')
+  })
+
+  it('should return undefined when passed undefined', () => {
+    expect(getRootCause(undefined)).toBeUndefined()
+  })
+})

package/src/index.ts

@@ -1,35 +1,32 @@
 // biome-ignore lint/performance/noBarrelFile: module entrypoint
 // biome-ignore lint/performance/noReExportAll: types
 export * from '@lifi/types'
-export { config } from './config.js'
-export { checkPermitSupport } from './core/EVM/checkPermitSupport.js'
-export { EVM } from './core/EVM/EVM.js'
-export {
-  getTokenAllowance,
-  getTokenAllowanceMulticall,
-} from './core/EVM/getAllowance.js'
-export { isBatchingSupported } from './core/EVM/isBatchingSupported.js'
-export { getNativePermit } from './core/EVM/permits/getNativePermit.js'
-export {
-  revokeTokenApproval,
-  setAllowance,
-  setTokenAllowance,
-} from './core/EVM/setAllowance.js'
-export {
-  isGaslessStep,
-  isRelayerStep,
-} from './core/EVM/typeguards.js'
-export type {
-  EVMProvider,
-  EVMProviderOptions,
-  WalletCallReceipt,
-} from './core/EVM/types.js'
-export { isEVM } from './core/EVM/types.js'
-export {
-  convertExtendedChain,
-  isDelegationDesignatorCode,
-  isExtendedChain,
-} from './core/EVM/utils.js'
+export type { Client } from 'viem'
+export { formatUnits, isHex, parseUnits } from 'viem/utils'
+export { getChains, getChainsFromConfig } from './actions/getChains.js'
+export { getConnections } from './actions/getConnections.js'
+export { getContractCallsQuote } from './actions/getContractCallsQuote.js'
+export { getGasRecommendation } from './actions/getGasRecommendation.js'
+export { getNameServiceAddress } from './actions/getNameServiceAddress.js'
+export { getQuote } from './actions/getQuote.js'
+export { getRelayedTransactionStatus } from './actions/getRelayedTransactionStatus.js'
+export { getRelayerQuote } from './actions/getRelayerQuote.js'
+export { getRoutes } from './actions/getRoutes.js'
+export { getStatus } from './actions/getStatus.js'
+export { getStepTransaction } from './actions/getStepTransaction.js'
+export { getToken } from './actions/getToken.js'
+export { getTokenBalance } from './actions/getTokenBalance.js'
+export { getTokenBalances } from './actions/getTokenBalances.js'
+export { getTokenBalancesByChain } from './actions/getTokenBalancesByChain.js'
+export { getTokens } from './actions/getTokens.js'
+export { getTools } from './actions/getTools.js'
+export { getTransactionHistory } from './actions/getTransactionHistory.js'
+export { getWalletBalances } from './actions/getWalletBalances.js'
+export { actions } from './actions/index.js'
+export { relayTransaction } from './actions/relayTransaction.js'
+export { createClient } from './client/createClient.js'
+export { BaseStepExecutor } from './core/BaseStepExecutor.js'
+export { checkBalance } from './core/checkBalance.js'
 export {
   executeRoute,
   getActiveRoute,
@@ -38,21 +35,24 @@ export {
   stopRouteExecution,
   updateRouteExecution,
 } from './core/execution.js'
-export { isSVMAddress } from './core/Solana/isSVMAddress.js'
-export {
-  KeypairWalletAdapter,
-  KeypairWalletName,
-} from './core/Solana/KeypairWalletAdapter.js'
-export { Solana } from './core/Solana/Solana.js'
-export type {
-  SolanaProvider,
-  SolanaProviderOptions,
-} from './core/Solana/types.js'
-export { isSolana } from './core/Solana/types.js'
 export { StatusManager } from './core/StatusManager.js'
-export { Sui } from './core/Sui/Sui.js'
-export type { SuiProvider, SuiProviderOptions } from './core/Sui/types.js'
-export { isSui } from './core/Sui/types.js'
+export { stepComparison } from './core/stepComparison.js'
+export { isTokenMessageSigningAllowed } from './core/utils.js'
+export { waitForDestinationChainTransaction } from './core/waitForDestinationChainTransaction.js'
+export { BaseError } from './errors/baseError.js'
+export type { ErrorCode } from './errors/constants.js'
+export { ErrorMessage, ErrorName, LiFiErrorCode } from './errors/constants.js'
+export {
+  BalanceError,
+  ProviderError,
+  RPCError,
+  ServerError,
+  TransactionError,
+  UnknownError,
+  ValidationError,
+} from './errors/errors.js'
+export { HTTPError } from './errors/httpError.js'
+export { SDKError } from './errors/SDKError.js'
 export type {
   AcceptExchangeRateUpdateHook,
   AcceptSlippageUpdateHook,
@@ -70,66 +70,24 @@ export type {
   RouteExecutionDataDictionary,
   RouteExecutionDictionary,
   RouteExtended,
+  RPCUrls,
+  SDKBaseConfig,
+  SDKClient,
+  SDKConfig,
   SDKProvider,
   StepExecutor,
   StepExecutorOptions,
   StepExtended,
   SwitchChainHook,
+  TransactionMethodType,
   TransactionParameters,
   TransactionRequestParameters,
   TransactionRequestUpdateHook,
   UpdateRouteHook,
-} from './core/types.js'
-export type { UTXOProvider, UTXOProviderOptions } from './core/UTXO/types.js'
-export { isUTXO } from './core/UTXO/types.js'
-export { UTXO } from './core/UTXO/UTXO.js'
-export { isTokenMessageSigningAllowed } from './core/utils.js'
-export { createConfig } from './createConfig.js'
-export { BaseError } from './errors/baseError.js'
-export type { ErrorCode } from './errors/constants.js'
-export { ErrorMessage, ErrorName, LiFiErrorCode } from './errors/constants.js'
-export {
-  BalanceError,
-  ProviderError,
-  RPCError,
-  ServerError,
-  TransactionError,
-  UnknownError,
-  ValidationError,
-} from './errors/errors.js'
-export { HTTPError } from './errors/httpError.js'
-export { SDKError } from './errors/SDKError.js'
-export {
-  getChains,
-  getConnections,
-  getContractCallsQuote,
-  getGasRecommendation,
-  getQuote,
-  getRelayedTransactionStatus,
-  getRelayerQuote,
-  getRoutes,
-  getStatus,
-  getStepTransaction,
-  getToken,
-  getTokens,
-  getTools,
-  getTransactionHistory,
-  relayTransaction,
-} from './services/api.js'
-export {
-  getTokenBalance,
-  getTokenBalances,
-  getTokenBalancesByChain,
-  getWalletBalances,
-} from './services/balance.js'
-export { getNameServiceAddress } from './services/getNameServiceAddress.js'
-export type {
-  GetStatusRequestExtended,
-  QuoteRequest,
-  QuoteRequestFromAmount,
-  QuoteRequestToAmount,
-} from './services/types.js'
-export type { RPCUrls, SDKBaseConfig, SDKConfig } from './types/internal.js'
+} from './types/core.js'
 export { checkPackageUpdates } from './utils/checkPackageUpdates.js'
 export { convertQuoteToRoute } from './utils/convertQuoteToRoute.js'
 export { fetchTxErrorDetails } from './utils/fetchTxErrorDetails.js'
+export { sleep } from './utils/sleep.js'
+export { waitForResult } from './utils/waitForResult.js'
+export { withDedupe } from './utils/withDedupe.js'

package/src/types/core.ts

@@ -0,0 +1,228 @@
+import type {
+  ChainId,
+  ChainType,
+  CoinKey,
+  ExtendedChain,
+  FeeCost,
+  GasCost,
+  LiFiStep,
+  Route,
+  RouteOptions,
+  Step,
+  Substatus,
+  Token,
+  TokenAmount,
+} from '@lifi/types'
+import type { Client } from 'viem'
+
+export interface SDKBaseConfig {
+  apiKey?: string
+  apiUrl: string
+  integrator: string
+  userId?: string
+  routeOptions?: RouteOptions
+  executionOptions?: ExecutionOptions
+  rpcUrls: RPCUrls
+  disableVersionCheck?: boolean
+  widgetVersion?: string
+  debug: boolean
+}
+
+export interface SDKConfig extends Partial<Omit<SDKBaseConfig, 'integrator'>> {
+  integrator: string
+}
+
+export type RPCUrls = Partial<Record<ChainId, string[]>>
+
+export interface SDKProvider {
+  readonly type: ChainType
+  isAddress(address: string): boolean
+  resolveAddress(
+    name: string,
+    client: SDKClient,
+    chainId?: ChainId,
+    token?: CoinKey
+  ): Promise<string | undefined>
+  getStepExecutor(options: StepExecutorOptions): Promise<StepExecutor>
+  getBalance(
+    client: SDKClient,
+    walletAddress: string,
+    tokens: Token[]
+  ): Promise<TokenAmount[]>
+}
+
+export interface SDKClient {
+  config: SDKBaseConfig
+  providers: SDKProvider[]
+  getProvider(type: ChainType): SDKProvider | undefined
+  setProviders(providers: SDKProvider[]): void
+  getChains(): Promise<ExtendedChain[]>
+  getChainById(chainId: ChainId): Promise<ExtendedChain>
+  getRpcUrls(): Promise<RPCUrls>
+  getRpcUrlsByChainId(chainId: ChainId): Promise<string[]>
+}
+
+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(
+    client: SDKClient,
+    step: LiFiStepExtended
+  ): Promise<LiFiStepExtended>
+}
+
+export interface RouteExecutionData {
+  route: Route
+  executors: StepExecutor[]
+  executionOptions?: ExecutionOptions
+}
+
+export type RouteExecutionDataDictionary = Partial<
+  Record<string, RouteExecutionData>
+>
+
+export interface RouteExtended extends Omit<Route, 'steps'> {
+  steps: LiFiStepExtended[]
+}
+
+export interface LiFiStepExtended extends LiFiStep {
+  execution?: Execution
+}
+
+export type StepExtended = Step & {
+  execution?: Execution
+}
+
+export type TransactionParameters = {
+  chainId?: number
+  to?: string
+  from?: string
+  nonce?: number
+  data?: string
+  value?: bigint
+  gas?: bigint
+  gasPrice?: bigint
+  maxFeePerGas?: bigint
+  maxPriorityFeePerGas?: bigint
+}
+
+export type RouteExecutionDictionary = Partial<Record<string, Promise<Route>>>
+
+export type UpdateRouteHook = (updatedRoute: RouteExtended) => void
+
+export interface TransactionRequestParameters extends TransactionParameters {
+  requestType: 'approve' | 'transaction'
+}
+
+export type TransactionRequestUpdateHook = (
+  updatedTxRequest: TransactionRequestParameters
+) => Promise<TransactionParameters>
+
+export type SwitchChainHook = (chainId: number) => Promise<Client | 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
+  disableMessageSigning?: boolean
+  /**
+   * @deprecated
+   */
+  infiniteApproval?: boolean
+}
+
+export type ExecutionStatus = 'ACTION_REQUIRED' | 'PENDING' | 'FAILED' | 'DONE'
+
+export type ProcessStatus =
+  | 'STARTED'
+  | 'ACTION_REQUIRED'
+  | 'MESSAGE_REQUIRED'
+  | 'RESET_REQUIRED'
+  | 'PENDING'
+  | 'FAILED'
+  | 'DONE'
+  | 'CANCELLED'
+
+export type ProcessType =
+  | 'TOKEN_ALLOWANCE'
+  | 'PERMIT'
+  | 'SWAP'
+  | 'CROSS_CHAIN'
+  | 'RECEIVING_CHAIN'
+
+export type Process = {
+  type: ProcessType
+  status: ProcessStatus
+  substatus?: Substatus
+  chainId?: number
+  txHash?: string
+  taskId?: string
+  txLink?: string
+  txType?: TransactionMethodType
+  actionRequiredAt?: number
+  doneAt?: number
+  failedAt?: number
+  pendingAt?: number
+  startedAt: number
+  message?: string
+  error?: {
+    code: string | number
+    message: string
+    htmlMessage?: string
+  }
+
+  // additional information
+  [key: string]: any
+}
+
+export interface Execution {
+  startedAt: number
+  doneAt?: number
+  status: ExecutionStatus
+  process: Array<Process>
+  fromAmount?: string
+  toAmount?: string
+  toToken?: Token
+  feeCosts?: FeeCost[]
+  gasCosts?: GasCost[]
+  internalTxLink?: string
+  externalTxLink?: string
+}
+
+export type TransactionMethodType = 'standard' | 'relayed' | 'batched'

package/src/utils/checkPackageUpdates.unit.spec.ts

@@ -0,0 +1,71 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  type Mock,
+  vi,
+} from 'vitest'
+import { checkPackageUpdates } from './checkPackageUpdates.js'
+
+const latestVersion = '2.5.6'
+
+describe('checkPackageUpdates', () => {
+  beforeEach(() => {
+    vi.spyOn(global, 'fetch').mockResolvedValue({
+      json: () => Promise.resolve({ version: latestVersion }),
+    } as Response)
+
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    vi.resetAllMocks()
+  })
+
+  it('should be able to check the version number against npm', async () => {
+    const packageName = '@lifi/sdk'
+    const currentVersion = '0.0.0'
+
+    await checkPackageUpdates(packageName, currentVersion)
+
+    expect(global.fetch as Mock).toBeCalledWith(
+      `https://registry.npmjs.org/${packageName}/latest`
+    )
+
+    expect(console.warn).toBeCalledWith(
+      `${packageName}: new package version is available. Please update as soon as possible to enjoy the newest features. Current version: ${currentVersion}. Latest version: ${latestVersion}.`
+    )
+  })
+
+  it('should not report if version matchs the latest on npm', async () => {
+    const packageName = '@lifi/sdk'
+    const currentVersion = '2.5.6'
+
+    await checkPackageUpdates(packageName, currentVersion)
+
+    expect(global.fetch as Mock).toBeCalledWith(
+      `https://registry.npmjs.org/${packageName}/latest`
+    )
+
+    expect(console.warn).not.toBeCalled()
+  })
+
+  it('should fail sliently if it encounters a problem', async () => {
+    vi.spyOn(global, 'fetch').mockRejectedValue({
+      json: () => Promise.resolve({ version: latestVersion }),
+    } as Response)
+
+    const packageName = '@lifi/sdk'
+    const currentVersion = '0.0.0'
+
+    await checkPackageUpdates(packageName, currentVersion)
+
+    expect(global.fetch as Mock).toBeCalledWith(
+      `https://registry.npmjs.org/${packageName}/latest`
+    )
+
+    expect(console.warn).not.toBeCalled()
+  })
+})

package/src/utils/convertQuoteToRoute.unit.spec.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest'
+import { SDKError } from '../errors/SDKError.js'
+import { convertQuoteToRoute } from './convertQuoteToRoute.js'
+
+describe('convertQuoteToRoute', () => {
+  const validQuote = {
+    id: 'test-quote',
+    type: 'swap',
+    tool: 'test-tool',
+    action: {
+      fromToken: { address: '0x111', decimals: 18, chainId: 1 },
+      fromAmount: '1000000000000000000',
+      fromAddress: '0xaaa',
+      toToken: { address: '0x222', decimals: 18, chainId: 1 },
+      toAddress: '0xbbb',
+    },
+    estimate: {
+      fromAmount: '1000000000000000000',
+      toAmount: '2000000000000000000',
+      toAmountMin: '1900000000000000000',
+      fromAmountUSD: '100',
+      toAmountUSD: '200',
+      approvalAddress: '0x333',
+    },
+  }
+
+  it('should convert valid quote to route', () => {
+    const route = convertQuoteToRoute(validQuote as any)
+
+    expect(route.id).toBe('test-quote')
+    expect(route.fromChainId).toBe(1)
+    expect(route.toChainId).toBe(1)
+    expect(route.fromAmount).toBe('1000000000000000000')
+    expect(route.toAmount).toBe('2000000000000000000')
+    expect(route.fromAmountUSD).toBe('100')
+    expect(route.toAmountUSD).toBe('200')
+  })
+
+  it('should throw error when fromAmountUSD is missing', () => {
+    const invalidQuote = {
+      ...validQuote,
+      estimate: { ...validQuote.estimate, fromAmountUSD: undefined },
+    }
+
+    expect(() => convertQuoteToRoute(invalidQuote as any)).toThrow(SDKError)
+  })
+
+  it('should throw error when toAmountUSD is missing', () => {
+    const invalidQuote = {
+      ...validQuote,
+      estimate: { ...validQuote.estimate, toAmountUSD: undefined },
+    }
+
+    expect(() => convertQuoteToRoute(invalidQuote as any)).toThrow(SDKError)
+  })
+})

package/src/utils/fetchTxErrorDetails.unit.spec.ts

@@ -0,0 +1,42 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { fetchTxErrorDetails } from './fetchTxErrorDetails.js'
+
+// Mock fetch
+global.fetch = vi.fn()
+
+describe('fetchTxErrorDetails', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should return response body on success', async () => {
+    const mockResponse = { error_message: 'Out of gas' }
+    ;(global.fetch as any).mockResolvedValueOnce({
+      json: vi.fn().mockResolvedValueOnce(mockResponse),
+    })
+
+    const result = await fetchTxErrorDetails('0x123', 1)
+
+    expect(result).toEqual(mockResponse)
+  })
+
+  it('should return undefined on error', async () => {
+    ;(global.fetch as any).mockRejectedValueOnce(new Error('Network error'))
+
+    const result = await fetchTxErrorDetails('0x123', 1)
+
+    expect(result).toBeUndefined()
+  })
+
+  it('should call correct tenderly URL', async () => {
+    ;(global.fetch as any).mockResolvedValueOnce({
+      json: vi.fn().mockResolvedValueOnce({}),
+    })
+
+    await fetchTxErrorDetails('0x123abc', 1)
+
+    expect(global.fetch).toHaveBeenCalledWith(
+      'https://api.tenderly.co/api/v1/public-contract/1/tx/0x123abc'
+    )
+  })
+})