docs: add documentation for circuits [skip-line-limit]

[0xjei]

Summary by CodeRabbit

Release Notes

• Documentation

  • Added comprehensive circuit specification documentation across all DKG, threshold, and recursive aggregation circuits with structured READMEs detailing circuit roles and inputs/outputs.
  • Introduced library structure documentation describing the Noir circuit layout, shared math utilities, configuration presets, and circuit mapping to protocol stages.
  • Enhanced source code documentation with improved module-level and inline comments clarifying circuit purposes and data flow.

• New Features

  • Added public center() function for field centering operations with documented behavior.

• Refactor

  • Renamed internal verification functions for clarity and consistency with protocol specifications.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
enclave-docs	Ready	Preview, Comment	Mar 30, 2026 9:39am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
crisp	Skipped		Mar 30, 2026 9:39am

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• ✅ Review completed - (🔄 Check again to review again)

📝 Walkthrough

Walkthrough

Adds extensive documentation across many circuits; implements a Configuration Verification circuit with many verify_* routines and a public center(raw, modulus) helper; removes DECRYPTED_SHARES_AGGREGATION_BIT_NOISE from configs/codegen and refactors decrypted-shares-aggregation into BigNum/Modular variants with new public constructors and execute APIs.

Changes

Cohort / File(s)	Summary
Documentation Expansions circuits/bin/config/README.md, circuits/bin/dkg/pk/README.md, circuits/bin/dkg/share_decryption/README.md, circuits/bin/dkg/share_encryption/README.md, circuits/bin/dkg/e_sm_share_computation/README.md, circuits/bin/dkg/sk_share_computation/README.md, circuits/bin/threshold/pk_generation/README.md, circuits/bin/threshold/share_decryption/README.md, circuits/bin/threshold/pk_aggregation/README.md, circuits/bin/threshold/decrypted_shares_aggregation_bn/README.md, circuits/bin/threshold/decrypted_shares_aggregation_mod/README.md, circuits/lib/src/README.md, circuits/bin/recursive_aggregation/fold/README.md, circuits/bin/recursive_aggregation/wrapper/README.md	Large README additions/replacements (C0–C7 naming, mermaid flowcharts, metadata). No behavioral/API changes.
Configuration Verification Circuit circuits/bin/config/src/main.nr	New orchestration and many verify_* routines for DKG / Threshold / user-data / cross-config checks; adds pub fn center(raw: Field, modulus: Field) -> Field; parity-matrix and cross-config consistency checks added.
Remove BIT_NOISE Config & Codegen circuits/lib/src/configs/insecure/threshold.nr, circuits/lib/src/configs/secure/threshold.nr, crates/zk-helpers/src/circuits/threshold/decrypted_shares_aggregation/codegen.rs	Deleted DECRYPTED_SHARES_AGGREGATION_BIT_NOISE public globals and stopped emitting it in codegen/tests.
Runtime Instantiation Updates circuits/bin/threshold/decrypted_shares_aggregation_bn/src/main.nr, circuits/bin/threshold/decrypted_shares_aggregation_mod/src/main.nr	Updated type instantiations/constructor calls to drop the BIT_NOISE generic/argument (now 3 generics instead of 4).
Decrypted Shares Aggregation — Core Refactor circuits/lib/src/core/threshold/decrypted_shares_aggregation.nr, crates/zk-helpers/src/circuits/threshold/decrypted_shares_aggregation/computation.rs	Replaced single BigNum impl with two public variants DecryptedSharesAggregationBigNum and DecryptedSharesAggregationModular; added q_inverse_mod_t in Configs, public new/execute and helpers (compute_all_lagrange_coeffs, compute_crt_components, verify_crt_reconstruction); removed noise field from Bits and simplified compute().
DKG Core API & Execution Surfaces circuits/lib/src/core/dkg/pk.nr, circuits/lib/src/core/dkg/share_computation.nr, circuits/lib/src/core/dkg/share_decryption.nr, circuits/lib/src/core/dkg/share_encryption.nr	Added pub fn new for Pk; added pub fn execute(self) -> [[Field; L]; N_PARTIES] for SecretKeyShareComputation and SmudgingNoiseShareComputation; share_encryption moved to commitment-based and batched verification; added public constructor for ShareDecryption; some public signatures updated to let-generic syntax.
Threshold Core Updates circuits/lib/src/core/threshold/pk_aggregation.nr, circuits/lib/src/core/threshold/pk_generation.nr, circuits/lib/src/core/threshold/share_decryption.nr	PK aggregation adds per-CRT-basis verification (verify_pk_for_basis); PK generation moved to commitment-based payload and single Fiat–Shamir gamma with Schwartz–Zippel batching; share_decryption docs/transcript order refined.
Build / Script Cleanup scripts/build-circuits.ts	Removed unused type import CircuitVariant. No runtime effect.

Sequence Diagram(s)

sequenceDiagram
    participant Operator as Operator
    participant Config as ConfigCircuit (main.nr)
    participant DKG as DKG subsystem
    participant Parity as ParityMatrix
    participant Threshold as Threshold subsystem
    participant Report as Report/Output

    Operator->>Config: supply parameter files & commitments
    Config->>DKG: verify_dkg_derived_values & verify_dkg_bounds
    DKG-->>Config: DKG verification results
    Config->>Parity: verify_dkg_parity_matrix
    Parity-->>Config: parity OK / fail
    Config->>Threshold: verify_threshold_derived_values & verify_threshold_bounds
    Threshold-->>Config: threshold verification results
    Config->>Config: verify_user_data_encryption_bounds & verify_cross_config_consistency
    Config->>Report: emit verification report / failures

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• feat: add parity matrix to config circuit [skip-line-limit] #1342: Overlaps config verification additions and center(raw, modulus) / parity-matrix verification.
• refactor: pk_generation circuit optimization #1353: Matches pk_generation changes (single gamma, commitment-based payload).
• feat: update circuits configs and benches [skip-line-limit] #1284: Overlaps removal/refactor of DECRYPTED_SHARES_AGGREGATION_BIT_NOISE and decrypted-shares-aggregation refactors.

Suggested reviewers

• cedoor

Poem

🐰
I hopped through circuits, lines to prune,
Took out a noisy constant by the moon.
READMEs bloomed and checks align,
New centers bind the modular line.
A rabbit cheers — the proofs look fine! 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: add documentation for circuits' clearly and accurately summarizes the main change: comprehensive documentation additions across multiple circuit modules and files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch circuits/docs

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}