Skip to content

Commit 796567b

Browse files
dannywillemsdannywillems
committed
Website: add circuits extraction logic in doc
1 parent 7c20e9a commit 796567b

File tree

3 files changed

+132
-1
lines changed

3 files changed

+132
-1
lines changed

‎ledger/src/proofs/circuit_blobs.rs‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,117 @@
1+
//! # Circuit Constraint Extraction
2+
//!
3+
//! This module handles circuit constraint extraction for the Mina Rust node.
4+
//! Circuit constraints are sourced from the
5+
//! [circuit-blobs](https://github.com/openmina/circuit-blobs) repository, which
6+
//! contains pre-compiled circuit data generated by the OCaml implementation.
7+
//!
8+
//! ## Overview
9+
//!
10+
//! The Mina Rust node automatically handles downloading and caching circuit
11+
//! files, making the process transparent to users. When you run the node or
12+
//! generate proofs, the system will automatically fetch the required circuit
13+
//! data if it's not already available locally.
14+
//!
15+
//! ## Circuit Data Files
16+
//!
17+
//! The circuit-blobs repository contains three types of files for each circuit:
18+
//!
19+
//! ### Gates Definition (`*_gates.json`)
20+
//!
21+
//! - JSON files containing the list of gates for each circuit
22+
//! - Define the circuit structure and operations
23+
//! - Used for generating proving and verification keys
24+
//!
25+
//! ### Internal Variables (`*_internal_vars.bin`)
26+
//!
27+
//! - Binary files containing internal variable mappings
28+
//! - Store relationships between field elements and variable indices
29+
//! - Essential for witness generation
30+
//!
31+
//! ### Row Reversal Data (`*_rows_rev.bin`)
32+
//!
33+
//! - Binary files containing constraint system data
34+
//! - Used for efficient constraint evaluation
35+
//! - Required for proof generation
36+
//!
37+
//! ## Extraction Process
38+
//!
39+
//! The Mina Rust node automatically handles circuit constraint extraction
40+
//! through this module's [`fetch_blocking`] function.
41+
//!
42+
//! ### Local Resolution
43+
//!
44+
//! The system searches for circuit files in these locations (in order):
45+
//!
46+
//! 1. **Environment Variable**: `MINA_CIRCUIT_BLOBS_BASE_DIR`
47+
//! 2. **Cargo Manifest Directory**: Current project directory
48+
//! 3. **Home Directory**: `~/.openmina/circuit-blobs/`
49+
//! 4. **System Directory**: `/usr/local/lib/openmina/circuit-blobs`
50+
//!
51+
//! ### Remote Fetching
52+
//!
53+
//! If files are not found locally, the system automatically downloads them from:
54+
//!
55+
//! ```text
56+
//! https://github.com/openmina/circuit-blobs/releases/download/<filename>
57+
//! ```
58+
//!
59+
//! Downloaded files are cached locally for future use.
60+
//!
61+
//! ## Web Environment
62+
//!
63+
//! For web deployments, circuit files are served statically:
64+
//!
65+
//! - **Frontend Path**: `/assets/webnode/circuit-blobs/<version>/`
66+
//! - **Download Script**: `frontend/docker/startup.sh` handles automatic
67+
//! downloading
68+
//! - **Version**: Specified by `CIRCUITS_VERSION` environment variable
69+
//!
70+
//! ## How It Works for Users
71+
//!
72+
//! ### First Run Experience
73+
//!
74+
//! When you first run the Mina Rust node or generate proofs:
75+
//!
76+
//! 1. **Automatic Detection**: The system checks for required circuit files
77+
//! 2. **Local Search**: Searches in these locations (in order):
78+
//! - `$MINA_CIRCUIT_BLOBS_BASE_DIR` (if set)
79+
//! - Current project directory
80+
//! - `~/.openmina/circuit-blobs/`
81+
//! - `/usr/local/lib/openmina/circuit-blobs`
82+
//! 3. **Automatic Download**: If files aren't found locally, downloads from GitHub
83+
//! 4. **Local Caching**: Saves downloaded files to `~/.openmina/circuit-blobs/`
84+
//! 5. **Ready to Use**: Circuit data is loaded and ready for proof generation
85+
//!
86+
//! ### Subsequent Runs
87+
//!
88+
//! - Uses cached files from `~/.openmina/circuit-blobs/`
89+
//! - No network requests needed
90+
//! - Fast startup times
91+
//!
92+
//! ## Development Guidelines
93+
//!
94+
//! ### Adding New Circuit Types
95+
//!
96+
//! 1. Generate circuit data using OCaml implementation
97+
//! 2. Add files to circuit-blobs repository
98+
//! 3. Update circuit configuration in `mina_core::network`
99+
//! 4. Add prover creation logic in [`crate::proofs::provers`]
100+
//!
101+
//! ### Local Development
102+
//!
103+
//! Set `MINA_CIRCUIT_BLOBS_BASE_DIR` environment variable to point to your
104+
//! local circuit-blobs repository clone:
105+
//!
106+
//! ```bash
107+
//! export MINA_CIRCUIT_BLOBS_BASE_DIR=/path/to/your/circuit-blobs
108+
//! ```
109+
//!
110+
//! ## Related Modules
111+
//!
112+
//! - [`crate::proofs::provers`]: Prover creation using circuit data
113+
//! - [`crate::proofs::constants`]: Circuit type definitions
114+
1115
use std::path::Path;
2116

3117
#[cfg(not(target_family = "wasm"))]

‎ledger/src/proofs/mod.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ use poly_commitment::evaluation_proof::OpeningProof;
44
pub mod accumulator_check;
55
pub mod block;
66
pub mod caching;
7-
mod circuit_blobs;
7+
pub mod circuit_blobs;
88
pub mod constants;
99
mod conv;
1010
pub mod field;

‎website/docs/developers/circuits.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,23 @@ proof types:
233233
- Protocol compliance validation
234234
- Regression testing for circuit changes
235235

236+
## Circuit Constraint Extraction
237+
238+
For a comprehensive technical overview of circuit constraint extraction, see the
239+
[circuit_blobs module documentation](https://o1-labs.github.io/mina-rust/api-docs/ledger/proofs/circuit_blobs/index.html)
240+
in the ledger crate.
241+
242+
### Overview
243+
244+
Circuit constraints for the Mina Rust node are sourced from the
245+
[circuit-blobs](https://github.com/openmina/circuit-blobs) repository, which
246+
contains pre-compiled circuit data generated by the OCaml implementation.
247+
248+
The Mina Rust node automatically handles downloading and caching these circuit
249+
files, making the process transparent to users. When you run the node or
250+
generate proofs, the system will automatically fetch the required circuit data
251+
if it's not already available locally.
252+
236253
## Related Documentation
237254

238255
- [Proof System Overview](https://o1-labs.github.io/mina-rust/api-docs/ledger/proofs/index.html):

0 commit comments

Comments
 (0)