Merge pull request #1736 from o1-labs/dw/node-crate-1

Node: add succinct top-level documentation

Author: dannywillems

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+
+- **Node**: add top-level documentation for the crate `node`
+  ([#1736](https://github.com/o1-labs/mina-rust/pull/1736))
+
 ### Changes
 
 - **Dependency**: use tag instead of references of o1-labs/proof-systems, fix

node/src/block_producer/mod.rs

@@ -175,14 +175,6 @@ pub fn next_epoch_first_slot(global_slot: &v2::ConsensusGlobalSlotStableV1) -> u
         .expect("overflow")
 }
 
-// Returns the epoch number and whether it is the last slot of the epoch
-// pub fn epoch_with_bounds(global_slot: u32) -> (u32, bool) {
-//     // let epoch_bound = |global_slot| -> (u32, bool) {
-//     //     (global_slot / SLOTS_PER_EPOCH, (global_slot + 1) % SLOTS_PER_EPOCH == 0)
-//     // };
-
-// }
-
 impl BlockWithoutProof {
     pub fn with_hash_and_proof(
         self,

node/src/lib.rs

@@ -1,3 +1,48 @@
+//! # Node Crate
+//!
+//! The node crate combines all state machines of the Mina blockchain node into
+//! one unified state machine using a Redux-style architecture.
+//!
+//! ## Core Architecture
+//!
+//! | Component   | Location           | Purpose                                      |
+//! |-------------|--------------------|----------------------------------------------|
+//! | Actions     | [`Action`]         | Events that trigger state changes            |
+//! | Effects     | [`effects()`]      | Side-effects and service calls               |
+//! | Reducers    | [`reducer()`]      | Functions that mutate state                  |
+//! | Services    | [`service`]        | I/O and heavy computation (separate threads) |
+//! | State       | [`State`]          | Centralized, immutable data structure        |
+//!
+//! ## Execution Flow
+//!
+//! ```text
+//! Event arrives
+//! -> Dispatch Action
+//! -> Check Enabling Condition
+//! -> Reducer (mutate state)
+//! -> Effects (side-effects)
+//! -> Service callbacks
+//! -> Loop
+//! ```
+//!
+//! ## Key Components
+//!
+//! | Component              | Module                     | Purpose                             |
+//! |------------------------|----------------------------|-------------------------------------|
+//! | Block Producer         | [`block_producer`]         | Block creation on won slots         |
+//! | Event Source           | [`event_source`]           | External event ingestion            |
+//! | External SNARK Worker  | [`external_snark_worker`]  | External SNARK worker management    |
+//! | Ledger                 | [`ledger`]                 | Account state and transactions      |
+//! | Logger                 | [`logger`]                 | Logging utilities                   |
+//! | P2P                    | [`p2p`]                    | Networking layer                    |
+//! | Recorder               | [`recorder`]               | Action recording for replay         |
+//! | RPC                    | [`rpc`]                    | JSON-RPC API                        |
+//! | SNARK Pool             | [`snark_pool`]             | Proof work management               |
+//! | Stats                  | [`stats`]                  | Statistics tracking                 |
+//! | Transaction Pool       | [`transaction_pool`]       | Mempool for pending transactions    |
+//! | Transition Frontier    | [`transition_frontier`]    | Blockchain consensus and best chain |
+//! | Watched Accounts       | [`watched_accounts`]       | Account monitoring                  |
+
 #![allow(clippy::if_same_then_else)]
 
 extern crate graphannis_malloc_size_of as malloc_size_of;