chore: rename simulateUtility -> executeUtility

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

@@ -9,6 +9,27 @@ Aztec is in active development. Each version may introduce breaking changes that
 
 ## TBD
 
+### `simulateUtility` renamed to `executeUtility`
+
+The `simulateUtility` method and related types have been renamed to `executeUtility` across the entire stack to better reflect that utility functions are executed, not simulated.
+
+**TypeScript:**
+
+```diff
+- import { SimulateUtilityOptions, UtilitySimulationResult } from '@aztec/aztec.js';
++ import { ExecuteUtilityOptions, UtilityExecutionResult } from '@aztec/aztec.js';
+
+- const result: UtilitySimulationResult = await wallet.simulateUtility(functionCall, opts);
++ const result: UtilityExecutionResult = await wallet.executeUtility(functionCall, opts);
+```
+
+**Noir (test environment):**
+
+```diff
+- let result = env.simulate_utility(my_contract_address, selector);
++ let result = env.execute_utility(my_contract_address, selector);
+```
+
 ### [Protocol] `include_by_timestamp` renamed to `expiration_timestamp`
 
 The `include_by_timestamp` field has been renamed to `expiration_timestamp` across the protocol to better convey its meaning.

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

@@ -550,14 +550,14 @@ impl TestEnvironment {
     /// ```noir
     /// let caller = env.create_light_account();
     /// let contract_addr = env.deploy("SampleContract").without_initializer();
-    /// let return_value = env.simulate_utility(SampleContract::at(contract_addr).sample_utility_function());
+    /// let return_value = env.execute_utility(SampleContract::at(contract_addr).sample_utility_function());
     /// ```
-    pub unconstrained fn simulate_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::simulate_utility_function(call.target_contract, call.selector, call.args);
+            txe_oracles::execute_utility_function(call.target_contract, call.selector, call.args);
 
         T::deserialize(serialized_return_values)
     }

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

@@ -55,12 +55,12 @@ pub unconstrained fn public_call_new_flow<let M: u32, let N: u32>(
     public_call_new_flow_oracle(from, contract_address, calldata, is_static_call)
 }
 
-pub unconstrained fn simulate_utility_function<let M: u32, let N: u32>(
+pub unconstrained fn execute_utility_function<let M: u32, let N: u32>(
     contract_address: AztecAddress,
     function_selector: FunctionSelector,
     args: [Field; M],
 ) -> [Field; N] {
-    simulate_utility_function_oracle(contract_address, function_selector, args)
+    execute_utility_function_oracle(contract_address, function_selector, args)
 }
 
 #[oracle(txeGetNextBlockNumber)]
@@ -145,8 +145,8 @@ unconstrained fn public_call_new_flow_oracle<let M: u32, let N: u32>(
     is_static_call: bool,
 ) -> [Field; N] {}
 
-#[oracle(txeSimulateUtilityFunction)]
-unconstrained fn simulate_utility_function_oracle<let M: u32, let N: u32>(
+#[oracle(txeExecuteUtilityFunction)]
+unconstrained fn execute_utility_function_oracle<let M: u32, let N: u32>(
     contract_address: AztecAddress,
     function_selector: FunctionSelector,
     args: [Field; M],

noir-projects/noir-contracts/contracts/app/amm_contract/src/test/test.nr

@@ -76,17 +76,17 @@ unconstrained fn add_liquidity_twice_and_remove_liquidity() {
     );
 
     // Liquidity provider 2 should have 0 token0 and the refund amount of token1
-    assert_eq(env.simulate_utility(token0.balance_of_private(liquidity_provider_2)), 0);
+    assert_eq(env.execute_utility(token0.balance_of_private(liquidity_provider_2)), 0);
     assert_eq(
-        env.simulate_utility(token1.balance_of_private(liquidity_provider_2)),
+        env.execute_utility(token1.balance_of_private(liquidity_provider_2)),
         expected_refund_amount1,
     );
 
     // Check liquidity provider 2 received liquidity tokens proportional to their contribution
     let expected_liquidity_tokens =
         (expected_amount_0_in * initial_liquidity_token_supply) / initial_amount0;
     assert_eq(
-        env.simulate_utility(liquidity_token.balance_of_private(liquidity_provider_2)),
+        env.execute_utility(liquidity_token.balance_of_private(liquidity_provider_2)),
         expected_liquidity_tokens,
     );
 
@@ -111,17 +111,17 @@ unconstrained fn add_liquidity_twice_and_remove_liquidity() {
     let expected_token1_back =
         (liquidity_to_remove * initial_amount1) / initial_liquidity_token_supply;
     assert_eq(
-        env.simulate_utility(token0.balance_of_private(liquidity_provider_1)),
+        env.execute_utility(token0.balance_of_private(liquidity_provider_1)),
         expected_token0_back,
     );
     assert_eq(
-        env.simulate_utility(token1.balance_of_private(liquidity_provider_1)),
+        env.execute_utility(token1.balance_of_private(liquidity_provider_1)),
         expected_token1_back,
     );
 
     // Check remaining liquidity tokens
     assert_eq(
-        env.simulate_utility(liquidity_token.balance_of_private(liquidity_provider_1)),
+        env.execute_utility(liquidity_token.balance_of_private(liquidity_provider_1)),
         // The expected remaining liquidity is the other half of the initial liquidity.
         AMM::INITIAL_LIQUIDITY / 2,
     );
@@ -182,9 +182,9 @@ unconstrained fn swap_exact_tokens_for_tokens() {
     );
 
     // Verify swap occurred - all of input tokens should be spent and hence the swapper should have 0 token0 balance.
-    assert_eq(env.simulate_utility(token0.balance_of_private(swapper)), 0);
+    assert_eq(env.execute_utility(token0.balance_of_private(swapper)), 0);
     // The exact amount out depends on the AMM formula, but should be > amount_out_min
-    assert(env.simulate_utility(token1.balance_of_private(swapper)) >= amount_out_min);
+    assert(env.execute_utility(token1.balance_of_private(swapper)) >= amount_out_min);
 }
 
 #[test]
@@ -243,9 +243,9 @@ unconstrained fn swap_tokens_for_exact_tokens() {
     );
 
     // Verify swap occurred - should get exact amount out
-    assert_eq(env.simulate_utility(token1.balance_of_private(swapper)), amount_out);
+    assert_eq(env.execute_utility(token1.balance_of_private(swapper)), amount_out);
     // Should have some token0 change returned
-    let swapper_token0_balance = env.simulate_utility(token0.balance_of_private(swapper));
+    let swapper_token0_balance = env.execute_utility(token0.balance_of_private(swapper));
     assert(swapper_token0_balance > 0);
     assert(swapper_token0_balance < amount_in_max);
 }

noir-projects/noir-contracts/contracts/app/nft_contract/src/test/utils.nr

@@ -72,7 +72,7 @@ pub unconstrained fn assert_owns_private_nft(
     token_id: Field,
 ) {
     let (private_nfts, _) =
-        env.simulate_utility(NFT::at(nft_contract_address).get_private_nfts(owner, 0));
+        env.execute_utility(NFT::at(nft_contract_address).get_private_nfts(owner, 0));
 
     let mut nft_found = false;
     for obtained_token_id in private_nfts {

noir-projects/noir-contracts/contracts/app/orderbook_contract/src/test/test.nr

@@ -45,7 +45,7 @@ unconstrained fn full_flow() {
     );
 
     // Get order and verify it's active
-    let (order, is_fulfilled) = env.simulate_utility(orderbook.get_order(order_id));
+    let (order, is_fulfilled) = env.execute_utility(orderbook.get_order(order_id));
 
     assert_eq(order.bid_amount, BID_AMOUNT);
     assert_eq(order.ask_amount, ASK_AMOUNT);
@@ -54,7 +54,7 @@ unconstrained fn full_flow() {
 
     // Verify that all maker's tokens were transferred to orderbook's public balance
     assert_eq(env.view_public(token0.balance_of_public(orderbook_address)), BID_AMOUNT);
-    assert_eq(env.simulate_utility(token0.balance_of_private(maker)), 0);
+    assert_eq(env.execute_utility(token0.balance_of_private(maker)), 0);
 
     // ORDER FULFILLMENT
 
@@ -72,13 +72,13 @@ unconstrained fn full_flow() {
     env.call_private(taker, orderbook.fulfill_order(order_id, FULFILL_ORDER_AUTHWIT_NONCE));
 
     // Verify final balances
-    assert_eq(env.simulate_utility(token0.balance_of_private(maker)), 0);
-    assert_eq(env.simulate_utility(token1.balance_of_private(maker)), ASK_AMOUNT);
-    assert_eq(env.simulate_utility(token0.balance_of_private(taker)), BID_AMOUNT);
-    assert_eq(env.simulate_utility(token1.balance_of_private(taker)), 0);
+    assert_eq(env.execute_utility(token0.balance_of_private(maker)), 0);
+    assert_eq(env.execute_utility(token1.balance_of_private(maker)), ASK_AMOUNT);
+    assert_eq(env.execute_utility(token0.balance_of_private(taker)), BID_AMOUNT);
+    assert_eq(env.execute_utility(token1.balance_of_private(taker)), 0);
 
     // Get order and verify it's fulfilled
-    let (order, is_fulfilled) = env.simulate_utility(orderbook.get_order(order_id));
+    let (order, is_fulfilled) = env.execute_utility(orderbook.get_order(order_id));
 
     assert_eq(order.bid_amount, BID_AMOUNT);
     assert_eq(order.ask_amount, ASK_AMOUNT);

noir-projects/noir-contracts/contracts/app/private_voting_contract/src/test/first.nr

@@ -63,7 +63,7 @@ unconstrained fn test_cast_vote() {
         PrivateVoting::at(voting_contract_address).cast_vote(election_id, candidate),
     );
 
-    let tally = env.simulate_utility(PrivateVoting::at(voting_contract_address).get_tally(
+    let tally = env.execute_utility(PrivateVoting::at(voting_contract_address).get_tally(
         election_id,
         candidate,
     ));
@@ -90,7 +90,7 @@ unconstrained fn test_cast_vote_with_separate_accounts() {
         PrivateVoting::at(voting_contract_address).cast_vote(election_id, candidate),
     );
 
-    let tally = env.simulate_utility(PrivateVoting::at(voting_contract_address).get_tally(
+    let tally = env.execute_utility(PrivateVoting::at(voting_contract_address).get_tally(
         election_id,
         candidate,
     ));
@@ -139,11 +139,11 @@ unconstrained fn test_vote_in_two_different_elections() {
         PrivateVoting::at(voting_contract_address).cast_vote(election_id_54, candidate),
     );
 
-    let vote_count_42 = env.simulate_utility(PrivateVoting::at(voting_contract_address).get_tally(
+    let vote_count_42 = env.execute_utility(PrivateVoting::at(voting_contract_address).get_tally(
         election_id_42,
         candidate,
     ));
-    let vote_count_54 = env.simulate_utility(PrivateVoting::at(voting_contract_address).get_tally(
+    let vote_count_54 = env.execute_utility(PrivateVoting::at(voting_contract_address).get_tally(
         election_id_54,
         candidate,
     ));

noir-projects/noir-contracts/contracts/app/token_contract/src/test/utils.nr

@@ -81,7 +81,7 @@ pub unconstrained fn check_private_balance(
     address_amount: u128,
 ) {
     assert_eq(
-        env.simulate_utility(Token::at(token_contract_address).balance_of_private(address)),
+        env.execute_utility(Token::at(token_contract_address).balance_of_private(address)),
         address_amount,
     );
 }

noir-projects/noir-contracts/contracts/test/counter_contract/src/main.nr

@@ -110,7 +110,7 @@ pub contract Counter {
 
             // Read the stored value in the note
             let initial_counter =
-                env.simulate_utility(Counter::at(contract_address).get_counter(owner));
+                env.execute_utility(Counter::at(contract_address).get_counter(owner));
             assert(
                 initial_counter == initial_value,
                 f"Expected {initial_value} but got {initial_counter}",
@@ -120,7 +120,7 @@ pub contract Counter {
             env.call_private(owner, Counter::at(contract_address).increment(owner));
 
             let incremented_counter =
-                env.simulate_utility(Counter::at(contract_address).get_counter(owner));
+                env.execute_utility(Counter::at(contract_address).get_counter(owner));
             let expected_current_value = initial_value + 1;
             assert(
                 expected_current_value == incremented_counter,
@@ -135,21 +135,21 @@ pub contract Counter {
 
             // Checking that the note was discovered from private logs
             let initial_note_value =
-                env.simulate_utility(Counter::at(contract_address).get_counter(owner));
+                env.execute_utility(Counter::at(contract_address).get_counter(owner));
             assert(initial_note_value == initial_value);
 
             env.call_private(owner, Counter::at(contract_address).increment_twice(owner));
 
-            assert_eq(env.simulate_utility(Counter::at(contract_address).get_counter(owner)), 7);
+            assert_eq(env.execute_utility(Counter::at(contract_address).get_counter(owner)), 7);
 
             let _ = env.call_private(
                 owner,
                 Counter::at(contract_address).increment_and_decrement(owner),
             );
-            assert_eq(env.simulate_utility(Counter::at(contract_address).get_counter(owner)), 7);
+            assert_eq(env.execute_utility(Counter::at(contract_address).get_counter(owner)), 7);
 
             env.call_private(owner, Counter::at(contract_address).decrement(owner));
-            assert_eq(env.simulate_utility(Counter::at(contract_address).get_counter(owner)), 6);
+            assert_eq(env.execute_utility(Counter::at(contract_address).get_counter(owner)), 6);
         }
     }
 }

noir-projects/noir-contracts/contracts/test/test_contract/src/test/note_delivery.nr

@@ -47,7 +47,7 @@ unconstrained fn create_note_private_only_tx_and_read_in_utility() {
         test_contract.call_create_note(VALUE, recipient, STORAGE_SLOT, make_tx_hybrid),
     );
 
-    let retrieved = env.simulate_utility(test_contract.call_view_notes(
+    let retrieved = env.execute_utility(test_contract.call_view_notes(
         recipient,
         STORAGE_SLOT,
         ACTIVE_OR_NULLIFIED,
@@ -85,7 +85,7 @@ unconstrained fn create_note_hybrid_tx_and_read_in_utility() {
         test_contract.call_create_note(VALUE, recipient, STORAGE_SLOT, make_tx_hybrid),
     );
 
-    let retrieved = env.simulate_utility(test_contract.call_view_notes(
+    let retrieved = env.execute_utility(test_contract.call_view_notes(
         recipient,
         STORAGE_SLOT,
         ACTIVE_OR_NULLIFIED,
@@ -121,7 +121,7 @@ unconstrained fn create_partial_note_in_one_tx_and_read_in_utility() {
         test_contract.call_create_and_complete_partial_note(recipient, STORAGE_SLOT, VALUE),
     );
 
-    let retrieved = env.simulate_utility(test_contract.call_view_notes(
+    let retrieved = env.execute_utility(test_contract.call_view_notes(
         recipient,
         STORAGE_SLOT,
         ACTIVE_OR_NULLIFIED,
@@ -157,7 +157,7 @@ unconstrained fn create_partial_note_in_two_txs_and_read_in_utility() {
 
     env.call_public(sender, test_contract.call_complete_partial_note(partial_note, VALUE));
 
-    let retrieved = env.simulate_utility(test_contract.call_view_notes(
+    let retrieved = env.execute_utility(test_contract.call_view_notes(
         recipient,
         STORAGE_SLOT,
         ACTIVE_OR_NULLIFIED,

yarn-project/aztec.js/src/api/wallet.ts

@@ -1,7 +1,7 @@
 export {
   type Aliased,
   type SimulateOptions,
-  type SimulateUtilityOptions,
+  type ExecuteUtilityOptions,
   type ProfileOptions,
   type SendOptions,
   type BatchableMethods,