feat: merge-train/fairies (#23055)

BEGIN_COMMIT_OVERRIDE
feat: allow setting additional scopes in nr tests (#22968)
feat(pxe): add execution hooks for authorizing cross-contract utility
calls (#23007)
END_COMMIT_OVERRIDE

Author: AztecBot

docs/docs-developers/docs/aztec-nr/debugging.md

@@ -35,6 +35,33 @@ LOG_LEVEL=verbose aztec start --local-network
 | `No public key registered for address`                   | Call `wallet.registerSender(...)`                                                                                                                               |
 | `Direct invocation of ... functions is not supported`    | Use `self.call()`, `self.view()`, or `self.enqueue()` to [call contract functions](framework-description/calling_contracts.md) |
 | `Failed to solve brillig function`                       | Check function parameters and note validity                                                                                                                     |
+| `Cross-contract utility call denied`                     | Configure an `authorizeUtilityCall` [execution hook](#cross-contract-utility-call-denied) on your PXE                                                           |
+
+#### Cross-contract utility call denied
+
+When a contract executes a utility function that calls into a different contract, PXE asks an **execution hook** whether the call should be allowed. If no hook is configured, or the hook denies the request, you will see:
+
+```
+Cross-contract utility call denied: <reason>. <caller> attempted to call <target>:<selector> (<name>).
+```
+
+To fix this, pass an `authorizeUtilityCall` hook when creating your PXE:
+
+```typescript
+import { PXE } from "@aztec/pxe/server";
+
+const pxe = await PXE.create({
+  // ...other options
+  hooks: {
+    authorizeUtilityCall: async (request) => {
+      // Inspect request.caller, request.target, request.functionSelector, etc.
+      return { authorized: true };
+    },
+  },
+});
+```
+
+The hook receives a `UtilityCallAuthorizationRequest` with the caller address, target address, function selector, function name, arguments, and caller context (`'private'` or `'utility'`). Return `{ authorized: true }` to allow or `{ authorized: false, reason: '...' }` to deny with a message.
 
 ### Circuit Errors
 

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

@@ -9,6 +9,26 @@ Aztec is in active development. Each version may introduce breaking changes that
 
 ## TBD
 
+### [Aztec.nr] TXE `call_public_incognito` no longer takes a `from` parameter
+
+`TestEnvironment::call_public_incognito` previously accepted a `from` address that was silently ignored (the function always uses a null `msg_sender`). The `from` parameter has been removed.
+
+```diff
+- env.call_public_incognito(sender, SampleContract::at(addr).some_function());
++ env.call_public_incognito(SampleContract::at(addr).some_function());
+```
+
+If you need to call a public function *with* a sender, use `call_public` instead.
+
+### [Aztec.nr] TXE `view_public_incognito` is deprecated
+
+`TestEnvironment::view_public_incognito` is now deprecated in favor of `view_public`, which has the same behavior (null `msg_sender`, static call).
+
+```diff
+- env.view_public_incognito(SampleContract::at(addr).some_view());
++ env.view_public(SampleContract::at(addr).some_view());
+```
+
 ### [Aztec.js] `DeployMethod` address-affecting parameters move to construction time
 
 Salt, deployer, and public keys are now passed when the `DeployMethod` is constructed, not on every call to `send` / `simulate` / `request` / `getInstance`. This locks the contract address once it is determined and prevents the silent salt-cache poisoning bug where the address could change between calls.

docs/netlify.toml

@@ -813,3 +813,8 @@
     # PXE: capsule operation attempted with a scope not in the allowed scopes list
     from = "/errors/10"
     to = "/developers/docs/aztec-nr/framework-description/advanced/how_to_use_capsules"
+
+[[redirects]]
+    # PXE: cross-contract utility call denied by execution hook
+    from = "/errors/11"
+    to = "/developers/docs/aztec-nr/debugging#cross-contract-utility-call-denied"

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

@@ -125,6 +125,80 @@ struct UtilityContextOptions {
     contract_address: Option<AztecAddress>,
 }
 
+/// Configuration for [`TestEnvironment::call_private_opts`].
+///
+/// Constructed by calling [`CallPrivateOptions::new`] and then chaining methods setting each value:
+///
+/// ```noir
+/// env.call_private_opts(from, CallPrivateOptions::new().with_additional_scopes([other]), call);
+/// ```
+pub struct CallPrivateOptions<let N: u32> {
+    additional_scopes: [AztecAddress; N],
+}
+
+impl CallPrivateOptions<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: [] }
+    }
+}
+
+impl<let N: u32> CallPrivateOptions<N> {
+    /// 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
+    /// retrieve private information from other accounts during execution.
+    ///
+    /// 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,
+        additional_scopes: [AztecAddress; N_2],
+    ) -> CallPrivateOptions<N_2> {
+        CallPrivateOptions { additional_scopes }
+    }
+}
+
+/// Configuration for [`TestEnvironment::view_private_opts`].
+///
+/// Constructed by calling [`ViewPrivateOptions::new`] and then chaining methods setting each value:
+///
+/// ```noir
+/// env.view_private_opts(from, ViewPrivateOptions::new().with_additional_scopes([other]), call);
+/// ```
+pub struct ViewPrivateOptions<let S: u32> {
+    additional_scopes: [AztecAddress; S],
+}
+
+impl ViewPrivateOptions<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: [] }
+    }
+}
+
+impl<let S: u32> ViewPrivateOptions<S> {
+    /// 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
+    /// retrieve private information from other accounts during execution.
+    ///
+    /// 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,
+        additional_scopes: [AztecAddress; S2],
+    ) -> ViewPrivateOptions<S2> {
+        ViewPrivateOptions { additional_scopes }
+    }
+}
+
 struct NoteDiscoveryOptions {
     contract_address: Option<AztecAddress>,
 }
@@ -544,20 +618,34 @@ impl TestEnvironment {
     /// let return_value = env.call_private(caller, SampleContract::at(contract_addr).sample_private_function());
     /// ```
     pub unconstrained fn call_private<let M: u32, let N: u32, T>(
+        self: Self,
+        from: AztecAddress,
+        call: PrivateCall<M, N, T>,
+    ) -> T
+    where
+        T: Deserialize,
+    {
+        self.call_private_opts(from, CallPrivateOptions::new(), call)
+    }
+
+    /// 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>(
         _self: Self,
         from: AztecAddress,
+        opts: CallPrivateOptions<S>,
         call: PrivateCall<M, N, T>,
     ) -> T
     where
         T: Deserialize,
     {
         let serialized_return_values = txe_oracles::private_call_new_flow(
-            from,
+            Option::some(from),
             call.target_contract,
             call.selector,
             call.args,
             hash_args(call.args),
             /*is_static=*/ false,
+            opts.additional_scopes,
         );
 
         T::deserialize(serialized_return_values)
@@ -571,20 +659,34 @@ impl TestEnvironment {
     /// The `from` parameter specifies the account from whose perspective the view is executed. This affects
     /// scope isolation - only notes scoped to this account will be visible during execution.
     pub unconstrained fn view_private<let M: u32, let N: u32, T>(
+        self: Self,
+        from: AztecAddress,
+        call: PrivateStaticCall<M, N, T>,
+    ) -> T
+    where
+        T: Deserialize,
+    {
+        self.view_private_opts(from, ViewPrivateOptions::new(), call)
+    }
+
+    /// 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>(
         _self: Self,
         from: AztecAddress,
+        opts: ViewPrivateOptions<S>,
         call: PrivateStaticCall<M, N, T>,
     ) -> T
     where
         T: Deserialize,
     {
         let serialized_return_values = txe_oracles::private_call_new_flow(
-            from,
+            Option::some(from),
             call.target_contract,
             call.selector,
             call.args,
             hash_args(call.args),
             /*is_static=*/ true,
+            opts.additional_scopes,
         );
 
         T::deserialize(serialized_return_values)
@@ -705,16 +807,12 @@ impl TestEnvironment {
     /// Performs a public contract function call, including the processing of any nested public calls. Returns the
     /// result of the called function. Variant of `call_public`, but the `from` address (`msg_sender`) is set to
     /// "null".
-    pub unconstrained fn call_public_incognito<let M: u32, let N: u32, T>(
-        _self: Self,
-        from: AztecAddress,
-        call: PublicCall<M, N, T>,
-    ) -> T
+    pub unconstrained fn call_public_incognito<let M: u32, let N: u32, T>(_self: Self, call: PublicCall<M, N, T>) -> T
     where
         T: Deserialize,
     {
         let serialized_return_values = txe_oracles::public_call_new_flow(
-            Option::some(from),
+            Option::none(),
             call.target_contract,
             call.selector,
             call.args,
@@ -727,13 +825,14 @@ impl TestEnvironment {
     /// Variant of `call_public` for public `#[view]` functions.
     ///
     /// Unlike `call_public`, no transaction is created and no block is mined (since `#[view]` functions are only
-    /// executable in a static context, and these produce no side effects).
+    /// executable in a static context, and these produce no side effects). The `msg_sender` is set to "null", since
+    /// view calls have no real caller.
     pub unconstrained fn view_public<let M: u32, let N: u32, T>(_self: Self, call: PublicStaticCall<M, N, T>) -> T
     where
         T: Deserialize,
     {
         let serialized_return_values = txe_oracles::public_call_new_flow(
-            Option::some(AztecAddress::zero()),
+            Option::none(),
             call.target_contract,
             call.selector,
             call.args,
@@ -743,26 +842,15 @@ impl TestEnvironment {
         T::deserialize(serialized_return_values)
     }
 
-    /// Variant of `view_public`, but the `from` address (`msg_sender`) is set to "null"
-    ///
-    /// Unlike `call_public`, no transaction is created and no block is mined (since `#[view]` functions are only
-    /// executable in a static context, and these produce no side effects).
+    #[deprecated("use `TestEnvironment::view_public` instead")]
     pub unconstrained fn view_public_incognito<let M: u32, let N: u32, T>(
-        _self: Self,
+        self: Self,
         call: PublicStaticCall<M, N, T>,
     ) -> T
     where
         T: Deserialize,
     {
-        let serialized_return_values = txe_oracles::public_call_new_flow(
-            Option::none(),
-            call.target_contract,
-            call.selector,
-            call.args,
-            true,
-        );
-
-        T::deserialize(serialized_return_values)
+        self.view_public(call)
     }
 
     /// Discovers a note from a [`NoteMessage`], which is expected to have been created in the last transaction

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

@@ -8,7 +8,7 @@ use crate::protocol::{
     address::AztecAddress,
     constants::{
         CONTRACT_INSTANCE_LENGTH, MAX_NOTE_HASHES_PER_TX, MAX_NULLIFIERS_PER_TX, MAX_PRIVATE_LOGS_PER_TX,
-        NULL_MSG_SENDER_CONTRACT_ADDRESS, PRIVATE_LOG_SIZE_IN_FIELDS,
+        PRIVATE_LOG_SIZE_IN_FIELDS,
     },
     contract_instance::ContractInstance,
     traits::{Deserialize, ToField},
@@ -36,13 +36,14 @@ pub unconstrained fn deploy<let M: u32, let N: u32, let P: u32>(
     ContractInstance::deserialize(instance_fields)
 }
 
-pub unconstrained fn private_call_new_flow<let M: u32, let N: u32>(
-    from: AztecAddress,
+pub unconstrained fn private_call_new_flow<let M: u32, let N: u32, let S: u32>(
+    from: Option<AztecAddress>,
     contract_address: AztecAddress,
     function_selector: FunctionSelector,
     args: [Field; M],
     args_hash: Field,
     is_static_call: bool,
+    additional_scopes: [AztecAddress; S],
 ) -> [Field; N] {
     private_call_new_flow_oracle(
         from,
@@ -51,6 +52,7 @@ pub unconstrained fn private_call_new_flow<let M: u32, let N: u32>(
         args,
         args_hash,
         is_static_call,
+        additional_scopes,
     )
 }
 
@@ -63,8 +65,6 @@ pub unconstrained fn public_call_new_flow<let M: u32, let N: u32>(
 ) -> [Field; N] {
     let calldata = [function_selector.to_field()].concat(args);
 
-    let from = from.unwrap_or(NULL_MSG_SENDER_CONTRACT_ADDRESS);
-
     public_call_new_flow_oracle(from, contract_address, calldata, is_static_call)
 }
 
@@ -209,18 +209,19 @@ pub unconstrained fn add_account(secret: Field) -> TestAccount {}
 pub unconstrained fn add_authwit(address: AztecAddress, message_hash: Field) {}
 
 #[oracle(aztec_txe_privateCallNewFlow)]
-unconstrained fn private_call_new_flow_oracle<let M: u32, let N: u32>(
-    _from: AztecAddress,
+unconstrained fn private_call_new_flow_oracle<let M: u32, let N: u32, let S: u32>(
+    _from: Option<AztecAddress>,
     _contract_address: AztecAddress,
     _function_selector: FunctionSelector,
     _args: [Field; M],
     _args_hash: Field,
     _is_static_call: bool,
+    _additional_scopes: [AztecAddress; S],
 ) -> [Field; N] {}
 
 #[oracle(aztec_txe_publicCallNewFlow)]
 unconstrained fn public_call_new_flow_oracle<let M: u32, let N: u32>(
-    from: AztecAddress,
+    from: Option<AztecAddress>,
     contract_address: AztecAddress,
     calldata: [Field; M],
     is_static_call: bool,