tapimo 0.0.2 → 0.2.0

package/src/admin/apps/verified-tokens.ts

@@ -4,9 +4,9 @@ import * as z from 'zod/mini'
 import * as OpenApi from '../../internal/OpenApi.js'
 import * as Response from '../../internal/Response.js'
 import * as Schema from '../../internal/Schema.js'
-import type * as Store from '../../internal/Store.js'
+import * as Db from '../../db/Db.js'
 import * as VerifiedTokens from '../../internal/VerifiedTokens.js'
-import { schema as readSchema } from '../../apps/verified-tokens.js'
+import { schema as readSchema } from '../../apps/data/routes/verified-tokens.js'
 import type * as App from '../App.js'
 
 /** Required `chainId` query: admin mutations always address a chain explicitly. */
@@ -149,9 +149,9 @@ export namespace schema {
 }
 
 /**
- * Management routes for the curated verified-token list, backed by the request's
- * `verifiedTokens` store; all `404` when no store is configured. Mutations accept
- * an optional `If-Match` precondition (`412` on mismatch).
+ * Management routes for the curated verified-token list, backed by the app
+ * database (snapshot rows). Mutations accept an optional `If-Match`
+ * precondition (`412` on mismatch).
  *
  * - `POST /` creates a token (`409` on a duplicate address or symbol).
  * - `PUT /` replaces a chain's entire list (seed/rollback).
@@ -170,7 +170,6 @@ export function verifiedTokens() {
       OpenApi.describeRoute({
         operationId: 'listVerifiedTokens',
         responses: OpenApi.responses({
-          errors: { 404: featureDisabledDescription },
           success: {
             description: 'Curated verified tokens.',
             schema: schema.listVerifiedTokens.Response,
@@ -180,10 +179,9 @@ export function verifiedTokens() {
         tags: ['Verified Tokens'],
       }),
       async (c) => {
-        const store = c.get('verifiedTokens')?.store
-        if (!store) return notEnabled(c)
+        const db = Db.get(c.get('db'))
         const { chainId } = c.req.valid('query')
-        const snapshot = await VerifiedTokens.read(store, chainId)
+        const snapshot = await VerifiedTokens.read(db, chainId)
         return c.json(
           Response.validated(schema.listVerifiedTokens.Response, {
             data: snapshot?.list ?? [],
@@ -202,7 +200,6 @@ export function verifiedTokens() {
         operationId: 'createVerifiedToken',
         responses: OpenApi.responses({
           errors: {
-            404: featureDisabledDescription,
             409: 'Duplicate address or symbol.',
             413: 'Logo exceeds the size limit.',
             415: 'Logo is not valid SVG.',
@@ -216,22 +213,21 @@ export function verifiedTokens() {
         tags: ['Verified Tokens'],
       }),
       async (c) => {
-        const store = c.get('verifiedTokens')?.store
-        if (!store) return notEnabled(c)
+        const db = Db.get(c.get('db'))
         const { logo, ...body } = c.req.valid('json')
         try {
           if (logo !== undefined) {
             const assets = c.get('assets')
             if (!assets?.put) return assetsNotEnabled(c)
             const svg = encodeLogo(logo)
-            const duplicate = await findDuplicate(store, body)
+            const duplicate = await findDuplicate(db, body)
             if (duplicate) throw duplicate
             await assets.put(logoKey(body.chainId, body.address), {
               body: svg,
               contentType: 'image/svg+xml',
             })
           }
-          const { snapshot, token } = await VerifiedTokens.create(store, body)
+          const { snapshot, token } = await VerifiedTokens.create(db, body)
           return c.json(
             Response.validated(schema.createVerifiedToken.Response, {
               data: token,
@@ -257,7 +253,6 @@ export function verifiedTokens() {
         operationId: 'replaceVerifiedTokens',
         responses: OpenApi.responses({
           errors: {
-            404: featureDisabledDescription,
             409: 'Duplicate address or symbol.',
             412: 'Version precondition failed.',
           },
@@ -270,12 +265,11 @@ export function verifiedTokens() {
         tags: ['Verified Tokens'],
       }),
       async (c) => {
-        const store = c.get('verifiedTokens')?.store
-        if (!store) return notEnabled(c)
+        const db = Db.get(c.get('db'))
         const { chainId } = c.req.valid('query')
         const { tokens } = c.req.valid('json')
         try {
-          const { snapshot } = await VerifiedTokens.replace(store, chainId, tokens, {
+          const { snapshot } = await VerifiedTokens.replace(db, chainId, tokens, {
             ...ifMatch(c),
           })
           return c.json(
@@ -320,13 +314,12 @@ export function verifiedTokens() {
         tags: ['Verified Tokens'],
       }),
       async (c) => {
-        const store = c.get('verifiedTokens')?.store
-        if (!store) return notEnabled(c)
+        const db = Db.get(c.get('db'))
         const { address } = c.req.valid('param')
         const { chainId } = c.req.valid('query')
         const body = c.req.valid('json')
         try {
-          const { snapshot, token } = await VerifiedTokens.patch(store, chainId, address, body, {
+          const { snapshot, token } = await VerifiedTokens.patch(db, chainId, address, body, {
             ...ifMatch(c),
           })
           return c.json(
@@ -366,12 +359,11 @@ export function verifiedTokens() {
         tags: ['Verified Tokens'],
       }),
       async (c) => {
-        const store = c.get('verifiedTokens')?.store
-        if (!store) return notEnabled(c)
+        const db = Db.get(c.get('db'))
         const { address } = c.req.valid('param')
         const { chainId } = c.req.valid('query')
         try {
-          const { snapshot } = await VerifiedTokens.remove(store, chainId, address, {
+          const { snapshot } = await VerifiedTokens.remove(db, chainId, address, {
             ...ifMatch(c),
           })
           return c.json(
@@ -476,9 +468,6 @@ export function verifiedTokens() {
 /** Largest accepted logo upload (SVG icons are tiny; this is generous). */
 const maxLogoBytes = 256 * 1024
 
-/** OpenAPI description shared by write routes' 404 when the feature is disabled. */
-const featureDisabledDescription = 'Verified-token management is not enabled (or not found).'
-
 /** Asset-store key the main API's loader reads for a token's curated icon. */
 function logoKey(chainId: number, address: string): string {
   return `${chainId}/icons/${address.toLowerCase()}`
@@ -511,10 +500,10 @@ function encodeLogo(logo: string): ArrayBuffer {
 // Returns the duplicate-address/symbol error a create would throw, or undefined,
 // so the logo upload can be skipped before it overwrites an existing icon.
 async function findDuplicate(
-  store: Store.State,
+  db: Db.Db,
   token: { address: string; chainId: VerifiedTokens.ChainId; symbol: string },
 ): Promise<Error | undefined> {
-  const snapshot = await VerifiedTokens.read(store, token.chainId)
+  const snapshot = await VerifiedTokens.read(db, token.chainId)
   if (!snapshot) return undefined
   if (snapshot.byAddress.has(token.address.toLowerCase()))
     return new VerifiedTokens.DuplicateAddressError({ address: token.address, chainId: token.chainId }) // prettier-ignore
@@ -556,11 +545,3 @@ function mutationError(c: Context<App.Environment>, cause: unknown) {
     return Response.error(c, { code: 'version_mismatch', message: cause.message, status: 412 })
   return Response.upstream(c, cause)
 }
-
-function notEnabled(c: Context<App.Environment>) {
-  return Response.error(c, {
-    code: 'verified_tokens_not_enabled',
-    message: 'Verified-token management is not enabled for this deployment.',
-    status: 404,
-  })
-}

package/src/admin/ui.generated.ts

@@ -11,7 +11,7 @@ export type Asset = {
 
 /** The prerendered SPA shell HTML (assets normalized to relative URLs). */
 export const shell =
-  '<!DOCTYPE html><html lang="en" data-theme="dark" data-regen-radius="none"><head><meta charSet="utf-8"/><meta content="width=device-width, initial-scale=1" name="viewport"/><link rel="stylesheet" href="./assets/styles-Cd7Fp5b_.css" data-precedence="default"/><title>Tempo API Admin</title><link rel="modulepreload" href="./assets/index-CPTihwDe.js"/><link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20269%20269%22%3E%3Crect%20width%3D%22269%22%20height%3D%22269%22%20fill%3D%22%23000%22%2F%3E%3Cpath%20d%3D%22M123.273%20190.794H93.445L121.09%20105.318H85.7334L93.445%2080.2642H191.95L184.238%20105.318H150.773L123.273%20190.794Z%22%20fill%3D%22%23fff%22%2F%3E%3C%2Fsvg%3E"/></head><body><div id="root"></div><script class="$tsr" id="$tsr-stream-barrier">(self.$R=self.$R||{})["tsr"]=[];self.$_TSR={h(){this.hydrated=!0,this.c()},e(){this.streamEnded=!0,this.c()},c(){this.hydrated&&this.streamEnded&&(delete self.$_TSR,delete self.$R.tsr)},p(e){this.initialized?e():this.buffer.push(e)},buffer:[]};$_TSR.router=($R=>$R[0]={manifest:$R[1]={routes:$R[2]={__root__:$R[3]={preloads:$R[4]=["./assets/index-CPTihwDe.js"],scripts:$R[5]=[$R[6]={attrs:$R[7]={type:"module",async:!0,src:"./assets/index-CPTihwDe.js"}}]}}},matches:$R[8]=[$R[9]={i:"__root__\u0000",u:1782959721668,s:"success",ssr:!0}],lastMatchId:"__root__\u0000"})($R["tsr"]);$_TSR.e();document.currentScript.remove()</script><script type="module" async="" src="./assets/index-CPTihwDe.js"></script></body></html>'
+  '<!DOCTYPE html><html lang="en" data-theme="dark" data-regen-radius="none"><head><meta charSet="utf-8"/><meta content="width=device-width, initial-scale=1" name="viewport"/><link rel="stylesheet" href="./assets/styles-Cd7Fp5b_.css" data-precedence="default"/><title>Tempo API Admin</title><link rel="modulepreload" href="./assets/index-CPTihwDe.js"/><link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20269%20269%22%3E%3Crect%20width%3D%22269%22%20height%3D%22269%22%20fill%3D%22%23000%22%2F%3E%3Cpath%20d%3D%22M123.273%20190.794H93.445L121.09%20105.318H85.7334L93.445%2080.2642H191.95L184.238%20105.318H150.773L123.273%20190.794Z%22%20fill%3D%22%23fff%22%2F%3E%3C%2Fsvg%3E"/></head><body><div id="root"></div><script class="$tsr" id="$tsr-stream-barrier">(self.$R=self.$R||{})["tsr"]=[];self.$_TSR={h(){this.hydrated=!0,this.c()},e(){this.streamEnded=!0,this.c()},c(){this.hydrated&&this.streamEnded&&(delete self.$_TSR,delete self.$R.tsr)},p(e){this.initialized?e():this.buffer.push(e)},buffer:[]};$_TSR.router=($R=>$R[0]={manifest:$R[1]={routes:$R[2]={__root__:$R[3]={preloads:$R[4]=["./assets/index-CPTihwDe.js"],scripts:$R[5]=[$R[6]={attrs:$R[7]={type:"module",async:!0,src:"./assets/index-CPTihwDe.js"}}]}}},matches:$R[8]=[$R[9]={i:"__root__\u0000",u:1783292569178,s:"success",ssr:!0}],lastMatchId:"__root__\u0000"})($R["tsr"]);$_TSR.e();document.currentScript.remove()</script><script type="module" async="" src="./assets/index-CPTihwDe.js"></script></body></html>'
 
 /** Content-hashed UI assets, keyed by their path under the mount (e.g. `assets/index-*.js`). */
 export const assets: Record<string, Asset> = {

package/src/apps/composition.test.ts

@@ -0,0 +1,66 @@
+import { App, Store } from 'tapimo'
+import { data, platform, relay } from 'tapimo/apps'
+import * as TestApp from '../../test/App.js'
+
+// Each test mounts one group and asserts its routes exist while the omitted
+// group's are absent (404 and not in the document). Only `paths` are checked;
+// tags/schemes stay a superset (Decision C).
+
+/** Paths (sans method) present in a composed app's OpenAPI document. */
+async function paths(app: { request: (path: string) => Promise<Response> | Response }) {
+  const res = await app.request('/openapi.json')
+  const spec = (await res.json()) as { paths: Record<string, unknown> }
+  return Object.keys(spec.paths)
+}
+
+describe('data()', () => {
+  test('mounts data routes and omits platform routes', async () => {
+    const app = App.create({ db: TestApp.database() }).route('/', data())
+
+    const keys = await paths(app)
+    expect(keys.some((path) => path.startsWith('/v1/tokens'))).toBe(true)
+    expect(keys.some((path) => path.startsWith('/v1/blocks'))).toBe(true)
+    expect(keys.some((path) => path.startsWith('/v1/orgs'))).toBe(false)
+    expect(keys.some((path) => path.startsWith('/v1/me'))).toBe(false)
+
+    // The omitted platform route resolves to a 404 (never mounted), not a 401.
+    const orgs = await app.request('/v1/orgs')
+    expect(orgs.status).toBe(404)
+  })
+})
+
+describe('relay()', () => {
+  test('mounts the relay after data() and stays out of the document', async () => {
+    const composed = App.create({ db: TestApp.database() }).route('/', data()).route('/', relay())
+
+    // Mounted but default-closed and hidden: unauthenticated requests are
+    // refused, and the path never appears in the OpenAPI document.
+    const mounted = await composed.request('/rpc/relay')
+    expect(mounted.status).toBe(401)
+    expect((await paths(composed)).some((path) => path.startsWith('/rpc/relay'))).toBe(false)
+
+    // Without the relay group, the data group no longer serves the path.
+    const dataOnly = App.create({ db: TestApp.database() }).route('/', data())
+    expect((await dataOnly.request('/rpc/relay')).status).toBe(404)
+  })
+})
+
+describe('platform()', () => {
+  test('mounts platform routes and omits data routes', async () => {
+    const app = App.create({
+      auth: { session: { wallet: { origin: 'https://test.example' } } },
+      db: TestApp.database(),
+      kv: { store: Store.memory() },
+    }).route('/', platform())
+
+    const keys = await paths(app)
+    expect(keys.some((path) => path.startsWith('/v1/orgs'))).toBe(true)
+    expect(keys.some((path) => path.startsWith('/v1/me'))).toBe(true)
+    expect(keys.some((path) => path.startsWith('/v1/tokens'))).toBe(false)
+    expect(keys.some((path) => path.startsWith('/v1/blocks'))).toBe(false)
+
+    // The omitted data route resolves to a 404 (never mounted).
+    const token = await app.request('/v1/tokens/0x20c0000000000000000000000000000000000000')
+    expect(token.status).toBe(404)
+  })
+})

package/src/apps/data/App.ts

@@ -0,0 +1,295 @@
+import { Hono } from 'hono'
+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 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 { transactions as transactionActivities } from './routes/activities.js'
+import { addresses } from './routes/addresses.js'
+import { blocks, blocksByTimestampCompat } from './routes/blocks.js'
+import { coingecko } from './routes/coingecko.js'
+import { exchanges } from './routes/exchanges.js'
+import { feeAmm } from './routes/fee-amm.js'
+import { indexer } from './routes/indexer.js'
+import { receipts } from './routes/receipts.js'
+import { rpc } from './routes/rpc.js'
+import { tokenlist } from './routes/tokenlist.js'
+import { tokens } from './routes/tokens.js'
+import { transactions } from './routes/transactions.js'
+import { transfers } from './routes/transfers.js'
+import { verifiedTokens } from './routes/verified-tokens.js'
+import { schema as webhookSchema, webhooks } from './routes/webhooks.js'
+
+/**
+ * The chain-data route group: read endpoints over blocks, transactions, tokens,
+ * the exchange/fee-AMM, and the RPC/indexer passthroughs. It owns all chain
+ * configuration and publishes the chain clients on request context.
+ *
+ * ```ts
+ * App.create(options).route('/', data())
+ * ```
+ */
+export function data(options: data.Options = {}) {
+  const { assets, defaultChainId = Viem.defaultChainId, rpc: rpc_option, tidx } = options
+
+  // 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.
+  const supportedChainIds = new Set<number>([
+    ...Object.keys(Viem.url).map(Number),
+    ...Object.keys(Tidx.url).map(Number),
+    defaultChainId,
+    ...(options.supportedChainIds ?? []),
+  ])
+
+  // Memoize one viem client per resolved upstream (stateless HTTP transports).
+  // Keying on the resolved output (`url`+`basicAuth`+`chainId`), not the
+  // principal, bounds cardinality by the number of distinct upstreams.
+  const clients = new Map<string, ReturnType<typeof Viem.getClient>>()
+  const getClient = (chainId = defaultChainId, principal: Auth.Principal | null = null) => {
+    const { url, basicAuth } = Viem.resolve(rpc_option, { chainId, principal })
+    const cacheKey = `${url}|${basicAuth ?? ''}|${chainId}`
+    const existing = clients.get(cacheKey)
+    if (existing) return existing
+    const client = Viem.getClient({ chainId, principal, rpc: rpc_option })
+    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.
+  const getTidx = Tidx.createGetClient({ defaultChainId, tidx })
+
+  const app = new Hono<App.Environment>()
+    // Publish the chain-data context vars for this group's handlers. Runs after
+    // `App.create`'s middleware, so `getClient`/`getTidx` can key on the
+    // resolved principal and `getAsset` can read `basePath` off context.
+    .use('*', async (c, next) => {
+      c.set('chainId', defaultChainId)
+      c.set('getAsset', createGetAsset({ assets, basePath: c.get('basePath'), origin: new URL(c.req.url).origin })) // prettier-ignore
+      c.set('getClient', (chainId) => getClient(chainId, Auth.getPrincipal(c)))
+      c.set('getTidx', (chainId) => getTidx(chainId, Auth.getPrincipal(c)))
+      c.set('rpc', rpc_option)
+      c.set('supportedChainIds', supportedChainIds)
+      c.set('tidx', tidx)
+      c.set('verifiedTokens', options.verifiedTokens === false ? undefined : (options.verifiedTokens ?? {})) // prettier-ignore
+      c.set('webhook', options.webhook === false ? undefined : (options.webhook ?? {}))
+      await next()
+    })
+    // Reject a well-formed but unsupported `chainId` before it reaches an
+    // upstream, which would otherwise return an opaque `upstream_error`.
+    .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)
+    })
+    // Serve static API assets (e.g. verified-token icons) from the configured
+    // store; a no-op fall-through when no store is configured (logo URIs simply
+    // go unresolved).
+    .use('/assets/*', async (c, next) => {
+      if (!assets) return next()
+      const key = stripAssetPath(c.req.path, c.get('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,
+      })
+    })
+    .route('/', addresses())
+    .route('/', blocks())
+    .route('/', exchanges())
+    .route('/', feeAmm())
+    .route('/', indexer())
+    .route('/', receipts())
+    .route('/', tokenlist())
+    .route('/', tokens())
+    .route('/', transactions())
+    .route('/', transactionActivities())
+    .route('/', transfers())
+    .route('/', verifiedTokens())
+    .route('/', webhooks({ enabled: options.webhook !== false }))
+    .route('/', rpc())
+    .route('/', coingecko())
+    .route('/', blocksByTimestampCompat())
+  return Metadata.attach(app, openapi)
+}
+
+export declare namespace data {
+  /** Options for the data route group. */
+  type Options = {
+    /** Static API asset store for the current runtime (e.g. `Assets.cloudflareR2(...)`). Omit to skip static assets — token logo URIs go unresolved. */
+    assets?: Assets.Assets | undefined
+    /** Default Tempo chain id for requests that omit `chainId`. */
+    defaultChainId?: Viem.ChainId | 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. */
+    supportedChainIds?: readonly number[] | undefined
+    /** TIDX query client options. */
+    tidx?: Tidx.getClient.Tidx | undefined
+    /** Verified-token feature configuration. Enabled by default (token rows live in `db`; empty until published); pass `false` to always serve an empty verified list. */
+    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
+  }
+
+  /** Verified-token feature configuration. */
+  type VerifiedTokens = {
+    /**
+     * Per-isolate soft-refresh window (ms). Lookups serve from the in-memory
+     * snapshot within it; after it, the next lookup re-checks the head version
+     * and recompiles only on change. Defaults to 10_000.
+     */
+    refreshMs?: number | undefined
+  }
+
+  /** Webhook feature configuration. */
+  type Webhook = {
+    /**
+     * Maximum active subscriptions per owner; creation is rejected with
+     * `403 limit_exceeded` once reached. Defaults to 100, bounding the spam/SSRF
+     * and delivery-cost surface per owner.
+     */
+    maxPerOwner?: number | undefined
+  }
+}
+
+/**
+ * The OpenAPI metadata this group owns: its operation tags and the outbound
+ * `webhooks` block. Tagged onto the {@link data} instance so `App.create`
+ * collects it; the webhooks block emits only when webhook routes are mounted.
+ */
+const openapi = {
+  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." }, // prettier-ignore
+    { 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.' },
+    { 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.' }, // prettier-ignore
+    { name: 'CoinGecko', description: "Exchange data in CoinGecko's GeckoTerminal format." },
+  ],
+  'x-tagGroups': [
+    {
+      name: 'Data API',
+      tags: [
+        'Activities',
+        'Balances',
+        'Blocks',
+        'Exchange',
+        'Fee AMM',
+        'Tokens',
+        'Transactions',
+        'Transfers',
+        'Verified Tokens',
+        'Webhooks',
+        'Indexer',
+        'RPC',
+        'CoinGecko',
+      ],
+    },
+  ],
+  webhooks: webhooksBlock,
+} satisfies App.create.Metadata
+
+// Builds the outbound-delivery `webhooks` block. `io: 'output'` documents the
+// serialized shape; `unrepresentable: 'any'` emits `{}` for payload transforms
+// (e.g. lazy fee-token metadata) that have no JSON-Schema form.
+function webhooksBlock() {
+  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 {
+    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'],
+      },
+    },
+  }
+}
+
+// Builds the per-request static-asset resolver. The store is keyed by
+// `:chainId/:path` (decoupled from the public `/assets/:chainId` URL) and
+// returns absolute URLs against the request origin. Without a store, every
+// lookup misses and callers fall back to undefined logo URIs.
+function createGetAsset(options: createGetAsset.Options): App.GetAsset {
+  const { assets, basePath, origin } = options
+  if (!assets) return () => undefined
+  return async (chainId, path) => {
+    const pathname = Path.join(basePath, 'assets', String(chainId), path)
+    // `path` may be absolute (`Path.join` returns a leading slash); strip it so
+    // the key is `:chainId/:path`, not `:chainId//:path`.
+    const key = `${chainId}/${path.replace(/^\/+/, '')}`
+    const asset = await assets.get(key)
+    if (!asset) return undefined
+    return {
+      response: new globalThis.Response(asset.body, {
+        headers: { 'Content-Type': asset.contentType },
+      }),
+      uri: new URL(pathname, origin).toString(),
+    }
+  }
+}
+
+declare namespace createGetAsset {
+  type Options = {
+    assets?: Assets.Assets | undefined
+    basePath: string
+    origin: string
+  }
+}
+
+// Strips the (possibly base-path-prefixed) `/assets/` segment so the remainder
+// is the store key path.
+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
+}

package/src/apps/data/index.ts

@@ -0,0 +1,2 @@
+export { data } from './App.js'
+export * as Sponsorships from '../relay/Sponsorships.js'

package/src/apps/{activities.test.ts → data/routes/activities.test.ts}

@@ -2,9 +2,9 @@ import { Address, Hex } from 'ox'
 import { encodeAbiParameters, encodeEventTopics } from 'viem'
 import { Abis } from 'viem/tempo'
 
-import * as TestApp from '../../test/App.js'
-import * as Runtime from '../../test/runtime.js'
-import * as Store from '../internal/Store.js'
+import * as TestApp from '../../../../test/App.js'
+import * as Runtime from '../../../../test/runtime.js'
+import * as Store from '../../../internal/Store.js'
 import * as Activities from './activities.js'
 
 /**

package/src/apps/{activities.ts → data/routes/activities.ts}

@@ -4,19 +4,19 @@ import { type Log, parseEventLogs, zeroAddress } from 'viem'
 import { Abis, Addresses } from 'viem/tempo'
 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 Cursor from '../internal/Cursor.js'
-import * as Mpp from '../internal/Mpp.js'
-import * as OpenApi from '../internal/OpenApi.js'
-import * as Response from '../internal/Response.js'
-import * as Schema from '../internal/Schema.js'
-import * as Store from '../internal/Store.js'
-import type * as Tidx from '../internal/Tidx.js'
-import * as Timing from '../internal/Timing.js'
-import * as Ttl from '../internal/Ttl.js'
-import * as Value from '../internal/Value.js'
+import type * as App from '../../../App.js'
+import * as Auth from '../../../internal/Auth.js'
+import * as Cache from '../../../internal/Cache.js'
+import * as Cursor from '../../../internal/Cursor.js'
+import * as Mpp from '../../../internal/Mpp.js'
+import * as OpenApi from '../../../internal/OpenApi.js'
+import * as Response from '../../../internal/Response.js'
+import * as Schema from '../../../internal/Schema.js'
+import * as Store from '../../../internal/Store.js'
+import type * as Tidx from '../../../internal/Tidx.js'
+import * as Timing from '../../../internal/Timing.js'
+import * as Ttl from '../../../internal/Ttl.js'
+import * as Value from '../../../internal/Value.js'
 import * as Tokens from './tokens.js'
 import * as Transfers from './transfers.js'
 
@@ -1667,7 +1667,7 @@ type TxGroup = {
  */
 export function addresses() {
   return new Hono<App.Environment>().get(
-    '/:address/activities',
+    '/v1/addresses/:address/activities',
     Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
     OpenApi.validate('param', schema.getAddressActivities.Params, {
       code: 'address_invalid',
@@ -1775,7 +1775,7 @@ export function addresses() {
  */
 export function transactions() {
   return new Hono<App.Environment>().get(
-    '/:transactionHash/activities',
+    '/v1/transactions/:transactionHash/activities',
     Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
     OpenApi.validate('param', schema.getTransactionActivities.Params, {
       code: 'transaction_invalid',

package/src/apps/{addresses.ts → data/routes/addresses.ts}

@@ -1,15 +1,15 @@
 import { Hono } from 'hono'
 
-import type * as App from '../App.js'
+import type * as App from '../../../App.js'
 import * as Activities from './activities.js'
 import * as Balances from './balances.js'
 
 /**
- * Composes the `/addresses/:address/*` route surface from the address-scoped
- * sub-routers exported by each resource module. The handlers and schemas live
- * with the resource they describe (activities, balances); this composer only
- * owns the `/addresses` mount path so docs grouping stays by tag while URLs
- * stay nested under the parent resource.
+ * Composes the `/v1/addresses/:address/*` route surface from the
+ * address-scoped sub-routers exported by each resource module. The handlers,
+ * schemas, and paths live with the resource they describe (activities,
+ * balances); this composer only aggregates them so docs grouping stays by tag
+ * while URLs stay nested under the parent resource.
  *
  * Only subject-relative resources live here — rows that cannot be interpreted
  * without the path address (activity classification, held-token balances).