add root to slot caching (#540)

* feat: add global root-to-slot cache

* feat: optimize root to slot caching and add pruning

* ttest: add integration test for root-to-slot cache lifecycle

* fix: address comment

* fix: move pruning to processFinaslizationAdvancement

* fix: address comment

* fix: initialize root-to-slot cache at chain startup

* fix: address PR review comments for root-to-slot cache

- Remove cache filling from process_block_header (done externally)
- Use orelse semantics for cache allocation in process_attestations
- Use block_cache directly without if check
- Add cache update in chain.zig onBlock before STF
- Update ArrayList API for Zig 0.15.2
- Strip debug info for zkvm targets to fix RISC-V linker overflow
- Update test to match new cache lifecycle design

* fix: resolve double-deinit panic in attestation processing

* fix: post merge changes and comment addressal

---------

Co-authored-by: g11tech <gajinder@zeam.in>

Author: chetanyb

build.zig

@@ -810,6 +810,7 @@ fn build_zkvm_targets(
                 .root_source_file = b.path("pkgs/state-transition-runtime/src/main.zig"),
                 .target = target,
                 .optimize = optimize,
+                .strip = true, // Strip debug info to avoid RISC-V relocation overflow
             }),
         });
         // addimport to root module is even required afer declaring it in mod

forkchoice_concurrency_analysis.md

@@ -0,0 +1,87 @@
+# Forkchoice Concurrency + Stale Snapshot Analysis
+
+Date: 2026-01-22
+Branch: forkchoice-graph (local)
+
+## Executive summary
+- Forkchoice can be mutated concurrently with chain processing in the current production path because gossip callbacks may run on the Rust bridge thread while `onInterval` runs on the xev loop thread.
+- The specific “canonical view + analysis mismatch” issue existed on `main` and has now been fixed locally by combining view + analysis under a single shared lock.
+- A broader “analysis result can become stale before it is used” risk remains anywhere analysis results are computed and then used later while forkchoice can still mutate concurrently.
+- These concurrency/staleness risks were **not introduced** by the forkchoice visualization PR; they already exist on `main`.
+
+## Evidence of concurrent mutation
+### Rust bridge thread calls gossip handlers directly
+- `pkgs/network/src/ethlibp2p.zig` spawns a Rust bridge thread (`Thread.spawn`) and uses it to deliver gossip.
+- In `handleGossipFromRustBridge`, gossip is dispatched via `gossipHandler.onGossip(..., scheduleOnLoop=false)`. That path invokes handlers immediately on the Rust thread.
+
+### gossip handler does not schedule on xev loop
+- `pkgs/network/src/interface.zig:GenericGossipHandler.onGossip` only schedules via xev when `scheduleOnLoop=true`. The ethlibp2p path passes `false`, so handlers run synchronously on the Rust thread.
+
+### chain mutation from gossip vs onInterval
+- `pkgs/node/src/node.zig:onGossip` -> `pkgs/node/src/chain.zig:onGossip` -> `forkChoice.onBlock/onAttestation` can run on the Rust bridge thread.
+- `pkgs/node/src/node.zig:onInterval` -> `pkgs/node/src/chain.zig:onInterval` -> `forkChoice.onInterval` runs on the xev loop.
+
+Net: forkchoice (and chain state) can be mutated concurrently.
+
+## Stale analysis: what it is
+A “stale analysis” happens when:
+1) canonical analysis is computed from snapshot S
+2) forkchoice mutates to snapshot S'
+3) the results from S are used later (pruning, DB updates, rebase)
+
+This can lead to misclassification or pruning of blocks that are now canonical.
+
+## Where stale analysis can occur
+### 1) Finalization processing
+File: `pkgs/node/src/chain.zig` in `processFinalizationAdvancement`
+- Local change (this branch) now uses `getCanonicalViewAndAnalysis(...)` to build view + analysis under one shared lock (fixing the *view/analysis mismatch*).
+- **Remaining risk:** analysis results can still be stale before DB updates/pruning if forkchoice mutates concurrently after analysis.
+
+### 2) Periodic pruning
+File: `pkgs/node/src/chain.zig` near line ~210
+- Uses `getCanonicalityAnalysis(..., null)`, which is internally consistent (view built inside analysis call).
+- **Remaining risk:** analysis results can become stale before pruning if forkchoice mutates concurrently.
+
+### 3) Observability (lower severity)
+- `pkgs/node/src/chain.zig:printSlot` reads multiple forkchoice values in separate calls. These can be inconsistent under concurrency, but this is observability only.
+
+## Specific bug fixed in this branch
+### View + analysis mismatch in finalization
+On `main`, `processFinalizationAdvancement` did:
+1) `getCanonicalView` (shared lock)
+2) `getCanonicalityAnalysis` (shared lock)
+
+If forkchoice mutated in between, analysis could be computed against a stale view. This was present on `main` before the PR.
+
+Local fix:
+- Added `getCanonicalViewAndAnalysis(...)` in `forkchoice.zig` to compute both under one shared lock.
+- Updated `processFinalizationAdvancement` to call the combined API.
+
+## Other forkchoice lock issue fixed
+- `computeDeltas(...)` previously used a shared lock while mutating `self.deltas` and `self.attestations`.
+- Updated to use exclusive lock in this branch.
+
+## Were these issues introduced by the forkchoice visualization PR?
+No.
+- The Rust bridge concurrency path exists on `main`.
+- The view/analysis split in finalization existed on `main`.
+- These are pre-existing issues; current branch fixes a subset of them.
+
+## Options to fully address concurrency/staleness
+### Option A — Single-threaded chain (recommended)
+- Route all gossip callbacks onto the xev loop thread (set `scheduleOnLoop=true` and fix the scheduling bug).
+- This makes chain + forkchoice effectively single-threaded and removes the stale-analysis hazard.
+
+### Option B — Chain-level mutex
+- Add a `Chain` mutex and lock at entry of `onGossip`, `onInterval`, `onBlock`, finalization pruning, etc.
+- Ensures serialized access without reworking network callbacks.
+
+### Option C — Full concurrent correctness
+- Introduce explicit locking around all shared chain state and make all analysis/pruning operate on snapshots.
+- Higher effort, higher complexity.
+
+## Recommendation
+Keep the forkchoice visualization PR scoped:
+- Accept the local fixes (combined view+analysis, computeDeltas lock).
+- Track the broader concurrency model decision separately (Option A or B).
+

pkgs/node/src/chain.zig

@@ -107,6 +107,8 @@ pub const BeamChain = struct {
     // Cache for validator public keys to avoid repeated SSZ deserialization during signature verification.
     // Significantly reduces CPU overhead when processing blocks with many attestations.
     public_key_cache: xmss.PublicKeyCache,
+    // Cache for root to slot mapping to optimize block processing performance.
+    root_to_slot_cache: types.RootToSlotCache,
 
     // Callback for pruning cached blocks after finalization advances
     prune_cached_blocks_ctx: ?*anyopaque = null,
@@ -139,7 +141,7 @@ pub const BeamChain = struct {
         try types.sszClone(allocator, types.BeamState, opts.anchorState.*, cloned_anchor_state);
         try states.put(fork_choice.head.blockRoot, cloned_anchor_state);
 
-        return Self{
+        var chain = Self{
             .nodeId = opts.nodeId,
             .config = opts.config,
             .forkChoice = fork_choice,
@@ -157,8 +159,13 @@ pub const BeamChain = struct {
             .node_registry = opts.node_registry,
             .force_block_production = opts.force_block_production,
             .public_key_cache = xmss.PublicKeyCache.init(allocator),
+            .root_to_slot_cache = types.RootToSlotCache.init(allocator),
             .pending_blocks = .empty,
         };
+        // Initialize cache with anchor block root and any post-finalized entries from state
+        try chain.root_to_slot_cache.put(fork_choice.head.blockRoot, opts.anchorState.slot);
+        try chain.anchor_state.initRootToSlotCache(&chain.root_to_slot_cache);
+        return chain;
     }
 
     pub fn setPruneCachedBlocksCallback(self: *Self, ctx: *anyopaque, func: PruneCachedBlocksFn) void {
@@ -186,6 +193,9 @@ pub const BeamChain = struct {
         // Clean up public key cache
         self.public_key_cache.deinit();
 
+        // Clean up root to slot cache
+        self.root_to_slot_cache.deinit();
+
         // Clean up any blocks that were queued waiting for the forkchoice clock
         for (self.pending_blocks.items) |*block| {
             block.deinit();
@@ -453,7 +463,7 @@ pub const BeamChain = struct {
         self.module_logger.debug("node-{d}::going for block production opts={any} raw block={s}", .{ self.nodeId, opts, block_str });
 
         // 2. apply STF to get post state & update post state root & cache it
-        try stf.apply_raw_block(self.allocator, post_state, &block, self.block_building_logger);
+        try stf.apply_raw_block(self.allocator, post_state, &block, self.block_building_logger, &self.root_to_slot_cache);
 
         const block_str_2 = try block.toJsonString(self.allocator);
         defer self.allocator.free(block_str_2);
@@ -774,13 +784,16 @@ pub const BeamChain = struct {
 
             // 3. apply state transition assuming signatures are valid (STF does not re-verify)
             try stf.apply_transition(self.allocator, cpost_state, block, .{
-                //
                 .logger = self.stf_logger,
                 .validSignatures = true,
+                .rootToSlotCache = &self.root_to_slot_cache,
             });
             break :computedstate cpost_state;
         };
 
+        // Add current block's root to cache AFTER STF (ensures cache stays in sync with historical_block_hashes)
+        try self.root_to_slot_cache.put(block_root, block.slot);
+
         var missing_roots: std.ArrayList(types.Root) = .empty;
         errdefer missing_roots.deinit(self.allocator);
 
@@ -1187,6 +1200,9 @@ pub const BeamChain = struct {
         //     }
         // }
 
+        // Prune root-to-slot cache up to finalized slot
+        try self.root_to_slot_cache.prune(latestFinalized.slot);
+
         // Record successful finalization
         zeam_metrics.metrics.lean_finalizations_total.incr(.{ .result = "success" }) catch {};
 

pkgs/state-transition/src/mock.zig

@@ -330,7 +330,7 @@ pub fn genMockChain(allocator: Allocator, numBlocks: usize, from_genesis: ?types
         agg_att_cleanup = false;
 
         // prepare pre state to process block for that slot, may be rename prepare_pre_state
-        try transition.apply_raw_block(allocator, &beam_state, &block, block_building_logger);
+        try transition.apply_raw_block(allocator, &beam_state, &block, block_building_logger, null);
         try zeam_utils.hashTreeRoot(types.BeamBlock, block, &block_root, allocator);
 
         // generate the signed beam block and add to block list

pkgs/state-transition/src/transition.zig

@@ -1,7 +1,6 @@
 const std = @import("std");
 const json = std.json;
 const types = @import("@zeam/types");
-const utils = types.utils;
 
 const params = @import("@zeam/params");
 const zeam_utils = @import("@zeam/utils");
@@ -20,6 +19,7 @@ pub const StateTransitionOpts = struct {
     validSignatures: bool = true,
     validateResult: bool = true,
     logger: zeam_utils.ModuleLogger,
+    rootToSlotCache: ?*types.RootToSlotCache = null,
 };
 
 // pub fn process_epoch(state: types.BeamState) void {
@@ -36,7 +36,7 @@ fn process_execution_payload_header(state: *types.BeamState, block: types.BeamBl
     }
 }
 
-pub fn apply_raw_block(allocator: Allocator, state: *types.BeamState, block: *types.BeamBlock, logger: zeam_utils.ModuleLogger) !void {
+pub fn apply_raw_block(allocator: Allocator, state: *types.BeamState, block: *types.BeamBlock, logger: zeam_utils.ModuleLogger, cache: ?*types.RootToSlotCache) !void {
     // prepare pre state to process block for that slot, may be rename prepare_pre_stateCollapse comment
     const transition_timer = zeam_metrics.lean_state_transition_time_seconds.start();
     defer _ = transition_timer.observe();
@@ -45,7 +45,7 @@ pub fn apply_raw_block(allocator: Allocator, state: *types.BeamState, block: *ty
     try state.process_slots(allocator, block.slot, logger);
 
     // process block and modify the pre state to post state
-    try state.process_block(allocator, block.*, logger);
+    try state.process_block(allocator, block.*, logger, cache);
 
     logger.debug("extracting state root\n", .{});
     // extract the post state root
@@ -205,7 +205,7 @@ pub fn apply_transition(allocator: Allocator, state: *types.BeamState, block: ty
     try state.process_slots(allocator, block.slot, opts.logger);
 
     // process the block
-    try state.process_block(allocator, block, opts.logger);
+    try state.process_block(allocator, block, opts.logger, opts.rootToSlotCache);
 
     const validateResult = opts.validateResult;
     if (validateResult) {

pkgs/types/src/lib.zig

@@ -68,6 +68,7 @@ pub const GenesisSpec = utils.GenesisSpec;
 pub const ChainSpec = utils.ChainSpec;
 pub const sszClone = utils.sszClone;
 pub const IsJustifiableSlot = utils.IsJustifiableSlot;
+pub const RootToSlotCache = utils.RootToSlotCache;
 
 const zk = @import("./zk.zig");
 pub const ZkVm = zk.ZkVm;