Merge branch 'next' into merge-train/barretenberg

Author: AztecBot

.claude/skills/release-docs/SKILL.md

@@ -90,9 +90,9 @@ Store the address for updating docs.
 **Note:** The Sponsored FPC is only deployed on devnet. For mainnet and testnet releases,
 mark the SponsoredFPC row as "Not deployed" in the L2 Contract Addresses table.
 
-### Step 5: Update Version Config
+### Step 5: Update Version Configs
 
-**File:** `docs/developer_version_config.json`
+**Developer docs:** `docs/developer_version_config.json`
 
 This file maps release types to version strings. Update the entry matching the
 release type with the new version (prefixed with `v`):
@@ -111,6 +111,9 @@ For example, for a devnet release of `4.1.0-devnet.1`, update `"devnet": "v4.1.0
 The preprocessor (`include_version.js`) reads defaults from this config file, so
 updating it is sufficient — you no longer need to edit hardcoded defaults in JS.
 
+**Network/operator docs** are updated separately in Step 13 after the version
+snapshot is created (the config update requires the versioned docs directory to exist).
+
 ### Step 6: Generate API Reference Docs
 
 Generate the Aztec.nr and TypeScript API documentation for the new version. The
@@ -279,13 +282,21 @@ cd docs
 <TAG_VAR>=<new_version> RELEASE_TYPE=<release_type> yarn docusaurus docs:version:developer v<new_version>
 ```
 
-Then update the versions file:
+Then update the versions files:
+
+```bash
+scripts/update_docs_versions.sh developer
+```
+
+For **mainnet** and **testnet** releases, also cut and configure the network/operator docs:
 
 ```bash
-docs/scripts/update_docs_versions.sh developer
+<TAG_VAR>=<new_version> RELEASE_TYPE=<release_type> yarn docusaurus docs:version:network v<new_version>
+scripts/update_docs_versions.sh network <release_type> v<new_version>
 ```
 
-Verify the new version appears in `docs/developer_version_config.json`.
+Verify the new version appears in both `docs/developer_version_config.json` and
+`docs/network_version_config.json`.
 
 ### Step 14: Review Recent Docs Updates on `next`
 

docs/CLAUDE.md

@@ -144,9 +144,10 @@ The TypeScript API generation is configured in `scripts/typescript_api_generatio
 Uses Docusaurus multi-instance versioning with separate version tracks:
 
 - **Developer docs**: Version config in `developer_version_config.json`, stored in `developer_versioned_docs/`
-- **Network docs**: Versions in `network_versions.json`, stored in `network_versioned_docs/`
-- Developer version config is an object mapping release type to version string (e.g., `{"mainnet": "v4.2.0", "testnet": "v4.1.0", ...}`)
-- `developer_versions.json` is auto-generated from the config file; `network_versions.json` is managed directly
+- **Network docs**: Version config in `network_version_config.json`, stored in `network_versioned_docs/`
+- Both config files map release types to version strings (e.g., `{"mainnet": "v4.2.0", "testnet": "v4.1.0", ...}`)
+- `docusaurus.config.js` auto-generates `*_versions.json` from these configs (filtered to versions with existing directories, plus any extra unmapped directories)
+- Use `scripts/update_docs_versions.sh` to update configs and reconcile: `./scripts/update_docs_versions.sh network mainnet v4.2.0`
 - Each docs instance has its own version dropdown in the navbar
 - Preprocessing macros (`#include_code`, `#release_version`, conditionals, etc.) only work in source folders, not in versioned copies
 - Create new versions with: `yarn docusaurus docs:version:<instance-id> <version>`

docs/README.md

@@ -65,19 +65,21 @@ The legacy `#include_aztec_version` macro uses `COMMIT_TAG`, while `#include_ver
 
 ### How do I change the versions that show in the website
 
-The version system uses two approaches:
+Both developer and network docs use **version config files** that map release types to version strings:
 
-- **Developer docs**: `developer_version_config.json` maps release types to version strings (e.g., `{"mainnet": "v4.2.0", "testnet": "v4.1.0", ...}`). The Docusaurus-compatible `developer_versions.json` is auto-generated from this config at startup.
-- **Network docs**: `network_versions.json` is managed directly as a simple array of version strings.
+- **Developer docs**: `developer_version_config.json` (e.g., `{"mainnet": "v4.2.0-aztecnr-rc.2", "testnet": "v4.1.0-rc.2", ...}`)
+- **Network docs**: `network_version_config.json` (e.g., `{"mainnet": "v4.1.2", "testnet": "v4.1.0-rc.2"}`)
 
-You can update the developer config manually, or use the `scripts/update_docs_versions.sh` script which reconciles it with the versioned docs directories:
+The `docusaurus.config.js` reads these configs and auto-generates the Docusaurus-compatible `*_versions.json` arrays at startup, including only versions that have matching versioned docs directories. Any extra directories not in the config are also included (to preserve newly cut versions before the config is updated).
+
+Use `scripts/update_docs_versions.sh` to update configs and reconcile with versioned docs directories:
 
 ```bash
-./scripts/update_docs_versions.sh developer  # Updates developer_version_config.json
+./scripts/update_docs_versions.sh developer                        # Reconcile developer config
+./scripts/update_docs_versions.sh network mainnet v4.2.0           # Set mainnet=v4.2.0, then reconcile
+./scripts/update_docs_versions.sh developer nightly v5.0.0-nightly # Set nightly version, then reconcile
 ```
 
-For network docs, edit `network_versions.json` directly.
-
 To create a new versioned snapshot of the docs:
 
 ```bash
@@ -87,33 +89,15 @@ yarn docusaurus docs:version:network v4.2.0              # New network version
 
 ### Version Configuration
 
-The `docusaurus.config.js` file reads `developer_version_config.json` which explicitly maps release types to version strings. This replaces fragile substring matching on version strings for developer docs.
-
-**Developer docs** (from `developer_version_config.json`):
-
-```javascript
-const mainnetDeveloperVersion = developerVersionConfig.mainnet || null;
-const developerTestnetVersion = developerVersionConfig.testnet || null;
-const devnetVersion = developerVersionConfig.devnet || null;
-const nightlyVersion = developerVersionConfig.nightly || null;
-```
-
-**Network docs** (from `network_versions.json`):
-
-```javascript
-const ignitionVersion = networkVersions.find((v) => v.includes("ignition"));
-const testnetVersion = networkVersions.find((v) => !v.includes("ignition"));
-```
+The `docusaurus.config.js` file reads both config files to determine version labels, paths, and defaults. The config-based approach replaces fragile substring matching on version strings.
 
 This ensures that:
 
-- Developer doc version types are always correct regardless of the version string format
+- Version types are always correct regardless of the version string format
 - When nightly versions are removed by the cleanup script, the build doesn't break
 - Version configurations are conditionally included only if they exist
 - The llms.txt plugin always points to the correct version (mainnet or testnet)
 
-**Why this matters:** The [nightly docs workflow](../.github/workflows/nightly-docs-release.yml) runs `cleanup_nightly_versions.sh` before creating new versioned docs. The config-based approach means version type detection never breaks even when version strings don't follow predictable patterns.
-
 ## Releases
 
 A new docs site is published on every merge to the next branch.

docs/developer_versioned_docs/version-v4.1.0-rc.2/ai_tooling.md

@@ -40,6 +40,10 @@ This is an Aztec smart contract project. Always use the `aztec` CLI wrapper inst
 - Prefer `T` return types over `T | null` when null would indicate a bug rather than a valid state.
 - Do not add `.catch(() => defaultValue)` to promises. If something fails, the caller needs to know.
 
+## Version Compatibility
+
+The Aztec developer SDK/aztec-nr version (used for writing and compiling contracts) may differ from the node version (used by operators to run the network). For example, aztec-nr `4.2.0-aztecnr-rc.2` is compatible with node version `4.1.2`. Check the [Networks page](https://docs.aztec.network/networks) for current network versions. When in doubt, use the version from the developer docs you are reading — it is the correct SDK version for contract development on that network.
+
 ## Hashing: Default to Poseidon2
 
 When writing Aztec.nr contract code that requires hashing, **always use Poseidon2** unless a specific protocol or interoperability requirement calls for a different hash.

docs/developer_versioned_docs/version-v4.2.0-aztecnr-rc.2/ai_tooling.md

@@ -40,6 +40,10 @@ This is an Aztec smart contract project. Always use the `aztec` CLI wrapper inst
 - Prefer `T` return types over `T | null` when null would indicate a bug rather than a valid state.
 - Do not add `.catch(() => defaultValue)` to promises. If something fails, the caller needs to know.
 
+## Version Compatibility
+
+The Aztec developer SDK/aztec-nr version (used for writing and compiling contracts) may differ from the node version (used by operators to run the network). For example, aztec-nr `4.2.0-aztecnr-rc.2` is compatible with node version `4.1.2`. Check the [Networks page](https://docs.aztec.network/networks) for current network versions. When in doubt, use the version from the developer docs you are reading — it is the correct SDK version for contract development on that network.
+
 ## Hashing: Default to Poseidon2
 
 When writing Aztec.nr contract code that requires hashing, **always use Poseidon2** unless a specific protocol or interoperability requirement calls for a different hash.

docs/developer_versioned_docs/version-v4.2.0-aztecnr-rc.2/docs/tutorials/contract_tutorials/counter_contract.md

@@ -22,7 +22,7 @@ This tutorial is compatible with the Aztec version `4.2.0-aztecnr-rc.2`. Install
 Run this to create a new contract project:
 
 ```bash
-aztec new --contract counter
+aztec new counter
 ```
 
 Your structure should look like this:

docs/developer_versioned_docs/version-v4.2.0-aztecnr-rc.2/docs/tutorials/contract_tutorials/recursive_verification.md

@@ -42,7 +42,7 @@ For example, consider a machine learning inference that needs 10,000 input featu
 
 1. Perform the computation offchain in a vanilla Noir circuit with no input limits
 2. Generate a proof of correct execution
-3. Verify only the proof onchain (115 fields for VK + 457-508 fields for proof + N public inputs)
+3. Verify only the proof onchain (115 fields for VK + ~500 fields for proof + N public inputs)
 
 This pattern transforms arbitrarily large computations into fixed-size proof verification.
 
@@ -68,7 +68,7 @@ flowchart LR
 
 Proof verification enables several patterns:
 
-- **Bypassing Input Limits**: Aztec private functions have strict input constraints. A proof verification call uses ~624 fields (115 VK + 508 proof + 1 public input), but can attest to computations with arbitrarily many inputs. For example, proving membership in a set of 10,000 elements becomes a fixed-size verification.
+- **Bypassing Input Limits**: Aztec private functions have strict input constraints. A proof verification call uses ~616 fields (115 VK + ~500 proof + 1 public input), but can attest to computations with arbitrarily many inputs. For example, proving membership in a set of 10,000 elements becomes a fixed-size verification.
 
 - **Cross-System Verification**: Verify proofs generated by external Noir circuits within your Aztec application. This enables composability: your contract can trust computations performed by other systems without those systems needing to be Aztec-native.
 
@@ -225,10 +225,10 @@ The contract demonstrates several important patterns:
 
 ### Create the Contract Project
 
-Use `aztec init` to generate the contract project structure:
+Use `aztec new` to generate the contract project structure:
 
 ```bash
-aztec init --contract contract
+aztec new contract --name ValueNotEqual
 ```
 
 This creates:
@@ -541,7 +541,7 @@ Create `scripts/generate_data.ts`:
 
 ```typescript title="generate_data" showLineNumbers 
 import { Noir } from "@aztec/noir-noir_js";
-import circuitJson from "../../../../target/hello_circuit.json" with { type: "json" };
+import circuitJson from "../circuit/target/hello_circuit.json" with { type: "json" };
 import { Barretenberg, UltraHonkBackend, deflattenFields } from "@aztec/bb.js";
 import fs from "fs";
 import { exit } from "process";
@@ -597,14 +597,14 @@ if (proofAsFields.length === 0) {
 const vkAsFields = recursiveArtifacts.vkAsFields;
 
 console.log(`VK size: ${vkAsFields.length}`); // Should be 115
-console.log(`Proof size: ${proofAsFields.length}`); // Should be 508
+console.log(`Proof size: ${proofAsFields.length}`); // Should be ~500
 console.log(`Public inputs: ${mainProofData.publicInputs.length}`); // Should be 1
 
 // Step 9: Save all data to JSON for contract interaction
 const data = {
   vkAsFields: vkAsFields, // 115 field elements - the verification key
   vkHash: recursiveArtifacts.vkHash, // Hash of VK - stored in contract
-  proofAsFields: proofAsFields, // 508 field elements - the proof
+  proofAsFields: proofAsFields, // ~500 field elements - the proof
   publicInputs: mainProofData.publicInputs.map((p: string) => p.toString()),
 };
 
@@ -659,7 +659,7 @@ Always verify locally before submitting onchain. Onchain verification costs gas/
 
 #### Field Element Conversion
 
-ZK proofs are arrays of bytes, but Aztec contracts work with field elements. We convert the proof and VK to arrays of 115 and 508 field elements respectively.
+ZK proofs are arrays of bytes, but Aztec contracts work with field elements. We convert the proof and VK to arrays of 115 and ~500 field elements respectively.
 
 ```typescript
 let proofAsFields = recursiveArtifacts.proofAsFields;
@@ -701,7 +701,7 @@ Expected output:
 Proof verification: SUCCESS
 Using deflattenFields to convert proof...
 VK size: 115
-Proof size: 508
+Proof size: 500
 Public inputs: 1
 Done
 ```
@@ -714,7 +714,7 @@ The generated `data.json` contains:
 {
   "vkAsFields": ["0x...", "0x...", ...],   // 115 field elements
   "vkHash": "0x...",                        // Single field element
-  "proofAsFields": ["0x...", "0x...", ...], // 508 field elements
+  "proofAsFields": ["0x...", "0x...", ...], // ~500 field elements
   "publicInputs": ["2"]                     // The public input y=2
 }
 ```
@@ -832,7 +832,7 @@ async function main() {
   const interaction = await valueNotEqual.methods.increment(
     accounts[0].item,
     data.vkAsFields as unknown as FieldLike[], // 115 field VK
-    data.proofAsFields as unknown as FieldLike[], // 508 field proof
+    data.proofAsFields as unknown as FieldLike[], // ~500 field proof
     data.publicInputs as unknown as FieldLike[], // Public inputs
   );
 
@@ -885,7 +885,7 @@ This single line triggers a complex flow:
 
 2. **Proof Generation** (client-side, in PXE):
    - Generate a ZK proof that the private execution was correct
-   - This proof doesn't reveal inputs (including the 508-field proof!)
+   - This proof doesn't reveal inputs (including the ~500-field proof!)
 
 3. **Transaction Submission**:
    - Send the proof + encrypted logs + public function calls to the network

docs/developer_versioned_docs/version-v4.2.0-aztecnr-rc.2/docs/tutorials/contract_tutorials/token_contract.md

@@ -44,13 +44,13 @@ cd bob_token
 yarn init
 # This is to ensure yarn uses node_modules instead of pnp for dependency installation
 yarn config set nodeLinker node-modules
-yarn add @aztec/aztec.js@4.2.0-aztecnr-rc.2 @aztec/accounts@4.2.0-aztecnr-rc.2 @aztec/test-wallet@4.2.0-aztecnr-rc.2 @aztec/kv-store@4.2.0-aztecnr-rc.2
+yarn add @aztec/aztec.js@4.2.0-aztecnr-rc.2 @aztec/accounts@4.2.0-aztecnr-rc.2 @aztec/kv-store@4.2.0-aztecnr-rc.2
 aztec init
 ```
 
 ## Contract structure
 
-The `aztec init` command created a workspace with two crates: a `bob_token_contract` crate for your smart contract code and a `bob_token_test` crate for Noir tests. In `bob_token_contract/src/main.nr` we even have a proto-contract. Let's replace it with a simple starting point:
+The `aztec init` command created a contract project with `Nargo.toml` and `src/main.nr`. Let's replace the boilerplate in `src/main.nr` with a simple starting point:
 
 ```rust
 use aztec::macros::aztec;

docs/developer_versioned_docs/version-v4.2.0-aztecnr-rc.2/docs/tutorials/js_tutorials/token_bridge.md

@@ -830,7 +830,7 @@ const INBOX_ABI = [
     type: "event",
     name: "MessageSent",
     inputs: [
-      { name: "l2BlockNumber", type: "uint256", indexed: true },
+      { name: "checkpointNumber", type: "uint256", indexed: true },
       { name: "index", type: "uint256", indexed: false },
       { name: "hash", type: "bytes32", indexed: true },
       { name: "rollingHash", type: "bytes16", indexed: false },

docs/docs-developers/ai_tooling.md

@@ -40,6 +40,10 @@ This is an Aztec smart contract project. Always use the `aztec` CLI wrapper inst
 - Prefer `T` return types over `T | null` when null would indicate a bug rather than a valid state.
 - Do not add `.catch(() => defaultValue)` to promises. If something fails, the caller needs to know.
 
+## Version Compatibility
+
+The Aztec developer SDK/aztec-nr version (used for writing and compiling contracts) may differ from the node version (used by operators to run the network). For example, aztec-nr `4.2.0-aztecnr-rc.2` is compatible with node version `4.1.2`. Check the [Networks page](https://docs.aztec.network/networks) for current network versions. When in doubt, use the version from the developer docs you are reading — it is the correct SDK version for contract development on that network.
+
 ## Hashing: Default to Poseidon2
 
 When writing Aztec.nr contract code that requires hashing, **always use Poseidon2** unless a specific protocol or interoperability requirement calls for a different hash.