Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
102 changes: 97 additions & 5 deletions ledger/src/lib.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,95 @@
//! # Mina Ledger Crate
//!
//! The ledger crate is the most complex component in the Mina Rust node
//! codebase.
//! It implements the core ledger functionality, transaction processing, and
//! proof system integration.
//!
//! ## Architecture Overview
//!
//! The ledger crate is organized into several key components:
//!
//! ### Core Ledger
//!
//! - [`base`] - BaseLedger trait providing the fundamental ledger interface
//! - [`database`] - In-memory account storage implementation
//! - [`mask`] - Layered ledger views with Arc-based sharing for efficient
//! copy-on-write semantics
//! - [`tree`] - Merkle tree operations for cryptographic integrity
//!
//! ### Transaction Processing
//!
//! - [`transaction_pool`] - Memory pool (mempool) with fee-based transaction
//! ordering
//! - [`staged_ledger`] - Block validation and transaction application logic
//! - [`scan_state`] - SNARK work coordination and parallel scan tree management
//!
//! ### Proof System
//!
//! - [`proofs`] - Transaction, block, and zkApp proof generation and
//! verification
//! - [`sparse_ledger`] - Minimal ledger representation optimized for proof
//! generation
//! - [`zkapps`] - zkApp (zero-knowledge application) transaction processing
//!
//! ### Account Management
//!
//! - [`account`] - Account structures, balances, and permission management
//! - [`address`] - Account addressing and public key management
//!
//! ## Implementation Status
//!
//! The ledger components have proven reliable on devnet despite some technical
//! debt patterns. The implementation maintains the same battle-tested logic
//! that runs the production Mina network, ensuring compatibility and
//! correctness.
//!
//! ### Known Areas for Improvement
//!
//! #### Error Handling
//!
//! - Extensive use of `.unwrap()` and `.expect()` calls, particularly in:
//! - `scan_state/transaction_logic.rs`
//! - `staged_ledger/staged_ledger.rs`
//! - `transaction_pool.rs`
//! - These calls are generally in code paths with well-understood preconditions
//! but could benefit from explicit error propagation
//! - Inconsistent error handling patterns across modules
//!
//! #### Code Organization
//!
//! - Large files with multiple responsibilities that could benefit from decomposition
//! - Some monolithic structures that make testing and maintenance more challenging
//! - Opportunities for better separation of concerns in transaction processing logic
//!
//! ## Design Principles
//!
//! The ledger implementation follows several key design principles:
//!
//! - **Immutability**: Ledger states are immutable with copy-on-write semantics
//! - **Layering**: Mask-based layering allows efficient branching and merging
//! - **Cryptographic Integrity**: All ledger operations maintain Merkle tree
//! consistency
//! - **Protocol Compliance**: Full compatibility with Mina protocol
//! specifications
//! - **Performance**: Optimized for high-throughput transaction processing
//!
//! ## Usage Examples
//!
//! ```rust,no_run
//! use mina_tree::{Database, Mask, BaseLedger};
//!
//! // Create a new ledger database
//! let database = Database::create(35); // depth = 35
//!
//! // Create a mask for efficient layering
//! let mask = Mask::new_root(database);
//!
//! // Ledger operations can now be performed through the mask
//! ```
//!
//! For more detailed examples and API usage, see the individual module documentation.

#![allow(dead_code)]
#![allow(clippy::type_complexity)]
#![allow(clippy::too_many_arguments)]
Expand Down Expand Up @@ -43,11 +135,11 @@ mod ffi;
#[cfg(any(test, feature = "fuzzing"))]
pub mod generators;

mod account;
mod address;
mod base;
pub mod account;
pub mod address;
pub mod base;
// mod blocks;
mod database;
pub mod database;
pub mod dummy;
mod hash;
pub mod mask;
Expand All @@ -58,7 +150,7 @@ pub mod scan_state;
pub mod sparse_ledger;
pub mod staged_ledger;
pub mod transaction_pool;
mod tree;
pub mod tree;
mod tree_version;
mod util;
pub mod verifier;
Expand Down
114 changes: 114 additions & 0 deletions ledger/src/proofs/circuit_blobs.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,117 @@
//! # Circuit Constraint Extraction
//!
//! This module handles circuit constraint extraction for the Mina Rust node.
//! Circuit constraints are sourced from the
//! [circuit-blobs](https://github.com/openmina/circuit-blobs) repository, which
//! contains pre-compiled circuit data generated by the OCaml implementation.
//!
//! ## Overview
//!
//! The Mina Rust node automatically handles downloading and caching circuit
//! files, making the process transparent to users. When you run the node or
//! generate proofs, the system will automatically fetch the required circuit
//! data if it's not already available locally.
//!
//! ## Circuit Data Files
//!
//! The circuit-blobs repository contains three types of files for each circuit:
//!
//! ### Gates Definition (`*_gates.json`)
//!
//! - JSON files containing the list of gates for each circuit
//! - Define the circuit structure and operations
//! - Used for generating proving and verification keys
//!
//! ### Internal Variables (`*_internal_vars.bin`)
//!
//! - Binary files containing internal variable mappings
//! - Store relationships between field elements and variable indices
//! - Essential for witness generation
//!
//! ### Row Reversal Data (`*_rows_rev.bin`)
//!
//! - Binary files containing constraint system data
//! - Used for efficient constraint evaluation
//! - Required for proof generation
//!
//! ## Extraction Process
//!
//! The Mina Rust node automatically handles circuit constraint extraction
//! through this module's [`fetch_blocking`] function.
//!
//! ### Local Resolution
//!
//! The system searches for circuit files in these locations (in order):
//!
//! 1. **Environment Variable**: `MINA_CIRCUIT_BLOBS_BASE_DIR`
//! 2. **Cargo Manifest Directory**: Current project directory
//! 3. **Home Directory**: `~/.openmina/circuit-blobs/`
//! 4. **System Directory**: `/usr/local/lib/openmina/circuit-blobs`
//!
//! ### Remote Fetching
//!
//! If files are not found locally, the system automatically downloads them from:
//!
//! ```text
//! https://github.com/openmina/circuit-blobs/releases/download/<filename>
//! ```
//!
//! Downloaded files are cached locally for future use.
//!
//! ## Web Environment
//!
//! For web deployments, circuit files are served statically:
//!
//! - **Frontend Path**: `/assets/webnode/circuit-blobs/<version>/`
//! - **Download Script**: `frontend/docker/startup.sh` handles automatic
//! downloading
//! - **Version**: Specified by `CIRCUITS_VERSION` environment variable
//!
//! ## How It Works for Users
//!
//! ### First Run Experience
//!
//! When you first run the Mina Rust node or generate proofs:
//!
//! 1. **Automatic Detection**: The system checks for required circuit files
//! 2. **Local Search**: Searches in these locations (in order):
//! - `$MINA_CIRCUIT_BLOBS_BASE_DIR` (if set)
//! - Current project directory
//! - `~/.openmina/circuit-blobs/`
//! - `/usr/local/lib/openmina/circuit-blobs`
//! 3. **Automatic Download**: If files aren't found locally, downloads from GitHub
//! 4. **Local Caching**: Saves downloaded files to `~/.openmina/circuit-blobs/`
//! 5. **Ready to Use**: Circuit data is loaded and ready for proof generation
//!
//! ### Subsequent Runs
//!
//! - Uses cached files from `~/.openmina/circuit-blobs/`
//! - No network requests needed
//! - Fast startup times
//!
//! ## Development Guidelines
//!
//! ### Adding New Circuit Types
//!
//! 1. Generate circuit data using OCaml implementation
//! 2. Add files to circuit-blobs repository
//! 3. Update circuit configuration in `mina_core::network`
//! 4. Add prover creation logic in [`crate::proofs::provers`]
//!
//! ### Local Development
//!
//! Set `MINA_CIRCUIT_BLOBS_BASE_DIR` environment variable to point to your
//! local circuit-blobs repository clone:
//!
//! ```bash
//! export MINA_CIRCUIT_BLOBS_BASE_DIR=/path/to/your/circuit-blobs
//! ```
//!
//! ## Related Modules
//!
//! - [`crate::proofs::provers`]: Prover creation using circuit data
//! - [`crate::proofs::constants`]: Circuit type definitions

use std::path::Path;

#[cfg(not(target_family = "wasm"))]
Expand Down
2 changes: 1 addition & 1 deletion ledger/src/proofs/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ use poly_commitment::evaluation_proof::OpeningProof;
pub mod accumulator_check;
pub mod block;
pub mod caching;
mod circuit_blobs;
pub mod circuit_blobs;
pub mod constants;
mod conv;
pub mod field;
Expand Down
Loading
Loading