tapimo 0.2.0 → 0.4.0

package/src/internal/FundingRoutes.ts

@@ -0,0 +1,898 @@
+/** Tempo mainnet as a CAIP-2 chain reference. */
+const destinationChain = {
+  addressFormat: 'evm',
+  id: 'eip155:4217',
+  kind: 'evm',
+  name: 'Tempo',
+} as const
+
+/** Tempo token used when the caller omits `destinationToken`. */
+const defaultDestinationToken = 'usdce'
+
+/** Source chains accepted by the funding route inventory. */
+const sourceChains = [
+  {
+    addressFormat: 'evm',
+    aliases: ['ethereum', 'eth', 'eip155:1'],
+    id: 'eip155:1',
+    kind: 'evm',
+    name: 'Ethereum',
+    providerIds: {
+      across: '1',
+      bridge: 'ethereum',
+      bungee: '1',
+      lifi: '1',
+      relay: '1',
+    },
+    slug: 'ethereum',
+    tokens: [
+      {
+        address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+        coingeckoId: 'usd-coin',
+        decimals: 6,
+        name: 'USD Coin',
+        standard: 'ERC-20',
+        symbol: 'USDC',
+      },
+      {
+        address: '0xdac17f958d2ee523a2206206994597c13d831ec7',
+        coingeckoId: 'tether',
+        decimals: 6,
+        name: 'Tether USD',
+        standard: 'ERC-20',
+        symbol: 'USDT',
+      },
+      {
+        address: '0x6c3ea9036406852006290770bedfcaba0e23a0e8',
+        coingeckoId: 'paypal-usd',
+        decimals: 6,
+        name: 'PayPal USD',
+        standard: 'ERC-20',
+        symbol: 'PYUSD',
+      },
+      {
+        address: '0x1abaea1f7c830bd89acc67ec4af516284b1bc33c',
+        coingeckoId: 'euro-coin',
+        decimals: 6,
+        name: 'Euro Coin',
+        standard: 'ERC-20',
+        symbol: 'EURC',
+      },
+      {
+        address: '0x6b175474e89094c44da98b954eedeac495271d0f',
+        coingeckoId: 'dai',
+        decimals: 18,
+        name: 'Dai Stablecoin',
+        standard: 'ERC-20',
+        symbol: 'DAI',
+      },
+    ],
+  },
+  {
+    addressFormat: 'evm',
+    aliases: ['base', 'eip155:8453'],
+    id: 'eip155:8453',
+    kind: 'evm',
+    name: 'Base',
+    providerIds: {
+      across: '8453',
+      bridge: 'base',
+      bungee: '8453',
+      lifi: '8453',
+      relay: '8453',
+    },
+    slug: 'base',
+    tokens: [
+      {
+        address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+        coingeckoId: 'usd-coin',
+        decimals: 6,
+        name: 'USD Coin',
+        standard: 'ERC-20',
+        symbol: 'USDC',
+      },
+      {
+        address: '0xfde4c96c8593536e31f229ea8f37b2ada2699bb2',
+        coingeckoId: 'tether',
+        decimals: 6,
+        name: 'Tether USD',
+        standard: 'ERC-20',
+        symbol: 'USDT',
+      },
+      {
+        address: '0x60a3e35cc302bfa44cb288bc5a4f316fdb1adb42',
+        coingeckoId: 'euro-coin',
+        decimals: 6,
+        name: 'Euro Coin',
+        standard: 'ERC-20',
+        symbol: 'EURC',
+      },
+    ],
+  },
+  {
+    addressFormat: 'evm',
+    aliases: ['bnb', 'bsc', 'eip155:56'],
+    id: 'eip155:56',
+    kind: 'evm',
+    name: 'BNB Smart Chain',
+    providerIds: {
+      across: '56',
+      bungee: '56',
+      lifi: '56',
+      relay: '56',
+    },
+    slug: 'bnb',
+    tokens: [
+      {
+        address: '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d',
+        coingeckoId: 'usd-coin',
+        decimals: 18,
+        name: 'Binance-Peg USD Coin',
+        standard: 'BEP-20',
+        symbol: 'USDC',
+      },
+      {
+        address: '0x55d398326f99059ff775485246999027b3197955',
+        coingeckoId: 'tether',
+        decimals: 18,
+        name: 'Tether USD',
+        standard: 'BEP-20',
+        symbol: 'USDT',
+      },
+    ],
+  },
+  {
+    addressFormat: 'solana',
+    aliases: ['solana', 'solana:mainnet'],
+    id: 'solana:mainnet',
+    kind: 'solana',
+    name: 'Solana',
+    providerIds: {
+      bridge: 'solana',
+      relay: 'solana',
+    },
+    slug: 'solana',
+    tokens: [
+      {
+        address: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+        coingeckoId: 'usd-coin',
+        decimals: 6,
+        name: 'USD Coin',
+        standard: 'SPL',
+        symbol: 'USDC',
+      },
+      {
+        address: 'Es9vMFrzaCERmJfrF4H2FYD4KCo3LwC1uix9YEaQ8t1v',
+        coingeckoId: 'tether',
+        decimals: 6,
+        name: 'Tether USD',
+        standard: 'SPL',
+        symbol: 'USDT',
+      },
+    ],
+  },
+  {
+    addressFormat: 'tron',
+    aliases: ['tron', 'tron:mainnet'],
+    id: 'tron:mainnet',
+    kind: 'tron',
+    name: 'Tron',
+    providerIds: {
+      bridge: 'tron',
+      relay: 'tron',
+    },
+    slug: 'tron',
+    tokens: [
+      {
+        address: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+        coingeckoId: 'tether',
+        decimals: 6,
+        name: 'Tether USD',
+        standard: 'TRC-20',
+        symbol: 'USDT',
+      },
+    ],
+  },
+] as const
+
+/** Tempo destination tokens supported by the initial funding route inventory. */
+const destinationTokens = [
+  {
+    address: '0x20c0000000000000000000000000000000000000',
+    decimals: 6,
+    name: 'pathUSD',
+    slug: 'pathusd',
+    standard: 'TIP-20',
+    symbol: 'pathUSD',
+  },
+  {
+    address: '0x20c000000000000000000000b9537d11c60e8b50',
+    decimals: 6,
+    name: 'Bridged USDC (Stargate)',
+    slug: 'usdce',
+    standard: 'TIP-20',
+    symbol: 'USDC.e',
+  },
+  {
+    address: '0x20c0000000000000000000001621e21f71cf12fb',
+    decimals: 6,
+    name: 'Bridged EURC',
+    slug: 'eurce',
+    standard: 'TIP-20',
+    symbol: 'EURC.e',
+  },
+  {
+    address: '0x20c00000000000000000000014f22ca97301eb73',
+    decimals: 6,
+    name: 'USDT0',
+    slug: 'usdt0',
+    standard: 'TIP-20',
+    symbol: 'USDT0',
+  },
+  {
+    address: '0x20c0000000000000000000003554d28269e0f3c2',
+    decimals: 6,
+    name: 'frxUSD',
+    slug: 'frxusd',
+    standard: 'TIP-20',
+    symbol: 'frxUSD',
+  },
+] as const
+
+/** Providers exposed by the generic provider catalog. */
+const providers = [
+  {
+    capabilities: ['fundingRoutes'],
+    id: 'across',
+    kind: 'intentBridge',
+    name: 'Across',
+    requiresApiKey: true,
+    status: 'inventoryOnly',
+  },
+  {
+    capabilities: ['fundingRoutes'],
+    id: 'relay',
+    kind: 'solverNetwork',
+    name: 'Relay',
+    requiresApiKey: false,
+    status: 'inventoryOnly',
+  },
+  {
+    capabilities: ['fundingRoutes'],
+    id: 'bridge',
+    kind: 'enterpriseTransfer',
+    name: 'Bridge.xyz',
+    requiresApiKey: true,
+    status: 'inventoryOnly',
+  },
+  {
+    capabilities: ['fundingRoutes'],
+    id: 'bungee',
+    kind: 'aggregator',
+    name: 'Bungee',
+    requiresApiKey: false,
+    status: 'inventoryOnly',
+  },
+  {
+    capabilities: ['fundingRoutes'],
+    id: 'lifi',
+    kind: 'aggregator',
+    name: 'LI.FI',
+    requiresApiKey: true,
+    status: 'planned',
+  },
+] as const
+
+type TokenInput = (typeof sourceChains)[number]['tokens'][number]
+type DestinationTokenInput = (typeof destinationTokens)[number]
+type ProviderInput = (typeof providers)[number]
+type SourceChainInput = (typeof sourceChains)[number]
+
+/** Provider ids accepted by the funding route inventory. */
+export type ProviderId = ProviderInput['id']
+
+/** Provider-specific route status for the requested amount. */
+export type RouteStatus = 'available' | 'thin' | 'unknown' | 'unavailable' | 'error'
+
+/** Machine-readable route quality tier. */
+export type QualityTier = 'liquid' | 'thin' | 'unknown' | 'unavailable' | 'error'
+
+/** Response expansions accepted by funding route discovery. */
+export type Include = 'quotes'
+
+/** Normalized chain reference passed to provider adapters. */
+export type ChainRef = ReturnType<typeof formatChain> | typeof destinationChain
+
+/** Normalized token amount passed to provider adapters. */
+export type TokenAmount = ReturnType<typeof resolveSourceAmount>
+
+/** Normalized token reference passed to provider adapters. */
+export type TokenRef = ReturnType<typeof formatDestinationToken> | ReturnType<typeof formatSourceToken>
+
+/** A normalized funding route candidate returned by route discovery. */
+export type RouteCandidate = ReturnType<typeof formatRouteCandidate>
+
+/** Cache policy for a single funding route discovery request. */
+export type CachePolicy = {
+  /** Whether provider adapters should bypass their own quote or inventory caches. */
+  bypass: boolean
+}
+
+/** Normalized caller request passed to provider adapters. */
+export type QuoteRequest = {
+  /** Optional Tempo destination token symbol, address, or token key. */
+  destinationToken?: string | undefined
+  /** Response expansions requested by the caller. */
+  include: readonly Include[]
+  /** Maximum number of route candidates requested by the caller. */
+  limit: number
+  /** Optional provider id filter. */
+  provider?: string | undefined
+  /** Source amount as supplied by the caller. */
+  sourceAmount: string
+  /** Unit used by {@link sourceAmount}. */
+  sourceAmountUnits: SourceAmountUnits
+  /** Chain alias or CAIP-2 source chain id. */
+  sourceChain: string
+  /** Source token symbol, contract address, mint, or Tempo token key. */
+  sourceToken: string
+}
+
+/** Input passed to a provider adapter for one static route candidate probe. */
+export type QuoteProbeInput = {
+  /** Cache policy for provider-side inventory, quote, and liquidity lookups. */
+  cache: CachePolicy
+  /** Destination chain, always Tempo mainnet in V1. */
+  destinationChain: ChainRef
+  /** Tempo token expected from this route. */
+  destinationToken: TokenRef
+  /** Response expansions requested by the caller. */
+  include: readonly Include[]
+  /** Normalized caller request that produced this route candidate. */
+  request: QuoteRequest
+  /** Static candidate being enriched with live provider information. */
+  route: RouteCandidate
+  /** Source amount in base units and display form. */
+  sourceAmount: TokenAmount
+  /** Chain where the caller currently holds funds. */
+  sourceChain: ChainRef
+  /** Token the caller currently holds. */
+  sourceToken: TokenRef
+}
+
+/** Provider-specific source amount limits, expressed in source base units. */
+export type QuoteProbeLimits = {
+  /** Provider-reported instant source amount capacity. */
+  instantSourceAmount?: string | null | undefined
+  /** Provider-reported maximum source amount. */
+  maxSourceAmount?: string | null | undefined
+  /** Provider-reported minimum source amount. */
+  minSourceAmount?: string | null | undefined
+}
+
+/** Quote probe data returned by a provider adapter. */
+export type QuoteProbeResult = {
+  /** Stable route error code when status is `error`. */
+  errorCode?: string | null | undefined
+  /** Provider quote expiry timestamp. */
+  expiresAt?: string | null | undefined
+  /** Provider-reported source amount limits. */
+  limits?: QuoteProbeLimits | null | undefined
+  /** Slippage-adjusted minimum destination amount in base units. */
+  minimumOutputAmount?: string | null | undefined
+  /** Expected destination amount in base units. */
+  outputAmount?: string | null | undefined
+  /** Expected destination amount rendered with destination token decimals. */
+  outputAmountFormatted?: string | null | undefined
+  /** Timestamp for the live quote or route probe. */
+  sampledAt: string
+  /** Provider-specific route status for the requested amount. */
+  status: RouteStatus
+  /** Provider-backed route quality metadata. */
+  quality?: {
+    /** Available USD capacity, when available. */
+    availableVolumeUsd?: string | null | undefined
+    /** Estimated settlement time in seconds, when known. */
+    estimatedSeconds?: number | null | undefined
+    /** Estimated fee in basis points, when known. */
+    feeBps?: number | null | undefined
+    /** 24h routed volume in USD, when available. */
+    historicalVolumeUsd24h?: string | null | undefined
+    /** Instant USD capacity, when available. */
+    instantVolumeUsd?: string | null | undefined
+    /** Where the live liquidity or support signal came from. */
+    liquiditySource: string
+    /** Explainable route score from 0 to 100, when enough signals are available. */
+    score?: number | null | undefined
+    /** Provider-specific quote source or endpoint detail. */
+    sourceDetail?: string | null | undefined
+    /** Machine-readable route quality tier. */
+    tier?: QualityTier | undefined
+  }
+}
+
+/** Adapter used to enrich a static route candidate with live provider information. */
+export type ProviderAdapter = {
+  /** Probes provider-backed quote information for one static candidate. */
+  probeQuote(input: QuoteProbeInput, signal: AbortSignal): Promise<QuoteProbeResult>
+}
+
+/** Provider adapter registry, keyed by provider id. Missing adapters leave routes static. */
+export type ProviderAdapters = Partial<Record<ProviderId, ProviderAdapter>>
+
+/** Static provider support rows used until live quote adapters are configured. */
+const inventory: readonly InventoryEntry[] = [
+  { destinationToken: 'usdce', provider: 'across', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDC'] }, // prettier-ignore
+  { destinationToken: 'usdce', provider: 'relay', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDC', 'USDT'] }, // prettier-ignore
+  { destinationToken: 'usdce', provider: 'bridge', sourceChains: ['ethereum', 'base', 'solana'], sourceTokens: ['USDC'] }, // prettier-ignore
+  { destinationToken: 'usdce', provider: 'bridge', sourceChains: ['ethereum', 'solana', 'tron'], sourceTokens: ['USDT'] }, // prettier-ignore
+  { destinationToken: 'usdce', provider: 'bungee', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDC'] }, // prettier-ignore
+]
+
+type InventoryEntry = {
+  destinationToken: string
+  provider: ProviderInput['id']
+  sourceChains: readonly string[]
+  sourceTokens: readonly string[]
+}
+
+const defaultAdapterTimeoutMs = 750
+const includes = ['quotes'] as const
+
+/** Lists normalized chains and source tokens that can fund Tempo. */
+export function listChains() {
+  return sourceChains.map((chain) => ({
+    ...formatChain(chain),
+    tokens: chain.tokens.map((token) => formatSourceToken(chain, token)),
+  }))
+}
+
+/** Lists providers, optionally filtered by one provider capability. */
+export function listProviders(options: listProviders.Options = {}) {
+  return providers
+    .filter((provider) =>
+      options.capability === undefined ? true : provider.capabilities.includes(options.capability),
+    )
+    .map((provider) => ({
+      ...formatProvider(provider),
+      status: options.adapters?.[provider.id] ? ('configured' as const) : provider.status,
+    }))
+}
+
+export declare namespace listProviders {
+  /** Options for listing providers. */
+  type Options = {
+    /** Provider adapters configured for this deployment. */
+    adapters?: ProviderAdapters | undefined
+    /** Provider capability to require. */
+    capability?: Capability | undefined
+  }
+}
+
+/** Parses the comma-separated `include` query parameter. */
+export function parseInclude(input: string | undefined) {
+  if (input === undefined || input.trim() === '') return []
+  const parsed = input.split(',').map((part) => part.trim()).filter(Boolean)
+  for (const include of parsed)
+    if (!(includes as readonly string[]).includes(include)) throw new UnsupportedIncludeError()
+  return [...new Set(parsed)] as readonly Include[]
+}
+
+/** Lists funding route candidates, enriching static inventory when adapters are configured. */
+export async function listRoutes(options: listRoutes.Options) {
+  const routes = listStaticRoutes(options)
+  const adapterEntries = Object.entries(options.adapters ?? {})
+  if (adapterEntries.length === 0) return routes
+
+  return Promise.all(
+    routes.map((route) =>
+      enrichRoute(route, {
+        adapters: options.adapters ?? {},
+        cache: options.cache ?? { bypass: false },
+        include: options.include ?? [],
+        request: {
+          destinationToken: options.destinationToken,
+          include: options.include ?? [],
+          limit: options.limit,
+          provider: options.provider,
+          sourceAmount: options.sourceAmount,
+          sourceAmountUnits: options.sourceAmountUnits,
+          sourceChain: options.sourceChain,
+          sourceToken: options.sourceToken,
+        },
+        timeoutMs: options.adapterTimeoutMs ?? defaultAdapterTimeoutMs,
+      }),
+    ),
+  )
+}
+
+/** Lists static funding route candidates for a normalized caller request. */
+export function listStaticRoutes(options: listStaticRoutes.Options) {
+  const sourceChain = resolveSourceChain(options.sourceChain)
+  const sourceToken = resolveSourceToken(sourceChain, options.sourceToken)
+  const destinationToken = resolveDestinationToken(options.destinationToken)
+  const provider = options.provider ? resolveProvider(options.provider) : undefined
+
+  if (!sourceToken) {
+    validateSourceAmountSyntax(options.sourceAmount, options.sourceAmountUnits)
+    return []
+  }
+
+  const sourceAmount = resolveSourceAmount({
+    amount: options.sourceAmount,
+    token: sourceToken,
+    units: options.sourceAmountUnits,
+  })
+
+  return inventory
+    .filter((entry) => entry.sourceChains.includes(sourceChain.slug))
+    .filter((entry) => entry.sourceTokens.includes(sourceToken.symbol))
+    .filter((entry) => entry.destinationToken === destinationToken.slug)
+    .filter((entry) => provider === undefined || entry.provider === provider.id)
+    .slice(0, options.limit)
+    .map((entry) =>
+      formatRouteCandidate({
+        destinationToken,
+        provider: providers.find((candidate) => candidate.id === entry.provider)!,
+        sourceAmount,
+        sourceChain,
+        sourceToken,
+      }),
+    )
+}
+
+export declare namespace listStaticRoutes {
+  /** Options for listing static funding routes. */
+  type Options = {
+    /** Optional Tempo destination token symbol, address, or token key. */
+    destinationToken?: string | undefined
+    /** Maximum number of route candidates to return. */
+    limit: number
+    /** Optional provider id filter. */
+    provider?: string | undefined
+    /** Source amount as supplied by the caller. */
+    sourceAmount: string
+    /** Unit used by {@link sourceAmount}. */
+    sourceAmountUnits: SourceAmountUnits
+    /** Chain alias or CAIP-2 source chain id. */
+    sourceChain: string
+    /** Source token symbol, contract address, mint, or Tempo token key. */
+    sourceToken: string
+  }
+}
+
+export declare namespace listRoutes {
+  /** Options for listing funding routes. */
+  type Options = listStaticRoutes.Options & {
+    /** Provider adapters used to enrich static inventory with live data. */
+    adapters?: ProviderAdapters | undefined
+    /** Per-provider quote timeout in milliseconds. */
+    adapterTimeoutMs?: number | undefined
+    /** Cache policy for provider-side inventory, quote, and liquidity lookups. */
+    cache?: CachePolicy | undefined
+    /** Response expansions requested by the caller. */
+    include?: readonly Include[] | undefined
+  }
+}
+
+/** Provider capability identifiers accepted by the generic provider catalog. */
+export type Capability = 'fundingRoutes'
+
+/** Source amount unit accepted by the funding route request. */
+export type SourceAmountUnits = 'baseUnits' | 'decimal'
+
+function tokenKey(chain: { id: string }, token: TokenInput | DestinationTokenInput) {
+  const standard =
+    token.standard === 'SPL' ? 'spl' : token.standard === 'TRC-20' ? 'trc20' : 'erc20'
+  return `${chain.id}/${standard}:${token.address}`
+}
+
+function decimalFromBaseUnits(baseUnits: string, decimals: number) {
+  const padded = baseUnits.padStart(decimals + 1, '0')
+  const whole = decimals === 0 ? padded : padded.slice(0, -decimals)
+  const fraction = decimals === 0 ? '' : padded.slice(-decimals).replace(/0+$/, '')
+  return fraction ? `${whole}.${fraction}` : whole
+}
+
+async function enrichRoute(
+  route: RouteCandidate,
+  options: {
+    adapters: ProviderAdapters
+    cache: CachePolicy
+    include: readonly Include[]
+    request: QuoteRequest
+    timeoutMs: number
+  },
+) {
+  const adapter = options.adapters[route.provider.id as ProviderId]
+  if (!adapter) return route
+
+  try {
+    const quote = await quoteWithTimeout(
+      adapter,
+      {
+        cache: options.cache,
+        destinationChain: route.destinationChain,
+        destinationToken: route.destinationToken,
+        include: options.include,
+        request: options.request,
+        route,
+        sourceAmount: route.sourceAmount,
+        sourceChain: route.sourceChain,
+        sourceToken: route.sourceToken,
+      },
+      options.timeoutMs,
+    )
+    return {
+      ...route,
+      errorCode: quote.errorCode ?? null,
+      quality: {
+        ...route.quality,
+        ...(quote.status === 'error' ? { tier: 'error' as const } : {}),
+        ...quote.quality,
+      },
+      quote: quote.status === 'error' ? null : formatRouteQuote(route, quote),
+      status: quote.status,
+    }
+  } catch (cause) {
+    return markRouteError(route, cause instanceof ProviderAdapterTimeoutError ? 'provider_timeout' : 'provider_error') // prettier-ignore
+  }
+}
+
+function formatChain(chain: SourceChainInput) {
+  const { addressFormat, id, kind, name, providerIds } = chain
+  return { addressFormat, id, kind, name, providerIds }
+}
+
+function formatDestinationToken(token: DestinationTokenInput) {
+  return {
+    address: token.address,
+    decimals: token.decimals,
+    metadata: {},
+    name: token.name,
+    standard: token.standard,
+    symbol: token.symbol,
+    tokenKey: tokenKey(destinationChain, token),
+    verified: true,
+  }
+}
+
+function formatProvider(provider: ProviderInput) {
+  const { id, kind, name, requiresApiKey, status } = provider
+  return { capabilities: [...provider.capabilities], id, kind, name, requiresApiKey, status }
+}
+
+function formatProviderRef(provider: ProviderInput) {
+  const { id, kind, name, requiresApiKey } = provider
+  return { id, kind, name, requiresApiKey }
+}
+
+function formatRouteCandidate(options: {
+  destinationToken: DestinationTokenInput
+  provider: ProviderInput
+  sourceAmount: ReturnType<typeof resolveSourceAmount>
+  sourceChain: SourceChainInput
+  sourceToken: TokenInput
+}) {
+  return {
+    destinationChain,
+    destinationToken: formatDestinationToken(options.destinationToken),
+    errorCode: null,
+    id: [
+      options.sourceChain.slug,
+      options.sourceToken.symbol.toLowerCase(),
+      'tempo',
+      options.destinationToken.slug,
+      options.provider.id,
+    ].join('-'),
+    provider: formatProviderRef(options.provider),
+    quality: {
+      availableVolumeUsd: null,
+      estimatedSeconds: null,
+      feeBps: null,
+      historicalVolumeUsd24h: null,
+      instantVolumeUsd: null,
+      liquiditySource: 'staticInventory',
+      score: null,
+      sourceDetail: null,
+      tier: 'unknown',
+    },
+    quote: null,
+    sourceAmount: options.sourceAmount,
+    sourceChain: formatChain(options.sourceChain),
+    sourceToken: formatSourceToken(options.sourceChain, options.sourceToken),
+    status: 'unknown',
+  } as const
+}
+
+function formatSourceToken(chain: SourceChainInput, token: TokenInput) {
+  return {
+    address: token.address,
+    decimals: token.decimals,
+    metadata: { coingeckoId: token.coingeckoId },
+    name: token.name,
+    standard: token.standard,
+    symbol: token.symbol,
+    tokenKey: tokenKey(chain, token),
+    verified: true,
+  }
+}
+
+function normalizeInput(value: string) {
+  return value.trim().toLowerCase()
+}
+
+function parseBaseUnits(value: string) {
+  if (!/^\d+$/.test(value) || BigInt(value) <= 0n) throw new InvalidAmountError()
+  return BigInt(value).toString()
+}
+
+function parseDecimalUnits(value: string, decimals: number) {
+  if (!/^\d+(\.\d+)?$/.test(value)) throw new InvalidAmountError()
+  const [whole, fraction = ''] = value.split('.')
+  if (fraction.length > decimals) throw new InvalidAmountError()
+  const baseUnits = BigInt(`${whole}${fraction.padEnd(decimals, '0')}`)
+  if (baseUnits <= 0n) throw new InvalidAmountError()
+  return baseUnits.toString()
+}
+
+function formatRouteQuote(route: RouteCandidate, quote: QuoteProbeResult) {
+  return {
+    expiresAt: quote.expiresAt ?? null,
+    inputAmount: route.sourceAmount.amount,
+    limits: quote.limits
+      ? {
+          instantSourceAmount: quote.limits.instantSourceAmount ?? null,
+          maxSourceAmount: quote.limits.maxSourceAmount ?? null,
+          minSourceAmount: quote.limits.minSourceAmount ?? null,
+        }
+      : null,
+    minimumOutputAmount: quote.minimumOutputAmount ?? null,
+    outputAmount: quote.outputAmount ?? null,
+    outputAmountFormatted: quote.outputAmountFormatted ?? null,
+    sampledAt: quote.sampledAt,
+  } as const
+}
+
+function markRouteError(route: RouteCandidate, errorCode: string) {
+  return {
+    ...route,
+    errorCode,
+    quality: {
+      ...route.quality,
+      liquiditySource: 'providerError',
+      score: null,
+      sourceDetail: null,
+      tier: 'error' as const,
+    },
+    quote: null,
+    status: 'error' as const,
+  }
+}
+
+function quoteWithTimeout(adapter: ProviderAdapter, input: QuoteProbeInput, timeoutMs: number) {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), timeoutMs)
+  return Promise.race([
+    adapter.probeQuote(input, controller.signal),
+    new Promise<never>((_, reject) => {
+      if (controller.signal.aborted) {
+        reject(new ProviderAdapterTimeoutError())
+        return
+      }
+      controller.signal.addEventListener('abort', () => reject(new ProviderAdapterTimeoutError()), {
+        once: true,
+      })
+    }),
+  ]).finally(() => clearTimeout(timeout))
+}
+
+function resolveDestinationToken(input: string | undefined) {
+  if (input === undefined) return destinationTokens.find((token) => token.slug === defaultDestinationToken)! // prettier-ignore
+  const normalized = normalizeInput(input)
+  const token = destinationTokens.find(
+    (candidate) =>
+      candidate.slug === normalized ||
+      candidate.symbol.toLowerCase() === normalized ||
+      candidate.address === normalized ||
+      tokenKey(destinationChain, candidate).toLowerCase() === normalized,
+  )
+  if (!token) throw new UnsupportedDestinationTokenError()
+  return token
+}
+
+function resolveProvider(input: string) {
+  const provider = providers.find((candidate) => candidate.id === normalizeInput(input))
+  if (!provider) throw new UnsupportedProviderError()
+  return provider
+}
+
+function resolveSourceAmount(options: resolveSourceAmount.Options) {
+  const amount =
+    options.units === 'baseUnits'
+      ? parseBaseUnits(options.amount)
+      : parseDecimalUnits(options.amount, options.token.decimals)
+  return {
+    amount,
+    formatted: decimalFromBaseUnits(amount, options.token.decimals),
+    usd: null,
+  }
+}
+
+declare namespace resolveSourceAmount {
+  type Options = {
+    amount: string
+    token: TokenInput
+    units: SourceAmountUnits
+  }
+}
+
+function resolveSourceToken(chain: SourceChainInput, input: string) {
+  const trimmed = input.trim()
+  const normalized = trimmed.toLowerCase()
+  return chain.tokens.find(
+    (token) =>
+      token.symbol.toLowerCase() === normalized ||
+      matchesTokenIdentifier(chain, token.address, trimmed, normalized) ||
+      matchesTokenIdentifier(chain, tokenKey(chain, token), trimmed, normalized),
+  )
+}
+
+function matchesTokenIdentifier(
+  chain: SourceChainInput,
+  candidate: string,
+  trimmed: string,
+  normalized: string,
+) {
+  return chain.kind === 'evm' ? candidate.toLowerCase() === normalized : candidate === trimmed
+}
+
+function resolveSourceChain(input: string) {
+  const normalized = normalizeInput(input)
+  const chain = sourceChains.find(
+    (candidate) =>
+      candidate.id === normalized || (candidate.aliases as readonly string[]).includes(normalized),
+  )
+  if (!chain) throw new UnsupportedSourceChainError()
+  return chain
+}
+
+function validateSourceAmountSyntax(value: string, units: SourceAmountUnits) {
+  if (units === 'baseUnits') {
+    parseBaseUnits(value)
+    return
+  }
+  if (!/^\d+(\.\d+)?$/.test(value)) throw new InvalidAmountError()
+  const [whole, fraction = ''] = value.split('.')
+  if (BigInt(`${whole}${fraction}`) <= 0n) throw new InvalidAmountError()
+}
+
+/** Error thrown when the caller supplies an unsupported destination token. */
+export class UnsupportedDestinationTokenError extends Error {
+  override name = 'FundingRoutes.UnsupportedDestinationTokenError'
+}
+
+/** Error thrown when the caller supplies an invalid source amount. */
+export class InvalidAmountError extends Error {
+  override name = 'FundingRoutes.InvalidAmountError'
+}
+
+/** Error thrown internally when a provider adapter exceeds its route quote timeout. */
+export class ProviderAdapterTimeoutError extends Error {
+  override name = 'FundingRoutes.ProviderAdapterTimeoutError'
+}
+
+/** Error thrown when the caller filters to an unknown provider. */
+export class UnsupportedProviderError extends Error {
+  override name = 'FundingRoutes.UnsupportedProviderError'
+}
+
+/** Error thrown when the caller requests an unsupported include expansion. */
+export class UnsupportedIncludeError extends Error {
+  override name = 'FundingRoutes.UnsupportedIncludeError'
+}
+
+/** Error thrown when the caller supplies an unsupported source chain. */
+export class UnsupportedSourceChainError extends Error {
+  override name = 'FundingRoutes.UnsupportedSourceChainError'
+}