docs: regenerate the aztec.js API reference - #25248
Conversation
Two bugs made a regeneration of the aztec.js API reference unlandable, which is part of why the committed reference had not been refreshed since December. The generator emitted multi-line types inside inline code spans. A type body containing a blank line closes the span early, leaving its braces and angle brackets to be parsed as MDX expressions and JSX tags, so the page no longer compiled and the docs build failed. Emit a fenced code block for multi-line types instead, matching what format_return_type already did, and collapse destructured parameter names onto one line. The table of contents also built anchors with its own slug logic, which stripped underscores that Docusaurus keeps. That left CAPABILITY_VERSION and the Contract / Protocol_Contracts section unreachable, and pointed NO_WAIT and NO_FROM at the NoWait and NoFrom headings instead. Derive the anchor from the rendered heading text the way github-slugger does. Also fix the aztec.js JSDoc that a regenerated reference trips cspell on: a "metadata" typo and the repo-flagged "on-chain" spelling.
Last generated on 2025-12-10, so the committed reference had drifted a long way from the source: 19 documented symbols no longer exist in aztec.js (including getGasLimits, which moved to the wallet SDK) and 82 current exports were missing entirely.
8af03a9 to
d1cee8c
Compare
…ecjs-reference-regen
The parser walked subdirectories in fs.readdirSync order and sorted files with localeCompare, so the module and file order in the generated page depended on the filesystem and on the runtime's locale data: the same sources produced a different page on macOS and on Linux. Sort both by code unit. Reversing every readdir now leaves the regenerated page identical apart from its timestamp.
Nine public members had no return annotation, so the generated API reference documented them through the type checker. Write the types out. They are the types the checker already reported, except waitForProven, which becomes Promise<BlockNumber> rather than retryUntil's Promise<NonNullable<BlockNumber>>.
The parser resolved @aztec/* imports, so an inferred return type depended on which sibling packages the environment had built: a page generated against a full build silently differed from one generated against a partial build, and the difference only surfaced in CI. Resolve relative imports only, so the page is a function of the aztec.js sources and nothing else. Types that cross a package boundary now have to be annotated in the source. Parsing also drops from ~50s to ~8s, since the checker no longer reads the workspace's declaration files.
| # Punctuation that github-slugger, which Docusaurus uses for heading anchors, drops. | ||
| SLUG_PUNCTUATION = set("\\'!\"#$%&()*+,./:;<=>?@[]^`{|}~") | ||
|
|
||
| def heading_anchor(self, heading_text: str) -> str: |
There was a problem hiding this comment.
heading_anchor doesn't model github-slugger's duplicate counter, so four TOC links land on the wrong heading:
| TOC link | Lands on | Should be |
|---|---|---|
[Fee](#fee) |
L1536 ##### fee, mid-Contract |
L4029 ## Fee = #fee-4 |
[Account](#account) |
L225 ## Account, the folder |
L267 #### Account = #account-1 |
[Contract](#contract) |
L647 ## Contract |
L877 #### Contract = #contract-1 |
[Wallet](#wallet) |
L5131 ## Wallet |
L6735 #### Wallet = #wallet-1 |
The other 190 links resolve correctly.
Should the slugger keep a per-slug count? It has to run over every heading in document order, including the ##### fee method headings the TOC never links to, since those are what push ## Fee out to #fee-4.
There was a problem hiding this comment.
Fixed in d5db925. Every heading claims its anchor in document order and the contents are built from the claimed anchors, so all four links land on the intended section. generate() also now verifies its headings, so a heading written as a plain string should break the build instead of silently misdirecting links.
| ### `contract/protocol_contracts/contract-class-registry.ts` | ||
|
|
||
|
|
||
| #### ContractClassRegistryContract |
There was a problem hiding this comment.
Was the page generated before the merge-train/fairies merge? Rerunning update_docs.sh current at this commit adds the static withWallet methods on ContractClassRegistryContract, ContractInstanceRegistryContract and FeeJuiceContract, and nothing else changes apart from the *Generated:* timestamp.
Worth doing, because the page currently doesn't mention them at all: parse_typescript.js drops jsdoc that is only a tag, so the @deprecated marker on at() doesn't survive either and at() renders with an empty description. Readers get a deprecated method presented as the only entry point.
| Formatted markdown string for the labeled type | ||
| """ | ||
| if '\n' in type_str: | ||
| return f"**{label}:**\n\n```typescript\n{type_str}\n```\n" |
There was a problem hiding this comment.
Nit: verify_docs.py's type-label regex needs the type on the same line, so the new multi-line branch makes it report 3 extra "missing **Type:** label" warnings, at the #### Properties sections on L3152, L3236 and L3334. There are 8 bare **Type:** lines in total, but the other four sections holding one also carry a single-line **Type:**, so they still pass. Should the regex learn about the fenced form while you're here? Just checking, it's warning-only and the script isn't in CI.
There was a problem hiding this comment.
We now get the following when running verify_docs.py:
Verifying docs/docs-developers/docs/aztec-js/aztec_js_reference.md...
✅ All checks passed! Documentation is production-ready.
| """ | ||
| slug = heading_text.lower().strip() | ||
| slug = ''.join(c for c in slug if c not in self.SLUG_PUNCTUATION) | ||
| return slug.replace(' ', '-') |
There was a problem hiding this comment.
Now that the TOC uses heading_anchor, is slugify still used? The three remaining calls (131, 192, 258) all assign to a local that's never read, and it produces different anchors than heading_anchor does, so leaving it around might cause someone to pick the wrong one. Should we drop it?
There was a problem hiding this comment.
yup slugify is removed and they are different than the new slug introduced here. updated
yarn-project/aztec.js/src/contract/protocol_contracts is gitignored build output, generated from the compiled Noir protocol contracts. Documenting it made the page depend on noir-projects: a checkout cannot regenerate or verify the reference without those artifacts, and a change to a protocol contract left the committed page stale. The page now covers 8 modules and 182 exports, and generating it with that directory absent produces the same bytes.
check_section_structure treated every H4 as an export, but the generator emits Constructor, Properties, Methods, Getters and Setters as H4 groups alongside them, so all 54 warnings on the aztec.js reference were groups with no Type label of their own. It also asked every export for a Signature, which only functions and type aliases are documented with. Skip the member groups, expect a signature only from the kinds that have one, share the fence tracking so a multi-line type's contents are not read as labels, and check the last section instead of dropping it when the file ends. The aztec.js reference now passes clean, so a real regression is visible instead of being buried.
Docusaurus keeps heading anchors unique by appending -1, -2 and so on, searching for an anchor no
earlier heading has taken. The table of contents computed anchors from the heading text alone, so
four of its links pointed at whichever heading claimed the bare slug first: Fee reached a fee method
rather than the module, and Account, Contract and Wallet reached their folder rather than their
class. Nothing catches this, because the links resolve, just to the wrong section.
Port the suffix search, claim each anchor as its heading is rendered, and build the contents from
what the body claimed. Generating a heading as a plain string would leave the contents wrong again
in the same silent way, so generate() now checks the rendered document against the anchors that were
claimed. This also removes slugify, which produced different anchors and whose three callers already
ignored its result.
Alongside that, two things the reference did not say: an export deprecated by a doc comment carrying
nothing but the tag rendered as though nothing were wrong with it, and `export { x }` with no `from`
rendered as a re-export from an empty module.
hermeticCompilerHost resolved relative imports, which is not hermetic; name it relativeImportsOnlyHost. Also spell out in the README why a heading written as a plain string is silent (the link resolves, to the wrong section) and how generate() catches it.
Stacked on #25248, which regenerates the page. The aztec.js reference sat eight months out of date because nothing watched it. Docs CI never regenerated or diffed it (`docs/bootstrap.sh` only builds and spellchecks). The release checklist regenerates the aztec-nr API, the TypeDoc TypeScript API and the three CLI references but not this one. The v5.1.0 release refreshed all of those in the same commit and left this page on its December content. Two changes so it cannot happen again: - `update_docs.sh --check` regenerates into a temp file and diffs it against the committed page, ignoring the generation timestamp the page stamps into itself. `docs/bootstrap.sh` gains a `check_generated_refs` step, so a change to `yarn-project/aztec.js/src` that alters the reference cannot land without the regenerated page. It skips on arm64 CI, matching `build_docs` and `test_cmds`. ### Verification - Red: with the December page restored in the working tree - Green: on this branch it exits 0 (`✓ Reference matches aztec.js`), and the temp files are cleaned up. - Scoped deliberately to this one artifact. The CLI references are generated from the installed dockerized release CLI rather than from the working tree, and the aztec-nr and TypeDoc references are release-pinned. The node JSON-RPC reference does regenerate byte-identically from source today, so it would be a cheap second candidate if we want one.
… rename (#25270) Fixes the `docs` job on `merge-train/fairies` ([failing run](http://ci.aztec-labs.com/1787129975967580), [docs log](http://ci.aztec-labs.com/9e1fa3ea2d75498d)). ## What broke The `check generated aztec.js reference` step added by #25249 fires on its own merge commit: ``` - node: Pick<AztecNode, 'getBlockData' | 'getL1ToL2MessageCheckpoint'>, committed page + node: Pick<AztecNode, 'getBlockData' | 'getL1ToL2MessageIndex'>, regenerated from source ``` Three commits in this order: | When (UTC) | What | | --- | --- | | Aug 18 16:45 | #25248 (`88bcee5650d`) regenerated `aztec_js_reference.md`. aztec.js used `getL1ToL2MessageCheckpoint` then, so the page recorded `Checkpoint`. | | Aug 18 21:04 | #25258 (`88426665a33`, merge-train/spartan) renamed the API back to `getL1ToL2MessageIndex` in `stdlib/src/interfaces/aztec-node.ts` and `aztec.js/src/utils/cross_chain.ts`, without touching the page — nothing forced it to, the check did not exist yet. | | Aug 19 08:59 | #25249 (`42a048d1a2c`) squash-merged into `merge-train/fairies`, which already contained #25258. | #25249's own CI was green because CI3 runs on the PR head, not on a merge with the base ([run 32234449928](https://github.com/AztecProtocol/aztec-packages/actions/runs/32234449928), `head_sha 56d47aa`): on that tree `cross_chain.ts` still said `Checkpoint`, so page and source agreed. The rename only meets the stale page at merge time — a semantic merge conflict a head-only CI cannot see. The check is doing exactly its job; the page really did document an export signature that no longer exists. ## This change Output of the documented regeneration command, nothing hand-edited: ``` cd docs && ./scripts/aztecjs_reference_generation/update_docs.sh current ``` Six lines: the three `getL1ToL2MessageCheckpoint` → `getL1ToL2MessageIndex` occurrences in `waitForL1ToL2MessageReady` / `isL1ToL2MessageReady` (signature block plus parameter list), and the `Generated:` timestamp the page stamps into itself. `--check` ignores that timestamp, so it is cosmetic here. Verified locally on this branch: `./scripts/aztecjs_reference_generation/update_docs.sh --check` exits 0 with `✓ Reference matches aztec.js` (it fails on the branch tip without this commit). ## Note for `next` The same drift is already sitting on `next`: the page there has `getL1ToL2MessageCheckpoint` while `aztec-node.ts` has `getL1ToL2MessageIndex`. `next` just does not have `check_generated_refs` in `docs/bootstrap.sh` yet — that arrives with this train. So `next`'s docs job starts failing the moment the fairies train merges unless this regeneration rides along with it. --- *Created by [claudebox](https://claudebox.work/v2/sessions/9e5a3b3c6fb75454/jobs/2) · group: `slackbot` · requested by Maxim Vezenov · [Slack thread](https://aztecprotocol.slack.com/archives/C0BFRKFSLMP/p1787130402250539?thread_ts=1787130402.250539&cid=C0BFRKFSLMP)*
## Summary Publishes `v5.2.0` as the shared release for both **Alpha (Mainnet)** and **Testnet** across developer and network/operator documentation, and removes the deprecated `v5.1.0` snapshots. - both `mainnet` and `testnet` selectors resolve to the same `v5.2.0` snapshot - developer and network/operator snapshots cut from the `v5.2.0` tag (`49a592109ec`), so `#include_code` snippets and version macros freeze against what shipped - Aztec.nr, TypeScript, Aztec.js, `aztec` / `aztec-wallet` / `aztec-up` CLI, operator `aztec start` CLI and Node JSON-RPC references all regenerated at the tag - identical generated API artifacts under the stable `mainnet` and `testnet` paths - `networks.md` re-derived from the node RPCs and on-chain reads A backport of this release into `v5-next` is [#25265](#25265). ## Merged `next` (2026-08-19) `next` moved 64 commits while this was open. Merged and resolved; `yarn build` re-run green on the merged tree. Two conflicts, both around the Aztec.js reference: - `docs/scripts/aztecjs_reference_generation/transform_to_markdown.py` — **took `next`'s version wholesale.** [#25248](#25248) landed a proper `HeadingSlugger` (github-slugger semantics including the `-1`/`-2` uniqueness suffixes) and code-block handling for multi-line types, which supersedes the two narrower fixes this PR originally carried. - `docs/docs-developers/docs/aztec-js/aztec_js_reference.md` — **took `next`'s version.** [#25249](#25249) added `update_docs.sh --check` to `docs/bootstrap.sh`, so the committed source page must match what the generator produces from the working tree. Regenerating on the merged tree reproduces `next`'s page byte-for-byte (modulo the self-stamped timestamp) and `--check` passes. The **v5.2.0 snapshot's** copy of that page was regenerated with `next`'s generator against the `v5.2.0` tag's `aztec.js` source, so the released snapshot gets the improved anchors and code-block formatting while still documenting v5.2.0's API. Also reconciled from `next` into the snapshot: [#25220](#25220 clarification that `teardownGasLimits` is carved out of `gasLimits` rather than added to it. Verified true at the tag (`yarn-project/stdlib/src/gas/gas_settings.ts`: "teardown gas is reserved from gasLimits during private execution ... the effective gas available for app logic is `gasLimits - teardownGasLimits - privateOverhead`"). The other post-tag doc changes on `next` are fast-inbox / AZIP-22 work (`inbox.md`, the `MessageSent` signature and message-availability wording in `token_bridge.md` and `uniswap_swap.md`, and dropping `AZTEC_INBOX_LAG`), which is not in v5.2.0 — deliberately **not** backported, so the snapshot keeps the wording that is correct for the release. ## Release details Verified from the node RPCs at cut time: | | Alpha (Mainnet) | Testnet | | --- | --- | --- | | `nodeVersion` from RPC | `5.1.0` | `5.2.0-nightly.20260815` | | `rollupVersion` | `4248422647` | `1821665230` | | L1 chain id | `1` | `11155111` | Per the instruction that the network versions are unchanged, the **Version** row in `networks.md` stays `5.1.0` for both columns; only the documentation version advances to `v5.2.0`. Every figure in `networks.md` was re-derived rather than carried forward: - all L1 addresses in both columns match `aztec_getNodeInfo` - Slasher, Honk verifier, Reward Booster, Tally Slashing Proposer and Slash Payload Cloneable re-read on chain from the Rollup / Slasher / Proposer for both networks, all unchanged - rollup version read from `getVersion()` on both rollups; chain ids from `cast chain-id` - governance parameters re-read on chain for **both** columns: proposer quorum 600/1000 and 60/100; voting delay, duration and execution delay decoded from `getConfiguration()` (mainnet 3 d / 7 d / 2 d, testnet 12 h / 24 h / 12 h); slashing quorum 65/128 over 4 epochs (128 slots) ### The canonical SponsoredFPC address changes under v5.2.0 tooling, and the new one is not deployed `aztec get-canonical-sponsored-fpc-address` built from the `v5.2.0` tag returns: ``` 0x2ece607a8dba690c9aa4ee1d53a55286fa815543a27f9364bbaf65eb68e7315b (class id 0x1cf37d561fb76ae2b95d3c395c3204c1dab4a6309b045a3fc17a58483c5ad2e9) ``` Testnet has nothing at that address (`aztec_getContract` returns `null`). What is deployed and funded is the v5.1.0-built FPC, `0x130925fb...923296` (class id `0x184e81e5...8673a5`), which is what this PR keeps. The SponsoredFPC Noir source is byte-identical between `v5.1.0` and `v5.2.0` — the address moved purely because the Noir compiler went `beta.22` to `beta.25`, which changes the compiled bytecode, the contract class id, and therefore the derived address. The same thing happened at the v5.1.0 cut, where a new FPC was deployed and funded. The consequence is worth stating plainly: `wallet.registerContract` does not validate that the supplied artifact matches the instance's class (explicit comment in `yarn-project/wallet-sdk/src/base-wallet/base_wallet.ts`), so `aztec-wallet register-contract ... SponsoredFPC` appears to succeed on v5.2.0 tooling and then fails at simulation, because the PXE only holds the `0x1cf37d...` artifact. **Either a v5.2.0-built SponsoredFPC is deployed and funded on testnet at `0x2ece...` and this PR is repointed at it, or sponsored fees on testnet stay pinned to v5.1.0 tooling.** ## Documentation content changes ### Aztec.nr: the v5.2.0 breaking change was live in three doc snippets Note structs declared inside a `contract` block must now be `pub` (Noir `beta.25`, [#24907](#24907)). `state_variables.md` (`AddressNote`, `UintNote`), `functions/attributes.md` (`CustomNote`) and the `#[custom_note]` example in the `notes.nr` doc comment (published through `nargo doc`) all showed non-`pub` declarations that do not compile on v5.2.0. Every `.nr` **source** file the docs pull in via `#include_code` was already `pub`, so the defect was confined to prose snippets. ### Migration notes - The `pub` note-visibility entry was filed under `## 5.1.0`, but the Noir `beta.25` bump that causes it is not in the `v5.1.0` tag. Moved to a new `## 5.2.0` section. - Four v5.2.0 behaviour changes had no migration note at all, each verified against `v5.1.0..v5.2.0`: the zero-peer proposing gate (`SEQ_MIN_PEERS_TO_PROPOSE`), JSON-RPC internal errors moving from `-32600` to `-32603`, `GET /status` gaining a per-component JSON body (and the widened `StatusCheckFn`), and the removal of `deserializeArrayFromVector` from `@aztec/foundation/serialize`. - The `## TBD` entries on this branch are left untouched: they describe changes on this line that have not shipped in a release yet. ### Operator / node docs All eight new v5.2.0 env vars were missing from the CLI reference; regenerating it at the tag picks them up, along with `--proverNode.proofSubmissionTargetAddress`, which existed in v5.1.0 code but was never documented. Hand edits on top: | File | Change | | --- | --- | | `reference/changelog/v5.2.md` | new page; the operator changelog stopped at v4.3.x. Plus index and sidebar entries | | `concepts/monitoring.md` | claimed the node emits no "about to be slashed" metric; it now does, so that section carries the real logs and metrics | | `monitoring/metrics-reference.md` | new own-validator slashing metrics section (with alert rule) and JSON-RPC server metrics section | | `concepts/sequencer-troubleshooting.md` | the four peerless-node gates, plus the `/status` health check and `P2P_HEALTH_MIN_PEERS` | | `reference/reading-logs.md` | five new entries: fatal p2p start failure, zero-peer warning, skipped proposal, mempool drop reasons, slash-target warning | | `sequencer-management/governance-participation.md` | the node now stops signalling an executed payload; `GOVERNANCE_PROPOSER_FORCE_PAYLOAD_VOTE` escape hatch | | `concepts/l1-rpc.md` | server-side filter methods are no longer required; watchers poll bounded `eth_getLogs` | | `provider/start-node.mdx`, `solo-sequencer/start-node.mdx` | sample `nodeVersion` `5.0.0` to `5.2.0` | Reviewed on the deploy preview by @yev. ### Developer docs - `tutorials/js_tutorials/aave_bridge.md` pinned `@aztec/l1-artifacts` to a literal version; it now uses the version macro like every other pin on that page, so it stops going stale each release. - `aztec-js/how_to_send_transaction.md` documents the new first-receipt-poll delay and `initialDelay` ([#25089](#25089)). - `@aztec/viem@2.38.2` is deliberately left alone in the three tutorials that pin it: it tracks upstream `viem`, not the release line. **Known gap, not fixed here:** the declarative deployment framework at `@aztec/aztec/deploy` ([#24685](#24685)), headlined as "New in this release", has **zero** documentation. It wants a new `aztec-js` page; that was scoped but not written, rather than shipping a half-verified page for a new API. ## Non-docs changes Three one-line source edits, all comment-only, no behaviour change: - `archiver/src/config.ts` and `stdlib/src/interfaces/archiver.ts` — `on-chain` to `onchain`, so the regenerated operator CLI reference passes the repo's own spellcheck (`on-chain` is a repo-wide `flagWord`) - `noir-projects/labs/aztec-nr/aztec/src/macros/notes.nr` — the `pub` fix in the `#[custom_note]` doc comment The equivalent `aztec.js` JSDoc fixes this PR originally carried are gone: `next` made the same corrections upstream, so the merge left nothing to change. ## Validation `MAINNET_TAG=5.2.0 TESTNET_TAG=5.2.0 RELEASE_TYPE=mainnet COMMIT_TAG=v5.2.0 yarn build`, re-run on the merged tree: - CSpell: 682 files, **0 issues** - Redirect targets: 185 checked, all valid - API reference links: 112 checked, **0 broken, 0 version mismatches** - Docusaurus production build: **successful** - `./scripts/aztecjs_reference_generation/update_docs.sh --check`: **✓ Reference matches aztec.js** - no unresolved `#release_version` / `#release_network` / `#include_code` macros in either snapshot - version configs and version lists carry one shared `v5.2.0` snapshot for both Alpha and Testnet - generated `mainnet` and `testnet` Aztec.nr and TypeScript API directories are byte-identical - empty `## TBD` heading stripped from the cut snapshot's migration notes Remaining broken-anchor warnings are the pre-existing ones only (the `validator-keys|valkeys` CLI alias and the operator compose-page anchors); `onBrokenAnchors` is `warn`, so the build passes. **Not run:** the functional validation pass (walking the guides and tutorials against a live local network). This container has no Docker daemon, so the dockerized `aztec` CLI could not be installed; everything above was produced from a source build of the tag with shims for `aztec` / `aztec-wallet` / `aztec-up`. The guides and tutorials in this snapshot are link- and spell-validated but not executed. --- *Created by [claudebox](https://claudebox.work/v2/sessions/c8d26e6f93543878/jobs/12) · group: `slackbot` · requested by Alejo Amiras · [Slack thread](https://aztecfoundation.slack.com/archives/C0B24G1GFGB/p1787064177273599?thread_ts=1787064177.273599&cid=C0B24G1GFGB)*
The committed
aztec_js_reference.mdwas last generated on 2025-12-10. Against today's aztec.js source it documents 125 symbols where the package exports 188: 19 documented symbols no longer exist (AccountInterface,AccountWithSecretKey,DeploySentTx,broadcastPrivateFunction,getGasLimits, ...) and 82 current exports are missing.The v5.1.0 snapshot that production serves carries the same December content, so this is what the live API reference shows today. The release refreshed the CLI references, the aztec-nr API and the TypeDoc TypeScript API in the same commit, but
aztecjs_reference_generation/update_docs.shis not part of the release checklist.This also resolves the contradiction @nchamo spotted in #25220, where the stale block still described the old two-argument form and said gas limits exclude teardown gas.
Why the generator changed too
A straight regeneration does not build, so two generator bugs are fixed first:
Unexpected end of file in expression. Multi-line types now use a fenced code block, matching whatformat_return_typealready did. Verified this reproduces onmerge-train/fairiesitself with none of these commits applied.CAPABILITY_VERSIONand theContract / Protocol_Contractssection unreachable and pointingNO_WAIT/NO_FROMat theNoWait/NoFromheadings. Anchors now derive from the rendered heading text the way github-slugger does.The aztec.js JSDoc edits are comment-only, and are needed because the regenerated page otherwise fails
yarn spellcheckon ametadatatypo and onon-chain, which is aflagWordsentry in the rootcspell.json.