tapimo 0.4.4 → 0.5.0

package/src/apps/data/App.ts

@@ -1,15 +1,19 @@
-import { Hono } from 'hono'
+import { type Context, Hono } from 'hono'
+import { matchedRoutes } from 'hono/route'
+import { ZoneRpcAuthentication } from 'ox/tempo'
 import * as z from 'zod/mini'
 
 import type * as Assets from '../../Assets.js'
 import type * as App from '../../App.js'
-import * as Metadata from '../metadata.js'
 import * as Auth from '../../internal/Auth.js'
+import * as EdgeCache from '../../internal/EdgeCache.js'
 import * as Path from '../../internal/Path.js'
 import * as Response from '../../internal/Response.js'
 import * as Schema from '../../internal/Schema.js'
 import * as Tidx from '../../internal/Tidx.js'
 import * as Viem from '../../internal/Viem.js'
+import * as Scope from '../../Scope.js'
+import * as Metadata from '../metadata.js'
 
 import { transactions as transactionActivities } from './routes/activities.js'
 import { addresses } from './routes/addresses.js'
@@ -40,6 +44,10 @@ import { schema as webhookSchema, webhooks } from './routes/webhooks.js'
 export function data(options: data.Options = {}) {
   const { assets, defaultChainId = Viem.defaultChainId, rpc: rpc_option, tidx } = options
 
+  // Zone endpoints are explicit trust boundaries; the API never derives them.
+  const zones = new Map((options.zones ?? []).map((zone) => [zone.chainId, zone]))
+  const dataRouteHandlers = new Set<unknown>()
+
   // The chain ids this deployment serves (built-in public chains plus
   // `defaultChainId` and any explicit `supportedChainIds`). Published on context
   // so handlers with a path `chainId` can guard it too.
@@ -48,6 +56,7 @@ export function data(options: data.Options = {}) {
     ...Object.keys(Tidx.url).map(Number),
     defaultChainId,
     ...(options.supportedChainIds ?? []),
+    ...zones.keys(),
   ])
 
   // Memoize one viem client per resolved upstream (stateless HTTP transports).
@@ -64,8 +73,7 @@ export function data(options: data.Options = {}) {
     return client
   }
 
-  // Memoize TIDX clients per `chainId` so the base URL resolver runs once per
-  // chain instead of on every request.
+  // Memoize TIDX clients per resolved upstream.
   const getTidx = Tidx.createGetClient({ defaultChainId, tidx })
 
   const app = new Hono<App.Environment>()
@@ -82,49 +90,75 @@ export function data(options: data.Options = {}) {
       c.set('tidx', tidx)
       c.set('verifiedTokens', options.verifiedTokens === false ? undefined : (options.verifiedTokens ?? {})) // prettier-ignore
       c.set('webhook', options.webhook === false ? undefined : (options.webhook ?? {}))
+      c.set('zones', zones)
       await next()
     })
-    // Reject a well-formed but unsupported `chainId` before it reaches an
-    // upstream, which would otherwise return an opaque `upstream_error`.
+    // Resolve one chain for every data route before auth and handlers use it.
     .use('*', async (c, next) => {
-      const raw = resolveChainSelector({
-        basePath: c.get('basePath') ?? '',
-        path: c.req.path,
-        query: c.req.query('chainId') ?? c.req.query('chain_id'),
+      const selection = resolveChainSelector({
+        c,
+        defaultChainId,
+        handlers: dataRouteHandlers,
       })
-      if (raw === undefined) return next()
-      // Only reject a well-formed-but-unsupported chain here; malformed values
-      // (e.g. `abc`, `0`) fall through to the route's own query validation.
-      const parsed = Schema.ChainId.safeParse(raw)
-      if (!parsed.success || supportedChainIds.has(parsed.data)) return next()
-      return Response.unsupportedChainId(c, parsed.data, supportedChainIds)
+      if (!selection.matched) return next()
+      if (selection.conflict || selection.invalid)
+        return Response.error(c, {
+          code: 'chain_id_invalid',
+          message: selection.conflict ? 'Conflicting chain ids' : 'Invalid chain id',
+          status: 400,
+        })
+      if (!supportedChainIds.has(selection.chainId))
+        return Response.unsupportedChainId(c, selection.chainId, supportedChainIds)
+      c.set('chainId', selection.chainId)
+      return next()
+    })
+    // Zone data requires an issued scope. Raw RPC may instead forward the
+    // caller's Zone token to the node that enforces account scoping.
+    .use('*', async (c, next) => {
+      if (zones.size === 0) return next()
+      const selection = resolveChainSelector({
+        c,
+        defaultChainId,
+        handlers: dataRouteHandlers,
+      })
+      if (!selection.matched) return next()
+      const chainId = c.get('chainId')
+      if (!zones.has(chainId)) return next()
+
+      const principal = Auth.getPrincipal(c)
+      const scopes = principal?.type === 'api_key' ? principal.apiKey.scopes : undefined
+      const allowed =
+        scopes?.includes(Scope.wildcard) ||
+        scopes?.includes(`zone:${chainId}:read`) ||
+        (selection.rpc && Boolean(c.req.header(ZoneRpcAuthentication.headerName)?.trim()))
+      if (!allowed)
+        return Response.error(c, {
+          code: 'api_key_forbidden',
+          message: selection.rpc
+            ? `Chain id ${chainId} is a zone. Use an API key granting \`zone:${chainId}:read\`, or pass a Zone token via \`X-Authorization-Token\`.`
+            : `Chain id ${chainId} is a zone. Use an API key granting \`zone:${chainId}:read\`.`,
+          status: 403,
+        })
+
+      await next()
+      // Defense in depth for cache misses; pre-auth lookups are disabled by
+      // the route eligibility predicate below.
+      c.set('edgeCache', undefined)
     })
     // Sandbox keys are testnet-only. A chain-scoped data route defaults to
     // mainnet, so a sandbox key that omits `chainId` (or targets mainnet) is
     // refused with a clear message telling the caller to pass a testnet
-    // `chainId`. The relay resolves its chain from the request body, not the
-    // query, so it is skipped and enforces the rule in its sponsor validation.
+    // `chainId`.
     .use('*', async (c, next) => {
-      const rpc = Path.join(c.get('basePath') ?? '', 'rpc')
-      const relay = Path.join(rpc, 'relay')
-      if (c.req.path === relay || c.req.path.startsWith(`${relay}/`)) return next()
-
       const principal = Auth.getPrincipal(c)
       if (principal?.type !== 'api_key' || principal.environment !== 'sandbox') return next()
 
-      const raw = resolveChainSelector({
-        basePath: c.get('basePath') ?? '',
-        path: c.req.path,
-        query: c.req.query('chainId') ?? c.req.query('chain_id'),
+      const selection = resolveChainSelector({
+        c,
+        defaultChainId,
+        handlers: dataRouteHandlers,
       })
-      // Absent falls back to the group default (mainnet); a malformed value
-      // stays with the route's own validator rather than the sandbox message.
-      const chainId = (() => {
-        if (raw === undefined) return defaultChainId
-        const parsed = Schema.ChainId.safeParse(raw)
-        return parsed.success ? parsed.data : undefined
-      })()
-      if (chainId === undefined || !Viem.isMainnet(chainId)) return next()
+      if (!selection.matched || !Viem.isMainnet(c.get('chainId'))) return next()
 
       return Response.error(c, {
         code: 'api_key_forbidden',
@@ -149,7 +183,7 @@ export function data(options: data.Options = {}) {
     .route('/', blocks())
     .route('/', exchanges())
     .route('/', feeAmm())
-    .route('/', funding(options.fundingRoutes))
+    .route('/', funding(options.funding))
     .route('/', indexer())
     .route('/', receipts())
     .route('/', tokenlist())
@@ -162,21 +196,23 @@ export function data(options: data.Options = {}) {
     .route('/', rpc())
     .route('/', coingecko())
     .route('/', blocksByTimestampCompat())
+  const edgeCacheEligible = (c: Context<App.Environment>) => {
+    const selection = resolveChainSelector({ c, defaultChainId, handlers: dataRouteHandlers })
+    return (
+      selection.matched &&
+      !selection.conflict &&
+      !selection.invalid &&
+      !zones.has(selection.chainId)
+    )
+  }
+  for (const route of app.routes) {
+    if (route.method === 'ALL') continue
+    dataRouteHandlers.add(route.handler)
+    if (zones.size > 0) EdgeCache.setEligibility(route.handler, edgeCacheEligible)
+  }
   return Metadata.attach(app, openapi)
 }
 
-function resolveChainSelector(options: {
-  basePath: string
-  path: string
-  query: string | undefined
-}) {
-  const rpc = Path.join(options.basePath, 'rpc')
-  if (options.path === rpc) return undefined
-  if (options.path.startsWith(`${rpc}/`))
-    return options.path.slice(rpc.length + 1).split('/')[0] || undefined
-  return options.query
-}
-
 export declare namespace data {
   /** Options for the data route group. */
   type Options = {
@@ -184,8 +220,8 @@ export declare namespace data {
     assets?: Assets.Assets | undefined
     /** Default Tempo chain id for requests that omit `chainId`. */
     defaultChainId?: Viem.ChainId | undefined
-    /** Funding route provider adapter configuration. Omit to serve static inventory only. */
-    fundingRoutes?: funding.Options | undefined
+    /** Funding quote provider configuration. */
+    funding?: funding.Options | undefined
     /** Tempo RPC options: a static config, or a per-request resolver that routes by request principal to a separate (e.g. public, no-auth) RPC. */
     rpc?: Viem.getClient.Rpc | undefined
     /** Extra chain ids this deployment serves, beyond the built-in public chains and `defaultChainId`. A `chainId` outside this set is rejected with a 400. */
@@ -196,6 +232,19 @@ export declare namespace data {
     verifiedTokens?: VerifiedTokens | false | undefined
     /** Webhook feature configuration. Enabled by default (rows live in `db`); pass `false` to disable, leaving `/webhooks` mounted but returning `404` and hidden from the OpenAPI document. */
     webhook?: Webhook | false | undefined
+    /**
+     * Zone chains served by this deployment. REST and TIDX require a
+     * `zone:<chainId>:read` scope; raw RPC may forward a Zone token instead.
+     */
+    zones?: readonly Zone[] | undefined
+  }
+
+  /** One zone chain served by this deployment. */
+  type Zone = {
+    /** Zone chain id. Consumer-supplied literal; the API never derives zone chain ids. */
+    chainId: number
+    /** Zone RPC used when forwarding a caller-supplied Zone token. */
+    forwardRpcUrl: string
   }
 
   /** Verified-token feature configuration. */
@@ -219,6 +268,66 @@ export declare namespace data {
   }
 }
 
+function resolveChainSelector(options: {
+  c: Context<App.Environment>
+  defaultChainId: Viem.ChainId
+  handlers: ReadonlySet<unknown>
+}) {
+  let matched = false
+  let path: string | undefined
+  let rpc = false
+  for (const route of matchedRoutes(options.c)) {
+    if (!options.handlers.has(route.handler)) continue
+    matched = true
+    const selector = pathChainSelector(route.path, options.c.req.path)
+    if (selector.name === undefined) continue
+    path = selector.value
+    rpc = selector.name === 'chain'
+    break
+  }
+
+  if (!matched)
+    return {
+      chainId: options.defaultChainId,
+      conflict: false,
+      invalid: false,
+      matched: false,
+      rpc: false,
+    }
+
+  const search = new URL(options.c.req.url).searchParams
+  const raw = [
+    ...(path === undefined ? [] : [path]),
+    ...(rpc ? [] : search.getAll('chainId')),
+    ...(rpc ? [] : search.getAll('chain_id')),
+  ]
+  const parsed = raw.map((value) => Schema.ChainId.safeParse(value))
+  const chainIds = [...new Set(parsed.flatMap((result) => (result.success ? [result.data] : [])))]
+  return {
+    chainId: chainIds[0] ?? options.defaultChainId,
+    conflict: chainIds.length > 1,
+    invalid: parsed.some((result) => !result.success),
+    matched: true,
+    rpc,
+  }
+}
+
+function pathChainSelector(routePath: string, requestPath: string) {
+  const route = routePath.split('/')
+  const request = requestPath.split('/')
+  for (let index = 0; index < route.length; index++) {
+    const segment = route[index] ?? ''
+    for (const name of ['chainId', 'chain'] as const) {
+      const prefix = `:${name}`
+      if (!segment.startsWith(prefix)) continue
+      const suffix = segment.slice(prefix.length)
+      if (suffix !== '' && suffix !== '?' && !suffix.startsWith('{')) continue
+      return { name, value: request[index] || undefined }
+    }
+  }
+  return { name: undefined, value: undefined }
+}
+
 /**
  * The OpenAPI metadata this group owns: its operation tags and the outbound
  * `webhooks` block. Tagged onto the {@link data} instance so `App.create`
@@ -231,8 +340,7 @@ const openapi = {
     { name: 'Blocks', description: 'The ordered batches of transactions making up the chain.' },
     { name: 'Exchange', description: "Tempo's built-in stablecoin exchange: pairs, swaps, orders, prices." }, // prettier-ignore
     { name: 'Fee AMM', description: 'Pools that convert stablecoins to pay fees.' },
-    { name: 'Funding', description: 'Routes and inventory for moving stablecoins into Tempo.' },
-    { name: 'Providers', description: 'Provider metadata, capabilities, and integration status.' },
+    { name: 'Funding', description: 'Live quotes and supported inputs for funding Tempo.' },
     { name: 'Tokens', description: 'TIP-20 token details, supply, and holders.' },
     { name: 'Transactions', description: 'Transactions submitted to Tempo, and their receipts.' },
     { name: 'Transfers', description: 'Token movements from executing transactions.' },
@@ -252,7 +360,6 @@ const openapi = {
         'Exchange',
         'Fee AMM',
         'Funding',
-        'Providers',
         'Tokens',
         'Transactions',
         'Transfers',

package/src/apps/data/FundingQuoteProviders.test.ts

@@ -0,0 +1,151 @@
+import * as FundingQuotes from '../../internal/FundingQuotes.js'
+import * as FundingQuoteProviders from './FundingQuoteProviders.js'
+
+const now = () => new Date('2026-01-01T00:00:00.000Z')
+
+describe('FundingQuoteProviders', () => {
+  test('maps successful Relay quotes to available quote probes', async () => {
+    const requests: RecordedRequest[] = []
+    const candidate = quoteCandidate()
+    const fetch = recordingFetch(requests, async () =>
+      jsonResponse({
+        details: {
+          currencyOut: {
+            amount: '990000',
+            minimumAmount: '980000',
+          },
+          timeEstimate: 15,
+          totalImpact: { percent: '-1.20' },
+        },
+      }),
+    )
+    const adapter = FundingQuoteProviders.relay({
+      apiKey: 'relay-api-key',
+      fetch,
+      now,
+      userAddress: '0x1111111111111111111111111111111111111111',
+    })
+
+    const result = await adapter.probeQuote(probeInput(candidate), new AbortController().signal)
+
+    expect(requests.map((request) => request.url.pathname)).toEqual(['/quote/v2'])
+    expect(new Headers(requests[0]?.init?.headers).get('x-api-key')).toBe('relay-api-key')
+    expect(jsonRequestBody(requests[0])).toMatchObject({
+      amount: '1000000',
+      destinationChainId: 4217,
+      destinationCurrency: candidate.destinationToken.address,
+      originChainId: 8453,
+      originCurrency: candidate.sourceToken.address,
+      tradeType: 'EXACT_INPUT',
+      user: '0x1111111111111111111111111111111111111111',
+    })
+    expect(result).toMatchObject({
+      minimumOutputAmount: '980000',
+      outputAmount: '990000',
+      outputAmountFormatted: '0.99',
+      quality: {
+        estimatedSeconds: 15,
+        liquiditySource: 'providerQuote',
+        sourceDetail: 'relay:quote-v2',
+        tier: 'liquid',
+      },
+      sampledAt: '2026-01-01T00:00:00.000Z',
+      status: 'available',
+    })
+  })
+
+  test('calls the runtime fetch method with its global receiver', async () => {
+    const candidate = quoteCandidate()
+    const fetch = vi.fn(function (this: unknown) {
+      expect(this).toBe(globalThis)
+      return Promise.resolve(
+        jsonResponse({
+          details: {
+            currencyOut: { amount: '990000', minimumAmount: '980000' },
+            timeEstimate: 15,
+          },
+        }),
+      )
+    })
+    vi.stubGlobal('fetch', fetch)
+
+    try {
+      const adapter = FundingQuoteProviders.relay({
+        now,
+        userAddress: '0x1111111111111111111111111111111111111111',
+      })
+      const result = await adapter.probeQuote(probeInput(candidate), new AbortController().signal)
+
+      expect(result.outputAmount).toBe('990000')
+      expect(fetch).toHaveBeenCalledTimes(1)
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+})
+
+type RecordedRequest = {
+  init: RequestInit | undefined
+  url: URL
+}
+
+function quoteCandidate(): FundingQuotes.QuoteProbeInput['candidate'] {
+  const [candidate] = FundingQuotes.listQuoteCandidates({
+    provider: 'relay',
+    sourceAmount: '1000000',
+    sourceAmountUnits: 'baseUnits',
+    sourceToken: 'USDC',
+    sourceChain: 'base',
+  })
+  if (!candidate) throw new Error('Missing Relay quote candidate')
+  return candidate
+}
+
+function probeInput(
+  candidate: FundingQuotes.QuoteProbeInput['candidate'],
+): FundingQuotes.QuoteProbeInput {
+  return {
+    candidate,
+    cache: { bypass: false },
+    destinationChain: candidate.destinationChain,
+    destinationToken: candidate.destinationToken,
+    request: {
+      provider: candidate.provider.id,
+      sourceAmount: candidate.sourceAmount.amount,
+      sourceAmountUnits: 'baseUnits',
+      sourceChain: candidate.sourceChain.id,
+      sourceToken: candidate.sourceToken.symbol,
+    },
+    sourceAmount: candidate.sourceAmount,
+    sourceChain: candidate.sourceChain,
+    sourceToken: candidate.sourceToken,
+  }
+}
+
+function recordingFetch(
+  requests: RecordedRequest[],
+  respond: (request: RecordedRequest) => Response | Promise<Response>,
+): typeof globalThis.fetch {
+  return async (input, init) => {
+    const request = { init, url: toUrl(input) }
+    requests.push(request)
+    return respond(request)
+  }
+}
+
+function toUrl(input: Parameters<typeof globalThis.fetch>[0]) {
+  if (input instanceof Request) return new URL(input.url)
+  return new URL(String(input))
+}
+
+function jsonResponse(body: unknown, status = 200) {
+  return new Response(JSON.stringify(body), {
+    headers: { 'content-type': 'application/json' },
+    status,
+  })
+}
+
+function jsonRequestBody(request: RecordedRequest | undefined) {
+  if (typeof request?.init?.body !== 'string') throw new Error('Expected JSON request body')
+  return JSON.parse(request.init.body) as unknown
+}