feat: support native loadState

- add native `loadState` that mirrors TS implementation
- add bindings
- add benchmarks to bench naive + loadState difference


part of #347

Author: spiral-ladder

bindings/napi/BeaconStateView.zig

@@ -937,6 +937,52 @@ pub fn processSlots(self: *const BeaconStateView, slot_arg: js.Number, options:
     return .{ .cached_state = post_state };
 }
 
+/// Load another state by reusing this state's validators / inactivity_scores subtrees
+/// where the byte ranges are unchanged. Mirrors TS `loadState` for ~500ms-per-reload speedup.
+pub fn loadOtherState(
+    self: *const BeaconStateView,
+    state_bytes: js.Uint8Array,
+    seed_validators_bytes: ?js.Uint8Array,
+    _: ?js.Value,
+) !BeaconStateView {
+    const cached_state = try self.requireState();
+    const state_bytes_slice = try state_bytes.toSlice();
+    const seed_validators_bytes_slice: ?[]const u8 =
+        if (seed_validators_bytes) |b| try b.toSlice() else null;
+
+    var result = try st.loadState(
+        allocator,
+        &pool.state.pool,
+        cached_state.config,
+        cached_state.state,
+        state_bytes_slice,
+        seed_validators_bytes_slice,
+    );
+
+    result.modified_validators.deinit(allocator);
+    errdefer {
+        result.state.deinit();
+        allocator.destroy(result.state);
+    }
+
+    const new_cached_state = try allocator.create(CachedBeaconState);
+    errdefer allocator.destroy(new_cached_state);
+
+    try new_cached_state.init(
+        allocator,
+        result.state,
+        .{
+            .config = cached_state.config,
+            .index_to_pubkey = cached_state.epoch_cache.index_to_pubkey,
+            .pubkey_to_index = cached_state.epoch_cache.pubkey_to_index,
+        },
+        // as of Feb 2026, it's not necessary to sync pubkey cache as it's shared across states in Lodestar
+        .{ .skip_sync_pubkeys = true },
+    );
+
+    return .{ .cached_state = new_cached_state };
+}
+
 fn requireState(self: *const BeaconStateView) !*CachedBeaconState {
     return self.cached_state orelse error.InvalidState;
 }

bindings/perf/loadState.test.ts

@@ -0,0 +1,54 @@
+import {config} from "@lodestar/config/default";
+import * as era from "@lodestar/era";
+import {loadState as loadStateTS} from "@lodestar/state-transition";
+import {ssz} from "@lodestar/types";
+import {bench, describe} from "@chainsafe/benchmark";
+import bindings from "../src/index.js";
+import {getFirstEraFilePath} from "../test/eraFiles.ts";
+
+const reader = await era.era.EraReader.open(config, getFirstEraFilePath());
+const stateBytes = await reader.readSerializedState();
+await reader.close();
+
+bindings.pool.ensureCapacity(10_000_000);
+bindings.pubkeys.ensureCapacity(2_000_000);
+try {
+  bindings.pubkeys.load("./mainnet.pkix");
+} catch (_e) {
+  // ignore
+}
+
+const seedState = bindings.BeaconStateView.createFromBytes(stateBytes);
+const seedValidatorsBytes = seedState.serializeValidators();
+
+const tsSeedState = ssz.fulu.BeaconState.deserializeToViewDU(stateBytes);
+
+describe("loadState: native vs TS (mainnet)", () => {
+  bench({
+    fn: () => {
+      seedState.loadOtherState(stateBytes);
+    },
+    id: "native (internal serialize seed)",
+  });
+
+  bench({
+    fn: () => {
+      loadStateTS(config, tsSeedState, stateBytes);
+    },
+    id: "TS (internal serialize seed)",
+  });
+
+  bench({
+    fn: () => {
+      seedState.loadOtherState(stateBytes, seedValidatorsBytes);
+    },
+    id: "native (prebuilt seedValidatorsBytes)",
+  });
+
+  bench({
+    fn: () => {
+      loadStateTS(config, tsSeedState, stateBytes, seedValidatorsBytes);
+    },
+    id: "TS (prebuilt seedValidatorsBytes)",
+  });
+});

bindings/src/index.d.ts

@@ -213,7 +213,18 @@ declare class BeaconStateView {
   createdWithTransferCache: boolean;
   // isStateValidatorsNodesPopulated(): boolean;
 
-  // loadOtherState(stateBytes: Uint8Array, seedValidatorsBytes?: Uint8Array): void;
+  /**
+   * Tree-reuse optimized: builds a new state from `stateBytes` while sharing this
+   * state's validators / inactivity_scores subtree nodes for unchanged entries.
+   * Pass `seedValidatorsBytes` to skip the internal serialization of seed validators.
+   * Note: `preloadValidatorsAndBalances` is currently a no-op (native state is
+   * always populated).
+   */
+  loadOtherState(
+    stateBytes: Uint8Array,
+    seedValidatorsBytes?: Uint8Array,
+    opts?: {preloadValidatorsAndBalances?: boolean}
+  ): BeaconStateView;
   serialize(): Uint8Array;
   serializedSize(): number;
   serializeToBytes(output: Uint8Array, offset: number): number;

bindings/test/beaconStateView.test.ts

@@ -623,4 +623,27 @@ describe("BeaconStateView", () => {
       expect(increments.length).toBe(state.validatorCount);
     });
   });
+
+  describe("loadOtherState", () => {
+    it("hashTreeRoot matches createFromBytes", () => {
+      const reloaded = state.loadOtherState(stateBytes);
+      expect(reloaded.hashTreeRoot()).toEqual(state.hashTreeRoot());
+    });
+
+    it("serialized output round-trips", () => {
+      const reloaded = state.loadOtherState(stateBytes);
+      const reloadedBytes = reloaded.serialize();
+      // Avoid vitest's expensive deep-comparison on ~300MB buffers.
+      expect(reloadedBytes.length).toBe(stateBytes.length);
+      // Compare bit-for-bit via Buffer.equals (fast native compare).
+      expect(Buffer.from(reloadedBytes).equals(Buffer.from(stateBytes))).toBe(true);
+    });
+
+    it("seedValidatorsBytes path matches no-seed path", () => {
+      const seedValidatorsBytes = state.serializeValidators();
+      const a = state.loadOtherState(stateBytes);
+      const b = state.loadOtherState(stateBytes, seedValidatorsBytes);
+      expect(b.hashTreeRoot()).toEqual(a.hashTreeRoot());
+    });
+  });
 });

src/state_transition/root.zig

@@ -92,6 +92,9 @@ pub const getEffectiveBalanceIncrementsZeroInactive = @import("./utils/balance.z
 
 pub const WithdrawalsResult = @import("./block/process_withdrawals.zig").WithdrawalsResult;
 
+pub const loadState = @import("./utils/load_state.zig").loadState;
+pub const LoadStateResult = @import("./utils/load_state.zig").LoadStateResult;
+
 pub const test_utils = @import("test_utils/root.zig");
 
 pub const bls = @import("utils/bls.zig");
@@ -109,5 +112,6 @@ test {
     testing.refAllDecls(@This());
     testing.refAllDecls(seed);
     testing.refAllDecls(state_transition);
+    testing.refAllDecls(@import("./utils/load_state.zig"));
     testing.refAllDecls(EpochShuffling);
 }