From fbaf50ed1ea0e533ce4b39bbc5d3955661cdb149 Mon Sep 17 00:00:00 2001
From: erhant <erhany96@gmail.com>
Date: Wed, 8 Jul 2026 17:49:21 +0300
Subject: [PATCH] chore(chain_state): doc fix

---
 lez/chain_state/src/apply.rs | 24 +++++++++++++-----------
 lez/chain_state/src/lib.rs   | 12 +++---------
 2 files changed, 16 insertions(+), 20 deletions(-)

diff --git a/lez/chain_state/src/apply.rs b/lez/chain_state/src/apply.rs
index 38e49b53..8a791a78 100644
--- a/lez/chain_state/src/apply.rs
+++ b/lez/chain_state/src/apply.rs
@@ -11,11 +11,8 @@ use lee::{GENESIS_BLOCK_ID, V03State};
 
 use crate::ingest_error::BlockIngestError;
 
-/// The last successfully applied block: the parent the next block must chain on.
-///
-/// Only what validation needs today (`block_id` + `hash`). The two-tier
-/// `ChainState`'s `final_tip` will extend this with the inscription `l1_slot`
-/// when the anchor layer lands; the slot is currently tracked separately.
+/// The parent the next block must chain on.
+// `l1_slot` will be added here when the `ChainState` anchor layer lands.
 #[derive(Debug, Clone)]
 pub struct Tip {
     pub block_id: u64,
@@ -34,9 +31,7 @@ pub enum AcceptOutcome {
 
 /// Validates `block` against `tip`, then applies it to `state`.
 ///
-/// Validation runs first and touches nothing. Application then mutates `state`
-/// in place and can fail partway, so callers pass a scratch clone and commit it
-/// only when this returns `Ok`.
+/// Mutates `state` in place, so callers pass a scratch clone and commit on `Ok`.
 pub fn apply_block(
     tip: Option<&Tip>,
     block: &Block,
@@ -181,7 +176,10 @@ mod tests {
         let err = apply_block(None, &block, &mut state).expect_err("should reject");
         assert!(matches!(
             err,
-            BlockIngestError::UnexpectedBlockId { expected: 1, got: 2 }
+            BlockIngestError::UnexpectedBlockId {
+                expected: 1,
+                got: 2
+            }
         ));
     }
 
@@ -193,10 +191,14 @@ mod tests {
 
         // Tip is at 1; a block with id 3 skips ahead.
         let bad = produce_dummy_block(3, Some(genesis.header.hash), vec![]);
-        let err = apply_block(Some(&tip_of(&genesis)), &bad, &mut state).expect_err("should reject");
+        let err =
+            apply_block(Some(&tip_of(&genesis)), &bad, &mut state).expect_err("should reject");
         assert!(matches!(
             err,
-            BlockIngestError::UnexpectedBlockId { expected: 2, got: 3 }
+            BlockIngestError::UnexpectedBlockId {
+                expected: 2,
+                got: 3
+            }
         ));
     }
 
diff --git a/lez/chain_state/src/lib.rs b/lez/chain_state/src/lib.rs
index 67efa146..065f643d 100644
--- a/lez/chain_state/src/lib.rs
+++ b/lez/chain_state/src/lib.rs
@@ -1,12 +1,6 @@
-//! Shared, storage-free chain-state core for the LEZ sequencer and indexer.
-//!
-//! Hosts the single validate-then-apply entry point ([`apply_block`]) plus the
-//! shared types ([`BlockIngestError`], [`StallReason`], [`Tip`],
-//! [`AcceptOutcome`]) that both the sequencer and the indexer build on. The
-//! crate performs no I/O: callers own their storage and drive the
-//! `scratch → persist → commit` ordering around these primitives.
-//!
-//! See `DESIGN.md` in this crate for the two-tier chain-state model this backs.
+//! Storage-free chain-state core shared by the LEZ sequencer and indexer:
+//! the [`apply_block`] entry point plus [`BlockIngestError`], [`StallReason`],
+//! [`Tip`], and [`AcceptOutcome`]. See `DESIGN.md` for the two-tier model.
 
 pub mod apply;
 pub mod ingest_error;