docs(handover): Improvements to the proofs docs

Author: tizoc

docs/handover/circuits.md

@@ -8,28 +8,53 @@ production, not constraint generation. This means that while OpenMina 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
+[`ledger/src/proofs/summary.md`](../../ledger/src/proofs/summary.md).
+
 ## Architecture
 
-### Witness-Only Implementation
+### Proof Generation Implementation and Limitations
+
+The OpenMina codebase includes complete proof generation capabilities with one
+key limitation:
 
-The OpenMina codebase includes:
+**What OpenMina Can Do:**
 
 - **Witness generation**: Full implementation for producing witnesses needed for
   proof generation
-- **Proof production**: Capability to create proofs using pre-existing circuit
-  definitions
-- **Constraint generation**: NOT implemented - circuits must be generated
-  externally
-
-Due to time constraints during development, constraint generation was not ported
-to OpenMina. As a result, circuits must be generated using the original OCaml
-implementation.
+- **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 OpenMina 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 OpenMina cannot generate circuits, the raw circuit data must be produced
-using the OCaml implementation from the original Mina codebase. This process
-involves:
+Since these constraint capabilities are missing, OpenMina requires externally
+generated circuit data. The following process describes how circuits are created
+and distributed using the original Mina codebase:
 
 1. Using a custom branch in the OpenMina fork of Mina:
    https://github.com/openmina/mina

docs/handover/component-summaries.md

@@ -11,6 +11,9 @@ technical debt analysis and implementation notes.
     - [summary.md](../../core/summary.md)
   - **ledger/**
     - [summary.md](../../ledger/summary.md)
+    - **src/**
+      - **proofs/**
+        - [summary.md](../../ledger/src/proofs/summary.md)
   - **node/**
     - **src/**
       - [summary.md](../../node/src/summary.md)

docs/handover/ledger-crate.md

@@ -77,6 +77,9 @@ Note: The crate implements witness generation for circuits but not the
 constraint generation, so circuits cannot be fully generated from this crate
 alone.
 
+For detailed technical information about the proof system implementation, see
+[`ledger/src/proofs/summary.md`](../../ledger/src/proofs/summary.md).
+
 **zkApp Support** (`src/zkapps/`)
 
 - Full zkApp transaction processing

ledger/src/proofs/summary.md

@@ -0,0 +1,69 @@
+# Proofs Module Summary
+
+The proofs module handles zero-knowledge proof generation and verification for
+the Mina protocol using the Kimchi proof system. The implementation has proven
+to work reliably on devnet but contains many TODOs and probably cleanup.
+
+## Quick Reference
+
+**Core Proof Types**
+
+- `transaction.rs` - Transaction verification with witness generation
+- `block.rs` - Blockchain state transitions with consensus validation
+- `merge.rs` - Combining multiple transaction proofs
+- `zkapp.rs` - Smart contract execution proofs with authorization types
+
+**Infrastructure**
+
+- `witness.rs` - Witness data management (primary/auxiliary)
+- `caching.rs` - Verifier index and SRS caching
+- `constants.rs` - Circuit sizes and domain configurations
+- `step.rs`/`wrap.rs` - Step/wrap proof pattern for recursion
+
+## Implementation
+
+**Kimchi Integration**
+
+- Type aliases in `mod.rs` directly use Kimchi types for verifier/prover indices
+  and proofs
+- Circuit constraints and field operations built on Kimchi foundations
+- Maintains compatibility with Mina protocol proof formats
+- Uses a fork of proof-systems that is based on an older version than currently
+  used by OCaml implementation
+- Uses a fork of arkworks to considerably speed up field operations on WASM
+- See [#1106](https://github.com/o1-labs/openmina/issues/1106) for details on
+  these forks
+
+**Performance Features**
+
+- Caching system stores verifier indices and SRS data in `$HOME/.cache/openmina`
+- Circuit blobs for external circuit data fetching
+- Precomputed verification indices for devnet/mainnet in `data/` directory
+
+**Pickles Recursive Proof System**
+
+- The entire proofs module implements Pickles (recursive proof composition
+  system)
+- `step.rs`/`wrap.rs` provide the fundamental step/wrap recursion pattern
+- `public_input/prepared_statement.rs` handles different recursion levels (N0,
+  N1, N2)
+
+**Witness vs Circuit Split**
+
+- Witness generation handled in `witness.rs` with comparison functionality for
+  OCaml compatibility testing
+- Circuit logic implemented but lacks constraint declarations and
+  compilation/evaluation functionality
+- Uses precomputed verification indices from `data/` directory
+
+For details on missing constraint functionality and circuit management, see
+[`docs/handover/circuits.md`](../../../docs/handover/circuits.md).
+
+## Known Issues
+
+**Incomplete Functionality**
+
+- Joint combiner functionality has TODO items in `step.rs`
+- Feature flag handling incomplete in some verification paths
+- ZkApp call stack hash computation needs completion
+- Some field type conversions marked as temporary hacks