Skip to content

fix(docs): fable review#24005

Draft
critesjosh wants to merge 3 commits into
nextfrom
jc/docs/fable-review
Draft

fix(docs): fable review#24005
critesjosh wants to merge 3 commits into
nextfrom
jc/docs/fable-review

Conversation

@critesjosh

@critesjosh critesjosh commented Jun 10, 2026

Copy link
Copy Markdown
Contributor

Fixes the critical issues found in a full audit of the docs site, applied to both the source docs and the published v4.3.1 versioned docs (versioned facts verified against the v4.3.1 tag, source facts against next).

Tutorials

  • Counter tutorial (source + v4.3.1): adds the missing "clear the scaffold's placeholder test" note. As written, renaming the contract Main -> Counter leaves the generated counter_test crate referencing Main, so aztec compile fails with 6 errors (reproduced on a live local network). The token and recursive-verification tutorials already carry this note.
  • Token bridge tutorial (source + v4.3.1): the deploy script was inlined from the monorepo's CI example, and its artifact imports don't resolve in the Hardhat project the tutorial sets up. Adds a correction note (Hardhat artifact paths and bytecode vs Forge's bytecode.object), fixes the run command (npx tsx scripts/index.ts instead of npx hardhat run ... --network localhost, which targets a network the starter repo doesn't define), adds a note to update the starter repo's @aztec/l1-contracts tag (pinned to v4.2.0-aztecnr-rc.2; a v4.3.1 tag exists upstream), and fixes a broken relative link.

CLI references

  • aztec CLI reference (source + v4.3.1): the aztec start section was completely empty. Adds usage, examples, common options, and module flags (verified against aztec_start_options.ts), linking to the operator CLI reference for the full per-module list.
  • aztec-wallet CLI reference (source + v4.3.1): removes generator-machine leakage: --data-dir default /home/josh/.aztec/wallet -> ~/.aztec/wallet, --node-url default host.docker.internal -> localhost.

Operator docs

  • useful-commands / governance-participation (source + v4.3.1): the documented cast calls target functions that no longer exist on the governance contracts. M() -> ROUND_SIZE(), N() -> QUORUM_SIZE(), yeaCount(...) -> signalCount(...) (EmpireBase.sol), and proposals(uint256) (internal mapping) -> getProposal(uint256) (Governance.sol).
  • slashing-configuration (source + v4.3.1): the ejection description ("98% of activation, max 3 slashes") didn't match the implementation. Slashing ejection is driven by the rollup's localEjectionThreshold (190,000 on mainnet, 95% of the 200,000 activation threshold; StakingLib withdraws the entire remaining stake when a slash would cross it). Also fixes stale 36s-per-slot math (slots are 72s) and the "28 rounds on testnet" execution-delay label (28 rounds is mainnet). Source and v4.3.1 copies use their respective slash amounts (v4.3.1: all 2,000; next: 2,000/5,000 per AZIP-16).

Aztec.nr / foundational topics

  • events_and_logs (source + v4.3.1): self.context.emit_public_log(...) doesn't exist; corrected to emit_public_log_unsafe(tag, log) with a pointer to prefer self.emit(event).
  • state_variables / how_to_retrieve_filter_notes (source + v4.3.1): get_notes/remove documented around nonexistent RetrievedNote/HintedNote types; the actual return type is ConfirmedNote.
  • contract_structure (source + v4.3.1): claimed the storage struct "can have any name"; the #[storage] macro requires it to be named Storage.
  • contract_creation (source + v4.3.1): the "Proving Contract States" block used a nonexistent aztec::history::contract_inclusion module; replaced with the real aztec::history::deployment assert functions.
  • outbox.md (source only): parameter tables and getRootData signature updated to the checkpoint-based IOutbox (Epoch + _numCheckpointsInEpoch). The v4.3.1 copy matches its own interface and is untouched.

Spellcheck (yarn cspell) passes on all 514 files.

Fix critical issues found in a full docs audit, in both the source docs
and the published v4.3.1 versioned docs:

- counter tutorial: add the missing 'clear the scaffold placeholder test'
  note (renaming Main->Counter broke aztec compile with 6 errors)
- token bridge tutorial: correct artifact import paths and bytecode field
  for the Hardhat layout, fix the run command (npx tsx), add a note to
  update the @aztec/l1-contracts tag, fix a broken relative link
- aztec CLI reference: write the missing 'aztec start' section
- aztec-wallet CLI reference: remove leaked generator-machine defaults
  (/home/josh/.aztec/wallet, host.docker.internal)
- sequencer governance/slashing pages: replace removed contract getters
  (M/N/yeaCount/proposals -> ROUND_SIZE/QUORUM_SIZE/signalCount/getProposal),
  correct the ejection threshold description (rollup localEjectionThreshold,
  not '98% / max 3 slashes'), fix 36s->72s slot math
- aztec-nr docs: replace nonexistent APIs (emit_public_log ->
  emit_public_log_unsafe, RetrievedNote/HintedNote -> ConfirmedNote,
  history::contract_inclusion -> history::deployment), correct the Storage
  struct naming claim
- outbox.md (source only): update IOutbox signatures to the
  checkpoint-based interface
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.

1 participant