tapimo 0.14.0 → 0.15.1

package/dist/apps/data/routes/rpc.js

@@ -8,6 +8,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
 // reach the RPC service (the proxy injects its own RPC basic auth instead).
@@ -26,199 +27,257 @@ const strippedHeaders = new Set([
     'x-api-key',
     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',
+    name: ZoneRpcAuthentication.headerName,
+    required: false,
+    schema: { pattern: '^0x[0-9a-fA-F]+$', type: 'string' },
+};
 /** Never reached; carries typed passthrough response variants into Hono client inference. */
 const narrowPassthrough = false;
 /** Zod schemas owned by the raw RPC passthrough. */
 export var schema;
 (function (schema) {
     /** JSON-RPC request identifier. */
-    schema.Id = z
-        .union([z.string(), z.number(), z.null()])
-        .check(z.describe('Client-supplied JSON-RPC request id used to match responses to requests.'));
+    schema.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. */
-    schema.Error = z
+    schema.Error = OpenApi.component(z
         .object({
         code: z
             .number()
-            .check(z.int(), z.describe('Numeric JSON-RPC error code returned by the upstream RPC server.')),
+            .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.')),
-        message: z.string().check(z.describe('Human-readable JSON-RPC error message.')),
+            .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.'));
+        .check(z.describe('JSON-RPC error object returned when a method fails.')), 'JsonRpcError');
     /** JSON-RPC request payload. */
-    schema.Request = z
+    schema.Request = OpenApi.component(z
         .object({
         id: z
             .optional(schema.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`.')),
+            .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`.')),
+            .check(z.describe('Ethereum JSON-RPC method to call, such as `eth_blockNumber`.'), z.meta({ examples: ['eth_blockNumber'] })),
         params: z
-            .optional(z.unknown())
-            .check(z.describe('Parameters for the JSON-RPC method, usually an array.')),
+            .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.'));
-    /** JSON-RPC response payload. */
-    schema.Response = z
-        .object({
-        error: z
-            .optional(schema.Error)
-            .check(z.describe('JSON-RPC error object returned when a method fails.')),
-        id: schema.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`.')),
+        .check(z.describe('One Ethereum JSON-RPC request to send to Tempo.')), 'JsonRpcRequest');
+    /** Successful JSON-RPC response payload. */
+    schema.SuccessResponse = OpenApi.component(z
+        .strictObject({
+        id: schema.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
-            .optional(z.unknown())
-            .check(z.describe('Result returned by the upstream RPC method.')),
+            .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. */
+    schema.ErrorResponse = OpenApi.component(z
+        .strictObject({
+        error: schema.Error.check(z.describe('JSON-RPC error returned by the upstream RPC server.')),
+        id: schema.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.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.'));
+        .check(z.describe('A failed JSON-RPC response returned by Tempo.')), 'JsonRpcErrorResponse');
+    /** JSON-RPC success or error response payload. */
+    schema.Response = OpenApi.component(z
+        .union([schema.SuccessResponse, schema.ErrorResponse])
+        .check(z.describe('One JSON-RPC response returned by Tempo.')), 'JsonRpcResponse');
     /** JSON-RPC request or batch request payload. */
-    schema.RequestBody = z
-        .union([schema.Request, z.array(schema.Request)])
-        .check(z.describe('A single JSON-RPC request or an array of requests for batch calls.'));
+    schema.RequestBody = OpenApi.component(z
+        .union([
+        schema.Request,
+        z.array(schema.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. */
-    schema.ResponseBody = z
-        .union([schema.Response, z.array(schema.Response).check(z.minLength(1))])
-        .check(z.describe('A single JSON-RPC response or an array of responses for batch calls.'));
+    schema.ResponseBody = OpenApi.component(z
+        .union([
+        z
+            .null()
+            .check(z.describe('Empty JSON value returned for notification requests.'), z.meta({ examples: [null] })),
+        schema.Response,
+        z.array(schema.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');
 })(schema || (schema = {}));
+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().post('/rpc/:chain{(mainnet|testnet|[0-9]+)}?', Auth.policy({
+    const auth = 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.',
+    });
+    return new Hono()
+        .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) {
+    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 inspectRpcRequest(c.req.raw) : undefined;
+    if (inspection && inspection.result === undefined) {
+        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: 'Optional chain selector. Use the alias `mainnet` or `testnet`, or a numeric chain id (mainnet is `4217`).',
+                description: 'Chain selector. Use the alias `mainnet` or `testnet`, or a numeric chain id (mainnet is `4217`).',
                 example: 'testnet',
                 in: 'path',
                 name: 'chain',
-                required: false,
+                required: true,
                 schema: { pattern: '^(mainnet|testnet|[0-9]+)$', type: 'string' },
             },
+            zoneTokenParameter,
         ],
-        requestBody: {
-            content: {
-                'application/json': {
-                    example: { jsonrpc: '2.0', id: 1, method: 'eth_blockNumber', params: [] },
-                },
-            },
-            required: true,
-        },
-        responses: OpenApi.responses({
+        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'],
                 },
-                502: 'The upstream Tempo RPC endpoint could not complete the request.',
+                413: {
+                    codes: ['payload_too_large'],
+                    description: 'Zone and anonymous RPC requests must not exceed 64 KiB.',
+                },
+                502: 'The Tempo API could not reach the upstream RPC endpoint.',
             },
             success: {
-                description: 'JSON-RPC response returned by the upstream Tempo RPC endpoint.',
-                example: { jsonrpc: '2.0', id: 1, result: '0x10f2c' },
+                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,
             },
         }),
-        summary: 'Call JSON-RPC',
-        tags: ['RPC'],
-    }), 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) {
     if (!c.get('auth'))
@@ -241,7 +300,7 @@ function isPublicMethod(request) {
     return typeof method === 'string' && method.startsWith('eth_');
 }
 function isNotificationOnly(body) {
-    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];
@@ -284,6 +343,37 @@ async function inspectNotificationOnly(request) {
         return false;
     }
 }
+async function inspectRpcRequest(request) {
+    const contentLength = Number(request.headers.get('content-length'));
+    if (Number.isFinite(contentLength) && contentLength > maxRpcInspectionBytes) {
+        await request.body?.cancel();
+        return { body: null, result: undefined };
+    }
+    if (!request.body)
+        return { body: null, result: { empty: true, ok: false } };
+    const reader = request.body.getReader();
+    const chunks = [];
+    let size = 0;
+    while (size <= maxRpcInspectionBytes) {
+        const read = await reader.read();
+        if (read.done)
+            break;
+        size += read.value.byteLength;
+        if (size > maxRpcInspectionBytes) {
+            await reader.cancel();
+            return { body: null, result: undefined };
+        }
+        chunks.push(read.value);
+    }
+    const bytes = joinChunks(chunks, size);
+    const body = new ReadableStream({
+        start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+        },
+    });
+    return { body, result: parseRpcBody(bytes) };
+}
 function hasZoneWriteScope(c, chainId) {
     const principal = Auth.getPrincipal(c);
     if (principal?.type !== 'api_key')
@@ -295,13 +385,19 @@ function isZoneReadMethod(request) {
     if (!request || typeof request !== 'object')
         return false;
     const method = request['method'];
-    return typeof method === 'string' && zoneReadMethods.has(method);
+    return typeof method === 'string' && ZoneRpc.readMethods.has(method);
 }
 function isZoneWriteMethod(request) {
     if (!request || typeof request !== 'object')
         return false;
     const method = request['method'];
-    return typeof method === 'string' && zoneWriteMethods.has(method);
+    return typeof method === 'string' && ZoneRpc.writeMethods.has(method);
+}
+function isZoneTokenMethod(request) {
+    if (!request || typeof request !== 'object')
+        return false;
+    const method = request['method'];
+    return typeof method === 'string' && ZoneRpc.tokenMethods.has(method);
 }
 async function passthrough(c, chainId, options) {
     // Keep caller-selected values out of metric dimensions even if an upstream
@@ -316,6 +412,11 @@ async function passthrough(c, chainId, options) {
     // different public upstream.
     const { basicAuth, bearerAuth, publicZoneUrl, zoneHeaders, 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);
+    }
     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).
@@ -340,16 +441,16 @@ async function passthrough(c, chainId, options) {
         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 = {
+        // 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';
     }
     try {
@@ -358,18 +459,52 @@ async function passthrough(c, chainId, options) {
         // 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 });
+                }
                 c.set('providerFailure', {
                     chainId: alertChainId,
                     failure: 'payload',
                     id: 'rpc',
                     operation: 'request',
                 });
+            }
+            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)
@@ -386,8 +521,8 @@ async function passthrough(c, chainId, options) {
                 }
             }
         }
-        // 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);
     }
     catch (cause) {
@@ -417,9 +552,14 @@ async function isCallerRpcFailure(response, usePublicZoneUrl) {
     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;
+    });
 }
-async function inspectRpcResponse(response) {
+async function inspectRpcBody(response) {
     const contentLength = Number(response.headers.get('content-length'));
     if (Number.isFinite(contentLength) && contentLength > maxRpcInspectionBytes)
         return { body: response.body, result: undefined };
@@ -457,21 +597,25 @@ async function inspectRpcResponse(response) {
     });
     if (!complete || size > maxRpcInspectionBytes)
         return { body, result: undefined };
+    const bytes = joinChunks(chunks, size);
+    return { body, result: parseRpcBody(bytes) };
+}
+function joinChunks(chunks, size) {
     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, value: JSON.parse(new TextDecoder().decode(bytes)) };
-        }
-        catch {
-            return { empty: size === 0, ok: false };
-        }
-    })();
-    return { body, result };
+    return bytes;
+}
+function parseRpcBody(bytes) {
+    try {
+        return { ok: true, value: JSON.parse(new TextDecoder().decode(bytes)) };
+    }
+    catch {
+        return { empty: bytes.byteLength === 0, ok: false };
+    }
 }
 function rpcProviderFailure(cause, chainId) {
     const base = { chainId, id: 'rpc', operation: 'request' };