Skip to content

docs(circuits): rewrite ABOUT.md and kernel docs for the v6 circuit set - #25668

Draft
AztecBot wants to merge 4 commits into
v6from
cb/md-cleanup-10-noir-projects-docs
Draft

AztecBot wants to merge 4 commits into
v6from
cb/md-cleanup-10-noir-projects-docs

Conversation

@AztecBot

Copy link
Copy Markdown
Collaborator

v6 Markdown cleanup, PR 10 of 10. Owner / reviewer: Michael Connor (@iAmMichaelConnor). This is a flat PR against v6, independent of the other nine (any merge order works). Every edit traces to a finding in the Markdown audit (two-pass verified; report); the branch was reviewed against the code twice, before opening and again after (review notes, second review). Replaces #25644, which the stale-draft workflow closed automatically on 2026-10-19 after five days without updates; same branch, same commits, same description. Intended base is mc/md-cleanup; opened against v6 until that branch exists.

In one paragraph

Protocol circuit docs: ABOUT.md, accumulated_data.md, the components README, the bignum, bigcurve and blob crate READMEs, and the mock circuits README. Rewrites the stale sections from the Noir source and fixes two one-line script bugs found while checking the README commands (a jq path in flamegraph.sh; argument forwarding in the mock bootstrap.sh). No .nr file, Nargo.toml, or toolchain pin is touched, so the compiled circuits and their verification keys are unchanged.

What kind of changes (line counts)

Type Files Lines added Lines removed Notes
Markdown 9 485 1287
Shell/Python scripts (developer tooling) 2 2 2 flamegraph.sh: jq path .[] → .[].pattern; mock bootstrap.sh: "${1:-}" → "$@". Both developer tooling; neither changes what the circuit build produces.
Test fixtures 0 0 0 none
Production code (C++, Noir, Solidity, TypeScript, Rust) 0 0 0 none
Total 11 487 1289

Counts are git diff --numstat -M origin/v6...HEAD. "Code comments" means the only changed lines in that file are comment lines; the classification was checked line by line.

Files created, moved, renamed or deleted

Action Path Size Why
Deleted noir-projects/fnd/noir-protocol-circuits/crates/types/src/utils/arrays.md 87 lines, 3,500 B Merged into accumulated_data.md ("Claimed lengths and padding").

Verification keys and build artifacts

No circuit source (.nr, Nargo.toml), no C++/TypeScript/Rust/Solidity code, and no toolchain pin changes in this PR, so no verification key, proof, compiled contract or published package changes.

CI cache keys that change: noir-protocol-circuits (circuits_hash covers crates/**, bootstrap.sh and scripts/; matches 7 files: crates/bigcurve/README.md, crates/bignum/README.md, crates/blob/README.md, crates/private-kernel-lib/src/accumulated_data/accumulated_data.md, crates/private-kernel-lib/src/components/README.md, crates/types/src/utils/arrays.md, scripts/flamegraph.sh). The content hash for those components includes these files, so CI rebuilds them once and re-uploads byte-identical outputs. The rebuild is the only cost; nothing in the outputs changes.

Base branch and stacking

Flat PR against v6, not stacked: it does not depend on any other cleanup PR and no other cleanup PR depends on it. The ten PRs touch disjoint files.

If the target becomes next instead: every touched file is identical on v6 and next, and a dry-run rebase onto next (git merge-tree --merge-base=origin/v6 origin/next HEAD) applies cleanly.

Summary

The protocol-circuit docs described the pre-v6 circuit set. ABOUT.md listed first-block block roots, parity base/root, in_hash and a 6-entry checkpoint-root VK list, none of which exist. accumulated_data.md named six functions that do not exist and documented separate tail circuits. components/README.md said the output validator covers Init. The bignum, bigcurve and blob READMEs were vendored upstream text or dead personal notes. This PR rewrites the wrong sections from the Noir source (crates/, constants.nr, the ALLOWED_* globals), keeps the still-accurate tx-level sections and the per-circuit extras, and fixes three one-line script bugs found while checking the README commands. Reviewer: Michael.

Changes by file

  • noir-projects/fnd/noir-protocol-circuits/ABOUT.md — block, checkpoint and epoch sections rewritten for the v6 circuits (block-root / -single-tx / -no-txs, inbox-parity-S, checkpoint-root-single-block, checkpoint-padding, current ALLOWED_* lists, message bundles and sponge, epoch out hash tree); tree uses real crate names incl. init-N/inner-N/reset-tail; root heading, AVM VK, .sh name, BUG? markers fixed; tx-merge section written; shared checks defined once; source-of-truth pointers; author notes removed.
  • noir-projects/fnd/noir-protocol-circuits/README.md — noirup --version v1.0.0-rc.3 (+ noir-from-release.flag route); ../../../barretenberg bb path; ./bootstrap.sh generate_variants; flamegraph output dir; "Build outputs and VKs" section; Composer/hint/Builder definitions match the code; Further reading links.
  • .../private-kernel-lib/src/accumulated_data/accumulated_data.md — real Init helpers and constrained composer; read requests appended as-is, already scoped by the app (Init, Inner, table); Init-N/Inner-N section; Reset vs Reset-tail/-to-public; dense/trimmed checks attributed to previous_kernel_for_tail_validator; overview table moved to the top; arrays.md diagrams merged in, fenced and corrected.
  • .../types/src/utils/arrays.md — deleted; content merged into accumulated_data.md ("Claimed lengths and padding").
  • .../private-kernel-lib/src/components/README.md — output validator = Inner only, batch validator = Init-N/Inner-N, composer rows per circuit; 14 modules; pattern defined once in README.md; "Why This Pattern?" and box diagram replaced by one sentence.
  • .../crates/bignum/README.md, .../crates/bigcurve/README.md — short provenance notes citing commit 12182b58d17, the replaced tags, the path deps, and the bigcurve subgroup-check note.
  • .../crates/blob/README.md — what the library crate does, how to test it, how to profile it.
  • noir-projects/fnd/mock-protocol-circuits/README.md — removed the non-existent public-kernel section; lists the crates, build entry point, published package and consumer.

Non-Markdown files touched

  • noir-projects/fnd/noir-protocol-circuits/scripts/flamegraph.sh L126 — jq -r '.[]' → jq -r '.[].pattern'. chonk_circuits.json entries are {pattern, kind} objects, so no kernel matched and kernel flamegraphs used --scheme ultra_honk. bootstrap.sh and gates_report.sh already read .pattern.
  • noir-projects/fnd/mock-protocol-circuits/bootstrap.sh — forwards "$@" instead of "${1:-}", so ./bootstrap.sh compile <name> keeps the name. No-argument calls still reach build (ci3/source_bootstrap sets cmd=${1:-}). Nothing else in the script changes.

Removed-content ledger

ABOUT.md

  • Old tree entries init, inner, reset, tail, hiding, tail-to-public, hiding-to-public, parity base/root, block-root-first — dead (crates do not exist; constants.nr L116-117, L127-128). Replaced by the real crate list.
  • "Ping Mike if you want to make edits…" — personal note; the view-only fact is kept.
  • "simply because it was too cumbersome…" — reworded; the rule (justify validation in a composer with a comment) is kept.
  • Composer/validator definition L48-50 — now in README.md "Naming Conventions" (linked); it contradicted the code.
  • unravel_favourite_structs.js — wrong extension, now .sh.
  • Empty "Client-side proving" heading — replaced by pointers to the kernel docs.
  • tx-base-private L89 chain-state paragraph and the 5-item check list, repeated in tx-base-public L175-180 — now once under "Shared checks: Tx chain-state checks".
  • .finish() blob/out_hash bullets repeated in both tx-base sections — now once under "Tx effect absorption".
  • contract_class_log_fields description repeated in tx-base-public — replaced by "as for tx-base-private".
  • Hackmd link (4 links + 1 mention) — now once under "Blob batching", plus an in-repo pointer (crates/blob/src/abis/blob_accumulator.nr).
  • "It's always worth questioning seemingly missing checks, though!" — reworded to "confirm that the avm performs it".
  • "AVM_VK_INDEX in the vk tree" — false (types/src/proof/proof_data.nr L80-86: VK hard-coded in the verifier); replaced.
  • "block-root <-- BUG?" and block-root-first-single-tx bullets — false/dead (block_root_rollup.nr L17-18).
  • "Explanation todo." — replaced by a tx-merge section from tx_merge_rollup.nr.
  • Whole block-root-first* block, "Empty (block-root-first-empty-tx only)", "First (…) Validate the parity root proof / Inserts the poseidon2 version of the l1_to_l2_msg subtree", parity-base, parity-root sections — dead topology. Their surviving facts are restated: empty-block zero values and unchanged state (now block-root-no-txs), message insertion (now per block, "All variants"), parity (now inbox-parity-<S>).
  • "Empty spongeblob" for empty blocks — false: block-root-no-txs takes a witnessed start sponge blob, pinned by the checkpoint root or block merge.
  • checkpoint-root [u32; 6] list and the "single block … first block" notice — dead; replaced by the current 4- and 3-entry lists and the checkpoint-root-single-block section.
  • "That the left timestamp is <= the right timestamp. Note: blocks in the same checkpoint can have equal timestamps." — kept as a per-circuit extra but corrected: validate_consecutive_block_rollups asserts equal timestamps, so blocks in a checkpoint share one timestamp; strictly increasing across checkpoints is kept.
  • "right.in_hash == 0", "The in_hash cannot be empty", "Set the accumulated in_hash to simply be the left in_hash" and its two sub-bullets — false (checkpoint_rollup_public_inputs_composer.nr L78: block headers carry no in_hash). Replaced by the message-sponge equality and the parity rolling hashes.
  • "For the 'single' variants, that means verifying a single tx-base proof" (checkpoint-root) — wrong circuit type; the vk-list bullet is kept.
  • "TODO: incorporate this hackmd into a protocol spec." — author note; listed under Questions.
  • Second #### checkpoint-merge heading under #### root — copy-paste error.
  • "If the left subtree represents a single checkpoint, the right proof is a special 'padding proof'… The circuit checks the conditions" — restated precisely (right is padding ⇒ left holds exactly one checkpoint).
  • "See the blobs hackmd for more detail on what that means." (root) — covered by the single "Blob batching" pointer.
  • Blob-stuff list in checkpoint-root — kept verbatim except blob_fields → blobs_fields (code name) and the limit expressed via the constants.

README.md

  • noirup --version nightly-2026-01-13 — wrong pin; now v1.0.0-rc.3.
  • "Generate Nargo.toml from Nargo.template.toml: yarn && node ./scripts/generate_variants.js" — replaced by ./bootstrap.sh generate_variants, which runs exactly those two commands (bootstrap.sh L355-359); outputs now named.
  • "Maybe equivelently… injected just for performance reasons" — merged into the new hint definition ("makes a check cheaper").
  • Composer "is not constrained…" — false (compose_output_for_init, rollup TxBasePublicInputsComposer); replaced.
  • Builder "We want to remove this type of structs… (We currently use them in ...Composer structs)" and the open question — false/unresolved: Builder structs exist only in tests and protocol-test-utils (FixtureBuilder); the open question goes to Questions.

accumulated_data.md

  • Six non-existent function names (validate_incrementing_counters_within_range, validate_incrementing_call_request_counters_within_range, validate_propagated_from_initial_private_call, assert_array_appended_to_empty_dest_and_scoped, assert_array_appended_to_empty_dest, assert_array_appended_reversed_to_empty_dest) — dead; replaced by the real helpers.
  • "A protocol nullifier may be added if no nullifier hint is provided" — false (always at index 0).
  • "Optionally (in the final reset iteration)… In ResetOutputValidator in the final reset iteration" — the content is kept, moved under Reset-tail (siloing only runs there; constants.nr L129-134).
  • private_kernel_tail.nr, private_kernel_tail_to_public.nr titles — dead files; content kept under Reset-tail / Reset-tail-to-public.
  • "In TailOutputValidator / TailToPublicOutputValidator: assert_dense_trimmed_array…" — misattributed; now under validate_previous_kernel_for_tail with the exact per-array checks.
  • Overview table at the end — moved to the top and updated.

arrays.md (deleted; merged into accumulated_data.md "Claimed lengths and padding")

  • "(although it's only 600 constraints saved in the Kernel Inner)" — unverifiable, undated figure (finding: delete).
  • "length - unvalidated until the tail" — false (validate_claimed_lengths); corrected.
  • Final "out hint: [ a, b, d, f, p, p, p| 0]" — wrong order; corrected to [ b, f, a, d, …].
  • Everything else moved verbatim inside text fences.

components/README.md

  • "Initial values are correctly set from inputs" (validator) — false for Inner; Init has no validator.
  • "### Why This Pattern?" (Efficiency, Clarity, Security) — compressed to one sentence that keeps the efficiency and security points; "Clarity" dropped as non-factual.
  • Data-flow box diagram — restated by the composer/validator sentence.
  • "contain unconstrained functions… Run in unconstrained mode" — corrected (Init composer is constrained).
  • Composer/validator bullet lists ("Perform complex data transformations…", "Generate constraints…") — the facts are in the one-sentence summary and README.md's definitions.
  • "Tail, TailToPublic" circuit names — now the tail steps of Reset-tail / Reset-tail-to-public.

bignum/README.md (582 → 9 lines)

  • Upstream usage guide, API reference, install snippet (tag = "v0.4.2", wrong for a path dep), "930 gates for 2048-bit multiplication", single-limb caveat, and v0.3.0/v0.4.x benchmarks — upstream documentation; the README links upstream and says the code may differ. The description, BigNumParams, src/lib.nr and src/fields/ pointers are kept.

bigcurve/README.md (215 → 16 lines)

  • Upstream usage guide, curve list, examples, S = a*G + … example (which referenced a non-existent earlier example), "Feature requests" table row — upstream documentation, linked. Kept: the curve equation, BigCurveParams, the Overview's modular-reduction / constrained-unconstrained / lookup-table notes, the package-vs-import name, and the from_coordinates_unsafe / validate_in_subgroup note.

blob/README.md

  • nargo compile, bb gates … target/blob.json, noir-profiler commands, bbup install from master, nargo 0.33.0 / bb 0.48.0, ~/packages/… and ~/.bb/bb paths, "Current count: 428,240" — dead: blob is type = "lib", so no artifact exists (03 results L107-109). Replaced by nargo test and profiling via rollup_checkpoint_root. The "serve an existing flamegraph" python3 -m http.server step is covered by flamegraph.sh -s.

mock-protocol-circuits/README.md

  • "# Public Kernel / The folder public-kernel is currently used to test the noir integration of the avm recursive verifier." — dead (no such folder).
  • "IVC integration between noir and barretenberg" — reworded with the scheme names (Chonk, UltraHonk rollup).

Questions for the owner

  • blob README's constraint count (428,240) is removed. Re-measuring needs a build of a binary that links blob. Should a current figure for rollup_checkpoint_root be recorded somewhere?
  • bigcurve has no LICENSE file, and upstream noir_bigcurve main ships none either (raw LICENSE 404). Is bignum/LICENSE meant to cover it, or should a LICENSE be added?
  • ABOUT.md's Drive diagram predates the block-root/inbox-parity changes; the content was not inspected. Update it, or drop the link?
  • The blob-batching HackMD returns 403 anonymously. Is it public? The old ABOUT.md had a TODO to move it into a protocol spec.
  • README.md's Builder entry ended with an open question: "What is a new function allowed to do? Can it do array validation…". Is there a rule to write down?
  • private_kernel_circuit_output_composer.nr L1-8 still says "Generates the output for Private Kernel Init and Inner circuits (unconstrained)" and points to the README; compose_output_for_init is constrained. That comment is outside this PR's file list.

Not done

  • scripts/flamegraph.sh L105 [[ ! $ALLOW_NO_CIRCUIT_NAMES ]] is always false (dead guard), and -l lists .gz witness files as duplicate names. Not in this PR's script list.
  • flamegraph.sh does not treat hiding* circuits as Chonk (the hiding pattern lives only in bootstrap.sh), so hiding kernels still get --scheme ultra_honk. Fixing it is more than a one-line jq change.
  • The three artifacts READMEs (protocol-circuits-artifacts, protocol-contracts-artifacts, mock-protocol-circuits-artifacts) have findings in batch L but are not in this PR's file list.
  • A pointer from types/src/utils/arrays/claimed_length_array.nr's doc comment to the merged section would be a code-comment edit outside the file list.
  • ABOUT.md's tx-base composer/validator bullets were kept as written (the findings mark them accurate); they were not re-audited line by line.

Evidence

Findings: https://gist.github.com/AztecBot/48c4773b53be34ed390fd1cf692a1289 (batch 25-L-noir-projects.md). Verified commands: 03-command-test-results.md in the same gist. Report and PR plan: https://gist.github.com/AztecBot/a930919653a16ab8cd533c5f76b86b70. Noir pin checked: noir/noir-repo gitlink 5a7ee9bf = v1.0.0-rc.3; tools/bin/nargo --version reports 1.0.0-rc.3+5a7ee9bf. No nargo compiles were run.

Deliberately not changed

  • noir-projects/fnd/noir-protocol-circuits/bootstrap.sh L235 tests a literal string instead of the NOIR_PROTOCOL_CIRCUITS_SKIP_CHECK_WARNINGS variable, so the "Checking libraries for warnings" step never runs. The guard is still broken on both v6 and next. A fix exists on the branch cb/circuits-lib-warnings-check (public #25508, private aztec-packages-private#804), but both PRs were closed unmerged on 2026-09-17. That fix is a build-behaviour change (every circuits build runs nargo check --deny-warnings on the library crates, and it fails until the twelve library warnings it found are fixed), so it does not belong in a docs PR; reopen or re-land it on its own. This PR leaves L235 and the dead assignment on mock bootstrap.sh L5 alone.

Created by claudebox · group: slackbot · requested by Mike (@iAmMichaelConnor) · Slack thread

noir-protocol-circuits/ABOUT.md
- Rewrite the block, checkpoint and epoch sections from the code: block-root,
  block-root-single-tx and block-root-no-txs (each at any position in the
  checkpoint), inbox-parity-{4,16,64,256,1024}, checkpoint-root-single-block,
  checkpoint-padding, current ALLOWED_* lists, message bundles and the message
  sponge in place of in_hash, epoch out hash tree, MAX_BLOCKS_PER_CHECKPOINT.
- Fix the root section heading, the AVM VK claim, the .sh script name, and
  the tx-base next-circuit lists. Write the tx-merge section.
- Define tx chain-state checks, tx effect absorption and merge
  consecutiveness once; keep per-circuit extras (timestamp rules, blob
  challenge equality). Add source-of-truth pointers; remove author notes.

noir-protocol-circuits/README.md
- noirup v1.0.0-rc.3 and the noir-from-release.flag route; bb path depth;
  ./bootstrap.sh generate_variants; flamegraph output dir; Build outputs and
  VKs section; one Composer/Validator/hint definition that matches the code;
  Further reading links.

private-kernel-lib accumulated_data.md (absorbs types/src/utils/arrays.md)
- Real Init helper names and constrained composer; read requests appended
  as-is (already scoped by the app) in Init, Inner and the table; batched
  Init-N/Inner-N section; Reset vs Reset-tail/Reset-tail-to-public; dense and
  trimmed checks attributed to previous_kernel_for_tail_validator; arrays.md
  diagrams fenced, with the bounds-check and sorted-output corrections.

private-kernel-lib components/README.md
- Output validator = Inner only; batch validator = Init-N/Inner-N; Init
  composer constrained; all 14 modules; pattern defined in README.md.

bignum, bigcurve READMEs: short provenance notes citing 12182b5.
blob/README.md: what the library crate is and how to test it.
mock-protocol-circuits/README.md: actual crates, build entry point, consumer.

Scripts
- flamegraph.sh: read .pattern from chonk_circuits.json entries.
- noir-protocol-circuits/bootstrap.sh: test the variable, not a literal.
- mock-protocol-circuits/bootstrap.sh: forward all arguments and pass
  NOIR_PROTOCOL_CIRCUITS_SKIP_CHECK_WARNINGS to the call it controls.
Re-enabling the dead `nargo check` warnings step changes what every full
build runs and conflicts with cb/circuits-lib-warnings-check, which fixes
the same bug with --deny-warnings and the correct ordering. Keep only the
argument-forwarding fix in the mock-protocol-circuits wrapper.
@AztecBot AztecBot added ci-draft Run CI on draft PRs. ci-no-fail-fast Sets NO_FAIL_FAST in the CI so the run is not aborted on the first failure claudebox Owned by claudebox. it can push to this PR. labels Oct 19, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci-draft Run CI on draft PRs. ci-no-fail-fast Sets NO_FAIL_FAST in the CI so the run is not aborted on the first failure claudebox Owned by claudebox. it can push to this PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant