@lifi/sdk 3.0.0-alpha.3 → 3.0.0-alpha.31

package/src/services/api.ts

@@ -0,0 +1,507 @@
+import type {
+  ChainId,
+  ChainKey,
+  ChainsRequest,
+  ChainsResponse,
+  ConnectionsRequest,
+  ConnectionsResponse,
+  ContractCallQuoteRequest,
+  ExtendedChain,
+  GasRecommendationRequest,
+  GasRecommendationResponse,
+  GetStatusRequest,
+  LiFiStep,
+  QuoteRequest,
+  RequestOptions,
+  RoutesRequest,
+  RoutesResponse,
+  StatusResponse,
+  Token,
+  TokensRequest,
+  TokensResponse,
+  ToolsRequest,
+  ToolsResponse,
+  WalletAnalytics,
+  WalletAnalyticsRequest,
+} from '@lifi/types'
+import { config } from '../config.js'
+import { request } from '../request.js'
+import { isRoutesRequest, isStep } from '../typeguards.js'
+import { ValidationError } from '../utils/errors.js'
+import { parseBackendError } from '../utils/parseBackendError.js'
+/**
+ * Fetch information about a Token
+ * @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 (
+  chain: ChainKey | ChainId,
+  token: string,
+  options?: RequestOptions
+): Promise<Token> => {
+  if (!chain) {
+    throw new ValidationError('Required parameter "chain" is missing.')
+  }
+  if (!token) {
+    throw new ValidationError('Required parameter "token" is missing.')
+  }
+  try {
+    const response = await request<Token>(
+      `${config.get().apiUrl}/token?${new URLSearchParams({
+        chain,
+        token,
+      } as Record<string, string>)}`,
+      {
+        signal: options?.signal,
+      }
+    )
+    return response
+  } catch (e) {
+    throw await parseBackendError(e)
+  }
+}
+
+/**
+ * Get a quote for a token transfer
+ * @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 const getQuote = async (
+  params: QuoteRequest,
+  options?: RequestOptions
+): Promise<LiFiStep> => {
+  const requiredParameters: Array<keyof QuoteRequest> = [
+    'fromChain',
+    'fromToken',
+    'fromAddress',
+    'fromAmount',
+    'toChain',
+    'toToken',
+  ]
+  requiredParameters.forEach((requiredParameter) => {
+    if (!params[requiredParameter]) {
+      throw new ValidationError(
+        `Required parameter "${requiredParameter}" is missing.`
+      )
+    }
+  })
+  const _config = config.get()
+  // apply defaults
+  params.integrator ??= _config.integrator
+  params.order ??= _config.routeOptions?.order
+  params.slippage ??= _config.routeOptions?.slippage
+  params.referrer ??= _config.routeOptions?.referrer
+  params.fee ??= _config.routeOptions?.fee
+  params.allowBridges ??= _config.routeOptions?.bridges?.allow
+  params.denyBridges ??= _config.routeOptions?.bridges?.deny
+  params.preferBridges ??= _config.routeOptions?.bridges?.prefer
+  params.allowExchanges ??= _config.routeOptions?.exchanges?.allow
+  params.denyExchanges ??= _config.routeOptions?.exchanges?.deny
+  params.preferExchanges ??= _config.routeOptions?.exchanges?.prefer
+
+  Object.keys(params).forEach(
+    (key) =>
+      !params[key as keyof QuoteRequest] &&
+      delete params[key as keyof QuoteRequest]
+  )
+
+  try {
+    const response = await request<LiFiStep>(
+      `${_config.apiUrl}/quote?${new URLSearchParams(
+        params as unknown as Record<string, string>
+      )}`,
+      {
+        signal: options?.signal,
+      }
+    )
+    return response
+  } catch (e) {
+    throw await parseBackendError(e)
+  }
+}
+
+/**
+ * Get a quote for a destination contract call
+ * @param params - The configuration of the requested destination call
+ * @param options - Request options
+ * @throws {LiFiError} - Throws a LiFiError if request fails
+ * @returns - Returns step.
+ */
+export const getContractCallQuote = async (
+  params: ContractCallQuoteRequest,
+  options?: RequestOptions
+): Promise<LiFiStep> => {
+  // validation
+  const requiredParameters: Array<keyof ContractCallQuoteRequest> = [
+    'fromChain',
+    'fromToken',
+    'fromAddress',
+    'toChain',
+    'toToken',
+    'toAmount',
+    'toContractAddress',
+    'toContractCallData',
+    'toContractGasLimit',
+  ]
+  requiredParameters.forEach((requiredParameter) => {
+    if (!params[requiredParameter]) {
+      throw new ValidationError(
+        `Required parameter "${requiredParameter}" is missing.`
+      )
+    }
+  })
+  const _config = config.get()
+  // apply defaults
+  // option.order is not used in this endpoint
+  params.integrator ??= _config.integrator
+  params.slippage ??= _config.routeOptions?.slippage
+  params.referrer ??= _config.routeOptions?.referrer
+  params.fee ??= _config.routeOptions?.fee
+  params.allowBridges ??= _config.routeOptions?.bridges?.allow
+  params.denyBridges ??= _config.routeOptions?.bridges?.deny
+  params.preferBridges ??= _config.routeOptions?.bridges?.prefer
+  params.allowExchanges ??= _config.routeOptions?.exchanges?.allow
+  params.denyExchanges ??= _config.routeOptions?.exchanges?.deny
+  params.preferExchanges ??= _config.routeOptions?.exchanges?.prefer
+  // send request
+  try {
+    const response = await request<LiFiStep>(
+      `${_config.apiUrl}/quote/contractCall`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(params),
+        signal: options?.signal,
+      }
+    )
+    return response
+  } catch (e) {
+    throw await parseBackendError(e)
+  }
+}
+
+/**
+ * Check the status of a transfer. For cross chain transfers, the "bridge" parameter is required.
+ * @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 (
+  params: GetStatusRequest,
+  options?: RequestOptions
+): Promise<StatusResponse> => {
+  if (!params.txHash) {
+    throw new ValidationError('Required parameter "txHash" is missing.')
+  }
+  const queryParams = new URLSearchParams(
+    params as unknown as Record<string, string>
+  )
+  try {
+    const response = await request<StatusResponse>(
+      `${config.get().apiUrl}/status?${queryParams}`,
+      {
+        signal: options?.signal,
+      }
+    )
+    return response
+  } catch (e) {
+    throw await parseBackendError(e)
+  }
+}
+
+/**
+ * Get all available chains
+ * @param params - The configuration of the requested chains
+ * @param options - Request options
+ * @returns A list of all available chains
+ * @throws {LiFiError} Throws a LiFiError if request fails.
+ */
+export const getChains = async (
+  params?: ChainsRequest,
+  options?: RequestOptions
+): Promise<ExtendedChain[]> => {
+  if (params) {
+    Object.keys(params).forEach(
+      (key) =>
+        !params[key as keyof ChainsRequest] &&
+        delete params[key as keyof ChainsRequest]
+    )
+  }
+  try {
+    const response = await request<ChainsResponse>(
+      `${config.get().apiUrl}/chains?${new URLSearchParams(
+        params as Record<string, string>
+      )}`,
+      {
+        signal: options?.signal,
+      }
+    )
+    return response.chains
+  } catch (e) {
+    throw await parseBackendError(e)
+  }
+}
+
+/**
+ * Get a set of routes for a request that describes a transfer of tokens.
+ * @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 (
+  params: RoutesRequest,
+  options?: RequestOptions
+): Promise<RoutesResponse> => {
+  if (!isRoutesRequest(params)) {
+    throw new ValidationError('Invalid routes request.')
+  }
+  const _config = config.get()
+  // apply defaults
+  params.options = {
+    ..._config.routeOptions,
+    ...params.options,
+  }
+  // send request
+  try {
+    const response = await request<RoutesResponse>(
+      `${_config.apiUrl}/advanced/routes`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(params),
+        signal: options?.signal,
+      }
+    )
+    return response
+  } catch (e) {
+    throw await parseBackendError(e)
+  }
+}
+
+/**
+ * Get the transaction data for a single step of a route
+ * @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 (
+  step: LiFiStep,
+  options?: RequestOptions
+): Promise<LiFiStep> => {
+  if (!isStep(step)) {
+    // While the validation fails for some users we should not enforce it
+    // eslint-disable-next-line no-console
+    console.warn('SDK Validation: Invalid Step', step)
+  }
+  try {
+    const response = await request<LiFiStep>(
+      `${config.get().apiUrl}/advanced/stepTransaction`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(step),
+        signal: options?.signal,
+      }
+    )
+    return response
+  } catch (e) {
+    throw await parseBackendError(e)
+  }
+}
+
+/**
+ * Get the available tools to bridge and swap tokens.
+ * @param params - The configuration of the requested tools
+ * @param options - Request options
+ * @returns The tools that are available on the requested chains
+ */
+export const getTools = async (
+  params?: ToolsRequest,
+  options?: RequestOptions
+): Promise<ToolsResponse> => {
+  if (params) {
+    Object.keys(params).forEach(
+      (key) =>
+        !params[key as keyof ToolsRequest] &&
+        delete params[key as keyof ToolsRequest]
+    )
+  }
+  try {
+    const response = await request<ToolsResponse>(
+      `${config.get().apiUrl}/tools?${new URLSearchParams(
+        params as Record<string, string>
+      )}`,
+      {
+        signal: options?.signal,
+      }
+    )
+    return response
+  } catch (e) {
+    throw await parseBackendError(e)
+  }
+}
+
+/**
+ * Get all known tokens.
+ * @param params - The configuration of the requested tokens
+ * @param options - Request options
+ * @returns The tokens that are available on the requested chains
+ */
+export const getTokens = async (
+  params?: TokensRequest,
+  options?: RequestOptions
+): Promise<TokensResponse> => {
+  if (params) {
+    Object.keys(params).forEach(
+      (key) =>
+        !params[key as keyof TokensRequest] &&
+        delete params[key as keyof TokensRequest]
+    )
+  }
+
+  try {
+    const response = await request<TokensResponse>(
+      `${config.get().apiUrl}/tokens?${new URLSearchParams(
+        params as Record<string, string>
+      )}`,
+      {
+        signal: options?.signal,
+      }
+    )
+    return response
+  } catch (e) {
+    throw await parseBackendError(e)
+  }
+}
+
+/**
+ * Get gas recommendation for a certain chain
+ * @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 (
+  params: GasRecommendationRequest,
+  options?: RequestOptions
+): Promise<GasRecommendationResponse> => {
+  if (!params.chainId) {
+    throw new ValidationError('Required parameter "chainId" is missing.')
+  }
+
+  const url = new URL(`${config.get().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)
+  }
+
+  try {
+    const response = await request<GasRecommendationResponse>(url.toString(), {
+      signal: options?.signal,
+    })
+    return response
+  } catch (e) {
+    throw await parseBackendError(e)
+  }
+}
+
+/**
+ * Get all the available connections for swap/bridging tokens
+ * @param connectionRequest ConnectionsRequest
+ * @returns ConnectionsResponse
+ */
+export const getConnections = async (
+  connectionRequest: ConnectionsRequest
+): Promise<ConnectionsResponse> => {
+  const url = new URL(`${config.get().apiUrl}/connections`)
+
+  const { fromChain, fromToken, toChain, toToken } = connectionRequest
+
+  if (fromChain) {
+    url.searchParams.append('fromChain', fromChain as unknown as string)
+  }
+  if (fromToken) {
+    url.searchParams.append('fromToken', fromToken)
+  }
+  if (toChain) {
+    url.searchParams.append('toChain', toChain as unknown as string)
+  }
+  if (toToken) {
+    url.searchParams.append('toToken', toToken)
+  }
+  const connectionRequestArrayParams: Array<keyof ConnectionsRequest> = [
+    'allowBridges',
+    'denyBridges',
+    'preferBridges',
+    'allowExchanges',
+    'denyExchanges',
+    'preferExchanges',
+  ]
+  connectionRequestArrayParams.forEach((parameter) => {
+    const connectionRequestArrayParam: string[] = connectionRequest[
+      parameter
+    ] as string[]
+
+    if (connectionRequestArrayParam?.length) {
+      connectionRequestArrayParam?.forEach((value) => {
+        url.searchParams.append(parameter, value)
+      })
+    }
+  })
+  try {
+    const response = await request<ConnectionsResponse>(url.toString())
+    return response
+  } catch (e) {
+    throw await parseBackendError(e)
+  }
+}
+
+export const getTransactionHistory = async (
+  walletAnalyticsRequest: WalletAnalyticsRequest
+): Promise<WalletAnalytics> => {
+  const _config = config.get()
+
+  if (!walletAnalyticsRequest.fromTimestamp) {
+    throw new ValidationError('Required parameter "fromTimestamp" is missing.')
+  }
+
+  if (!walletAnalyticsRequest.toTimestamp) {
+    throw new ValidationError('Required parameter "toTimestamp" is missing.')
+  }
+
+  const url = new URL(
+    `${_config.apiUrl}/analytics/wallets/${walletAnalyticsRequest.walletAddress}`
+  )
+
+  url.searchParams.append(
+    'fromTimestamp',
+    walletAnalyticsRequest.fromTimestamp.toString()
+  )
+
+  url.searchParams.append(
+    'toTimestamp',
+    walletAnalyticsRequest.toTimestamp.toString()
+  )
+  try {
+    const response = await request<WalletAnalytics>(url)
+    return response
+  } catch (e) {
+    throw await parseBackendError(e)
+  }
+}

package/src/services/balance.ts

@@ -0,0 +1,93 @@
+import type { Token, TokenAmount } from '@lifi/types'
+import { config } from '../config.js'
+import { isToken } from '../typeguards.js'
+import { ValidationError } from '../utils/errors.js'
+
+/**
+ * Returns the balances of a specific token a wallet holds across all aggregated chains.
+ * @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 parameters are invalid.
+ */
+export const getTokenBalance = async (
+  walletAddress: string,
+  token: Token
+): Promise<TokenAmount | null> => {
+  const tokenAmounts = await getTokenBalances(walletAddress, [token])
+  return tokenAmounts.length ? tokenAmounts[0] : null
+}
+
+/**
+ * Returns the balances for a list tokens a wallet holds  across all aggregated chains.
+ * @param walletAddress - A wallet address.
+ * @param tokens - A list of Token objects.
+ * @returns A list of objects containing the tokens and the amounts on different chains.
+ * @throws {ValidationError} Throws a ValidationError if parameters are invalid.
+ */
+export const getTokenBalances = async (
+  walletAddress: string,
+  tokens: Token[]
+): Promise<TokenAmount[]> => {
+  // 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[] }
+  )
+
+  const tokenAmountsByChain = await getTokenBalancesByChain(
+    walletAddress,
+    tokensByChain
+  )
+  return Object.values(tokenAmountsByChain).flat()
+}
+
+/**
+ * This method queries the balances of tokens for a specific list of chains for a given wallet.
+ * @param walletAddress - A walletaddress.
+ * @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 parameters are invalid.
+ */
+export const getTokenBalancesByChain = async (
+  walletAddress: string,
+  tokensByChain: { [chainId: number]: Token[] }
+): Promise<{ [chainId: number]: TokenAmount[] }> => {
+  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 token passed: address "${invalidTokens[0].address}" on chainId "${invalidTokens[0].chainId}"`
+    )
+  }
+
+  const tokenAmountsByChain: { [chainId: number]: TokenAmount[] } = {}
+  await Promise.allSettled(
+    Object.keys(tokensByChain).map(async (chainIdStr) => {
+      const chainId = parseInt(chainIdStr)
+      const baseTokenAddress = tokensByChain[chainId][0].address
+      const provider = config
+        .get()
+        .providers?.find((provider) => provider.isAddress(baseTokenAddress))
+      if (!provider) {
+        throw new Error('SDK Token Provider not found.')
+      }
+      const tokenAmounts = await provider.getBalance(
+        walletAddress,
+        tokensByChain[chainId]
+      )
+      tokenAmountsByChain[chainId] = tokenAmounts
+    })
+  )
+  return tokenAmountsByChain
+}

package/src/typeguards.ts

@@ -0,0 +1,89 @@
+import type {
+  Action,
+  Estimate,
+  LiFiStep,
+  RouteOptions,
+  RoutesRequest,
+  StaticToken,
+} from '@lifi/types'
+
+export const isRoutesRequest = (
+  routesRequest: RoutesRequest
+): routesRequest is RoutesRequest => {
+  const {
+    fromChainId,
+    fromAmount,
+    fromTokenAddress,
+    toChainId,
+    toTokenAddress,
+    options,
+  } = routesRequest
+
+  return (
+    typeof fromChainId === 'number' &&
+    typeof fromAmount === 'string' &&
+    fromAmount !== '' &&
+    typeof fromTokenAddress === 'string' &&
+    fromTokenAddress !== '' &&
+    typeof toChainId === 'number' &&
+    typeof toTokenAddress === 'string' &&
+    toTokenAddress !== '' &&
+    (!options || isRoutesOptions(options))
+  )
+}
+
+const isRoutesOptions = (
+  routeOptions: RouteOptions
+): routeOptions is RouteOptions =>
+  !routeOptions?.slippage || typeof routeOptions.slippage === 'number'
+
+export const isStep = (step: LiFiStep): step is LiFiStep => {
+  const { id, type, tool, action, estimate } = step
+
+  return (
+    typeof id === 'string' &&
+    ['swap', 'cross', 'lifi'].includes(type) &&
+    typeof tool === 'string' &&
+    isAction(action) &&
+    isEstimate(estimate)
+  )
+}
+
+const isAction = (action: Action): action is Action => {
+  const { fromChainId, fromAmount, fromToken, toChainId, toToken, slippage } =
+    action
+
+  return (
+    typeof fromChainId === 'number' &&
+    typeof fromAmount === 'string' &&
+    fromAmount !== '' &&
+    isToken(fromToken) &&
+    typeof toChainId === 'number' &&
+    isToken(toToken) &&
+    typeof slippage === 'number'
+  )
+}
+
+const isEstimate = (estimate: Estimate): estimate is Estimate => {
+  const { fromAmount, toAmount, toAmountMin, approvalAddress } = estimate
+
+  return (
+    typeof fromAmount === 'string' &&
+    fromAmount !== '' &&
+    typeof toAmount === 'string' &&
+    toAmount !== '' &&
+    typeof toAmountMin === 'string' &&
+    toAmountMin !== '' &&
+    typeof approvalAddress === 'string'
+  )
+}
+
+export const isToken = (token: StaticToken): token is StaticToken => {
+  const { address, decimals, chainId } = token
+
+  return (
+    typeof address === 'string' &&
+    typeof decimals === 'number' &&
+    typeof chainId === 'number'
+  )
+}

package/src/types/index.ts

@@ -0,0 +1 @@
+export * from './internal.js'