docs: add more documentation for the Store API

crates/storage/src/api/mod.rs

@@ -1,3 +1,18 @@
+//! Storage backend API.
+//!
+//! This module defines the traits and types for pluggable storage backends.
+//!
+//! # Traits
+//!
+//! - [`StorageBackend`]: Main trait for storage implementations. Creates read views and write batches.
+//! - [`StorageReadView`]: Read-only access to storage via `get` and `prefix_iterator`.
+//! - [`StorageWriteBatch`]: Batched writes with atomic `commit`.
+//!
+//! # Tables
+//!
+//! Storage is organized into [`Table`]s, each storing a different type of data.
+//! All keys and values are byte slices (`&[u8]` / `Vec<u8>`).
+
 mod tables;
 mod traits;
 

crates/storage/src/api/traits.rs

@@ -6,9 +6,9 @@ pub type Error = Box<dyn std::error::Error + Send + Sync>;
 /// Result type for prefix iterator operations.
 pub type PrefixResult = Result<(Box<[u8]>, Box<[u8]>), Error>;
 
-/// A storage backend that can create read views and write batches.
+/// A storage backend that can read and write data through views and batches.
 pub trait StorageBackend: Send + Sync {
-    /// Begin a read-only transaction.
+    /// Begin a read-only view.
     fn begin_read(&self) -> Result<Box<dyn StorageReadView + '_>, Error>;
 
     /// Begin a write batch.

crates/storage/src/backend/mod.rs

@@ -1,3 +1,12 @@
+//! Storage backend implementations.
+//!
+//! This module provides concrete implementations of the [`crate::api::StorageBackend`] trait.
+//!
+//! # Backends
+//!
+//! - [`InMemoryBackend`]: Thread-safe in-memory storage using `RwLock<HashMap>`.
+//!   Suitable for testing and ephemeral nodes. Data is lost on restart.
+
 mod in_memory;
 
 pub use in_memory::InMemoryBackend;

crates/storage/src/store.rs

@@ -52,11 +52,17 @@ impl ForkCheckpoints {
 
 // ============ Metadata Keys ============
 
+/// Key for "time" field of the Store. Its value has type [`u64`] and it's SSZ-encoded.
 const KEY_TIME: &[u8] = b"time";
+/// Key for "config" field of the Store. Its value has type [`ChainConfig`] and it's SSZ-encoded.
 const KEY_CONFIG: &[u8] = b"config";
+/// Key for "head" field of the Store. Its value has type [`H256`] and it's SSZ-encoded.
 const KEY_HEAD: &[u8] = b"head";
+/// Key for "safe_target" field of the Store. Its value has type [`H256`] and it's SSZ-encoded.
 const KEY_SAFE_TARGET: &[u8] = b"safe_target";
+/// Key for "latest_justified" field of the Store. Its value has type [`Checkpoint`] and it's SSZ-encoded.
 const KEY_LATEST_JUSTIFIED: &[u8] = b"latest_justified";
+/// Key for "latest_finalized" field of the Store. Its value has type [`Checkpoint`] and it's SSZ-encoded.
 const KEY_LATEST_FINALIZED: &[u8] = b"latest_finalized";
 
 // ============ Key Encoding Helpers ============
@@ -76,20 +82,8 @@ fn decode_signature_key(bytes: &[u8]) -> SignatureKey {
     (validator_id, root)
 }
 
-/// Forkchoice store tracking chain state and validator attestations.
-///
-/// This is the "local view" that a node uses to run LMD GHOST. It contains:
-///
-/// - which blocks and states are known,
-/// - which checkpoints are justified and finalized,
-/// - which block is currently considered the head,
-/// - and, for each validator, their latest attestation that should influence fork choice.
-///
-/// The `Store` is updated whenever:
-/// - a new block is processed,
-/// - an attestation is received (via a block or gossip),
-/// - an interval tick occurs (activating new attestations),
-/// - or when the head is recomputed.
+/// Underlying storage of the node.
+/// Similar to the spec's `Store`, but backed by a pluggable storage backend.
 ///
 /// All data is stored in the backend. Metadata fields (time, config, head, etc.)
 /// are stored in the Metadata table with their field name as the key.