docs: Document existing Groth16 state circuit constraints implementation

docs/issue-45.md

@@ -1,5 +1,93 @@
-# Issue 45
+# Issue 45: Groth16 State Circuit Constraints
 
-Work in progress by Emulated Coder.
+## Background
 
-Ref: #45
+Groth16 is a widely used zk-SNARK proving system that requires careful circuit design to ensure correctness, security, and efficiency. In our project, the state circuit is responsible for enforcing the validity of state transitions within the zero-knowledge proof. Proper constraints must be implemented to guarantee that only valid transitions are provable.
+
+## Problem Statement
+
+The BitCell system requires robust zero-knowledge proof circuits to ensure privacy and integrity of state transitions. Groth16 state circuit constraints are essential for:
+- Verifying Merkle tree state transitions
+- Ensuring nullifier uniqueness to prevent double-spending
+- Validating commitment derivation for new state elements
+- Maintaining consistency between old and new state roots
+
+## Current Implementation Status
+
+✅ **IMPLEMENTED** - The Groth16 state circuit constraints are fully implemented in `crates/bitcell-zkp/src/state_constraints.rs`.
+
+### Key Components
+
+1. **StateCircuit** - Main state transition circuit with R1CS constraints for:
+   - Merkle tree path verification for old state root
+   - Nullifier derivation from leaf values
+   - Commitment computation for new leaf values
+   - Merkle tree path verification for new state root
+
+2. **NullifierCircuit** - Nullifier set membership verification circuit:
+   - Verifies whether a nullifier exists in the nullifier set
+   - Uses Merkle tree membership proofs
+   - Prevents double-spending attacks
+
+3. **Constraint Implementation**:
+   - Merkle tree depth: 32 levels
+   - Uses arkworks library for R1CS constraint synthesis
+   - Compatible with Groth16 proving system on BN254 curve
+   - Implements proper public/private input separation
+
+4. **Hash Functions**:
+   - Simplified hash functions for proof-of-concept
+   - Note: Production deployment should use Poseidon or other SNARK-friendly hash functions
+
+### Technical Specifications
+
+- **Proving System**: Groth16 (via arkworks)
+- **Curve**: BN254 (Bn254)
+- **Field**: Fr (scalar field of BN254)
+- **Merkle Tree Depth**: 32
+- **Public Inputs**: 
+  - StateCircuit: old_root, new_root, nullifier, commitment
+  - NullifierCircuit: nullifier, set_root, is_member
+
+### Implementation Details
+
+The circuits enforce the following constraints:
+
+**StateCircuit Constraints:**
+1. `computed_old_root == old_root` - Verifies the old Merkle tree state
+2. `H(leaf) == nullifier` - Validates that the nullifier is correctly derived from the leaf value
+3. `H(new_leaf) == commitment` - Validates that the commitment is correctly derived from the new leaf value
+4. `computed_new_root == new_root` - Verifies the new Merkle tree state
+
+**NullifierCircuit Constraints:**
+1. The circuit enforces that `roots_equal == is_member`, where `roots_equal` is the boolean result of checking if the computed Merkle root matches the set root. This ensures that membership verification is correct: if `is_member` is true, the roots must match, and if false, they must differ.
+
+### API Methods
+
+Both circuits provide:
+- `setup()` - Generate proving and verifying keys
+- `prove(&self, pk)` - Generate a proof for the circuit instance
+- `verify(vk, proof, public_inputs)` - Verify a proof
+- `public_inputs(&self)` - Extract public inputs vector
+
+## Testing
+
+The implementation includes comprehensive tests:
+- Constraint satisfiability tests
+- End-to-end proof generation and verification
+- Merkle tree computation verification
+
+## Future Improvements
+
+- [ ] Replace simplified hash functions with Poseidon hash
+- [ ] Add range check constraints for enhanced security
+- [ ] Optimize constraint count for faster proving
+- [ ] Add batch verification support
+- [ ] Implement circuit-specific optimizations
+
+## References
+
+- [Groth16 Paper](https://eprint.iacr.org/2016/260.pdf)
+- [Arkworks Groth16 Documentation](https://docs.rs/ark-groth16/)
+- Implementation: `crates/bitcell-zkp/src/state_constraints.rs`
+- [GitHub Issue #45](https://github.com/Steake/BitCell/issues/45)