SNARK library: document with top-level comments

Author: dannywillems

snark/src/block_verify/mod.rs

@@ -1,3 +1,34 @@
+//! # Block Verification State Machine
+//!
+//! This module implements the state machine for verifying blockchain block proofs
+//! within the Mina protocol. It manages the lifecycle of block verification requests
+//! and maintains verification state.
+//!
+//! ## Overview
+//!
+//! Block verification ensures that:
+//! - Block proofs are cryptographically valid
+//! - Block headers contain correct consensus information
+//! - Blockchain state transitions are legitimate
+//!
+//! ## State Machine
+//!
+//! The block verification process follows these states:
+//! - **Idle**: Ready to accept new verification requests
+//! - **Pending**: Verification in progress
+//! - **Success**: Block successfully verified
+//! - **Error**: Verification failed with error details
+//!
+//! ## Usage
+//!
+//! Block verification is typically initiated by:
+//! - Consensus mechanisms validating incoming blocks
+//! - Sync processes verifying historical blocks
+//! - Fork resolution comparing competing chains
+//!
+//! The verification process runs asynchronously in service threads to avoid
+//! blocking the main state machine.
+
 mod snark_block_verify_state;
 pub use snark_block_verify_state::*;
 

snark/src/block_verify_effectful/mod.rs

@@ -1,3 +1,31 @@
+//! # Block Verification Service Layer
+//!
+//! This module provides the effectful (side-effect) operations for block verification,
+//! separating the heavy cryptographic computations from the main state machine logic.
+//!
+//! ## Architecture Separation
+//!
+//! This effectful layer handles:
+//! - **Asynchronous Operations**: CPU-intensive proof verification
+//! - **Service Interactions**: Integration with verification backends
+//! - **Thread Management**: Non-blocking execution of verification tasks
+//! - **Error Handling**: Detailed verification failure reporting
+//!
+//! ## Service Interface
+//!
+//! The [`SnarkBlockVerifyService`] trait defines the interface for:
+//! - Initiating block verification requests
+//! - Receiving verification results via callbacks
+//! - Managing verification queue and priorities
+//!
+//! ## Integration Pattern
+//!
+//! The effectful pattern ensures that:
+//! 1. State machine remains deterministic and pure
+//! 2. Heavy computations don't block the main thread
+//! 3. Verification results flow back through events
+//! 4. System stays responsive during proof verification
+
 mod snark_block_verify_effectful_actions;
 pub use snark_block_verify_effectful_actions::*;
 

snark/src/lib.rs

@@ -1,3 +1,75 @@
+//! # SNARK Verification Orchestration
+//!
+//! The SNARK crate provides zero-knowledge proof verification capabilities for the Mina Rust node,
+//! orchestrating the verification of blocks, transactions, and SNARK work through a Redux-style
+//! state machine architecture.
+//!
+//! ## Overview
+//!
+//! This crate handles three main types of proof verification:
+//! - **Block Verification**: Validates blockchain blocks and their proofs
+//! - **Transaction Verification**: Verifies user commands and zkApp transactions
+//! - **Work Verification**: Validates SNARK work proofs from workers
+//!
+//! ## Architecture
+//!
+//! The crate follows the Mina node's Redux architecture pattern with:
+//! - **State**: [`SnarkState`] - Centralized verification state
+//! - **Actions**: [`SnarkAction`] - Events triggering verification operations
+//! - **Enabling Conditions**: [`redux::EnablingCondition`] - Guards preventing invalid state transitions
+//! - **Reducers**: Pure functions managing state transitions
+//! - **Effects**: Service interactions for actual proof verification
+//!
+//! ## Core Components
+//!
+//! ### Verification State Machine
+//!
+//! Each verification type maintains its own state machine:
+//! - [`block_verify`] - Block proof verification state machine
+//! - [`user_command_verify`] - User command verification state machine
+//! - [`work_verify`] - SNARK work verification state machine
+//!
+//! ### Effectful Operations
+//!
+//! Heavy cryptographic operations run in separate service threads:
+//! - [`block_verify_effectful`] - Block verification services
+//! - [`user_command_verify_effectful`] - Transaction verification services
+//! - [`work_verify_effectful`] - Work verification services
+//!
+//! ## Configuration
+//!
+//! The [`SnarkConfig`] contains verifier indices and SRS (Structured Reference String)
+//! parameters required for proof verification. These are network-specific and loaded
+//! during initialization.
+//!
+//! ## Integration
+//!
+//! The SNARK crate integrates with:
+//! - **Ledger**: Uses cryptographic primitives from the ledger crate
+//! - **Kimchi**: Leverages the Kimchi proving system for verification
+//! - **Node**: Provides verification services to the main node
+//!
+//! ## Example Usage
+//!
+//! ```rust,no_run
+//! use snark::{SnarkConfig, SnarkState};
+//!
+//! // Initialize SNARK state with configuration
+//! let config = SnarkConfig { /* ... */ };
+//! let state = SnarkState::new(config);
+//!
+//! // The state machine handles verification requests through actions
+//! // dispatched by the main node's Redux store
+//! ```
+//!
+//! ## Performance Considerations
+//!
+//! - Proof verification is CPU-intensive and runs asynchronously
+//! - Verifier indices and SRS parameters are cached for reuse
+//! - Multiple verification operations can run concurrently
+//!
+//! For detailed API documentation, see the individual module documentation.
+
 use kimchi::mina_curves::pasta::Vesta;
 
 mod merkle_path;

snark/src/merkle_path/mod.rs

@@ -1,3 +1,27 @@
+//! # Merkle Path Verification Utilities
+//!
+//! This module provides utilities for computing and verifying Merkle tree paths,
+//! which are essential for account existence proofs in the Mina ledger.
+//!
+//! ## Overview
+//!
+//! Merkle paths enable:
+//! - **Account Verification**: Proving an account exists in the ledger
+//! - **State Consistency**: Validating ledger state transitions
+//! - **Efficient Proofs**: Compact proofs of inclusion without full ledger
+//!
+//! ## Key Function
+//!
+//! [`calc_merkle_root_hash`] computes the root hash from an account and its Merkle path,
+//! allowing verification that the account is part of a specific ledger state.
+//!
+//! ## Usage in Verification
+//!
+//! This is commonly used in:
+//! - Transaction verification (ensuring account exists)
+//! - SNARK proof generation (ledger state proofs)
+//! - Account state validation in zkApps
+
 use ark_ff::fields::arithmetic::InvalidBigInt;
 use mina_p2p_messages::{bigint::BigInt, v2::MerkleTreeNode};
 use poseidon::hash::params::get_merkle_param_for_height;

snark/src/user_command_verify/mod.rs

@@ -1,3 +1,34 @@
+//! # User Command Verification State Machine
+//!
+//! This module handles the verification of user commands and zkApp transactions
+//! within the Mina protocol. It manages cryptographic proof validation for
+//! transactions before they are included in blocks.
+//!
+//! ## Overview
+//!
+//! User command verification validates:
+//! - **Payment transactions**: Simple value transfers between accounts
+//! - **Delegation commands**: Stake delegation operations
+//! - **zkApp transactions**: Complex smart contract interactions with zero-knowledge proofs
+//!
+//! ## Verification Process
+//!
+//! The verification process includes:
+//! - Signature validation for transaction authorization
+//! - Proof verification for zkApp transactions
+//! - Account state consistency checks
+//! - Fee and nonce validation
+//!
+//! ## Performance
+//!
+//! Transaction verification is batched for efficiency:
+//! - Multiple transactions verified concurrently
+//! - Failed verifications reported with detailed errors
+//! - Successful transactions forwarded to the transaction pool
+//!
+//! This module is critical for maintaining network security by ensuring
+//! only valid transactions are propagated and included in blocks.
+
 mod snark_user_command_verify_state;
 pub use snark_user_command_verify_state::*;
 

snark/src/work_verify/mod.rs

@@ -1,3 +1,40 @@
+//! # SNARK Work Verification State Machine
+//!
+//! This module manages the verification of SNARK work proofs submitted by
+//! external SNARK workers. It validates computational work that helps maintain
+//! the blockchain's security and scalability.
+//!
+//! ## Overview
+//!
+//! SNARK work verification handles:
+//! - **Transaction SNARK proofs**: Proofs for transaction validity
+//! - **Merge proofs**: Proofs combining multiple transaction proofs
+//!
+//! ## SNARK Worker Ecosystem
+//!
+//! The Mina protocol relies on a decentralized network of SNARK workers who:
+//! - Compute zero-knowledge proofs for transactions
+//! - Submit completed work to block producers
+//! - Receive fees for successful proof generation
+//!
+//! ## Verification Pipeline
+//!
+//! Work verification follows this process:
+//! 1. **Reception**: SNARK work received from workers or peers
+//! 2. **Validation**: Cryptographic proof verification
+//! 3. **Integration**: Valid work added to the SNARK pool
+//! 4. **Rewards**: Workers compensated for successful work
+//!
+//! ## Economic Incentives
+//!
+//! This module supports the economic model where:
+//! - SNARK workers are paid fees for valid proofs
+//! - Invalid work is rejected without compensation
+//! - The network maintains decentralized proof generation
+//!
+//! The verification process is essential for Mina's scalability, enabling
+//! the blockchain to maintain constant size regardless of transaction volume.
+
 mod snark_work_verify_state;
 pub use snark_work_verify_state::*;