tapimo 0.4.4 → 0.5.1

package/src/apps/data/FundingQuoteProviders.ts

@@ -0,0 +1,633 @@
+import * as z from 'zod/mini'
+
+import * as FundingQuotes from '../../internal/FundingQuotes.js'
+
+type Fetch = typeof globalThis.fetch
+
+const defaultFetch: Fetch = (input, init) => globalThis.fetch(input, init)
+
+const defaultAcrossBaseUrl = 'https://app.across.to/api'
+const defaultRelayBaseUrl = 'https://api.relay.link'
+const defaultRhinoBaseUrl = 'https://api.rhino.fi/bridge'
+const providerOperations = {
+  across: 'swap/approval',
+  relay: 'quote/v2',
+  rhino: 'quote/bridge-swap/public',
+} as const
+
+namespace schema {
+  const IntegerString = z.string().check(z.regex(/^\d+$/))
+
+  const AcrossToken = z.object({
+    address: z.string(),
+    chainId: z.number().check(z.int(), z.nonnegative()),
+    decimals: z.number().check(z.int(), z.nonnegative()),
+  })
+
+  export const AcrossQuote = z.object({
+    amountType: z.literal('exactInput'),
+    expectedFillTime: z.number().check(z.int(), z.nonnegative()),
+    expectedOutputAmount: IntegerString,
+    inputAmount: IntegerString,
+    inputToken: AcrossToken,
+    minOutputAmount: IntegerString,
+    outputToken: AcrossToken,
+    quoteExpiryTimestamp: z.number().check(z.int(), z.nonnegative()),
+  })
+
+  export const RhinoQuote = z.object({
+    _tag: z.literal('bridge'),
+    chainIn: z.string(),
+    chainOut: z.string(),
+    estimatedDuration: z.optional(z.nullable(z.number().check(z.nonnegative()))),
+    payAmount: z.string().check(z.regex(/^\d+(\.\d+)?$/)),
+    receiveAmount: z.string().check(z.regex(/^\d+(\.\d+)?$/)),
+    token: z.string(),
+  })
+}
+
+/** Creates the live funding quote adapters configured for this deployment. */
+export function createAdapters(options: createAdapters.Options = {}) {
+  return {
+    ...(options.across ? { across: across(options.across) } : {}),
+    ...(options.relay ? { relay: relay(options.relay) } : {}),
+    ...(options.rhino ? { rhino: rhino(options.rhino) } : {}),
+  } satisfies FundingQuotes.ProviderAdapters
+}
+
+export declare namespace createAdapters {
+  /** Provider adapter factory options. Omit a provider to leave it unconfigured. */
+  type Options = {
+    /** Across quote adapter options. */
+    across?: across.Options | false | undefined
+    /** Relay quote adapter options. */
+    relay?: relay.Options | false | undefined
+    /** Rhino quote adapter options. */
+    rhino?: rhino.Options | false | undefined
+  }
+}
+
+/** Resolves all-or-none Across deployment configuration. */
+export function configureAcross(options: configureAcross.Options = {}): across.Options | undefined {
+  const configured = [options.apiKey, options.integratorId, options.userAddress].filter(Boolean)
+  if (configured.length === 0) return undefined
+  if (!options.apiKey || !options.integratorId || !options.userAddress)
+    throw new ProviderConfigurationError()
+  return {
+    apiKey: options.apiKey,
+    integratorId: options.integratorId,
+    userAddress: options.userAddress,
+  }
+}
+
+export declare namespace configureAcross {
+  /** Optional deployment bindings required together to enable Across. */
+  type Options = {
+    /** Across API key binding. */
+    apiKey?: string | undefined
+    /** Across integrator id binding. */
+    integratorId?: string | undefined
+    /** Across quote-user binding. */
+    userAddress?: string | undefined
+  }
+}
+
+/** Creates an Across quote adapter backed by `/swap/approval`. */
+export function across(options: across.Options): FundingQuotes.ProviderAdapter {
+  assertAcrossConfiguration(options)
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? defaultAcrossBaseUrl)
+  const fetcher = options.fetch ?? defaultFetch
+  const now = options.now ?? (() => new Date())
+
+  return {
+    async probeQuote({ candidate }, signal) {
+      const destinationChainId = eip155ChainId(candidate.destinationChain)
+      const originChainId = providerChainId(candidate.sourceChain, 'across')
+      const url = new URL(`${baseUrl}/swap/approval`)
+      url.search = new URLSearchParams({
+        amount: candidate.sourceAmount.amount,
+        depositor: options.userAddress,
+        destinationChainId,
+        inputToken: candidate.sourceToken.address,
+        integratorId: options.integratorId,
+        originChainId,
+        outputToken: candidate.destinationToken.address,
+        recipient: options.userAddress,
+        skipOriginTxEstimation: 'true',
+        strictTradeType: 'true',
+        tradeType: 'exactInput',
+      }).toString()
+
+      try {
+        const quote = await requestJson(url, {
+          fetcher,
+          headers: { Authorization: `Bearer ${options.apiKey}` },
+          signal,
+        })
+        return formatAcrossResult(candidate, quote, now())
+      } catch (cause) {
+        const unavailable = providerUnavailable(cause, [
+          'AMOUNT_TOO_HIGH',
+          'AMOUNT_TOO_LOW',
+          'INSUFFICIENT_LIQUIDITY',
+          'NO_QUOTES',
+          'NO_ROUTE',
+          'UNSUPPORTED_ROUTE',
+        ])
+        if (!unavailable) throw cause
+        return unavailableResult({
+          detail: 'across:swap-approval',
+          message: unavailable,
+          now: now(),
+          source: 'providerQuote',
+        })
+      }
+    },
+  }
+}
+
+export declare namespace across {
+  /** Across quote adapter options. */
+  type Options = {
+    /** Across API key sent as a bearer token. */
+    apiKey: string
+    /** Override for tests or Across test environments. */
+    baseUrl?: string | undefined
+    /** Fetch implementation override for tests. */
+    fetch?: Fetch | undefined
+    /** Across integrator id sent as the required query parameter. */
+    integratorId: string
+    /** Clock override for deterministic tests. */
+    now?: (() => Date) | undefined
+    /** Probe wallet address used as the Across depositor and recipient. */
+    userAddress: string
+  }
+}
+
+/** Creates a Relay quote adapter backed by `/quote/v2`. */
+export function relay(options: relay.Options): FundingQuotes.ProviderAdapter {
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? defaultRelayBaseUrl)
+  const fetcher = options.fetch ?? defaultFetch
+  const now = options.now ?? (() => new Date())
+
+  return {
+    async probeQuote({ candidate }, signal) {
+      const originChainId = providerChainId(candidate.sourceChain, 'relay')
+      const destinationChainId = eip155ChainId(candidate.destinationChain)
+      const headers = relayHeaders(options.apiKey)
+
+      try {
+        const quote = await requestJson(new URL(`${baseUrl}/quote/v2`), {
+          body: {
+            amount: candidate.sourceAmount.amount,
+            destinationChainId: Number(destinationChainId),
+            destinationCurrency: candidate.destinationToken.address,
+            originChainId: Number(originChainId),
+            originCurrency: candidate.sourceToken.address,
+            recipient: options.recipientAddress ?? options.userAddress,
+            tradeType: 'EXACT_INPUT',
+            user: options.userAddress,
+          },
+          fetcher,
+          headers,
+          method: 'POST',
+          signal,
+        })
+        return formatRelayResult(candidate, quote, 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
+  }
+}
+
+/** Creates a Rhino quote adapter backed by the public bridge-and-swap quote endpoint. */
+export function rhino(options: rhino.Options = {}): FundingQuotes.ProviderAdapter {
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? defaultRhinoBaseUrl)
+  const fetcher = options.fetch ?? defaultFetch
+  const now = options.now ?? (() => new Date())
+
+  return {
+    async probeQuote({ cache, candidate }, signal) {
+      const chainIn = providerChainReference(candidate.sourceChain, 'rhino')
+      const tokenOut = rhinoToken(candidate.destinationToken)
+      const url = new URL(`${baseUrl}/quote/bridge-swap/public`)
+      url.search = new URLSearchParams({
+        amount: candidate.sourceAmount.formatted,
+        amountNative: '0',
+        chainIn,
+        chainOut: 'TEMPO',
+        mode: 'pay',
+        tokenIn: candidate.sourceToken.symbol,
+        tokenOut,
+      }).toString()
+
+      try {
+        const quote = await requestJson(url, {
+          fetcher,
+          headers: cache.bypass ? { 'cache-control': 'no-cache' } : undefined,
+          signal,
+        })
+        return formatRhinoResult(candidate, quote, { chainIn, now: now(), tokenOut })
+      } catch (cause) {
+        const unavailable = providerUnavailable(cause, ['NoRouteFoundError'])
+        if (!unavailable) throw cause
+        return unavailableResult({
+          detail: 'rhino:bridge-swap-public',
+          message: unavailable,
+          now: now(),
+          source: 'providerQuote',
+        })
+      }
+    },
+  }
+}
+
+export declare namespace rhino {
+  /** Rhino public quote adapter options. */
+  type Options = {
+    /** Override for tests or Rhino test environments. */
+    baseUrl?: string | undefined
+    /** Fetch implementation override for tests. */
+    fetch?: Fetch | undefined
+    /** Clock override for deterministic tests. */
+    now?: (() => Date) | undefined
+  }
+}
+
+/** Returns bounded provider failure details suitable for structured request logs. */
+export function providerFailure(options: providerFailure.Options): providerFailure.Result {
+  const operation = providerOperations[options.provider]
+  if (
+    options.cause instanceof FundingQuotes.ProviderAdapterTimeoutError ||
+    (options.cause instanceof DOMException && options.cause.name === 'AbortError')
+  )
+    return { failure: 'timeout', id: options.provider, operation }
+  if (options.cause instanceof ProviderResponseError) {
+    const code = providerErrorCode(options.cause.body)
+    return {
+      ...(code === undefined ? {} : { code }),
+      failure: 'http',
+      id: options.provider,
+      operation,
+      status: options.cause.status,
+    }
+  }
+  if (options.cause instanceof ProviderPayloadError)
+    return { failure: 'payload', id: options.provider, operation }
+  if (options.cause instanceof TypeError)
+    return { failure: 'network', id: options.provider, operation }
+  return { failure: 'unknown', id: options.provider, operation }
+}
+
+export declare namespace providerFailure {
+  /** Inputs used to classify a provider failure. */
+  type Options = FundingQuotes.ProviderFailure
+
+  /** Bounded provider failure fields. */
+  type Result = {
+    /** Stable provider error code, when one is safe to retain. */
+    code?: string | undefined
+    /** Failure boundary that rejected the provider request. */
+    failure: 'http' | 'network' | 'payload' | 'timeout' | 'unknown'
+    /** Provider identifier. */
+    id: FundingQuotes.ProviderId
+    /** Provider operation identifier. */
+    operation: (typeof providerOperations)[FundingQuotes.ProviderId]
+    /** Upstream HTTP status, when a response was received. */
+    status?: number | undefined
+  }
+}
+
+function formatAcrossResult(
+  candidate: FundingQuotes.QuoteCandidate,
+  quote: unknown,
+  now: Date,
+): FundingQuotes.QuoteProbeResult {
+  const parsed = schema.AcrossQuote.safeParse(quote)
+  if (!parsed.success) throw new ProviderPayloadError()
+  const response = parsed.data
+  const expiresAt = new Date(response.quoteExpiryTimestamp * 1_000)
+  if (
+    response.inputAmount !== candidate.sourceAmount.amount ||
+    !matchesToken(response.inputToken, candidate.sourceChain, candidate.sourceToken) ||
+    !matchesToken(response.outputToken, candidate.destinationChain, candidate.destinationToken) ||
+    BigInt(response.expectedOutputAmount) <= 0n ||
+    BigInt(response.minOutputAmount) <= 0n ||
+    BigInt(response.minOutputAmount) > BigInt(response.expectedOutputAmount) ||
+    Number.isNaN(expiresAt.getTime()) ||
+    response.quoteExpiryTimestamp * 1_000 <= now.getTime()
+  )
+    throw new ProviderPayloadError()
+
+  return {
+    expiresAt: expiresAt.toISOString(),
+    minimumOutputAmount: response.minOutputAmount,
+    outputAmount: response.expectedOutputAmount,
+    outputAmountFormatted: decimalFromBaseUnits(
+      response.expectedOutputAmount,
+      candidate.destinationToken.decimals,
+    ),
+    quality: {
+      estimatedSeconds: response.expectedFillTime,
+      liquiditySource: 'providerQuote',
+      sourceDetail: 'across:swap-approval',
+      tier: 'liquid',
+    },
+    sampledAt: now.toISOString(),
+    status: 'available',
+  }
+}
+
+function formatRelayResult(
+  candidate: FundingQuotes.QuoteCandidate,
+  quote: unknown,
+  now: Date,
+): FundingQuotes.QuoteProbeResult {
+  const details = record(record(quote)['details'])
+  const currencyOut = record(details['currencyOut'])
+  const outputAmount = decimalString(currencyOut['amount'])
+  const status = outputAmount
+    ? { status: 'available' as const, tier: 'liquid' as const }
+    : { status: 'unknown' as const, tier: 'unknown' as const }
+
+  return {
+    minimumOutputAmount: decimalString(currencyOut['minimumAmount']),
+    outputAmount,
+    outputAmountFormatted: outputAmount
+      ? decimalFromBaseUnits(outputAmount, candidate.destinationToken.decimals)
+      : undefined,
+    quality: {
+      estimatedSeconds: nonnegativeInteger(details['timeEstimate']),
+      liquiditySource: 'providerQuote',
+      sourceDetail: 'relay:quote-v2',
+      tier: status.tier,
+    },
+    sampledAt: now.toISOString(),
+    status: status.status,
+  }
+}
+
+function formatRhinoResult(
+  candidate: FundingQuotes.QuoteCandidate,
+  quote: unknown,
+  options: { chainIn: string; now: Date; tokenOut: string },
+): FundingQuotes.QuoteProbeResult {
+  const parsed = schema.RhinoQuote.safeParse(quote)
+  if (!parsed.success) throw new ProviderPayloadError()
+  const response = parsed.data
+  const inputAmount = baseUnitsFromDecimal(response.payAmount, candidate.sourceToken.decimals)
+  const outputAmount = baseUnitsFromDecimal(
+    response.receiveAmount,
+    candidate.destinationToken.decimals,
+  )
+  if (
+    response.chainIn !== options.chainIn ||
+    response.chainOut !== 'TEMPO' ||
+    response.token !== options.tokenOut ||
+    inputAmount !== candidate.sourceAmount.amount ||
+    outputAmount === undefined ||
+    BigInt(outputAmount) <= 0n
+  )
+    throw new ProviderPayloadError()
+
+  return {
+    outputAmount,
+    outputAmountFormatted: decimalFromBaseUnits(outputAmount, candidate.destinationToken.decimals),
+    quality: {
+      ...(response.estimatedDuration === undefined || response.estimatedDuration === null
+        ? {}
+        : { estimatedSeconds: Math.ceil(response.estimatedDuration / 1_000) }),
+      liquiditySource: 'providerQuote',
+      sourceDetail: 'rhino:bridge-swap-public',
+      tier: 'liquid',
+    },
+    sampledAt: options.now.toISOString(),
+    status: 'available',
+  }
+}
+
+function unavailableResult(options: {
+  detail: string
+  message: string
+  now: Date
+  source: string
+}): FundingQuotes.QuoteProbeResult {
+  return {
+    quality: {
+      liquiditySource: options.source,
+      sourceDetail: `${options.detail}:${options.message}`,
+      tier: 'unavailable',
+    },
+    sampledAt: options.now.toISOString(),
+    status: 'unavailable',
+  }
+}
+
+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 code = providerErrorCode(cause.body)
+  if (code && codes.includes(code)) return code
+  return undefined
+}
+
+function providerErrorCode(input: unknown) {
+  const body = record(input)
+  const code =
+    stringValue(body['_tag']) ?? stringValue(body['code']) ?? stringValue(body['errorCode'])
+  return code && /^[A-Za-z0-9_.:-]{1,64}$/.test(code) ? code : undefined
+}
+
+function providerChainId(
+  quoteChain: FundingQuotes.QuoteCandidate['sourceChain'],
+  provider: string,
+) {
+  const providerIds = quoteChain.providerIds as Record<string, string> | undefined
+  const id = providerIds?.[provider]
+  if (id && /^\d+$/.test(id)) return id
+  return eip155ChainId(quoteChain)
+}
+
+function providerChainReference(
+  quoteChain: FundingQuotes.QuoteCandidate['sourceChain'],
+  provider: string,
+) {
+  const providerIds = quoteChain.providerIds as Record<string, string> | undefined
+  const id = providerIds?.[provider]
+  if (!id) throw new UnsupportedProviderChainError()
+  return id
+}
+
+function rhinoToken(token: FundingQuotes.TokenRef) {
+  const tokens: Record<string, string> = {
+    '0x20c00000000000000000000014f22ca97301eb73': 'USDT',
+    '0x20c000000000000000000000b9537d11c60e8b50': 'USDC',
+  }
+  const id = tokens[token.address.toLowerCase()]
+  if (!id) throw new UnsupportedProviderTokenError()
+  return id
+}
+
+function matchesToken(
+  token: z.output<typeof schema.AcrossQuote>['inputToken'],
+  chain: FundingQuotes.ChainRef,
+  expected: FundingQuotes.TokenRef,
+) {
+  return (
+    token.address.toLowerCase() === expected.address.toLowerCase() &&
+    token.chainId === Number(eip155ChainId(chain)) &&
+    token.decimals === expected.decimals
+  )
+}
+
+function eip155ChainId(chain: { id: string; kind: string }) {
+  if (chain.kind !== 'evm') throw new UnsupportedProviderChainError()
+  const match = /^eip155:(\d+)$/.exec(chain.id)
+  if (!match?.[1]) throw new UnsupportedProviderChainError()
+  return match[1]
+}
+
+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 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 undefined
+}
+
+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 baseUnitsFromDecimal(value: string, decimals: number) {
+  if (!/^\d+(\.\d+)?$/.test(value)) return undefined
+  const [whole, fraction = ''] = value.split('.')
+  const significantFraction = fraction.replace(/0+$/, '')
+  if (significantFraction.length > decimals) return undefined
+  return BigInt(`${whole}${significantFraction.padEnd(decimals, '0')}`).toString()
+}
+
+function assertAcrossConfiguration(options: across.Options) {
+  if (
+    options.apiKey.length === 0 ||
+    !/^0x[\da-fA-F]{4}$/.test(options.integratorId) ||
+    !/^0x[\da-fA-F]{40}$/.test(options.userAddress)
+  )
+    throw new ProviderConfigurationError()
+}
+
+class ProviderConfigurationError extends Error {
+  override name = 'FundingQuoteProviders.ProviderConfigurationError'
+}
+
+class ProviderPayloadError extends Error {
+  override name = 'FundingQuoteProviders.ProviderPayloadError'
+}
+
+class ProviderResponseError extends Error {
+  override name = 'FundingQuoteProviders.ProviderResponseError'
+
+  constructor(
+    readonly status: number,
+    readonly body: unknown,
+  ) {
+    super(`Provider request failed with status ${status}`)
+  }
+}
+
+class UnsupportedProviderChainError extends Error {
+  override name = 'FundingQuoteProviders.UnsupportedProviderChainError'
+}
+
+class UnsupportedProviderTokenError extends Error {
+  override name = 'FundingQuoteProviders.UnsupportedProviderTokenError'
+}

package/src/apps/data/index.ts

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