0xtrails 0.13.2 → 0.14.0

package/src/query/balance.fetchers.ts

@@ -1,753 +0,0 @@
-/**
- * Pure async fetcher functions and helpers for balance queries.
- * This is a leaf module — NO React imports, NO queryClient, NO balanceKeys.
- */
-import type {
-  NativeTokenBalance,
-  Page,
-  SequenceIndexerGateway,
-  TokenBalance,
-} from "@0xsequence/indexer"
-import { ContractVerificationStatus } from "@0xsequence/indexer"
-import type { TokenPrice } from "@0xtrails/api"
-import { erc20Abi, parseUnits, zeroAddress } from "viem"
-import { getTokenPrices } from "./price.queries.js"
-import { getChainInfo, getChainRpcClient } from "../chains.js"
-import { getTokenImageUrl, type Token } from "../tokens.js"
-import type { TrailsClient } from "../trailsClient.js"
-import { logger } from "../logger.js"
-import {
-  addressEqual,
-  isNativeToken as isNativeTokenAddress,
-} from "../utils/address.js"
-import {
-  formatBalanceFields,
-  formatPriceFields,
-  formatUsdFields,
-  getTokenBalanceUsd,
-  rawAmountToNumber,
-  type Price,
-} from "../utils/format.js"
-import { isNetworkError } from "./helpers.js"
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export type GetTokenBalancesParams = {
-  account: string
-  tokenAddress?: string | null
-  indexerGatewayClient: SequenceIndexerGateway
-  page?: number
-  pageSize?: number
-}
-
-export type GetTokenBalancesForMultipleAccountsParams = {
-  accounts: string[]
-  indexerGatewayClient: SequenceIndexerGateway
-  page?: number
-  pageSize?: number
-}
-
-/**
- * Flat balance data for a single account using Token type (converted from raw gateway data)
- */
-export type FlatTokenBalancesData = {
-  /** All tokens (native + ERC20) converted to Token type */
-  tokens: Token[]
-  /** Native tokens only (converted to Token type) */
-  nativeTokens: Token[]
-  /** ERC20 tokens only (converted to Token type) */
-  erc20Tokens: Token[]
-  page: Page
-}
-
-export type GetTokenBalancesForMultipleAccountsReturn = {
-  [account: string]: FlatTokenBalancesData
-}
-
-export type GetTokenBalancesWithPricesParams = {
-  account: string
-  indexerGatewayClient: SequenceIndexerGateway
-  trailsClient: TrailsClient
-}
-
-export type GetTokenBalancesWithPriceReturn = {
-  balances: Token[]
-}
-
-type TokenBalancesSummary = Awaited<
-  ReturnType<SequenceIndexerGateway["getTokenBalancesSummary"]>
->
-
-// ============================================================================
-// Helper Functions
-// ============================================================================
-
-/**
- * Helper to add price and USD fields to a Token result
- * Extracts common logic for handling price and balance USD calculations
- */
-function addPriceAndUsdFields(
-  result: Token,
-  token: TokenBalance | NativeTokenBalance,
-  priceData?: TokenPrice,
-): void {
-  // Get prices from both sources
-  const apiPriceUSD =
-    "priceUSD" in token && typeof token.priceUSD === "string"
-      ? token.priceUSD
-      : undefined
-  const apiBalanceUSD =
-    "balanceUSD" in token && typeof token.balanceUSD === "string"
-      ? token.balanceUSD
-      : undefined
-  const coinApiPrice = priceData?.priceUsd
-  const parsedIndexerPrice = apiPriceUSD ? parseFloat(apiPriceUSD) : Number.NaN
-  const indexerPrice = Number.isNaN(parsedIndexerPrice)
-    ? undefined
-    : parsedIndexerPrice
-
-  // Use coin prices API as primary source, fall back to indexer price
-  const priceUsd = coinApiPrice !== undefined ? coinApiPrice : indexerPrice
-
-  if (priceUsd !== undefined) {
-    const priceFields = formatPriceFields(priceUsd)
-    result.priceUsd = priceFields.priceUsd
-    result.priceUsdFormatted = priceFields.priceUsdFormatted
-    result.priceUsdDisplay = priceFields.priceUsdDisplay
-
-    if (token.balance) {
-      const price: Price = {
-        value: priceUsd,
-        currency: "USD",
-      }
-      const balanceUsd = getTokenBalanceUsd(token, price)
-      if (balanceUsd !== undefined) {
-        const usdFields = formatUsdFields(balanceUsd)
-        result.balanceUsd = usdFields.balanceUsd
-        result.balanceUsdFormatted = usdFields.balanceUsdFormatted
-        result.balanceUsdDisplay = usdFields.balanceUsdDisplay
-        result.balanceUsdLocaleDisplay = usdFields.balanceUsdLocaleDisplay
-      }
-    } else if (apiBalanceUSD !== undefined) {
-      // Fallback to API balance if we can't calculate
-      const parsedBalanceUsd = parseFloat(apiBalanceUSD)
-      if (Number.isNaN(parsedBalanceUsd)) return
-      const usdFields = formatUsdFields(parsedBalanceUsd)
-      result.balanceUsd = usdFields.balanceUsd
-      result.balanceUsdFormatted = usdFields.balanceUsdFormatted
-      result.balanceUsdDisplay = usdFields.balanceUsdDisplay
-      result.balanceUsdLocaleDisplay = usdFields.balanceUsdLocaleDisplay
-    }
-  }
-}
-
-// ============================================================================
-// Conversion Helpers for TokenBalance -> Token
-// ============================================================================
-
-/**
- * Converts TokenBalance to Token
- */
-export function convertTokenBalanceToToken(
-  token: TokenBalance,
-  priceData?: TokenPrice,
-  chainInfo?: ReturnType<typeof getChainInfo>,
-): Token {
-  const chainId = token.contractInfo?.chainId || 0
-  const chain = chainInfo || getChainInfo(chainId)
-  const contractAddress = token.contractAddress || zeroAddress
-
-  const result: Token = {
-    symbol: token.contractInfo?.symbol || "???",
-    name: token.contractInfo?.name || "Unknown Token",
-    decimals: token.contractInfo?.decimals ?? 18,
-    contractAddress,
-    chainId,
-    chainName: chain?.name || `Chain ${chainId}`,
-    imageUrl: getTokenImageUrl({
-      chainId,
-      contractAddress,
-      symbol: token.contractInfo?.symbol || "???",
-      fallbackImageUrl: token.contractInfo?.logoURI,
-    }),
-    isNativeToken: false,
-  }
-
-  // Format balance if available
-  if (token.balance) {
-    const decimals = result.decimals
-    const balanceFields = formatBalanceFields(token.balance, decimals)
-    result.balance = balanceFields.balance
-    result.balanceFormatted = balanceFields.balanceFormatted
-    result.balanceDisplay = balanceFields.balanceDisplay
-    result.balanceLocaleDisplay = balanceFields.balanceLocaleDisplay
-  }
-
-  // Add price and USD balance
-  addPriceAndUsdFields(result, token, priceData)
-
-  // Default isSufficientBalance to true
-  result.isSufficientBalance = true
-
-  return result
-}
-
-/**
- * Converts NativeTokenBalance to Token
- */
-export function convertNativeTokenBalanceToToken(
-  token: NativeTokenBalance,
-  priceData?: TokenPrice,
-  chainInfo?: ReturnType<typeof getChainInfo>,
-): Token {
-  const chainId = token.chainId
-  const chain = chainInfo || getChainInfo(chainId)
-  const symbol = chain?.nativeCurrency.symbol || "Unknown"
-
-  const result: Token = {
-    symbol,
-    name: chain?.nativeCurrency.name || "Unknown",
-    decimals: chain?.nativeCurrency.decimals ?? 18,
-    contractAddress: zeroAddress,
-    chainId,
-    chainName: chain?.name || `Chain ${chainId}`,
-    imageUrl: getTokenImageUrl({
-      chainId,
-      contractAddress: zeroAddress,
-      symbol,
-    }),
-    isNativeToken: true,
-  }
-
-  // Format balance if available
-  if (token.balance) {
-    const decimals = result.decimals
-    const balanceFields = formatBalanceFields(token.balance, decimals)
-    result.balance = balanceFields.balance
-    result.balanceFormatted = balanceFields.balanceFormatted
-    result.balanceDisplay = balanceFields.balanceDisplay
-    result.balanceLocaleDisplay = balanceFields.balanceLocaleDisplay
-  }
-
-  // Add price and USD balance
-  addPriceAndUsdFields(result, token, priceData)
-
-  // Default isSufficientBalance to true
-  result.isSufficientBalance = true
-
-  return result
-}
-
-type BalanceEntry = TokenBalance | NativeTokenBalance
-
-function convertBalanceToTokenOrNull(
-  token: BalanceEntry,
-  priceData?: TokenPrice,
-): Token | null {
-  try {
-    if (isNativeToken(token)) {
-      return convertNativeTokenBalanceToToken(token, priceData)
-    }
-
-    return convertTokenBalanceToToken(token, priceData)
-  } catch (err) {
-    logger.console.warn(
-      "[trails-sdk] Skipping malformed token balance:",
-      token,
-      err,
-    )
-    return null
-  }
-}
-
-// Default empty page info for query fallback
-export const defaultPage = { page: 1, pageSize: 10, more: false }
-
-function getPageRequest(page?: number, pageSize?: number): Page | undefined {
-  if (page === undefined && pageSize === undefined) return undefined
-  return {
-    page,
-    pageSize,
-  }
-}
-
-function createEmptyMultiAccountResult(
-  accounts: string[],
-): GetTokenBalancesForMultipleAccountsReturn {
-  const result: GetTokenBalancesForMultipleAccountsReturn = {}
-  for (const account of accounts) {
-    result[account.toLowerCase()] = {
-      tokens: [],
-      nativeTokens: [],
-      erc20Tokens: [],
-      page: defaultPage,
-    }
-  }
-  return result
-}
-
-function mapChainEntryResults<T extends BalanceEntry>(
-  entries: Array<{ chainId: number; results?: T[] }>,
-  result: GetTokenBalancesForMultipleAccountsReturn,
-  toToken: (entry: T) => Token | null,
-  bucket: "erc20Tokens" | "nativeTokens",
-): void {
-  for (const chainEntry of entries) {
-    if (!getChainInfo(chainEntry.chainId)) {
-      logger.console.warn(
-        `[tokenBalances] Skipping unsupported chain ID: ${chainEntry.chainId}`,
-      )
-      continue
-    }
-
-    for (const entry of chainEntry.results || []) {
-      const accountAddr = entry.accountAddress?.toLowerCase()
-      const accountEntry = accountAddr ? result[accountAddr] : undefined
-      if (!accountEntry) continue
-
-      const token = toToken(entry)
-      if (!token) continue
-
-      accountEntry[bucket].push(token)
-      accountEntry.tokens.push(token)
-    }
-  }
-}
-
-function toTokenPriceKey(chainId: number, tokenAddress?: string): string {
-  return `${chainId}:${tokenAddress || zeroAddress}`
-}
-
-function createTokenMapFromGatewaySummary(
-  summary: TokenBalancesSummary,
-): Map<string, TokenBalance | NativeTokenBalance> {
-  const tokenMap = new Map<string, TokenBalance | NativeTokenBalance>()
-
-  for (const chainEntry of summary.balances) {
-    for (const tokenBalance of chainEntry.results) {
-      if (!("contractAddress" in tokenBalance)) continue
-      if (!("contractInfo" in tokenBalance)) continue
-      tokenMap.set(
-        `${tokenBalance.contractAddress}-${tokenBalance.chainId}-${tokenBalance.contractInfo?.symbol}`,
-        tokenBalance,
-      )
-    }
-  }
-
-  for (const chainEntry of summary.nativeBalances) {
-    for (const nativeBalance of chainEntry.results) {
-      tokenMap.set(
-        `${zeroAddress}-${nativeBalance.chainId}-native`,
-        nativeBalance,
-      )
-    }
-  }
-
-  return tokenMap
-}
-
-// Type guard for native token balance
-export function isNativeToken(
-  token: TokenBalance | NativeTokenBalance,
-): token is NativeTokenBalance {
-  if (!("contractAddress" in token)) {
-    return true
-  }
-  if (token.contractAddress === zeroAddress) {
-    return true
-  }
-  return false
-}
-
-/**
- * Sort function for Token by priority
- */
-export function sortTokensByPriority(a: Token, b: Token): number {
-  // First sort by USD balance if available
-  const aUsdBalance = a.balanceUsd ?? 0
-  const bUsdBalance = b.balanceUsd ?? 0
-
-  // If both have non-zero balances, sort by balance
-  if (aUsdBalance > 0 && bUsdBalance > 0) {
-    return bUsdBalance - aUsdBalance // Higher USD balance first
-  }
-
-  // If one has balance and other doesn't, prioritize the one with balance
-  if (aUsdBalance > 0 && bUsdBalance === 0) return -1
-  if (aUsdBalance === 0 && bUsdBalance > 0) return 1
-
-  // If both have zero balance, sort by price volume (if available)
-  if (aUsdBalance === 0 && bUsdBalance === 0) {
-    // Note: price24hVol is not in Token, so we skip volume sorting
-    // This can be added later if needed
-  }
-
-  // Then sort by native token status
-  if (a.isNativeToken && !b.isNativeToken) return -1
-  if (!a.isNativeToken && b.isNativeToken) return 1
-
-  // Then sort by token balance
-  try {
-    const balanceA = BigInt(a.balance || "0")
-    const balanceB = BigInt(b.balance || "0")
-    if (balanceA > balanceB) return -1
-    if (balanceA < balanceB) return 1
-  } catch (err) {
-    logger.console.warn("[trails-sdk] Failed to compare token balances:", {
-      tokenA: a.symbol,
-      tokenB: b.symbol,
-      err,
-    })
-  }
-
-  return 0
-}
-
-// ============================================================================
-// Pure Fetcher Functions
-// ============================================================================
-
-/**
- * Fetch token balances summary for a single account
- * Returns chain-grouped data: { balances: [{ chainId, results: [...] }] }
- */
-export async function fetchTokenBalancesSummary({
-  account,
-  tokenAddress,
-  indexerGatewayClient,
-  page,
-  pageSize,
-}: GetTokenBalancesParams): Promise<TokenBalancesSummary> {
-  if (!account || !indexerGatewayClient) {
-    throw new Error("Account address and indexer client are required")
-  }
-
-  try {
-    const summaryFromGateway =
-      await indexerGatewayClient.getTokenBalancesSummary({
-        filter: {
-          accountAddresses: [account],
-          contractStatus: ContractVerificationStatus.VERIFIED,
-          contractTypes: ["ERC20"],
-          contractWhitelist: tokenAddress ? [tokenAddress] : undefined,
-          omitNativeBalances: false,
-        },
-        page: getPageRequest(page, pageSize),
-      })
-
-    return summaryFromGateway
-  } catch (error) {
-    if (isNetworkError(error)) {
-      logger.console.warn(
-        "[trails-sdk] Network error fetching token balances, returning empty result:",
-        { error, account },
-      )
-      return {
-        balances: [],
-        nativeBalances: [],
-        page: defaultPage,
-      }
-    }
-
-    logger.console.error(
-      "[trails-sdk] Failed to fetch token balances summary:",
-      error,
-    )
-    throw error
-  }
-}
-
-/**
- * Fetch token balances summary for multiple accounts in a single API call
- */
-export async function fetchMultiAccountBalances({
-  accounts,
-  indexerGatewayClient,
-  page,
-  pageSize,
-}: GetTokenBalancesForMultipleAccountsParams): Promise<GetTokenBalancesForMultipleAccountsReturn> {
-  if (!accounts.length || !indexerGatewayClient) {
-    throw new Error(
-      "At least one account address and indexer client are required",
-    )
-  }
-
-  // Filter out empty/null accounts
-  const validAccounts = accounts.filter((a) => a && a.length > 0)
-  if (!validAccounts.length) {
-    return {}
-  }
-
-  try {
-    const summaryFromGateway =
-      await indexerGatewayClient.getTokenBalancesSummary({
-        filter: {
-          accountAddresses: validAccounts,
-          contractStatus: ContractVerificationStatus.VERIFIED,
-          contractTypes: ["ERC20"],
-          omitNativeBalances: false,
-        },
-        page: getPageRequest(page, pageSize),
-      })
-
-    const result = createEmptyMultiAccountResult(validAccounts)
-
-    mapChainEntryResults(
-      summaryFromGateway.balances,
-      result,
-      convertBalanceToTokenOrNull,
-      "erc20Tokens",
-    )
-
-    mapChainEntryResults(
-      summaryFromGateway.nativeBalances,
-      result,
-      convertBalanceToTokenOrNull,
-      "nativeTokens",
-    )
-
-    // Set page info from gateway response
-    for (const account of validAccounts) {
-      const accountEntry = result[account.toLowerCase()]
-      if (accountEntry) {
-        accountEntry.page = summaryFromGateway.page ?? defaultPage
-      }
-    }
-
-    return result
-  } catch (error) {
-    if (isNetworkError(error)) {
-      logger.console.warn(
-        "[trails-sdk] Network error fetching token balances, returning empty result:",
-        { error, accounts },
-      )
-      return createEmptyMultiAccountResult(validAccounts)
-    }
-
-    logger.console.error(
-      "[trails-sdk] Failed to fetch token balances summary for multiple accounts:",
-      error,
-    )
-    throw error
-  }
-}
-
-// ============================================================================
-// Composite Fetcher — replaces the imperative getTokenBalancesWithPrices chain
-// ============================================================================
-
-/**
- * Fetches token balances for an account, enriches them with price data,
- * and returns an array of Token objects with balance and price fields.
- *
- * This is a pure function — no queryClient, no balanceKeys.
- */
-export async function fetchBalancesWithPrices({
-  account,
-  indexerGatewayClient,
-  trailsClient,
-}: GetTokenBalancesWithPricesParams): Promise<GetTokenBalancesWithPriceReturn> {
-  const summaryFromGateway = await fetchTokenBalancesSummary({
-    account,
-    indexerGatewayClient,
-  })
-  const tokenMap = createTokenMapFromGatewaySummary(summaryFromGateway)
-  const tokens = Array.from(tokenMap.values())
-
-  let tokenPrices: Awaited<ReturnType<typeof getTokenPrices>> = []
-  try {
-    tokenPrices = await getTokenPrices(
-      trailsClient,
-      tokens.map((t) => ({
-        chainId: t.chainId,
-        tokenAddress: isNativeToken(t) ? zeroAddress : t.contractAddress,
-        tokenSymbol: isNativeToken(t) ? "" : t.contractInfo?.symbol || "",
-      })),
-    )
-  } catch (err) {
-    logger.console.warn(
-      "[trails-sdk] Price fetch failed, returning balances without prices:",
-      err,
-    )
-  }
-
-  const tokenPriceMap = new Map<string, TokenPrice>()
-  for (const tokenPrice of tokenPrices) {
-    tokenPriceMap.set(
-      toTokenPriceKey(tokenPrice.token.chainId, tokenPrice.token.tokenAddress),
-      tokenPrice,
-    )
-  }
-
-  const balancesWithPrices: Token[] = tokens.flatMap((b) => {
-    const priceData = tokenPriceMap.get(
-      toTokenPriceKey(
-        b.chainId,
-        isNativeToken(b) ? zeroAddress : b.contractAddress,
-      ),
-    )
-    const token = convertBalanceToTokenOrNull(b, priceData)
-    return token ? [token] : []
-  })
-
-  return {
-    balances: balancesWithPrices,
-  }
-}
-
-// ============================================================================
-// On-chain Balance Fetcher — bypasses the indexer entirely
-// ============================================================================
-
-export type FetchTokenBalanceOnchainParams = {
-  token: Token
-  accountAddress: string
-}
-
-export type FetchTokenBalanceOnchainWithPricesParams = {
-  token: Token
-  accountAddress: string
-  trailsClient: TrailsClient
-}
-
-export type FetchTokenBalanceOnchainReturn = {
-  token: Token
-}
-
-/**
- * Reads the on-chain balance for a single token via RPC.
- * Fast path — only a single RPC call, no price API.
- *
- * Returns a Token with fresh balance fields (balance, balanceFormatted,
- * balanceDisplay, balanceLocaleDisplay).
- */
-export async function fetchTokenBalanceOnchain({
-  token,
-  accountAddress,
-}: FetchTokenBalanceOnchainParams): Promise<FetchTokenBalanceOnchainReturn> {
-  const chainId = token.chainId
-  if (!chainId) {
-    throw new Error("Token must have a chainId")
-  }
-
-  const publicClient = getChainRpcClient(chainId)
-  const isNative = isNativeTokenAddress(token.contractAddress)
-
-  let rawBalance: bigint
-  if (isNative) {
-    rawBalance = await publicClient.getBalance({
-      address: accountAddress as `0x${string}`,
-    })
-  } else {
-    rawBalance = (await publicClient.readContract({
-      address: token.contractAddress as `0x${string}`,
-      abi: erc20Abi,
-      functionName: "balanceOf",
-      args: [accountAddress as `0x${string}`],
-    })) as bigint
-  }
-
-  const balanceFields = formatBalanceFields(
-    rawBalance.toString(),
-    token.decimals,
-  )
-
-  return {
-    token: {
-      ...token,
-      ...balanceFields,
-      isSufficientBalance: true,
-    },
-  }
-}
-
-/**
- * Reads the on-chain balance via RPC, then enriches it with price and USD
- * data from the Trails price API.
- *
- * Use this variant only when the caller needs balanceUsd / priceUsd fields.
- */
-export async function fetchTokenBalanceOnchainWithPrices({
-  token,
-  accountAddress,
-  trailsClient,
-}: FetchTokenBalanceOnchainWithPricesParams): Promise<FetchTokenBalanceOnchainReturn> {
-  const { token: tokenWithBalance } = await fetchTokenBalanceOnchain({
-    token,
-    accountAddress,
-  })
-
-  const chainId = token.chainId!
-  const isNative = isNativeTokenAddress(token.contractAddress)
-
-  let priceUsd: number | undefined
-  try {
-    const tokenPrices = await getTokenPrices(trailsClient, [
-      {
-        chainId,
-        tokenAddress: isNative ? zeroAddress : token.contractAddress,
-        tokenSymbol: isNative ? "" : token.symbol,
-      },
-    ])
-    if (tokenPrices.length > 0 && tokenPrices[0]?.priceUsd !== undefined) {
-      priceUsd = tokenPrices[0].priceUsd
-    }
-  } catch (err) {
-    logger.console.warn(
-      "[trails-sdk] Price fetch failed, returning balance without prices:",
-      err,
-    )
-  }
-
-  const priceFields = priceUsd !== undefined ? formatPriceFields(priceUsd) : {}
-
-  let usdFields: ReturnType<typeof formatUsdFields> = {}
-  if (priceUsd !== undefined && tokenWithBalance.balance) {
-    const balanceNum = rawAmountToNumber(
-      tokenWithBalance.balance,
-      token.decimals,
-    )
-    const balanceUsdValue = balanceNum * priceUsd
-    if (Number.isFinite(balanceUsdValue)) {
-      usdFields = formatUsdFields(balanceUsdValue)
-    }
-  }
-
-  return {
-    token: {
-      ...tokenWithBalance,
-      ...priceFields,
-      ...usdFields,
-    },
-  }
-}
-
-// ============================================================================
-// Pure Sufficiency Check
-// ============================================================================
-
-/**
- * Checks if a specific token has sufficient balance for a given amount.
- * Pure function — no queryClient, no React.
- */
-export function checkSufficientToken(
-  balances: Token[],
-  token: string,
-  amount: string,
-  chainId: number,
-): boolean {
-  const tb = balances.find(
-    (b) =>
-      (b.chainId ?? 0) === chainId &&
-      (addressEqual(b.contractAddress, token) ||
-        (!b.contractAddress && token === zeroAddress)),
-  )
-  if (!tb?.balance || tb.decimals == null) return false
-  try {
-    return BigInt(tb.balance) >= parseUnits(amount, tb.decimals)
-  } catch {
-    return false
-  }
-}