@layerzerolabs/protocol-stellar-v2 0.2.35 → 0.2.37

package/contracts/common-macros/src/auth.rs

@@ -27,14 +27,14 @@ pub fn generate_ownable_impl(input: TokenStream) -> TokenStream {
     quote! {
         #item_struct
 
-        use utils::{auth::Auth as _, option_ext::OptionExt as _, ownable::{Ownable as _, OwnableInitializer as _}};
+        use utils::{auth::Auth as _, ownable::{Ownable as _, OwnableInitializer as _}};
 
         impl utils::ownable::OwnableInitializer for #name {}
 
         #[common_macros::contract_impl]
         impl utils::auth::Auth for #name {
-            fn authorizer(env: &soroban_sdk::Env) -> soroban_sdk::Address {
-                <Self as utils::ownable::Ownable>::owner(env).unwrap_or_panic(env, utils::errors::OwnableError::OwnerNotSet)
+            fn authorizer(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
+                <Self as utils::ownable::Ownable>::owner(env)
             }
         }
 
@@ -63,8 +63,8 @@ pub fn generate_multisig_impl(input: TokenStream) -> TokenStream {
 
         #[common_macros::contract_impl]
         impl utils::auth::Auth for #name {
-            fn authorizer(env: &soroban_sdk::Env) -> soroban_sdk::Address {
-                env.current_contract_address()
+            fn authorizer(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
+                Some(env.current_contract_address())
             }
         }
 

package/contracts/common-macros/src/lib.rs

@@ -7,6 +7,8 @@
 //! - [`lz_contract`] - Wrapper macro combining common LayerZero contract attributes
 //! - [`multisig`] - MultiSig trait implementation macro
 //! - [`only_auth`] - Auth-based access control attribute macro
+//! - [`only_role`] - RBAC role check with auth attribute macro
+//! - [`has_role`] - RBAC role check attribute macro
 //! - [`ownable`] - Ownable trait implementation macro
 //! - [`storage`] - Storage enum to API macro
 //! - [`ttl_configurable`] - TTL configuration with freeze support
@@ -20,6 +22,7 @@ mod auth;
 mod contract_ttl;
 mod error;
 mod lz_contract;
+mod rbac;
 mod storage;
 mod ttl_configurable;
 mod ttl_extendable;
@@ -232,6 +235,72 @@ pub fn only_auth(_attr: TokenStream, item: TokenStream) -> TokenStream {
     auth::prepend_only_auth_check(item.into()).into()
 }
 
+// ============================================================================
+// RBAC Macros
+// ============================================================================
+
+/// Checks that the given account has the specified role.
+///
+/// Injects a role check at the start of the function. Panics with
+/// `RbacError::Unauthorized` if the account does not have the role (aligns with OpenZeppelin).
+///
+/// # Requirements
+/// - The function must have an `Env` parameter
+/// - The function must have a parameter matching the first macro arg (of type `Address` or `&Address`)
+/// - The contract must use `utils::rbac` (e.g. `RbacStorage` or `RoleBasedAccessControl`)
+///
+/// # Example
+/// ```ignore
+/// #[has_role(caller, "minter")]
+/// pub fn mint(env: Env, caller: Address, amount: i128) { ... }
+///
+/// // Or with a &str constant:
+/// const MINTER_ROLE: &str = "minter";
+/// #[has_role(caller, MINTER_ROLE)]
+/// pub fn mint(env: Env, caller: Address, amount: i128) { ... }
+/// ```
+///
+/// # Generated code
+/// ```ignore
+/// pub fn mint(env: Env, caller: Address, amount: i128) {
+///     utils::rbac::ensure_role(&env, &soroban_sdk::Symbol::new(&env, "minter"), &caller);
+///     // Original function body
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn has_role(attr: TokenStream, item: TokenStream) -> TokenStream {
+    rbac::generate_role_check(attr.into(), item.into(), false).into()
+}
+
+/// Checks that the given account has the specified role and requires auth.
+///
+/// Same as `#[has_role]` but also calls `account.require_auth()` to ensure
+/// the caller has authorized the transaction.
+///
+/// # Requirements
+/// Same as `#[has_role]`.
+///
+/// # Example
+/// ```ignore
+/// #[only_role(caller, "minter")]
+/// pub fn mint(env: Env, caller: Address, amount: i128) { ... }
+///
+/// // Or with a &str constant: #[only_role(caller, MINTER_ROLE)]
+/// ```
+///
+/// # Generated code
+/// ```ignore
+/// pub fn mint(env: Env, caller: Address, amount: i128) {
+///     utils::rbac::ensure_role(&env, &soroban_sdk::Symbol::new(&env, "minter"), &caller);
+///     caller.require_auth();
+///     // Original function body
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn only_role(attr: TokenStream, item: TokenStream) -> TokenStream {
+    rbac::generate_role_check(attr.into(), item.into(), true).into()
+}
+
 // ============================================================================
 // TTL Configuration Macro
 // ============================================================================

package/contracts/common-macros/src/rbac.rs

@@ -0,0 +1,90 @@
+//! RBAC attribute macros for Stellar contracts.
+//!
+//! Provides `#[has_role]` and `#[only_role]` for role-based access control,
+//! delegating to `utils::rbac::ensure_role`.
+
+use crate::utils;
+use proc_macro2::TokenStream;
+use quote::{quote, ToTokens};
+use syn::parse_quote;
+use syn::{
+    parse::{Parse, ParseStream},
+    Expr, FnArg, Ident, ItemFn, Pat, Token, Type,
+};
+
+/// Helper that generates the role check for both `has_role` and `only_role`.
+/// If `require_auth` is true, also injects `account.require_auth()`.
+pub fn generate_role_check(args: TokenStream, input: TokenStream, require_auth: bool) -> TokenStream {
+    let HasRoleArgs { param, role } =
+        syn::parse2(args).unwrap_or_else(|e| panic!("failed to parse has_role/only_role args: {}", e));
+    let mut input_fn: ItemFn = syn::parse2(input).unwrap_or_else(|e| panic!("failed to parse function: {}", e));
+
+    let is_address_ref = validate_address_type(&input_fn, &param);
+    let param_ref = if is_address_ref { quote!(#param) } else { quote!(&#param) };
+
+    let env_param = utils::expect_env_param(&input_fn.sig.inputs);
+    let env_ref = env_param.as_ref_tokens();
+
+    // Insert the role check at the beginning of the function body
+    input_fn.block.stmts.insert(
+        0,
+        parse_quote!(utils::rbac::ensure_role(#env_ref, &soroban_sdk::Symbol::new(#env_ref, #role), #param_ref);),
+    );
+    if require_auth {
+        input_fn.block.stmts.insert(1, parse_quote!(#param.require_auth();));
+    }
+    input_fn.into_token_stream()
+}
+
+struct HasRoleArgs {
+    param: Ident,
+    role: Expr,
+}
+
+impl Parse for HasRoleArgs {
+    fn parse(input: ParseStream) -> syn::Result<Self> {
+        // Parse the parameter name (the account identifier to check)
+        let param: Ident = input.parse()?;
+        // Expect a comma separator between param and role
+        input.parse::<Token![,]>()?;
+        // Parse the role expression (e.g., a string literal or constant)
+        let role: Expr = input.parse()?;
+        Ok(HasRoleArgs { param, role })
+    }
+}
+
+/// Looks up `param_name` in the function signature and validates that its type
+/// is `Address` or `&Address`. Returns `true` when the parameter is a reference,
+/// so the caller knows whether an extra `&` is needed when forwarding it.
+///
+/// Panics at macro-expansion time if the parameter doesn't exist.
+fn validate_address_type(func: &ItemFn, param_name: &Ident) -> bool {
+    for arg in &func.sig.inputs {
+        let FnArg::Typed(pat_type) = arg else { continue };
+        let Pat::Ident(pat_ident) = &*pat_type.pat else { continue };
+        if pat_ident.ident != *param_name {
+            continue;
+        }
+        return match &*pat_type.ty {
+            Type::Reference(r) => {
+                assert_is_address(&r.elem, param_name);
+                true
+            }
+            ty => {
+                assert_is_address(ty, param_name);
+                false
+            }
+        };
+    }
+    panic!("Parameter `{param_name}` not found in function signature");
+}
+
+/// Asserts that the type path resolves to `Address`, panicking otherwise.
+fn assert_is_address(ty: &Type, param_name: &Ident) {
+    let Type::Path(tp) = ty else {
+        panic!("Parameter `{param_name}` must be of type `Address` or `&Address`");
+    };
+    if tp.path.segments.last().is_none_or(|s| s.ident != "Address") {
+        panic!("Parameter `{param_name}` must be of type `Address` or `&Address`");
+    }
+}

package/contracts/common-macros/src/tests/lz_contract.rs

@@ -22,8 +22,10 @@ fn snapshot_generated_lz_contract_code() {
         &syn::parse2::<syn::File>(multisig_upgradeable_result).expect("failed to parse generated code"),
     );
 
-    let upgradeable_no_migration_result =
-        crate::lz_contract::generate_lz_contract(quote! { upgradeable(no_migration) }, quote! { pub struct MyContract; });
+    let upgradeable_no_migration_result = crate::lz_contract::generate_lz_contract(
+        quote! { upgradeable(no_migration) },
+        quote! { pub struct MyContract; },
+    );
     let upgradeable_no_migration_formatted = prettyplease::unparse(
         &syn::parse2::<syn::File>(upgradeable_no_migration_result).expect("failed to parse generated code"),
     );
@@ -45,11 +47,7 @@ fn test_lz_contract_invalid_config_table_driven() {
     let input = quote! { pub struct MyContract; };
 
     let cases: Vec<(&str, TokenStream, &str)> = vec![
-        (
-            "unknown option",
-            quote! { not_a_real_option },
-            "expected one of `upgradeable`, `multisig`",
-        ),
+        ("unknown option", quote! { not_a_real_option }, "expected one of `upgradeable`, `multisig`"),
         ("invalid attr syntax", quote! { 123 }, "failed to parse lz_contract config"),
         ("upgradeable(bad_inner)", quote! { upgradeable(not_migration) }, "expected `no_migration`"),
         (

package/contracts/common-macros/src/tests/mod.rs

@@ -2,6 +2,7 @@ mod auth;
 mod contract_ttl;
 mod error;
 mod lz_contract;
+mod rbac;
 mod storage;
 mod test_helpers;
 mod ttl_configurable;

package/contracts/common-macros/src/tests/rbac.rs

@@ -0,0 +1,420 @@
+use proc_macro2::TokenStream;
+use quote::quote;
+
+use crate::tests::test_helpers::{assert_panics_contains, filter_item_inputs_excluding_labels};
+
+// ============================================
+// Snapshot Test: has_role and only_role
+// ============================================
+
+#[test]
+fn snapshot_preserve_function_signature() {
+    let args = quote! { caller, "minter" };
+    let input = quote! {
+        pub fn mint(env: Env, caller: Address, amount: i128) {
+            // mint logic
+        }
+    };
+
+    let has_role_result = crate::rbac::generate_role_check(args.clone(), input.clone(), false);
+    let has_role_formatted =
+        prettyplease::unparse(&syn::parse2::<syn::File>(has_role_result).expect("failed to parse generated code"));
+
+    let only_role_result = crate::rbac::generate_role_check(args, input, true);
+    let only_role_formatted =
+        prettyplease::unparse(&syn::parse2::<syn::File>(only_role_result).expect("failed to parse generated code"));
+
+    let combined =
+        format!("// === has_role ===\n\n{}\n\n// === only_role ===\n\n{}", has_role_formatted, only_role_formatted);
+
+    insta::assert_snapshot!(combined);
+}
+
+// ============================================
+// generate_role_check assertion tests
+// ============================================
+
+fn assert_stmt_eq(stmt: &syn::Stmt, expected: &str, test_name: &str) {
+    let actual = quote::quote!(#stmt).to_string().replace(" ", "");
+    assert_eq!(actual, expected, "{test_name}: expected '{expected}', got '{actual}'");
+}
+
+fn assert_role_check_exact_stmts(
+    args: TokenStream,
+    input: TokenStream,
+    require_auth: bool,
+    expected_ensure_stmt_no_spaces: &str,
+    expected_auth_stmt_no_spaces: Option<&str>,
+    expected_stmt_count: Option<usize>,
+    test_name: &str,
+) -> syn::ItemFn {
+    let result_tokens = crate::rbac::generate_role_check(args, input, require_auth);
+    let output_fn: syn::ItemFn =
+        syn::parse2(result_tokens).unwrap_or_else(|e| panic!("{test_name}: failed to parse output function: {e}"));
+
+    assert!(!output_fn.block.stmts.is_empty(), "{test_name}: function body should contain at least one statement");
+
+    assert_stmt_eq(&output_fn.block.stmts[0], expected_ensure_stmt_no_spaces, test_name);
+
+    if let Some(expected_auth) = expected_auth_stmt_no_spaces {
+        assert!(output_fn.block.stmts.len() >= 2, "{test_name}: expected at least two statements");
+        assert_stmt_eq(&output_fn.block.stmts[1], expected_auth, test_name);
+    }
+
+    if let Some(expected_count) = expected_stmt_count {
+        assert_eq!(
+            output_fn.block.stmts.len(),
+            expected_count,
+            "{test_name}: expected {expected_count} statements, got {}",
+            output_fn.block.stmts.len()
+        );
+    }
+
+    output_fn
+}
+
+#[test]
+fn test_role_check_inserts_expected_statements_table_driven() {
+    struct Case {
+        name: &'static str,
+        args: TokenStream,
+        input: TokenStream,
+        require_auth: bool,
+        expected_ensure_stmt: &'static str,
+        expected_auth_stmt: Option<&'static str>,
+        expected_stmt_count: usize,
+    }
+
+    let cases = vec![
+        Case {
+            name: "has_role: Env ref + Address value",
+            args: quote! { caller, "minter" },
+            input: quote! { pub fn mint(env: &Env, caller: Address, amount: i128) {} },
+            require_auth: false,
+            expected_ensure_stmt: "utils::rbac::ensure_role(env,&soroban_sdk::Symbol::new(env,\"minter\"),&caller);",
+            expected_auth_stmt: None,
+            expected_stmt_count: 1,
+        },
+        Case {
+            name: "only_role: Env owned + Address value",
+            args: quote! { caller, "minter" },
+            input: quote! { pub fn mint(env: Env, caller: Address, amount: i128) {} },
+            require_auth: true,
+            expected_ensure_stmt: "utils::rbac::ensure_role(&env,&soroban_sdk::Symbol::new(&env,\"minter\"),&caller);",
+            expected_auth_stmt: Some("caller.require_auth();"),
+            expected_stmt_count: 2,
+        },
+        Case {
+            name: "only_role: Env ref + Address value",
+            args: quote! { caller, "minter" },
+            input: quote! { pub fn mint(env: &Env, caller: Address, amount: i128) {} },
+            require_auth: true,
+            expected_ensure_stmt: "utils::rbac::ensure_role(env,&soroban_sdk::Symbol::new(env,\"minter\"),&caller);",
+            expected_auth_stmt: Some("caller.require_auth();"),
+            expected_stmt_count: 2,
+        },
+        Case {
+            name: "has_role: &Address param uses account directly",
+            args: quote! { account, "admin" },
+            input: quote! { pub fn admin_action(env: Env, account: &Address) {} },
+            require_auth: false,
+            expected_ensure_stmt: "utils::rbac::ensure_role(&env,&soroban_sdk::Symbol::new(&env,\"admin\"),account);",
+            expected_auth_stmt: None,
+            expected_stmt_count: 1,
+        },
+    ];
+
+    for c in cases {
+        assert_role_check_exact_stmts(
+            c.args,
+            c.input,
+            c.require_auth,
+            c.expected_ensure_stmt,
+            c.expected_auth_stmt,
+            Some(c.expected_stmt_count),
+            c.name,
+        );
+    }
+}
+
+#[test]
+fn test_has_role_role_arg_variants_generate_expected_symbol_new_table_driven() {
+    struct Case {
+        name: &'static str,
+        args: TokenStream,
+        input: TokenStream,
+        expected_ensure_stmt: &'static str,
+    }
+
+    let cases = vec![
+        Case {
+            name: "role string literal passed to Symbol::new (Env ref)",
+            args: quote! { caller, "minter" },
+            input: quote! { pub fn mint(env: &Env, caller: Address) {} },
+            expected_ensure_stmt: "utils::rbac::ensure_role(env,&soroban_sdk::Symbol::new(env,\"minter\"),&caller);",
+        },
+        Case {
+            name: "role const expr passed to Symbol::new (Env ref)",
+            args: quote! { caller, MINTER_ROLE },
+            input: quote! { pub fn mint(env: &Env, caller: Address) {} },
+            expected_ensure_stmt: "utils::rbac::ensure_role(env,&soroban_sdk::Symbol::new(env,MINTER_ROLE),&caller);",
+        },
+        Case {
+            name: "role const expr passed to Symbol::new (Env owned)",
+            args: quote! { caller, MINTER_ROLE },
+            input: quote! { pub fn mint(env: Env, caller: Address) {} },
+            expected_ensure_stmt: "utils::rbac::ensure_role(&env,&soroban_sdk::Symbol::new(&env,MINTER_ROLE),&caller);",
+        },
+        Case {
+            name: "role path expr passed to Symbol::new",
+            args: quote! { caller, roles::MINTER_ROLE },
+            input: quote! { pub fn mint(env: &Env, caller: Address) {} },
+            expected_ensure_stmt:
+                "utils::rbac::ensure_role(env,&soroban_sdk::Symbol::new(env,roles::MINTER_ROLE),&caller);",
+        },
+    ];
+
+    for c in cases {
+        assert_role_check_exact_stmts(c.args, c.input, false, c.expected_ensure_stmt, None, Some(1), c.name);
+    }
+}
+
+// ============================================
+// Error cases: invalid args (table-driven)
+// ============================================
+
+#[test]
+fn test_has_role_rejects_invalid_args_table_driven() {
+    struct Case {
+        name: &'static str,
+        args: TokenStream,
+        expected_substring: &'static str,
+    }
+
+    let input = quote! { pub fn mint(env: Env, caller: Address) {} };
+    let cases = vec![
+        Case {
+            name: "missing comma in args",
+            args: quote! { caller "minter" },
+            expected_substring: "failed to parse has_role/only_role args",
+        },
+        Case {
+            name: "missing role",
+            args: quote! { caller, },
+            expected_substring: "failed to parse has_role/only_role args",
+        },
+        Case {
+            name: "extra tokens in args",
+            args: quote! { caller, "minter", extra },
+            expected_substring: "failed to parse has_role/only_role args",
+        },
+    ];
+
+    for c in cases {
+        assert_panics_contains(c.name, c.expected_substring, || {
+            crate::rbac::generate_role_check(c.args.clone(), input.clone(), false);
+        });
+    }
+}
+
+// ============================================
+// Error cases: invalid function signature inputs (table-driven)
+// ============================================
+
+#[test]
+fn test_has_role_rejects_invalid_function_signature_table_driven() {
+    struct Case {
+        name: &'static str,
+        args: TokenStream,
+        input: TokenStream,
+        expected_substring: &'static str,
+    }
+
+    let args = quote! { caller, "minter" };
+    let cases = vec![
+        Case {
+            name: "no Env param",
+            args: args.clone(),
+            input: quote! { pub fn mint(caller: Address, amount: i128) {} },
+            expected_substring: "function must have an Env argument",
+        },
+        Case {
+            name: "param not in signature",
+            args: args.clone(),
+            input: quote! { pub fn mint(env: Env, account: Address, amount: i128) {} },
+            expected_substring: "not found in function signature",
+        },
+        Case {
+            name: "param not Address",
+            args: args.clone(),
+            input: quote! { pub fn mint(env: Env, caller: u32, amount: i128) {} },
+            expected_substring: "must be of type `Address` or `&Address`",
+        },
+        Case {
+            name: "wildcard Env pattern",
+            args: args.clone(),
+            input: quote! { pub fn mint(_: Env, caller: Address) {} },
+            expected_substring: "function must have an Env argument",
+        },
+        Case {
+            name: "tuple Env pattern",
+            args: args.clone(),
+            input: quote! { pub fn mint((env, _): (&Env, u32), caller: Address) { let _ = env; } },
+            expected_substring: "function must have an Env argument",
+        },
+        Case {
+            name: "struct Env pattern",
+            args: args.clone(),
+            input: quote! { pub fn mint(Env { .. }: Env, caller: Address) {} },
+            expected_substring: "function must have an Env argument",
+        },
+        Case {
+            name: "&&Address is invalid",
+            args: args.clone(),
+            input: quote! { pub fn mint(env: &Env, caller: &&Address) {} },
+            expected_substring: "must be of type `Address` or `&Address`",
+        },
+    ];
+
+    for c in cases {
+        assert_panics_contains(c.name, c.expected_substring, || {
+            crate::rbac::generate_role_check(c.args.clone(), c.input.clone(), false);
+        });
+    }
+}
+
+// ============================================
+// Error cases: non-function input
+// ============================================
+
+#[test]
+fn test_has_role_rejects_non_function_inputs() {
+    let args = quote! { caller, "minter" };
+    for (case, input) in filter_item_inputs_excluding_labels(&["function"]) {
+        assert_panics_contains(case, "failed to parse function", || {
+            crate::rbac::generate_role_check(args.clone(), input.clone(), false);
+        });
+    }
+}
+
+// ============================================
+// High-value coverage: Env + Address + role variants (table-driven)
+// ============================================
+
+#[test]
+fn test_has_role_env_variants_generate_correct_env_ref_in_ensure_role() {
+    struct Case {
+        name: &'static str,
+        input: TokenStream,
+        expected_ensure_stmt: &'static str,
+    }
+
+    // Role is a literal so we also validate Symbol::new uses the same env_ref form.
+    let args = quote! { caller, "minter" };
+
+    let cases = vec![
+        Case {
+            name: "owned Env",
+            input: quote! { pub fn mint(env: Env, caller: Address) {} },
+            expected_ensure_stmt: "utils::rbac::ensure_role(&env,&soroban_sdk::Symbol::new(&env,\"minter\"),&caller);",
+        },
+        Case {
+            name: "ref Env",
+            input: quote! { pub fn mint(env: &Env, caller: Address) {} },
+            expected_ensure_stmt: "utils::rbac::ensure_role(env,&soroban_sdk::Symbol::new(env,\"minter\"),&caller);",
+        },
+        Case {
+            name: "mut ref Env",
+            input: quote! { pub fn mint(env: &mut Env, caller: Address) {} },
+            expected_ensure_stmt: "utils::rbac::ensure_role(env,&soroban_sdk::Symbol::new(env,\"minter\"),&caller);",
+        },
+        Case {
+            name: "qualified owned Env",
+            input: quote! { pub fn mint(env: soroban_sdk::Env, caller: Address) {} },
+            expected_ensure_stmt: "utils::rbac::ensure_role(&env,&soroban_sdk::Symbol::new(&env,\"minter\"),&caller);",
+        },
+        Case {
+            name: "qualified ref Env",
+            input: quote! { pub fn mint(env: &soroban_sdk::Env, caller: Address) {} },
+            expected_ensure_stmt: "utils::rbac::ensure_role(env,&soroban_sdk::Symbol::new(env,\"minter\"),&caller);",
+        },
+        Case {
+            name: "leading :: qualified owned Env",
+            input: quote! { pub fn mint(env: ::soroban_sdk::Env, caller: Address) {} },
+            expected_ensure_stmt: "utils::rbac::ensure_role(&env,&soroban_sdk::Symbol::new(&env,\"minter\"),&caller);",
+        },
+    ];
+
+    for c in cases {
+        assert_role_check_exact_stmts(args.clone(), c.input, false, c.expected_ensure_stmt, None, Some(1), c.name);
+    }
+}
+
+#[test]
+fn test_has_role_address_variants_generate_correct_param_reference() {
+    struct Case {
+        name: &'static str,
+        input: TokenStream,
+        expected_ensure_stmt: &'static str,
+    }
+
+    let args = quote! { caller, "minter" };
+
+    let cases = vec![
+        Case {
+            name: "Address by value -> &caller",
+            input: quote! { pub fn mint(env: &Env, caller: Address) {} },
+            expected_ensure_stmt: "utils::rbac::ensure_role(env,&soroban_sdk::Symbol::new(env,\"minter\"),&caller);",
+        },
+        Case {
+            name: "&Address -> caller",
+            input: quote! { pub fn mint(env: &Env, caller: &Address) {} },
+            expected_ensure_stmt: "utils::rbac::ensure_role(env,&soroban_sdk::Symbol::new(env,\"minter\"),caller);",
+        },
+        Case {
+            name: "&mut Address -> caller",
+            input: quote! { pub fn mint(env: &Env, caller: &mut Address) {} },
+            expected_ensure_stmt: "utils::rbac::ensure_role(env,&soroban_sdk::Symbol::new(env,\"minter\"),caller);",
+        },
+        Case {
+            name: "qualified Address by value",
+            input: quote! { pub fn mint(env: &Env, caller: soroban_sdk::Address) {} },
+            expected_ensure_stmt: "utils::rbac::ensure_role(env,&soroban_sdk::Symbol::new(env,\"minter\"),&caller);",
+        },
+        Case {
+            name: "qualified &Address",
+            input: quote! { pub fn mint(env: &Env, caller: &soroban_sdk::Address) {} },
+            expected_ensure_stmt: "utils::rbac::ensure_role(env,&soroban_sdk::Symbol::new(env,\"minter\"),caller);",
+        },
+    ];
+
+    for c in cases {
+        assert_role_check_exact_stmts(args.clone(), c.input, false, c.expected_ensure_stmt, None, Some(1), c.name);
+    }
+}
+
+#[test]
+fn test_only_role_inserts_expected_statements_and_preserves_original_body() {
+    let args = quote! { caller, "minter" };
+    let input = quote! {
+        pub fn mint(env: Env, caller: Address) {
+            let x = 1u32;
+            let _ = x + 1;
+        }
+    };
+
+    let output_fn = assert_role_check_exact_stmts(
+        args,
+        input,
+        true,
+        "utils::rbac::ensure_role(&env,&soroban_sdk::Symbol::new(&env,\"minter\"),&caller);",
+        Some("caller.require_auth();"),
+        Some(4),
+        "only_role inserts ensure_role + require_auth",
+    );
+
+    // Ensure original statements remain after the inserted checks.
+    let third_stmt = &output_fn.block.stmts[2];
+    let third_stmt_str = quote::quote!(#third_stmt).to_string().replace(" ", "");
+    assert!(third_stmt_str.starts_with("letx=1u32;"), "expected original 'let x = 1u32;' to be preserved");
+}

package/contracts/common-macros/src/tests/snapshots/common_macros__tests__auth__snapshot_generated_multisig_code.snap

@@ -8,8 +8,8 @@ pub struct MyContract;
 use utils::{auth::Auth as _, multisig::MultiSig as _};
 #[common_macros::contract_impl]
 impl utils::auth::Auth for MyContract {
-    fn authorizer(env: &soroban_sdk::Env) -> soroban_sdk::Address {
-        env.current_contract_address()
+    fn authorizer(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
+        Some(env.current_contract_address())
     }
 }
 #[common_macros::contract_impl(contracttrait)]
@@ -23,8 +23,8 @@ pub struct MyContract(pub u32);
 use utils::{auth::Auth as _, multisig::MultiSig as _};
 #[common_macros::contract_impl]
 impl utils::auth::Auth for MyContract {
-    fn authorizer(env: &soroban_sdk::Env) -> soroban_sdk::Address {
-        env.current_contract_address()
+    fn authorizer(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
+        Some(env.current_contract_address())
     }
 }
 #[common_macros::contract_impl(contracttrait)]