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

package/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/src/ttl_configurable.rs

@@ -0,0 +1,24 @@
+//! TtlConfigurable macro for Stellar smart contracts.
+
+use proc_macro2::TokenStream;
+use quote::quote;
+use syn::ItemStruct;
+
+/// Generates the `TtlConfigurable` trait implementation for a contract.
+///
+/// This macro implements `TtlConfigurable` using the trait's default methods (which include auth).
+///
+/// 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;
+
+    quote! {
+        #item_struct
+
+        use utils::ttl_configurable::TtlConfigurable as _;
+
+        #[common_macros::contract_impl(contracttrait)]
+        impl utils::ttl_configurable::TtlConfigurable for #name {}
+    }
+}

package/src/ttl_extendable.rs

@@ -0,0 +1,28 @@
+//! TtlExtendable macro for Stellar smart contracts.
+
+use proc_macro2::TokenStream;
+use quote::quote;
+use syn::ItemStruct;
+
+/// Generates the TtlExtendable trait implementation from the `#[ttl_extendable]` attribute macro.
+///
+/// This macro implements the `TtlExtendable` trait for a contract struct,
+/// providing a public `extend_instance_ttl` function for manual TTL extension.
+///
+/// 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`.
+pub fn generate_ttl_extendable_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;
+
+    quote! {
+        #item_struct
+
+        use utils::ttl_extendable::TtlExtendable as _;
+
+        #[soroban_sdk::contractimpl(contracttrait)]
+        impl utils::ttl_extendable::TtlExtendable for #name {}
+    }
+}

package/src/upgradeable.rs

@@ -0,0 +1,136 @@
+//! Upgradeable macro for Stellar smart contracts.
+
+use proc_macro2::TokenStream;
+use quote::quote;
+use syn::{
+    parse::{Parse, ParseStream},
+    Ident, ItemStruct, Token,
+};
+
+/// Configuration options for the `#[upgradeable]` macro.
+#[derive(Debug, Default)]
+pub struct UpgradeableConfig {
+    /// If true, generates a default no-op `UpgradeableInternal` implementation.
+    /// Use this for initial deployments when no migration logic is needed yet.
+    pub no_migration: bool,
+    /// If true, uses `UpgradeableRbac` (Auth + RoleBased) instead of `Upgradeable` (Auth only).
+    pub rbac: bool,
+}
+
+impl Parse for UpgradeableConfig {
+    fn parse(input: ParseStream) -> syn::Result<Self> {
+        let mut config = Self::default();
+        if input.is_empty() {
+            return Ok(config);
+        }
+
+        while !input.is_empty() {
+            let ident: Ident = input.parse()?;
+            match ident.to_string().as_str() {
+                "no_migration" => config.no_migration = true,
+                "rbac" => config.rbac = true,
+                _ => return Err(syn::Error::new(ident.span(), "expected `no_migration` or `rbac`")),
+            }
+
+            // Consume optional trailing comma
+            if input.peek(Token![,]) {
+                input.parse::<Token![,]>()?;
+            }
+        }
+        Ok(config)
+    }
+}
+
+/// Generates the upgradeable implementation from the `#[upgradeable]` attribute macro.
+///
+/// Generates an impl of `Upgradeable` or `UpgradeableRbac` for a contract type,
+/// enabling upgrades by replacing WASM bytecode with migration support.
+///
+/// # Behavior
+///
+/// - By default implements `Upgradeable` (Auth-based, `#[only_auth]`). With `rbac`,
+///   implements `UpgradeableRbac` (Auth + RoleBased, `UPGRADER_ROLE`).
+/// - Sets the contract crate version as `"binver"` metadata using
+///   `soroban_sdk::contractmeta!`. Uses `CARGO_PKG_VERSION` (from Cargo.toml
+///   `[package]` version). Skips if missing or `"0.0.0"`.
+/// - By default, requires the contract to implement `UpgradeableInternal`.
+/// - With `no_migration`, generates a no-op `UpgradeableInternal` impl.
+/// - With `rbac`, uses `UpgradeableRbac` (requires `RoleBasedAccessControl`, which
+///   extends `Auth`) instead of `Upgradeable` (requires `Auth`).
+///
+/// See the `#[upgradeable]` macro documentation for full examples.
+pub fn generate_upgradeable_impl(attr: TokenStream, input: TokenStream) -> TokenStream {
+    let config: UpgradeableConfig =
+        syn::parse2(attr).unwrap_or_else(|e| panic!("failed to parse upgradeable config: {}", e));
+    let item_struct: ItemStruct = syn::parse2(input).unwrap_or_else(|e| panic!("failed to parse struct: {}", e));
+
+    let name = &item_struct.ident;
+    let binver = set_binver_from_env();
+
+    // Generate default UpgradeableInternal impl only when no_migration is set
+    let default_internal_impl = if config.no_migration {
+        quote! {
+            impl utils::upgradeable::UpgradeableInternal for #name {
+                type MigrationData = ();
+                fn __migrate(_env: &soroban_sdk::Env, _migration_data: &Self::MigrationData) {}
+            }
+        }
+    } else {
+        quote! {}
+    };
+
+    let trait_path = if config.rbac {
+        quote! { utils::upgradeable::UpgradeableRbac }
+    } else {
+        quote! { utils::upgradeable::Upgradeable }
+    };
+
+    quote! {
+        #item_struct
+
+        use #trait_path as _;
+
+        #binver
+
+        #default_internal_impl
+
+        #[common_macros::contract_impl(contracttrait)]
+        impl #trait_path for #name {}
+    }
+}
+
+/// Sets the value of the environment variable `CARGO_PKG_VERSION` as `binver`
+/// in the wasm binary metadata. This env variable corresponds to the attribute
+/// "version" in Cargo.toml. If the attribute is missing or if it is "0.0.0",
+/// the function does nothing.
+fn set_binver_from_env() -> TokenStream {
+    // However when "version" is missing from Cargo.toml,
+    // the following does not return error, but Ok("0.0.0")
+    let version = std::env::var("CARGO_PKG_VERSION");
+
+    match version {
+        Ok(v) if v != "0.0.0" => {
+            quote! { soroban_sdk::contractmeta!(key = "binver", val = #v); }
+        }
+        _ => quote! {},
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::env;
+
+    use super::*;
+
+    #[test]
+    fn test_set_binver_from_env_zero_version() {
+        // Set version to 0.0.0
+        env::set_var("CARGO_PKG_VERSION", "0.0.0");
+
+        let result = set_binver_from_env();
+        let result_str = result.to_string();
+
+        // Should return empty tokens
+        assert_eq!(result_str.trim(), "");
+    }
+}

package/src/utils.rs

@@ -0,0 +1,56 @@
+use proc_macro2::TokenStream;
+use quote::quote;
+use syn::{punctuated::Punctuated, token::Comma, FnArg, Ident, Pat, Type, TypePath};
+
+/// 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(EnvParam { ident: &pat.ident, is_reference: is_reference_type(&pat_type.ty) })
+    })
+}
+
+/// 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.
+pub fn is_env_type(ty: &Type) -> bool {
+    match ty {
+        Type::Path(TypePath { path, .. }) => path.segments.last().is_some_and(|seg| seg.ident == "Env"),
+        Type::Reference(r) => is_env_type(&r.elem),
+        _ => false,
+    }
+}
+
+/// Checks if a type is a reference type.
+fn is_reference_type(ty: &Type) -> bool {
+    matches!(ty, Type::Reference(_))
+}