@lifi/sdk 3.13.5 → 4.0.0-alpha.2

package/src/actions/getGasRecommendation.ts

@@ -0,0 +1,47 @@
+import type {
+  GasRecommendationRequest,
+  GasRecommendationResponse,
+  RequestOptions,
+} from '@lifi/types'
+import { ValidationError } from '../errors/errors.js'
+import { SDKError } from '../errors/SDKError.js'
+import type { SDKClient } from '../types/core.js'
+import { request } from '../utils/request.js'
+
+/**
+ * Get gas recommendation for a certain chain
+ * @param client - The SDK client
+ * @param params - Configuration of the requested gas recommendation.
+ * @param options - Request options
+ * @throws {LiFiError} Throws a LiFiError if request fails.
+ * @returns Gas recommendation response.
+ */
+export const getGasRecommendation = async (
+  client: SDKClient,
+  params: GasRecommendationRequest,
+  options?: RequestOptions
+): Promise<GasRecommendationResponse> => {
+  if (!params.chainId) {
+    throw new SDKError(
+      new ValidationError('Required parameter "chainId" is missing.')
+    )
+  }
+
+  const url = new URL(
+    `${client.config.apiUrl}/gas/suggestion/${params.chainId}`
+  )
+  if (params.fromChain) {
+    url.searchParams.append('fromChain', params.fromChain as unknown as string)
+  }
+  if (params.fromToken) {
+    url.searchParams.append('fromToken', params.fromToken)
+  }
+
+  return await request<GasRecommendationResponse>(
+    client.config,
+    url.toString(),
+    {
+      signal: options?.signal,
+    }
+  )
+}

package/src/actions/getNameServiceAddress.ts

@@ -0,0 +1,42 @@
+import type { ChainType } from '@lifi/types'
+import type { SDKClient } from '../types/core.js'
+
+/**
+ * Get the address of a name service
+ * @param client - The SDK client
+ * @param name - The name to resolve
+ * @param chainType - The chain type to resolve the name on
+ * @returns The address of the name service
+ */
+export const getNameServiceAddress = async (
+  client: SDKClient,
+  name: string,
+  chainType?: ChainType
+): Promise<string | undefined> => {
+  try {
+    let providers = []
+    if (chainType) {
+      providers = client.providers.filter(
+        (provider) => provider.type === chainType
+      )
+    } else {
+      providers = client.providers
+    }
+    const resolvers = providers.map((provider) => provider.resolveAddress)
+    if (!resolvers.length) {
+      return
+    }
+    const result = await Promise.any(
+      resolvers.map(async (resolve) => {
+        const address = await resolve(name, client)
+        if (!address) {
+          throw undefined
+        }
+        return address
+      })
+    )
+    return result
+  } catch (_) {
+    return
+  }
+}

package/src/actions/getQuote.ts

@@ -0,0 +1,102 @@
+import type { LiFiStep, RequestOptions } from '@lifi/types'
+import { ValidationError } from '../errors/errors.js'
+import { SDKError } from '../errors/SDKError.js'
+import type {
+  QuoteRequest,
+  QuoteRequestFromAmount,
+  QuoteRequestToAmount,
+} from '../types/actions.js'
+import type { SDKClient } from '../types/core.js'
+import { request } from '../utils/request.js'
+
+/**
+ * Get a quote for a token transfer
+ * @param client - The SDK client
+ * @param params - The configuration of the requested quote
+ * @param options - Request options
+ * @throws {LiFiError} - Throws a LiFiError if request fails
+ * @returns Quote for a token transfer
+ */
+export async function getQuote(
+  client: SDKClient,
+  params: QuoteRequestFromAmount,
+  options?: RequestOptions
+): Promise<LiFiStep>
+export async function getQuote(
+  client: SDKClient,
+  params: QuoteRequestToAmount,
+  options?: RequestOptions
+): Promise<LiFiStep>
+export async function getQuote(
+  client: SDKClient,
+  params: QuoteRequest,
+  options?: RequestOptions
+): Promise<LiFiStep> {
+  const requiredParameters: Array<keyof QuoteRequest> = [
+    'fromChain',
+    'fromToken',
+    'fromAddress',
+    'toChain',
+    'toToken',
+  ]
+
+  for (const requiredParameter of requiredParameters) {
+    if (!params[requiredParameter]) {
+      throw new SDKError(
+        new ValidationError(
+          `Required parameter "${requiredParameter}" is missing.`
+        )
+      )
+    }
+  }
+
+  const isFromAmountRequest =
+    'fromAmount' in params && params.fromAmount !== undefined
+  const isToAmountRequest =
+    'toAmount' in params && params.toAmount !== undefined
+
+  if (!isFromAmountRequest && !isToAmountRequest) {
+    throw new SDKError(
+      new ValidationError(
+        'Required parameter "fromAmount" or "toAmount" is missing.'
+      )
+    )
+  }
+
+  if (isFromAmountRequest && isToAmountRequest) {
+    throw new SDKError(
+      new ValidationError(
+        'Cannot provide both "fromAmount" and "toAmount" parameters.'
+      )
+    )
+  }
+
+  // apply defaults
+  params.integrator ??= client.config.integrator
+  params.order ??= client.config.routeOptions?.order
+  params.slippage ??= client.config.routeOptions?.slippage
+  params.referrer ??= client.config.routeOptions?.referrer
+  params.fee ??= client.config.routeOptions?.fee
+  params.allowBridges ??= client.config.routeOptions?.bridges?.allow
+  params.denyBridges ??= client.config.routeOptions?.bridges?.deny
+  params.preferBridges ??= client.config.routeOptions?.bridges?.prefer
+  params.allowExchanges ??= client.config.routeOptions?.exchanges?.allow
+  params.denyExchanges ??= client.config.routeOptions?.exchanges?.deny
+  params.preferExchanges ??= client.config.routeOptions?.exchanges?.prefer
+
+  for (const key of Object.keys(params)) {
+    if (!params[key as keyof QuoteRequest]) {
+      delete params[key as keyof QuoteRequest]
+    }
+  }
+
+  return await request<LiFiStep>(
+    client.config,
+    `${client.config.apiUrl}/${isFromAmountRequest ? 'quote' : 'quote/toAmount'}?${new URLSearchParams(
+      params as unknown as Record<string, string>
+    )}`,
+    {
+      signal: options?.signal,
+    }
+  )
+}

package/src/actions/getRelayedTransactionStatus.ts

@@ -0,0 +1,67 @@
+import type {
+  RelayStatusRequest,
+  RelayStatusResponse,
+  RelayStatusResponseData,
+  RequestOptions,
+} from '@lifi/types'
+import { BaseError } from '../errors/baseError.js'
+import { ErrorName } from '../errors/constants.js'
+import { ValidationError } from '../errors/errors.js'
+import { SDKError } from '../errors/SDKError.js'
+import type { SDKClient } from '../types/core.js'
+import { decodeTaskId } from '../utils/decode.js'
+import { request } from '../utils/request.js'
+import { getStatus } from './getStatus.js'
+
+/**
+ * Get the status of a relayed transaction
+ * @param client - The SDK client
+ * @param params - Parameters for the relay status request
+ * @param options - Request options
+ * @throws {LiFiError} - Throws a LiFiError if request fails
+ * @returns Status of the relayed transaction
+ */
+export const getRelayedTransactionStatus = async (
+  client: SDKClient,
+  params: RelayStatusRequest,
+  options?: RequestOptions
+): Promise<RelayStatusResponseData> => {
+  if (!params.taskId) {
+    throw new SDKError(
+      new ValidationError('Required parameter "taskId" is missing.')
+    )
+  }
+
+  const { taskId, ...otherParams } = params
+  const queryParams = new URLSearchParams(
+    otherParams as unknown as Record<string, string>
+  )
+
+  const decodedTaskId = decodeTaskId(taskId)
+  // Temporary solution during the transition between status endpoints
+  if (decodedTaskId.length === 3) {
+    return (await getStatus(
+      client,
+      params,
+      options
+    )) as unknown as RelayStatusResponseData
+  }
+
+  const result = await request<RelayStatusResponse>(
+    client.config,
+    `${client.config.apiUrl}/relayer/status/${taskId}?${queryParams}`,
+    {
+      signal: options?.signal,
+    }
+  )
+
+  if (result.status === 'error') {
+    throw new BaseError(
+      ErrorName.ServerError,
+      result.data.code,
+      result.data.message
+    )
+  }
+
+  return result.data
+}

package/src/actions/getRelayerQuote.ts

@@ -0,0 +1,83 @@
+import type {
+  LiFiStep,
+  RelayerQuoteResponse,
+  RequestOptions,
+} from '@lifi/types'
+import { BaseError } from '../errors/baseError.js'
+import { ErrorName } from '../errors/constants.js'
+import { ValidationError } from '../errors/errors.js'
+import { SDKError } from '../errors/SDKError.js'
+import type { QuoteRequest, QuoteRequestFromAmount } from '../types/actions.js'
+import type { SDKClient } from '../types/core.js'
+import { request } from '../utils/request.js'
+
+/**
+ * Get a relayer quote for a token transfer
+ * @param client - The SDK client
+ * @param params - The configuration of the requested quote
+ * @param options - Request options
+ * @throws {LiFiError} - Throws a LiFiError if request fails
+ * @returns Relayer quote for a token transfer
+ */
+export const getRelayerQuote = async (
+  client: SDKClient,
+  params: QuoteRequestFromAmount,
+  options?: RequestOptions
+): Promise<LiFiStep> => {
+  const requiredParameters: Array<keyof QuoteRequestFromAmount> = [
+    'fromChain',
+    'fromToken',
+    'fromAddress',
+    'fromAmount',
+    'toChain',
+    'toToken',
+  ]
+  for (const requiredParameter of requiredParameters) {
+    if (!params[requiredParameter]) {
+      throw new SDKError(
+        new ValidationError(
+          `Required parameter "${requiredParameter}" is missing.`
+        )
+      )
+    }
+  }
+
+  // apply defaults
+  params.integrator ??= client.config.integrator
+  params.order ??= client.config.routeOptions?.order
+  params.slippage ??= client.config.routeOptions?.slippage
+  params.referrer ??= client.config.routeOptions?.referrer
+  params.fee ??= client.config.routeOptions?.fee
+  params.allowBridges ??= client.config.routeOptions?.bridges?.allow
+  params.denyBridges ??= client.config.routeOptions?.bridges?.deny
+  params.preferBridges ??= client.config.routeOptions?.bridges?.prefer
+  params.allowExchanges ??= client.config.routeOptions?.exchanges?.allow
+  params.denyExchanges ??= client.config.routeOptions?.exchanges?.deny
+  params.preferExchanges ??= client.config.routeOptions?.exchanges?.prefer
+
+  for (const key of Object.keys(params)) {
+    if (!params[key as keyof QuoteRequest]) {
+      delete params[key as keyof QuoteRequest]
+    }
+  }
+
+  const result = await request<RelayerQuoteResponse>(
+    client.config,
+    `${client.config.apiUrl}/relayer/quote?${new URLSearchParams(
+      params as unknown as Record<string, string>
+    )}`,
+    {
+      signal: options?.signal,
+    }
+  )
+
+  if (result.status === 'error') {
+    throw new BaseError(
+      ErrorName.ServerError,
+      result.data.code,
+      result.data.message
+    )
+  }
+
+  return result.data
+}

package/src/actions/getRoutes.ts

@@ -0,0 +1,43 @@
+import type { RequestOptions, RoutesRequest, RoutesResponse } from '@lifi/types'
+import { ValidationError } from '../errors/errors.js'
+import { SDKError } from '../errors/SDKError.js'
+import type { SDKClient } from '../types/core.js'
+import { isRoutesRequest } from '../utils/isRoutesRequest.js'
+import { request } from '../utils/request.js'
+
+/**
+ * Get a set of routes for a request that describes a transfer of tokens.
+ * @param client - The SDK client.
+ * @param params - A description of the transfer.
+ * @param options - Request options
+ * @returns The resulting routes that can be used to realize the described transfer of tokens.
+ * @throws {LiFiError} Throws a LiFiError if request fails.
+ */
+export const getRoutes = async (
+  client: SDKClient,
+  params: RoutesRequest,
+  options?: RequestOptions
+): Promise<RoutesResponse> => {
+  if (!isRoutesRequest(params)) {
+    throw new SDKError(new ValidationError('Invalid routes request.'))
+  }
+  // apply defaults
+  params.options = {
+    integrator: client.config.integrator,
+    ...client.config.routeOptions,
+    ...params.options,
+  }
+
+  return await request<RoutesResponse>(
+    client.config,
+    `${client.config.apiUrl}/advanced/routes`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(params),
+      signal: options?.signal,
+    }
+  )
+}

package/src/actions/getStatus.ts

@@ -0,0 +1,41 @@
+import type { RequestOptions, StatusResponse } from '@lifi/types'
+import { ValidationError } from '../errors/errors.js'
+import { SDKError } from '../errors/SDKError.js'
+import type { GetStatusRequestExtended } from '../types/actions.js'
+import type { SDKClient } from '../types/core.js'
+import { request } from '../utils/request.js'
+
+/**
+ * Check the status of a transfer. For cross chain transfers, the "bridge" parameter is required.
+ * @param client - The SDK client
+ * @param params - Configuration of the requested status
+ * @param options - Request options.
+ * @throws {LiFiError} - Throws a LiFiError if request fails
+ * @returns Returns status response.
+ */
+export const getStatus = async (
+  client: SDKClient,
+  params: GetStatusRequestExtended,
+  options?: RequestOptions
+): Promise<StatusResponse> => {
+  if (
+    !('taskId' in params && params.taskId) &&
+    !('txHash' in params && params.txHash)
+  ) {
+    throw new SDKError(
+      new ValidationError(
+        'Either "taskId" or "txHash" must be provided and non-empty.'
+      )
+    )
+  }
+  const queryParams = new URLSearchParams(
+    params as unknown as Record<string, string>
+  )
+  return await request<StatusResponse>(
+    client.config,
+    `${client.config.apiUrl}/status?${queryParams}`,
+    {
+      signal: options?.signal,
+    }
+  )
+}

package/src/actions/getStepTransaction.ts

@@ -0,0 +1,36 @@
+import type { LiFiStep, RequestOptions, SignedLiFiStep } from '@lifi/types'
+import type { SDKClient } from '../types/core.js'
+import { isStep } from '../utils/isStep.js'
+import { request } from '../utils/request.js'
+
+/**
+ * Get the transaction data for a single step of a route
+ * @param client - The SDK client
+ * @param step - The step object.
+ * @param options - Request options
+ * @returns The step populated with the transaction data.
+ * @throws {LiFiError} Throws a LiFiError if request fails.
+ */
+export const getStepTransaction = async (
+  client: SDKClient,
+  step: LiFiStep | SignedLiFiStep,
+  options?: RequestOptions
+): Promise<LiFiStep> => {
+  if (!isStep(step)) {
+    // While the validation fails for some users we should not enforce it
+    console.warn('SDK Validation: Invalid Step', step)
+  }
+
+  return await request<LiFiStep>(
+    client.config,
+    `${client.config.apiUrl}/advanced/stepTransaction`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(step),
+      signal: options?.signal,
+    }
+  )
+}

package/src/actions/getToken.ts

@@ -0,0 +1,47 @@
+import type {
+  ChainId,
+  ChainKey,
+  RequestOptions,
+  TokenExtended,
+} from '@lifi/types'
+import { ValidationError } from '../errors/errors.js'
+import { SDKError } from '../errors/SDKError.js'
+import type { SDKClient } from '../types/core.js'
+import { request } from '../utils/request.js'
+
+/**
+ * Fetch information about a Token
+ * @param client - The SDK client
+ * @param chain - Id or key of the chain that contains the token
+ * @param token - Address or symbol of the token on the requested chain
+ * @param options - Request options
+ * @throws {LiFiError} - Throws a LiFiError if request fails
+ * @returns Token information
+ */
+export const getToken = async (
+  client: SDKClient,
+  chain: ChainKey | ChainId,
+  token: string,
+  options?: RequestOptions
+): Promise<TokenExtended> => {
+  if (!chain) {
+    throw new SDKError(
+      new ValidationError('Required parameter "chain" is missing.')
+    )
+  }
+  if (!token) {
+    throw new SDKError(
+      new ValidationError('Required parameter "token" is missing.')
+    )
+  }
+  return await request<TokenExtended>(
+    client.config,
+    `${client.config.apiUrl}/token?${new URLSearchParams({
+      chain,
+      token,
+    } as Record<string, string>)}`,
+    {
+      signal: options?.signal,
+    }
+  )
+}

package/src/actions/getTokenBalance.ts

@@ -0,0 +1,21 @@
+import type { Token, TokenAmount } from '@lifi/types'
+import type { SDKClient } from '../types/core.js'
+import { getTokenBalances } from './getTokenBalances.js'
+
+/**
+ * Returns the balances of a specific token a wallet holds across all aggregated chains.
+ * @param client - The SDK client.
+ * @param walletAddress - A wallet address.
+ * @param token - A Token object.
+ * @returns An object containing the token and the amounts on different chains.
+ * @throws {ValidationError} Throws a ValidationError if validation fails.
+ * @throws {Error} Throws an Error if the SDK Provider for the wallet address is not found.
+ */
+export const getTokenBalance = async (
+  client: SDKClient,
+  walletAddress: string,
+  token: Token
+): Promise<TokenAmount | null> => {
+  const tokenAmounts = await getTokenBalances(client, walletAddress, [token])
+  return tokenAmounts.length ? tokenAmounts[0] : null
+}

package/src/actions/getTokenBalances.ts

@@ -0,0 +1,47 @@
+import type {
+  Token,
+  TokenAmount,
+  TokenAmountExtended,
+  TokenExtended,
+} from '@lifi/types'
+import type { SDKClient } from '../types/core.js'
+import { getTokenBalancesByChain } from './getTokenBalancesByChain.js'
+
+/**
+ * Returns the balances for a list tokens a wallet holds across all aggregated chains.
+ * @param client - The SDK client.
+ * @param walletAddress - A wallet address.
+ * @param tokens - A list of Token (or TokenExtended) objects.
+ * @returns A list of objects containing the tokens and the amounts on different chains.
+ * @throws {ValidationError} Throws a ValidationError if validation fails.
+ * @throws {Error} Throws an Error if the SDK Provider for the wallet address is not found.
+ */
+export async function getTokenBalances(
+  client: SDKClient,
+  walletAddress: string,
+  tokens: Token[]
+): Promise<TokenAmount[]>
+export async function getTokenBalances(
+  client: SDKClient,
+  walletAddress: string,
+  tokens: TokenExtended[]
+): Promise<TokenAmountExtended[]> {
+  // split by chain
+  const tokensByChain = tokens.reduce(
+    (tokens, token) => {
+      if (!tokens[token.chainId]) {
+        tokens[token.chainId] = []
+      }
+      tokens[token.chainId].push(token)
+      return tokens
+    },
+    {} as { [chainId: number]: Token[] | TokenExtended[] }
+  )
+
+  const tokenAmountsByChain = await getTokenBalancesByChain(
+    client,
+    walletAddress,
+    tokensByChain
+  )
+  return Object.values(tokenAmountsByChain).flat()
+}

package/src/actions/getTokenBalancesByChain.ts

@@ -0,0 +1,76 @@
+import type {
+  Token,
+  TokenAmount,
+  TokenAmountExtended,
+  TokenExtended,
+} from '@lifi/types'
+import { ValidationError } from '../errors/errors.js'
+import type { SDKClient } from '../types/core.js'
+import { isToken } from '../utils/isToken.js'
+
+/**
+ * This method queries the balances of tokens for a specific list of chains for a given wallet.
+ * @param client - The SDK client.
+ * @param walletAddress - A wallet address.
+ * @param tokensByChain - A list of token objects organized by chain ids.
+ * @returns A list of objects containing the tokens and the amounts on different chains organized by the chosen chains.
+ * @throws {ValidationError} Throws a ValidationError if validation fails.
+ * @throws {Error} Throws an Error if the SDK Provider for the wallet address is not found.
+ */
+export async function getTokenBalancesByChain(
+  client: SDKClient,
+  walletAddress: string,
+  tokensByChain: { [chainId: number]: Token[] }
+): Promise<{ [chainId: number]: TokenAmount[] }>
+export async function getTokenBalancesByChain(
+  client: SDKClient,
+  walletAddress: string,
+  tokensByChain: { [chainId: number]: TokenExtended[] }
+): Promise<{ [chainId: number]: TokenAmountExtended[] }> {
+  if (!walletAddress) {
+    throw new ValidationError('Missing walletAddress.')
+  }
+
+  const tokenList = Object.values(tokensByChain).flat()
+  const invalidTokens = tokenList.filter((token) => !isToken(token))
+  if (invalidTokens.length) {
+    throw new ValidationError('Invalid tokens passed.')
+  }
+
+  const provider = client.providers.find((provider) =>
+    provider.isAddress(walletAddress)
+  )
+  if (!provider) {
+    throw new Error(`SDK Token Provider for ${walletAddress} is not found.`)
+  }
+
+  const tokenAmountsByChain: {
+    [chainId: number]: TokenAmount[] | TokenAmountExtended[]
+  } = {}
+  const tokenAmountsSettled = await Promise.allSettled(
+    Object.keys(tokensByChain).map(async (chainIdStr) => {
+      const chainId = Number.parseInt(chainIdStr, 10)
+      const chain = await client.getChainById(chainId)
+      if (provider.type === chain.chainType) {
+        const tokenAmounts = await provider.getBalance(
+          client,
+          walletAddress,
+          tokensByChain[chainId]
+        )
+        tokenAmountsByChain[chainId] = tokenAmounts
+      } else {
+        // if the provider is not the same as the chain type,
+        // return the tokens as is
+        tokenAmountsByChain[chainId] = tokensByChain[chainId]
+      }
+    })
+  )
+  if (client.config.debug) {
+    for (const result of tokenAmountsSettled) {
+      if (result.status === 'rejected') {
+        console.warn("Couldn't fetch token balance.", result.reason)
+      }
+    }
+  }
+  return tokenAmountsByChain
+}