Skip to content

refactor(circuits)!: prove C4 one CRT limb at a time - #2533

Open
ctrlc03 wants to merge 13 commits into
large/c6-chonkfrom
large/c4-per-limb
Open

ctrlc03 wants to merge 13 commits into
large/c6-chonkfrom
large/c4-per-limb

Conversation

@ctrlc03

@ctrlc03 ctrlc03 commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

What and why

Split from #2398 (Zara's work). Stacked on #2532 (large/c6-chonk); review that one first.

At 28 honest parties C4 is a 2^24 circuit, over a node's 13 GiB per-job budget. Its openings and sums
are independent per CRT limb, and the aggregate commitment C6 reads is one SAFE sponge over the
normalized limbs in order. So this proves each limb separately and carries that sponge between them,
the way C2 is already proven as a chunk chain. The last limb squeezes the unchunked C4 commitment, so
C6 and every commitment link are unchanged.

  • share_decryption_limb_0/1/2 each run C4's statement for one limb (aggregate_limb: checked
    openings of the H dealer shares, sum, reverse and center) and continue the aggregate sponge from
    the state the previous limb left. Each limb starts at its own fixed sponge position, so every
    absorb position is static and each limb has its own circuit.
  • The final share_decryption circuit verifies the three limb proofs, each with its own key, links
    them from the fresh sponge (DS_SHARE_DECRYPTION_CHAIN_STATE) and returns the aggregate commitment
    then the hash of the limb keys.
  • c4ab_fold folds that key hash into its own key hash next to the C4 key, and the VK tree's C4 node
    is hash(C4, C4 chain, C4, C4 chain), so the anchor pins every limb circuit. A peer verifying a C4
    directly compares the key tree with its own limb keys (zk_verify_share_proof_bundle, secret-shared
    profile only; the synchronized C4 stays a single circuit).
  • The C4 output layout gains a trailing key_tree field. The C4→C6 links extract commitment by
    name from the tail, so they still find it. The C2→C4 link's row bound now requires both C4 outputs
    (aggregate commitment and key tree) after a row.
  • The limb circuits are proven non-ZK and only verified inside the final circuit, so the build
    publishes them in the default variant alone, as it does the C2 chunks. required-artifacts.json
    lists them.
  • aggregate_limb (one limb, opening the C2 commitments) and the synchronized C4
    (aggregate_canonical_shares) share the per-limb arithmetic (aggregate_canonical_limb), so
    there is one definition of the sum, reverse and center step.
  • Benchmarks gain the three limb cases and prove the final C4 through the chain.
  • node_fold, nodes_fold and nodes_fold_kernel call the length c4ab_fold passes on
    C4_FOLDED_LEN, now one field shorter than c4ab_fold::C4_PUBLIC_LEN, as they already do for C2.

Verification

Per the current stack policy, tests are not run here; CI runs them. Static checks run on this branch:

  • nargo check and nargo compile of the dkg, recursive_aggregation and synchronized circuit
    workspaces; scripts/circuits/lint.sh.
  • cargo check -p e3-zk-config -p e3-zk-witness -p e3-zk-build -p e3-zk-prover -p e3-zk-benchmarks --all-targets
    and cargo check --workspace --all-targets, which only fails in the e3-evm, e3-evm-client and
    e3-indexer tests for missing generated contract bindings; cargo fmt --all --check.
  • prettier --check on the changed Markdown and JSON.
  • node scripts/blueprint/check.mjs (without --fix) moves no reference relative to main.

Tests this change adds or extends, for CI:

  • nargo test in circuits/lib: limb_chain_equals_the_unchunked_c4_commitment (the three limb
    steps, chained, return the unchunked C4 commitment) and the chain's tamper tests.
  • cargo test -p e3-zk-witness --test dkg_samples:
    limb_chain_aggregate_equals_the_unchunked_commitment pins that the limb chain's aggregate equals
    the unchunked C4 commitment on a real sample.
  • -p e3-zk-config --test circuit_identity, -p e3-zk-build, the C4/C6 commitment link tests, and
    the C4 cases of local_e2e_tests and node_fold_correlated_e2e_tests.
  • The layout locks (-p e3-net --lib layout_lock, -p e3-slashing --lib layout_lock,
    -p e3-zk-prover --lib layout_lock, -p e3-tests --test layout_lock) gain rows for the three new
    CircuitName variants. They are not regenerated on this branch.

Compatibility

Breaking within the unreleased protocol-9 cutover (no separate counter change): drain-and-resync.

  • The C4 circuit, c4ab_fold and the VK tree's C4 node change, with them every nodes-tree anchor and
    the DKG wrapper (BfvPkVerifier). The C6 tree and the decryption wrapper do not depend on C4. The
    deployed verifiers and artifacts from before this change do not accept the new proofs; drain
    first. Rollback: drain, then restore the previous binary and artifacts.
  • The C4 commitments are unchanged, so C6 and the commitment-consistency links need no change. The
    C4 public output gains one trailing field (the limb key tree).
  • Storage schema and gossip/sync majors are unchanged. CircuitName::DkgShareDecryptionLimb0/1/2 are
    appended after the existing variants, so stored encodings keep their indices. Limb proofs are never
    persisted or gossiped.
  • The VK catalogue (circuits/vk-commitments.json), the Solidity verifiers, the BFV VK-binding
    fixture and the layout-lock fixtures are regenerated once, from one matrix build, in chore(circuits): regenerate the circuit outputs of the large stack #2541 (large/circuit-outputs), near the top of
    the stack. Until then this PR's circuit, verifier and layout-lock checks
    fail by design.

@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
interfold-dashboard Ready Ready Preview Nov 20, 2026 9:49am UTC
interfold-docs Ready Ready Preview Nov 20, 2026 9:49am UTC

Request Review

@coderabbitai

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 2 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

Commits

Reviewing files that changed from the base of the PR and between d0177de and f7c2a0e.

Files selected for processing: 60

  • circuits/README.md
  • circuits/benchmarks/config.json
  • circuits/bin/dkg/Nargo.toml
  • circuits/bin/dkg/share_decryption/Nargo.toml
  • circuits/bin/dkg/share_decryption/README.md
  • circuits/bin/dkg/share_decryption/src/main.nr
  • circuits/bin/dkg/share_decryption_limb_0/Nargo.toml
  • circuits/bin/dkg/share_decryption_limb_0/src/main.nr
  • circuits/bin/dkg/share_decryption_limb_1/Nargo.toml
  • circuits/bin/dkg/share_decryption_limb_1/src/main.nr
  • circuits/bin/dkg/share_decryption_limb_2/Nargo.toml
  • circuits/bin/dkg/share_decryption_limb_2/src/main.nr
  • circuits/bin/recursive_aggregation/c4ab_fold/src/main.nr
  • circuits/bin/recursive_aggregation/node_fold/src/main.nr
  • circuits/bin/recursive_aggregation/nodes_fold/src/main.nr
  • circuits/bin/recursive_aggregation/nodes_fold_kernel/src/main.nr
  • circuits/lib/src/README.md
  • circuits/lib/src/core/dkg/mod.nr
  • circuits/lib/src/core/dkg/share_decryption.nr
  • circuits/lib/src/core/dkg/share_decryption_chain.nr
  • circuits/lib/src/math/commitments.nr
  • crates/zk/benchmarks/src/circuit_benchmark/artifacts.rs
  • crates/zk/benchmarks/src/circuit_benchmark/inputs.rs
  • crates/zk/benchmarks/src/circuit_benchmark/leaf.rs
  • crates/zk/benchmarks/src/circuit_benchmark/selection.rs
  • crates/zk/benchmarks/src/circuit_benchmark/tests.rs
  • crates/zk/build/src/artifacts.rs
  • crates/zk/build/src/tests.rs
  • crates/zk/build/src/vk_tree.rs
  • crates/zk/config/src/circuit.rs
  • crates/zk/config/src/output_layout.rs
  • crates/zk/config/tests/circuit_identity.rs
  • crates/zk/prover/required-artifacts.json
  • crates/zk/prover/src/circuits/aggregation/c2_chain.rs
  • crates/zk/prover/src/circuits/aggregation/c4_chain.rs
  • crates/zk/prover/src/circuits/aggregation/chain_keys.rs
  • crates/zk/prover/src/circuits/aggregation/mod.rs
  • crates/zk/prover/src/circuits/dkg/share_decryption.rs
  • crates/zk/prover/src/commitment_links/c2_to_c4/mod.rs
  • crates/zk/prover/src/commitment_links/c2_to_c4/tests.rs
  • crates/zk/prover/src/commitment_links/c4a_to_c6.rs
  • crates/zk/prover/src/commitment_links/c4b_to_c6.rs
  • crates/zk/prover/src/lib.rs
  • crates/zk/prover/src/request_execution.rs
  • crates/zk/prover/src/request_execution_tests.rs
  • crates/zk/prover/tests/common/helpers.rs
  • crates/zk/prover/tests/local_e2e_tests.rs
  • crates/zk/prover/tests/node_fold_correlated_e2e_tests.rs
  • crates/zk/witness/src/commitments.rs
  • crates/zk/witness/src/dkg/mod.rs
  • crates/zk/witness/src/dkg/share_decryption_chain.rs
  • crates/zk/witness/tests/dkg_samples.rs
  • docs/architecture/proof-statements.md
  • docs/pages/build/noir-circuits.mdx
  • docs/pages/internals/commitment-consistency.mdx
  • docs/pages/internals/dkg.mdx
  • scripts/blueprint/curated.mjs
  • scripts/blueprint/facts/05-zk.json
  • scripts/blueprint/facts/11-circuits.json
  • scripts/blueprint/refs/D-circuits.json
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Architecture change

From 044ea8c97 to f7c2a0e70. Open this change in the blueprint: green is new, red is removed and yellow is changed, and a number on a box counts the changes inside it.

Experimental. The page goes away when the pull request closes. scripts/blueprint/diff/README.md says how to turn it off or remove it.

zahrajavar and others added 5 commits November 20, 2026 09:38
…ommitments

At 28 honest parties C4 is a 2^24 circuit, over a node's 13 GiB per-job
budget. Its openings and sums are independent per limb, and the aggregate
commitment C6 reads is one SAFE sponge over the normalized limbs in order,
so prove each limb separately and carry that sponge between them. The last
limb squeezes the unchunked C4 commitment; C6 is unchanged.

- aggregate_limb holds C4's per-limb statement (checked openings, sum,
  reverse and center); the unchunked execute and the limb circuits share
  it.
- share_decryption_limb_0/1/2 each start the aggregate sponge at their
  limb's fixed position, so every absorb position is static. The final
  share_decryption circuit verifies the three limbs, links them from the
  fresh sponge and returns the aggregate commitment, then the limb key
  tree.
- c4ab_fold and the VK tree anchor the key tree; peers check it when
  verifying a C4. The C4 output layout names the trailing key tree.
- The limb circuits are published in the default variant only, as the C2
  chunk circuits are.
- The circuit identity lock gains rows for the limb circuit names,
  appended after the existing variants.
…length

C4 now also outputs its key tree, so c4ab_fold's C4_PUBLIC_LEN is one
field more than what the fold passes on. The node and nodes folds call
their length C4_FOLDED_LEN, as they already do for C2.
…anchor test

The limb keys are VK_PATHS 29..=31; 25..=28 are the C6 Chonk keys, so the
expected node tree used the wrong keys and the mutation loop counted the
limb keys as C6 descendants.
The peer C4 handler now checks the final C4's limb key tree. Run the
key-tree test over C4 as well as C2, so a regression to the bare
outer-proof check fails.
No circuit calls ShareDecryption::execute since C4 is proven per limb; only
the chain test used it as its oracle. Keep C4's role as module docs, take
the one-shot commitment from aggregate_canonical_shares in the test, and
point the blueprint at the limb statement and the chain check.
The final C4 returns its limb key tree after the aggregate commitment. Say
so in the link's layout and row comment, and end the C4 test signals with
a key tree as a real final C4 does.
Naming C4_FOLDED_LEN added two lines to node_fold, nodes_fold and
nodes_fold_kernel, which left ten blueprint references two lines short.
chunk_circuits returns the C4 limb circuits too, so the comment that named
only C2 chunks was stale.
The final C4 proof now ends on two outputs (the aggregate commitment, then the limb key tree), but the C2-to-C4 row bound still asked for one field after the row. With one modulus the row one past the roster passed the bound and compared C2's commitments with C4's aggregate. Unreachable today (three moduli, roster-mapped rows); the bound is exact again.
…selection

The benchmark configuration lists share_decryption_limb_0/1/2 for both modes, so the default selection has 18 secure and 17 insecure cases.

This branch was successfully deployed

3 active deployments
Preview – interfold-dashboard — f7c2a0e7 Deployed Nov 20, 2026 by vercel[bot]
Preview – interfold-docs — f7c2a0e7 Deployed Nov 20, 2026 by vercel[bot]
github-pages — f7c2a0e7 Deployed Nov 20, 2026 by ctrlc03 via Publish the previews #1284
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants