@hisoka-io/anon-rpc-worker 0.2.0 → 0.3.0

package/dist/anon-rpc-worker.js.keccak256

@@ -1 +1 @@
-0x0a58f9915f686950072a4786249d396ecbf2194a39ac835effe8ea1a7c76f324  anon-rpc-worker.js
+0x24604525d220bcc7e39f2dbc22966a814600a63ada51baafad5dd0bcc1d28549  anon-rpc-worker.js

package/dist/anon-rpc-worker.provenance.json

@@ -3,25 +3,25 @@
     "arch": "x64",
     "os": "linux"
   },
-  "gitCommit": "ef019a716d7994820d7d63d6de3e60ae8f71e80d",
+  "gitCommit": "6bddd851c5b1f4e5508f4718e2ea9b4db626b17f",
   "gitTreeClean": true,
   "inputs": {
     "bootstrapKeccak": "0x6567e3ad5e1b1ac81529391c890d2652695d3ec139d56625170384794085fb74",
-    "lockfileSha256": "0398a97b0a813b2a5305a745bac0233cea4bd9c8c4a3b084873d0e091383a825",
+    "lockfileSha256": "0a205a04cd3b6d861b8fedef8b8e6cd6356642e5f2cd9752ce0e2f403fbae426",
     "snapshotBlock": 316207920,
     "snapshotKeccak": "0xa351960e2c268b9665d1aabec87feaa132d30ade773aef64ef495ec25c94fbb2",
     "wasmKeccak": "0x6ff418a78fc022d34dff00a867e173269413fb6887c9d6bf8e6505d4dcfffe2d",
     "wasmSha256": "5171416972ea4499fd4b4ea8bcadf002f4c10f10ed42cafb0d5a426121da9c4f"
   },
   "output": {
-    "bytes": 924847,
-    "keccak256": "0x0a58f9915f686950072a4786249d396ecbf2194a39ac835effe8ea1a7c76f324",
-    "sha256": "479f10a34d113a551312f3adf2e6952f3ab8bc7a4ff98c470e13f9543a44131f"
+    "bytes": 961799,
+    "keccak256": "0x24604525d220bcc7e39f2dbc22966a814600a63ada51baafad5dd0bcc1d28549",
+    "sha256": "0458b19258dffcfb9ce23d584096f3df06532080390d34ee71b201b6b78dbbac"
   },
   "package": "@hisoka-io/anon-rpc-worker",
   "toolchain": {
     "esbuild": "0.27.3",
-    "node": "v25.5.0",
+    "node": "v22.23.3",
     "pins": {
       "BINARYEN_SHA256_AARCH64": "ad560204426015a815faa45693c83bef7d58677d38a39422c272a30ba4b6da2a",
       "BINARYEN_SHA256_X86_64": "3dc677006555b355ea2da5e82602065a161d5e83eaefd3f759afa00b96e83212",
@@ -44,5 +44,5 @@
     "wasmPack": "0.13.1",
     "wasmPinsChecked": true
   },
-  "version": "0.2.0"
+  "version": "0.3.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hisoka-io/anon-rpc-worker",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Nox mixnet worker for the anon-rpc standard, built as one reproducible classic-script bundle with a pinned NoxRegistry snapshot",
   "license": "Apache-2.0",
   "repository": {
@@ -25,7 +25,7 @@
     "ethers": "6.16.0",
     "typescript": "5.9.3",
     "vitest": "1.6.1",
-    "@hisoka-io/nox-client": "0.6.0",
+    "@hisoka-io/nox-client": "0.7.0",
     "@hisoka-io/nox-wasm": "0.2.0"
   },
   "publishConfig": {

package/src/config.ts

@@ -31,6 +31,12 @@ export interface NoxWorkerConfig {
   readonly logLevel: LogLevel;
   /** Per attempt for small and medium reads. */
   readonly attemptTimeoutMs: number;
+  /**
+   * Resendable reads: a second copy goes out on another route when no reply
+   * arrived after this long (raised to the observed p95 reply time); the
+   * first reply wins. 0 turns hedging off.
+   */
+  readonly hedgeAfterMs: number;
   /** Whole call, from acceptance: waiting for ready, sending, attempts. */
   readonly callDeadlineMs: number;
   readonly maxConcurrentCalls: number;
@@ -55,6 +61,7 @@ export const CONFIG_DEFAULTS: NoxWorkerConfig = Object.freeze({
   trust: "auto",
   logLevel: "info",
   attemptTimeoutMs: 12_000,
+  hedgeAfterMs: 3_000,
   callDeadlineMs: 25_000,
   maxConcurrentCalls: 16,
   maxRequestBytes: 1_048_576,
@@ -69,6 +76,7 @@ export const CONFIG_DEFAULTS: NoxWorkerConfig = Object.freeze({
 /** Inclusive integer ranges of the numeric fields. */
 export const CONFIG_RANGES = Object.freeze({
   attemptTimeoutMs: [3_000, 60_000],
+  hedgeAfterMs: [0, 60_000],
   callDeadlineMs: [3_000, 120_000],
   maxConcurrentCalls: [1, 64],
   maxRequestBytes: [1_024, 4_194_304],

package/src/core.ts

@@ -15,6 +15,8 @@
  * learned-anchor cache.
  */
 import {
+  DISCOVERY_FIRST_CHECK_MAX_DEFER_MS,
+  RESEND_FAST,
   eligiblePinnedMembers,
   pinnedKpsAddresses,
   verifyBootstrap,
@@ -40,7 +42,15 @@ import {
   type BootRetryCode,
   type FailedCode,
 } from "./errors.js";
-import { mapClientError, prepareRequest, sendPrepared, type CallBudget, type NoxHttpPort } from "./fetch-map.js";
+import {
+  mapClientError,
+  prepareRequest,
+  sendPrepared,
+  type CallBudget,
+  type NoxHttpPort,
+  type PreparedRequest,
+} from "./fetch-map.js";
+import { LocalAnswers } from "./local-answers.js";
 import { createLogger, describeError, errorCode, type LogLevel, type WorkerLogger } from "./log.js";
 import {
   LearnedCacheWriter,
@@ -148,6 +158,7 @@ class NoxWorker {
   private cacheTimer: ReturnType<typeof setInterval> | undefined;
   private learnedWriter: LearnedCacheWriter | undefined;
   private callSeq = 0;
+  private readonly answers = new LocalAnswers();
   private readonly now: () => number;
   private readonly random: () => number;
   private readonly sleep: (ms: number) => Promise<void>;
@@ -291,11 +302,20 @@ class NoxWorker {
       log: this.sdkLogSink(),
       timeoutMs: cfg.attemptTimeoutMs,
       surbFormat: cfg.surbFormat,
+      // Interactive latency: hedge at about p95, resend at once on a lost
+      // reply, transport resends of their own, same-entry resends for a
+      // single bridge (ARCHITECTURE §4.7).
+      resend: { ...RESEND_FAST, hedgeAfterMs: cfg.hedgeAfterMs },
       kps: {
         dial: kpsDial,
         pinned,
         topologySources: cfg.topologySources,
         claimIntervalMs: cfg.claimIntervalMs,
+        // A warm standby entry. Claims share the primary connection: a second
+        // claim connection per entry measured mixed live and doubles per-IP
+        // connections at the relay.
+        claimLane: false,
+        standby: true,
         discovery: this.discoveryOptions(cfg, bootstrap, learned),
         ...(deprioritize.length === 0 ? {} : { deprioritize }),
       },
@@ -340,6 +360,8 @@ class NoxWorker {
     return {
       bootstrap,
       chain: cfg.discovery === "chain",
+      // Wallet calls first: the first registry check waits for the first call (bounded).
+      firstCheckDeferMs: DISCOVERY_FIRST_CHECK_MAX_DEFER_MS,
       onVerified: (state) => this.onVerified(state),
       ...(cfg.gateways === undefined ? {} : { gateways: cfg.gateways }),
       ...(cfg.bridges === undefined ? {} : { bridges: cfg.bridges }),
@@ -447,8 +469,20 @@ class NoxWorker {
     const budget = new CallControl(call.requestInit?.signal, cfg.callDeadlineMs, this.now);
     try {
       const prepared = await prepareRequest(call.url, call.requestInit, cfg, budget.signal);
+      const local = this.answers.lookup(prepared);
+      if (local !== undefined) {
+        this.log.debug("call.done", {
+          seq,
+          jsonrpcMethod: prepared.profile.method ?? null,
+          ms: this.now() - started,
+          outcome: "ok",
+          local: local.kind,
+        });
+        return local.response;
+      }
       const client = await this.waitReady(budget.signal);
       const response = await sendPrepared(prepared, client, cfg, budget);
+      if (this.answers.observe(prepared, response) === "verify") this.verifyAnswer(prepared, client, cfg);
       if (this.log.enabled("debug")) {
         this.log.debug("call.done", {
           seq,
@@ -470,6 +504,25 @@ class NoxWorker {
     }
   }
 
+  /**
+   * Send a memo call (`eth_chainId`, `net_version`) once more through the
+   * mixnet on a fresh route, in the background; the answer is kept only when
+   * both agree (see `LocalAnswers`).
+   */
+  private verifyAnswer(prepared: PreparedRequest, client: NoxClientPort, cfg: NoxWorkerConfig): void {
+    const budget = new CallControl(undefined, cfg.callDeadlineMs, this.now);
+    sendPrepared(prepared, client, cfg, budget)
+      .then(
+        (response) => {
+          this.answers.observe(prepared, response);
+        },
+        (error: unknown) => {
+          this.log.debug("local.verify.failed", { code: errorCode(mapClientError(error)) ?? "error" });
+        },
+      )
+      .finally(() => budget.dispose());
+  }
+
   private waitReady(signal: AbortSignal): Promise<NoxClientPort> {
     if (this.client !== undefined) return Promise.resolve(this.client);
     if (this.failed || this.stopped) {

package/src/fetch-map.ts

@@ -32,6 +32,24 @@ export interface FetchSettings {
   readonly attemptTimeoutMs: number;
   readonly maxRequestBytes: number;
   readonly maxResponseBytes: number;
+  /**
+   * `accept-encoding` sent upstream. Default: `gzip` where the runtime has
+   * `DecompressionStream`, else `identity`.
+   */
+  readonly acceptEncoding?: ReplyEncoding;
+}
+
+/** Reply encodings the worker can ask upstreams for. */
+export type ReplyEncoding = "gzip" | "identity";
+
+/**
+ * `gzip` when this runtime can inflate replies itself. Exits pass bodies
+ * through as the upstream sent them (their HTTP client has no decompression),
+ * so a gzip reply crosses the mixnet compressed: a 414 KB `eth_getLogs` reply
+ * takes about 2 reply packets instead of 14.
+ */
+export function defaultReplyEncoding(): ReplyEncoding {
+  return typeof DecompressionStream === "function" ? "gzip" : "identity";
 }
 
 /** A validated request, ready for the mixnet. */
@@ -74,7 +92,7 @@ const CROSS_ORIGIN_DROPPED_HEADERS = new Set(["authorization", "cookie"]);
  * Request headers never forwarded: the exit drops `host` and `user-agent`
  * itself, framing and hop-by-hop fields belong to the exit's own connection,
  * and cookies, origin and referer would tie calls together or to a page.
- * `accept-encoding` is replaced (see `FORCED_REQUEST_HEADERS`).
+ * `accept-encoding` is replaced (see `defaultReplyEncoding`).
  */
 const DROPPED_REQUEST_HEADERS = new Set([
   "host",
@@ -93,8 +111,8 @@ const DROPPED_REQUEST_HEADERS = new Set([
   "accept-encoding",
 ]);
 
-/** The exit's HTTP client has no decompression, so bodies must come back as sent. */
-const FORCED_REQUEST_HEADERS: readonly [string, string][] = [["accept-encoding", "identity"]];
+/** Content codings the worker inflates. */
+const GZIP_CODINGS: ReadonlySet<string> = new Set(["gzip", "x-gzip"]);
 
 /** Response fields that describe the exit's hop, or that a worker must not hand on. */
 const DROPPED_RESPONSE_HEADERS = new Set([
@@ -126,7 +144,7 @@ export async function prepareRequest(
   if (redirect !== "follow" && redirect !== "manual" && redirect !== "error") {
     throw callError(CALL_CODES.unsupported, 'redirect must be "follow", "manual" or "error"');
   }
-  const headers = prepareHeaders(init?.headers);
+  const headers = prepareHeaders(init?.headers, settings.acceptEncoding ?? defaultReplyEncoding());
   const body = await readBody(init?.body, settings.maxRequestBytes, signal);
   if ((method === "GET" || method === "HEAD") && body.length > 0) {
     throw callError(CALL_CODES.unsupported, `A ${method} request cannot carry a body`);
@@ -180,7 +198,7 @@ export async function sendPrepared(
     const reply = await exchange(current, port, settings, budget);
     checkStatus(reply);
     if (!REDIRECT_STATUSES.has(reply.status) || current.redirect === "manual") {
-      return toAnonResponse(reply, current, settings);
+      return finishResponse(reply, current, settings);
     }
     if (current.redirect === "error") {
       throw callError(
@@ -190,9 +208,9 @@ export async function sendPrepared(
     }
     const location = reply.headers.find(([name]) => name.toLowerCase() === "location")?.[1];
     // fetch returns a redirect status without a Location as an ordinary response.
-    if (location === undefined) return toAnonResponse(reply, current, settings);
+    if (location === undefined) return finishResponse(reply, current, settings);
     const next = redirectedRequest(current, reply.status, location);
-    if (next === null) return toAnonResponse(reply, current, settings);
+    if (next === null) return finishResponse(reply, current, settings);
     if (hop + 1 > MAX_REDIRECT_HOPS) {
       throw callError(CALL_CODES.networkError, `Too many redirects: more than ${MAX_REDIRECT_HOPS} hops`);
     }
@@ -290,6 +308,67 @@ function checkStatus(reply: DecodedHttpResponse): void {
   }
 }
 
+/** Inflate a gzip reply (see `inflateReply`), then map it with `toAnonResponse`. */
+export async function finishResponse(
+  reply: DecodedHttpResponse,
+  request: Pick<PreparedRequest, "url">,
+  settings: Pick<FetchSettings, "maxResponseBytes">,
+): Promise<AnonFetchResponse> {
+  checkStatus(reply);
+  if (reply.truncated) {
+    throw callError(CALL_CODES.tooLarge, "The exit cut the response body at its response size limit");
+  }
+  return toAnonResponse(await inflateReply(reply, settings.maxResponseBytes), request, settings);
+}
+
+/**
+ * The reply with a `gzip` body inflated and its `content-encoding` removed;
+ * any other reply unchanged. Inflation stops past `maxBytes` (`too-large`),
+ * so a small compressed reply cannot expand without bound; a corrupt body is
+ * a `protocol-error`.
+ */
+export async function inflateReply(reply: DecodedHttpResponse, maxBytes: number): Promise<DecodedHttpResponse> {
+  const coding = reply.headers.find(([name]) => name.toLowerCase() === "content-encoding")?.[1]?.trim().toLowerCase();
+  if (coding === undefined || !GZIP_CODINGS.has(coding)) return reply;
+  const headers = reply.headers.filter(([name]) => name.toLowerCase() !== "content-encoding");
+  if (reply.body.length === 0) return { ...reply, headers };
+  if (typeof DecompressionStream !== "function") {
+    throw callError(CALL_CODES.protocolError, "The upstream sent a gzip body and this runtime cannot inflate it");
+  }
+  const source = reply.body;
+  const inflated = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(source);
+      controller.close();
+    },
+  }).pipeThrough(new DecompressionStream("gzip") as unknown as TransformStream<Uint8Array, Uint8Array>);
+  const reader = inflated.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    let result: Awaited<ReturnType<typeof reader.read>>;
+    try {
+      result = await reader.read();
+    } catch (error) {
+      throw callError(CALL_CODES.protocolError, "The upstream's gzip body is corrupt", error);
+    }
+    if (result.done) break;
+    total += result.value.length;
+    if (total > maxBytes) {
+      void reader.cancel().catch(() => undefined);
+      throw callError(CALL_CODES.tooLarge, `The response body inflates past ${maxBytes} bytes`);
+    }
+    chunks.push(result.value);
+  }
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return { ...reply, headers, body };
+}
+
 /** Map the exit's decoded reply to an `AnonFetchResponse`; `request.url` becomes `url`. */
 export function toAnonResponse(
   reply: DecodedHttpResponse,
@@ -312,7 +391,7 @@ export function toAnonResponse(
     if (lower === "content-encoding" && value.trim().toLowerCase() !== "identity") {
       throw callError(
         CALL_CODES.protocolError,
-        "The upstream sent an encoded body although the request asked for identity; exits cannot decode it",
+        `The upstream sent a ${value.trim()} body; this worker accepts identity and gzip`,
       );
     }
     if (DROPPED_RESPONSE_HEADERS.has(lower) || !TOKEN_RE.test(name) || !FIELD_VALUE_RE.test(value)) continue;
@@ -403,9 +482,9 @@ function normalizeMethod(method: unknown): string {
   return NORMALIZED_METHODS.has(upper) ? upper : method;
 }
 
-/** Keep order and duplicates (the wire type is a list), drop and force per policy. */
-function prepareHeaders(list: HeaderList | undefined): [string, string][] {
-  if (list === undefined) return FORCED_REQUEST_HEADERS.map(([name, value]): [string, string] => [name, value]);
+/** Keep order and duplicates (the wire type is a list), drop per policy, then set `accept-encoding`. */
+function prepareHeaders(list: HeaderList | undefined, encoding: ReplyEncoding): [string, string][] {
+  if (list === undefined) return [["accept-encoding", encoding]];
   if (!Array.isArray(list)) throw callError(CALL_CODES.unsupported, "headers must be a list of [name, value] pairs");
   const out: [string, string][] = [];
   let bytes = 0;
@@ -427,7 +506,7 @@ function prepareHeaders(list: HeaderList | undefined): [string, string][] {
     }
     out.push([name, value]);
   }
-  for (const [name, value] of FORCED_REQUEST_HEADERS) out.push([name, value]);
+  out.push(["accept-encoding", encoding]);
   return out;
 }
 

package/src/local-answers.ts

@@ -0,0 +1,238 @@
+/**
+ * Worker-local answers: JSON-RPC calls whose answer
+ * cannot change are answered from memory instead of crossing the mixnet
+ * again. Fewer queries leave the device, and a hit costs no round trip.
+ *
+ * What is answered locally, per upstream URL and exact params:
+ *
+ * - `eth_chainId` and `net_version`: memoised once a second, independently
+ *   routed request through the mixnet returned the same result (the worker
+ *   sends that check in the background after the first answer).
+ * - Only with `blockHashReads` (off by default, because an answer is not yet
+ *   checked against the block hash): reads addressed by block hash, whose
+ *   result is fixed by the hash:
+ *   `eth_getBlockByHash`, `eth_getBlockReceipts`, `eth_getLogs` with a
+ *   `blockHash` filter, the `…ByBlockHash…` lookups, and EIP-1898 state reads
+ *   (`eth_call`, `eth_getBalance`, `eth_getCode`, `eth_getStorageAt`,
+ *   `eth_getTransactionCount`, `eth_getProof`) whose block is
+ *   `{"blockHash": …}` without `requireCanonical`. They are kept once two
+ *   separate calls returned the same result. Each call takes its own route,
+ *   so a wrong answer is kept only when both calls went through exits that
+ *   returned the same wrong result.
+ *
+ * Only single calls (not batches) with a `result` that is not null are kept;
+ * errors never are, and neither is an empty list for a block-hash read: an
+ * upstream that has not seen the block yet may answer `[]` for its logs or
+ * receipts, and a later call returns the full list. A request with `Cache-Control: no-cache` or `no-store`
+ * always goes through the mixnet. The reply carries the caller's own
+ * JSON-RPC `id`. Memory is bounded by entry count and bytes (oldest out).
+ */
+import type { AnonFetchResponse, HeaderList } from "./spec-types.js";
+import type { PreparedRequest } from "./fetch-map.js";
+
+/** Most answers kept. */
+export const LOCAL_ANSWER_MAX_ENTRIES = 512;
+/** Most result bytes kept in total. */
+export const LOCAL_ANSWER_MAX_BYTES = 4 * 1024 * 1024;
+/** Largest single result kept. */
+export const LOCAL_ANSWER_MAX_ENTRY_BYTES = 512 * 1024;
+/** Matching answers needed before a content-addressed result is served locally. */
+export const LOCAL_ANSWER_CONFIRMATIONS = 2;
+
+const MEMO_METHODS: ReadonlySet<string> = new Set(["eth_chainId", "net_version"]);
+
+/** Methods whose first param is a block hash. */
+const BY_BLOCK_HASH: ReadonlySet<string> = new Set([
+  "eth_getBlockByHash",
+  "eth_getBlockTransactionCountByHash",
+  "eth_getTransactionByBlockHashAndIndex",
+  "eth_getUncleByBlockHashAndIndex",
+  "eth_getUncleCountByBlockHash",
+]);
+
+/** EIP-1898 state reads: the block selector is the last param. */
+const STATE_READS: ReadonlySet<string> = new Set([
+  "eth_call",
+  "eth_getBalance",
+  "eth_getCode",
+  "eth_getStorageAt",
+  "eth_getTransactionCount",
+  "eth_getProof",
+]);
+
+const HASH_RE = /^0x[0-9a-fA-F]{64}$/u;
+
+/** Why a call was or was not answered locally (for debug logs). */
+export type LocalKind = "memo" | "block-hash";
+
+interface Entry {
+  readonly kind: LocalKind;
+  /** The JSON text of `result`. */
+  readonly result: string;
+  readonly headers: HeaderList;
+  confirmations: number;
+}
+
+/** A single JSON-RPC call read from a prepared request. */
+interface Call {
+  readonly key: string;
+  readonly kind: LocalKind;
+  readonly id: unknown;
+}
+
+const decoder = new TextDecoder("utf-8", { fatal: true });
+const encoder = new TextEncoder();
+
+/** Options for {@link LocalAnswers}. */
+export interface LocalAnswersOptions {
+  /** Also keep reads addressed by block hash (see above). Default false. */
+  readonly blockHashReads?: boolean;
+}
+
+export class LocalAnswers {
+  private readonly entries = new Map<string, Entry>();
+  private bytes = 0;
+  private readonly blockHashReads: boolean;
+
+  constructor(options: LocalAnswersOptions = {}) {
+    this.blockHashReads = options.blockHashReads ?? false;
+  }
+
+  /** The cacheable call in `request`, honouring the enabled kinds. */
+  private call(request: PreparedRequest): Call | undefined {
+    const call = cacheableCall(request);
+    if (call === undefined) return undefined;
+    return call.kind === "block-hash" && !this.blockHashReads ? undefined : call;
+  }
+
+  /** The local answer for `request`, if one is confirmed. */
+  lookup(request: PreparedRequest): { response: AnonFetchResponse; kind: LocalKind } | undefined {
+    const call = this.call(request);
+    if (call === undefined) return undefined;
+    const entry = this.entries.get(call.key);
+    if (entry === undefined || !this.served(entry)) return undefined;
+    this.entries.delete(call.key);
+    this.entries.set(call.key, entry);
+    const body = `{"jsonrpc":"2.0","id":${JSON.stringify(call.id ?? null)},"result":${entry.result}}`;
+    return {
+      kind: call.kind,
+      response: { status: 200, headers: entry.headers.map(([name, value]) => [name, value]), body: encoder.encode(body), url: request.url },
+    };
+  }
+
+  /**
+   * Record a mixnet answer. Returns `verify` when the call is a memo method
+   * seen for the first time: the caller sends it once more through the
+   * mixnet and passes that answer here too.
+   */
+  observe(request: PreparedRequest, response: AnonFetchResponse): "verify" | undefined {
+    const call = this.call(request);
+    if (call === undefined || response.status !== 200 || !(response.body instanceof Uint8Array)) return undefined;
+    const result = resultOf(response.body);
+    if (result === undefined || result.length > LOCAL_ANSWER_MAX_ENTRY_BYTES) return undefined;
+    if (call.kind === "block-hash" && result === "[]") return undefined;
+    const existing = this.entries.get(call.key);
+    if (existing !== undefined) {
+      if (existing.result === result) {
+        existing.confirmations += 1;
+      } else {
+        // Two answers disagree: keep neither.
+        this.remove(call.key, existing);
+      }
+      return undefined;
+    }
+    const headers = response.headers.filter(([name]) => name.toLowerCase() === "content-type");
+    this.entries.set(call.key, { kind: call.kind, result, headers, confirmations: 1 });
+    this.bytes += result.length;
+    this.evict();
+    return call.kind === "memo" ? "verify" : undefined;
+  }
+
+  /** Number of answers held (served or awaiting confirmation). */
+  get size(): number {
+    return this.entries.size;
+  }
+
+  private served(entry: Entry): boolean {
+    return entry.confirmations >= LOCAL_ANSWER_CONFIRMATIONS;
+  }
+
+  private remove(key: string, entry: Entry): void {
+    this.entries.delete(key);
+    this.bytes -= entry.result.length;
+  }
+
+  private evict(): void {
+    for (const [key, entry] of this.entries) {
+      if (this.entries.size <= LOCAL_ANSWER_MAX_ENTRIES && this.bytes <= LOCAL_ANSWER_MAX_BYTES) return;
+      this.remove(key, entry);
+    }
+  }
+}
+
+/** The call's cache key and kind, when `request` is one call whose answer is fixed. */
+function cacheableCall(request: PreparedRequest): Call | undefined {
+  if (request.method !== "POST" || request.profile.method === undefined || request.profile.method === "batch") {
+    return undefined;
+  }
+  for (const [name, value] of request.headers) {
+    if (name.toLowerCase() === "cache-control" && /no-cache|no-store/iu.test(value)) return undefined;
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(decoder.decode(request.body));
+  } catch {
+    return undefined;
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  const call = value as { jsonrpc?: unknown; method?: unknown; params?: unknown; id?: unknown };
+  if (call.jsonrpc !== "2.0" || typeof call.method !== "string" || !("id" in call)) return undefined;
+  const id = call.id;
+  if (id !== null && typeof id !== "string" && typeof id !== "number") return undefined;
+  const params = call.params ?? [];
+  const kind = classify(call.method, params);
+  if (kind === undefined) return undefined;
+  return { key: `${request.url}\n${call.method}\n${JSON.stringify(params)}`, kind, id };
+}
+
+function classify(method: string, params: unknown): LocalKind | undefined {
+  if (MEMO_METHODS.has(method)) return Array.isArray(params) && params.length === 0 ? "memo" : undefined;
+  if (!Array.isArray(params) || params.length === 0) return undefined;
+  const first: unknown = params[0];
+  if (BY_BLOCK_HASH.has(method)) return isHash(first) ? "block-hash" : undefined;
+  if (method === "eth_getBlockReceipts") return isHash(first) || isBlockHashSelector(first) ? "block-hash" : undefined;
+  if (method === "eth_getLogs") {
+    if (typeof first !== "object" || first === null) return undefined;
+    const filter = first as Record<string, unknown>;
+    return isHash(filter["blockHash"]) && filter["fromBlock"] === undefined && filter["toBlock"] === undefined
+      ? "block-hash"
+      : undefined;
+  }
+  if (STATE_READS.has(method)) return isBlockHashSelector(params[params.length - 1]) ? "block-hash" : undefined;
+  return undefined;
+}
+
+function isHash(value: unknown): boolean {
+  return typeof value === "string" && HASH_RE.test(value);
+}
+
+/** EIP-1898 `{"blockHash": …}` without `requireCanonical: true` (whose answer can turn into an error after a reorg). */
+function isBlockHashSelector(value: unknown): boolean {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const selector = value as Record<string, unknown>;
+  return isHash(selector["blockHash"]) && selector["requireCanonical"] !== true && selector["blockNumber"] === undefined;
+}
+
+/** The JSON text of a successful reply's `result` (not null), else undefined. */
+function resultOf(body: Uint8Array): string | undefined {
+  let value: unknown;
+  try {
+    value = JSON.parse(decoder.decode(body));
+  } catch {
+    return undefined;
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  const reply = value as { result?: unknown; error?: unknown };
+  if (reply.error !== undefined || reply.result === undefined || reply.result === null) return undefined;
+  return JSON.stringify(reply.result);
+}