added docs to prunned_utreexo module and its submodules

crates/floresta-chain/src/lib.rs

@@ -21,6 +21,9 @@ pub use pruned_utreexo::error::*;
 pub use pruned_utreexo::udata::*;
 pub use pruned_utreexo::Notification;
 
+/// Simple enum representing the network type.
+///
+/// Possible values are Bitcoin, Testnet, Regtest, and Signet.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Network {
     Bitcoin,

crates/floresta-chain/src/pruned_utreexo/chain_state.rs

@@ -1,3 +1,19 @@
+//! The chain state contains both the blocks and blockchain validation logic
+//!
+//! This module provides the implementation of Bitcoin's consensus rules and chain validation,
+//! enabling verification of transactions and blocks. It maintains:
+//!
+//! - Block headers and chain organization
+//! - Chain selection based on proof-of-work
+//! - Block validation and transaction verification
+//! - UTXO set tracking via a Utreexo accumulator
+//! - Support for Initial Block Download (IBD)
+//!
+//! Key types:
+//! - [ChainState]: Main type implementing chain consensus and block validation
+//! - [ChainStateInner]: Internal state storage and validation data
+//! - [BlockConsumer]: Trait for receiving new block notifications
+//! - [BestChain]: Tracks the current best chain and alternative forks
 extern crate alloc;
 
 use alloc::borrow::ToOwned;

crates/floresta-chain/src/pruned_utreexo/chain_state_builder.rs

@@ -1,3 +1,13 @@
+//! This module provides a builder pattern for constructing ChainState instances with various
+//! optional configurations.
+//!
+//! It includes:
+//! - Chain parameters
+//! - Chainstore backend
+//! - Initial block download status
+//! - Assumed valid blocks for validation optimization
+//! - UTREEXO accumulator state
+//! - Current chain tip and header
 use bitcoin::block::Header as BlockHeader;
 use bitcoin::hashes::Hash;
 use bitcoin::BlockHash;

crates/floresta-chain/src/pruned_utreexo/chainparams.rs

@@ -1,3 +1,14 @@
+//! This module provides configuration and parameters for different Bitcoin networks (mainnet,
+//! testnet, signet, and regtest).
+//!
+//! It includes:
+//! - Network-specific parameters like block reward halving intervals and maturity periods
+//! - DNS seeds for peer discovery
+//! - Assumable validation states for Utreexo
+//! - Block verification flag exceptions
+//!
+//! The main struct [`ChainParams`] encapsulates all chain-specific parameters while
+//! [`DnsSeed`] handles peer discovery through DNS.
 extern crate alloc;
 use alloc::vec::Vec;
 use core::ffi::c_uint;

crates/floresta-chain/src/pruned_utreexo/error.rs

@@ -1,3 +1,12 @@
+//! High-level error type that encapsulates all the error kinds from our node chain backend operation.
+//!
+//! The main error types are:
+//! - [BlockchainError]: Top-level error type for blockchain operations
+//! - [TransactionError]: Represents errors in transaction validation
+//! - [BlockValidationErrors]: Errors encountered during block validation that are not tied to any specific transaction
+//!
+//! Each error type implements `Display` and `Debug` for error reporting.
+
 use core::fmt::Debug;
 
 use bitcoin::blockdata::script;

crates/floresta-chain/src/pruned_utreexo/mod.rs

@@ -1,3 +1,12 @@
+//! The pruned utreexo module is where the full blockchain logic is handled (validation, state tracking and interfacing). It uses a pruned chain, which does not keep the historical blocks.
+//!
+//! This module contains the main traits and types for interacting with an utreexo-enabled blockchain.
+//! It also provides some utilities for inspecting the utxo set and managing chain state.
+//!
+//! The key components are:
+//! - [BlockchainInterface]: The main interface for interacting with the blockchain
+//! - [UpdatableChainstate]: Handles updates to the chain state including blocks and transactions
+//! - [ChainStore]: Defines persistence and retrieval of blockchain data
 extern crate alloc;
 
 pub mod chain_state;
@@ -158,10 +167,10 @@ pub trait UpdatableChainstate {
     fn mark_chain_as_assumed(&self, acc: Stump, tip: BlockHash) -> Result<bool, BlockchainError>;
 }
 
-/// [ChainStore] is a trait defining how we interact with our chain database. This definitions
-/// will be used by the [ChainState] to save and retrieve data about the blockchain, likely
+/// This trait is defining how we interact with our chain database. This definitions
+/// will be used by the [ChainState](chain_state::ChainState) to save and retrieve data about the blockchain, likely
 /// on disk.
-/// Right now, you can use the [KvChainStore] in your code, it implements this trait and
+/// Right now, you can use the [KvChainStore](chainstore::KvChainStore) in your code, it implements this trait and
 /// uses a key-value store to save data.
 /// The [DatabaseError] is a simple trait that can be implemented by any error type that
 /// implements [std::error::Error] and [std::fmt::Display]. This is useful to abstract