tapimo 0.2.0 → 0.4.0

package/src/apps/data/FundingRouteProviders.ts

@@ -0,0 +1,459 @@
+import type * as FundingRoutes from '../../internal/FundingRoutes.js'
+
+type Fetch = typeof globalThis.fetch
+
+const defaultAcrossBaseUrl = 'https://app.across.to/api'
+const defaultRelayBaseUrl = 'https://api.relay.link'
+
+/** Creates the live funding route adapters configured for this deployment. */
+export function createAdapters(options: createAdapters.Options = {}) {
+  return {
+    ...(options.across ? { across: across(options.across) } : {}),
+    ...(options.relay ? { relay: relay(options.relay) } : {}),
+  } satisfies FundingRoutes.ProviderAdapters
+}
+
+export declare namespace createAdapters {
+  /** Provider adapter factory options. Omit a provider to keep its routes static. */
+  type Options = {
+    /** Across quote adapter options. */
+    across?: across.Options | false | undefined
+    /** Relay quote adapter options. */
+    relay?: relay.Options | false | undefined
+  }
+}
+
+/** Creates an Across quote adapter backed by `/suggested-fees`. */
+export function across(options: across.Options): FundingRoutes.ProviderAdapter {
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? defaultAcrossBaseUrl)
+  const fetcher = options.fetch ?? globalThis.fetch
+  const now = options.now ?? (() => new Date())
+
+  return {
+    async probeQuote({ route }, signal) {
+      const sourceChainId = providerChainId(route.sourceChain, 'across')
+      const destinationChainId = eip155ChainId(route.destinationChain)
+      const url = new URL(`${baseUrl}/suggested-fees`)
+      url.search = new URLSearchParams({
+        allowUnmatchedDecimals: 'true',
+        amount: route.sourceAmount.amount,
+        destinationChainId,
+        inputToken: route.sourceToken.address,
+        integratorId: options.integratorId,
+        originChainId: sourceChainId,
+        outputToken: route.destinationToken.address,
+      }).toString()
+
+      try {
+        const body = await requestJson(url, {
+          fetcher,
+          headers: { Authorization: `Bearer ${options.apiKey}` },
+          signal,
+        })
+        return formatAcrossResult(route, body, now())
+      } catch (cause) {
+        const unavailable = providerUnavailable(cause, ['AMOUNT_TOO_HIGH', 'AMOUNT_TOO_LOW'])
+        if (!unavailable) throw cause
+        return unavailableResult({
+          detail: 'across:suggested-fees',
+          message: unavailable,
+          now: now(),
+          source: 'providerLimit',
+        })
+      }
+    },
+  }
+}
+
+export declare namespace across {
+  /** Across quote adapter options. */
+  type Options = {
+    /** Across API key sent as a bearer token. */
+    apiKey: string
+    /** Across integrator id sent as the required query parameter. */
+    integratorId: string
+    /** Override for tests or non-production Across environments. */
+    baseUrl?: string | undefined
+    /** Fetch implementation override for tests. */
+    fetch?: Fetch | undefined
+    /** Clock override for deterministic tests. */
+    now?: (() => Date) | undefined
+  }
+}
+
+/** Creates a Relay quote adapter backed by `/chains/liquidity` and `/quote/v2`. */
+export function relay(options: relay.Options): FundingRoutes.ProviderAdapter {
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? defaultRelayBaseUrl)
+  const fetcher = options.fetch ?? globalThis.fetch
+  const now = options.now ?? (() => new Date())
+
+  return {
+    async probeQuote({ route }, signal) {
+      const originChainId = providerChainId(route.sourceChain, 'relay')
+      const destinationChainId = eip155ChainId(route.destinationChain)
+      const headers = relayHeaders(options.apiKey)
+
+      try {
+        const quote = await requestJson(new URL(`${baseUrl}/quote/v2`), {
+          body: {
+            amount: route.sourceAmount.amount,
+            destinationChainId: Number(destinationChainId),
+            destinationCurrency: route.destinationToken.address,
+            originChainId: Number(originChainId),
+            originCurrency: route.sourceToken.address,
+            recipient: options.recipientAddress ?? options.userAddress,
+            tradeType: 'EXACT_INPUT',
+            user: options.userAddress,
+          },
+          fetcher,
+          headers,
+          method: 'POST',
+          signal,
+        })
+        const liquidityUrl = new URL(`${baseUrl}/chains/liquidity`)
+        liquidityUrl.searchParams.set('chainId', destinationChainId)
+        const liquidity = await requestJson(liquidityUrl, { fetcher, headers, signal }).catch(
+          () => undefined,
+        )
+        return formatRelayResult(route, quote, liquidity, now())
+      } catch (cause) {
+        const unavailable = providerUnavailable(cause, [
+          'NO_QUOTES',
+          'NO_ROUTE',
+          'UNSUPPORTED_ROUTE',
+        ])
+        if (!unavailable) throw cause
+        return unavailableResult({
+          detail: 'relay:quote-v2',
+          message: unavailable,
+          now: now(),
+          source: 'providerQuote',
+        })
+      }
+    },
+  }
+}
+
+export declare namespace relay {
+  /** Relay quote adapter options. */
+  type Options = {
+    /** Probe wallet address required by Relay's quote API. */
+    userAddress: string
+    /** Optional recipient override; defaults to `userAddress`. */
+    recipientAddress?: string | undefined
+    /** Optional Relay API key for higher rate limits. */
+    apiKey?: string | undefined
+    /** Override for tests or Relay testnet environments. */
+    baseUrl?: string | undefined
+    /** Fetch implementation override for tests. */
+    fetch?: Fetch | undefined
+    /** Clock override for deterministic tests. */
+    now?: (() => Date) | undefined
+  }
+}
+
+function formatAcrossResult(
+  route: FundingRoutes.RouteCandidate,
+  body: unknown,
+  now: Date,
+): FundingRoutes.QuoteProbeResult {
+  const response = record(body)
+  const timestamp = integerString(response['timestamp'])
+  const sampledAt = timestamp ? isoFromUnixSeconds(timestamp) : now.toISOString()
+  const limits = acrossLimits(response['limits'])
+  const amountStatus = statusFromLimits(route.sourceAmount.amount, limits)
+  const status = response['isAmountTooLow'] === true ? 'unavailable' : amountStatus.status
+  const tier = response['isAmountTooLow'] === true ? 'unavailable' : amountStatus.tier
+  const outputAmount = decimalString(response['outputAmount'])
+
+  return {
+    expiresAt: timestamp ? isoFromUnixSeconds((BigInt(timestamp) + 600n).toString()) : null,
+    limits,
+    outputAmount,
+    outputAmountFormatted: outputAmount
+      ? decimalFromBaseUnits(outputAmount, route.destinationToken.decimals)
+      : null,
+    quality: {
+      availableVolumeUsd: stablecoinUsdCapacity(route, limits?.maxSourceAmount),
+      estimatedSeconds: nonnegativeInteger(response['estimatedFillTimeSec']),
+      feeBps: scaledPctToBps(
+        nestedString(response['totalRelayFee'], 'pct') ?? decimalString(response['relayFeePct']),
+      ),
+      historicalVolumeUsd24h: null,
+      instantVolumeUsd: stablecoinUsdCapacity(route, limits?.instantSourceAmount),
+      liquiditySource: 'providerLimit',
+      score: scoreFor(tier),
+      sourceDetail: 'across:suggested-fees',
+      tier,
+    },
+    sampledAt,
+    status,
+  }
+}
+
+function formatRelayResult(
+  route: FundingRoutes.RouteCandidate,
+  quote: unknown,
+  liquidity: unknown,
+  now: Date,
+): FundingRoutes.QuoteProbeResult {
+  const details = record(record(quote)['details'])
+  const currencyOut = record(details['currencyOut'])
+  const outputAmount = decimalString(currencyOut['amount'])
+  const liquidityRow = relayLiquidity(liquidity, route)
+  const destinationLiquidity = decimalString(liquidityRow?.['balance'])
+  const availableVolumeUsd = decimalString(liquidityRow?.['amountUsd']) ?? null
+  const liquidityStatus = relayLiquidityStatus({ destinationLiquidity, outputAmount })
+
+  return {
+    limits: null,
+    minimumOutputAmount: decimalString(currencyOut['minimumAmount']),
+    outputAmount,
+    outputAmountFormatted: outputAmount
+      ? decimalFromBaseUnits(outputAmount, route.destinationToken.decimals)
+      : null,
+    quality: {
+      availableVolumeUsd: availableVolumeUsd,
+      estimatedSeconds: nonnegativeInteger(details['timeEstimate']),
+      feeBps: null,
+      historicalVolumeUsd24h: null,
+      instantVolumeUsd: availableVolumeUsd,
+      liquiditySource: 'providerQuote',
+      score: scoreFor(liquidityStatus.tier),
+      sourceDetail: 'relay:quote-v2',
+      tier: liquidityStatus.tier,
+    },
+    sampledAt: now.toISOString(),
+    status: liquidityStatus.status,
+  }
+}
+
+function relayLiquidityStatus(options: {
+  destinationLiquidity: string | undefined
+  outputAmount: string | undefined
+}): { status: FundingRoutes.RouteStatus; tier: FundingRoutes.QualityTier } {
+  if (!options.outputAmount) return { status: 'unknown', tier: 'unknown' }
+  if (!options.destinationLiquidity) return { status: 'unknown', tier: 'unknown' }
+  if (compareIntegerStrings(options.destinationLiquidity, options.outputAmount) < 0)
+    return { status: 'thin', tier: 'thin' }
+  return { status: 'available', tier: 'liquid' }
+}
+
+function unavailableResult(options: {
+  detail: string
+  message: string
+  now: Date
+  source: string
+}): FundingRoutes.QuoteProbeResult {
+  return {
+    quality: {
+      availableVolumeUsd: null,
+      estimatedSeconds: null,
+      feeBps: null,
+      historicalVolumeUsd24h: null,
+      instantVolumeUsd: null,
+      liquiditySource: options.source,
+      score: 0,
+      sourceDetail: `${options.detail}:${options.message}`,
+      tier: 'unavailable',
+    },
+    sampledAt: options.now.toISOString(),
+    status: 'unavailable',
+  }
+}
+
+function acrossLimits(input: unknown): FundingRoutes.QuoteProbeLimits | null {
+  const limits = record(input)
+  const minSourceAmount = decimalString(limits['minDeposit'])
+  const maxSourceAmount = decimalString(limits['maxDeposit'])
+  const instantSourceAmount =
+    decimalString(limits['maxDepositInstant']) ?? decimalString(limits['recommendedDepositInstant'])
+  return minSourceAmount || maxSourceAmount || instantSourceAmount
+    ? { instantSourceAmount, maxSourceAmount, minSourceAmount }
+    : null
+}
+
+function statusFromLimits(
+  amount: string,
+  limits: FundingRoutes.QuoteProbeLimits | null,
+): { status: FundingRoutes.RouteStatus; tier: FundingRoutes.QualityTier } {
+  if (!limits) return { status: 'available', tier: 'liquid' }
+  if (limits.minSourceAmount && compareIntegerStrings(amount, limits.minSourceAmount) < 0)
+    return { status: 'unavailable', tier: 'unavailable' }
+  if (limits.maxSourceAmount && compareIntegerStrings(amount, limits.maxSourceAmount) > 0)
+    return { status: 'unavailable', tier: 'unavailable' }
+  if (limits.instantSourceAmount && compareIntegerStrings(amount, limits.instantSourceAmount) > 0)
+    return { status: 'thin', tier: 'thin' }
+  return { status: 'available', tier: 'liquid' }
+}
+
+function relayLiquidity(input: unknown, route: FundingRoutes.RouteCandidate) {
+  const response = record(input)
+  const rows = Array.isArray(response['liquidity']) ? response['liquidity'] : []
+  const destinationChainId = eip155ChainId(route.destinationChain)
+  return rows.map(record).find((row) => {
+    const rowChainId = integerString(row['chainId'])
+    const rowAddress = typeof row['address'] === 'string' ? row['address'].toLowerCase() : undefined
+    return (
+      rowChainId === destinationChainId &&
+      rowAddress === route.destinationToken.address.toLowerCase()
+    )
+  })
+}
+
+async function requestJson(
+  url: URL,
+  options: {
+    body?: unknown
+    fetcher: Fetch
+    headers?: Record<string, string> | undefined
+    method?: string | undefined
+    signal: AbortSignal
+  },
+) {
+  const headers = { accept: 'application/json', ...options.headers }
+  const init: RequestInit = {
+    headers:
+      options.body === undefined ? headers : { ...headers, 'content-type': 'application/json' },
+    method: options.method ?? 'GET',
+    signal: options.signal,
+  }
+  if (options.body !== undefined) init.body = JSON.stringify(options.body)
+  const response = await options.fetcher(url, init)
+  const text = await response.text()
+  const body = parseJson(text)
+  if (!response.ok) throw new ProviderResponseError(response.status, body)
+  return body
+}
+
+function relayHeaders(apiKey: string | undefined): Record<string, string> | undefined {
+  return apiKey ? { 'x-api-key': apiKey } : undefined
+}
+
+function providerUnavailable(cause: unknown, codes: readonly string[]) {
+  if (!(cause instanceof ProviderResponseError) || cause.status < 400 || cause.status >= 500)
+    return undefined
+  const body = record(cause.body)
+  const code = stringValue(body['code']) ?? stringValue(body['errorCode'])
+  if (code && codes.includes(code)) return code
+  return undefined
+}
+
+class ProviderResponseError extends Error {
+  override name = 'FundingRouteProviders.ProviderResponseError'
+
+  constructor(
+    readonly status: number,
+    readonly body: unknown,
+  ) {
+    super(`Provider request failed with status ${status}`)
+  }
+}
+
+function providerChainId(
+  routeChain: FundingRoutes.RouteCandidate['sourceChain'],
+  provider: string,
+) {
+  const providerIds = routeChain.providerIds as Record<string, string> | undefined
+  const id = providerIds?.[provider]
+  if (id && /^\d+$/.test(id)) return id
+  return eip155ChainId(routeChain)
+}
+
+function eip155ChainId(chain: { id: string; kind: string }) {
+  if (chain.kind !== 'evm') throw new UnsupportedProviderRouteError()
+  const match = /^eip155:(\d+)$/.exec(chain.id)
+  if (!match?.[1]) throw new UnsupportedProviderRouteError()
+  return match[1]
+}
+
+class UnsupportedProviderRouteError extends Error {
+  override name = 'FundingRouteProviders.UnsupportedProviderRouteError'
+}
+
+function normalizeBaseUrl(input: string) {
+  return input.replace(/\/+$/, '')
+}
+
+function parseJson(input: string) {
+  if (!input) return null
+  try {
+    return JSON.parse(input) as unknown
+  } catch {
+    return input
+  }
+}
+
+function record(input: unknown): Record<string, unknown> {
+  return input && typeof input === 'object' && !Array.isArray(input)
+    ? (input as Record<string, unknown>)
+    : {}
+}
+
+function stringValue(input: unknown) {
+  return typeof input === 'string' && input.length > 0 ? input : undefined
+}
+
+function decimalString(input: unknown) {
+  if (typeof input === 'string' && /^\d+(\.\d+)?$/.test(input)) return input
+  if (typeof input === 'number' && Number.isFinite(input) && input >= 0) return String(input)
+  return undefined
+}
+
+function integerString(input: unknown) {
+  if (typeof input === 'string' && /^\d+$/.test(input)) return input
+  if (typeof input === 'number' && Number.isSafeInteger(input) && input >= 0) return String(input)
+  return undefined
+}
+
+function nestedString(input: unknown, key: string) {
+  return decimalString(record(input)[key])
+}
+
+function nonnegativeInteger(input: unknown) {
+  if (typeof input === 'number' && Number.isSafeInteger(input) && input >= 0) return input
+  if (typeof input === 'string' && /^\d+$/.test(input)) return Number(input)
+  return null
+}
+
+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
+}
+
+function compareIntegerStrings(left: string, right: string) {
+  return BigInt(left) === BigInt(right) ? 0 : BigInt(left) > BigInt(right) ? 1 : -1
+}
+
+function isoFromUnixSeconds(input: string) {
+  return new Date(Number(input) * 1_000).toISOString()
+}
+
+function stablecoinUsdCapacity(
+  route: FundingRoutes.RouteCandidate,
+  baseUnits: string | null | undefined,
+) {
+  if (!baseUnits || !isDollarStablecoin(route.sourceToken.symbol)) return null
+  return decimalFromBaseUnits(baseUnits, route.sourceToken.decimals)
+}
+
+function isDollarStablecoin(symbol: string) {
+  return ['DAI', 'FRXUSD', 'PYUSD', 'USDC', 'USDC.E', 'USDT', 'USDT0'].includes(
+    symbol.toUpperCase(),
+  )
+}
+
+function scaledPctToBps(input: string | undefined) {
+  if (!input || !/^\d+$/.test(input)) return null
+  const denominator = 1_000_000_000_000_000_000n
+  return Number((BigInt(input) * 10_000n + denominator / 2n) / denominator)
+}
+
+function scoreFor(tier: FundingRoutes.QualityTier) {
+  if (tier === 'liquid') return 90
+  if (tier === 'thin') return 65
+  if (tier === 'unavailable') return 0
+  return null
+}

package/src/apps/data/index.ts

@@ -1,2 +1,3 @@
 export { data } from './App.js'
+export * as FundingRouteProviders from './FundingRouteProviders.js'
 export * as Sponsorships from '../relay/Sponsorships.js'