tapimo 0.7.1 → 0.8.0

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

@@ -3,7 +3,9 @@ import { ZoneRpcAuthentication } from 'ox/tempo'
 import * as z from 'zod/mini'
 
 import type * as App from '../../../App.js'
+import * as Scope from '../../../Scope.js'
 import * as Auth from '../../../internal/Auth.js'
+import * as Log from '../../../internal/Log.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
@@ -66,11 +68,24 @@ const zoneReadMethods = new Set([
   'net_version',
   'web3_clientVersion',
   'web3_sha3',
+  'zone_getEncryptionKey',
+  'zone_getZoneInfo',
 ])
 
+// Zone write scopes broadcast caller-signed transactions only. Node-managed
+// accounts, signing, faucet, admin, and debug methods remain inaccessible.
+const zoneWriteMethods = new Set(['eth_sendRawTransaction', 'eth_sendRawTransactionSync'])
+
+const maxRpcInspectionBytes = 64 * 1_024
+
 /** Never reached; carries typed passthrough response variants into Hono client inference. */
 const narrowPassthrough = false as boolean
 
+type RpcInspection = {
+  body: ReadableStream<Uint8Array<ArrayBuffer>> | null
+  result: { empty: boolean; ok: false } | { ok: true; value: unknown } | undefined
+}
+
 /** Zod schemas owned by the raw RPC passthrough. */
 export namespace schema {
   /** JSON-RPC request identifier. */
@@ -118,17 +133,20 @@ export namespace schema {
       error: z
         .optional(Error)
         .check(z.describe('JSON-RPC error object returned when a method fails.')),
-      id: z
-        .optional(Id)
-        .check(
-          z.describe('Client-supplied JSON-RPC request id used to match responses to requests.'),
-        ),
+      id: Id.check(
+        z.describe('Client-supplied JSON-RPC request id used to match responses to requests.'),
+      ),
       jsonrpc: z.literal('2.0').check(z.describe('JSON-RPC protocol version; Tempo uses `2.0`.')),
       result: z
         .optional(z.unknown())
         .check(z.describe('Result returned by the upstream RPC method.')),
     })
-    .check(z.describe('One JSON-RPC response returned by Tempo.'))
+    .check(
+      z.refine((response) => (response.error === undefined) !== (response.result === undefined), {
+        error: 'A JSON-RPC response must contain exactly one of result or error.',
+      }),
+      z.describe('One JSON-RPC response returned by Tempo.'),
+    )
 
   /** JSON-RPC request or batch request payload. */
   export const RequestBody = z
@@ -137,7 +155,7 @@ export namespace schema {
 
   /** JSON-RPC response or batch response payload. */
   export const ResponseBody = z
-    .union([Response, z.array(Response)])
+    .union([Response, z.array(Response).check(z.minLength(1))])
     .check(z.describe('A single JSON-RPC response or an array of responses for batch calls.'))
 }
 
@@ -148,7 +166,7 @@ export function rpc() {
     Auth.policy({ apiKey: { scopes: ['data:read'] }, public: true }),
     OpenApi.describeRoute({
       description:
-        'Sends a single or batch Ethereum JSON-RPC request directly to Tempo. Use `/rpc/testnet`, `/rpc/mainnet`, or `/rpc/:chain` to choose a chain. Zone-scoped API keys may call read-only methods. A Zone token in `X-Authorization-Token` is forwarded to the authenticated Zone RPC. This passthrough is not part of the stable API contract and is supported on a best-effort basis only. It has no compatibility, latency, availability, or data-freshness guarantees, and breaking changes may happen with limited notice.',
+        'Sends a single or batch Ethereum JSON-RPC request directly to Tempo. Use `/rpc/testnet`, `/rpc/mainnet`, or `/rpc/:chain` to choose a chain. Zone read scopes permit read-only methods; Zone write scopes also permit signed transaction broadcasts. A Zone token in `X-Authorization-Token` is forwarded to the authenticated Zone RPC. This passthrough is not part of the stable API contract and is supported on a best-effort basis only. It has no compatibility, latency, availability, or data-freshness guarantees, and breaking changes may happen with limited notice.',
       operationId: 'rpcRequest',
       parameters: [
         {
@@ -214,17 +232,33 @@ export function rpc() {
           message: 'Missing API key',
           status: 401,
         })
-      if (zone && !zoneToken && !isZoneReadRequest(body))
-        return Response.error(c, {
-          code: 'api_key_forbidden',
-          message:
-            'Zone API keys may only call read-only RPC methods. Pass a Zone token via `X-Authorization-Token` for other methods.',
-          status: 403,
-        })
+      if (zone && !zoneToken) {
+        const requests = Array.isArray(body) ? body : [body]
+        const allowed =
+          requests.length > 0 &&
+          requests.every(
+            (request) =>
+              isZoneReadMethod(request) ||
+              (isZoneWriteMethod(request) && hasZoneWriteScope(c, chainId)),
+          )
+        if (!allowed)
+          return Response.error(c, {
+            code: 'api_key_forbidden',
+            message:
+              'Zone API keys may call read-only RPC methods. A matching Zone write scope also permits signed transaction broadcasts; pass a Zone token for other methods.',
+            status: 403,
+          })
+      }
 
       if (narrowPassthrough)
-        return c.json(Response.validated(schema.ResponseBody, { jsonrpc: '2.0' }), 200)
-      return passthrough(c, chainId)
+        return c.json(
+          Response.validated(schema.ResponseBody, { id: null, jsonrpc: '2.0', result: null }),
+          200,
+        )
+      const notificationOnly = inspectBody
+        ? isNotificationOnly(body)
+        : await inspectNotificationOnly(c.req.raw)
+      return passthrough(c, chainId, { notificationOnly })
     },
   )
 }
@@ -251,9 +285,55 @@ function isPublicMethod(request: unknown): boolean {
   return typeof method === 'string' && method.startsWith('eth_')
 }
 
-function isZoneReadRequest(body: unknown): boolean {
-  const requests = Array.isArray(body) ? body : [body]
-  return requests.length > 0 && requests.every((request) => isZoneReadMethod(request))
+function isNotificationOnly(body: unknown): boolean {
+  const parsed = schema.RequestBody.safeParse(body)
+  if (!parsed.success) return false
+  const requests = Array.isArray(parsed.data) ? parsed.data : [parsed.data]
+  return requests.length > 0 && requests.every((request) => request.id === undefined)
+}
+
+async function inspectNotificationOnly(request: Request): Promise<boolean> {
+  const contentLength = Number(request.headers.get('content-length'))
+  if (Number.isFinite(contentLength) && contentLength > maxRpcInspectionBytes) return false
+  const body = request.clone().body
+  if (!body) return false
+
+  const reader = body.getReader()
+  const chunks: Uint8Array<ArrayBuffer>[] = []
+  let size = 0
+  let complete = false
+  while (size <= maxRpcInspectionBytes) {
+    const read = await reader.read()
+    if (read.done) {
+      complete = true
+      break
+    }
+    chunks.push(read.value)
+    size += read.value.byteLength
+  }
+  if (!complete || size > maxRpcInspectionBytes) {
+    void reader.cancel()
+    return false
+  }
+
+  const bytes = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  try {
+    return isNotificationOnly(JSON.parse(new TextDecoder().decode(bytes)) as unknown)
+  } catch {
+    return false
+  }
+}
+
+function hasZoneWriteScope(c: Context<App.Environment>, chainId: number): boolean {
+  const principal = Auth.getPrincipal(c)
+  if (principal?.type !== 'api_key') return false
+  const scopes = principal.apiKey.scopes
+  return scopes.includes(Scope.wildcard) || scopes.includes(`zone:${chainId}:write`)
 }
 
 function isZoneReadMethod(request: unknown): boolean {
@@ -262,19 +342,37 @@ function isZoneReadMethod(request: unknown): boolean {
   return typeof method === 'string' && zoneReadMethods.has(method)
 }
 
+function isZoneWriteMethod(request: unknown): boolean {
+  if (!request || typeof request !== 'object') return false
+  const method = (request as Record<string, unknown>)['method']
+  return typeof method === 'string' && zoneWriteMethods.has(method)
+}
+
 async function passthrough(
   c: Context<App.Environment>,
   chainId: z.output<typeof Schema.ChainId>,
+  options: passthrough.Options,
 ): Promise<globalThis.Response & TypedResponse<never, never, never>> {
+  // Keep caller-selected values out of metric dimensions even if an upstream
+  // resolver accepts a chain the deployment did not declare.
+  const alertChainId = c.get('supportedChainIds').has(chainId) ? chainId : 0
   const zone = c.get('zones').get(chainId)
   const zoneToken = getZoneToken(c)
-  const rpc = zone && zoneToken ? { url: () => zone.forwardRpcUrl } : c.get('rpc')
+  const rpc = c.get('rpc')
   const principal = Auth.getPrincipal(c)
   const upstream_rpc =
     !zone && principal?.type === 'public' && typeof rpc !== 'function' ? undefined : rpc
   // Anonymous callers use the built-in public RPC unless a resolver chooses a
   // different public upstream.
-  const { basicAuth, url } = Viem.resolve(upstream_rpc, { chainId, principal })
+  const {
+    basicAuth,
+    bearerAuth,
+    publicZoneUrl,
+    zoneHeaders,
+    url: resolvedUrl,
+  } = Viem.resolveRpc(upstream_rpc, { chainId, principal, zone })
+  const usePublicZoneUrl = Boolean(zone && zoneToken)
+  const url = usePublicZoneUrl ? publicZoneUrl : resolvedUrl
   // The chain id is syntactically valid but this deployment has no RPC upstream
   // configured for it (no `rpc` config and no built-in default).
   if (!url)
@@ -288,7 +386,10 @@ async function passthrough(
   const headers = new Headers()
   for (const [name, value] of c.req.raw.headers)
     if (!strippedHeaders.has(name.toLowerCase())) headers.set(name, value)
-  if (basicAuth) headers.set('authorization', `Basic ${btoa(basicAuth)}`)
+  if (zoneHeaders) for (const [name, value] of new Headers(zoneHeaders)) headers.set(name, value)
+  // Public Zone endpoints authenticate with the caller's token, never internal RPC credentials.
+  if (!usePublicZoneUrl && basicAuth) headers.set('authorization', `Basic ${btoa(basicAuth)}`)
+  else if (!usePublicZoneUrl && bearerAuth) headers.set('authorization', `Bearer ${bearerAuth}`)
   if (zone && zoneToken) headers.set(ZoneRpcAuthentication.headerName, zoneToken)
 
   // `duplex` is required when streaming a request body, but is not yet in
@@ -306,18 +407,137 @@ async function passthrough(
 
   try {
     const response = await fetch(new Request(upstream, init))
+    let body = response.body
+
+    if (!response.ok) {
+      // Malformed requests and public Zone authentication failures are caused
+      // by caller input, not by the RPC provider.
+      if (!isCallerRpcFailure(response.status, usePublicZoneUrl))
+        c.set('providerFailure', rpcProviderFailure(response, alertChainId))
+    } else if (response.status === 200) {
+      const inspection = await inspectRpcResponse(response)
+      body = inspection.body
+      if (inspection.result?.ok === false && !(inspection.result.empty && options.notificationOnly))
+        c.set('providerFailure', {
+          chainId: alertChainId,
+          failure: 'payload',
+          id: 'rpc',
+          operation: 'request',
+        })
+      else if (inspection.result?.ok) {
+        const parsed = schema.ResponseBody.safeParse(inspection.result.value)
+        if (!parsed.success)
+          c.set('providerFailure', {
+            chainId: alertChainId,
+            failure: 'payload',
+            id: 'rpc',
+            operation: 'request',
+          })
+        else {
+          const rpc = Log.rpcErrors(parsed.data)
+          if (rpc) c.set('rpcResponse', rpc)
+        }
+      }
+    }
 
     // Stream the upstream response back verbatim so JSON-RPC bodies, status
     // codes, and headers survive exactly as clients expect.
-    return c.newResponse(response.body, response) as globalThis.Response &
-      TypedResponse<never, never, never>
+    return c.newResponse(body, response) as globalThis.Response & TypedResponse<never, never, never>
   } catch (cause) {
     // Timeouts and network failures become the standard 502 envelope instead
     // of an unhandled 500.
+    c.set('providerFailure', rpcProviderFailure(cause, alertChainId))
     return Response.upstream(c, cause) as never
   }
 }
 
+function isCallerRpcFailure(status: number, usePublicZoneUrl: boolean) {
+  return (
+    status === 400 ||
+    status === 413 ||
+    status === 415 ||
+    status === 422 ||
+    (usePublicZoneUrl && (status === 401 || status === 403))
+  )
+}
+
+declare namespace passthrough {
+  /** Request facts needed to classify the upstream response. */
+  type Options = {
+    /** Whether every valid request in the payload omits an id. */
+    notificationOnly: boolean
+  }
+}
+
+async function inspectRpcResponse(response: globalThis.Response): Promise<RpcInspection> {
+  const contentLength = Number(response.headers.get('content-length'))
+  if (Number.isFinite(contentLength) && contentLength > maxRpcInspectionBytes)
+    return { body: response.body, result: undefined }
+  if (!response.body) return { body: null, result: { empty: true, ok: false } }
+
+  const reader = response.body.getReader()
+  const chunks: Uint8Array<ArrayBuffer>[] = []
+  let size = 0
+  let complete = false
+  while (size <= maxRpcInspectionBytes) {
+    const read = await reader.read()
+    if (read.done) {
+      complete = true
+      break
+    }
+    chunks.push(read.value)
+    size += read.value.byteLength
+  }
+
+  let index = 0
+  const body = new ReadableStream<Uint8Array<ArrayBuffer>>({
+    cancel: (reason) => reader.cancel(reason),
+    async pull(controller) {
+      const chunk = chunks[index]
+      if (chunk) {
+        index += 1
+        controller.enqueue(chunk)
+        return
+      }
+      const read = await reader.read()
+      if (read.done) controller.close()
+      else controller.enqueue(read.value)
+    },
+  })
+  if (!complete || size > maxRpcInspectionBytes) return { body, result: undefined }
+
+  const bytes = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  const result = (() => {
+    try {
+      return { ok: true as const, value: JSON.parse(new TextDecoder().decode(bytes)) as unknown }
+    } catch {
+      return { empty: size === 0, ok: false as const }
+    }
+  })()
+  return { body, result }
+}
+
+function rpcProviderFailure(cause: unknown, chainId: number): Log.ProviderFailure {
+  const base = { chainId, id: 'rpc', operation: 'request' } as const
+  if (
+    cause instanceof DOMException &&
+    (cause.name === 'AbortError' || cause.name === 'TimeoutError')
+  )
+    return { ...base, failure: 'timeout' }
+  if (cause instanceof globalThis.Response) {
+    if (cause.status === 408) return { ...base, failure: 'timeout', status: cause.status }
+    if (cause.status === 429) return { ...base, failure: 'rate_limit', status: cause.status }
+    return { ...base, failure: 'http', status: cause.status }
+  }
+  if (cause instanceof TypeError) return { ...base, failure: 'network' }
+  return { ...base, failure: 'unknown' }
+}
+
 function resolveChainId(c: Context<App.Environment>) {
   const parameter = c.req.param('chain')
   if (parameter === undefined) return c.get('chainId')

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

@@ -1,4 +1,4 @@
-import { Hono } from 'hono'
+import { Hono, type Context } from 'hono'
 import * as z from 'zod/mini'
 
 import type * as App from '../../../App.js'
@@ -8,6 +8,7 @@ import * as EdgeCache from '../../../internal/EdgeCache.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
+import * as Timing from '../../../internal/Timing.js'
 import * as VerifiedTokens from '../../../internal/VerifiedTokens.js'
 import * as Viem from '../../../internal/Viem.js'
 import { getTokenLogo } from './tokens.js'
@@ -160,7 +161,8 @@ export function tokenlist() {
       summary: 'Get token list',
       tags: ['Verified Tokens'],
     }),
-    // The shared edge cache is URL-keyed and cannot include the snapshot version.
+    // Anonymous callers accept the route's five-minute freshness window.
+    // Credentialed reads keep snapshot-version invalidation.
     EdgeCache.setEligibility(
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.stable,
@@ -175,7 +177,7 @@ export function tokenlist() {
           return `${base}:v:${version}`
         },
       }),
-      () => false,
+      anonymousEdgeCache,
     ),
     async (c) => {
       if (Auth.narrowAccess) return Auth.paidAccessError(c)
@@ -189,22 +191,18 @@ export function tokenlist() {
       const chainId = query.chainId ?? c.get('chainId')
       try {
         const snapshot = await VerifiedTokens.snapshot(c, chainId)
-        const tokens = await Promise.all(
-          snapshot.list.map(async (token) => {
-            // Prefer the curated icon asset (served by the API), falling back to
-            // the verified entry's stored `logoUri`. Most verified tokens carry
-            // no stored `logoUri` — their logo lives in the asset store.
-            const logoURI = (await getTokenLogo(c, { address: token.address, chainId })) ?? token.logoUri // prettier-ignore
-            return {
-              chainId,
-              address: token.address,
-              name: token.name,
-              symbol: token.symbol,
-              decimals: token.decimals,
-              ...(logoURI === undefined ? {} : { logoURI }),
-            }
-          }),
-        )
+        const logos = await getTokenLogos(c, { chainId, tokens: snapshot.list })
+        const tokens = snapshot.list.map((token) => {
+          const logoURI = logos.get(token.address) ?? token.logoUri
+          return {
+            chainId,
+            address: token.address,
+            name: token.name,
+            symbol: token.symbol,
+            decimals: token.decimals,
+            ...(logoURI === undefined ? {} : { logoURI }),
+          }
+        })
         const list = {
           name: Viem.chains.find((chain) => chain.id === chainId)?.name ?? `Tempo ${chainId}`,
           timestamp: snapshot.updatedAt,
@@ -218,3 +216,58 @@ export function tokenlist() {
     },
   )
 }
+
+function anonymousEdgeCache(c: Context<App.Environment>) {
+  return (
+    !c.req.header('authorization') &&
+    !c.req.header('cookie') &&
+    !c.req.header('tempo-api-key') &&
+    !c.req.header('x-api-key')
+  )
+}
+
+async function getTokenLogos(
+  c: Context<App.Environment>,
+  options: getTokenLogos.Options,
+): Promise<ReadonlyMap<string, string>> {
+  return Timing.time(c, 'token_logos', async () => {
+    const getAsset = c.get('getAsset')
+    const listAssets = getAsset.list
+    if (!listAssets) {
+      const entries = await Promise.all(
+        options.tokens.map(
+          async (token) =>
+            [
+              token.address,
+              await getTokenLogo(c, { address: token.address, chainId: options.chainId }).catch(
+                () => undefined,
+              ),
+            ] as const,
+        ),
+      )
+      const logos = new Map<string, string>()
+      for (const [address, uri] of entries) if (uri) logos.set(address, uri)
+      return logos
+    }
+
+    // Logos are optional metadata; an asset-store outage must not hide the
+    // verified token list itself. Snapshot logo URIs remain available below.
+    const assets = await listAssets(options.chainId, 'icons/').catch(() => [])
+    const uris = new Map(assets.map((asset) => [asset.key, asset.uri]))
+    return new Map(
+      options.tokens.flatMap((token) => {
+        const uri = uris.get(`${options.chainId}/icons/${token.address}`)
+        return uri ? [[token.address, uri] as const] : []
+      }),
+    )
+  })
+}
+
+declare namespace getTokenLogos {
+  type Options = {
+    /** Tempo chain containing the token assets. */
+    chainId: number
+    /** Verified tokens whose curated logo locations should be resolved. */
+    tokens: readonly Pick<VerifiedTokens.Token, 'address'>[]
+  }
+}

package/src/apps/data/routes/tokens.test.ts

@@ -274,7 +274,6 @@ describe('GET /tokens?verified=true', () => {
 describe('GET /tokens?addresses=', () => {
   test('separates repeated addresses in the response cache', async () => {
     const routed = TestApp.create({ db })
-    const headers = { authorization: `Bearer ${TestApp.key.token}` }
     const repeated = new URLSearchParams()
     repeated.append('addresses', TestApp.token)
     repeated.append('addresses', TestApp.tokenWithHolders)
@@ -282,9 +281,9 @@ describe('GET /tokens?addresses=', () => {
       addresses: TestApp.tokenWithHolders,
     })
 
-    const primed = await routed.request(`/v1/tokens?${repeated}`, { headers })
-    const miss = await routed.request(`/v1/tokens?${single}`, { headers })
-    const hit = await routed.request(`/v1/tokens?${single}`, { headers })
+    const primed = await routed.request(`/v1/tokens?${repeated}`)
+    const miss = await routed.request(`/v1/tokens?${single}`)
+    const hit = await routed.request(`/v1/tokens?${single}`)
     const primedBody = await TestApp.json(primed, Tokens.schema.getTokens.Response)
     const body = await TestApp.json(hit, Tokens.schema.getTokens.Response)
 
@@ -302,7 +301,6 @@ describe('GET /tokens?addresses=', () => {
 
   test('separates repeated includes in the response cache', async () => {
     const routed = TestApp.create({ db })
-    const headers = { authorization: `Bearer ${TestApp.key.token}` }
     const repeated = new URLSearchParams({ limit: '5' })
     repeated.append('include', 'createdAt')
     repeated.append('include', 'holderCount')
@@ -311,9 +309,9 @@ describe('GET /tokens?addresses=', () => {
       limit: '5',
     })
 
-    const primed = await routed.request(`/v1/tokens?${repeated}`, { headers })
-    const miss = await routed.request(`/v1/tokens?${single}`, { headers })
-    const hit = await routed.request(`/v1/tokens?${single}`, { headers })
+    const primed = await routed.request(`/v1/tokens?${repeated}`)
+    const miss = await routed.request(`/v1/tokens?${single}`)
+    const hit = await routed.request(`/v1/tokens?${single}`)
     const primedBody = await TestApp.json(primed, Tokens.schema.getTokens.Response)
     const body = await TestApp.json(hit, Tokens.schema.getTokens.Response)