mina_tree/
lib.rs

1//! # Mina Ledger Crate
2//!
3//! The ledger crate is the most complex component in the Mina Rust node
4//! codebase.
5//! It implements the core ledger functionality, transaction processing, and
6//! proof system integration.
7//!
8//! ## Architecture Overview
9//!
10//! The ledger crate is organized into several key components:
11//!
12//! ### Core Ledger
13//!
14//! - [`base`] - BaseLedger trait providing the fundamental ledger interface
15//! - [`database`] - In-memory account storage implementation
16//! - [`mask`] - Layered ledger views with Arc-based sharing for efficient
17//!   copy-on-write semantics
18//! - [`tree`] - Merkle tree operations for cryptographic integrity
19//!
20//! ### Transaction Processing
21//!
22//! - [`transaction_pool`] - Memory pool (mempool) with fee-based transaction
23//!   ordering
24//! - [`staged_ledger`] - Block validation and transaction application logic
25//! - [`scan_state`] - SNARK work coordination and parallel scan tree management
26//!
27//! ### Proof System
28//!
29//! - [`proofs`] - Transaction, block, and zkApp proof generation and
30//!   verification
31//! - [`sparse_ledger`] - Minimal ledger representation optimized for proof
32//!   generation
33//! - [`zkapps`] - zkApp (zero-knowledge application) transaction processing
34//!
35//! ### Account Management
36//!
37//! - [`account`] - Account structures, balances, and permission management
38//! - [`address`] - Account addressing and public key management
39//!
40//! ## Implementation Status
41//!
42//! The ledger components have proven reliable on devnet despite some technical
43//! debt patterns. The implementation maintains the same battle-tested logic
44//! that runs the production Mina network, ensuring compatibility and
45//! correctness.
46//!
47//! ### Known Areas for Improvement
48//!
49//! #### Error Handling
50//!
51//! - Extensive use of `.unwrap()` and `.expect()` calls, particularly in:
52//!   - `scan_state/transaction_logic.rs`
53//!   - `staged_ledger/staged_ledger.rs`
54//!   - `transaction_pool.rs`
55//! - These calls are generally in code paths with well-understood preconditions
56//!   but could benefit from explicit error propagation
57//! - Inconsistent error handling patterns across modules
58//!
59//! #### Code Organization
60//!
61//! - Large files with multiple responsibilities that could benefit from decomposition
62//! - Some monolithic structures that make testing and maintenance more challenging
63//! - Opportunities for better separation of concerns in transaction processing logic
64//!
65//! ## Design Principles
66//!
67//! The ledger implementation follows several key design principles:
68//!
69//! - **Immutability**: Ledger states are immutable with copy-on-write semantics
70//! - **Layering**: Mask-based layering allows efficient branching and merging
71//! - **Cryptographic Integrity**: All ledger operations maintain Merkle tree
72//!   consistency
73//! - **Protocol Compliance**: Full compatibility with Mina protocol
74//!   specifications
75//! - **Performance**: Optimized for high-throughput transaction processing
76//!
77//! ## Usage Examples
78//!
79//! ```rust,no_run
80//! use mina_tree::{Database, Mask, BaseLedger};
81//!
82//! // Create a new ledger database
83//! let database = Database::create(35); // depth = 35
84//!
85//! // Create a mask for efficient layering
86//! let mask = Mask::new_root(database);
87//!
88//! // Ledger operations can now be performed through the mask
89//! ```
90//!
91//! For more detailed examples and API usage, see the individual module documentation.
92
93#![allow(dead_code)]
94#![allow(clippy::type_complexity)]
95#![allow(clippy::too_many_arguments)]
96#![allow(clippy::uninlined_format_args)]
97#![allow(clippy::len_without_is_empty)]
98#![allow(clippy::result_unit_err)]
99// #![forbid(clippy::needless_pass_by_ref_mut)]
100
101// Unused, we don't want to print on stdout
102// /// Print logs on stdout with the prefix `[ledger]`
103// macro_rules! log {
104//     () => (elog!("[ledger]"));
105//     ($($arg:tt)*) => ({
106//         println!("[ledger] {}", format_args!($($arg)*))
107//     })
108// }
109
110/// Print logs on stderr with the prefix `[ledger]`
111macro_rules! elog {
112    () => (elog!("[ledger]"));
113    ($($arg:tt)*) => ({
114        let _ = &format_args!($($arg)*);
115        // eprintln!("[ledger] {}", format_args!($($arg)*));
116    })
117}
118
119// We need a feature to tests both nodejs and browser
120// <https://github.com/rustwasm/wasm-bindgen/issues/2571>
121#[cfg(not(feature = "in_nodejs"))]
122#[cfg(target_family = "wasm")]
123#[cfg(test)]
124mod wasm {
125    use wasm_bindgen_test::*;
126    wasm_bindgen_test_configure!(run_in_browser);
127}
128
129#[macro_use]
130mod cache;
131
132#[cfg(all(not(target_family = "wasm"), feature = "ocaml-interop"))]
133mod ffi;
134
135#[cfg(any(test, feature = "fuzzing"))]
136pub mod generators;
137
138pub mod account;
139pub mod address;
140pub mod base;
141// mod blocks;
142pub mod database;
143pub mod dummy;
144mod hash;
145pub mod mask;
146pub mod ondisk;
147mod port_ocaml;
148pub mod proofs;
149pub mod scan_state;
150pub mod sparse_ledger;
151pub mod staged_ledger;
152pub mod transaction_pool;
153pub mod tree;
154mod tree_version;
155mod util;
156pub mod verifier;
157pub mod zkapps;
158
159pub use account::*;
160pub use address::*;
161pub use base::*;
162// pub use blocks::*;
163pub use database::*;
164pub use hash::*;
165pub use mask::*;
166pub use tree::*;
167pub use tree_version::*;
168pub use util::*;
mina_tree/lib.rs

mina_tree/
lib.rs
