diff --git a/crates/storage/src/api/mod.rs b/crates/storage/src/api/mod.rs index f93e9d10..00755269 100644 --- a/crates/storage/src/api/mod.rs +++ b/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`). + mod tables; mod traits; diff --git a/crates/storage/src/api/traits.rs b/crates/storage/src/api/traits.rs index 6014ddab..5ab82601 100644 --- a/crates/storage/src/api/traits.rs +++ b/crates/storage/src/api/traits.rs @@ -6,9 +6,9 @@ pub type Error = Box; /// 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, Error>; /// Begin a write batch. diff --git a/crates/storage/src/backend/mod.rs b/crates/storage/src/backend/mod.rs index f1464461..d53103fa 100644 --- a/crates/storage/src/backend/mod.rs +++ b/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`. +//! Suitable for testing and ephemeral nodes. Data is lost on restart. + mod in_memory; pub use in_memory::InMemoryBackend; diff --git a/crates/storage/src/store.rs b/crates/storage/src/store.rs index 4ed2af43..7830924c 100644 --- a/crates/storage/src/store.rs +++ b/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.