feat: utility function

Author: benesjan

cspell.json

@@ -97,12 +97,12 @@
     "doesnt",
     "dont",
     "ecdh",
+    "ecdsasecp",
     "elif",
     "endgroup",
     "enrs",
     "entrypoints",
     "erc",
-    "ecdsasecp",
     "falsey",
     "fargate",
     "Fieldable",
@@ -155,6 +155,7 @@
     "libp",
     "linkability",
     "lmdb",
+    "macroified",
     "maddiaa",
     "mcache",
     "memdown",

noir-projects/aztec-nr/aztec/src/macros/aztec.nr

@@ -4,7 +4,7 @@ use crate::{
         dispatch::generate_public_dispatch,
         functions::{
             stub_registry,
-            utils::{create_message_discovery_call, find_and_transform_top_level_unconstrained_fns},
+            utils::{check_each_fn_macroified, create_message_discovery_call},
         },
         notes::{generate_note_export, NOTES},
         storage::STORAGE_LAYOUT_NAME,
@@ -18,7 +18,9 @@ use crate::{
 pub comptime fn aztec(m: Module) -> Quoted {
     let interface = generate_contract_interface(m);
 
-    find_and_transform_top_level_unconstrained_fns(m);
+    // Functions that don't have #[private], #[public], #[utility], #[contract_library_method], or #[test] are not
+    //allowed in contracts.
+    check_each_fn_macroified(m);
 
     let contract_library_method_compute_note_hash_and_nullifier =
         generate_contract_library_method_compute_note_hash_and_nullifier();

noir-projects/aztec-nr/aztec/src/macros/functions/mod.nr

@@ -4,7 +4,7 @@ pub(crate) mod initialization_utils;
 pub(crate) mod stub_registry;
 pub(crate) mod utils;
 
-use utils::{transform_private, transform_public};
+use utils::{transform_private, transform_public, transform_utility};
 
 // Functions can have multiple attributes applied to them, e.g. a single function can have #[public], #[view] and
 // #[internal]. However. the order in which this will be evaluated is unknown, which makes combining them tricky.
@@ -55,3 +55,10 @@ pub comptime fn public(f: FunctionDefinition) -> Quoted {
         transform_public(f)
     }
 }
+
+/// Utility functions are standalone unconstrained functions that cannot be called from within a contract. They are
+/// typically used either to obtain some information from the contract (e.g. token balance of a user) or to modify
+/// internal contract-related state of PXE (e,g, processing logs in Aztec.nr during sync).
+pub comptime fn utility(f: FunctionDefinition) {
+    transform_utility(f);
+}

noir-projects/aztec-nr/aztec/src/macros/functions/utils.nr

@@ -2,9 +2,9 @@ use crate::macros::{
     functions::{abi_export::create_fn_abi_export, call_interface_stubs::stub_fn, stub_registry},
     notes::NOTES,
     utils::{
-        add_to_hasher, fn_has_noinitcheck, get_fn_visibility, is_fn_initializer, is_fn_internal,
-        is_fn_private, is_fn_public, is_fn_view, modify_fn_body, module_has_initializer,
-        module_has_storage,
+        add_to_hasher, fn_has_noinitcheck, get_fn_visibility, is_fn_contract_library_method,
+        is_fn_initializer, is_fn_internal, is_fn_private, is_fn_public, is_fn_test, is_fn_utility,
+        is_fn_view, modify_fn_body, module_has_initializer, module_has_storage,
     },
 };
 use protocol_types::meta::generate_serialize_to_fields;
@@ -272,45 +272,7 @@ pub(crate) comptime fn transform_public(f: FunctionDefinition) -> Quoted {
     fn_abi
 }
 
-pub(crate) comptime fn find_and_transform_top_level_unconstrained_fns(m: Module) {
-    // Top-level unconstrained fns are contract entrypoints, but they're not explicitly designated in any way. They're
-    // the fallback case for a function that matches no other rules.
-    // TODO(#12743): improve this
-
-    // We first find non-standard contract entrypoints, i.e. functions in the `contract` mod that are not private or
-    // public, but which *are* contract entrypoints (i.e. they're not opting out via the #[test] or
-    // #[contract_library_method] attributes). Ideally entrypoints would be explicitly designated instead.
-    let non_private_public_entrypoint_functions = m.functions().filter(|f: FunctionDefinition| {
-        !is_fn_private(f)
-            & !is_fn_public(f)
-            & !f.has_named_attribute("contract_library_method")
-            & !f.has_named_attribute("test")
-    });
-
-    // TODO: uncomment the code below and emit a warning once support for them is added to Noir (tracked in
-    // https://github.com/noir-lang/noir/issues/7714). We can't simply print a message since that'd otherwise break the
-    // output of utils such as `nargo test --list-tests`.
-    // // We don't expect to see any custom constrained entrypoints (i.e. private functions created outside of aztec-nr's
-    // // #[private] macro, possibly resulting in a non-standard interface).
-    // for f in non_private_public_entrypoint_functions.filter(|f: FunctionDefinition| {
-    //     !f.is_unconstrained()
-    // }) {
-    //     let name = f.name();
-    //     warn(
-    //         f"found private contract function '{name}' which does not have the #[private] attribute - make sure you know what you're doing!",
-    //     );
-    // }
-
-    // An unconstrained contract entrypoints is what we call a top-level unconstrained function, to which we apply the
-    // appropriate transformation. Ideally these would be explicitly designated as such instead.
-    for f in non_private_public_entrypoint_functions.filter(|f: FunctionDefinition| {
-        f.is_unconstrained()
-    }) {
-        transform_top_level_unconstrained(f);
-    }
-}
-
-pub(crate) comptime fn transform_top_level_unconstrained(f: FunctionDefinition) {
+pub(crate) comptime fn transform_utility(f: FunctionDefinition) {
     let context_creation = quote { let mut context = dep::aztec::context::unconstrained_context::UnconstrainedContext::new(); };
     let module_has_storage = module_has_storage(f.module());
 
@@ -395,3 +357,20 @@ pub(crate) comptime fn create_message_discovery_call() -> Quoted {
         };
     }
 }
+
+/// Checks if each function in the module is marked with either #[private], #[public], #[utility],
+/// #[contract_library_method], or #[test]. Non-macroified functions are not allowed in contracts.
+pub(crate) comptime fn check_each_fn_macroified(m: Module) {
+    for f in m.functions() {
+        let name = f.name();
+        if !is_fn_private(f)
+            & !is_fn_public(f)
+            & !is_fn_utility(f)
+            & !is_fn_contract_library_method(f)
+            & !is_fn_test(f) {
+            panic(
+                f"Function {name} must be marked as either #[private], #[public], #[utility], #[contract_library_method], or #[test]",
+            );
+        }
+    }
+}

noir-projects/aztec-nr/aztec/src/macros/utils.nr

@@ -18,6 +18,18 @@ pub(crate) comptime fn is_fn_public(f: FunctionDefinition) -> bool {
     f.has_named_attribute("public")
 }
 
+pub(crate) comptime fn is_fn_utility(f: FunctionDefinition) -> bool {
+    f.has_named_attribute("utility")
+}
+
+pub(crate) comptime fn is_fn_contract_library_method(f: FunctionDefinition) -> bool {
+    f.has_named_attribute("contract_library_method")
+}
+
+pub(crate) comptime fn is_fn_test(f: FunctionDefinition) -> bool {
+    f.has_named_attribute("test")
+}
+
 pub(crate) comptime fn is_fn_view(f: FunctionDefinition) -> bool {
     f.has_named_attribute("view")
 }

noir-projects/noir-contracts/contracts/amm_contract/src/main.nr

@@ -39,7 +39,7 @@ pub contract AMM {
         lib::{get_amount_in, get_amount_out, get_amounts_on_remove, get_amounts_to_add},
     };
     use dep::aztec::{
-        macros::{functions::{initializer, internal, private, public}, storage::storage},
+        macros::{functions::{initializer, internal, private, public, utility}, storage::storage},
         prelude::{AztecAddress, PublicImmutable},
     };
 
@@ -461,6 +461,7 @@ pub contract AMM {
         );
     }
 
+    #[utility]
     unconstrained fn get_amount_out_for_exact_in(
         balance_in: u128,
         balance_out: u128,
@@ -470,6 +471,7 @@ pub contract AMM {
         get_amount_out(amount_in, balance_in, balance_out)
     }
 
+    #[utility]
     unconstrained fn get_amount_in_for_exact_out(
         balance_in: u128,
         balance_out: u128,

noir-projects/noir-contracts/contracts/app_subscription_contract/src/main.nr

@@ -11,7 +11,7 @@ pub contract AppSubscription {
     use authwit::auth::assert_current_call_valid_authwit;
     use aztec::{
         encrypted_logs::log_assembly_strategies::default_aes128::note::encode_and_encrypt_note,
-        macros::{functions::{initializer, private, public}, storage::storage},
+        macros::{functions::{initializer, private, public, utility}, storage::storage},
         prelude::{AztecAddress, Map, PrivateMutable, PublicImmutable},
         protocol_types::{constants::MAX_FIELD_VALUE, traits::ToField},
         utils::comparison::Comparator,
@@ -115,6 +115,7 @@ pub contract AppSubscription {
         );
     }
 
+    #[utility]
     unconstrained fn is_initialized(subscriber: AztecAddress) -> pub bool {
         storage.subscriptions.at(subscriber).is_initialized()
     }

noir-projects/noir-contracts/contracts/auth_registry_contract/src/main.nr

@@ -6,7 +6,7 @@ pub contract AuthRegistry {
         assert_current_call_valid_authwit, compute_authwit_message_hash, IS_VALID_SELECTOR,
     };
     use dep::aztec::{
-        macros::{functions::{internal, private, public, view}, storage::storage},
+        macros::{functions::{internal, private, public, utility, view}, storage::storage},
         protocol_types::address::AztecAddress,
         state_vars::{Map, PublicMutable},
     };
@@ -128,6 +128,7 @@ pub contract AuthRegistry {
         storage.approved_actions.at(on_behalf_of).at(message_hash).read()
     }
 
+    #[utility]
     unconstrained fn unconstrained_is_consumable(
         on_behalf_of: AztecAddress,
         message_hash: Field,

noir-projects/noir-contracts/contracts/card_game_contract/src/main.nr

@@ -12,7 +12,7 @@ pub contract CardGame {
 
     use crate::cards::{Card, compute_deck_strength, Deck, get_pack_cards};
     use crate::game::{Game, PLAYABLE_CARDS, PlayerEntry};
-    use dep::aztec::macros::{functions::{internal, private, public}, storage::storage};
+    use dep::aztec::macros::{functions::{internal, private, public, utility}, storage::storage};
 
     use dep::aztec::protocol_types::traits::{FromField, ToField};
 
@@ -134,6 +134,7 @@ pub contract CardGame {
         game_storage.write(game_data);
     }
 
+    #[utility]
     unconstrained fn view_collection_cards(
         owner: AztecAddress,
         offset: u32,
@@ -142,6 +143,7 @@ pub contract CardGame {
         collection.view_cards(offset)
     }
 
+    #[utility]
     unconstrained fn view_game_cards(
         game: u32,
         player: AztecAddress,
@@ -152,6 +154,7 @@ pub contract CardGame {
         game_deck.view_cards(offset)
     }
 
+    #[utility]
     unconstrained fn view_game(game: u32) -> pub Game {
         storage.games.at(game as Field).read()
     }

noir-projects/noir-contracts/contracts/token_contract/src/main.nr

@@ -27,7 +27,7 @@ pub contract Token {
         event::event_interface::EventInterface,
         macros::{
             events::event,
-            functions::{initializer, internal, private, public, view},
+            functions::{initializer, internal, private, public, utility, view},
             storage::storage,
         },
         prelude::{AztecAddress, Map, PublicContext, PublicImmutable, PublicMutable},
@@ -618,8 +618,8 @@ pub contract Token {
     }
     // docs:end:reduce_total_supply
 
-    /// Unconstrained ///
     // docs:start:balance_of_private
+    #[utility]
     pub(crate) unconstrained fn balance_of_private(owner: AztecAddress) -> pub u128 {
         storage.balances.at(owner).balance_of()
     }