docs: update crisp circuit documentation#1132
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughRewrites CRISP documentation and README; refactors circuit docs and main Noir circuit (expanded public inputs and verification steps); adds constants and vote-validation helpers; updates verifier contract's embedded verification key data. No public API changes outside the circuit entry-point signature and new circuit helpers. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
docs/pages/CRISP/introduction.mdx(2 hunks)examples/CRISP/Readme.md(3 hunks)examples/CRISP/circuits/src/ciphertext_addition.nr(7 hunks)examples/CRISP/circuits/src/main.nr(5 hunks)
🧰 Additional context used
🧠 Learnings (8)
📚 Learning: 2025-08-25T10:28:56.174Z
Learnt from: ctrlc03
Repo: gnosisguild/enclave PR: 657
File: Cargo.toml:32-34
Timestamp: 2025-08-25T10:28:56.174Z
Learning: The examples/CRISP directory has its own Cargo.toml workspace configuration with members like "server", "wasm-crypto", "program/core", "program/client", etc. The root workspace intentionally excludes "examples/CRISP/server", "examples/CRISP/program", and "examples/CRISP/wasm-crypto" to prevent double workspace membership, which is the correct approach for self-contained example workspaces.
Applied to files:
examples/CRISP/Readme.mddocs/pages/CRISP/introduction.mdx
📚 Learning: 2025-11-05T14:12:57.814Z
Learnt from: ctrlc03
Repo: gnosisguild/enclave PR: 963
File: examples/CRISP/client/package.json:25-25
Timestamp: 2025-11-05T14:12:57.814Z
Learning: In the Enclave/CRISP codebase, `enclave-e3/sdk` and `crisp-e3/sdk` are different packages: `enclave-e3/sdk` is the general Enclave SDK, while `crisp-e3/sdk` is the CRISP-specific SDK. The CRISP client (`examples/CRISP/client`) intentionally depends on `enclave-e3/sdk`, not `crisp-e3/sdk`.
Applied to files:
examples/CRISP/Readme.mddocs/pages/CRISP/introduction.mdx
📚 Learning: 2025-11-12T10:08:30.720Z
Learnt from: ctrlc03
Repo: gnosisguild/enclave PR: 996
File: examples/CRISP/packages/crisp-contracts/contracts/CRISPProgram.sol:144-169
Timestamp: 2025-11-12T10:08:30.720Z
Learning: In the CRISP program (examples/CRISP/packages/crisp-contracts/contracts/CRISPProgram.sol), there are plans to move the merkle tree from the Enclave contract to the program contract itself in the future, which would allow direct calls to validateInput to be stored in the merkle tree.
Applied to files:
examples/CRISP/Readme.mddocs/pages/CRISP/introduction.mdx
📚 Learning: 2024-10-23T02:03:02.008Z
Learnt from: ryardley
Repo: gnosisguild/enclave PR: 156
File: packages/ciphernode/keyshare/src/encryption.rs:45-45
Timestamp: 2024-10-23T02:03:02.008Z
Learning: In the `packages/ciphernode/keyshare/src/encryption.rs` file, the environment variable `CIPHERNODE_SECRET` is used for the encryption password. A secure secret management solution is not currently available, but may be considered in future iterations.
Applied to files:
examples/CRISP/Readme.md
📚 Learning: 2024-10-08T19:45:18.209Z
Learnt from: ryardley
Repo: gnosisguild/enclave PR: 107
File: packages/ciphernode/sortition/src/distance.rs:1-1
Timestamp: 2024-10-08T19:45:18.209Z
Learning: In `packages/ciphernode/core/src/events.rs`, the import statements use the correct and updated `alloy::primitives` module.
Applied to files:
examples/CRISP/circuits/src/main.nr
📚 Learning: 2025-09-22T15:08:29.814Z
Learnt from: ozgurarmanc
Repo: gnosisguild/enclave PR: 734
File: packages/circuits/crates/libs/polynomial/src/lib.nr:140-155
Timestamp: 2025-09-22T15:08:29.814Z
Learning: Greco (packages/circuits/crates/libs/greco/src/lib.nr) performs range_check_1bound/2bounds on all polynomials (u, e0/e1, k1, pk*, r*, p*) before serialization; packer/flatten rely on these bounds, so per-limb asserts inside packer are unnecessary in this crate’s flow.
Applied to files:
examples/CRISP/circuits/src/main.nrexamples/CRISP/circuits/src/ciphertext_addition.nr
📚 Learning: 2025-08-27T13:49:48.617Z
Learnt from: 0xjei
Repo: gnosisguild/enclave PR: 648
File: examples/CRISP/circuits/src/main.nr:40-44
Timestamp: 2025-08-27T13:49:48.617Z
Learning: In CRISP circuits using Greco library, the binary check `assert(0 == b * (qmt - b))` for polynomial k1 should not be applied to all coefficients - only specific coefficients require this constraint, such as `k1.coefficients[2048 - 1]`.
Applied to files:
examples/CRISP/circuits/src/ciphertext_addition.nr
📚 Learning: 2025-12-19T11:35:43.204Z
Learnt from: ctrlc03
Repo: gnosisguild/enclave PR: 1109
File: examples/CRISP/server/src/server/routes/state.rs:33-37
Timestamp: 2025-12-19T11:35:43.204Z
Learning: In the CRISP voting system (examples/CRISP), ciphertext data and slot states are public and stored on-chain in the CRISPProgram smart contract. The server endpoints `/previous-ciphertext` and `/is-slot-empty` expose public blockchain data that can already be accessed by anyone through the contract's external view functions (getSlotIndex, isSlotEmptyByAddress) or by reading contract state directly. Authentication is not needed for these endpoints since they only expose data that is already publicly available on the blockchain.
Applied to files:
docs/pages/CRISP/introduction.mdx
🪛 LanguageTool
examples/CRISP/Readme.md
[style] ~144-~144: Consider shortening or rephrasing this to strengthen your wording.
Context: ...ploading Your Program to IPFS When you make changes to the guest program in program/, you ne...
(MAKE_CHANGES)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)
- GitHub Check: build_e3_support_dev
- GitHub Check: build_crisp_sdk
- GitHub Check: rust_integration
- GitHub Check: build_enclave_cli
- GitHub Check: test_net
- GitHub Check: rust_unit
- GitHub Check: build_sdk
- GitHub Check: integration_prebuild
🔇 Additional comments (19)
examples/CRISP/Readme.md (4)
11-32: LGTM! Clear and consistent project structure documentation.The project structure is well-organized with clear descriptions for each component. The structure diagram matches the one in
introduction.mdx, ensuring consistency across documentation.
47-90: Excellent comprehensive Quick Start guide.The Quick Start section now provides both an all-in-one approach (
pnpm dev:up) and individual component commands, giving users flexibility in their development workflow. The step-by-step breakdown of whatdev:updoes is particularly helpful for understanding the complete startup process.
105-166: Comprehensive configuration documentation with clear production guidance.The configuration section effectively covers both development and production scenarios. The Boundless configuration is detailed with all necessary requirements, and the IPFS upload workflow is clearly explained. This gives developers a complete understanding of how to move from development to production.
167-172: Clear explanation of environment configuration.The environment variables section effectively clarifies the distinction between
.envfiles (created from templates) andenclave.config.yaml(populated with contract addresses after deployment), which addresses previous confusion about configuration sources.docs/pages/CRISP/introduction.mdx (6)
14-48: Excellent introduction with consistent project structure.The updated introduction clearly establishes CRISP as a "full-stack implementation including frontend, backend, smart contracts, and zero-knowledge components," which helps readers understand the scope. The project structure diagram is consistent with the Readme.md, and the addition of the Enclave repository link provides easy access to the source code.
50-61: Clear and well-structured Client Application description.The client section effectively describes the key capabilities with appropriate cross-references to the SDK and coordination server sections. The feature list is comprehensive and easy to understand.
62-77: Excellent explanation of the Coordination Server's optional role.The section effectively communicates that the server acts as a facilitator and that clients can bypass it to interact directly with the blockchain. This flexibility is an important architectural feature that's well-documented here.
78-101: Well-documented FHE Program and Zero-knowledge Circuits with improved terminology.Both sections provide clear technical descriptions. The terminology has been appropriately updated to use "reduce the risk of collusion and coercion" (line 97), which is more accurate than the previous phrasing. The FHE Program section effectively explains the BFV homomorphic addition process, and the Zero-knowledge Circuits section comprehensively covers vote validation with a helpful link to the main circuit implementation.
102-126: Comprehensive Smart Contracts documentation.The Smart Contracts section effectively explains the complete voting lifecycle from initialization through tally decoding. The explanation of Merkle tree usage for efficient vote storage and the relationship between CRISPProgram.sol and CRISPVerifier.sol is particularly clear.
128-141: Thorough JavaScript SDK documentation.The SDK section comprehensively covers the complete workflow from round details fetching through result decoding. The mention of mask votes for reducing collusion/coercion risks and local proof verification to prevent failed transactions demonstrates attention to both security and user experience.
examples/CRISP/circuits/src/ciphertext_addition.nr (3)
7-41: Excellent documentation enhancement!The module-level documentation provides comprehensive context on the BFV ciphertext addition verification, including mathematical background, purpose in CRISP, and the verification strategy. This significantly improves code maintainability and understanding.
130-172: Well-documented verification strategy.The expanded documentation clearly explains the three-step verification process and the mathematical reasoning behind using the Schwartz-Zippel lemma with linear combinations. The explanation of correction/quotient terms is particularly helpful for understanding modular reduction in BFV ciphertexts.
184-267: Clear documentation of range constraints and evaluation verification.The documentation for
check_range_bounds()provides excellent intuition for why quotient coefficients must be in {-1, 0, 1} for M=2 ciphertext addition. Theverify_evaluations()documentation clearly describes the accumulator-based verification approach using challenge weights.examples/CRISP/circuits/src/main.nr (6)
20-45: Comprehensive circuit documentation.The main function documentation clearly explains the CRISP voting system, the two use cases (actual votes and mask votes), and the purpose of the Merkle tree for eligibility verification. This provides excellent context for understanding the circuit logic.
119-119: Critical assertion added for Merkle proof verification.The explicit
assert(merkle_root_calculated == merkle_root);ensures that the computed Merkle root matches the expected root, validating that the (slot_address, balance) pair exists in the eligibility tree. This is essential for security.
149-149: Critical assertion added for BFV encryption verification.The explicit
assert(greco.verify());ensures that the ciphertext is a valid BFV encryption of the plaintext under the provided public key. This is essential for cryptographic soundness.
160-171: Ciphertext addition verification object created unconditionally.The
CiphertextAdditionobject is instantiated for all cases, even though it's only needed for mask votes updating slots (checked at line 201). In zero-knowledge circuits, this unconditional computation is often necessary for circuit satisfiability, as all execution paths must be defined. However, verify this is the intended design pattern for this circuit framework.
173-205: Well-structured vote type detection and return logic.The return logic correctly handles both cases:
- Actual votes: Verifies balance constraint and returns new vote ciphertext
- Mask votes: Verifies zero vote, returns zero ciphertext for first votes or sum ciphertext for updates (with addition verification)
The assertions ensure cryptographic soundness in each path.
50-53: Current design is correct—no changes needed.The inputs
sum_ct0is,sum_ct1is,sum_r0is, andsum_r1isshould remain private witnesses. In zero-knowledge circuits, it is standard and intentional for private witness values to be verified in-circuit and then returned as public outputs. Making these inputs public would be unnecessary and inefficient, as verifiers do not need to provide them—they are computed by the prover during proof generation.
2 participants
Closes #1123
Summary by CodeRabbit
Documentation
New Features
Refactor
✏️ Tip: You can customize this high-level summary in your review settings.