tapimo 0.0.0 → 0.0.2

package/src/App.ts

@@ -0,0 +1,855 @@
+import type { Context, MiddlewareHandler } from 'hono'
+import { Hono } from 'hono'
+import { compress as hono_compress } from 'hono/compress'
+import { cors as hono_cors } from 'hono/cors'
+import { HTTPException } from 'hono/http-exception'
+import { requestId, type RequestIdVariables } from 'hono/request-id'
+import { generateSpecs } from 'hono-openapi'
+import { Handler } from 'vocs/server'
+import * as z from 'zod/mini'
+
+import * as ApiKey from './ApiKey.js'
+import * as Assets from './Assets.js'
+import * as Auth from './internal/Auth.js'
+import * as EdgeCache from './internal/EdgeCache.js'
+import * as Log from './internal/Log.js'
+import * as MetricSink from './internal/MetricSink.js'
+import type * as Metrics from './Metrics.js'
+import * as OpenApi from './internal/OpenApi.js'
+import * as Store from './internal/Store.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 Timing from './internal/Timing.js'
+import * as Viem from './internal/Viem.js'
+
+import openrpcSpec from './openrpc.json' with { type: 'json' }
+
+import { transactions as transactionActivities } from './apps/activities.js'
+import { addresses } from './apps/addresses.js'
+import { blocks, blocksByTimestampCompat } from './apps/blocks.js'
+import { coingecko } from './apps/coingecko.js'
+import { exchanges } from './apps/exchanges.js'
+import { feeAmm } from './apps/fee-amm.js'
+import { indexer } from './apps/indexer.js'
+import { receipts } from './apps/receipts.js'
+import { rpc as rpcApp } from './apps/rpc.js'
+import { tokens } from './apps/tokens.js'
+import { transactions } from './apps/transactions.js'
+import { transfers } from './apps/transfers.js'
+import { verifiedTokens } from './apps/verified-tokens.js'
+import { tokenlist } from './apps/tokenlist.js'
+import { schema as webhookSchema, webhooks } from './apps/webhooks.js'
+
+/** Hono environment variables set by the Tempo API app. */
+export type Environment = {
+  Variables: Auth.Variables &
+    RequestIdVariables & {
+      /** Base path for this API app. */
+      basePath: string
+      /** Default Tempo chain id for this API app. */
+      chainId: Viem.ChainId
+      /** Gets one static API asset. */
+      getAsset: GetAsset
+      /** Gets a Tempo RPC client for a chain id. */
+      getClient: Viem.GetClient
+      /** Gets a TIDX query client for a chain id. */
+      getTidx: Tidx.GetClient
+      /** Configured RPC client options used by the raw RPC passthrough. */
+      rpc: Viem.getClient.Rpc | undefined
+      /** Cache store: handler `Store.memoize` and the edge response cache. */
+      store: Store.Store
+      /** Chain ids this deployment serves; a request outside this set is rejected with a clear 400. */
+      supportedChainIds: ReadonlySet<number>
+      /** Configured TIDX client options used by the raw indexer passthrough. */
+      tidx: Tidx.getClient.Tidx | undefined
+      /** Verified-token feature configuration (state store + refresh window), or undefined when verified tokens are bundle-backed. */
+      verifiedTokens: { refreshMs?: number | undefined; store: Store.State } | undefined
+      /** Webhook feature configuration (state store, etc.), or undefined when webhooks are disabled. */
+      webhook: { maxPerOwner?: number | undefined; store: Store.State } | undefined
+    } & EdgeCache.Variables &
+    Log.Variables &
+    Timing.Variables
+}
+
+/**
+ * Tempo API Hono app with shared API dependencies. Inferred from `create`.
+ * The `path` generic is pinned to `'/'` (its default) so the resulting Hono
+ * `BasePath` is a concrete literal; without the explicit type argument
+ * `ReturnType<typeof create>` would resolve `path` to its constraint
+ * (`string`), and Hono's `MergePath<string, '/foo'>` would surface every
+ * endpoint key as `` `… ${string}/foo` `` — which can be satisfied but never
+ * autocompleted.
+ */
+export type App = ReturnType<typeof create<'/'>>
+
+/** Node.js request listener for `node:http` and compatible interfaces. */
+export type Listener = (incoming: unknown, outgoing: unknown) => Promise<void>
+
+/** HTTP endpoints owned by Tempo API handlers, used for typed auth overrides. */
+export type Endpoint = Auth.Endpoint<App>
+
+/** One static API asset resolved from packaged data. */
+export type Asset = {
+  /** Loaded asset response. */
+  response: Response
+  /** Absolute public API URL for the asset (scheme + host + path). */
+  uri: string
+}
+
+/** Gets one static API asset for a chain, or undefined when it is missing. */
+export type GetAsset = (
+  chainId: Viem.ChainId,
+  path: string,
+) => Asset | undefined | Promise<Asset | undefined>
+
+/** Top-level OpenAPI `info.description`, rendered above the reference. */
+const infoDescription = 'REST API for reading and interacting with Tempo'
+
+/** Creates the Tempo API Hono app. */
+export function create<const path extends string = '/'>(options: create.Options<path> = {}) {
+  const { assets, defaultChainId = Viem.defaultChainId, path = '/' as path, rpc } = options
+
+  // Capture as the literal generic so `Hono.basePath(...)` preserves the
+  // typed prefix. testClient's `Client<T, ...>` inference collapses to a
+  // `Record<string, ...>` index signature when the BasePath generic is the
+  // unconstrained `string`, which strips per-route typing.
+  const basePath = Path.normalize(path) as path
+
+  // The cache store backs both caching layers: handler `memoize` (upstream
+  // RPC/indexer reads, keyed by data identity) and the edge response cache
+  // (whole responses, keyed by URL). Both are caches, not durable storage — a
+  // miss simply re-fetches — so it defaults to in-memory. Point it at a
+  // colo-local store (`Store.cache(caches.default)`) in production; never the
+  // Durable Object, or edge-cache hits re-incur the round-trip they skip.
+  // Authoritative state (webhooks) lives in its own state store, configured
+  // separately via `options.webhook.store` (a Durable Object in production).
+  const store = options.cache?.store ?? Store.memory()
+
+  // Memoize one viem client per resolved upstream. Clients are stateless HTTP
+  // transports, so reusing them avoids per-request construction cost. The cache
+  // key is the resolved output (`url` + `basicAuth` + `chainId`), not the
+  // principal, so a resolver `rpc` may branch on any principal field while
+  // client cardinality stays bounded by the number of distinct upstreams —
+  // callers that resolve to the same upstream share a client.
+  const clients = new Map<string, ReturnType<typeof Viem.getClient>>()
+  const getClient = (chainId = defaultChainId, principal: Auth.Principal | null = null) => {
+    // Resolve to derive the cache key; `Viem.getClient` re-resolves to build the
+    // client on a miss. `resolve` is pure and cheap, so the extra call is free.
+    const { url, basicAuth } = Viem.resolve(rpc, { chainId, principal })
+    const cacheKey = `${url}|${basicAuth ?? ''}|${chainId}`
+    const existing = clients.get(cacheKey)
+    if (existing) return existing
+    const client = Viem.getClient({ chainId, principal, rpc })
+    clients.set(cacheKey, client)
+    return client
+  }
+
+  // Memoize TIDX clients per `chainId` so the base URL resolver runs once per
+  // chain instead of on every request. The same factory backs the scheduled
+  // webhook poller (`Webhooks.createPoller`), keeping client construction in
+  // one place.
+  const getTidx = Tidx.createGetClient({ defaultChainId, tidx: options.tidx })
+
+  // Build the app in two phases: register middleware imperatively, then chain
+  // route mounts so the merged Hono schema flows through the return type. The
+  // chained type is what makes `testClient(create())` produce typed path
+  // proxies in tests. `basePath` is typed as the literal `path` generic above,
+  // which keeps the merged schema keys typed (vs. the unconstrained `string`
+  // basePath that would collapse them to an index signature).
+  const base = new Hono<Environment>().basePath(basePath)
+
+  if (options.cors !== false)
+    base.use('*', hono_cors(typeof options.cors === 'object' ? options.cors : undefined))
+  if (options.compress)
+    base.use(
+      '*',
+      hono_compress(typeof options.compress === 'object' ? options.compress : undefined),
+    )
+  base.use('*', requestId({ headerName: 'tempo-request-id' }))
+  // One canonical structured log line per request, plus request metrics.
+  // Registered after `requestId` (the entry embeds it) and before the timing and
+  // edge-cache layers so the entry covers edge-cache hits and includes the
+  // Server-Timing metrics collected inside the request.
+  //
+  // Logging and metrics are separate concerns sharing one entry: `logger` emits
+  // the structured log line, the request metrics sink records HTTP series, and
+  // the optional `metrics.analytics` hook ships the full wide-event entry. The
+  // webhook poller/queue run outside this app, so they wire their own
+  // `MetricSink.webhooks` sink over the same backend.
+  // Wire the request (HTTP) metrics sink over the provided backend.
+  const recordRequest = options.metrics ? MetricSink.requests(options.metrics) : undefined
+  // Per-request analytics hook (e.g. ClickHouse wide events), if the backend
+  // provides one. Its promise is returned from `emit` below so `Log.middleware`
+  // keeps it alive via `waitUntil` without holding the response open.
+  const recordAnalytics = options.metrics?.analytics
+  // Resolve `logger` to a single emit sink: a custom function as-is, `true` to
+  // the level-matched console emit, a level string to that emit filtered to the
+  // level and above (e.g. `'warn'` drops successful-request info lines).
+  const log: Log.Emit | undefined = (() => {
+    if (typeof options.logger === 'function') return options.logger
+    if (options.logger === true) return Log.emit
+    if (typeof options.logger === 'string') return Log.withMinLevel(options.logger)
+    return undefined
+  })()
+  if (log || recordRequest || recordAnalytics)
+    base.use(
+      '*',
+      Log.middleware<Environment>({
+        emit: (entry) => {
+          log?.(entry)
+          recordRequest?.(entry)
+          // Return the analytics promise so `Log.middleware` extends the
+          // response with `waitUntil`; otherwise the async sink's `queue.send`
+          // is a floating promise the Workers runtime cancels once the response
+          // is returned, and no analytics ever reach the sink.
+          return recordAnalytics?.(entry)
+        },
+      }),
+    )
+  // The chain ids this deployment serves: the built-in public chains plus the
+  // configured `defaultChainId` and any explicit `supportedChainIds`. Exposed on
+  // context so mounted apps with a path `chainId` (e.g. GeckoTerminal) can guard
+  // it too.
+  const supportedChainIds = new Set<number>([
+    ...Object.keys(Viem.url).map(Number),
+    ...Object.keys(Tidx.url).map(Number),
+    defaultChainId,
+    ...(options.supportedChainIds ?? []),
+  ])
+
+  base.use('*', Timing.middleware())
+  base.use('*', async (c, next) => {
+    // Put app-level dependencies on Hono context so mounted handlers only
+    // receive request-local state from `c`.
+    c.set('basePath', basePath)
+    c.set('chainId', defaultChainId)
+    c.set('getAsset', createGetAsset({ assets, basePath, origin: new URL(c.req.url).origin }))
+    c.set('getClient', (chainId) => getClient(chainId, Auth.getPrincipal(c)))
+    c.set('getTidx', (chainId) => getTidx(chainId, Auth.getPrincipal(c)))
+    c.set('rpc', rpc)
+    c.set('store', store)
+    c.set('supportedChainIds', supportedChainIds)
+    c.set('tidx', options.tidx)
+    c.set('verifiedTokens', options.verifiedTokens)
+    c.set('webhook', options.webhook)
+    await next()
+  })
+
+  // Reject a syntactically valid `chainId` this deployment does not serve before
+  // it reaches an upstream — an unknown chain otherwise hits the configured
+  // RPC/indexer (a static `tidx.baseUrl` answers for any chain id) and comes
+  // back as an opaque `upstream_error`.
+  base.use('*', async (c, next) => {
+    const raw = c.req.query('chainId') ?? c.req.query('chain_id')
+    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)
+  })
+  // Skip the static asset route entirely when no store is configured; token
+  // logo URIs simply go unresolved.
+  if (assets)
+    base.use('/assets/*', async (c, next) => {
+      const key = stripAssetPath(c.req.path, basePath).replace(/^\/+/, '')
+      const asset = key ? await assets.get(key) : undefined
+      if (!asset) return next()
+      return c.body(asset.body, 200, {
+        'Cache-Control': 'public, max-age=86400',
+        'Content-Type': asset.contentType,
+      })
+    })
+
+  // Safety net: any non-2xx response (auth/validation errors, MPP `402`
+  // challenges, rate-limit `429`s, upstream `502`s, etc.) must never be
+  // cached. This wraps endpoint middleware and handlers registered below.
+  base.use('*', async (c, next) => {
+    await next()
+    if (c.res.status >= 200 && c.res.status < 300) return
+    if (c.res.headers.has('Cache-Control')) return
+    c.res.headers.set('Cache-Control', 'no-store')
+  })
+
+  // Serve GETs from the cache store before user middleware (auth, rate limiting)
+  // runs, so cache hits skip the per-request store round-trips that dominate
+  // latency.
+  if (options.cache?.edge !== false) base.use('*', EdgeCache.middleware<Environment>({ store }))
+
+  const base_routed = base.get('/health', OpenApi.describeRoute({ hide: true }), (c) =>
+    c.json({ status: 'ok' }, 200),
+  )
+
+  for (const middleware of options.middleware ?? []) base_routed.use('*', middleware)
+
+  const app = base_routed
+    .route('/v1/addresses', addresses())
+    .route('/v1/blocks', blocks())
+    .route('/v1/exchange', exchanges())
+    .route('/v1/fee-amm', feeAmm())
+    .route('/v1/indexer', indexer())
+    .route('/v1/tokenlist', tokenlist())
+    .route('/v1/tokens', tokens())
+    .route('/v1/transactions', receipts())
+    .route('/v1/transactions', transactions())
+    .route('/v1/transactions', transactionActivities())
+    .route('/v1/transfers', transfers())
+    .route('/v1/verified-tokens', verifiedTokens())
+    .route('/v1/webhooks', webhooks({ enabled: options.webhook !== undefined }))
+    .route('/rpc', rpcApp())
+    .route('/gecko', coingecko())
+    // Hidden compatibility route for the prior Tempo API's
+    // `GET /chains/:chainId/blocks/by-timestamp` (chain id in the path).
+    .route('/chains', blocksByTimestampCompat())
+
+  const spec = (async () => {
+    // OAS 3.1 `webhooks`: document the signed envelope Tempo API POSTs to subscriber
+    // URLs (an outbound payload, not an endpoint of this API). Only when enabled.
+    const webhooksDoc = (() => {
+      if (!options.webhook) return {}
+      // `io: 'output'` documents the delivered (serialized) shape; `unrepresentable: 'any'`
+      // tolerates the transaction payload's transforms (e.g. lazy fee-token metadata),
+      // which have no JSON-Schema form, by emitting `{}` for those nodes rather than throwing.
+      const envelope = z.toJSONSchema(webhookSchema.Envelope, {
+        io: 'output',
+        target: 'draft-2020-12',
+        unrepresentable: 'any',
+      })
+      delete envelope.$schema
+      const header = (name: string, description: string) => ({
+        description,
+        in: 'header' as const,
+        name,
+        required: true,
+        schema: { type: 'string' as const },
+      })
+      return {
+        webhooks: {
+          event: {
+            post: {
+              description:
+                'When an event you subscribed to happens, Tempo sends this signed message to your webhook URL as an HTTP POST (the same shape is used by `POST /webhooks/:id/ping` so you can test your endpoint). Always verify the `tempo-signature` header before trusting the body, then reply with any 2xx status to confirm you received it. If your endpoint returns a non-2xx status, times out, or redirects, Tempo retries with increasing delays; an endpoint that keeps failing is eventually disabled.',
+              parameters: [
+                header(
+                  'tempo-signature',
+                  'Signature proving the message really came from Tempo. An HMAC-SHA256 of the body using your webhook secret, formatted `t=<unix>,v1=<hex>`. Verify this before trusting the payload.',
+                ),
+                header(
+                  'tempo-event-id',
+                  'A unique, stable id for this event (`evt_…`). The same event may be delivered more than once, so use this id to skip duplicates.',
+                ),
+                header('tempo-event-type', 'What happened: `token:transfer`, `transaction:included`, `log:emitted`, `block:created`, or `ping`.'), // prettier-ignore
+              ],
+              requestBody: {
+                content: { 'application/json': { schema: envelope } },
+                required: true,
+              },
+              responses: { '2xx': { description: 'Delivery acknowledged.' } },
+              summary: 'Webhook event delivery',
+              tags: ['Webhooks'],
+            },
+          },
+        },
+      }
+    })()
+    const generated = await generateSpecs(app, {
+      documentation: {
+        components: {
+          headers: OpenApi.headerComponents,
+          responses: OpenApi.responseComponents,
+          securitySchemes: {
+            apiKey: {
+              description:
+                'Your Tempo API key, sent in the `tempo-api-key` request header. This is the canonical and recommended API-key header.',
+              in: 'header',
+              name: 'tempo-api-key',
+              type: 'apiKey',
+            },
+            bearerAuth: {
+              description: 'Compatibility alternative for API keys: send `Authorization: Bearer <key>`. Prefer the `tempo-api-key` header when your HTTP client supports custom headers.', // prettier-ignore
+              scheme: 'bearer',
+              type: 'http',
+            },
+          },
+        },
+        info: {
+          description: infoDescription,
+          title: 'Tempo API',
+          version: '1.0.0',
+        },
+        security: [{ apiKey: [] }, { bearerAuth: [] }],
+        servers: [
+          ...(options.servers ?? [
+            { url: basePath || '/', description: 'Relative to the host serving this document.' },
+          ]),
+        ],
+        tags: [
+          {
+            name: 'Activities',
+            description: 'A readable feed of what an account did onchain.',
+          },
+          {
+            name: 'Balances',
+            description: 'How much of each token an account holds.',
+          },
+          {
+            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.",
+          },
+          {
+            name: 'Fee AMM',
+            description: 'Pools that convert stablecoins to pay fees.',
+          },
+          {
+            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.',
+          },
+          {
+            name: 'Verified Tokens',
+            description: 'A curated, trusted list of TIP-20 tokens.',
+          },
+          ...(options.webhook
+            ? [
+                {
+                  name: 'Webhooks',
+                  description: 'Get signed callbacks when onchain events happen.',
+                },
+              ]
+            : []),
+          {
+            name: 'Indexer',
+            description: "Run read-only SQL queries against Tempo's indexed data.",
+          },
+          {
+            name: 'RPC',
+            description:
+              'Direct access to the chain over Ethereum JSON-RPC. Not part of the stable API contract; best-effort support only. No compatibility, latency, availability, or data-freshness guarantees. Breaking changes may happen with limited notice.',
+          },
+          {
+            name: 'CoinGecko',
+            description: "Exchange data in CoinGecko's GeckoTerminal format.",
+          },
+        ],
+      },
+    })
+    // Set per-operation `security` and the `402` payment-challenge response from
+    // each route's resolved auth policy (the single source of truth), so the
+    // anonymous option and `402` appear only where the public/MPP lanes are
+    // enabled — not on every operation via the document default.
+    applyAccess(generated.paths, Auth.describeAccess(app))
+    // Point the `/rpc` operation at the OpenRPC document via `x-openrpc`.
+    applyOpenrpcLink(generated.paths, basePath)
+    // Re-order paths so list endpoints appear before get endpoints inside each
+    // tag group in the sidebar. We classify by operation summary, which every
+    // handler sets as either "List ..." or "Get ...". The reference groups by
+    // tag and preserves document path order within a tag, so reordering here
+    // drives the sidebar sub-item order.
+    return { ...generated, ...webhooksDoc, paths: sortPaths(generated.paths) }
+  })()
+
+  app.get('/openapi.json', async (c) => c.json(await spec))
+
+  // The OpenRPC document is a committed build artifact (no runtime generator);
+  // see scripts/openrpc/build.ts and `pnpm openrpc:build`.
+  app.get('/openrpc.json', (c) => c.json(openrpcSpec))
+
+  if (options.docs !== false)
+    app.route(
+      '/',
+      Handler.openApi(
+        {
+          // Inline the OpenRPC doc so vocs expands it without a self-subrequest
+          // (see `inlineOpenrpc`); the public `/openapi.json` keeps the URL ref.
+          spec: spec.then(inlineOpenrpc),
+          sidebar: { collapsed: true },
+          vocs: { logoUrl: OpenApi.logoUrl, title: 'Tempo API Reference', ...options.docs },
+        },
+        { fallback: 'next', css: OpenApi.css },
+      ),
+    )
+
+  app.notFound((c) =>
+    Response.error(c, { code: 'not_found', message: 'Route not found', status: 404 }),
+  )
+
+  app.onError((cause, c) => {
+    if (cause instanceof HTTPException) return errorFromException(c, cause)
+
+    // Redact any leaked API-key token from the logged error/stack.
+    console.error(
+      ApiKey.redact(cause instanceof Error ? (cause.stack ?? cause.message) : String(cause)),
+    )
+    return Response.error(c, {
+      code: 'internal_error',
+      message: 'Internal server error',
+      status: 500,
+    })
+  })
+
+  // Return the typed chained Hono directly. Spreading `store`/`listener` onto
+  // the app would intersect the inferred Hono type and breaks `testClient`'s
+  // schema inference for downstream consumers. The cache `store` is owned by
+  // the caller (pass `options.cache.store`), and a Node listener is produced on
+  // demand via `App.listener(app)`.
+  return app
+}
+
+/**
+ * Wraps a Tempo API app with a `node:http`-compatible request listener.
+ * Lifted out of `create()` so the returned `app` keeps its precise chained
+ * Hono type (which `testClient` needs); intersecting the listener onto the
+ * app degrades the typed proxy inference.
+ */
+export function listener(app: { fetch: NodeFetch }): Listener {
+  return getRequestListener(app.fetch)
+}
+
+export declare namespace create {
+  /** Options for creating the Tempo API Hono app. */
+  type Options<path extends string = '/'> = {
+    /** Static API asset store for the current runtime (e.g. `Assets.cloudflareR2(...)`). Omit to skip static assets — token logo URIs go unresolved. */
+    assets?: Assets | undefined
+    /** Caching configuration: the cache store plus the edge response cache toggle. */
+    cache?: Cache | undefined
+    /** Response compression for API handlers. Disabled by default; pass true for defaults or a config object to customize. Leave disabled when fronted by a proxy/CDN that already compresses. */
+    compress?: boolean | Compress | undefined
+    /** CORS for API handlers. Enabled by default (wildcard origin, no credentials); pass a config object to customize, true for defaults, or false to disable (e.g. when CORS is handled by a fronting gateway/CDN). */
+    cors?: boolean | Cors | undefined
+    /** Default Tempo chain id for requests that omit `chainId`. */
+    defaultChainId?: Viem.ChainId | undefined
+    /** Vocs API reference options. Set to false to disable the `/` docs page. */
+    docs?: Docs | false | undefined
+    /** Request logging. Disabled by default. Pass `true` to emit one canonical structured log entry per request through the level-matched console method (indexed by Workers Logs); a level (e.g. `'warn'`) to emit only that level and above (dropping successful-request info lines); or an emit function for a custom sink. */
+    logger?: boolean | Log.Level | Logger | undefined
+    /** Metrics backend. Disabled by default; pass a backend (e.g. `Metrics.cloudflare()`) to emit request (HTTP) metrics per response. Pass the same backend to the webhook poller/queue handlers so they emit over it too. */
+    metrics?: Metrics.Metrics | undefined
+    /** Hono middleware to run before API handlers mount. */
+    middleware?: readonly MiddlewareHandler[] | undefined
+    /** Base path to mount API handlers under. Provided as a literal via the `path` generic so the resulting Hono schema keeps typed route paths for `testClient`. */
+    path?: path | undefined
+    /** OpenAPI `servers` for the generated document. Defaults to a single relative server (the host serving the doc), so the reference targets the deployment it is served from. Set the canonical public URL(s) here, e.g. `[{ url: 'https://api.tempo.xyz' }]`. */
+    servers?: readonly Server[] | undefined
+    /** Extra Tempo chain ids this deployment serves, in addition to the built-in public chains and the configured `defaultChainId`. A request for a `chainId` outside this set is rejected with a clear 400 instead of reaching an upstream. */
+    supportedChainIds?: readonly number[] | undefined
+    /** Tempo RPC options. */
+    rpc?: Rpc | undefined
+    /** TIDX query client options. */
+    tidx?: Tidx.getClient.Tidx | undefined
+    /** Verified-token feature configuration. Omit to serve an empty verified list (nothing is verified). Provide a state `store` (Cloudflare KV or a Durable Object in production; never the cache, which a miss would silently drop) to make the curated list API-managed and durable. */
+    verifiedTokens?: VerifiedTokens | undefined
+    /** Webhook feature configuration. Omit to disable webhooks: the `/webhooks` routes stay mounted (for a stable schema and typed test client) but return `404` and are hidden from the OpenAPI document. Requires a state `store` (a Durable Object in production; never the cache, which a miss would silently drop). */
+    webhook?: Webhook | undefined
+  }
+
+  /** Caching configuration. */
+  type Cache = {
+    /** Edge response caching for public GET endpoints, serving cache hits from `store` before auth/rate-limiting for all callers (hits bypass origin metering). Enabled by default; set false to disable. */
+    edge?: boolean | undefined
+    /** Cache store backing both the handler read cache and the edge response cache. This is a cache, not durable storage — a miss simply re-fetches — and defaults to in-memory. Use `Store.cache(caches.default)` in production for a colo-local store; never the Durable Object. */
+    store?: Store.Store | undefined
+  }
+
+  /** Verified-token feature configuration. */
+  type VerifiedTokens = {
+    /**
+     * Per-isolate soft-refresh window in milliseconds. Within this window
+     * verified-token lookups are served from the in-memory snapshot with no
+     * store I/O; after it, the next lookup re-checks the store's `head` version
+     * (single-flight) and recompiles only when it changed. Defaults to 10_000.
+     */
+    refreshMs?: number | undefined
+    /**
+     * State store backing the curated verified-token snapshots. Must be a
+     * {@link Store.State} (e.g. `Store.cloudflareKv(...)`, `Store.durableObject(...)`,
+     * or `Store.memory()`); the Web Cache adapter (`Store.cache`) is rejected at
+     * the type level since a miss there would silently drop authoritative state.
+     */
+    store: Store.State
+  }
+
+  /** Webhook feature configuration. */
+  type Webhook = {
+    /**
+     * Maximum active subscriptions a single owner may hold. Creation is rejected
+     * with `403 limit_exceeded` once reached. Defaults to 100; bounds the
+     * spam/SSRF surface and unbounded downstream delivery cost per owner.
+     */
+    maxPerOwner?: number | undefined
+    /**
+     * State store backing webhook subscriptions, cursors, and the delivery
+     * log. Must be a {@link Store.State} (e.g. `Store.durableObject(...)` or
+     * `Store.memory()`); the Web Cache adapter (`Store.cache`) is rejected at
+     * the type level since a miss there would silently drop authoritative state.
+     */
+    store: Store.State
+  }
+
+  /** Binary asset store for static API assets (e.g. `Assets.cloudflareR2(...)`). */
+  type Assets = Assets.Assets
+
+  /** Response compression middleware options. */
+  type Compress = NonNullable<Parameters<typeof hono_compress>[0]>
+
+  /** CORS middleware options. */
+  type Cors = NonNullable<Parameters<typeof hono_cors>[0]>
+
+  /** Vocs API reference options (theme, top navigation, logo, socials, …). */
+  type Docs = NonNullable<Parameters<typeof Handler.openApi>[0]['vocs']>
+
+  /** Custom request-log sink, receiving one canonical entry per request. */
+  type Logger = Log.Emit
+
+  /** OpenAPI server entry for the generated document. */
+  type Server = {
+    /** Server URL (absolute, or relative to the requesting host). */
+    url: string
+    /** Optional human-readable description. */
+    description?: string
+  }
+
+  /**
+   * Tempo RPC options: a static config, or a per-request resolver function that
+   * routes by request principal to a separate (e.g. public, no-auth) RPC.
+   */
+  type Rpc = Viem.getClient.Rpc
+}
+
+function getRequestId(c: Context<Environment>) {
+  return c.get('requestId')
+}
+
+async function errorFromException(c: Context<Environment>, cause: HTTPException) {
+  const requestId = getRequestId(c)
+  const response = cause.getResponse()
+  response.headers.set('tempo-request-id', requestId)
+
+  if (!isJson(response)) return response
+
+  const body = await response
+    .clone()
+    .json()
+    .catch(() => null)
+  if (!isRecord(body)) return response
+
+  return c.json({ ...body, requestId }, cause.status, Object.fromEntries(response.headers))
+}
+
+// Reorder OpenAPI `paths` so reads come before writes within each tag group,
+// and shallower paths come before deeper paths inside each bucket so root-level
+// routes ("List tokens" — `/tokens`) win over nested ones ("List address
+// tokens" — `/addresses/{address}/tokens`). Tie-break by original document
+// order to keep registered grouping.
+//
+// A path is ranked as a unit because REST groups verbs onto shared paths (and
+// the reference renders all methods of a path adjacently, in the fixed canonical
+// method order GET→POST→PATCH→DELETE), so two operations on the same path can
+// never be separated or reordered relative to each other.
+//
+// Read-only tags keep lists-before-gets (tiers 0/2). The `Webhooks` tag instead
+// groups all reads (lists, then the item GET) ahead of the item writes, scoped
+// to that tag so the read tags are untouched. The shared-path constraint means
+// the desired "Create, all GETs (lists first), Update, Delete" can only be
+// approximated: `Create webhook` shares `/webhooks` with `List webhooks`, and
+// vocs renders GET before POST, so "List webhooks" unavoidably precedes
+// "Create". `Get`/`Update`/`Delete` all share `/webhooks/{id}`, so they render
+// adjacently as Get→Update→Delete. The `{id}` item is tiered right after the
+// collection root, so `Get/Update/Delete` sit just below `List webhooks/Create`,
+// ahead of the remaining lists and action POSTs. Tiers:
+//   0 collection root (`GET`+`POST /webhooks`)        → "List webhooks, Create webhook"
+//   1 item (`GET`+`PATCH`+`DELETE /webhooks/{id}`)    → "Get, Update, Delete"
+//   2 other list-only paths (`/event-types`, `/deliveries`)
+//   3 other writes/actions (`POST .../ping`, `.../retry`)
+function sortPaths(paths: PathsObject): PathsObject {
+  const entries = Object.entries(paths)
+  const rank = (entry: [string, PathItem]) => {
+    const operations = Object.values(entry[1])
+    const summaries = operations.flatMap((op) =>
+      isOperation(op) && op.summary ? [op.summary] : [],
+    )
+    const has = (prefix: string) => summaries.some((summary) => summary.startsWith(prefix))
+    if (operations.some((op) => isOperation(op) && op.tags?.includes('Webhooks'))) {
+      if (has('Create')) return 0
+      if (has('Get')) return 1
+      if (has('List')) return 2
+      return 3
+    }
+    if (has('List')) return has('Create') ? 1 : 0
+    if (has('Get')) return 2
+    if (has('Create')) return 3
+    return 4
+  }
+  const depth = (path: string) =>
+    path.endsWith('/rpc') ? 2 : path.split('/').filter(Boolean).length
+  const indexed = entries.map(
+    (entry, index) => [entry, index, rank(entry), depth(entry[0])] as const,
+  )
+  indexed.sort(([, ai, ar, ad], [, bi, br, bd]) => ar - br || ad - bd || ai - bi)
+  return Object.fromEntries(indexed.map(([entry]) => entry))
+}
+
+/**
+ * Sets per-operation `security` and the `402` payment-challenge response from
+ * each route's resolved access lanes (see {@link Auth.describeAccess}). The
+ * anonymous (`{}`) security option and the `402` response are emitted only where
+ * the route's policy enables the public and MPP lanes respectively; required
+ * API-key scopes are surfaced as the `x-required-scopes` extension.
+ */
+function applyAccess(paths: PathsObject, access: Record<string, Auth.OperationAccess>) {
+  for (const item of Object.values(paths)) {
+    for (const op of Object.values(item as Record<string, unknown>)) {
+      if (!isMutableOperation(op)) continue
+      const lanes = access[op.operationId]
+      if (!lanes) continue
+      op.security = [{ apiKey: [] }, { bearerAuth: [] }, ...(lanes.public ? [{}] : [])]
+      if (lanes.scopes.length > 0) op['x-required-scopes'] = [...lanes.scopes]
+      if (lanes.mpp) op.responses = { ...op.responses, 402: OpenApi.paymentChallengeRef }
+      else if (op.responses) delete op.responses['402']
+    }
+  }
+}
+
+/**
+ * Links the JSON-RPC passthrough operation to the OpenRPC document (served at
+ * `{basePath}/openrpc.json`) via an `x-openrpc` vendor extension. The raw `/rpc`
+ * request body is opaque to OpenAPI, so this lets consumers discover the
+ * method/param/return schemas it accepts.
+ *
+ * The public `/openapi.json` keeps a URL reference (small, conventional). The
+ * docs handler instead receives the document inlined — see `inlineOpenrpc`.
+ */
+function applyOpenrpcLink(paths: PathsObject, basePath: string) {
+  // `basePath` is `/` at the root mount and `/api` etc. otherwise; strip any
+  // trailing slash so the join never doubles up (`//openrpc.json`).
+  const url = `${basePath.replace(/\/$/, '')}/openrpc.json`
+  for (const item of Object.values(paths))
+    for (const op of Object.values(item as Record<string, unknown>))
+      if (isMutableOperation(op) && isRpcOperation(op)) op['x-openrpc'] = url
+}
+
+/**
+ * Returns a shallow copy of `spec` with the JSON-RPC passthrough operation's
+ * `x-openrpc` replaced by the inline OpenRPC document, for the docs handler.
+ *
+ * Vocs expands `x-openrpc` at request time. A URL reference (as kept in the
+ * public `/openapi.json`) would make the docs worker fetch its own
+ * `/openrpc.json` — a self-subrequest that is unreliable on Cloudflare Workers
+ * and silently falls back to a single, unexpanded operation. Inlining the
+ * committed artifact keeps expansion deterministic across local and deployed
+ * environments, without bloating the public spec. Only the affected path/op are
+ * cloned; the rest of the (large) document is shared by reference.
+ */
+function inlineOpenrpc<spec extends { paths: Record<string, unknown> }>(spec: spec): spec {
+  const paths: Record<string, unknown> = {}
+  for (const [pathname, item] of Object.entries(spec.paths)) {
+    let next = item
+    if (isRecord(item))
+      for (const [method, op] of Object.entries(item))
+        if (isMutableOperation(op) && isRpcOperation(op))
+          next = { ...item, [method]: { ...op, 'x-openrpc': openrpcSpec } }
+    paths[pathname] = next
+  }
+  return { ...spec, paths }
+}
+
+type PathsObject = Awaited<ReturnType<typeof generateSpecs>>['paths']
+type PathItem = PathsObject[string]
+type Operation = { summary?: string | undefined }
+type MutableOperation = {
+  operationId: string
+  responses?: Record<string, unknown> | undefined
+  security?: unknown
+  'x-openrpc'?: unknown
+  'x-required-scopes'?: unknown
+}
+
+function isRpcOperation(op: MutableOperation) {
+  return op.operationId === 'rpcRequest'
+}
+
+function isOperation(value: unknown): value is Operation {
+  return !!value && typeof value === 'object' && 'summary' in value
+}
+
+function isMutableOperation(value: unknown): value is MutableOperation {
+  return isRecord(value) && typeof value['operationId'] === 'string'
+}
+
+function isJson(response: globalThis.Response) {
+  return response.headers.get('content-type')?.includes('application/json') ?? false
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+function createGetAsset(options: createGetAsset.Options): GetAsset {
+  const { assets, basePath, origin } = options
+  // Without an asset store, every lookup misses so callers fall back to their
+  // "no static data" behavior (undefined logo URIs).
+  if (!assets) return () => undefined
+  return async (chainId, path) => {
+    // Public URLs include `/assets/:chainId`, but the store is keyed by
+    // `:chainId/:path` (e.g. an R2 object key), decoupled from the URL shape.
+    // `path` may be absolute (`Path.join` returns a leading slash); strip it so
+    // the key is `:chainId/:path`, not `:chainId//:path`.
+    const pathname = Path.join(basePath, 'assets', String(chainId), path)
+    const key = `${chainId}/${path.replace(/^\/+/, '')}`
+    const asset = await assets.get(key)
+    if (!asset) return undefined
+    // Return an absolute public URL (scheme + host) against the request origin
+    // so logo URLs work for any consumer regardless of the API's domain.
+    return {
+      response: new globalThis.Response(asset.body, {
+        headers: { 'Content-Type': asset.contentType },
+      }),
+      uri: new URL(pathname, origin).toString(),
+    }
+  }
+}
+
+declare namespace createGetAsset {
+  type Options = {
+    assets?: create.Assets | undefined
+    basePath: string
+    origin: string
+  }
+}
+
+function stripAssetPath(path: string, basePath: string) {
+  for (const prefix of [`${Path.join(basePath, 'assets')}/`, '/assets/'])
+    if (path.startsWith(prefix)) return `/${path.slice(prefix.length)}`
+  return path
+}
+
+type GetNodeRequestListener = (typeof import('@hono/node-server'))['getRequestListener']
+type NodeFetch = Parameters<GetNodeRequestListener>[0]
+type NodeRequestListener = ReturnType<GetNodeRequestListener>
+
+function getRequestListener(fetch: NodeFetch): Listener {
+  let listener: NodeRequestListener | undefined
+  return async (incoming_, outgoing_) => {
+    // Resolve the Node-only adapter at call time. The split specifier keeps
+    // Worker bundlers from eagerly including a server adapter they never run.
+    if (listener === undefined) {
+      const nodeServer = (await import(
+        /* @vite-ignore */ ['@hono', 'node-server'].join('/')
+      )) as typeof import('@hono/node-server')
+      listener = nodeServer.getRequestListener(fetch)
+    }
+    return listener(incoming_ as never, outgoing_ as never)
+  }
+}