tapimo 0.4.3 → 0.5.0

package/src/internal/FundingQuotes.ts

@@ -0,0 +1,735 @@
+/** 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 considered by funding quote providers. */
+const sourceChains = [
+  {
+    addressFormat: 'evm',
+    aliases: ['ethereum', 'eth', 'eip155:1'],
+    id: 'eip155:1',
+    kind: 'evm',
+    name: 'Ethereum',
+    providerIds: {
+      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: {
+      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: {
+      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',
+      },
+    ],
+  },
+] as const
+
+/** Tempo destination tokens supported by funding quote providers. */
+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 supported by live funding quotes. */
+const providers = [
+  {
+    id: 'relay',
+    kind: 'solverNetwork',
+    name: 'Relay',
+    requiresApiKey: false,
+    status: 'unconfigured',
+  },
+] 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 funding quote requests. */
+export type ProviderId = ProviderInput['id']
+
+/** Provider-specific quote status for the requested amount. */
+export type QuoteStatus = 'available' | 'thin' | 'unknown' | 'unavailable'
+
+/** Machine-readable quote quality tier. */
+export type QualityTier = 'liquid' | 'thin' | 'unknown' | 'unavailable'
+
+/** 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 internal candidate passed to funding quote providers. */
+export type QuoteCandidate = ReturnType<typeof formatQuoteCandidate>
+
+/** A successful normalized funding quote returned to callers. */
+export type FundingQuote = ReturnType<typeof formatFundingQuote>
+
+/** Cache policy for a single funding quote 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
+  /** 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 curated quote candidate. */
+export type QuoteProbeInput = {
+  /** Cache policy for provider-side discovery and quote lookups. */
+  cache: CachePolicy
+  /** Destination chain, always Tempo mainnet in V1. */
+  destinationChain: ChainRef
+  /** Tempo token expected from this quote. */
+  destinationToken: TokenRef
+  /** Normalized caller request that produced this quote candidate. */
+  request: QuoteRequest
+  /** Curated candidate selected for live provider quoting. */
+  candidate: QuoteCandidate
+  /** 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
+}
+
+/** Quote probe data returned by a provider adapter. */
+export type QuoteProbeResult = {
+  /** Slippage-adjusted minimum destination amount in base units. */
+  minimumOutputAmount?: string | undefined
+  /** Expected destination amount in base units. */
+  outputAmount?: string | undefined
+  /** Expected destination amount rendered with destination token decimals. */
+  outputAmountFormatted?: string | undefined
+  /** Timestamp for the live quote probe. */
+  sampledAt: string
+  /** Provider-specific quote status for the requested amount. */
+  status: QuoteStatus
+  /** Provider-backed quote quality metadata. */
+  quality?: {
+    /** Estimated settlement time in seconds, when known. */
+    estimatedSeconds?: number | undefined
+    /** Where the live liquidity or support signal came from. */
+    liquiditySource: string
+    /** Provider-specific quote source or endpoint detail. */
+    sourceDetail?: string | undefined
+    /** Machine-readable quote quality tier. */
+    tier?: QualityTier | undefined
+  }
+}
+
+/** Adapter used to request a live provider quote. */
+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. */
+export type ProviderAdapters = Partial<Record<ProviderId, ProviderAdapter>>
+
+/** Curated provider support rows used to select live quote probes. */
+const inventory: readonly InventoryEntry[] = [
+  { destinationToken: 'usdce', provider: 'relay', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDC', 'USDT'] }, // prettier-ignore
+]
+
+type InventoryEntry = {
+  destinationToken: string
+  provider: ProviderInput['id']
+  sourceChains: readonly string[]
+  sourceTokens: readonly string[]
+}
+
+const defaultAdapterTimeoutMs = 2_000
+
+/** Lists normalized chains and source tokens supported by quote providers. */
+export function listChains() {
+  return sourceChains.flatMap((chain) => {
+    const symbols = new Set(
+      inventory
+        .filter((entry) => entry.sourceChains.includes(chain.slug))
+        .flatMap((entry) => entry.sourceTokens),
+    )
+    if (symbols.size === 0) return []
+    return [
+      {
+        ...formatChain(chain),
+        tokens: chain.tokens
+          .filter((token) => symbols.has(token.symbol))
+          .map((token) => formatSourceToken(chain, token)),
+      },
+    ]
+  })
+}
+
+/** Lists funding quote providers and their deployment status. */
+export function listProviders(options: listProviders.Options = {}) {
+  return providers.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
+  }
+}
+
+/** Returns successful live funding quotes from configured providers. */
+export async function listQuotes(options: listQuotes.Options) {
+  const candidates = listQuoteCandidates(options)
+  const results = await Promise.allSettled(
+    candidates.map((candidate) =>
+      quoteCandidate(candidate, {
+        adapters: options.adapters ?? {},
+        cache: options.cache ?? { bypass: false },
+        request: {
+          destinationToken: options.destinationToken,
+          provider: options.provider,
+          sourceAmount: options.sourceAmount,
+          sourceAmountUnits: options.sourceAmountUnits,
+          sourceChain: options.sourceChain,
+          sourceToken: options.sourceToken,
+        },
+        timeoutMs: options.adapterTimeoutMs ?? defaultAdapterTimeoutMs,
+      }),
+    ),
+  )
+  const quotes = results.flatMap((result) =>
+    result.status === 'fulfilled' && result.value ? [result.value] : [],
+  )
+  if (quotes.length === 0 && results.some((result) => result.status === 'rejected'))
+    throw new ProviderQuoteError()
+  return quotes
+}
+
+/** Lists internal quote candidates for a normalized caller request. */
+export function listQuoteCandidates(options: listQuoteCandidates.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)
+    .map((entry) =>
+      formatQuoteCandidate({
+        destinationToken,
+        provider: providers.find((candidate) => candidate.id === entry.provider)!,
+        sourceAmount,
+        sourceChain,
+        sourceToken,
+      }),
+    )
+}
+
+export declare namespace listQuoteCandidates {
+  /** Options for selecting funding quote candidates. */
+  type Options = {
+    /** Optional Tempo destination token symbol, address, or token key. */
+    destinationToken?: string | undefined
+    /** 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 listQuotes {
+  /** Options for requesting live funding quotes. */
+  type Options = listQuoteCandidates.Options & {
+    /** Provider adapters used to request live quotes. */
+    adapters?: ProviderAdapters | undefined
+    /** Per-provider quote timeout in milliseconds. */
+    adapterTimeoutMs?: number | undefined
+    /** Cache policy for provider-side discovery and quote lookups. */
+    cache?: CachePolicy | undefined
+  }
+}
+
+/** Source amount unit accepted by the funding quote request. */
+export type SourceAmountUnits = 'baseUnits' | 'decimal'
+
+function tokenKey(chain: { id: string }, token: TokenInput | DestinationTokenInput) {
+  return `${chain.id}/erc20:${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 quoteCandidate(
+  candidate: QuoteCandidate,
+  options: {
+    adapters: ProviderAdapters
+    cache: CachePolicy
+    request: QuoteRequest
+    timeoutMs: number
+  },
+) {
+  const adapter = options.adapters[candidate.provider.id as ProviderId]
+  if (!adapter) return undefined
+
+  const quote = await runWithTimeout(
+    (signal) =>
+      adapter.probeQuote(
+        {
+          cache: options.cache,
+          destinationChain: candidate.destinationChain,
+          destinationToken: candidate.destinationToken,
+          request: options.request,
+          candidate,
+          sourceAmount: candidate.sourceAmount,
+          sourceChain: candidate.sourceChain,
+          sourceToken: candidate.sourceToken,
+        },
+        signal,
+      ),
+    options.timeoutMs,
+  )
+  if (quote.status === 'unavailable') return undefined
+  if (
+    (quote.status !== 'available' && quote.status !== 'thin') ||
+    quote.outputAmount === undefined ||
+    quote.outputAmount === null
+  )
+    throw new ProviderQuoteError()
+  return formatFundingQuote(candidate, {
+    ...quote,
+    outputAmount: quote.outputAmount,
+    status: quote.status,
+  })
+}
+
+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 { id, kind, name, requiresApiKey, status }
+}
+
+function formatProviderRef(provider: ProviderInput) {
+  const { id, kind, name, requiresApiKey } = provider
+  return { id, kind, name, requiresApiKey }
+}
+
+function formatQuoteCandidate(options: {
+  destinationToken: DestinationTokenInput
+  provider: ProviderInput
+  sourceAmount: ReturnType<typeof resolveSourceAmount>
+  sourceChain: SourceChainInput
+  sourceToken: TokenInput
+}) {
+  return {
+    destinationChain,
+    destinationToken: formatDestinationToken(options.destinationToken),
+    id: [
+      options.sourceChain.slug,
+      options.sourceToken.symbol.toLowerCase(),
+      'tempo',
+      options.destinationToken.slug,
+      options.provider.id,
+    ].join('-'),
+    provider: formatProviderRef(options.provider),
+    sourceAmount: options.sourceAmount,
+    sourceChain: formatChain(options.sourceChain),
+    sourceToken: formatSourceToken(options.sourceChain, options.sourceToken),
+  } 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()
+}
+
+type SuccessfulQuoteProbe = QuoteProbeResult & {
+  outputAmount: string
+  status: 'available' | 'thin'
+}
+
+function formatFundingQuote(candidate: QuoteCandidate, quote: SuccessfulQuoteProbe) {
+  return {
+    ...candidate,
+    quality: {
+      ...(quote.quality?.estimatedSeconds !== undefined
+        ? { estimatedSeconds: quote.quality.estimatedSeconds }
+        : {}),
+      liquiditySource: quote.quality?.liquiditySource ?? 'providerQuote',
+      ...(quote.quality?.sourceDetail !== undefined
+        ? { sourceDetail: quote.quality.sourceDetail }
+        : {}),
+      tier: quote.status === 'thin' ? ('thin' as const) : ('liquid' as const),
+    },
+    quote: {
+      inputAmount: candidate.sourceAmount.amount,
+      ...(quote.minimumOutputAmount !== undefined
+        ? { minimumOutputAmount: quote.minimumOutputAmount }
+        : {}),
+      outputAmount: quote.outputAmount,
+      outputAmountFormatted:
+        quote.outputAmountFormatted ??
+        decimalFromBaseUnits(quote.outputAmount, candidate.destinationToken.decimals),
+      sampledAt: quote.sampledAt,
+    },
+  } as const
+}
+
+function runWithTimeout<result>(fn: (signal: AbortSignal) => Promise<result>, timeoutMs: number) {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), timeoutMs)
+  return Promise.race([
+    fn(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),
+  }
+}
+
+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 = 'FundingQuotes.UnsupportedDestinationTokenError'
+}
+
+/** Error thrown when the caller supplies an invalid source amount. */
+export class InvalidAmountError extends Error {
+  override name = 'FundingQuotes.InvalidAmountError'
+}
+
+/** Error thrown internally when a provider adapter exceeds its quote timeout. */
+export class ProviderAdapterTimeoutError extends Error {
+  override name = 'FundingQuotes.ProviderAdapterTimeoutError'
+}
+
+/** Error thrown when every matching provider fails to produce a quote. */
+export class ProviderQuoteError extends Error {
+  override name = 'FundingQuotes.ProviderQuoteError'
+}
+
+/** Error thrown when the caller filters to an unknown provider. */
+export class UnsupportedProviderError extends Error {
+  override name = 'FundingQuotes.UnsupportedProviderError'
+}
+
+/** Error thrown when the caller supplies an unsupported source chain. */
+export class UnsupportedSourceChainError extends Error {
+  override name = 'FundingQuotes.UnsupportedSourceChainError'
+}