feat(storage): diff beacon states against their snapshot, not their parent

crates/common/types/src/beacon/fork.rs

@@ -22,9 +22,10 @@ use crate::beacon::preset;
 const LEAN_SNAPSHOT_INTERVAL: u64 = 1_024;
 
 /// How many slots apart full state snapshots are written for the Beacon
-/// Chain, in [`ForkName::snapshot_interval`]: one epoch, so a
-/// reconstruction fold is bounded at one epoch of blocks plus a single
-/// decode.
+/// Chain, in [`ForkName::snapshot_interval`]: one epoch. A beacon read applies
+/// one delta against its snapshot whatever the interval, so what this bounds
+/// is how large a delta grows (it carries every change since its snapshot) and
+/// how often a full snapshot is written.
 const BEACON_SNAPSHOT_INTERVAL: u64 = preset::SLOTS_PER_EPOCH;
 
 /// A named fork of the Beacon Chain, ordered oldest to newest, followed by
@@ -188,10 +189,11 @@ impl ForkName {
     /// here rather than on `Config`: putting it in a config a chain agrees on
     /// would imply the two had to agree on it.
     ///
-    /// Lean's interval does not survive contact with a ~350 MB beacon state,
-    /// since the reconstruction fold would apply that many deltas; beacon
-    /// takes an epoch, so the fold is bounded at one epoch of blocks plus a
-    /// single decode.
+    /// Lean's interval does not survive contact with a ~350 MB beacon state:
+    /// a beacon diff carries every change since its snapshot, so a long
+    /// interval lets deltas grow large, and a snapshot is a full copy of the
+    /// state. Beacon takes an epoch, which bounds both; a read applies a single
+    /// delta whatever the interval, and decodes once.
     pub const fn snapshot_interval(self) -> u64 {
         match self {
             ForkName::Lean => LEAN_SNAPSHOT_INTERVAL,

crates/storage/src/api/tables.rs

@@ -31,9 +31,11 @@ pub enum Table {
     States,
     /// State diffs: slot || root -> StateDiff
     ///
-    /// Parent-linked diff written for every non-anchor state, keyed like
-    /// `States`. Pruned below the finalized snapshot interval together with
-    /// `States`. See `get_state` for reconstruction.
+    /// Diff written for every non-anchor state, keyed like `States`. Lean's is
+    /// parent-linked; a beacon diff is taken against the nearest snapshot on
+    /// its branch, so a beacon state is one snapshot plus one delta. Pruned
+    /// below the finalized snapshot interval together with `States`. See
+    /// `get_state` for reconstruction.
     StateDiffs,
     /// Metadata: string keys -> various scalar values
     Metadata,

crates/storage/src/beacon_state_delta.rs

@@ -20,8 +20,14 @@
 //!
 //! `insert_state`/`get_state` (in `store.rs`) call into this module for the
 //! beacon arm: `insert_state` writes a snapshot at anchors and a
-//! [`frame`]d [`encode`] otherwise, and `get_state` walks the resulting
-//! chain and [`decode`]s it back, via [`unframe`].
+//! [`frame`]d [`encode`] otherwise, and `get_state` follows the frame's base
+//! and [`decode`]s it back, via [`unframe`].
+//!
+//! The base of a delta is the nearest snapshot on the state's branch, not its
+//! parent. A read is then one snapshot plus one delta, whatever the state's
+//! distance from the snapshot; the price is that a delta carries every change
+//! since the snapshot, so it grows across the interval. The frame names its
+//! own base, so the reader does not care which of the two a given frame uses.
 
 use ethlambda_types::primitives::H256;