Website: add circuits doc from handover

Author: dannywillems

website/docs/developers/circuits.md

@@ -0,0 +1,257 @@
+---
+sidebar_position: 4
+title: Circuit Generation and Management
+description: Circuit logic implementation and proof generation capabilities
+slug: /developers/circuits
+---
+
+# Circuit Generation and Management
+
+## Overview
+
+The Mina Rust node has ported the circuit logic from the Mina protocol, but with
+an important architectural distinction: the implementation only handles witness
+production, not constraint generation. This means that while the Mina Rust node
+can produce proofs using existing circuits, it cannot generate the circuit
+definitions themselves.
+
+For an overview of the proof system implementation in `ledger/src/proofs/`, see
+the
+[ledger crate documentation](https://o1-labs.github.io/mina-rust/api-docs/ledger/index.html).
+
+## Architecture
+
+### Proof Generation Implementation and Limitations
+
+The Mina Rust node codebase includes complete proof generation capabilities with
+one key limitation:
+
+**What the Mina Rust node Can Do:**
+
+- **Witness generation**: Full implementation for producing witnesses needed for
+  proof generation
+- **Proof production**: Complete capability to create proofs using pre-existing
+  circuit definitions
+- **Circuit logic**: Equivalent to the OCaml implementation for all proof types
+- **Proof verification**: Can verify proofs using precomputed verification
+  indices
+
+**What the Mina Rust node Cannot Do:**
+
+- **Circuit constraints**: Missing the constraint declarations from the OCaml
+  code that define circuit structure
+- **Constraint compilation/evaluation**: Missing the functionality to
+  compile/evaluate constraint declarations into circuit constraints
+- **Verification key generation**: Cannot generate verification keys for new
+  circuits
+
+**Practical Implications:**
+
+- Can generate proofs and witnesses for existing circuits
+- Cannot create new circuits or modify existing circuit definitions
+- Relies on OCaml implementation for all circuit creation and constraint
+  processing
+- Uses precomputed verification indices from the OCaml implementation
+
+The circuit logic is equivalent to the OCaml implementation except both the
+constraint declarations and the constraint compilation/evaluation functionality
+are missing - these were not ported due to time constraints during development,
+not technical limitations, and could be added for full independence.
+
+### Circuit Generation Process
+
+Since these constraint capabilities are missing, the Mina Rust node requires
+externally generated circuit data. The following process describes how circuits
+are created and distributed using the original Mina codebase:
+
+1. **Circuit Definition**: Circuits are defined using the OCaml implementation's
+   constraint system
+2. **Index Generation**: Verification and proving indices are generated from the
+   circuit definitions
+3. **Distribution**: Pre-generated indices are distributed for use by Rust nodes
+4. **Proof Generation**: The Mina Rust node uses these indices to generate and
+   verify proofs
+
+## Implementation Details
+
+### Witness Production
+
+The Mina Rust node implements complete witness production for all supported
+proof types:
+
+- **Transaction proofs**: Witness generation for user command verification
+- **Block proofs**: Witness production for blockchain state transitions
+- **Merge proofs**: Witness generation for proof aggregation
+- **Base proofs**: Witness production for foundational protocol operations
+
+### Proof Types Supported
+
+#### Transaction Proofs
+
+- User command verification
+- Payment and delegation transactions
+- zkApp account updates and state changes
+
+#### Blockchain Proofs
+
+- Block state transition verification
+- Consensus state updates
+- Protocol state evolution
+
+#### SNARK Work Proofs
+
+- Transaction SNARK generation
+- Proof merging and aggregation
+- Work verification
+
+### Circuit Data Management
+
+#### Verification Indices
+
+- Pre-computed verification keys from OCaml implementation
+- Distributed as binary data files
+- Loaded at runtime for proof verification
+
+#### Proving Indices
+
+- Pre-computed proving keys for proof generation
+- Large binary files stored separately
+- Lazy-loaded when proof generation is required
+
+## Performance Characteristics
+
+### Witness Generation
+
+- **Speed**: Comparable to OCaml implementation
+- **Memory Usage**: Efficient memory management during witness production
+- **Parallelization**: Some witness generation can be parallelized
+
+### Proof Production
+
+- **Throughput**: Supports concurrent proof generation
+- **Resource Usage**: CPU and memory intensive operations
+- **Optimization**: Optimized for production workloads
+
+## Integration with Protocol
+
+### Block Producer Integration
+
+- Seamless integration with block production pipeline
+- Automatic proof generation for produced blocks
+- Efficient witness caching and reuse
+
+### Transaction Pool Integration
+
+- On-demand proof generation for transactions
+- Batch processing for multiple transactions
+- Memory-efficient proof storage
+
+### Archive Integration
+
+- Proof verification for historical blocks
+- Efficient storage of verification results
+- Support for proof re-verification
+
+## Limitations and Future Work
+
+### Current Limitations
+
+#### Constraint System
+
+- Missing constraint declaration framework
+- No support for custom circuit creation
+- Dependent on OCaml implementation for new circuits
+
+#### Verification Key Generation
+
+- Cannot generate verification keys independently
+- Requires external tooling for circuit updates
+- Limited flexibility for protocol upgrades
+
+### Future Improvements
+
+#### Constraint Implementation
+
+- **Goal**: Port constraint declaration system from OCaml
+- **Benefit**: Full independence from OCaml implementation
+- **Effort**: Significant development work required
+
+#### Circuit Optimization
+
+- **Goal**: Rust-specific circuit optimizations
+- **Benefit**: Improved performance over OCaml version
+- **Effort**: Moderate development work
+
+#### Custom Circuit Support
+
+- **Goal**: Enable creation of custom circuits
+- **Benefit**: Support for protocol evolution and experimentation
+- **Effort**: Requires constraint system implementation first
+
+## Development Guidelines
+
+### Working with Circuits
+
+#### Adding New Proof Types
+
+1. Implement witness generation logic
+2. Define proof type structure
+3. Add integration points with existing systems
+4. Test with precomputed verification indices
+
+#### Optimizing Performance
+
+1. Profile witness generation bottlenecks
+2. Optimize memory allocation patterns
+3. Consider parallelization opportunities
+4. Benchmark against OCaml implementation
+
+#### Debugging Circuit Issues
+
+1. Use structured logging for witness generation
+2. Compare outputs with OCaml reference implementation
+3. Validate proof generation against known test vectors
+4. Monitor memory usage during proof production
+
+### Testing Strategy
+
+#### Unit Tests
+
+- Individual witness generation functions
+- Proof type serialization and deserialization
+- Circuit data loading and validation
+
+#### Integration Tests
+
+- End-to-end proof generation and verification
+- Performance benchmarks against OCaml
+- Memory usage validation
+
+#### Compatibility Tests
+
+- Cross-verification with OCaml-generated proofs
+- Protocol compliance validation
+- Regression testing for circuit changes
+
+## Related Documentation
+
+- [Proof System Overview](https://o1-labs.github.io/mina-rust/api-docs/ledger/proofs/index.html):
+  Technical implementation details
+- [SNARK Work](../researchers/snark-work): Protocol-level SNARK work
+  documentation
+- [Architecture Overview](architecture): Overall system architecture
+- [Performance Considerations](mainnet-readiness): Mainnet performance
+  requirements
+
+## Conclusion
+
+While the Mina Rust node successfully implements witness production and proof
+generation, the missing constraint system represents a significant dependency on
+the OCaml implementation. This architectural choice was made to accelerate
+initial development but represents an area for future enhancement to achieve
+full protocol independence.
+
+The current implementation provides sufficient functionality for mainnet
+operation while maintaining compatibility with the broader Mina ecosystem.
+Future work on constraint system implementation would enable full circuit
+independence and support for protocol evolution.

website/sidebars.ts

@@ -67,6 +67,7 @@ const sidebars: SidebarsConfig = {
       items: [
         'developers/why-rust',
         'developers/architecture',
+        'developers/circuits',
       ],
     },
     {