@layerzerolabs/common-utils-macros-stellar-contracts 0.2.122

package/src/tests/snapshots/common_macros__tests__contract_ttl__snapshot_generated_contracttrait_code.snap

@@ -0,0 +1,46 @@
+---
+source: contracts/common-macros/src/tests/contract_ttl.rs
+expression: combined
+---
+// === Trait (no attr) ===
+
+#[soroban_sdk::contracttrait]
+pub trait MyTrait: Sized {
+    const A_CONST: u32;
+    type Alias;
+    /// Default method with Env - should have TTL extension
+    fn default_with_env(env: Env, value: u32) -> u32 {
+        utils::ttl_configurable::extend_instance_ttl(&env);
+        value * 2
+    }
+    /// Default method with qualified Env path - should have TTL extension
+    fn with_qualified_env(env: soroban_sdk::Env) -> u32 {
+        utils::ttl_configurable::extend_instance_ttl(&env);
+        42
+    }
+    /// Default method with Env not as first parameter - should have TTL extension
+    fn env_second(value: u32, env: &Env) -> u32 {
+        utils::ttl_configurable::extend_instance_ttl(env);
+        value * 2
+    }
+    /// Default method without Env - should NOT have TTL extension
+    fn default_without_env(value: u32) -> u32 {
+        value * 4
+    }
+    /// Abstract method with Env - should NOT have TTL extension (no body)
+    fn abstract_with_env(env: Env, value: u32) -> u32;
+    /// Abstract method without Env - should NOT have TTL extension (no body)
+    fn abstract_without_env(value: u32) -> u32;
+}
+
+
+// === Trait (crate attr) ===
+
+#[soroban_sdk::contracttrait(crate = "other_sdk")]
+pub trait AnotherTrait {
+    /// Default method with Env - should have TTL extension
+    fn method_with_env(env: &Env, value: u32) -> u32 {
+        utils::ttl_configurable::extend_instance_ttl(env);
+        value * 3
+    }
+}

package/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/src/tests/snapshots/common_macros__tests__lz_contract__snapshot_generated_lz_contract_code.snap

@@ -0,0 +1,51 @@
+---
+source: contracts/common-macros/src/tests/lz_contract.rs
+expression: combined
+---
+// === Default (ownable) ===
+
+#[soroban_sdk::contract]
+#[common_macros::ttl_configurable]
+#[common_macros::ttl_extendable]
+#[common_macros::ownable]
+pub struct MyContract;
+
+
+// === MultiSig + Upgradeable ===
+
+#[soroban_sdk::contract]
+#[common_macros::ttl_configurable]
+#[common_macros::ttl_extendable]
+#[common_macros::multisig]
+#[common_macros::upgradeable]
+pub struct MyContract;
+
+
+// === Upgradeable (no_migration) ===
+
+#[soroban_sdk::contract]
+#[common_macros::ttl_configurable]
+#[common_macros::ttl_extendable]
+#[common_macros::ownable]
+#[common_macros::upgradeable(no_migration)]
+pub struct MyContract;
+
+
+// === Upgradeable (rbac) ===
+
+#[soroban_sdk::contract]
+#[common_macros::ttl_configurable]
+#[common_macros::ttl_extendable]
+#[common_macros::ownable]
+#[common_macros::upgradeable(rbac)]
+pub struct MyContract;
+
+
+// === Upgradeable (rbac, no_migration) pass-through ===
+
+#[soroban_sdk::contract]
+#[common_macros::ttl_configurable]
+#[common_macros::ttl_extendable]
+#[common_macros::ownable]
+#[common_macros::upgradeable(rbac, no_migration)]
+pub struct MyContract;

package/src/tests/snapshots/common_macros__tests__rbac__snapshot_authorizer_role.snap

@@ -0,0 +1,21 @@
+---
+source: contracts/common-macros/src/tests/rbac.rs
+expression: combined
+---
+// === has_role(operator, AUTHORIZER) ===
+
+pub fn admin_action(env: Env, operator: Address) {
+    utils::rbac::ensure_role::<
+        Self,
+    >(&env, &soroban_sdk::Symbol::new(&env, AUTHORIZER), &operator);
+}
+
+
+// === only_role(operator, AUTHORIZER) ===
+
+pub fn admin_action(env: Env, operator: Address) {
+    utils::rbac::ensure_role::<
+        Self,
+    >(&env, &soroban_sdk::Symbol::new(&env, AUTHORIZER), &operator);
+    operator.require_auth();
+}

package/src/tests/snapshots/common_macros__tests__rbac__snapshot_preserve_function_signature.snap

@@ -0,0 +1,21 @@
+---
+source: contracts/common-macros/src/tests/rbac.rs
+expression: combined
+---
+// === has_role ===
+
+pub fn mint(env: Env, caller: Address, amount: i128) {
+    utils::rbac::ensure_role::<
+        Self,
+    >(&env, &soroban_sdk::Symbol::new(&env, "minter"), &caller);
+}
+
+
+// === only_role ===
+
+pub fn mint(env: Env, caller: Address, amount: i128) {
+    utils::rbac::ensure_role::<
+        Self,
+    >(&env, &soroban_sdk::Symbol::new(&env, "minter"), &caller);
+    caller.require_auth();
+}

package/src/tests/snapshots/common_macros__tests__ttl_configurable__snapshot_generated_ttl_configurable_code.snap

@@ -0,0 +1,10 @@
+---
+source: contracts/common-macros/src/tests/ttl_configurable.rs
+expression: formatted
+---
+pub struct MyContract {
+    some_field: u32,
+}
+use utils::ttl_configurable::TtlConfigurable as _;
+#[common_macros::contract_impl(contracttrait)]
+impl utils::ttl_configurable::TtlConfigurable for MyContract {}

package/src/tests/snapshots/common_macros__tests__ttl_extendable__snapshot_generated_ttl_extendable_code.snap

@@ -0,0 +1,8 @@
+---
+source: contracts/common-macros/src/tests/ttl_extendable.rs
+expression: formatted
+---
+pub struct MyContract;
+use utils::ttl_extendable::TtlExtendable as _;
+#[soroban_sdk::contractimpl(contracttrait)]
+impl utils::ttl_extendable::TtlExtendable for MyContract {}

package/src/tests/snapshots/common_macros__tests__upgradeable__snapshot_generated_upgradeable_code.snap

@@ -0,0 +1,28 @@
+---
+source: contracts/common-macros/src/tests/upgradeable.rs
+assertion_line: 80
+expression: combined
+---
+// ============================================
+// Default: requires manual UpgradeableInternal
+// ============================================
+
+pub struct MyContract;
+use utils::upgradeable::Upgradeable as _;
+soroban_sdk::contractmeta!(key = "binver", val = "0.0.1");
+#[common_macros::contract_impl(contracttrait)]
+impl utils::upgradeable::Upgradeable for MyContract {}
+
+// ============================================
+// With no_migration: auto-generates impl
+// ============================================
+
+pub struct MyContract;
+use utils::upgradeable::Upgradeable as _;
+soroban_sdk::contractmeta!(key = "binver", val = "0.0.1");
+impl utils::upgradeable::UpgradeableInternal for MyContract {
+    type MigrationData = ();
+    fn __migrate(_env: &soroban_sdk::Env, _migration_data: &Self::MigrationData) {}
+}
+#[common_macros::contract_impl(contracttrait)]
+impl utils::upgradeable::Upgradeable for MyContract {}

package/src/tests/storage/extract_fields.rs

@@ -0,0 +1,87 @@
+//! Unit tests for the `extract_fields` function.
+
+use crate::storage::test::extract_fields_for_test;
+use crate::tests::test_helpers::assert_panics_contains;
+use quote::{quote, ToTokens};
+
+use super::test_setup::parse_variant;
+
+#[test]
+fn test_unit_variant_returns_empty() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[persistent(u32)]
+            UnitVariant,
+        }
+    });
+
+    let fields = extract_fields_for_test(&variant);
+    assert!(fields.is_empty(), "unit variant should have no fields");
+}
+
+#[test]
+fn test_named_variant_single_field() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[persistent(u32)]
+            NamedVariant { key: Address },
+        }
+    });
+
+    let fields = extract_fields_for_test(&variant);
+    assert_eq!(fields.len(), 1, "should have exactly one field");
+    assert_eq!(fields[0].0.to_string(), "key");
+    assert_eq!(fields[0].1.to_token_stream().to_string(), "Address");
+}
+
+#[test]
+fn test_named_variant_multiple_fields() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[persistent(u32)]
+            NamedVariant { first: u32, second: String, third: Address },
+        }
+    });
+
+    let fields = extract_fields_for_test(&variant);
+    assert_eq!(fields.len(), 3, "should have exactly three fields");
+    assert_eq!(fields[0].0.to_string(), "first");
+    assert_eq!(fields[1].0.to_string(), "second");
+    assert_eq!(fields[2].0.to_string(), "third");
+
+    assert_eq!(fields[0].1.to_token_stream().to_string(), "u32");
+    assert_eq!(fields[1].1.to_token_stream().to_string(), "String");
+    assert_eq!(fields[2].1.to_token_stream().to_string(), "Address");
+}
+
+#[test]
+fn test_tuple_variant_panics() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            TupleVariant(u32, String),
+        }
+    });
+
+    assert_panics_contains("tuple variant", "only unit variants or named fields are supported", || {
+        extract_fields_for_test(&variant);
+    });
+}
+
+#[test]
+fn test_preserves_field_order() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[persistent(u32)]
+            OrderedVariant { alpha: u32, beta: String, gamma: Address, delta: bool },
+        }
+    });
+
+    let fields = extract_fields_for_test(&variant);
+    let names: Vec<_> = fields.iter().map(|(name, _)| name.to_string()).collect();
+    assert_eq!(names, vec!["alpha", "beta", "gamma", "delta"]);
+
+    assert_eq!(fields[0].1.to_token_stream().to_string(), "u32");
+    assert_eq!(fields[1].1.to_token_stream().to_string(), "String");
+    assert_eq!(fields[2].1.to_token_stream().to_string(), "Address");
+    assert_eq!(fields[3].1.to_token_stream().to_string(), "bool");
+}

package/src/tests/storage/gen_accessor_methods.rs

@@ -0,0 +1,223 @@
+//! Unit tests for the `gen_accessor_methods` function.
+
+use crate::storage::test::gen_accessor_methods_for_test;
+use proc_macro2::Ident;
+use quote::{format_ident, quote, ToTokens};
+use syn::{ImplItem, ImplItemFn, ItemImpl, ReturnType, Type, Variant};
+
+use super::test_setup::{normalize, parse_variant};
+
+fn gen_impl(enum_name: &Ident, variant: &Variant) -> ItemImpl {
+    let methods = gen_accessor_methods_for_test(enum_name, variant);
+    syn::parse2::<ItemImpl>(quote! { impl #enum_name { #methods } }).expect("failed to parse generated methods")
+}
+
+fn impl_fn_names(item_impl: &ItemImpl) -> Vec<String> {
+    item_impl
+        .items
+        .iter()
+        .filter_map(|it| match it {
+            ImplItem::Fn(f) => Some(f.sig.ident.to_string()),
+            _ => None,
+        })
+        .collect()
+}
+
+fn find_fn<'a>(item_impl: &'a ItemImpl, name: &str) -> &'a ImplItemFn {
+    item_impl
+        .items
+        .iter()
+        .find_map(|it| match it {
+            ImplItem::Fn(f) if f.sig.ident == name => Some(f),
+            _ => None,
+        })
+        .unwrap_or_else(|| panic!("expected to find function '{name}' in generated impl"))
+}
+
+fn output_type(sig: &syn::Signature) -> Option<&Type> {
+    match &sig.output {
+        ReturnType::Default => None,
+        ReturnType::Type(_, ty) => Some(ty.as_ref()),
+    }
+}
+
+#[test]
+fn generates_all_expected_methods_for_unit_variant() {
+    let variant = parse_variant(quote! {
+        enum TestEnum {
+            #[persistent(u32)]
+            Counter,
+        }
+    });
+    let enum_name = format_ident!("TestEnum");
+
+    let item_impl = gen_impl(&enum_name, &variant);
+    let mut names = impl_fn_names(&item_impl);
+    names.sort();
+
+    // Getter + CRUD-ish methods + TTL extender are always generated.
+    assert_eq!(
+        names,
+        vec!["counter", "extend_counter_ttl", "has_counter", "remove_counter", "set_counter", "set_or_remove_counter",]
+    );
+}
+
+#[test]
+fn uses_correct_storage_accessor_for_each_kind() {
+    let enum_name = format_ident!("TestEnum");
+
+    let variant = parse_variant(quote! {
+        enum TestEnum {
+            #[instance(u32)]
+            Counter,
+        }
+    });
+    let instance = gen_accessor_methods_for_test(&enum_name, &variant);
+    let instance_norm = normalize(instance);
+    let expected_instance = normalize(quote!(env.storage().instance()));
+    assert!(instance_norm.contains(&expected_instance));
+
+    let variant = parse_variant(quote! {
+        enum TestEnum {
+            #[persistent(u32)]
+            Counter,
+        }
+    });
+    let persistent = gen_accessor_methods_for_test(&enum_name, &variant);
+    let persistent_norm = normalize(persistent);
+    let expected_persistent = normalize(quote!(env.storage().persistent()));
+    assert!(persistent_norm.contains(&expected_persistent));
+
+    let variant = parse_variant(quote! {
+        enum TestEnum {
+            #[temporary(u32)]
+            Counter,
+        }
+    });
+    let temporary = gen_accessor_methods_for_test(&enum_name, &variant);
+    let temporary_norm = normalize(temporary);
+    let expected_temporary = normalize(quote!(env.storage().temporary()));
+    assert!(temporary_norm.contains(&expected_temporary));
+}
+
+#[test]
+fn persistent_includes_auto_ttl_and_can_be_disabled() {
+    let variant = parse_variant(quote! {
+        enum TestEnum {
+            #[persistent(u32)]
+            Counter,
+        }
+    });
+    let enum_name = format_ident!("TestEnum");
+
+    let methods = gen_accessor_methods_for_test(&enum_name, &variant);
+    let methods_str = normalize(methods);
+
+    assert!(
+        methods_str.contains("utils :: ttl_configurable :: extend_persistent_ttl"),
+        "persistent storage should include auto TTL extension"
+    );
+
+    let variant = parse_variant(quote! {
+        enum TestEnum {
+            #[persistent(u32)]
+            #[no_ttl_extension]
+            Counter,
+        }
+    });
+    let methods = gen_accessor_methods_for_test(&enum_name, &variant);
+    let methods_str = normalize(methods);
+
+    assert!(
+        !methods_str.contains("utils :: ttl_configurable :: extend_persistent_ttl"),
+        "no_ttl_extension should disable auto TTL extension"
+    );
+}
+
+#[test]
+fn default_value_changes_getter_return_type_and_body() {
+    let variant = parse_variant(quote! {
+        enum TestEnum {
+            #[instance(u32)]
+            #[default(0)]
+            Counter,
+        }
+    });
+    let enum_name = format_ident!("TestEnum");
+
+    let item_impl = gen_impl(&enum_name, &variant);
+    let getter = find_fn(&item_impl, "counter");
+
+    // With default, return type should be the value type directly, not Option<...>
+    let out = output_type(&getter.sig).expect("getter should have an explicit return type");
+    assert_eq!(normalize(out.to_token_stream()), normalize(quote!(u32)));
+
+    let body = normalize(getter.block.to_token_stream());
+    assert!(body.contains("unwrap_or"), "getter should apply default via unwrap_or(...)");
+}
+
+#[test]
+fn no_default_getter_returns_option() {
+    let variant = parse_variant(quote! {
+        enum TestEnum {
+            #[instance(u32)]
+            Counter,
+        }
+    });
+    let enum_name = format_ident!("TestEnum");
+
+    let item_impl = gen_impl(&enum_name, &variant);
+    let getter = find_fn(&item_impl, "counter");
+
+    let out = output_type(&getter.sig).expect("getter should have an explicit return type");
+    assert_eq!(normalize(out.to_token_stream()), normalize(quote!(Option<u32>)));
+}
+
+#[test]
+fn snake_case_and_custom_name_attribute_are_applied() {
+    let variant = parse_variant(quote! {
+        enum TestEnum {
+            #[instance(u32)]
+            MyLongVariantName,
+        }
+    });
+    let enum_name = format_ident!("TestEnum");
+
+    let item_impl = gen_impl(&enum_name, &variant);
+    let names = impl_fn_names(&item_impl);
+
+    assert!(names.iter().any(|n| n == "my_long_variant_name"), "should convert to snake_case");
+    assert!(names.iter().any(|n| n == "set_my_long_variant_name"), "setter should use snake_case");
+
+    let variant = parse_variant(quote! {
+        enum TestEnum {
+            #[instance(u32)]
+            #[name("custom_name")]
+            Counter,
+        }
+    });
+    let item_impl = gen_impl(&enum_name, &variant);
+    let names = impl_fn_names(&item_impl);
+
+    assert!(names.iter().any(|n| n == "custom_name"), "should use custom name for getter");
+    assert!(names.iter().any(|n| n == "set_custom_name"), "should use custom name for setter");
+}
+
+#[test]
+fn named_variant_generates_expected_param_passing_rules() {
+    let variant = parse_variant(quote! {
+        enum TestEnum {
+            #[instance(u32)]
+            Nonce { nonce: u32, user: Address },
+        }
+    });
+    let enum_name = format_ident!("TestEnum");
+
+    let item_impl = gen_impl(&enum_name, &variant);
+    let getter = find_fn(&item_impl, "nonce");
+    let sig_norm = normalize(getter.sig.to_token_stream());
+
+    // Non-primitive types are passed by reference, primitives by value.
+    assert!(sig_norm.contains("nonce : u32"), "primitive field should be passed by value");
+    assert!(sig_norm.contains("user : & Address"), "non-primitive field should be passed by reference");
+}

package/src/tests/storage/gen_args.rs

@@ -0,0 +1,65 @@
+//! Unit tests for the `gen_args` function.
+
+use crate::storage::test::gen_args_for_test;
+use quote::quote;
+
+use super::test_setup::{normalize, parse_variant};
+
+#[test]
+fn test_unit_variant_only_env_arg() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[persistent(u32)]
+            UnitVariant,
+        }
+    });
+
+    let args = gen_args_for_test(&variant);
+    let expected = quote! { env };
+    assert_eq!(normalize(args), normalize(expected));
+}
+
+#[test]
+fn test_named_variant_single_field() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[persistent(u32)]
+            NamedVariant { key: Address },
+        }
+    });
+
+    let args = gen_args_for_test(&variant);
+    let expected = quote! { env, key };
+    assert_eq!(normalize(args), normalize(expected));
+}
+
+#[test]
+fn test_named_variant_multiple_fields() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[persistent(u32)]
+            NamedVariant { first: u32, second: String, third: Address },
+        }
+    });
+
+    let args = gen_args_for_test(&variant);
+    let expected = quote! { env, first, second, third };
+    assert_eq!(normalize(args), normalize(expected));
+}
+
+#[test]
+fn test_args_do_not_include_types() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[persistent(u32)]
+            NamedVariant { key: SomeComplexType },
+        }
+    });
+
+    let args = gen_args_for_test(&variant);
+    let args_str = args.to_string();
+
+    // Args should only contain identifiers, not types
+    assert!(!args_str.contains("SomeComplexType"), "args should not include types");
+    assert!(args_str.contains("key"), "args should include field name");
+}

package/src/tests/storage/gen_enum_variant.rs

@@ -0,0 +1,78 @@
+//! Unit tests for the `gen_enum_variant` function.
+
+use crate::storage::test::gen_enum_variant_for_test;
+use crate::tests::test_helpers::assert_panics_contains;
+use quote::quote;
+
+use super::test_setup::{normalize, parse_variant};
+
+#[test]
+fn test_unit_variant() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[persistent(u32)]
+            UnitVariant,
+        }
+    });
+
+    let generated = gen_enum_variant_for_test(&variant);
+    let expected = quote! { UnitVariant };
+    assert_eq!(normalize(generated), normalize(expected));
+}
+
+#[test]
+fn test_named_variant_single_field() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[persistent(u32)]
+            NamedVariant { key: Address },
+        }
+    });
+
+    let generated = gen_enum_variant_for_test(&variant);
+    // Named fields become tuple variant with types only
+    let expected = quote! { NamedVariant(Address) };
+    assert_eq!(normalize(generated), normalize(expected));
+}
+
+#[test]
+fn test_named_variant_multiple_fields() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[persistent(u32)]
+            NamedVariant { first: u32, second: String, third: Address },
+        }
+    });
+
+    let generated = gen_enum_variant_for_test(&variant);
+    // Multiple fields become tuple variant with all types
+    let expected = quote! { NamedVariant(u32, String, Address) };
+    assert_eq!(normalize(generated), normalize(expected));
+}
+
+#[test]
+fn test_tuple_variant_panics() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            TupleVariant(u32, String),
+        }
+    });
+
+    assert_panics_contains("tuple variant", "only unit variants or named fields are supported", || {
+        gen_enum_variant_for_test(&variant);
+    });
+}
+
+#[test]
+fn test_complex_generic_types() {
+    let variant = parse_variant(quote! {
+        enum Test {
+            #[persistent(u32)]
+            GenericVariant { key: BytesN<32>, value: Vec<u8> },
+        }
+    });
+
+    let generated = gen_enum_variant_for_test(&variant);
+    let expected = quote! { GenericVariant(BytesN<32>, Vec<u8>) };
+    assert_eq!(normalize(generated), normalize(expected));
+}