Skip to content

docs: backport v5.2.0 developer and node docs to v5-next - #25265

Open
AztecBot wants to merge 3 commits into
v5-nextfrom
cb/release-docs-v5.2.0
Open

docs: backport v5.2.0 developer and node docs to v5-next#25265
AztecBot wants to merge 3 commits into
v5-nextfrom
cb/release-docs-v5.2.0

Conversation

@AztecBot

@AztecBot AztecBot commented Aug 18, 2026

Copy link
Copy Markdown
Collaborator

Backport of the merged #25266 (docs: release v5.2.0 developer and node docs, merged into next as 2e32f82a9db) onto the v5-next line.

Summary

Cuts the v5.2.0 developer and network/operator documentation snapshots, points both the mainnet and testnet selectors at that shared snapshot, and removes the superseded snapshot. All generated references (Aztec.nr, TypeScript, Aztec.js, aztec / aztec-wallet / aztec-up CLI, operator aztec start CLI, Node JSON-RPC) regenerated at the v5.2.0 tag.

The release artifacts are byte-identical to what merged in #25266: the version-v5.2.0 developer and network snapshots, both sidebars, and the generated aztec-nr-api / typescript-api static directories were taken verbatim from the merged next tree (git diff origin/next over those paths is empty). That includes the post-review improvements #25266 picked up while resolving conflicts with next:

  • the Aztec.js reference regenerated with the new generator from #25248 (proper github-slugger anchors, code blocks for multi-line types) against the tag's aztec.js source
  • the teardownGasLimits is-carved-out-of-gasLimits clarification from #25220, verified true at the tag (yarn-project/stdlib/src/gas/gas_settings.ts)

Also brought across so the two lines behave the same:

  • docs/scripts/aztecjs_reference_generation/ (the docs: regenerate the aztec.js API reference #25248 generator plus update_docs.sh --check from #25249), and the check_generated_refs CI hook grafted into this line's docs/bootstrap.sh (hunk-only — the file legitimately diverges from next in its toolchain paths, so it was not overwritten). --check passes on this branch: the committed source reference matches what the generator produces from v5-next's aztec.js source, which is identical to the tag's.
  • the source-tree how_to_pay_fees.md gasLimits clarification and the source Aztec.js reference page (same content as the snapshot, since this line's aztec.js is the tag's).

Deliberately not brought across: next's post-tag fast-inbox / AZIP-22 doc changes (MessageSent signature, message-availability wording, AZTEC_INBOX_LAG removal) — that work is not in v5.2.0 or on this line.

What differs from #25266 (each branch's starting tree)

next (#25266, merged) v5-next (this PR)
snapshot superseded version-v5.1.0 version-v5.0.1
version config before {"mainnet":"v5.1.0","testnet":"v5.1.0"} {"mainnet":"v5.0.1","testnet":"v5.0.1"}
## TBD migration entries left untouched (real on that line) two removed, one corrected (below)
operator L1 address refresh (d00f0582d96) already present backported here
networks.md already current taken from next
aztec.js JSDoc typo fixes (on-chain, meatadata) fixed upstream on next carried here (not on this line)

The v5.1.0 docs release (#25085) merged into next only, so this line never had a v5.1.0 snapshot; "deprecate v5.1.0" lands here as the v5.2.0 cut superseding and removing version-v5.0.1.

Migration notes corrected on this line only

Both bogus entries arrived via c85280dbbf3 "docs: backport next docs baseline to v5-next", which imported next's (6.0.0-line) migration notes wholesale. Neither describes code that exists at v5.2.0:

  • Protocol contracts removed from @aztec/noir-contracts.js and at(wallet) to withWallet(wallet) — both from #24998, which is not an ancestor of v5.2.0; following either note on v5.2.0 throws. Removed.
  • Standard contracts re-pinned at new addresses claimed all standard contracts moved, but standard_addresses.nr is byte-identical between v5.1.0 and v5.2.0. Restored to the accurate v5.1.0 wording (HandshakeRegistry only) under ## 5.1.0.

Everything else matches #25266: the pub note-visibility entry under ## 5.2.0, plus the four new entries (zero-peer proposing gate, -32600 to -32603, GET /status JSON body, deserializeArrayFromVector removal).

Everything else

Identical in substance to #25266 — see that PR for the full breakdown: the three non-pub #[note] doc snippets, all eight new operator env vars via the regenerated CLI reference, the new changelog/v5.2.md, the own-validator slashing signal, the peerless-node behaviour, the governance-payload auto-stop, the eth_getLogs note, and the re-derived networks.md (Version row stays 5.1.0 for both columns per the release instruction). The operator pages were reviewed on #25266's deploy preview.

The open SponsoredFPC question also carries over unchanged: v5.2.0 tooling derives 0x2ece607a...e7315b, which is not deployed on testnet; the docs keep the deployed and funded 0x130925fb...923296.

Validation

MAINNET_TAG=5.2.0 TESTNET_TAG=5.2.0 RELEASE_TYPE=mainnet COMMIT_TAG=v5.2.0 yarn build, run on this branch after merging origin/v5-next (which had moved two commits, neither touching docs or aztec.js):

  • 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
  • git diff origin/next over both versioned snapshot trees and both generated API static directories: empty

Remaining broken-anchor warnings are the same six pre-existing ones as on next; onBrokenAnchors is warn, so the build passes.

Not run: the functional validation pass (walking guides and tutorials against a live local network) — no Docker daemon in this container; same caveat as #25266.


Created by claudebox · group: slackbot · requested by Alejo Amiras · Slack thread

@AztecBot AztecBot added A-documentation Area: relates to documentation C-docs Component: docs.aztec.network 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 Aug 18, 2026
@AztecBot AztecBot changed the title docs: release v5.2.0 developer and node docs docs: backport v5.2.0 developer and node docs to v5-next Aug 18, 2026
AztecBot added a commit that referenced this pull request Aug 19, 2026
## 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)*
@alejoamiras
alejoamiras marked this pull request as ready for review August 19, 2026 13:50
@alejoamiras
alejoamiras self-requested a review August 19, 2026 13:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-documentation Area: relates to documentation C-docs Component: docs.aztec.network 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.

2 participants