tapimo 0.5.0 → 0.5.2

package/src/apps/data/FundingQuoteProviders.ts

@@ -1,23 +1,211 @@
+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 defaultSquidBaseUrl = 'https://v2.api.squidrouter.com/v2'
+const providerOperations = {
+  across: 'swap/approval',
+  relay: 'quote/v2',
+  rhino: 'quote/bridge-swap/public',
+  squid: 'v2/route',
+} 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(),
+  })
+
+  const SquidToken = z.object({
+    address: z.string(),
+    chainId: z.union([z.string(), z.number().check(z.int(), z.nonnegative())]),
+    decimals: z.number().check(z.int(), z.nonnegative()),
+  })
+
+  export const SquidQuote = z.object({
+    route: z.object({
+      estimate: z.object({
+        estimatedRouteDuration: z.number().check(z.nonnegative()),
+        fromAmount: IntegerString,
+        fromToken: SquidToken,
+        toAmount: IntegerString,
+        toAmountMin: IntegerString,
+        toToken: SquidToken,
+      }),
+    }),
+  })
+}
 
 /** Creates the live funding quote adapters configured for this deployment. */
 export function createAdapters(options: createAdapters.Options = {}) {
-  return (
-    options.relay ? { relay: relay(options.relay) } : {}
-  ) satisfies FundingQuotes.ProviderAdapters
+  return {
+    ...(options.across ? { across: across(options.across) } : {}),
+    ...(options.relay ? { relay: relay(options.relay) } : {}),
+    ...(options.rhino ? { rhino: rhino(options.rhino) } : {}),
+    ...(options.squid ? { squid: squid(options.squid) } : {}),
+  } 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
+    /** Squid quote adapter options. */
+    squid?: squid.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
+  }
+}
+
+/** Resolves all-or-none Squid deployment configuration. */
+export function configureSquid(options: configureSquid.Options = {}): squid.Options | undefined {
+  const configured = [options.integratorId, options.userAddress].filter(Boolean)
+  if (configured.length === 0) return undefined
+  if (!options.integratorId || !options.userAddress) throw new ProviderConfigurationError()
+  return {
+    integratorId: options.integratorId,
+    userAddress: options.userAddress,
+  }
+}
+
+export declare namespace configureSquid {
+  /** Optional deployment bindings required together to enable Squid. */
+  type Options = {
+    /** Squid integrator id binding. */
+    integratorId?: string | undefined
+    /** Squid 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
   }
 }
 
@@ -87,6 +275,212 @@ export declare namespace relay {
   }
 }
 
+/** 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
+  }
+}
+
+/** Creates a Squid quote adapter backed by `/v2/route`. */
+export function squid(options: squid.Options): FundingQuotes.ProviderAdapter {
+  assertSquidConfiguration(options)
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? defaultSquidBaseUrl)
+  const fetcher = options.fetch ?? defaultFetch
+  const now = options.now ?? (() => new Date())
+
+  return {
+    async probeQuote({ candidate }, signal) {
+      const fromChain = eip155ChainId(candidate.sourceChain)
+      const toChain = eip155ChainId(candidate.destinationChain)
+
+      try {
+        const quote = await requestJson(new URL(`${baseUrl}/route`), {
+          body: {
+            fromAddress: options.userAddress,
+            fromAmount: candidate.sourceAmount.amount,
+            fromChain,
+            fromToken: candidate.sourceToken.address,
+            quoteOnly: true,
+            // V1 quotes use a fixed 1% tolerance; callers cannot customize execution policy.
+            slippage: 1,
+            toAddress: options.userAddress,
+            toChain,
+            toToken: candidate.destinationToken.address,
+          },
+          fetcher,
+          headers: { 'x-integrator-id': options.integratorId },
+          method: 'POST',
+          signal,
+        })
+        return formatSquidResult(candidate, quote, now())
+      } catch (cause) {
+        const unavailable =
+          providerUnavailable(cause, [
+            'NO_ROUTE',
+            'NO_ROUTE_FOUND',
+            'ROUTE_NOT_FOUND',
+            'UNSUPPORTED_ROUTE',
+          ]) ?? squidUnavailable(cause)
+        if (!unavailable) throw cause
+        return unavailableResult({
+          detail: 'squid:route-v2',
+          message: unavailable,
+          now: now(),
+          source: 'providerQuote',
+        })
+      }
+    },
+  }
+}
+
+export declare namespace squid {
+  /** Squid quote adapter options. */
+  type Options = {
+    /** Override for tests or Squid test environments. */
+    baseUrl?: string | undefined
+    /** Fetch implementation override for tests. */
+    fetch?: Fetch | undefined
+    /** Squid integrator id sent in the required request header. */
+    integratorId: string
+    /** Clock override for deterministic tests. */
+    now?: (() => Date) | undefined
+    /** Probe wallet address used as the Squid sender and recipient. */
+    userAddress: string
+  }
+}
+
+/** 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,
@@ -116,6 +510,81 @@ function formatRelayResult(
   }
 }
 
+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 formatSquidResult(
+  candidate: FundingQuotes.QuoteCandidate,
+  quote: unknown,
+  now: Date,
+): FundingQuotes.QuoteProbeResult {
+  const parsed = schema.SquidQuote.safeParse(quote)
+  if (!parsed.success) throw new ProviderPayloadError()
+  const response = parsed.data.route.estimate
+  if (
+    response.fromAmount !== candidate.sourceAmount.amount ||
+    !matchesSquidToken(response.fromToken, candidate.sourceChain, candidate.sourceToken) ||
+    !matchesSquidToken(response.toToken, candidate.destinationChain, candidate.destinationToken) ||
+    BigInt(response.toAmount) <= 0n ||
+    BigInt(response.toAmountMin) <= 0n ||
+    BigInt(response.toAmountMin) > BigInt(response.toAmount)
+  )
+    throw new ProviderPayloadError()
+
+  return {
+    minimumOutputAmount: response.toAmountMin,
+    outputAmount: response.toAmount,
+    outputAmountFormatted: decimalFromBaseUnits(
+      response.toAmount,
+      candidate.destinationToken.decimals,
+    ),
+    quality: {
+      estimatedSeconds: Math.ceil(response.estimatedRouteDuration),
+      liquiditySource: 'providerQuote',
+      sourceDetail: 'squid:route-v2',
+      tier: 'liquid',
+    },
+    sampledAt: now.toISOString(),
+    status: 'available',
+  }
+}
+
 function unavailableResult(options: {
   detail: string
   message: string
@@ -172,10 +641,29 @@ function providerUnavailable(cause: unknown, codes: readonly string[]) {
 
 function providerErrorCode(input: unknown) {
   const body = record(input)
-  const code = stringValue(body['code']) ?? stringValue(body['errorCode'])
+  const error = record(body['error'])
+  const code =
+    stringValue(body['_tag']) ??
+    stringValue(body['code']) ??
+    stringValue(body['errorCode']) ??
+    stringValue(body['errorType']) ??
+    stringValue(body['type']) ??
+    stringValue(error['code']) ??
+    stringValue(error['type'])
   return code && /^[A-Za-z0-9_.:-]{1,64}$/.test(code) ? code : undefined
 }
 
+function squidUnavailable(cause: unknown) {
+  if (!(cause instanceof ProviderResponseError) || cause.status !== 400) return undefined
+  const body = record(cause.body)
+  if (
+    body['type'] === 'BAD_REQUEST' &&
+    body['message'] === 'Please increase the swap amount and try again.'
+  )
+    return 'AMOUNT_TOO_LOW'
+  return undefined
+}
+
 function providerChainId(
   quoteChain: FundingQuotes.QuoteCandidate['sourceChain'],
   provider: string,
@@ -186,6 +674,50 @@ function providerChainId(
   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 matchesSquidToken(
+  token: z.output<typeof schema.SquidQuote>['route']['estimate']['fromToken'],
+  chain: FundingQuotes.ChainRef,
+  expected: FundingQuotes.TokenRef,
+) {
+  return (
+    token.address.toLowerCase() === expected.address.toLowerCase() &&
+    String(token.chainId) === 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)
@@ -235,6 +767,36 @@ function decimalFromBaseUnits(baseUnits: string, decimals: number) {
   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()
+}
+
+function assertSquidConfiguration(options: squid.Options) {
+  if (options.integratorId.length === 0 || !/^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'
 
@@ -249,3 +811,7 @@ class ProviderResponseError extends Error {
 class UnsupportedProviderChainError extends Error {
   override name = 'FundingQuoteProviders.UnsupportedProviderChainError'
 }
+
+class UnsupportedProviderTokenError extends Error {
+  override name = 'FundingQuoteProviders.UnsupportedProviderTokenError'
+}