Merge branch 'next' into ad/chore/ci-release-pr-canary

Author: AztecBot

CLAUDE.md

@@ -107,6 +107,16 @@ Do not explain *what* the code does — well-named identifiers cover that. Comme
 Do not reference the current task, PR, caller, or author (`// used by X`, `// fix for issue #123`, `// AI-generated`), and do not add banner-style section comments (`// ===== HELPERS =====`). Both rot the moment the surrounding code is moved.
 </writing_comments>
 
+<jargon>
+Avoid recurring AI-isms in chat replies, PR descriptions, commit messages, code comments, and docs. Substitutes:
+
+- **"load bearing"** → *important*, *critical*, *required*, or describe the actual dependency (e.g. "the scheduler relies on this invariant").
+- **"seam"** (for an interaction point or boundary) → *interface*, *boundary*, *call site*, *integration point*.
+- **"north star"** → *goal*, *main goal*, *objective*.
+- **"sharpening"** (for adding detail or refining wording) → *clarifying*, *adding detail*, *tightening*, *refining*.
+- **"You're absolutely right"** and effusive agreement openers (*"Great catch!"*, *"Excellent point!"*) → never lead a reply with these. A short acknowledgement (*"Right — …"*, *"Agreed."*) is fine, and a closing *"you're right"* at the end of a long reply is acceptable when warranted. Lead with substance, not validation.
+</jargon>
+
 <attribution>
 Attribute work to the git author, not to Claude. Do not add `Co-Authored-By: Claude` trailers or `Generated with Claude Code` in PR descriptions. The git author (from `git config user.name`) is the author of record.
 </attribution>

Makefile

@@ -301,7 +301,6 @@ aztec-nr: noir bb-cpp-native
 noir-projects-txe-tests:
 	$(call test,$@,noir-projects/aztec-nr)
 	$(call test,$@,noir-projects/noir-contracts)
-	$(call test,$@,noir-projects/noir-contracts-comp-failures)
 
 # Noir Projects - Aggregate target (builds all sub-projects)
 noir-projects: noir-protocol-circuits mock-protocol-circuits noir-contracts aztec-nr

barretenberg/bbup/bb-versions.json

@@ -1,4 +1,5 @@
 {
+  "1.0.0-beta.21": "5.0.0-nightly.20260324",
   "1.0.0-beta.20": "5.0.0-nightly.20260324",
   "1.0.0-beta.19": "4.0.0-nightly.20260120",
   "1.0.0-beta.18": "3.0.0-nightly.20260102",

cspell.json

@@ -71,6 +71,7 @@
     "cimg",
     "ciphertext",
     "ciphertexts",
+    "clippy",
     "clonedeep",
     "clonedeepwith",
     "cmd",
@@ -171,6 +172,7 @@
     "includable",
     "incrementation",
     "indexeddb",
+    "INSTA",
     "interruptible",
     "IPFS",
     "isequal",
@@ -367,8 +369,8 @@
     "unfinalized",
     "uniquified",
     "uniquify",
-    "unlinkability",
     "unkonstrained",
+    "unlinkability",
     "unnullify",
     "unpadded",
     "unprefixed",

docs/docs-developers/docs/aztec-js/how_to_test.md

@@ -83,6 +83,24 @@ const result = await contract.methods.read_balance(account).simulate({
 
 Use this to set up state preconditions, reproduce production bugs against pinned storage, or exercise rare value branches without orchestrating the contract calls that produce them.
 
+### Fast-forwarding a contract update
+
+`fastForwardContractUpdate` returns a `SimulationOverrides` object that simulates a deployed instance as if it had already been upgraded to a new contract class. The new class must already be registered on chain. The cheat mirrors a real `pxe.updateContract` followed by waiting out the upgrade delay: the instance's `currentContractClassId` is bumped, and the `ContractInstanceRegistry`'s delayed-public-mutable storage is rewritten to look like the upgrade was scheduled in the past.
+
+```typescript
+import { fastForwardContractUpdate } from '@aztec/aztec.js';
+
+const overrides = await fastForwardContractUpdate({
+  instanceAddress: contract.address,
+  newClassId: upgradedClass.id,
+  node,
+});
+
+const result = await contract.methods.upgraded_method().simulate({ overrides });
+```
+
+Use this to test code paths that only execute after an upgrade, without orchestrating the full delayed-mutable upgrade flow.
+
 ## Further reading
 
 - [How to read contract data](./how_to_read_data.md)

docs/docs-developers/docs/resources/migration_notes.md

@@ -185,6 +185,19 @@ Direct callers of the `SimulationOverrides` constructor must switch from a posit
 + new SimulationOverrides({ contracts });
 ```
 
+`overrides.contracts` swaps contract instances in the simulator's contract DB — useful for simulating a contract being on a different class than the one it was deployed with. To simulate a complete onchain upgrade flow, use the `fastForwardContractUpdate` helper which returns a `SimulationOverrides` covering both registry storage rewrites and the upgraded instance entry:
+
+```typescript
+import { fastForwardContractUpdate } from '@aztec/aztec.js';
+
+const overrides = await fastForwardContractUpdate({
+  instanceAddress: contract.address,
+  newClassId: upgradedClass.id,
+  node,
+});
+const result = await contract.methods.upgraded_method().simulate({ overrides });
+```
+
 ### [PXE] `proveTx` takes an options bag
 
 `PXE.proveTx` used to accept `scopes` as a positional argument; it now takes an options bag consistent with `simulateTx` and `profileTx`, and adds an optional `senderForTags` field. Update direct callers:

docs/docusaurus.config.js

@@ -315,6 +315,11 @@ const config = {
           ],
           apiKey: "gpH8o2YnqsOEj2jgtIMTULbtHi1kZ2X3", // public search-only api key, safe to commit
         },
+        // aztec-nr-api pages live in /static/ as raw HTML, not React Router
+        // routes. Without this, the dropdown calls history.push() and the SPA
+        // 404s on click. Matching the regex makes the theme use
+        // window.location.href for a real page load that Netlify resolves.
+        externalUrlRegex: "/aztec-nr-api/",
       },
       colorMode: {
         defaultMode: "light",

noir-projects/aztec-nr/aztec/src/test/helpers/test_environment.nr

@@ -132,21 +132,22 @@ struct UtilityContextOptions {
 /// ```noir
 /// env.call_private_opts(from, CallPrivateOptions::new().with_additional_scopes([other]), call);
 /// ```
-pub struct CallPrivateOptions<let N: u32> {
+pub struct CallPrivateOptions<let N: u32, let T: u32> {
     additional_scopes: [AztecAddress; N],
+    authorized_utility_call_targets: [AztecAddress; T],
 }
 
-impl CallPrivateOptions<0> {
+impl CallPrivateOptions<0, 0> {
     /// Creates default `CallPrivateOptions`.
     ///
     /// The default values are the same as if using [`TestEnvironment::call_private`] instead of
     /// [`TestEnvironment::call_private_opts`].
     pub fn new() -> Self {
-        CallPrivateOptions { additional_scopes: [] }
+        CallPrivateOptions { additional_scopes: [], authorized_utility_call_targets: [] }
     }
 }
 
-impl<let N: u32> CallPrivateOptions<N> {
+impl<let N: u32, let T: u32> CallPrivateOptions<N, T> {
     /// Grants access to secrets of additional accounts.
     ///
     /// By default only the secrets that belong to the `from` account can be accessed: this function lets contracts
@@ -155,10 +156,27 @@ impl<let N: u32> CallPrivateOptions<N> {
     /// Example usage includes accounts withdrawing from an escrow, which may require accessing the escrow's own notes
     /// and secrets.
     pub fn with_additional_scopes<let N_2: u32>(
-        _self: Self,
+        self,
         additional_scopes: [AztecAddress; N_2],
-    ) -> CallPrivateOptions<N_2> {
-        CallPrivateOptions { additional_scopes }
+    ) -> CallPrivateOptions<N_2, T> {
+        CallPrivateOptions {
+            additional_scopes,
+            authorized_utility_call_targets: self.authorized_utility_call_targets,
+        }
+    }
+
+    /// Authorizes cross-contract utility calls to the given target contracts during this call.
+    ///
+    /// By default, cross-contract utility calls are denied. This method lets the test author specify which target
+    /// contracts are allowed to be called via utility functions during execution.
+    pub fn with_authorized_utility_call_targets<let T_2: u32>(
+        self,
+        targets: [AztecAddress; T_2],
+    ) -> CallPrivateOptions<N, T_2> {
+        CallPrivateOptions {
+            additional_scopes: self.additional_scopes,
+            authorized_utility_call_targets: targets,
+        }
     }
 }
 
@@ -169,21 +187,22 @@ impl<let N: u32> CallPrivateOptions<N> {
 /// ```noir
 /// env.view_private_opts(from, ViewPrivateOptions::new().with_additional_scopes([other]), call);
 /// ```
-pub struct ViewPrivateOptions<let S: u32> {
+pub struct ViewPrivateOptions<let S: u32, let T: u32> {
     additional_scopes: [AztecAddress; S],
+    authorized_utility_call_targets: [AztecAddress; T],
 }
 
-impl ViewPrivateOptions<0> {
+impl ViewPrivateOptions<0, 0> {
     /// Creates default `ViewPrivateOptions`.
     ///
     /// The default values are the same as if using [`TestEnvironment::view_private`] instead of
     /// [`TestEnvironment::view_private_opts`].
     pub fn new() -> Self {
-        ViewPrivateOptions { additional_scopes: [] }
+        ViewPrivateOptions { additional_scopes: [], authorized_utility_call_targets: [] }
     }
 }
 
-impl<let S: u32> ViewPrivateOptions<S> {
+impl<let S: u32, let T: u32> ViewPrivateOptions<S, T> {
     /// Grants access to secrets of additional accounts.
     ///
     /// By default only the secrets that belong to the `from` account can be accessed: this function lets contracts
@@ -192,10 +211,27 @@ impl<let S: u32> ViewPrivateOptions<S> {
     /// Example usage includes accounts querying an escrow's balance, which may require accessing the escrow's own
     /// notes.
     pub fn with_additional_scopes<let S2: u32>(
-        _self: Self,
+        self,
         additional_scopes: [AztecAddress; S2],
-    ) -> ViewPrivateOptions<S2> {
-        ViewPrivateOptions { additional_scopes }
+    ) -> ViewPrivateOptions<S2, T> {
+        ViewPrivateOptions {
+            additional_scopes,
+            authorized_utility_call_targets: self.authorized_utility_call_targets,
+        }
+    }
+
+    /// Authorizes cross-contract utility calls to the given target contracts during this call.
+    ///
+    /// By default, cross-contract utility calls are denied. This method lets the test author specify which target
+    /// contracts are allowed to be called via utility functions during execution.
+    pub fn with_authorized_utility_call_targets<let T_2: u32>(
+        self,
+        targets: [AztecAddress; T_2],
+    ) -> ViewPrivateOptions<S, T_2> {
+        ViewPrivateOptions {
+            additional_scopes: self.additional_scopes,
+            authorized_utility_call_targets: targets,
+        }
     }
 }
 
@@ -207,6 +243,40 @@ struct EventDiscoveryOptions {
     contract_address: Option<AztecAddress>,
 }
 
+/// Configuration for [`TestEnvironment::execute_utility_opts`].
+///
+/// Constructed by calling [`ExecuteUtilityOptions::new`] and then chaining methods:
+///
+/// ```noir
+/// env.execute_utility_opts(
+///     ExecuteUtilityOptions::new().with_authorized_utility_call_targets([target]),
+///     SomeContract::at(addr).some_utility_function(),
+/// );
+/// ```
+pub struct ExecuteUtilityOptions<let T: u32> {
+    authorized_utility_call_targets: [AztecAddress; T],
+}
+
+impl ExecuteUtilityOptions<0> {
+    /// Creates default `ExecuteUtilityOptions`.
+    pub fn new() -> Self {
+        ExecuteUtilityOptions { authorized_utility_call_targets: [] }
+    }
+}
+
+impl<let T: u32> ExecuteUtilityOptions<T> {
+    /// Authorizes cross-contract utility calls to the given target contracts during this call.
+    ///
+    /// By default, cross-contract utility calls are denied. This method lets the test author specify which target
+    /// contracts are allowed to be called via utility functions during execution.
+    pub fn with_authorized_utility_call_targets<let T_2: u32>(
+        _self: Self,
+        targets: [AztecAddress; T_2],
+    ) -> ExecuteUtilityOptions<T_2> {
+        ExecuteUtilityOptions { authorized_utility_call_targets: targets }
+    }
+}
+
 /// Configuration values for [`TestEnvironment::deploy_opts`]. Meant to be used by calling `new` and then chaining
 /// methods setting each value, e.g.:
 /// ```noir
@@ -629,10 +699,10 @@ impl TestEnvironment {
     }
 
     /// Variant of `call_private` which allows specifying multiple configuration values via `CallPrivateOptions`.
-    pub unconstrained fn call_private_opts<let M: u32, let N: u32, let S: u32, T>(
+    pub unconstrained fn call_private_opts<let M: u32, let N: u32, let S: u32, let U: u32, T>(
         _self: Self,
         from: AztecAddress,
-        opts: CallPrivateOptions<S>,
+        opts: CallPrivateOptions<S, U>,
         call: PrivateCall<M, N, T>,
     ) -> T
     where
@@ -646,6 +716,7 @@ impl TestEnvironment {
             hash_args(call.args),
             /*is_static=*/ false,
             opts.additional_scopes,
+            opts.authorized_utility_call_targets,
         );
 
         T::deserialize(serialized_return_values)
@@ -670,10 +741,10 @@ impl TestEnvironment {
     }
 
     /// Variant of `view_private` which allows specifying multiple configuration values via `ViewPrivateOptions`.
-    pub unconstrained fn view_private_opts<let M: u32, let N: u32, let S: u32, T>(
+    pub unconstrained fn view_private_opts<let M: u32, let N: u32, let S: u32, let U: u32, T>(
         _self: Self,
         from: AztecAddress,
-        opts: ViewPrivateOptions<S>,
+        opts: ViewPrivateOptions<S, U>,
         call: PrivateStaticCall<M, N, T>,
     ) -> T
     where
@@ -687,6 +758,7 @@ impl TestEnvironment {
             hash_args(call.args),
             /*is_static=*/ true,
             opts.additional_scopes,
+            opts.authorized_utility_call_targets,
         );
 
         T::deserialize(serialized_return_values)
@@ -701,12 +773,32 @@ impl TestEnvironment {
     /// let contract_addr = env.deploy("SampleContract").without_initializer();
     /// let return_value = env.execute_utility(SampleContract::at(contract_addr).sample_utility_function());
     /// ```
-    pub unconstrained fn execute_utility<let M: u32, let N: u32, T>(_self: Self, call: UtilityCall<M, N, T>) -> T
+    pub unconstrained fn execute_utility<let M: u32, let N: u32, T>(
+        self: Self,
+        call: UtilityCall<M, N, T>,
+    ) -> T
     where
         T: Deserialize,
     {
-        let serialized_return_values =
-            txe_oracles::execute_utility_function(call.target_contract, call.selector, call.args);
+        self.execute_utility_opts(ExecuteUtilityOptions::new(), call)
+    }
+
+    /// Variant of `execute_utility` which allows specifying configuration values via `ExecuteUtilityOptions`, such as
+    /// authorizing cross-contract utility calls.
+    pub unconstrained fn execute_utility_opts<let M: u32, let N: u32, let U: u32, T>(
+        _self: Self,
+        opts: ExecuteUtilityOptions<U>,
+        call: UtilityCall<M, N, T>,
+    ) -> T
+    where
+        T: Deserialize,
+    {
+        let serialized_return_values = txe_oracles::execute_utility_function(
+            call.target_contract,
+            call.selector,
+            call.args,
+            opts.authorized_utility_call_targets,
+        );
 
         T::deserialize(serialized_return_values)
     }