chore: backport feat: allow setting additional scopes in nr tests (#22968) to v4-next (#23057)

Backport of #22968 ("feat: allow setting additional scopes in nr tests")
to `backport-to-v4-next-staging`.

Rebased on top of latest staging (which now includes the backport of
#22889 — `feat(txe): add tx private logs to tx side effects oracle`).
All conflicts handled in a single resolution commit.

## What

The PR adds `call_private_opts` / `view_private_opts` (with
`CallPrivateOptions` / `ViewPrivateOptions`) to `TestEnvironment`,
letting tests grant access to additional account scopes when calling
private functions. It also reshapes the TXE oracle ABI for
`private_call_new_flow` / `public_call_new_flow` to take an
`Option<AztecAddress>` for `from`, removes `call_public_incognito`'s
ignored `from` parameter, deprecates `view_public_incognito`, and
introduces `AztecAddress.NULL_MSG_SENDER` on the TS side.

## Conflicts handled (single commit)

After rebasing, four files still drifted vs `next`:

- **`noir-projects/aztec-nr/aztec/src/test/helpers/txe_oracles.nr`** —
with #22889 now on staging, the imports here match `next` exactly aside
from `NULL_MSG_SENDER_CONTRACT_ADDRESS`. Just drop that one symbol (the
PR removes its only use).
- **`docs/docs-developers/docs/resources/migration_notes.md`** — keep
only the two new TBD entries from #22968. The DeployMethod and
`aztec-up` bundled-binary entries that the cherry-pick brought along
belong to other PRs not yet backported (e.g. #22985); leave them out so
those backports add them in their own PRs.
-
**`yarn-project/pxe/src/contract_function_simulator/oracle/private_execution.test.ts`**
— drop `NULL_MSG_SENDER_CONTRACT_ADDRESS` (replaced by
`AztecAddress.NULL_MSG_SENDER`). Keep `L1_TO_L2_MSG_TREE_HEIGHT`,
`NOTE_HASH_TREE_HEIGHT`, `PUBLIC_DATA_TREE_HEIGHT` — they're still in
use on this branch since #21577 hasn't been backported.
- **`yarn-project/stdlib/src/aztec-address/index.ts`** — keep both the
existing `eslint-disable
@typescript-eslint/no-unsafe-declaration-merging` comment and the new
`NULL_MSG_SENDER_CONTRACT_ADDRESS` import.

## Verification

- `nargo check` passes for both Noir contracts the PR touches
(`scope_test_contract`, `public_checks_contract`).
- No conflict markers remain.

Original PR: #22968

Author: nchamo

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());
+```
+
 ### [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:

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

@@ -7,8 +7,8 @@ use crate::protocol::{
     abis::function_selector::FunctionSelector,
     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,
+        CONTRACT_INSTANCE_LENGTH, MAX_NOTE_HASHES_PER_TX, MAX_NULLIFIERS_PER_TX, MAX_PRIVATE_LOGS_PER_TX,
+        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)
 }
 
@@ -109,8 +109,7 @@ pub struct TxEffects {
 
 /// Returns the effects of the last transaction included by the TXE.
 pub unconstrained fn get_last_tx_effects() -> TxEffects {
-    let (tx_hash, note_hashes, nullifiers, raw_log_storage, log_lengths, log_count) =
-        get_last_tx_effects_oracle();
+    let (tx_hash, note_hashes, nullifiers, raw_log_storage, log_lengths, log_count) = get_last_tx_effects_oracle();
 
     let mut private_logs = BoundedVec::new();
     for i in 0..log_count {
@@ -121,14 +120,7 @@ pub unconstrained fn get_last_tx_effects() -> TxEffects {
 }
 
 #[oracle(aztec_txe_getLastTxEffects)]
-unconstrained fn get_last_tx_effects_oracle() -> (
-    Field,
-    TxNoteHashes,
-    TxNullifiers,
-    [[Field; PRIVATE_LOG_SIZE_IN_FIELDS]; MAX_PRIVATE_LOGS_PER_TX],
-    [u32; MAX_PRIVATE_LOGS_PER_TX],
-    u32,
-) {}
+unconstrained fn get_last_tx_effects_oracle() -> (Field, TxNoteHashes, TxNullifiers, [[Field; PRIVATE_LOG_SIZE_IN_FIELDS]; MAX_PRIVATE_LOGS_PER_TX], [u32; MAX_PRIVATE_LOGS_PER_TX], u32) {}
 
 /// Returns the raw offchain effect payloads emitted by the last top-level call into TXE.
 /// Each effect is a variable-length field array (e.g. offchain messages have a different size
@@ -217,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,

noir-projects/noir-contracts/contracts/protocol/public_checks_contract/src/test.nr

@@ -13,7 +13,7 @@ unconstrained fn check_block_number() {
     let public_checks = PublicChecks::at(public_checks_contract_address);
 
     let expected_next_block_number = env.next_block_number();
-    env.view_public_incognito(public_checks.check_block_number(Comparator.LT, expected_next_block_number + 1));
+    env.view_public(public_checks.check_block_number(Comparator.LT, expected_next_block_number + 1));
 }
 
 #[test(should_fail_with = "Block number mismatch.")]
@@ -24,7 +24,7 @@ unconstrained fn check_block_number_fail() {
     let public_checks = PublicChecks::at(public_checks_contract_address);
 
     let expected_next_block_number = env.next_block_number();
-    env.view_public_incognito(public_checks.check_block_number(Comparator.LT, expected_next_block_number));
+    env.view_public(public_checks.check_block_number(Comparator.LT, expected_next_block_number));
 }
 
 #[test]
@@ -36,7 +36,7 @@ unconstrained fn check_timestamp() {
 
     let expected_next_block_timestamp = env.last_block_timestamp() + 100;
     env.set_next_block_timestamp(expected_next_block_timestamp);
-    env.view_public_incognito(public_checks.check_timestamp(Comparator.LT, expected_next_block_timestamp + 1));
+    env.view_public(public_checks.check_timestamp(Comparator.LT, expected_next_block_timestamp + 1));
 }
 
 #[test(should_fail_with = "Timestamp mismatch.")]
@@ -48,5 +48,5 @@ unconstrained fn check_timestamp_fail() {
 
     let expected_next_block_timestamp = env.last_block_timestamp() + 100;
     env.set_next_block_timestamp(expected_next_block_timestamp);
-    env.view_public_incognito(public_checks.check_timestamp(Comparator.LT, expected_next_block_timestamp));
+    env.view_public(public_checks.check_timestamp(Comparator.LT, expected_next_block_timestamp));
 }