tapimo 0.7.1 → 0.8.0

package/src/apps/data/routes/funding.ts

@@ -1,604 +0,0 @@
-import { Hono } from 'hono'
-import * as z from 'zod/mini'
-
-import type * as App from '../../../App.js'
-import * as Auth from '../../../internal/Auth.js'
-import * as Cache from '../../../internal/Cache.js'
-import * as FundingQuotes from '../../../internal/FundingQuotes.js'
-import type * as Log from '../../../internal/Log.js'
-import * as OpenApi from '../../../internal/OpenApi.js'
-import * as Response from '../../../internal/Response.js'
-import * as Schema from '../../../internal/Schema.js'
-import * as Value from '../../../internal/Value.js'
-import * as FundingQuoteProviders from '../FundingQuoteProviders.js'
-
-/** Zod schemas owned by funding quote resources. */
-export namespace schema {
-  /** Source or destination chain reference. */
-  export const Chain = Schema.describe(
-    z.object({
-      addressFormat: z
-        .enum(['base58', 'base58check', 'evm'])
-        .check(
-          z.describe('Address family used by accounts and token identifiers on this chain.'),
-          z.meta({ examples: ['evm'] }),
-        ),
-      id: z
-        .string()
-        .check(
-          z.describe(
-            'Stable chain id. Uses CAIP-2 where standardized and a Tempo-defined compatible id otherwise.',
-          ),
-          z.meta({ examples: ['eip155:8453'] }),
-        ),
-      kind: z
-        .enum(['evm', 'solana', 'tron'])
-        .check(
-          z.describe('Chain execution family used for provider routing.'),
-          z.meta({ examples: ['evm'] }),
-        ),
-      name: z
-        .string()
-        .check(z.describe('Human-readable chain name.'), z.meta({ examples: ['Base'] })),
-      providerIds: z
-        .optional(z.record(z.string(), z.string()))
-        .check(
-          z.describe('Provider-specific chain ids Tempo uses when requesting quotes.'),
-          z.meta({ examples: [{ across: '8453', relay: '8453', rhino: 'BASE' }] }),
-        ),
-    }),
-    'A normalized chain reference for funding quotes.',
-  )
-
-  /** Source or destination token reference. */
-  export const Token = Schema.describe(
-    z.object({
-      address: z
-        .string()
-        .check(
-          z.describe('Contract address, mint, or issuer address on the token chain.'),
-          z.meta({ examples: ['0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'] }),
-        ),
-      currency: z
-        .string()
-        .check(
-          z.describe('Monetary denomination represented by this token.'),
-          z.meta({ examples: ['USD'] }),
-        ),
-      decimals: z
-        .number()
-        .check(
-          z.int(),
-          z.gte(0),
-          z.describe('Number of decimal places this token uses.'),
-          z.meta({ examples: [6] }),
-        ),
-      metadata: z
-        .record(z.string(), z.string())
-        .check(
-          z.describe('Curated display or lookup metadata for this token.'),
-          z.meta({ examples: [{ coingeckoId: 'usd-coin' }] }),
-        ),
-      name: z
-        .string()
-        .check(z.describe('Human-readable token name.'), z.meta({ examples: ['USD Coin'] })),
-      standard: z
-        .string()
-        .check(z.describe('Token standard on the token chain.'), z.meta({ examples: ['ERC-20'] })),
-      symbol: z
-        .string()
-        .check(z.describe('Short token ticker symbol.'), z.meta({ examples: ['USDC'] })),
-      tokenKey: z.string().check(
-        z.describe('Stable Tempo token key scoped to the token chain.'),
-        z.meta({
-          examples: ['eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'],
-        }),
-      ),
-      verified: z
-        .boolean()
-        .check(
-          z.describe('Whether Tempo recognizes this token in its funding quote inventory.'),
-          z.meta({ examples: [true] }),
-        ),
-    }),
-    'A normalized token reference for funding quotes.',
-  )
-
-  /** Self-contained source or destination amount in a funding quote. */
-  export const TokenAmount = Schema.describe(
-    Schema.TokenAmount,
-    'A funding amount in base units and human-readable form.',
-  )
-
-  /** Provider summary embedded in a funding quote. */
-  export const ProviderRef = Schema.describe(
-    z.object({
-      id: z
-        .enum(['across', 'relay', 'rhino', 'squid', 'symbiosis'])
-        .check(z.describe('Stable provider id.'), z.meta({ examples: ['relay'] })),
-      kind: z
-        .string()
-        .check(
-          z.describe('Provider category, such as a solver network or aggregator.'),
-          z.meta({ examples: ['solverNetwork'] }),
-        ),
-      name: z
-        .string()
-        .check(z.describe('Human-readable provider name.'), z.meta({ examples: ['Relay'] })),
-      requiresApiKey: z
-        .boolean()
-        .check(
-          z.describe('Whether Tempo needs provider credentials to query or use this provider.'),
-          z.meta({ examples: [false] }),
-        ),
-    }),
-    'Provider metadata embedded in a funding quote.',
-  )
-
-  /** Quote quality signals exposed directly instead of implied by list order. */
-  export const Quality = Schema.describe(
-    z.object({
-      estimatedSeconds: z
-        .optional(z.number().check(z.int(), z.nonnegative()))
-        .check(
-          z.describe('Estimated settlement time in seconds, when known.'),
-          z.meta({ examples: [2] }),
-        ),
-      liquiditySource: z
-        .string()
-        .check(
-          z.describe('Provider source for the live quote quality signal.'),
-          z.meta({ examples: ['providerQuote'] }),
-        ),
-      sourceDetail: z
-        .optional(z.string())
-        .check(
-          z.describe('Provider-specific source or endpoint detail for the quality signal.'),
-          z.meta({ examples: ['providerEndpoint'] }),
-        ),
-      tier: z
-        .enum(['liquid', 'thin'])
-        .check(
-          z.describe('Machine-readable quality tier for a successful quote.'),
-          z.meta({ examples: ['liquid'] }),
-        ),
-    }),
-    'Machine-readable liquidity, fee, and source signals for a successful quote.',
-  )
-
-  /** Provider quote freshness data. */
-  export const QuoteDetails = Schema.describe(
-    z.object({
-      expiresAt: z
-        .optional(z.iso.datetime())
-        .check(
-          z.describe('Timestamp after which the provider quote is no longer valid.'),
-          z.meta({ examples: ['2026-01-01T00:01:00Z'] }),
-        ),
-      sampledAt: z.iso
-        .datetime()
-        .check(
-          z.describe('Timestamp for the live quote probe.'),
-          z.meta({ examples: ['2026-01-01T00:00:00Z'] }),
-        ),
-    }),
-    'Freshness data for a provider funding quote.',
-  )
-
-  /** Successful live funding quote. */
-  export const FundingQuote = Schema.describe(
-    z.object({
-      destinationAmount: TokenAmount.check(z.describe('Expected destination amount.')),
-      destinationAmountMin: z
-        .optional(TokenAmount)
-        .check(
-          z.describe(
-            'Provider-derived minimum destination amount. Symbiosis and Squid quotes use a fixed 1% slippage tolerance.',
-          ),
-        ),
-      destinationChain: Chain.check(z.describe('Destination chain, always Tempo mainnet in V1.')),
-      destinationToken: Token.check(z.describe('Tempo token expected from this quote.')),
-      id: z
-        .string()
-        .check(
-          z.describe('Stable deterministic funding quote id.'),
-          z.meta({ examples: ['base-usdc-tempo-usdce-relay'] }),
-        ),
-      provider: ProviderRef,
-      quality: Quality,
-      quote: QuoteDetails,
-      sourceAmount: TokenAmount,
-      sourceChain: Chain.check(z.describe('Chain where the caller currently holds funds.')),
-      sourceToken: Token.check(z.describe('Token the caller currently holds.')),
-    }),
-    'One successful provider-specific funding quote.',
-  )
-
-  /** Funding quote provider catalog entry. */
-  export const Provider = Schema.describe(
-    z.object({
-      id: z
-        .enum(['across', 'relay', 'rhino', 'squid', 'symbiosis'])
-        .check(z.describe('Stable provider id.'), z.meta({ examples: ['relay'] })),
-      kind: z
-        .string()
-        .check(z.describe('Provider category.'), z.meta({ examples: ['solverNetwork'] })),
-      name: z
-        .string()
-        .check(z.describe('Human-readable provider name.'), z.meta({ examples: ['Relay'] })),
-      requiresApiKey: z
-        .boolean()
-        .check(
-          z.describe('Whether Tempo needs provider credentials to query or use this provider.'),
-          z.meta({ examples: [false] }),
-        ),
-      status: z
-        .enum(['configured', 'unconfigured'])
-        .check(
-          z.describe(
-            '`configured` means live quotes are enabled for this deployment. `unconfigured` means the provider is supported but unavailable here.',
-          ),
-          z.meta({ examples: ['configured', 'unconfigured'] }),
-        ),
-    }),
-    'One funding quote provider.',
-  )
-
-  /** Chain inventory entry returned by the funding chains endpoint. */
-  export const ChainInventory = Schema.describe(
-    z.extend(Chain, {
-      tokens: z.array(Token).check(z.describe('Stablecoins known on this source chain.')),
-    }),
-    'One source chain and its known stablecoin inventory.',
-  )
-
-  /** Schemas for the quoteFunding operation. */
-  export namespace quoteFunding {
-    /** Query parameters for live funding quotes. */
-    export const Query = z
-      .strictObject({
-        destinationToken: z
-          .optional(z.string())
-          .check(
-            z.describe(
-              'Tempo destination token symbol, address, or token key. Defaults to USDC.e.',
-            ),
-            z.meta({ examples: ['USDC.e'] }),
-          ),
-        provider: z
-          .optional(z.enum(['across', 'relay', 'rhino', 'squid', 'symbiosis']))
-          .check(
-            z.describe(
-              'Only request a quote from this provider. Supported ids are `across`, `relay`, `rhino`, `squid`, and `symbiosis`; omit it to query every configured provider.',
-            ),
-            z.meta({ examples: ['relay'] }),
-          ),
-        sourceAmount: z
-          .string()
-          .check(
-            z.regex(/^(?=.*[1-9])\d+(\.\d+)?$/),
-            z.describe(
-              'Positive source token amount. Base units by default, so 1 USDC is `1000000`.',
-            ),
-            z.meta({ examples: ['1000000'] }),
-          ),
-        sourceAmountUnits: z
-          ._default(z.enum(['baseUnits', 'decimal']), 'baseUnits')
-          .check(
-            z.describe('Whether `sourceAmount` is base units or a human-readable decimal.'),
-            z.meta({ examples: ['baseUnits', 'decimal'] }),
-          ),
-        sourceChain: z
-          .string()
-          .check(
-            z.minLength(1),
-            z.describe(
-              'Source chain alias or stable id, such as `base`, `solana`, or `eip155:8453`.',
-            ),
-            z.meta({ examples: ['base', 'eip155:8453'] }),
-          ),
-        sourceToken: z
-          .string()
-          .check(
-            z.minLength(1),
-            z.describe(
-              'Source token symbol, contract address, or Tempo token key. Lookup is scoped to `sourceChain`; non-EVM addresses are case-sensitive. An unknown token returns an empty list.',
-            ),
-            z.meta({ examples: ['USDC', '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'] }),
-          ),
-      })
-      .check(z.describe('Query parameters for live funding quotes into Tempo.'))
-
-    /** Non-paginated list of successful funding quotes. */
-    export const Response = Schema.describe(
-      z.object({
-        data: z.array(FundingQuote).check(z.describe('Successful live funding quotes.')),
-      }),
-      'A non-paginated list of successful live funding quotes.',
-    )
-  }
-
-  /** Schemas for the listFundingChains operation. */
-  export namespace listFundingChains {
-    /** Non-paginated source-chain inventory. */
-    export const Response = Schema.describe(
-      z.object({
-        data: z
-          .array(ChainInventory)
-          .check(z.describe('Source chains and stablecoins supported by funding quotes.')),
-      }),
-      'A non-paginated list of source chains and stablecoin inventory.',
-    )
-  }
-
-  /** Schemas for the listProviders operation. */
-  export namespace listProviders {
-    /** Non-paginated funding quote provider catalog. */
-    export const Response = Schema.describe(
-      z.object({
-        data: z.array(Provider).check(z.describe("Providers in Tempo's funding quote catalog.")),
-      }),
-      'A non-paginated list of funding quote providers.',
-    )
-  }
-}
-
-const fundingQuoteResponseExample = (() => {
-  const [candidate] = FundingQuotes.listQuoteCandidates({
-    provider: 'relay',
-    sourceAmount: '1000000',
-    sourceAmountUnits: 'baseUnits',
-    sourceChain: 'base',
-    sourceToken: 'USDC',
-  })
-  if (!candidate) throw new Error('Missing Relay funding quote example candidate')
-  return {
-    data: [
-      {
-        destinationAmount: Value.tokenAmount({
-          baseUnits: '979295',
-          currency: candidate.destinationToken.currency,
-          decimals: candidate.destinationToken.decimals,
-        }),
-        destinationAmountMin: Value.tokenAmount({
-          baseUnits: '939242',
-          currency: candidate.destinationToken.currency,
-          decimals: candidate.destinationToken.decimals,
-        }),
-        destinationChain: candidate.destinationChain,
-        destinationToken: candidate.destinationToken,
-        id: candidate.id,
-        provider: candidate.provider,
-        quality: {
-          estimatedSeconds: 1,
-          liquiditySource: 'providerQuote',
-          sourceDetail: 'relay:quote-v2',
-          tier: 'liquid',
-        },
-        quote: {
-          sampledAt: '2026-01-01T00:00:00.000Z',
-        },
-        sourceAmount: Value.tokenAmount({
-          baseUnits: candidate.sourceAmount.amount,
-          currency: candidate.sourceToken.currency,
-          decimals: candidate.sourceToken.decimals,
-        }),
-        sourceChain: candidate.sourceChain,
-        sourceToken: candidate.sourceToken,
-      },
-    ],
-  }
-})() satisfies z.output<typeof schema.quoteFunding.Response>
-
-const fundingChainsResponseExample = {
-  data: FundingQuotes.listChains(),
-} satisfies z.output<typeof schema.listFundingChains.Response>
-
-const providersResponseExample = {
-  data: FundingQuotes.listProviders().map((provider) => ({
-    ...provider,
-    status: 'configured' as const,
-  })),
-} satisfies z.output<typeof schema.listProviders.Response>
-
-/** Mounts live funding quotes and their supporting inventory endpoints. */
-export function funding(options: funding.Options = {}) {
-  return new Hono<App.Environment>()
-    .get(
-      '/v1/funding/quotes',
-      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
-      OpenApi.validate('query', schema.quoteFunding.Query, {
-        code: 'query_invalid',
-        message: 'Invalid query parameters',
-      }),
-      OpenApi.describeRoute({
-        description:
-          'Returns live quotes for funding Tempo with a stablecoin. Omit `provider` to query all configured providers. Provider minimums can use provider-specific slippage policies; Symbiosis and Squid use 1%. This endpoint does not execute a transfer.',
-        operationId: 'quoteFunding',
-        responses: OpenApi.responses({
-          errors: {
-            400: { codes: ['query_invalid'] },
-            502: {
-              codes: ['upstream_error'],
-              description:
-                'No quote succeeded and at least one matching provider failed unexpectedly.',
-            },
-          },
-          success: {
-            description: 'Live funding quotes. An empty list means no provider returned a quote.',
-            example: fundingQuoteResponseExample,
-            schema: schema.quoteFunding.Response,
-          },
-        }),
-        summary: 'Get funding quotes',
-        tags: ['Funding'],
-      }),
-      async (c) => {
-        if (Auth.narrowAccess) return Auth.paidAccessError(c)
-        if (OpenApi.narrowValidation)
-          return OpenApi.validationError(c, {
-            code: 'query_invalid',
-            message: 'Invalid query parameters',
-          })
-
-        const query = c.req.valid('query')
-        const attempts: FundingQuotes.ProviderAttempt[] = []
-        try {
-          c.header('Cache-Control', 'no-store')
-          return c.json(
-            Response.validated(schema.quoteFunding.Response, {
-              data: await FundingQuotes.listQuotes({
-                adapters: options.adapters,
-                adapterTimeoutMs: options.adapterTimeoutMs,
-                cache: { bypass: cacheBypass(c.req.raw) },
-                destinationToken: query.destinationToken,
-                onAttempt: (attempt) => attempts.push(attempt),
-                provider: query.provider,
-                sourceAmount: query.sourceAmount,
-                sourceAmountUnits: query.sourceAmountUnits,
-                sourceChain: query.sourceChain,
-                sourceToken: query.sourceToken,
-              }),
-            }),
-            200,
-          )
-        } catch (cause) {
-          const message = requestErrorMessage(cause)
-          if (message) return Response.error(c, { code: 'query_invalid', message, status: 400 })
-          if (cause instanceof FundingQuotes.ProviderQuoteError) {
-            const failures = cause.failures.map(FundingQuoteProviders.providerFailure)
-            const failure = failures[0]
-            if (failure) c.set('providerFailure', failure)
-            if (failures.length > 1) c.set('providerFailures', failures)
-            return Response.error(c, {
-              code: 'upstream_error',
-              message: 'Quote providers could not complete the request.',
-              status: 502,
-            })
-          }
-          throw cause
-        } finally {
-          if (attempts.length > 0)
-            c.set('fundingProviderAttempts', attempts.map(fundingProviderAttempt))
-        }
-      },
-    )
-    .get(
-      '/v1/funding/chains',
-      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
-      OpenApi.describeRoute({
-        description:
-          'Lists the source chains and stablecoins you can use when requesting a funding quote.',
-        operationId: 'listFundingChains',
-        responses: OpenApi.responses({
-          success: {
-            description: 'Supported source chains and stablecoins.',
-            example: fundingChainsResponseExample,
-            schema: schema.listFundingChains.Response,
-          },
-        }),
-        summary: 'List funding chains',
-        tags: ['Funding'],
-      }),
-      Cache.response<App.Environment>({
-        cacheControl: Cache.policies.stable,
-        name: 'tempo-api:funding-chains:v2',
-        key: (c) => c.req.url,
-      }),
-      (c) => {
-        if (Auth.narrowAccess) return Auth.paidAccessError(c)
-        return c.json(
-          Response.validated(schema.listFundingChains.Response, {
-            data: FundingQuotes.listChains(),
-          }),
-          200,
-        )
-      },
-    )
-    .get(
-      '/v1/funding/providers',
-      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
-      OpenApi.describeRoute({
-        description:
-          'Lists funding quote providers and whether live quoting is configured for this deployment.',
-        operationId: 'listFundingProviders',
-        responses: OpenApi.responses({
-          success: {
-            description: 'Funding quote providers supported by Tempo.',
-            example: providersResponseExample,
-            schema: schema.listProviders.Response,
-          },
-        }),
-        summary: 'List funding providers',
-        tags: ['Funding'],
-      }),
-      Cache.response<App.Environment>({
-        cacheControl: Cache.policies.stable,
-        name: 'tempo-api:funding-providers:v1',
-        key: (c) => c.req.url,
-      }),
-      (c) => {
-        if (Auth.narrowAccess) return Auth.paidAccessError(c)
-        return c.json(
-          Response.validated(schema.listProviders.Response, {
-            data: FundingQuotes.listProviders({ adapters: options.adapters }),
-          }),
-          200,
-        )
-      },
-    )
-}
-
-export declare namespace funding {
-  /** Options for live funding quotes. */
-  type Options = {
-    /** Provider adapters used to request live quotes. */
-    adapters?: FundingQuotes.ProviderAdapters | undefined
-    /** Per-provider quote timeout in milliseconds. */
-    adapterTimeoutMs?: number | undefined
-  }
-}
-
-function fundingProviderAttempt(
-  attempt: FundingQuotes.ProviderAttempt,
-): Log.FundingProviderAttempt {
-  const operation = FundingQuoteProviders.providerOperation(attempt.provider)
-  if (attempt.outcome !== 'failed')
-    return {
-      durationMs: attempt.durationMs,
-      id: attempt.provider,
-      operation,
-      outcome: attempt.outcome,
-    }
-
-  return {
-    durationMs: attempt.durationMs,
-    failure: FundingQuoteProviders.providerFailure({
-      cause: attempt.cause,
-      provider: attempt.provider,
-    }).failure,
-    id: attempt.provider,
-    operation,
-    outcome: attempt.outcome,
-  }
-}
-
-// Maps caller-input errors to a specific 400 message; anything else rethrows.
-function requestErrorMessage(cause: unknown) {
-  if (cause instanceof FundingQuotes.InvalidAmountError) return 'Invalid `sourceAmount`.'
-  if (cause instanceof FundingQuotes.UnsupportedDestinationTokenError)
-    return 'Unsupported `destinationToken`.'
-  if (cause instanceof FundingQuotes.UnsupportedProviderError) return 'Unsupported `provider`.'
-  if (cause instanceof FundingQuotes.UnsupportedSourceChainError)
-    return 'Unsupported `sourceChain`.'
-  return undefined
-}
-
-function cacheBypass(request: Request) {
-  const directives = (
-    request.headers.get('Cache-Control') ??
-    request.headers.get('Pragma') ??
-    ''
-  ).toLowerCase()
-  return directives.includes('no-cache') || directives.includes('no-store')
-}