chore: Accumulated backports to v4-next

boxes/boxes/vanilla/contracts/src/main.nr

@@ -3,7 +3,6 @@ use aztec::macros::aztec;
 
 #[aztec]
 pub contract PrivateVoting {
-    // docs:start:imports
     use aztec::macros::{functions::{external, initializer, only_self, view}, storage::storage};
     use aztec::protocol::{address::AztecAddress, traits::{Deserialize, Serialize, ToField}};
     use aztec::state_vars::{Map, Owned, PublicImmutable, PublicMutable, SingleUseClaim};
@@ -25,8 +24,6 @@ pub contract PrivateVoting {
         }
     }
 
-    // docs:end:imports
-    // docs:start:storage_struct
     #[storage]
     struct Storage<Context> {
         // admin can start and end elections
@@ -40,23 +37,19 @@ pub contract PrivateVoting {
         // election => voter => single use claim that ensures voter can at most vote once per election
         vote_claims: Map<ElectionId, Owned<SingleUseClaim<Context>, Context>, Context>,
     }
-    // docs:end:storage_struct
 
-    // docs:start:constructor
     #[external("public")]
     #[initializer]
     fn constructor(admin: AztecAddress) {
         self.storage.admin.write(admin);
     }
-    // docs:end:constructor
 
     #[external("private")]
     fn cast_vote(election_id: ElectionId, candidate: Field) {
         self.storage.vote_claims.at(election_id).at(self.msg_sender()).claim();
         self.enqueue_self.add_to_tally_public(election_id, candidate);
     }
 
-    // docs:start:nested_map_access
     #[external("public")]
     #[only_self]
     fn add_to_tally_public(election_id: ElectionId, candidate: Field) {
@@ -65,7 +58,6 @@ pub contract PrivateVoting {
         let new_tally = self.storage.tally.at(election_id).at(candidate).read() + 1;
         self.storage.tally.at(election_id).at(candidate).write(new_tally);
     }
-    // docs:end:nested_map_access
 
     #[external("public")]
     fn start_vote(election_id: ElectionId) {

docs/CLAUDE.md

@@ -52,14 +52,14 @@ For development:
 
 The preprocessing system uses these environment variables:
 
-| Variable       | Description                                                         | Default                                  |
-| -------------- | ------------------------------------------------------------------- | ---------------------------------------- |
-| `RELEASE_TYPE` | Release type: `nightly`, `devnet`, `testnet`, `mainnet`             | `nightly`                                |
-| `NIGHTLY_TAG`  | Version for nightly builds (falls back to `COMMIT_TAG`)             | from `developer_version_config.json`     |
-| `DEVNET_TAG`   | Version for devnet builds                                           | from `developer_version_config.json`     |
-| `TESTNET_TAG`  | Version for testnet builds                                          | from `developer_version_config.json`     |
-| `MAINNET_TAG`  | Version for mainnet builds                                          | from `developer_version_config.json`     |
-| `COMMIT_TAG`   | Legacy variable, used as fallback for `NIGHTLY_TAG`                 | `next`                                   |
+| Variable       | Description                                             | Default                              |
+| -------------- | ------------------------------------------------------- | ------------------------------------ |
+| `RELEASE_TYPE` | Release type: `nightly`, `devnet`, `testnet`, `mainnet` | `nightly`                            |
+| `NIGHTLY_TAG`  | Version for nightly builds (falls back to `COMMIT_TAG`) | from `developer_version_config.json` |
+| `DEVNET_TAG`   | Version for devnet builds                               | from `developer_version_config.json` |
+| `TESTNET_TAG`  | Version for testnet builds                              | from `developer_version_config.json` |
+| `MAINNET_TAG`  | Version for mainnet builds                              | from `developer_version_config.json` |
+| `COMMIT_TAG`   | Legacy variable, used as fallback for `NIGHTLY_TAG`     | `next`                               |
 
 ### Preprocessing Macros
 
@@ -163,6 +163,7 @@ The `examples/` directory contains runnable code examples that are included in d
 - **`AZTEC_NODE_URL`**: All example `index.ts` files and `run.sh` use this env var (defaults to `http://localhost:8080`). In Docker Compose, it points to `http://local-network:8080`.
 
 When adding new TypeScript examples:
+
 1. Create a directory under `examples/ts/` with `index.ts`, `config.yaml`, and empty `yarn.lock`
 2. Use `process.env.AZTEC_NODE_URL ?? "http://localhost:8080"` for the node URL
 3. Add the example to the list in `examples/ts/aztecjs_runner/run.sh` if it should be executed at runtime
@@ -246,6 +247,31 @@ Use these terms consistently throughout:
 - **Emphasis**: Use _italics_ sparingly for emphasis
 - **File paths**: Always use forward slashes (e.g., `/usr/local/bin`)
 - **Placeholders**: Use `[PLACEHOLDER_NAME]` format in examples
+- **Em-dashes (`—`)**: Do not use em-dashes. They often signal AI-generated prose and add friction when editing across tools. Rewrite with a comma, colon, parentheses, or a new sentence. Examples:
+  - ❌ `Alpha is live — bugs are expected.`
+  - ✅ `Alpha is live, and bugs are expected.`
+  - ❌ `Limits apply — number of notes, nullifiers, logs.`
+  - ✅ `Limits apply: number of notes, nullifiers, logs.`
+  - ❌ `[Networks Overview](/networks) — Technical details`
+  - ✅ `[Networks Overview](/networks): Technical details`
+
+### Heading Capitalization
+
+**Use sentence case for all headings (H1 through H6).** Only capitalize the first word and proper nouns. Do not capitalize common nouns, verbs, prepositions, articles, or conjunctions.
+
+**Examples:**
+
+- ✅ `## What Alpha is`
+- ✅ `## Known limitations and expected issues`
+- ✅ `### Proving system bugs`
+- ✅ `## State migration and rollup upgrades`
+- ✅ `## Path to beta`
+- ✅ `## How to deploy a contract`
+- ❌ `## What Alpha Is`
+- ❌ `## Known Limitations and Expected Issues`
+- ❌ `## How To Deploy A Contract`
+
+**Applying this to existing files:** When editing an existing page that uses Title Case, convert the headings you touch (and ideally the whole page) to sentence case. The goal is to converge on one style across the site, rather than preserving historical inconsistency.
 
 ### Standard Sections
 
@@ -288,7 +314,8 @@ The description should:
 - ✅ Missing context or assumptions about user knowledge
 - ✅ Outdated screenshots or version references
 - ✅ Broken markdown formatting
-- ✅ Inconsistent capitalization in headings
+- ✅ Headings using Title Case instead of sentence case (see "Heading Capitalization")
+- ✅ Em-dashes (`—`) in prose (see "Formatting Conventions")
 - ✅ Missing alt text for images
 - ✅ Security implications of commands or configurations
 
@@ -299,7 +326,7 @@ The description should:
 - ❌ Legal disclaimers or license text
 - ❌ Direct quotes from external sources
 - ❌ API endpoint URLs or configuration values
-- ❌ Existing migration notes in `resources/migration_notes.md` — never modify already-published migration entries. Instead, add new migration notes to the `## TBD` section at the top of the file.
+- ❌ Existing migration notes in `resources/migration_notes.md`. Never modify already-published migration entries. Instead, add new migration notes to the `## TBD` section at the top of the file.
 
 ## Review Output Format
 
@@ -355,5 +382,5 @@ Approved external documentation sources:
 - Suggest improvements even if they go beyond pure editing
 - When making changes to documentation processes or tooling, remember to check and update READMEs, project documentation (like this file), and code comments
 
-Last updated: 2026-02-23
-Version: 1.5
+Last updated: 2026-04-21
+Version: 1.7

docs/developer_versioned_docs/version-v4.1.0-rc.2/docs/aztec-nr/framework-description/advanced/protocol_oracles.md

@@ -21,20 +21,15 @@ If we fetch the notes using an oracle call, we can keep the function signature i
 
 Oracles introduce **non-determinism** into a circuit, and thus are `unconstrained`. It is important that any information that is injected into a circuit through an oracle is later constrained for correctness. Otherwise, the circuit will be **under-constrained** and potentially insecure!
 
-`Aztec.nr` has a module dedicated to its oracles. If you are interested, you can view them by following the link below:
-```rust title="oracles-module" showLineNumbers 
-/// Oracles module
-```
-> <sup><sub><a href="https://github.com/AztecProtocol/aztec-packages/blob/v4.1.0-rc.2/noir-projects/aztec-nr/aztec/src/oracle/mod.nr#L3-L5" target="_blank" rel="noopener noreferrer">Source code: noir-projects/aztec-nr/aztec/src/oracle/mod.nr#L3-L5</a></sub></sup>
-
+`Aztec.nr` has a [module dedicated to its oracles](pathname:///aztec-nr-api/mainnet/noir_aztec/oracle/index.html) where you can browse the full list.
 
 ## Inbuilt oracles
 
-- [`debug_log`](https://github.com/AztecProtocol/aztec-packages/blob/v4.1.0-rc.2/noir-projects/noir-protocol-circuits/crates/types/src/debug_log.nr) - Provides debug functions that can be used to log information to the console. Read more about debugging [here](../../debugging.md).
-- [`auth_witness`](https://github.com/AztecProtocol/aztec-packages/blob/v4.1.0-rc.2/noir-projects/aztec-nr/aztec/src/oracle/auth_witness.nr) - Provides a way to fetch the authentication witness for a given address. This is useful when building account contracts to support approve-like functionality.
-- [`get_l1_to_l2_membership_witness`](https://github.com/AztecProtocol/aztec-packages/blob/v4.1.0-rc.2/noir-projects/aztec-nr/aztec/src/oracle/get_l1_to_l2_membership_witness.nr) - Returns the leaf index and sibling path for an L1 to L2 message, used to prove message existence in cross-chain applications like token bridges.
-- [`notes`](https://github.com/AztecProtocol/aztec-packages/blob/v4.1.0-rc.2/noir-projects/aztec-nr/aztec/src/oracle/notes.nr) - Provides functions related to notes, such as fetching notes from storage, used behind the scenes for value notes and other pre-built note implementations.
-- [`logs`](https://github.com/AztecProtocol/aztec-packages/blob/v4.1.0-rc.2/noir-projects/aztec-nr/aztec/src/oracle/logs.nr) - Provides functions to log encrypted and unencrypted data.
+- [`debug_log`](pathname:///aztec-nr-api/mainnet/noir_aztec/protocol/logging/fn.debug_log) - Provides debug functions that can be used to log information to the console. Read more about debugging [here](../../debugging.md).
+- [`auth_witness`](pathname:///aztec-nr-api/mainnet/noir_aztec/oracle/auth_witness/index.html) - Provides a way to fetch the authentication witness for a given address. This is useful when building account contracts to support approve-like functionality.
+- [`get_l1_to_l2_membership_witness`](pathname:///aztec-nr-api/mainnet/noir_aztec/oracle/get_l1_to_l2_membership_witness/index.html) - Returns the leaf index and sibling path for an L1 to L2 message, used to prove message existence in cross-chain applications like token bridges.
+- [`notes`](pathname:///aztec-nr-api/mainnet/noir_aztec/oracle/notes/index.html) - Provides functions related to notes, such as fetching notes from storage, used behind the scenes for value notes and other pre-built note implementations.
+- [`logs`](pathname:///aztec-nr-api/mainnet/noir_aztec/oracle/logs/index.html) - Provides functions to log encrypted and unencrypted data.
 
 Find a full list [on GitHub](https://github.com/AztecProtocol/aztec-packages/tree/v4.1.0-rc.2/noir-projects/aztec-nr/aztec/src/oracle).
 

docs/developer_versioned_docs/version-v4.1.0-rc.2/docs/aztec-nr/installation.md

@@ -5,14 +5,24 @@ tags: [local network, sandbox]
 description: Learn how to install and configure the Noir Language Server for a better development experience.
 ---
 
-Install the [Noir Language Support extension](https://marketplace.visualstudio.com/items?itemName=noir-lang.vscode-noir) to get syntax highlighting, syntax error detection and go-to definitions for your Aztec contracts.
+Install the [Noir Language Support extension](https://marketplace.visualstudio.com/items?itemName=noir-lang.vscode-noir) to get syntax highlighting, syntax error detection, and go-to definitions for your Aztec contracts.
 
-Once the extension is installed, check your nargo binary by hovering over Nargo in the status bar on the bottom right of the application window. Click to choose the path to `aztec` (or regular nargo, if you have that installed).
-
-You can print the path of your `aztec` executable by running:
+The extension drives its language server with `nargo`. The Aztec installer installs its own version of `nargo` and adds that directory to your `PATH`, so in most cases you do not need to configure anything else. Verify the binary is on your `PATH`:
 
 ```bash
-which aztec
+which nargo
+# expected: $HOME/.aztec/<path to nargo binary>
 ```
 
-To specify a custom nargo executable, go to the VSCode settings and search for "noir", or click extension settings on the `noir-lang` LSP plugin. Update the `Noir: Nargo Path` field to point to your desired `aztec` executable.
+If you have not installed the Aztec toolchain yet, follow [Getting Started on Local Network](../../getting_started_on_local_network.md) first.
+
+## Configure the extension
+
+Leave the extension's `Noir: Nargo Path` setting empty so it auto-discovers `nargo` from your `PATH`. To confirm, hover over **Nargo** in the VSCode status bar in the bottom right corner — it should show the path under the result from `which nargo`.
+
+If auto-discovery fails, set `Noir: Nargo Path` to the absolute path printed by `which nargo`, then reload the window.
+
+## Troubleshooting
+
+- **LSP reports `startFailed` after setting a custom path**: clear `Noir: Nargo Path`, reload the window, and let auto-discovery take over.
+- **`which nargo` points outside `$HOME/.aztec/current/bin`**: another `nargo` earlier on your `PATH` is shadowing the Aztec-provided one. Either remove it or set `Noir: Nargo Path` explicitly to the Aztec-provided `nargo`.

docs/developer_versioned_docs/version-v4.1.0-rc.2/docs/aztec-nr/testing_contracts.md

@@ -67,7 +67,7 @@ unconstrained fn test_basic_flow() {
 
 - Tests run in parallel by default
 - Use `unconstrained` functions for faster execution
-- See all `TestEnvironment` methods [here](https://github.com/AztecProtocol/aztec-packages/blob/v4.1.0-rc.2/noir-projects/aztec-nr/aztec/src/test/helpers/test_environment.nr)
+- See all `TestEnvironment` methods [here](pathname:///aztec-nr-api/mainnet/noir_aztec/test/helpers/test_environment/struct.TestEnvironment)
 
 :::
 

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

@@ -37,11 +37,16 @@ Run:
 VERSION=4.1.0-rc.2 bash -i <(curl -sL https://install.aztec.network/4.1.0-rc.2)
 ```
 
-This will install the following tools:
+This will install the following tools and add them to your `PATH`:
 
-- **aztec** - compiles and tests aztec contracts and launches various infrastructure subsystems (full local network, sequencer, prover, pxe, etc) and provides utility commands to interact with the network
+- **nargo** - the Noir programming language compiler and simulator
+- **noir-profiler** - a profiler for analyzing and visualizing Noir programs
+- **bb** - the Barretenberg proving backend
+- **aztec** - compiles and tests Aztec contracts and launches various infrastructure subsystems (full local network, sequencer, prover, PXE, etc.) and provides utility commands to interact with the network
 - **aztec-up** - a version manager for the Aztec toolchain. Use `aztec-up install <version>` to install a new version, `aztec-up use <version>` to switch between installed versions, or `aztec-up list` to see installed versions.
-- **aztec-wallet** - a tool for interacting with the aztec network
+- **aztec-wallet** - a tool for interacting with the Aztec network
+
+For syntax highlighting and LSP support while editing contracts, see the [Noir VSCode Extension guide](./docs/aztec-nr/installation.md).
 
 ### Start the local network
 

docs/developer_versioned_docs/version-v4.2.0-aztecnr-rc.2/docs/aztec-js/how_to_create_account.md

@@ -15,7 +15,7 @@ This guide shows you how to create and deploy a new account on Aztec.
 ## Install dependencies
 
 ```bash
-yarn add @aztec/aztec.js@4.2.0-aztecnr-rc.2 @aztec/wallets@4.2.0-aztecnr-rc.2
+yarn add @aztec/aztec.js@4.2.0-aztecnr-rc.2 @aztec/wallets@4.2.0-aztecnr-rc.2 @aztec/noir-contracts.js@4.2.0-aztecnr-rc.2
 ```
 
 ## Create a new account
@@ -78,12 +78,28 @@ await deployMethod.send({
 
 
 :::info
-See the [guide on fees](./how_to_pay_fees.md#sponsored-fee-payment-contracts) for setting up the Sponsored FPC.
+See the [guide on fees](./how_to_pay_fees.md#sponsored-fee-payment-contracts) for more details on the Sponsored FPC and what this snippet means.
 :::
 
 ### Using Fee Juice
 
-If your account has Fee Juice from a [bridge from L1](./how_to_pay_fees.md#bridge-fee-juice-from-l1), you can claim it and deploy in one step using `FeeJuicePaymentMethodWithClaim`:
+If your account has Fee Juice from a [bridge from L1](./how_to_pay_fees.md#bridge-fee-juice-from-l1), you can claim it and deploy in one step using `FeeJuicePaymentMethodWithClaim`.
+
+Create a new Schnorr account for this path:
+
+```typescript title="create_fee_juice_account" showLineNumbers
+// `feeJuiceAccount` is just another Schnorr account — the same kind as
+// `newAccount` above. It gets its own name here so both deploy paths
+// can coexist in one example; in your own code, pick whichever name fits.
+const feeJuiceSecret = Fr.random();
+const feeJuiceSalt = Fr.random();
+const feeJuiceAccount = await wallet.createSchnorrAccount(
+  feeJuiceSecret,
+  feeJuiceSalt,
+);
+```
+
+Claim the bridged Fee Juice and deploy in one step:
 
 ```typescript title="bridge_fee_juice_claim" showLineNumbers
 import { FeeJuicePaymentMethodWithClaim } from "@aztec/aztec.js/fee";
@@ -106,10 +122,12 @@ The `from: NO_FROM` signals that this transaction should be executed without acc
 
 ## Verify deployment
 
-Confirm the account was deployed successfully:
+Confirm the account was deployed successfully. Substitute the account variable for whichever path you used above (`newAccount` for the Sponsored FPC path, `feeJuiceAccount` for the Fee Juice path):
 
 ```typescript title="verify_account_deployment" showLineNumbers 
-const metadata = await wallet.getContractMetadata(feeJuiceAccount.address);
+// `newAccount` refers to whichever account you just deployed —
+// either the Sponsored FPC account or `feeJuiceAccount` from the Fee Juice path.
+const metadata = await wallet.getContractMetadata(newAccount.address);
 console.log("Account deployed:", metadata.initializationStatus);
 ```
 > <sup><sub><a href="https://github.com/AztecProtocol/aztec-packages/blob/v4.2.0-aztecnr-rc.2/docs/examples/ts/aztecjs_connection/index.ts#L157-L160" target="_blank" rel="noopener noreferrer">Source code: docs/examples/ts/aztecjs_connection/index.ts#L157-L160</a></sub></sup>

docs/developer_versioned_docs/version-v4.2.0-aztecnr-rc.2/docs/aztec-nr/debugging.md

@@ -69,6 +69,8 @@ LOG_LEVEL="info;debug:simulator:client_execution_context;debug:simulator:client_
 - `level:module` - Sets level for a specific module
 - `level:module:submodule` - Sets level for a specific submodule
 
+**The default-level filter must be the first segment.** A bare `level:module` with no preceding default (e.g. `LOG_LEVEL="warn:simulator"`) is invalid and throws `Invalid log level`, because the parser reads everything before the first `;` as the default level. To filter only specific modules, lead with a default level — use `silent` to suppress everything else.
+
 ```bash
 # Default level only
 LOG_LEVEL="debug"
@@ -78,6 +80,9 @@ LOG_LEVEL="info;debug:simulator;debug:execution"
 
 # Default level + specific submodule overrides
 LOG_LEVEL="info;debug:simulator:client_execution_context;debug:simulator:client_view_context"
+
+# Silence everything except one module
+LOG_LEVEL="silent;debug:simulator"
 ```
 
 :::

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

@@ -90,7 +90,7 @@ use balance_set::BalanceSet;
 - `messages::message_delivery::MessageDelivery`
   Imports `MessageDelivery` for specifying how note delivery should be handled (e.g., constrained onchain delivery).
 
-- `oracle::debug_log::debug_log_format`
+- `oracle::logging::debug_log_format`
   Imports a debug logging utility for printing formatted messages during contract execution.
 
 - `protocol::{address::AztecAddress, traits::ToField}`