docs(core): Add module-level docs for `checkpoint_entry`

Explain the purpose of `CheckPointEntry` and its two variants:
- `Occupied`: real checkpoint at this height
- `Placeholder`: implied by `prev_blockhash` from checkpoint above

Also fix typo: "atleast" → "at least"

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

diff --git a/crates/chain/src/local_chain.rs b/crates/chain/src/local_chain.rs
index 4e92e94d72e62538eb4b12c412d23116099c8d4c..537e910ece8bdef410f57c30f381376648f47f2e 100644 (file)
--- a/crates/chain/src/local_chain.rs
+++ b/crates/chain/src/local_chain.rs
@@ -263,7 +263,7 @@ where
         CheckPoint::from_blocks(blocks)
             .map(|tip| Self { tip })
             .map_err(|err| {
-                let last_cp = err.expect("must have atleast one block (genesis)");
+                let last_cp = err.expect("must have at least one block (genesis)");
                 ApplyBlockError::PrevBlockhashMismatch {
                     expected: last_cp.block_id(),
                 }

diff --git a/crates/core/src/checkpoint_entry.rs b/crates/core/src/checkpoint_entry.rs
index 7475e4f4c9c0e538e706cc03389037c70ef0a82b..b0151ec98f164f1ebd43f06d37835de765ad7686 100644 (file)
--- a/crates/core/src/checkpoint_entry.rs
+++ b/crates/core/src/checkpoint_entry.rs
@@ -1,3 +1,16 @@
+//! Checkpoint entries for `prev_blockhash`-aware iteration.
+//!
+//! A [`CheckPoint`] chain may have gaps (non-contiguous heights). However, each checkpoint's
+//! data can include a `prev_blockhash` that references the block one height below. This module
+//! provides [`CheckPointEntry`], which represents either:
+//!
+//! - **Occupied**: A real checkpoint stored at this height.
+//! - **Placeholder**: No checkpoint exists at this height, but the checkpoint above references it
+//!   via `prev_blockhash`. The placeholder contains the implied [`BlockId`].
+//!
+//! Use [`CheckPoint::entry_iter`] to iterate over entries, which yields placeholders for any
+//! gaps where `prev_blockhash` implies a block.
+
 use core::ops::RangeBounds;
 
 use bitcoin::BlockHash;