tapimo 0.13.0 → 0.15.0

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

@@ -10,6 +10,7 @@ import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
 import * as Viem from '../../../internal/Viem.js'
+import * as ZoneRpc from '../../../internal/ZoneRpc.js'
 
 // Request headers that must not be forwarded upstream: hop-by-hop headers, the
 // inbound host, and any caller auth so the consumer's Tempo API credentials never
@@ -30,54 +31,17 @@ const strippedHeaders = new Set([
   ZoneRpcAuthentication.headerName.toLowerCase(),
 ])
 
-// API-issued Zone read scopes never reach stateful or privileged RPC modules.
-const zoneReadMethods = new Set([
-  'eth_blobBaseFee',
-  'eth_blockNumber',
-  'eth_call',
-  'eth_chainId',
-  'eth_createAccessList',
-  'eth_estimateGas',
-  'eth_feeHistory',
-  'eth_fillTransaction',
-  'eth_gasPrice',
-  'eth_getBalance',
-  'eth_getBlockByHash',
-  'eth_getBlockByNumber',
-  'eth_getBlockReceipts',
-  'eth_getBlockTransactionCountByHash',
-  'eth_getBlockTransactionCountByNumber',
-  'eth_getCode',
-  'eth_getLogs',
-  'eth_getProof',
-  'eth_getRawTransactionByHash',
-  'eth_getStorageAt',
-  'eth_getTransactionByBlockHashAndIndex',
-  'eth_getTransactionByBlockNumberAndIndex',
-  'eth_getTransactionByHash',
-  'eth_getTransactionCount',
-  'eth_getTransactionReceipt',
-  'eth_getUncleByBlockHashAndIndex',
-  'eth_getUncleByBlockNumberAndIndex',
-  'eth_getUncleCountByBlockHash',
-  'eth_getUncleCountByBlockNumber',
-  'eth_maxPriorityFeePerGas',
-  'eth_simulateV1',
-  'eth_syncing',
-  'net_listening',
-  'net_peerCount',
-  '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
+const exampleZoneToken =
+  '0x3844647dc3ffc87cb42fdd4112431720a60e33a8c5b42156784b8440b82e360a63c5e71109b8d22eb103650d0df75fa63af4e072400f9cf8a53eb778592c71931b00000000010000000054e53ef3000000006a8df314000000006a8df440'
+const zoneTokenParameter = {
+  description: 'Optional signed Zone credential forwarded only to the selected Zone RPC.',
+  example: exampleZoneToken,
+  in: 'header' as const,
+  name: ZoneRpcAuthentication.headerName,
+  required: false,
+  schema: { pattern: '^0x[0-9a-fA-F]+$', type: 'string' as const },
+}
 
 /** Never reached; carries typed passthrough response variants into Hono client inference. */
 const narrowPassthrough = false as boolean
@@ -90,181 +54,353 @@ type RpcInspection = {
 /** Zod schemas owned by the raw RPC passthrough. */
 export namespace schema {
   /** JSON-RPC request identifier. */
-  export const Id = z
-    .union([z.string(), z.number(), z.null()])
-    .check(z.describe('Client-supplied JSON-RPC request id used to match responses to requests.'))
+  export const Id = OpenApi.component(
+    z
+      .union([
+        z.string().check(z.meta({ examples: ['request-1'] })),
+        z.number().check(z.meta({ examples: [1] })),
+        z.null(),
+      ])
+      .check(
+        z.describe('Client-supplied JSON-RPC request id used to match responses to requests.'),
+        z.meta({ examples: [1, 'request-1', null] }),
+      ),
+    'JsonRpcId',
+  )
 
   /** JSON-RPC error payload. */
-  export const Error = z
-    .object({
-      code: z
-        .number()
-        .check(
-          z.int(),
-          z.describe('Numeric JSON-RPC error code returned by the upstream RPC server.'),
-        ),
-      data: z
-        .optional(z.unknown())
-        .check(z.describe('Optional extra error details returned by the upstream RPC server.')),
-      message: z.string().check(z.describe('Human-readable JSON-RPC error message.')),
-    })
-    .check(z.describe('JSON-RPC error object returned when a method fails.'))
+  export const Error = OpenApi.component(
+    z
+      .object({
+        code: z
+          .number()
+          .check(
+            z.int(),
+            z.describe('Numeric JSON-RPC error code returned by the upstream RPC server.'),
+            z.meta({ examples: [-32_601] }),
+          ),
+        data: z
+          .optional(z.unknown())
+          .check(
+            z.describe('Optional extra error details returned by the upstream RPC server.'),
+            z.meta({ examples: [{ method: 'tempo_fundAddress' }] }),
+          ),
+        message: z
+          .string()
+          .check(
+            z.describe('Human-readable JSON-RPC error message.'),
+            z.meta({ examples: ['Method not found'] }),
+          ),
+      })
+      .check(z.describe('JSON-RPC error object returned when a method fails.')),
+    'JsonRpcError',
+  )
 
   /** JSON-RPC request payload. */
-  export const Request = z
-    .object({
-      id: z
-        .optional(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`.')),
-      method: z
-        .string()
-        .check(z.describe('Ethereum JSON-RPC method to call, such as `eth_blockNumber`.')),
-      params: z
-        .optional(z.unknown())
-        .check(z.describe('Parameters for the JSON-RPC method, usually an array.')),
-    })
-    .check(z.describe('One Ethereum JSON-RPC request to send to Tempo.'))
-
-  /** JSON-RPC response payload. */
-  export const Response = z
-    .object({
-      error: z
-        .optional(Error)
-        .check(z.describe('JSON-RPC error object returned when a method fails.')),
-      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.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.'),
-    )
+  export const Request = OpenApi.component(
+    z
+      .object({
+        id: z
+          .optional(Id)
+          .check(
+            z.describe(
+              'Client-supplied JSON-RPC request id used to match responses; omit for a notification.',
+            ),
+            z.meta({ examples: [1] }),
+          ),
+        jsonrpc: z
+          .literal('2.0')
+          .check(
+            z.describe('JSON-RPC protocol version; Tempo uses `2.0`.'),
+            z.meta({ examples: ['2.0'] }),
+          ),
+        method: z
+          .string()
+          .check(
+            z.describe('Ethereum JSON-RPC method to call, such as `eth_blockNumber`.'),
+            z.meta({ examples: ['eth_blockNumber'] }),
+          ),
+        params: z
+          .optional(z.union([z.array(z.unknown()), z.record(z.string(), z.unknown())]))
+          .check(
+            z.describe('Positional array or named object parameters for the JSON-RPC method.'),
+            z.meta({ examples: [[]] }),
+          ),
+      })
+      .check(z.describe('One Ethereum JSON-RPC request to send to Tempo.')),
+    'JsonRpcRequest',
+  )
+
+  /** Successful JSON-RPC response payload. */
+  export const SuccessResponse = OpenApi.component(
+    z
+      .strictObject({
+        id: Id.check(z.meta({ examples: [1] })),
+        jsonrpc: z
+          .literal('2.0')
+          .check(
+            z.describe('JSON-RPC protocol version; Tempo uses `2.0`.'),
+            z.meta({ examples: ['2.0'] }),
+          ),
+        result: z
+          .unknown()
+          .check(
+            z.describe('Result returned by the upstream RPC method.'),
+            z.meta({ examples: ['0x10f2c'] }),
+          ),
+      })
+      .check(z.describe('A successful JSON-RPC response returned by Tempo.')),
+    'JsonRpcSuccessResponse',
+  )
+
+  /** Failed JSON-RPC response payload. */
+  export const ErrorResponse = OpenApi.component(
+    z
+      .strictObject({
+        error: Error.check(z.describe('JSON-RPC error returned by the upstream RPC server.')),
+        id: Id.check(z.meta({ examples: [1] })),
+        jsonrpc: z
+          .literal('2.0')
+          .check(
+            z.describe('JSON-RPC protocol version; Tempo uses `2.0`.'),
+            z.meta({ examples: ['2.0'] }),
+          ),
+      })
+      .check(z.describe('A failed JSON-RPC response returned by Tempo.')),
+    'JsonRpcErrorResponse',
+  )
+
+  /** JSON-RPC success or error response payload. */
+  export const Response = OpenApi.component(
+    z
+      .union([SuccessResponse, ErrorResponse])
+      .check(z.describe('One JSON-RPC response returned by Tempo.')),
+    'JsonRpcResponse',
+  )
 
   /** JSON-RPC request or batch request payload. */
-  export const RequestBody = z
-    .union([Request, z.array(Request)])
-    .check(z.describe('A single JSON-RPC request or an array of requests for batch calls.'))
+  export const RequestBody = OpenApi.component(
+    z
+      .union([
+        Request,
+        z.array(Request).check(
+          z.minLength(1),
+          z.meta({
+            examples: [
+              [
+                { id: 1, jsonrpc: '2.0', method: 'eth_blockNumber', params: [] },
+                { id: 2, jsonrpc: '2.0', method: 'eth_chainId', params: [] },
+              ],
+            ],
+          }),
+        ),
+      ])
+      .check(
+        z.describe('A single JSON-RPC request or an array of requests for batch calls.'),
+        z.meta({
+          examples: [{ id: 1, jsonrpc: '2.0', method: 'eth_blockNumber', params: [] }],
+        }),
+      ),
+    'JsonRpcRequestBody',
+  )
 
   /** JSON-RPC response or batch response payload. */
-  export const ResponseBody = z
-    .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.'))
+  export const ResponseBody = OpenApi.component(
+    z
+      .union([
+        z
+          .null()
+          .check(
+            z.describe('Empty JSON value returned for notification requests.'),
+            z.meta({ examples: [null] }),
+          ),
+        Response,
+        z.array(Response).check(
+          z.minLength(1),
+          z.meta({
+            examples: [
+              [
+                { id: 1, jsonrpc: '2.0', result: '0x10f2c' },
+                { id: 2, jsonrpc: '2.0', result: '0x1069' },
+              ],
+            ],
+          }),
+        ),
+      ])
+      .check(z.describe('A single JSON-RPC response or an array of responses for batch calls.')),
+    'JsonRpcResponseBody',
+  )
 }
 
+const inspectionRequest = z.object({
+  id: z.optional(schema.Id),
+  jsonrpc: z.literal('2.0'),
+  method: z.string(),
+  params: z.optional(z.unknown()),
+})
+const inspectionRequestBody = z.union([inspectionRequest, z.array(inspectionRequest)])
+
 /** Creates the raw Tempo RPC passthrough handler. */
 export function rpc() {
-  return new Hono<App.Environment>().post(
-    '/rpc/:chain{(mainnet|testnet|[0-9]+)}?',
-    Auth.policy({
-      apiKey: { scopes: ['data:read'] },
-      public: { rateLimit: { limit: 20, period: 'second' } },
-    }),
-    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 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: [
-        {
-          description:
-            'Optional chain selector. Use the alias `mainnet` or `testnet`, or a numeric chain id (mainnet is `4217`).',
-          example: 'testnet',
-          in: 'path' as const,
-          name: 'chain',
-          required: false,
-          schema: { pattern: '^(mainnet|testnet|[0-9]+)$', type: 'string' as const },
-        },
-      ],
-      requestBody: {
-        content: {
-          'application/json': {
-            example: { jsonrpc: '2.0', id: 1, method: 'eth_blockNumber', params: [] },
-          },
-        },
+  const auth = Auth.policy({
+    apiKey: { scopes: ['data:read'] },
+    public: { rateLimit: { limit: 20, period: 'second' } },
+  })
+  return new Hono<App.Environment>()
+    .post(
+      '/rpc',
+      auth,
+      OpenApi.documentJsonRequest(schema.RequestBody),
+      describeRootRpcRoute(),
+      (c) => handleRpc(c),
+    )
+    .post(
+      '/rpc/:chain{(mainnet|testnet|[0-9]+)}',
+      auth,
+      OpenApi.documentJsonRequest(schema.RequestBody),
+      describeChainRpcRoute(),
+      (c) => handleRpc(c),
+    )
+}
+
+async function handleRpc(c: Context<App.Environment>) {
+  if (Auth.narrowAccess) return Auth.accessError(c)
+
+  const chainId = resolveChainId(c)
+  if (!chainId)
+    return Response.error(c, {
+      code: 'chain_id_invalid',
+      message: 'Invalid chain id',
+      status: 400,
+    })
+
+  const zone = c.get('zones').get(chainId)
+  const zoneToken = getZoneToken(c)
+  const apiKeyRequired = requiresApiKey(c)
+  const inspectBody = apiKeyRequired || Boolean(zone)
+  const inspection = inspectBody ? await inspectRpcBody(c.req.raw) : undefined
+  if (inspection && inspection.result === undefined) {
+    await inspection.body?.cancel()
+    return Response.error(c, {
+      code: 'payload_too_large',
+      message: 'RPC requests requiring method inspection must not exceed 64 KiB.',
+      status: 413,
+    })
+  }
+  const body = inspection?.result?.ok ? inspection.result.value : undefined
+
+  if (apiKeyRequired && !isPublicRequest(body))
+    return Response.error(c, {
+      code: 'api_key_missing',
+      message: 'Missing API key',
+      status: 401,
+    })
+  if (zone) {
+    const requests = Array.isArray(body) ? body : [body]
+    const allowed =
+      requests.length > 0 &&
+      requests.every(
+        (request) =>
+          isZoneReadMethod(request) ||
+          (isZoneWriteMethod(request) && (Boolean(zoneToken) || hasZoneWriteScope(c, chainId))) ||
+          (Boolean(zoneToken) && isZoneTokenMethod(request)),
+      )
+    if (!allowed)
+      return Response.error(c, {
+        code: 'api_key_forbidden',
+        message:
+          'Zone RPC permits read-only methods and signed transaction broadcasts. Broadcasts require a matching Zone write scope or a Zone token; account-scoped methods require a Zone token.',
+        status: 403,
+      })
+  }
+
+  if (narrowPassthrough)
+    return c.json(
+      Response.validated(schema.ResponseBody, { id: null, jsonrpc: '2.0', result: null }),
+      200,
+    )
+  if (narrowPassthrough) return c.body(null, 204)
+  if (narrowPassthrough)
+    return Response.error(c, {
+      code: 'chain_id_unsupported',
+      message: 'Unsupported chain id',
+      status: 400,
+    })
+  if (narrowPassthrough) return Response.upstream(c, new Error('RPC passthrough failed'))
+  const notificationOnly = inspectBody
+    ? isNotificationOnly(body)
+    : await inspectNotificationOnly(c.req.raw)
+  return passthrough(c, chainId, {
+    body: inspection ? inspection.body : c.req.raw.body,
+    notificationOnly,
+  })
+}
+
+function describeRootRpcRoute() {
+  return OpenApi.describeRoute({
+    description:
+      'Proxies single or batch Ethereum JSON-RPC calls to Tempo. Zone API keys are method restricted; nonempty upstream responses pass through unchanged and are outside the stable REST contract.',
+    operationId: 'rpcRequest',
+    parameters: [zoneTokenParameter],
+    responses: rpcResponses(),
+    summary: 'Call JSON-RPC',
+    tags: ['RPC'],
+  })
+}
+
+function describeChainRpcRoute() {
+  return OpenApi.describeRoute({
+    description:
+      'Proxies single or batch Ethereum JSON-RPC calls to a selected Tempo chain. Zone API keys are method restricted; upstream responses pass through unchanged.',
+    operationId: 'rpcRequestByChain',
+    parameters: [
+      {
+        description:
+          'Chain selector. Use the alias `mainnet` or `testnet`, or a numeric chain id (mainnet is `4217`).',
+        example: 'testnet',
+        in: 'path' as const,
+        name: 'chain',
         required: true,
+        schema: { pattern: '^(mainnet|testnet|[0-9]+)$', type: 'string' as const },
       },
-      responses: OpenApi.responses({
-        errors: {
-          400: {
-            description: 'The chain id is invalid or this API deployment does not support it.',
-            codes: ['chain_id_invalid', 'chain_id_unsupported'],
-          },
-          502: 'The upstream Tempo RPC endpoint could not complete the request.',
+      zoneTokenParameter,
+    ],
+    responses: rpcResponses(),
+    summary: 'Call chain JSON-RPC',
+    tags: ['RPC'],
+  })
+}
+
+function rpcResponses() {
+  return {
+    ...OpenApi.responses({
+      errors: {
+        400: {
+          description: 'The chain id is invalid or this API deployment does not support it.',
+          codes: ['chain_id_invalid', 'chain_id_unsupported'],
         },
-        success: {
-          description: 'JSON-RPC response returned by the upstream Tempo RPC endpoint.',
-          example: { jsonrpc: '2.0', id: 1, result: '0x10f2c' },
-          schema: schema.ResponseBody,
+        413: {
+          codes: ['payload_too_large'],
+          description: 'Zone and anonymous RPC requests must not exceed 64 KiB.',
         },
-      }),
-      summary: 'Call JSON-RPC',
-      tags: ['RPC'],
+        502: 'The Tempo API could not reach the upstream RPC endpoint.',
+      },
+      success: {
+        description:
+          'JSON-RPC response returned by the upstream endpoint. Empty 200 responses are normalized to null; unexpected empty responses are reported as provider failures.',
+        example: { id: 1, jsonrpc: '2.0', result: '0x10f2c' },
+        schema: schema.ResponseBody,
+      },
     }),
-    async (c) => {
-      if (Auth.narrowAccess) return Auth.accessError(c)
-
-      const chainId = resolveChainId(c)
-      if (!chainId)
-        return Response.error(c, {
-          code: 'chain_id_invalid',
-          message: 'Invalid chain id',
-          status: 400,
-        })
-
-      const zone = c.get('zones').get(chainId)
-      const zoneToken = getZoneToken(c)
-      const apiKeyRequired = requiresApiKey(c)
-      const inspectBody = apiKeyRequired || Boolean(zone && !zoneToken)
-      const body = inspectBody
-        ? await c.req.raw
-            .clone()
-            .json()
-            .catch(() => undefined)
-        : undefined
-
-      if (apiKeyRequired && !isPublicRequest(body))
-        return Response.error(c, {
-          code: 'api_key_missing',
-          message: 'Missing API key',
-          status: 401,
-        })
-      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, { id: null, jsonrpc: '2.0', result: null }),
-          200,
-        )
-      const notificationOnly = inspectBody
-        ? isNotificationOnly(body)
-        : await inspectNotificationOnly(c.req.raw)
-      return passthrough(c, chainId, { notificationOnly })
+    204: {
+      description: 'Notification accepted with no response body.',
+      headers: OpenApi.successHeaders,
     },
-  )
+    default: {
+      description:
+        'An upstream HTTP response passed through unchanged, including its status, headers, content type, and body.',
+    },
+  }
 }
 
 function requiresApiKey(c: Context<App.Environment>) {
@@ -290,7 +426,7 @@ function isPublicMethod(request: unknown): boolean {
 }
 
 function isNotificationOnly(body: unknown): boolean {
-  const parsed = schema.RequestBody.safeParse(body)
+  const parsed = inspectionRequestBody.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)
@@ -343,13 +479,19 @@ function hasZoneWriteScope(c: Context<App.Environment>, chainId: number): boolea
 function isZoneReadMethod(request: unknown): boolean {
   if (!request || typeof request !== 'object') return false
   const method = (request as Record<string, unknown>)['method']
-  return typeof method === 'string' && zoneReadMethods.has(method)
+  return typeof method === 'string' && ZoneRpc.readMethods.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)
+  return typeof method === 'string' && ZoneRpc.writeMethods.has(method)
+}
+
+function isZoneTokenMethod(request: unknown): boolean {
+  if (!request || typeof request !== 'object') return false
+  const method = (request as Record<string, unknown>)['method']
+  return typeof method === 'string' && ZoneRpc.tokenMethods.has(method)
 }
 
 async function passthrough(
@@ -376,6 +518,11 @@ async function passthrough(
     url: resolvedUrl,
   } = Viem.resolveRpc(upstream_rpc, { chainId, principal, zone })
   const usePublicZoneUrl = Boolean(zone && zoneToken)
+  if (usePublicZoneUrl && !publicZoneUrl) {
+    const cause = new Viem.PublicZoneRpcUnavailableError()
+    c.set('providerFailure', rpcProviderFailure(cause, alertChainId))
+    return Response.upstream(c, cause) as never
+  }
   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).
@@ -396,16 +543,18 @@ async function passthrough(
   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
-  // the DOM `RequestInit` type.
-  const init: RequestInit & { duplex?: 'half' } = {
+  // Node requires duplex for streaming; Workers types omit browser credential handling.
+  type Init = RequestInit & { credentials: 'omit'; duplex?: 'half' }
+  const init: Init = {
+    // Credentials are explicit headers; automatic HTTP auth retries cannot replay a streamed body.
+    credentials: 'omit',
     headers,
     method: c.req.method,
     redirect: 'manual',
     signal: AbortSignal.timeout(35_000),
   }
-  if (c.req.raw.body) {
-    init.body = c.req.raw.body
+  if (options.body) {
+    init.body = options.body
     init.duplex = 'half'
   }
 
@@ -415,20 +564,53 @@ async function passthrough(
     // by caller input, not by the RPC provider.
     if (!response.ok && !(await isCallerRpcFailure(response, usePublicZoneUrl)))
       c.set('providerFailure', rpcProviderFailure(response, alertChainId))
+    if (response.status === 204 && !options.notificationOnly)
+      c.set('providerFailure', {
+        chainId: alertChainId,
+        failure: 'payload',
+        id: 'rpc',
+        operation: 'request',
+      })
 
     // `Response.clone()` replaces the body stream, so capture it after classifying errors.
     let body = response.body
     if (response.status === 200) {
-      const inspection = await inspectRpcResponse(response)
+      const inspection = await inspectRpcBody(response)
       body = inspection.body
-      if (inspection.result?.ok === false && !(inspection.result.empty && options.notificationOnly))
+      if (inspection.result?.ok === false) {
+        if (inspection.result.empty) {
+          if (!options.notificationOnly)
+            c.set('providerFailure', {
+              chainId: alertChainId,
+              failure: 'payload',
+              id: 'rpc',
+              operation: 'request',
+            })
+          const headers = new Headers(response.headers)
+          headers.delete('content-encoding')
+          headers.delete('content-length')
+          headers.delete('content-md5')
+          headers.delete('digest')
+          headers.delete('etag')
+          headers.set('content-type', 'application/json')
+          return c.newResponse('null', { headers, status: 200 }) as globalThis.Response &
+            TypedResponse<never, never, never>
+        }
         c.set('providerFailure', {
           chainId: alertChainId,
           failure: 'payload',
           id: 'rpc',
           operation: 'request',
         })
-      else if (inspection.result?.ok) {
+      } else if (inspection.result?.ok && inspection.result.value === null) {
+        if (!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', {
@@ -444,8 +626,8 @@ async function passthrough(
       }
     }
 
-    // Stream the upstream response back verbatim so JSON-RPC bodies, status
-    // codes, and headers survive exactly as clients expect.
+    // Stream nonempty upstream responses back verbatim so JSON-RPC bodies,
+    // status codes, and headers survive exactly as clients expect.
     return c.newResponse(body, response) as globalThis.Response & TypedResponse<never, never, never>
   } catch (cause) {
     // Timeouts and network failures become the standard 502 envelope instead
@@ -476,18 +658,24 @@ async function isCallerRpcFailure(response: globalThis.Response, usePublicZoneUr
   const parsed = schema.ResponseBody.safeParse(body)
   if (!parsed.success) return false
   const responses = Array.isArray(parsed.data) ? parsed.data : [parsed.data]
-  return responses.every((response) => response.error?.code === -32_601)
+  return responses.every((response) => {
+    if (!response || !('error' in response)) return false
+    const error = schema.Error.safeParse(response.error)
+    return error.success && error.data.code === -32_601
+  })
 }
 
 declare namespace passthrough {
   /** Request facts needed to classify the upstream response. */
   type Options = {
+    /** Original request bytes, replayed after bounded inspection when required. */
+    body: ReadableStream<Uint8Array<ArrayBuffer>> | null
     /** Whether every valid request in the payload omits an id. */
     notificationOnly: boolean
   }
 }
 
-async function inspectRpcResponse(response: globalThis.Response): Promise<RpcInspection> {
+async function inspectRpcBody(response: Request | globalThis.Response): Promise<RpcInspection> {
   const contentLength = Number(response.headers.get('content-length'))
   if (Number.isFinite(contentLength) && contentLength > maxRpcInspectionBytes)
     return { body: response.body, result: undefined }