@layerzerolabs/protocol-stellar-v2 0.2.9 → 0.2.11

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

@@ -19,15 +19,33 @@ fn snapshot_generated_ownable_code() {
 
 #[test]
 fn snapshot_only_owner_preserves_function_signature() {
-    let input = quote! {
+    // Test with borrowed Env (&Env) - should use env directly
+    let input_borrowed = quote! {
         pub(crate) async fn admin_action<T: Clone>(env: &Env, value: T) -> Result<T, Error> {
             Ok(value.clone())
         }
     };
-    let result = crate::ownable::prepend_only_owner_check(input);
-    let formatted = prettyplease::unparse(&syn::parse2::<syn::File>(result).expect("failed to parse generated code"));
+    let result_borrowed = crate::ownable::prepend_only_owner_check(input_borrowed);
+    let formatted_borrowed =
+        prettyplease::unparse(&syn::parse2::<syn::File>(result_borrowed).expect("failed to parse generated code"));
 
-    insta::assert_snapshot!(formatted);
+    // Test with owned Env - should produce &env reference in the generated code
+    let input_owned = quote! {
+        pub(crate) async fn admin_action<T: Clone>(env: Env, value: T) -> Result<T, Error> {
+            Ok(value.clone())
+        }
+    };
+    let result_owned = crate::ownable::prepend_only_owner_check(input_owned);
+    let formatted_owned =
+        prettyplease::unparse(&syn::parse2::<syn::File>(result_owned).expect("failed to parse generated code"));
+
+    // Combine all for single snapshot
+    let combined = format!(
+        "// === Borrowed Env (&Env) ===\n\n{}\n\n// === Owned Env (Env) ===\n\n{}",
+        formatted_borrowed, formatted_owned
+    );
+
+    insta::assert_snapshot!(combined);
 }
 
 // ============================================
@@ -35,7 +53,7 @@ fn snapshot_only_owner_preserves_function_signature() {
 // ============================================
 
 /// Helper function to verify that the owner check is correctly inserted at the beginning of a function.
-fn assert_owner_check_inserted(input: TokenStream, test_name: &str) {
+fn assert_owner_check_inserted(input: TokenStream, expected_env_ref: &str, test_name: &str) {
     let result_tokens = crate::ownable::prepend_only_owner_check(input);
     let output_fn: syn::ItemFn =
         syn::parse2(result_tokens).unwrap_or_else(|e| panic!("{}: failed to parse output function: {}", test_name, e));
@@ -43,7 +61,7 @@ fn assert_owner_check_inserted(input: TokenStream, test_name: &str) {
     assert!(!output_fn.block.stmts.is_empty(), "{}: function body should contain at least one statement", test_name);
 
     let first_stmt = &output_fn.block.stmts[0];
-    let expected_stmt = "utils::ownable::require_owner_auth::<Self>(my_custom_env);";
+    let expected_stmt = format!("utils::ownable::require_owner_auth::<Self>({});", expected_env_ref);
     let actual_stmt = quote::quote!(#first_stmt).to_string().replace(" ", "");
 
     assert_eq!(
@@ -55,15 +73,22 @@ fn assert_owner_check_inserted(input: TokenStream, test_name: &str) {
 
 #[test]
 fn test_only_owner_inserts_correct_code_at_the_beginning() {
+    // (description, input, expected_env_ref)
+    // Owned Env should produce &env, reference Env should produce env directly
     let test_cases = vec![
-        ("Env by value", quote! { pub fn f(my_custom_env: Env) {} }),
-        ("Env not first param", quote! { pub fn f(x: u32, my_custom_env: &Env) {} }),
-        ("Qualified path (soroban_sdk::Env)", quote! { pub fn f(my_custom_env: soroban_sdk::Env) {} }),
-        ("Nested reference (&&Env)", quote! { pub fn f(my_custom_env: &&Env) {} }),
+        ("Env by value", quote! { pub fn f(my_custom_env: Env) {} }, "&my_custom_env"),
+        ("Env not first param (ref)", quote! { pub fn f(x: u32, my_custom_env: &Env) {} }, "my_custom_env"),
+        (
+            "Qualified path (soroban_sdk::Env)",
+            quote! { pub fn f(my_custom_env: soroban_sdk::Env) {} },
+            "&my_custom_env",
+        ),
+        ("Reference to qualified path", quote! { pub fn f(my_custom_env: &soroban_sdk::Env) {} }, "my_custom_env"),
+        ("Nested reference (&&Env)", quote! { pub fn f(my_custom_env: &&Env) {} }, "my_custom_env"),
     ];
 
-    for (description, input) in test_cases {
-        assert_owner_check_inserted(input, description);
+    for (description, input, expected_env_ref) in test_cases {
+        assert_owner_check_inserted(input, expected_env_ref, description);
     }
 }
 
@@ -101,51 +126,3 @@ fn test_ownable_rejects_non_struct_inputs() {
         });
     }
 }
-
-// ============================================
-// is_env_type Unit Tests
-// ============================================
-
-#[test]
-fn test_is_env_type_recognizes_env_types() {
-    let env_types = [
-        "Env",
-        "&Env",
-        "&&Env",
-        "&mut Env",
-        "soroban_sdk::Env",
-        "&soroban_sdk::Env",
-        "some::deeply::nested::module::Env",
-    ];
-
-    for ty_str in env_types {
-        let ty = syn::parse_str::<syn::Type>(ty_str).expect("failed to parse type");
-        assert!(crate::utils::is_env_type(&ty), "{ty_str} should be recognized as an Env type");
-    }
-}
-
-#[test]
-fn test_is_env_type_rejects_non_env_types() {
-    let non_env_types = ["u32", "bool", "String", "Address", "&u32", "soroban_sdk::Address"];
-
-    for ty_str in non_env_types {
-        let ty = syn::parse_str::<syn::Type>(ty_str).expect("failed to parse type");
-        assert!(!crate::utils::is_env_type(&ty), "{ty_str} should NOT be recognized as an Env type");
-    }
-}
-
-#[test]
-fn test_is_env_type_rejects_other_type_variants() {
-    let other_variants = [
-        ("(Env, u32)", "tuple"),
-        ("[Env; 1]", "array"),
-        ("[Env]", "slice"),
-        ("Option<Env>", "generic"),
-        ("!", "never"),
-    ];
-
-    for (ty_str, label) in other_variants {
-        let ty = syn::parse_str::<syn::Type>(ty_str).expect("failed to parse type");
-        assert!(!crate::utils::is_env_type(&ty), "{label} type {ty_str} should NOT be recognized as an Env type");
-    }
-}

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

@@ -1,6 +1,6 @@
 ---
 source: contracts/common-macros/src/tests/contract_impl.rs
-assertion_line: 98
+assertion_line: 104
 expression: combined
 ---
 // === Inherent Impl (no attr) ===
@@ -9,7 +9,7 @@ expression: combined
 impl MyContract {
     /// Public method with Env - should have TTL extension
     pub fn public_with_env(env: Env, value: u32) -> u32 {
-        if let Some(instance_ttl) = utils::ttl::TtlConfigStorage::instance(env) {
+        if let Some(instance_ttl) = utils::ttl::TtlConfigStorage::instance(&env) {
             env.storage()
                 .instance()
                 .extend_ttl(instance_ttl.threshold, instance_ttl.extend_to);
@@ -18,7 +18,7 @@ impl MyContract {
     }
     /// Public method with qualified Env path - should have TTL extension
     pub fn with_qualified_env(env: soroban_sdk::Env) -> u32 {
-        if let Some(instance_ttl) = utils::ttl::TtlConfigStorage::instance(env) {
+        if let Some(instance_ttl) = utils::ttl::TtlConfigStorage::instance(&env) {
             env.storage()
                 .instance()
                 .extend_ttl(instance_ttl.threshold, instance_ttl.extend_to);
@@ -26,7 +26,7 @@ impl MyContract {
         42
     }
     /// Public method with Env not as first parameter - should have TTL extension
-    pub fn env_second(value: u32, env: Env) -> u32 {
+    pub fn env_second(value: u32, env: &Env) -> u32 {
         if let Some(instance_ttl) = utils::ttl::TtlConfigStorage::instance(env) {
             env.storage()
                 .instance()
@@ -55,7 +55,7 @@ impl MyContract {
 impl SomeTrait for MyContract {
     /// Trait method with Env - should have TTL extension
     fn trait_method_with_env(env: Env, value: u32) -> u32 {
-        if let Some(instance_ttl) = utils::ttl::TtlConfigStorage::instance(env) {
+        if let Some(instance_ttl) = utils::ttl::TtlConfigStorage::instance(&env) {
             env.storage()
                 .instance()
                 .extend_ttl(instance_ttl.threshold, instance_ttl.extend_to);
@@ -66,6 +66,16 @@ impl SomeTrait for MyContract {
     fn trait_method_without_env(value: u32) -> u32 {
         value * 4
     }
+    /// Trait method with macro attribute - should have TTL extension
+    #[common_macros::only_owner]
+    fn trait_method_with_only_owner_attribute(env: Env, value: u32) -> u32 {
+        if let Some(instance_ttl) = utils::ttl::TtlConfigStorage::instance(&env) {
+            env.storage()
+                .instance()
+                .extend_ttl(instance_ttl.threshold, instance_ttl.extend_to);
+        }
+        value * 5
+    }
 }
 
 
@@ -74,7 +84,7 @@ impl SomeTrait for MyContract {
 #[soroban_sdk::contractimpl(contracttrait)]
 impl AnotherTrait for MyContract {
     /// Trait method with contracttrait attr - should have TTL extension
-    fn contracttrait_method(env: Env, value: u32) -> u32 {
+    fn contracttrait_method(env: &Env, value: u32) -> u32 {
         if let Some(instance_ttl) = utils::ttl::TtlConfigStorage::instance(env) {
             env.storage()
                 .instance()

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

@@ -0,0 +1,20 @@
+---
+source: contracts/common-macros/src/tests/error.rs
+expression: formatted
+---
+#[soroban_sdk::contracterror]
+#[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
+#[repr(u32)]
+/// Example error enum
+pub enum MyError {
+    /// Implicit (should start at 1)
+    A = 1u32,
+    /// Implicit (should be 2)
+    B = 2u32,
+    /// Explicit (must be >= previous + 1)
+    C = 10,
+    /// Implicit (should be 11)
+    D = 11u32,
+    /// Explicit max boundary (u32::MAX)
+    E = 4294967295,
+}

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

@@ -16,14 +16,16 @@ impl utils::ownable::OwnableInitializer for MyContract {
     }
 }
 /// Implement the Ownable trait for the contract.
-#[soroban_sdk::contractimpl]
+#[common_macros::contract_impl]
 impl utils::ownable::Ownable for MyContract {
     fn owner(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
         utils::ownable::DefaultOwnable::owner(env)
     }
+    #[common_macros::only_owner]
     fn transfer_ownership(env: &soroban_sdk::Env, new_owner: &soroban_sdk::Address) {
         utils::ownable::DefaultOwnable::transfer_ownership(env, new_owner)
     }
+    #[common_macros::only_owner]
     fn renounce_ownership(env: &soroban_sdk::Env) {
         utils::ownable::DefaultOwnable::renounce_ownership(env)
     }

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

@@ -1,9 +1,19 @@
 ---
 source: contracts/common-macros/src/tests/ownable.rs
-assertion_line: 28
-expression: formatted
+assertion_line: 48
+expression: combined
 ---
+// === Borrowed Env (&Env) ===
+
 pub(crate) async fn admin_action<T: Clone>(env: &Env, value: T) -> Result<T, Error> {
     utils::ownable::require_owner_auth::<Self>(env);
     Ok(value.clone())
 }
+
+
+// === Owned Env (Env) ===
+
+pub(crate) async fn admin_action<T: Clone>(env: Env, value: T) -> Result<T, Error> {
+    utils::ownable::require_owner_auth::<Self>(&env);
+    Ok(value.clone())
+}

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

@@ -8,7 +8,7 @@ pub struct MyContract {
     some_field: u32,
 }
 use utils::ttl::TtlConfigurable as _;
-#[soroban_sdk::contractimpl]
+#[common_macros::contract_impl]
 impl utils::ttl::TtlConfigurable for MyContract {
     #[common_macros::only_owner]
     fn set_ttl_configs(
@@ -31,6 +31,10 @@ impl utils::ttl::TtlConfigurable for MyContract {
         utils::ttl::DefaultTtlConfigurable::is_ttl_configs_frozen(env)
     }
 }
+/// Uses `soroban_sdk::contractimpl` directly instead of `common_macros::contract_impl`
+/// because `contract_impl` automatically extends TTL on every invocation. Since this
+/// impl block provides manual TTL extension control, auto-extension would be redundant
+/// and could mask the intended behavior of `extend_instance_ttl`.
 #[soroban_sdk::contractimpl]
 impl MyContract {
     /// Extends the instance TTL.

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

@@ -0,0 +1,267 @@
+use quote::quote;
+use syn::{parse_quote, punctuated::Punctuated, token::Comma, FnArg};
+
+use crate::tests::test_helpers::assert_panics_contains;
+
+// ============================================
+// find_env_param Tests
+// ============================================
+
+fn parse_fn_args(input: proc_macro2::TokenStream) -> Punctuated<FnArg, Comma> {
+    let item_fn: syn::ItemFn = syn::parse2(input).expect("failed to parse function");
+    item_fn.sig.inputs
+}
+
+#[test]
+fn test_find_env_param_owned_env_is_not_reference() {
+    let args = parse_fn_args(quote! { fn f(env: Env) {} });
+    let param = crate::utils::find_env_param(&args);
+    assert!(param.is_some());
+    let param = param.unwrap();
+    assert_eq!(param.ident.to_string(), "env");
+    assert!(!param.is_reference, "Env should not be marked as reference");
+}
+
+#[test]
+fn test_find_env_param_ref_env_is_reference() {
+    let args = parse_fn_args(quote! { fn f(env: &Env) {} });
+    let param = crate::utils::find_env_param(&args);
+    assert!(param.is_some());
+    let param = param.unwrap();
+    assert_eq!(param.ident.to_string(), "env");
+    assert!(param.is_reference, "&Env should be marked as reference");
+}
+
+#[test]
+fn test_find_env_param_mut_ref_env_is_reference() {
+    let args = parse_fn_args(quote! { fn f(env: &mut Env) {} });
+    let param = crate::utils::find_env_param(&args);
+    assert!(param.is_some());
+    let param = param.unwrap();
+    assert_eq!(param.ident.to_string(), "env");
+    assert!(param.is_reference, "&mut Env should be marked as reference");
+}
+
+#[test]
+fn test_find_env_param_qualified_owned_env() {
+    let args = parse_fn_args(quote! { fn f(my_env: soroban_sdk::Env) {} });
+    let param = crate::utils::find_env_param(&args);
+    assert!(param.is_some());
+    let param = param.unwrap();
+    assert_eq!(param.ident.to_string(), "my_env");
+    assert!(!param.is_reference, "soroban_sdk::Env should not be marked as reference");
+}
+
+#[test]
+fn test_find_env_param_qualified_ref_env() {
+    let args = parse_fn_args(quote! { fn f(my_env: &soroban_sdk::Env) {} });
+    let param = crate::utils::find_env_param(&args);
+    assert!(param.is_some());
+    let param = param.unwrap();
+    assert_eq!(param.ident.to_string(), "my_env");
+    assert!(param.is_reference, "&soroban_sdk::Env should be marked as reference");
+}
+
+#[test]
+fn test_find_env_param_returns_none_for_no_env() {
+    let args = parse_fn_args(quote! { fn f(x: u32) {} });
+    let param = crate::utils::find_env_param(&args);
+    assert!(param.is_none());
+}
+
+#[test]
+fn test_find_env_param_finds_deeply_nested_env() {
+    let args = parse_fn_args(quote! { fn f(e: some::deep::module::Env) {} });
+    let param = crate::utils::find_env_param(&args);
+    assert!(param.is_some());
+    let param = param.unwrap();
+    assert_eq!(param.ident.to_string(), "e");
+    assert!(!param.is_reference, "some::deep::module::Env should not be marked as reference");
+}
+
+#[test]
+fn test_find_env_param_finds_env_not_first_param() {
+    let args = parse_fn_args(quote! { fn f(x: u32, y: String, env: &Env) {} });
+    let param = crate::utils::find_env_param(&args);
+    assert!(param.is_some());
+    let param = param.unwrap();
+    assert_eq!(param.ident.to_string(), "env");
+    assert!(param.is_reference, "&Env should be marked as reference");
+}
+
+#[test]
+fn test_find_env_param_returns_first_env_when_multiple() {
+    let args = parse_fn_args(quote! { fn f(first_env: Env, second_env: Env) {} });
+    let param = crate::utils::find_env_param(&args);
+    assert!(param.is_some());
+    let param = param.unwrap();
+    assert_eq!(param.ident.to_string(), "first_env");
+    assert!(!param.is_reference, "first_env should not be marked as reference");
+}
+
+#[test]
+fn test_find_env_param_returns_none_for_empty_args() {
+    let args = parse_fn_args(quote! { fn f() {} });
+    let param = crate::utils::find_env_param(&args);
+    assert!(param.is_none());
+}
+
+#[test]
+fn test_find_env_param_returns_none_for_wildcard_pattern() {
+    // Wildcard pattern _ is not a valid identifier pattern
+    let args = parse_fn_args(quote! { fn f(_: Env) {} });
+    let param = crate::utils::find_env_param(&args);
+    assert!(param.is_none());
+}
+
+#[test]
+fn test_find_env_param_returns_none_for_tuple_pattern() {
+    // Tuple destructuring is not a simple identifier pattern
+    let args = parse_fn_args(quote! { fn f((env, _): (Env, u32)) {} });
+    let param = crate::utils::find_env_param(&args);
+    assert!(param.is_none());
+}
+
+#[test]
+fn test_find_env_param_ignores_self_receiver() {
+    // Method with self receiver - find_env_param should skip receiver and find env
+    let args: Punctuated<FnArg, Comma> = parse_quote!(&self, env: &Env);
+    let param = crate::utils::find_env_param(&args);
+    assert!(param.is_some());
+    let param = param.unwrap();
+    assert_eq!(param.ident.to_string(), "env");
+    assert!(param.is_reference, "&Env should be marked as reference");
+}
+
+#[test]
+fn test_find_env_param_returns_none_for_self_only() {
+    // Method with only self receiver
+    let args: Punctuated<FnArg, Comma> = parse_quote!(&self);
+    let param = crate::utils::find_env_param(&args);
+    assert!(param.is_none());
+}
+
+#[test]
+fn test_find_env_param_with_double_reference() {
+    let args = parse_fn_args(quote! { fn f(env: &&Env) {} });
+    let param = crate::utils::find_env_param(&args);
+    assert!(param.is_some());
+    let param = param.unwrap();
+    assert_eq!(param.ident.to_string(), "env");
+    assert!(param.is_reference, "&&Env should be marked as reference");
+}
+
+// ============================================
+// expect_env_param Tests
+// ============================================
+
+#[test]
+fn test_expect_env_param_returns_param_for_owned_env() {
+    let args = parse_fn_args(quote! { fn f(env: Env) {} });
+    let param = crate::utils::expect_env_param(&args);
+    assert_eq!(param.ident.to_string(), "env");
+    assert!(!param.is_reference);
+}
+
+#[test]
+fn test_expect_env_param_returns_param_for_ref_env() {
+    let args = parse_fn_args(quote! { fn f(env: &Env) {} });
+    let param = crate::utils::expect_env_param(&args);
+    assert_eq!(param.ident.to_string(), "env");
+    assert!(param.is_reference);
+}
+
+#[test]
+fn test_expect_env_param_panics_when_no_env() {
+    assert_panics_contains("no Env param", "function must have an Env argument", || {
+        let args = parse_fn_args(quote! { fn f(x: u32) {} });
+        crate::utils::expect_env_param(&args);
+    });
+}
+
+// ============================================
+// EnvParam::as_ref_tokens Tests
+// ============================================
+
+#[test]
+fn test_as_ref_tokens_for_owned_env_adds_ampersand() {
+    let args = parse_fn_args(quote! { fn f(env: Env) {} });
+    let param = crate::utils::find_env_param(&args).unwrap();
+    let tokens = param.as_ref_tokens();
+    // For owned Env, as_ref_tokens should produce `&env`
+    assert_eq!(tokens.to_string(), "& env");
+}
+
+#[test]
+fn test_as_ref_tokens_for_ref_env_no_ampersand() {
+    let args = parse_fn_args(quote! { fn f(env: &Env) {} });
+    let param = crate::utils::find_env_param(&args).unwrap();
+    let tokens = param.as_ref_tokens();
+    // For reference Env, as_ref_tokens should produce `env` (no extra &)
+    assert_eq!(tokens.to_string(), "env");
+}
+
+#[test]
+fn test_as_ref_tokens_for_custom_named_owned_env() {
+    let args = parse_fn_args(quote! { fn f(my_environment: Env) {} });
+    let param = crate::utils::find_env_param(&args).unwrap();
+    let tokens = param.as_ref_tokens();
+    assert_eq!(tokens.to_string(), "& my_environment");
+}
+
+#[test]
+fn test_as_ref_tokens_for_custom_named_ref_env() {
+    let args = parse_fn_args(quote! { fn f(my_environment: &Env) {} });
+    let param = crate::utils::find_env_param(&args).unwrap();
+    let tokens = param.as_ref_tokens();
+    assert_eq!(tokens.to_string(), "my_environment");
+}
+
+// ============================================
+// is_env_type Tests (comprehensive coverage)
+// ============================================
+
+#[test]
+fn test_is_env_type_recognizes_env_types() {
+    let env_types = [
+        "Env",
+        "&Env",
+        "&&Env",
+        "&mut Env",
+        "soroban_sdk::Env",
+        "&soroban_sdk::Env",
+        "some::deeply::nested::module::Env",
+    ];
+
+    for ty_str in env_types {
+        let ty = syn::parse_str::<syn::Type>(ty_str).expect("failed to parse type");
+        assert!(crate::utils::is_env_type(&ty), "{ty_str} should be recognized as an Env type");
+    }
+}
+
+#[test]
+fn test_is_env_type_rejects_non_env_types() {
+    let non_env_types = ["u32", "bool", "String", "Address", "&u32", "soroban_sdk::Address", "Environment"];
+
+    for ty_str in non_env_types {
+        let ty = syn::parse_str::<syn::Type>(ty_str).expect("failed to parse type");
+        assert!(!crate::utils::is_env_type(&ty), "{ty_str} should NOT be recognized as an Env type");
+    }
+}
+
+#[test]
+fn test_is_env_type_rejects_other_type_variants() {
+    let other_variants = [
+        ("(Env, u32)", "tuple"),
+        ("[Env; 1]", "array"),
+        ("[Env]", "slice"),
+        ("Option<Env>", "generic"),
+        ("!", "never"),
+        ("fn() -> Env", "fn pointer"),
+    ];
+
+    for (ty_str, label) in other_variants {
+        let ty = syn::parse_str::<syn::Type>(ty_str).expect("failed to parse type");
+        assert!(!crate::utils::is_env_type(&ty), "{label} type {ty_str} should NOT be recognized as an Env type");
+    }
+}

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

@@ -19,8 +19,7 @@ pub fn generate_ttl_configurable_impl(input: TokenStream) -> TokenStream {
     let expanded = quote! {
         use utils::ttl::TtlConfigurable as _;
 
-        // TODO: should use custom contract_impl macro instead of soroban_sdk::contractimpl
-        #[soroban_sdk::contractimpl]
+        #[common_macros::contract_impl]
         impl utils::ttl::TtlConfigurable for #name {
 
             #[common_macros::only_owner]
@@ -53,17 +52,21 @@ pub fn generate_ttl_configurable_impl(input: TokenStream) -> TokenStream {
     };
 
     let inherent_impl = quote! {
+        /// Uses `soroban_sdk::contractimpl` directly instead of `common_macros::contract_impl`
+        /// because `contract_impl` automatically extends TTL on every invocation. Since this
+        /// impl block provides manual TTL extension control, auto-extension would be redundant
+        /// and could mask the intended behavior of `extend_instance_ttl`.
         #[soroban_sdk::contractimpl]
-            impl #name {
-                /// Extends the instance TTL.
-                ///
-                /// # Arguments
-                ///
-                /// * `threshold` - The threshold to extend the TTL.
-                /// * `extend_to` - The TTL to extend to.
-                pub fn extend_instance_ttl(env: &soroban_sdk::Env, threshold: u32, extend_to: u32) {
-                    env.storage().instance().extend_ttl(threshold, extend_to);
-                }
+        impl #name {
+            /// Extends the instance TTL.
+            ///
+            /// # Arguments
+            ///
+            /// * `threshold` - The threshold to extend the TTL.
+            /// * `extend_to` - The TTL to extend to.
+            pub fn extend_instance_ttl(env: &soroban_sdk::Env, threshold: u32, extend_to: u32) {
+                env.storage().instance().extend_ttl(threshold, extend_to);
+            }
         }
     };
 

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

@@ -1,20 +1,44 @@
+use proc_macro2::TokenStream;
+use quote::quote;
 use syn::{punctuated::Punctuated, token::Comma, FnArg, Ident, Pat, Type, TypePath};
 
-/// Finds the `Env` argument identifier in a function signature.
-pub fn find_env_ident(args: &Punctuated<FnArg, Comma>) -> Option<&Ident> {
+/// Information about an `Env` parameter in a function signature.
+pub struct EnvParam<'a> {
+    /// The identifier of the Env parameter
+    pub ident: &'a Ident,
+    /// Whether the parameter is a reference type (`&Env` or `&mut Env`)
+    pub is_reference: bool,
+}
+
+impl EnvParam<'_> {
+    /// Returns a token stream that produces a `&Env` reference.
+    /// - If the parameter is already a reference (`&Env`), returns the ident as-is
+    /// - If the parameter is owned (`Env`), returns `&ident`
+    pub fn as_ref_tokens(&self) -> TokenStream {
+        let ident = self.ident;
+        if self.is_reference {
+            quote!(#ident)
+        } else {
+            quote!(&#ident)
+        }
+    }
+}
+
+/// Finds the `Env` argument in a function signature and returns its info.
+pub fn find_env_param(args: &Punctuated<FnArg, Comma>) -> Option<EnvParam<'_>> {
     args.iter().find_map(|arg| {
         let FnArg::Typed(pat_type) = arg else { return None };
         if !is_env_type(&pat_type.ty) {
             return None;
         }
         let Pat::Ident(pat) = pat_type.pat.as_ref() else { return None };
-        Some(&pat.ident)
+        Some(EnvParam { ident: &pat.ident, is_reference: is_reference_type(&pat_type.ty) })
     })
 }
 
-/// Expects the `Env` argument identifier in a function signature.
-pub fn expect_env_ident(args: &Punctuated<FnArg, Comma>) -> &Ident {
-    find_env_ident(args).expect("function must have an Env argument")
+/// Expects the `Env` argument in a function signature and returns its info.
+pub fn expect_env_param(args: &Punctuated<FnArg, Comma>) -> EnvParam<'_> {
+    find_env_param(args).expect("function must have an Env argument")
 }
 
 /// Checks if a type is an `Env` type.
@@ -25,3 +49,8 @@ pub fn is_env_type(ty: &Type) -> bool {
         _ => false,
     }
 }
+
+/// Checks if a type is a reference type.
+fn is_reference_type(ty: &Type) -> bool {
+    matches!(ty, Type::Reference(_))
+}

package/contracts/message-libs/uln-302/src/receive_uln.rs

@@ -4,7 +4,7 @@ use super::*;
 // IReceiveUln302 Contract Implementation
 // ============================================================================================
 
-#[contractimpl(contracttrait)]
+#[contract_impl(contracttrait)]
 impl IReceiveUln302 for Uln302 {
     /// Called by a DVN to verify a message with a specific number of block confirmations.
     ///