feat(pxe): hash-pinned node read cache

[nchamo]

Motivation

Client flows repeat identical node reads: simulation, witness generation and kernel proving fetch the same membership witnesses, leaf indexes and public storage over and over, and separate PXE services re-fetch what a simulator just read. Every duplicate is a serial RPC round trip on the critical path of proving.

Code today

PXE already deduplicates some of this, but through two caches with their own scope and rules:

• ContractClassService keeps a class-id cache keyed by (address, anchorHash).
• Each utility execution gets an AztecNodeReadCache that memoizes witnesses, storage, blocks and receipts for that one execution.

Nothing is shared across consumers: kernel proving re-reads what simulation just fetched, and every execution starts cold.

Our change

• withCache(node): an AztecNode wrapper every PXE consumer reads through, backed by one shared cache. Only reads pinned to a block hash are cached. Hash-named content is immutable, so a repeat can never change, which makes the cache safe to share across consumers on different anchors. Reads by block number or tag (like "latest") pass through, and concurrent identical reads share one request.
• Simulation, kernel proving, contract sync and utility execution now share each other's reads. The class-id cache is deleted, and the per-execution cache is reduced to receipts: the one thing it held that is not immutable (pending → mined → finalized), so it cannot join the shared cache.
• The BlockSynchronizer wipes the cache when the anchor block advances. Wiping only bounds memory; correctness never depends on it.

Important note: profiling stats are recorded differently now, and their absolute values will jump relative to dashboard history. See the discussion in the comments of this PR.

Metrics

Measured at the node: an identical counting wrapper between the benchmarking wallet and the in-process node, applied to both base and this branch, so the numbers are independent of either side's instrumentation. RPC calls count every request the node serves; round trips count how many times the client blocks waiting on the node (concurrent requests are many calls but one round trip), so client-perceived latency scales with round trips.

Change impact in benchmarks

Per RPC

RPC call	Node calls
findLeavesIndexes	52 → 35 (−32.7%)
getPublicStorageAt	11 → 7 (−36.4%)
getNoteHashMembershipWitness	26 → 22 (−15.4%)
getPublicDataWitness	44 → 39 (−11.4%)
getNullifierMembershipWitness	19 → 17 (−10.5%)
getPrivateLogsByTags	108 → 108
getContract	40 → 40
getTxReceipt	22 → 22
everything else	60 → 60
Total	382 → 350 (−8.4%)

The savings land on witnesses, leaf indexes and storage. getContract and getTxReceipt stay at their floor because the caches this PR replaces already deduplicated them. getPrivateLogsByTags is tag-addressed and uncacheable by hash today: extending the cache to reference-block-bounded log queries is the natural follow-up.

Per scenario

The bridging flow is omitted because it profiles through the cross-chain harness wallet, outside the counter.

Flow	RPC calls	Round trips
transfer_0_recursions+private_fpc	66 → 56 (−15.2%)	41 → 36 (−12.2%)
transfer_1_recursions+private_fpc	66 → 56 (−15.2%)	38 → 32 (−15.8%)
transfer_0_recursions+sponsored_fpc	36 → 35 (−2.8%)	27 → 26 (−3.7%)
transfer_1_recursions+sponsored_fpc	39 → 37 (−5.1%)	24 → 22 (−8.3%)
amm_add_liquidity_1_recursions	69 → 63 (−8.7%)	41 → 37 (−9.8%)
deploy_account_ecdsar1	21 → 21	18 → 18
deploy_account_schnorr	17 → 14 (−17.6%)	11 → 11
deploy_token_ecdsar1	21 → 21	18 → 18
deploy_token_schnorr	22 → 22	16 → 16
storage_proof_7_layers	25 → 25	19 → 19
Total	382 → 350 (−8.4%)	253 → 235 (−7.1%)

Entire benchmarks

Each suite runs its own wallet and PXE; within a suite, the cache lives across setup, sync and every tx. Counting each suite's whole run, the improvement is larger than per scenario, because later operations reuse reads earlier ones already paid for — the longest-lived suite (transfers, four profiled txs on one wallet) improves the most.

Suite	RPC calls	Round trips
transfers	267 → 220 (−17.6%)	181 → 152 (−16.0%)
amm	73 → 67 (−8.2%)	45 → 41 (−8.9%)
account_deployments	41 → 38 (−7.3%)	32 → 32
deployments	46 → 46	37 → 37
storage_proof	28 → 28	22 → 22
Total	458 → 402 (−12.2%)	320 → 287 (−10.3%)

The benchmarks advance the anchor between interactions, wiping the cache at the fastest possible cadence, so sessions doing repeated operations against one anchor reuse strictly more.

Cool finding

Running this branch with the cache disabled entirely measures the value of the caching layer as a whole — the unified cache plus the base caches it replaced — rather than this PR's delta:

Scope	RPC calls	Round trips
Whole package, cache off → on	777 → 356 (−54.2%)	622 → 222 (−64.3%)
amm_add_liquidity alone	131 → 62 (−52.7%)	103 → 36 (−65.0%)
of which getContract	70 → 7 (−90.0%)

[nchamo]

Like we say below, receipts are not associated to a specific block hash. They can change over time, even if the anchor block hasn't moved. So we don't cache them at the general PXE cache level. But we were caching them here before in the AztecNodeReadCache, so it makes sense to continue to do that

[nchamo]

I moved this away from the contract simulator, into the node itself. Felt cleaner

[nchamo]

We now have more control about what we record, so it's a great opportunity to discuss how we were calculating benchmarks before, and what we can do now.

What the stats measured before

nodeRPCCalls came from a wrapper owned by the contract-function simulator, so it covered only the reads the simulator itself issued: membership witnesses, leaf indexes, public storage, blocks fetched during execution, and note discovery (log and receipt queries run from execution oracles). Everything else in the same operation read the node directly and was invisible: block sync, ContractSyncService and ContractClassService (all the getContract and class-id traffic), kernel proving, public simulation and tx validation.

What they measure now

One recording on the shared node wrapper spans the whole operation, from before block sync until the operation returns. It covers every read the operation triggers, and only reads the node actually answered: a cache-served read appears nowhere, and a batch served entirely from cache is not a round trip. This is why absolute rpc and round_trips values will jump relative to dashboard history even though actual node traffic went down.

Alternatives, if we prefer a narrower window

• Start the recording after block sync. The metric becomes a function of the tx alone, since sync cost varies with how stale the PXE is. The downside is that timings.sync stays inside the same stats object while its RPC cost goes unreported, and the sync reads the cache saves disappear from the metric.
• Start it at simulation, reproducing the old window. Comparable with dashboard history, but it hides kernel proving, contract sync and validation, which is where much of the duplication lives.
• Keep two windows (sync and the rest) and report both. Full visibility with stable per-tx numbers, at the cost of a second window in the NodeStats schema.

[Thunkar]

Love it!

[AztecBot]

❌ Failed to cherry-pick to v5-next due to conflicts. (🤖) View backport run.