@layerzerolabs/protocol-stellar-v2 0.2.21 → 0.2.23

package/contracts/common-macros/src/tests/storage/storage_kind.rs

@@ -0,0 +1,39 @@
+//! Unit tests for the `StorageKind` enum methods via wrapper functions.
+
+use crate::storage::test::{
+    storage_kind_instance_accessor, storage_kind_instance_name, storage_kind_persistent_accessor,
+    storage_kind_persistent_name, storage_kind_temporary_accessor, storage_kind_temporary_name,
+};
+
+#[test]
+fn test_instance_name() {
+    assert_eq!(storage_kind_instance_name(), "instance");
+}
+
+#[test]
+fn test_persistent_name() {
+    assert_eq!(storage_kind_persistent_name(), "persistent");
+}
+
+#[test]
+fn test_temporary_name() {
+    assert_eq!(storage_kind_temporary_name(), "temporary");
+}
+
+#[test]
+fn test_instance_accessor() {
+    let accessor = storage_kind_instance_accessor();
+    assert_eq!(accessor.to_string(), "env . storage () . instance ()");
+}
+
+#[test]
+fn test_persistent_accessor() {
+    let accessor = storage_kind_persistent_accessor();
+    assert_eq!(accessor.to_string(), "env . storage () . persistent ()");
+}
+
+#[test]
+fn test_temporary_accessor() {
+    let accessor = storage_kind_temporary_accessor();
+    assert_eq!(accessor.to_string(), "env . storage () . temporary ()");
+}

package/contracts/common-macros/src/tests/storage/test_setup.rs

@@ -0,0 +1,25 @@
+//! Shared helpers for storage macro unit tests.
+//!
+//! Keep these helpers scoped to the storage test module to avoid leaking
+//! test-only utilities across the crate.
+/// Parse the first `syn::Variant` from a single-variant `enum` token stream.
+pub(in crate::tests::storage) fn parse_variant(input: proc_macro2::TokenStream) -> syn::Variant {
+    let item_enum: syn::ItemEnum = syn::parse2(input).expect("failed to parse enum");
+    item_enum.variants.into_iter().next().expect("no variant found")
+}
+
+/// Parse the attributes from the first variant in a single-variant `enum` token stream.
+pub(in crate::tests::storage) fn parse_attrs(input: proc_macro2::TokenStream) -> Vec<syn::Attribute> {
+    let item_enum: syn::ItemEnum = syn::parse2(input).expect("failed to parse enum");
+    item_enum.variants.into_iter().next().expect("no variant found").attrs
+}
+
+/// Normalize whitespace in a `TokenStream` for stable string comparisons.
+pub(in crate::tests::storage) fn normalize(ts: proc_macro2::TokenStream) -> String {
+    ts.to_string().split_whitespace().collect::<Vec<_>>().join(" ")
+}
+
+/// Convenience for tests building input via `format!(...)`.
+pub(in crate::tests::storage) fn parse_variant_str(input: &str) -> syn::Variant {
+    parse_variant(input.parse().expect("failed to parse token stream"))
+}

package/contracts/common-macros/src/tests/storage/validate_attrs.rs

@@ -0,0 +1,138 @@
+//! Unit tests for the `validate_attrs` function.
+
+use crate::storage::test::{known_attrs_for_test, validate_attrs_for_test};
+use quote::{format_ident, quote};
+
+use super::test_setup::parse_attrs;
+
+#[test]
+fn test_accepts_known_attributes() {
+    let known_attrs = known_attrs_for_test();
+
+    for attr_name in known_attrs {
+        if *attr_name == "doc" {
+            // doc attribute uses /// syntax
+            let attrs = parse_attrs(quote! {
+                enum Test {
+                    /// This is a doc comment
+                    #[persistent(u32)]
+                    Variant,
+                }
+            });
+            let variant_ident = format_ident!("Variant");
+            assert!(validate_attrs_for_test(&attrs, &variant_ident).is_ok(), "doc attribute should be accepted");
+        } else {
+            // Other attributes use #[attr] or #[attr(...)] syntax
+            let input = match *attr_name {
+                "instance" => quote! {
+                    enum Test {
+                        #[instance(u32)]
+                        Variant,
+                    }
+                },
+                "persistent" => quote! {
+                    enum Test {
+                        #[persistent(u32)]
+                        Variant,
+                    }
+                },
+                "temporary" => quote! {
+                    enum Test {
+                        #[temporary(u32)]
+                        Variant,
+                    }
+                },
+                "default" => quote! {
+                    enum Test {
+                        #[persistent(u32)]
+                        #[default(0)]
+                        Variant,
+                    }
+                },
+                "name" => quote! {
+                    enum Test {
+                        #[persistent(u32)]
+                        #[name("custom")]
+                        Variant,
+                    }
+                },
+                "no_ttl_extension" => quote! {
+                    enum Test {
+                        #[persistent(u32)]
+                        #[no_ttl_extension]
+                        Variant,
+                    }
+                },
+                _ => continue,
+            };
+
+            let attrs = parse_attrs(input);
+            let variant_ident = format_ident!("Variant");
+            assert!(
+                validate_attrs_for_test(&attrs, &variant_ident).is_ok(),
+                "attribute '{}' should be accepted",
+                attr_name
+            );
+        }
+    }
+}
+
+#[test]
+fn test_rejects_unknown_attribute() {
+    let attrs = parse_attrs(quote! {
+        enum Test {
+            #[persistent(u32)]
+            #[unknown_attr]
+            Variant,
+        }
+    });
+    let variant_ident = format_ident!("Variant");
+
+    let result = validate_attrs_for_test(&attrs, &variant_ident);
+    assert!(result.is_err(), "unknown attribute should be rejected");
+    let err = result.unwrap_err();
+    assert!(
+        err.contains("unknown attribute 'unknown_attr' on variant 'Variant'"),
+        "error should mention unknown attribute"
+    );
+}
+
+#[test]
+fn test_accepts_multiple_valid_attributes() {
+    let attrs = parse_attrs(quote! {
+        enum Test {
+            /// Doc comment
+            #[persistent(u32)]
+            #[default(0)]
+            #[name("custom")]
+            Variant,
+        }
+    });
+    let variant_ident = format_ident!("Variant");
+
+    assert!(validate_attrs_for_test(&attrs, &variant_ident).is_ok(), "multiple valid attributes should be accepted");
+}
+
+#[test]
+fn test_empty_attrs_is_valid() {
+    let attrs: Vec<syn::Attribute> = vec![];
+    let variant_ident = format_ident!("Variant");
+
+    // Empty attrs is valid for validate_attrs (storage type check is separate)
+    assert!(validate_attrs_for_test(&attrs, &variant_ident).is_ok());
+}
+
+#[test]
+fn test_rejects_path_attribute() {
+    let attrs = parse_attrs(quote! {
+        enum Test {
+            #[persistent(u32)]
+            #[some::path::attr]
+            Variant,
+        }
+    });
+    let variant_ident = format_ident!("Variant");
+
+    let result = validate_attrs_for_test(&attrs, &variant_ident);
+    assert!(result.is_err(), "path attributes should be rejected");
+}

package/contracts/common-macros/src/tests/storage/variant_config.rs

@@ -0,0 +1,226 @@
+//! Unit tests for the `VariantConfig` struct and its `TryFrom` implementation via wrapper functions.
+
+use crate::storage::test::{get_variant_config_for_test, get_variant_method_names_for_test};
+use quote::quote;
+
+use super::test_setup::parse_variant;
+
+// ============================================================================
+// TryFrom<&Variant> Tests
+// ============================================================================
+
+#[test]
+fn test_try_from_instance_variant() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[instance(u32)]
+            Counter,
+        }
+    });
+
+    let config = get_variant_config_for_test(&variant);
+    assert!(config.is_ok());
+    let config = config.unwrap();
+    assert_eq!(config.kind_name, "instance");
+    assert_eq!(config.value_type, "u32");
+    assert_eq!(config.name, "counter"); // snake_case conversion
+    assert!(!config.auto_ttl); // instance storage doesn't have auto TTL
+    assert!(!config.has_default);
+}
+
+#[test]
+fn test_try_from_persistent_variant() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[persistent(Address)]
+            Owner,
+        }
+    });
+
+    let config = get_variant_config_for_test(&variant);
+    assert!(config.is_ok());
+    let config = config.unwrap();
+    assert_eq!(config.kind_name, "persistent");
+    assert_eq!(config.value_type, "Address");
+    assert_eq!(config.name, "owner");
+    assert!(config.auto_ttl); // persistent has auto TTL by default
+    assert!(!config.has_default);
+}
+
+#[test]
+fn test_try_from_temporary_variant() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[temporary(bool)]
+            Flag,
+        }
+    });
+
+    let config = get_variant_config_for_test(&variant);
+    assert!(config.is_ok());
+    let config = config.unwrap();
+    assert_eq!(config.kind_name, "temporary");
+    assert_eq!(config.value_type, "bool");
+    assert_eq!(config.name, "flag");
+    assert!(!config.auto_ttl); // temporary doesn't have auto TTL
+    assert!(!config.has_default);
+}
+
+#[test]
+fn test_try_from_with_default() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[instance(u32)]
+            #[default(0)]
+            Counter,
+        }
+    });
+
+    let config = get_variant_config_for_test(&variant);
+    assert!(config.is_ok());
+    let config = config.unwrap();
+    assert!(config.has_default);
+}
+
+#[test]
+fn test_try_from_with_custom_name() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[instance(u32)]
+            #[name("custom_name")]
+            Counter,
+        }
+    });
+
+    let config = get_variant_config_for_test(&variant);
+    assert!(config.is_ok());
+    let config = config.unwrap();
+    assert_eq!(config.name, "custom_name");
+}
+
+#[test]
+fn test_try_from_snake_case_conversion() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[instance(u32)]
+            MyLongVariantName,
+        }
+    });
+
+    let config = get_variant_config_for_test(&variant);
+    assert!(config.is_ok());
+    let config = config.unwrap();
+    assert_eq!(config.name, "my_long_variant_name");
+}
+
+#[test]
+fn test_try_from_persistent_with_no_ttl_extension() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[persistent(u32)]
+            #[no_ttl_extension]
+            CachedValue,
+        }
+    });
+
+    let config = get_variant_config_for_test(&variant);
+    assert!(config.is_ok());
+    let config = config.unwrap();
+    assert_eq!(config.kind_name, "persistent");
+    assert!(!config.auto_ttl); // disabled by no_ttl_extension
+}
+
+#[test]
+fn test_try_from_error_no_ttl_extension_on_instance() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[instance(u32)]
+            #[no_ttl_extension]
+            Counter,
+        }
+    });
+
+    let config = get_variant_config_for_test(&variant);
+    assert!(config.is_err());
+    let err = config.unwrap_err();
+    assert!(err.contains("can only be used with #[persistent"));
+}
+
+#[test]
+fn test_try_from_error_no_ttl_extension_on_temporary() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[temporary(u32)]
+            #[no_ttl_extension]
+            TempData,
+        }
+    });
+
+    let config = get_variant_config_for_test(&variant);
+    assert!(config.is_err());
+    let err = config.unwrap_err();
+    assert!(err.contains("can only be used with #[persistent"));
+}
+
+#[test]
+fn test_try_from_error_unknown_attribute() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[persistent(u32)]
+            #[unknown_attr]
+            Counter,
+        }
+    });
+
+    let config = get_variant_config_for_test(&variant);
+    assert!(config.is_err());
+    let err = config.unwrap_err();
+    assert!(err.contains("unknown attribute"));
+}
+
+// ============================================================================
+// method_names() Tests
+// ============================================================================
+
+#[test]
+fn test_method_names_basic() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[instance(u32)]
+            Counter,
+        }
+    });
+
+    let result = get_variant_method_names_for_test(&variant);
+    assert!(result.is_ok());
+    let (getter, setter, remover, set_or_remove, has, ttl_extender) = result.unwrap();
+
+    assert_eq!(getter, "counter");
+    assert_eq!(setter, "set_counter");
+    assert_eq!(remover, "remove_counter");
+    assert_eq!(set_or_remove, "set_or_remove_counter");
+    assert_eq!(has, "has_counter");
+    assert_eq!(ttl_extender, "extend_counter_ttl");
+}
+
+#[test]
+fn test_method_names_with_custom_name() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[instance(u32)]
+            #[name("custom")]
+            Counter,
+        }
+    });
+
+    let result = get_variant_method_names_for_test(&variant);
+    assert!(result.is_ok());
+    let (getter, setter, remover, set_or_remove, has, ttl_extender) = result.unwrap();
+
+    assert_eq!(getter, "custom");
+    assert_eq!(setter, "set_custom");
+    assert_eq!(remover, "remove_custom");
+    assert_eq!(set_or_remove, "set_or_remove_custom");
+    assert_eq!(has, "has_custom");
+    assert_eq!(ttl_extender, "extend_custom_ttl");
+}

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

@@ -22,12 +22,10 @@ where
     );
 }
 
-pub(in crate::tests) fn non_struct_item_inputs() -> Vec<(&'static str, proc_macro2::TokenStream)> {
-    filter_item_inputs_excluding_labels(&["struct"])
-}
-
-pub(in crate::tests) fn non_enum_item_inputs() -> Vec<(&'static str, proc_macro2::TokenStream)> {
-    filter_item_inputs_excluding_labels(&["enum"])
+pub(in crate::tests) fn filter_item_inputs_excluding_labels(
+    excluded: &[&str],
+) -> Vec<(&'static str, proc_macro2::TokenStream)> {
+    item_inputs().into_iter().filter(|(label, _)| !excluded.iter().any(|x| x == label)).collect()
 }
 
 /// Canonical list of syntactically-valid `syn::Item` inputs.
@@ -87,7 +85,3 @@ pub(in crate::tests) fn item_inputs() -> Vec<(&'static str, proc_macro2::TokenSt
         ("type alias", quote::quote! { type AnAlias = u32; }),
     ]
 }
-
-fn filter_item_inputs_excluding_labels(excluded: &[&str]) -> Vec<(&'static str, proc_macro2::TokenStream)> {
-    item_inputs().into_iter().filter(|(label, _)| !excluded.iter().any(|x| x == label)).collect()
-}

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

@@ -1,6 +1,6 @@
 use quote::quote;
 
-use crate::tests::test_helpers::{assert_panics_contains, non_struct_item_inputs};
+use crate::tests::test_helpers::{assert_panics_contains, filter_item_inputs_excluding_labels};
 
 // ============================================
 // Snapshot Test: TtlConfigurable Code Generation
@@ -26,7 +26,7 @@ fn snapshot_generated_ttl_configurable_code() {
 
 #[test]
 fn test_ttl_configurable_rejects_non_struct_inputs() {
-    for (case, input) in non_struct_item_inputs() {
+    for (case, input) in filter_item_inputs_excluding_labels(&["struct"]) {
         assert_panics_contains(case, "failed to parse struct", || {
             crate::ttl_configurable::generate_ttl_configurable_impl(input.clone());
         });

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

@@ -0,0 +1,32 @@
+use quote::quote;
+
+use crate::tests::test_helpers::{assert_panics_contains, filter_item_inputs_excluding_labels};
+
+// ============================================
+// Snapshot Test: TtlExtendable Code Generation
+// ============================================
+
+#[test]
+fn snapshot_generated_ttl_extendable_code() {
+    let input = quote! {
+        pub struct MyContract;
+    };
+
+    let result = crate::ttl_extendable::generate_ttl_extendable_impl(input);
+    let formatted = prettyplease::unparse(&syn::parse2::<syn::File>(result).expect("failed to parse generated code"));
+
+    insta::assert_snapshot!(formatted);
+}
+
+// ============================================
+// Error Cases: Non-Struct Input
+// ============================================
+
+#[test]
+fn test_ttl_extendable_rejects_non_struct_inputs() {
+    for (case, input) in filter_item_inputs_excluding_labels(&["struct"]) {
+        assert_panics_contains(case, "failed to parse struct", || {
+            crate::ttl_extendable::generate_ttl_extendable_impl(input.clone());
+        });
+    }
+}

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

@@ -1,7 +1,49 @@
 use proc_macro2::TokenStream;
 use quote::quote;
 
-use crate::tests::test_helpers::{assert_panics_contains, non_struct_item_inputs};
+use crate::tests::test_helpers::{assert_panics_contains, filter_item_inputs_excluding_labels};
+
+static CARGO_PKG_VERSION_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
+/// Small RAII helper for temporarily mutating a single environment variable in tests.
+///
+/// Why this exists:
+/// - `generate_upgradeable_impl` reads `CARGO_PKG_VERSION` at runtime to decide whether to emit
+///   `soroban_sdk::contractmeta!(key = "binver", ...)`.
+/// - Tests need to set/unset that env var deterministically and then restore it to avoid polluting
+///   other tests (especially snapshot tests).
+/// - `Drop` guarantees restoration even if the test panics.
+struct EnvVarGuard {
+    key: &'static str,
+    prev: Option<String>,
+}
+
+impl EnvVarGuard {
+    /// Captures the current value of `key` (if any) so it can be restored on drop.
+    fn new(key: &'static str) -> Self {
+        Self { key, prev: std::env::var(key).ok() }
+    }
+
+    /// Sets the environment variable for the duration of this guard's lifetime.
+    fn set(&self, value: &str) {
+        std::env::set_var(self.key, value);
+    }
+
+    /// Removes the environment variable for the duration of this guard's lifetime.
+    fn remove(&self) {
+        std::env::remove_var(self.key);
+    }
+}
+
+impl Drop for EnvVarGuard {
+    /// Restores the original env var state captured in `new()`.
+    fn drop(&mut self) {
+        match &self.prev {
+            Some(v) => std::env::set_var(self.key, v),
+            None => std::env::remove_var(self.key),
+        }
+    }
+}
 
 // ============================================
 // Snapshot Test: Upgradeable Code Generation
@@ -9,6 +51,7 @@ use crate::tests::test_helpers::{assert_panics_contains, non_struct_item_inputs}
 
 #[test]
 fn snapshot_generated_upgradeable_code() {
+    let _lock = CARGO_PKG_VERSION_LOCK.lock().expect("lock poisoned");
     let input = quote! {
         pub struct MyContract;
     };
@@ -41,13 +84,86 @@ fn snapshot_generated_upgradeable_code() {
 // Error Cases: upgradeable macro non-struct input
 // ============================================
 
+#[test]
+fn test_upgradeable_skips_binver_when_version_is_0_0_0() {
+    let _lock = CARGO_PKG_VERSION_LOCK.lock().expect("lock poisoned");
+    let guard = EnvVarGuard::new("CARGO_PKG_VERSION");
+    guard.set("0.0.0");
+
+    let input = quote! {
+        pub struct MyContract;
+    };
+    let result = crate::upgradeable::generate_upgradeable_impl(TokenStream::new(), input);
+    let result_str = result.to_string();
+
+    assert!(
+        !result_str.contains("contractmeta ! (key = \"binver\""),
+        "should skip binver contractmeta when version is 0.0.0. Got: {}",
+        result_str
+    );
+}
+
+#[test]
+fn test_upgradeable_skips_binver_when_version_is_missing() {
+    let _lock = CARGO_PKG_VERSION_LOCK.lock().expect("lock poisoned");
+    let guard = EnvVarGuard::new("CARGO_PKG_VERSION");
+    guard.remove();
+
+    let input = quote! {
+        pub struct MyContract;
+    };
+    let result = crate::upgradeable::generate_upgradeable_impl(TokenStream::new(), input);
+    let result_str = result.to_string();
+
+    assert!(
+        !result_str.contains("contractmeta ! (key = \"binver\""),
+        "should skip binver contractmeta when version env is missing. Got: {}",
+        result_str
+    );
+}
+
 #[test]
 fn test_upgradeable_rejects_non_struct_inputs() {
     let attr = TokenStream::new();
-    for (case, input) in non_struct_item_inputs() {
+    for (case, input) in filter_item_inputs_excluding_labels(&["struct"]) {
         let attr_clone = attr.clone();
         assert_panics_contains(case, "failed to parse struct", || {
             crate::upgradeable::generate_upgradeable_impl(attr_clone, input.clone());
         });
     }
 }
+
+#[test]
+fn test_upgradeable_emits_binver_when_version_is_set() {
+    let _lock = CARGO_PKG_VERSION_LOCK.lock().expect("lock poisoned");
+    let guard = EnvVarGuard::new("CARGO_PKG_VERSION");
+    guard.set("9.9.9");
+
+    let input = quote! {
+        pub struct MyContract;
+    };
+    let result = crate::upgradeable::generate_upgradeable_impl(TokenStream::new(), input);
+    let result_str = result.to_string();
+
+    assert!(
+        result_str.contains("contractmeta ! (key = \"binver\" , val = \"9.9.9\""),
+        "should emit binver contractmeta when version is set. Got: {}",
+        result_str
+    );
+}
+
+#[test]
+fn test_upgradeable_rejects_invalid_config_table_driven() {
+    let input = quote! { pub struct MyContract; };
+    let cases: Vec<(&str, TokenStream, &str)> = vec![
+        ("unknown option", quote! { not_migration }, "failed to parse upgradeable config"),
+        ("invalid attr syntax", quote! { 123 }, "failed to parse upgradeable config"),
+        ("extra tokens", quote! { no_migration, extra }, "failed to parse upgradeable config"),
+    ];
+
+    for (case, attr, expected) in cases {
+        assert_panics_contains(case, expected, || {
+            crate::upgradeable::generate_upgradeable_impl(attr.clone(), input.clone());
+        });
+    }
+}

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

@@ -8,10 +8,7 @@ use syn::ItemStruct;
 ///
 /// This macro implements `TtlConfigurable` using the trait's default methods (which include auth).
 ///
-/// The contract must also implement `Auth` (typically via `#[ownable]` or `Multisig`).
-///
-/// For manual TTL extension functionality, use the `#[ttl_extendable]` macro which provides
-/// the `extend_instance_ttl` function.
+/// The contract must also implement `Auth` (typically via `#[ownable]` or `#[multisig]`).
 pub fn generate_ttl_configurable_impl(input: TokenStream) -> TokenStream {
     let item_struct: ItemStruct = syn::parse2(input).unwrap_or_else(|e| panic!("failed to parse struct: {}", e));
     let name = &item_struct.ident;