Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

added docs to prunned_utreexo module and its submodules #401

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+63 −3
Open

added docs to prunned_utreexo module and its submodules #401

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions crates/floresta-chain/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)]
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As per the contributing.md:

If you need an attribute, use the attribute before the docstring

Please swap the attributes (this #[derive]) with the comment

pub enum Network {
Bitcoin,
Expand Down
18 changes: 18 additions & 0 deletions crates/floresta-chain/src/pruned_utreexo/chain_state.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,21 @@
//! This module is centered around the `ChainState` type, defining it and providing
//! implementations for the [BlockchainInterface] and [UpdatableChainstate] traits.
//!
//! Consequently, `ChainState` serves as the blockchain backend for our node and is
//! the highest-level type in `floresta-chain`. It is responsible for:
//!
//! - Keeping track of the chain state, and using a [ChainStore] for persisted storage
//! - Correctly updating the state with the help of the `consensus.rs` functions
//! - Interfacing with other components, and providing data about the current view of the chain
//!
//! The primary methods for updating our state are [ChainState::accept_header], which constructs
//! a chain of headers, and [ChainState::connect_block], which verifies the corresponding blocks.
//!
//! Key types:
//! - [ChainState]: The high-level chain backend
//! - [ChainStateInner]: Inner `ChainState` type that is guarded by a lock
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This struct doesn't leaks from our API. I'm not sure it should be here?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah

//! - [BlockConsumer]: Trait for receiving new block notifications
//! - [BestChain]: Tracks the current best chain and alternative forks
extern crate alloc;

use alloc::borrow::ToOwned;
Expand Down
10 changes: 10 additions & 0 deletions crates/floresta-chain/src/pruned_utreexo/chain_state_builder.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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;
Expand Down
11 changes: 11 additions & 0 deletions crates/floresta-chain/src/pruned_utreexo/chainparams.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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;
Expand Down
9 changes: 9 additions & 0 deletions crates/floresta-chain/src/pruned_utreexo/error.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,12 @@
//! This module defines error types specific to the blockchain validation and database operations, along with conversion between types.
//!
//! The main error types are:
//! - [BlockchainError]: High-level error type that encapsulates all the error kinds from our node chain backend operation.
//! - [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;
Expand Down
15 changes: 12 additions & 3 deletions crates/floresta-chain/src/pruned_utreexo/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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]: It defines persistence and retrieval of blockchain data
Comment on lines +1 to +9
Copy link
Contributor

@JoseSK999 JoseSK999 Mar 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A final nit, can you do something like this:

//! The pruned utreexo module handles the full blockchain logic: validation, state tracking and
//! interfacing. This blockchain backend does not store the historical blocks, it's pruned.
//!
//! This module file defines the main traits for an utreexo-enabled chain backend:
//!
//! - [BlockchainInterface]: The main interface for interacting with the backend
//! - [UpdatableChainstate]: Trait defining methods for updating the chain state
//! - [ChainStore]: Trait for persisting and retrieving blockchain data (headers, block hashes,
//!   the best chain data, and the accumulator)

extern crate alloc;

pub mod chain_state;
Expand Down Expand Up @@ -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
Expand Down