docs

Author: clabby

glue/src/stateful/db.rs

@@ -1,3 +1,19 @@
+//! Database batch lifecycle traits for stateful applications.
+//!
+//! This module defines the traits that bridge the [`Stateful`](super::wrapper::Stateful)
+//! wrapper with the underlying storage layer (QMDB). The batch lifecycle has
+//! three stages:
+//!
+//! 1. [`Unmerkleized`]: an in-progress batch of reads and writes.
+//! 2. [`Merkleized`]: a sealed batch whose state root has been computed.
+//! 3. Finalization: applying a merkleized batch's changeset to the
+//!    database via [`ManagedDb::finalize`].
+//!
+//! [`DatabaseSet`] composes one or more [`ManagedDb`] instances (each behind
+//! its own `Arc<AsyncRwLock<...>>`) into a single unit that the wrapper
+//! manages as a group. It is implemented for `Arc<AsyncRwLock<T>>` (singleton)
+//! and for tuples of up to 8 such values.
+
 use commonware_cryptography::Digest;
 use commonware_utils::sync::AsyncRwLock;
 use std::{fmt::Debug, future::Future, sync::Arc};

glue/src/stateful/wrapper.rs

@@ -1,3 +1,28 @@
+//! Consensus-facing wrapper that manages pending state on behalf of a
+//! stateful application.
+//!
+//! [`Stateful`] implements the consensus [`Application`](ConsensusApplication)
+//! and [`VerifyingApplication`](ConsensusVerifyingApplication) traits by
+//! delegating execution to the inner [`Application`] while managing the
+//! pending-tip DAG of merkleized batches:
+//!
+//! - Before each `propose` or `verify`, the wrapper forks unmerkleized
+//!   batches from the parent block's pending state (or from the committed
+//!   database state if the parent has been finalized).
+//! - After execution, the wrapper stores the resulting merkleized batches
+//!   as a new pending tip keyed by the block's payload.
+//! - On finalization, the wrapper applies the winning tip's changesets to
+//!   the underlying databases and prunes dead forks.
+//!
+//! # Lazy Recovery
+//!
+//! Pending state lives entirely in memory. After a restart the map is empty,
+//! but the wrapper recovers lazily: when a parent's state is missing, it
+//! walks back through the block DAG via a [`BlockProvider`] to the nearest
+//! known ancestor, then replays forward via [`Application::replay`]. Each
+//! replayed block is inserted into the pending map immediately so that
+//! partial progress survives timeouts.
+
 use super::{db::DatabaseSet, Application};
 use commonware_consensus::{
     marshal::ancestry::{AncestorStream, BlockProvider},