@layerzerolabs/protocol-stellar-v2 0.2.13 → 0.2.18

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

@@ -3,24 +3,34 @@
 //! This crate provides foundational macros for Stellar contract development:
 //! - **Storage macros** - Strongly-typed contract storage API generation
 //! - **Error macros** - Contract error enum generation
-//! - **Ownable macros** - Owner-based access control implementation
+//! - **Auth macros** - Authorization-based access control (ownable, multisig, only_auth)
 //! - **TTL macros** - Time-to-live configuration and automatic extension
+//! - **Wrapper macros** - Convenient macro combinations for common patterns
 //!
 //! # Quick Links
 //! - [`storage`] - Storage enum to API macro
 //! - [`contract_error`] - Error enum generation macro
 //! - [`ownable`] - Ownable trait implementation macro
-//! - [`only_owner`] - Owner-only access control attribute macro
+//! - [`multisig`] - Multisig trait implementation macro
+//! - [`only_auth`] - Auth-based access control attribute macro
 //! - [`ttl_configurable`] - TTL configuration with freeze support
+//! - [`ttl_extendable`] - Manual instance TTL extension
 //! - [`contract_impl`] - Contract impl with automatic instance TTL extension
+//! - [`contract_trait`] - Contract trait with automatic instance TTL extension
+//! - [`upgradeable`] - Upgradeable trait implementation macro
+//! - [`lz_contract`] - Wrapper macro combining common LayerZero contract attributes
 //!
+
 use proc_macro::TokenStream;
 
-mod contract_impl;
+mod auth;
+mod contract_ttl;
 mod error;
-mod ownable;
+mod lz_contract;
 mod storage;
 mod ttl_configurable;
+mod ttl_extendable;
+mod upgradeable;
 mod utils;
 
 #[cfg(test)]
@@ -139,60 +149,91 @@ pub fn contract_error(attr: TokenStream, item: TokenStream) -> TokenStream {
 /// - `Ownable` trait impl - `owner(env)`, `transfer_ownership(env, new_owner)`, `renounce_ownership(env)`
 #[proc_macro_attribute]
 pub fn ownable(_attr: TokenStream, item: TokenStream) -> TokenStream {
-    ownable::generate_ownable_impl(item.into()).into()
+    auth::generate_ownable_impl(item.into()).into()
+}
+
+// ============================================================================
+// Multisig Macro
+// ============================================================================
+
+/// Generates multisig implementation with self-owning access control.
+///
+/// Implements the `Multisig` trait and the `Auth` trait with self-owning pattern,
+/// where the contract's own address is the authorizer. This allows multisig
+/// quorum approval to serve as the authorizer for owner-protected operations
+/// like TTL configuration and upgrades.
+///
+/// # Example
+/// ```ignore
+/// #[multisig]
+/// pub struct MyContract;
+/// ```
+///
+/// Generated code includes:
+/// - `Auth` trait impl - `authorizer(env)` returns `env.current_contract_address()`
+/// - `Multisig` trait impl - `set_signer(...)`, `set_threshold(...)`, `verify_signatures(...)`
+#[proc_macro_attribute]
+pub fn multisig(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    auth::generate_multisig_impl(item.into()).into()
 }
 
 // ============================================================================
-// Only Owner Macro
+// Only Auth Macro
 // ============================================================================
 
-/// Restricts function access to the contract owner only.
+/// Restricts function access to the contract authorizer only.
 ///
-/// This attribute macro injects an owner authentication check at the beginning
-/// of the function. The function will panic if called by a non-owner address.
+/// This attribute macro injects an auth check at the beginning of the function
+/// using the `Auth` trait. The function will panic if called without authorization.
+///
+/// Works with any contract that implements `Auth`, including both `Ownable` and
+/// `Multisig` contracts.
 ///
 /// # Requirements
 /// - The function must have an `Env` parameter (by value or reference)
-/// - The containing contract must implement the `Ownable` trait (use `#[ownable]`)
+/// - The containing contract must implement the `Auth` trait
 ///
 /// # Example
 /// ```ignore
-/// #[ownable]
+/// #[ownable]  // or implement Multisig
 /// pub struct MyContract;
 ///
 /// #[soroban_sdk::contractimpl]
 /// impl MyContract {
-///     #[only_owner]
-///     pub fn admin_action(env: Env) {
-///         // Only the owner can execute this
+///     #[only_auth]
+///     pub fn protected_action(env: Env) {
+///         // Only the authorizer can execute this
 ///     }
 /// }
 /// ```
 ///
 /// Generated code (conceptual):
 /// ```ignore
-/// pub fn admin_action(env: Env) {
-///     utils::ownable::require_owner_auth::<Self>(&env);
+/// pub fn protected_action(env: Env) {
+///     utils::auth::require_auth::<Self>(&env);
 ///     // Original function body
 /// }
 /// ```
 #[proc_macro_attribute]
-pub fn only_owner(_attr: TokenStream, item: TokenStream) -> TokenStream {
-    ownable::prepend_only_owner_check(item.into()).into()
+pub fn only_auth(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    auth::prepend_only_auth_check(item.into()).into()
 }
 
 // ============================================================================
 // TTL Configuration Macro
 // ============================================================================
 
-/// Generates TtlConfigurable trait implementation with ownable support.
+/// Generates TtlConfigurable trait implementation.
 ///
-/// This macro automatically applies `#[ownable]` for owner management.:
-/// - `#[ownable]` - Applies the ownable macro for owner management
-/// - TtlConfigurable trait implementation - TTL configuration with freeze support
+/// This macro implements the `TtlConfigurable` trait for a contract struct,
+/// providing TTL configuration management with auth-based access control.
+///
+/// # Requirements
+/// The contract must implement the `Auth` trait (typically via `#[ownable]` or `Multisig`).
 ///
 /// # Example
 /// ```ignore
+/// #[ownable]  // or implement Multisig for self-owning contracts
 /// #[ttl_configurable]
 /// pub struct MyContract;
 ///
@@ -205,18 +246,39 @@ pub fn only_owner(_attr: TokenStream, item: TokenStream) -> TokenStream {
 /// ```
 ///
 /// Generated code includes:
-/// - `#[ownable]` attribute on the struct (provides owner management)
-/// - `set_ttl_configs(env, instance, persistent)` - Set TTL configs (owner only)
+/// - `set_ttl_configs(env, instance, persistent)` - Set TTL configs (auth required)
 /// - `ttl_configs(env)` - Get current TTL configs (instance, persistent)
-/// - `freeze_ttl_configs(env)` - Permanently freeze TTL configs (owner only)
+/// - `freeze_ttl_configs(env)` - Permanently freeze TTL configs (auth required)
 /// - `is_ttl_configs_frozen(env)` - Check if TTL configs are frozen
-///
-/// See [`ownable`] for the owner management methods also generated.
 #[proc_macro_attribute]
 pub fn ttl_configurable(_attr: TokenStream, item: TokenStream) -> TokenStream {
     ttl_configurable::generate_ttl_configurable_impl(item.into()).into()
 }
 
+// ============================================================================
+// TTL Extendable Macro
+// ============================================================================
+
+/// Generates TtlExtendable trait implementation for manual instance TTL extension.
+///
+/// This macro implements the `TtlExtendable` trait, providing a public
+/// `extend_instance_ttl` function that allows external callers to extend
+/// the contract's instance storage TTL.
+///
+/// # Example
+/// ```ignore
+/// #[contract]
+/// #[ttl_extendable]
+/// pub struct MyContract;
+/// ```
+///
+/// Generated code includes:
+/// - `extend_instance_ttl(env, threshold, extend_to)` - Extends instance TTL
+#[proc_macro_attribute]
+pub fn ttl_extendable(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    ttl_extendable::generate_ttl_extendable_impl(item.into()).into()
+}
+
 // ============================================================================
 // Contract Impl Macro
 // ============================================================================
@@ -255,7 +317,7 @@ pub fn ttl_configurable(_attr: TokenStream, item: TokenStream) -> TokenStream {
 /// #[soroban_sdk::contractimpl]
 /// impl MyContract {
 ///     pub fn my_method(env: &Env) {
-///         if let Some(ttl) = <Self as ::utils::ttl::TtlConfigurable>::ttl_config(env).0 {
+///         if let Some(ttl) = <Self as ::utils::ttl_configurable::TtlConfigurable>::ttl_config(env).0 {
 ///             env.storage().instance().extend_ttl(ttl.threshold, ttl.extend_to);
 ///         }
 ///         // ... your code
@@ -264,5 +326,133 @@ pub fn ttl_configurable(_attr: TokenStream, item: TokenStream) -> TokenStream {
 /// ```
 #[proc_macro_attribute]
 pub fn contract_impl(attr: TokenStream, item: TokenStream) -> TokenStream {
-    contract_impl::contract_impl(attr.into(), item.into()).into()
+    contract_ttl::contractimpl_with_ttl(attr.into(), item.into()).into()
+}
+
+// ============================================================================
+// Contract Trait Macro
+// ============================================================================
+
+/// Wraps `#[soroban_sdk::contracttrait]` with automatic instance TTL extension.
+///
+/// This macro applies `#[soroban_sdk::contracttrait]` and injects TTL extension logic
+/// at the beginning of each default trait method to keep the contract instance alive.
+///
+/// # Requirements
+/// - The implementing contract must have `#[ttl_configurable]` applied
+/// - Methods must have an `Env` parameter to receive TTL extension
+/// - Only methods with default implementations are processed
+///
+/// # Behavior
+/// - All default methods with an `Env` parameter receive TTL extension
+/// - Methods without a body (abstract methods) are not modified
+/// - Methods without an `Env` parameter are skipped
+///
+/// # Example
+/// ```ignore
+/// #[contract_trait]
+/// pub trait MyTrait {
+///     /// This method will have TTL extension injected
+///     fn my_method(env: &Env) {
+///         // TTL extension is automatically injected here
+///         // ... your code
+///     }
+///
+///     /// Abstract methods are not modified
+///     fn abstract_method(env: &Env) -> u32;
+/// }
+/// ```
+///
+/// Generated code (conceptual):
+/// ```ignore
+/// #[soroban_sdk::contracttrait]
+/// pub trait MyTrait {
+///     fn my_method(env: &Env) {
+///         if let Some(ttl) = utils::ttl_configurable::TtlConfigStorage::instance(env) {
+///             env.storage().instance().extend_ttl(ttl.threshold, ttl.extend_to);
+///         }
+///         // ... your code
+///     }
+///
+///     fn abstract_method(env: &Env) -> u32;
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn contract_trait(attr: TokenStream, item: TokenStream) -> TokenStream {
+    contract_ttl::contracttrait_with_ttl(attr.into(), item.into()).into()
+}
+
+// ============================================================================
+// Upgradeable Macro
+// ============================================================================
+
+/// Generates upgradeable implementation with auth-based access control.
+///
+/// Implements the `Upgradeable` trait for contract upgrade and migration functionality.
+///
+/// # Requirements
+/// - The contract must implement the `Auth` trait (via `#[ownable]` or `Multisig`)
+/// - The contract must implement `UpgradeableInternal` trait with migration logic
+///
+/// # Example
+/// ```ignore
+/// #[ownable]  // or implement Multisig for self-owning contracts
+/// #[upgradeable]
+/// pub struct MyContract;
+///
+/// impl utils::upgradeable::UpgradeableInternal for MyContract {
+///     type MigrationData = ();
+///
+///     fn _migrate(env: &Env, migration_data: &Self::MigrationData) {
+///         // Migration logic here
+///     }
+/// }
+/// ```
+///
+/// Generated code includes:
+/// - `upgrade(env, new_wasm_hash)` - Upgrades the contract WASM (auth required)
+/// - `migrate(env, migration_data)` - Runs migration after upgrade (auth required)
+/// - `contractmeta!` with `binver` set to the Cargo package version (if not 0.0.0)
+#[proc_macro_attribute]
+pub fn upgradeable(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    upgradeable::generate_upgradeable_impl(item.into()).into()
+}
+
+// ============================================================================
+// LZ Contract Wrapper Macro
+// ============================================================================
+
+/// Wrapper macro that combines common LayerZero contract attributes.
+///
+/// This macro simplifies contract declarations by combining multiple commonly
+/// used macros into a single attribute.
+///
+/// # Default (no options)
+/// `#[lz_contract]` generates:
+/// - `#[contract]` - Soroban contract
+/// - `#[ttl_configurable]` - TTL configuration with auth
+/// - `#[ttl_extendable]` - Manual TTL extension
+/// - `#[ownable]` - Single-owner access control
+///
+/// # Options
+/// - `upgradeable` - Adds `#[upgradeable]` for contract upgrade support
+/// - `multisig` - Uses `#[multisig]` instead of `#[ownable]`
+///
+/// # Examples
+/// ```ignore
+/// // Basic contract with ownable auth
+/// #[lz_contract]
+/// pub struct EndpointV2;
+///
+/// // Contract with upgrade support
+/// #[lz_contract(upgradeable)]
+/// pub struct DVNFeeLib;
+///
+/// // Contract with multisig auth and upgrade support
+/// #[lz_contract(multisig, upgradeable)]
+/// pub struct DVN;
+/// ```
+#[proc_macro_attribute]
+pub fn lz_contract(attr: TokenStream, item: TokenStream) -> TokenStream {
+    lz_contract::generate_lz_contract(attr.into(), item.into()).into()
 }

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

@@ -0,0 +1,83 @@
+//! LzContract wrapper macro for Stellar smart contracts.
+//!
+//! This module provides the `#[lz_contract]` macro which combines commonly used
+//! LayerZero contract attributes into a single macro invocation.
+
+use proc_macro2::TokenStream;
+use quote::quote;
+use syn::{
+    parse::{Parse, ParseStream},
+    punctuated::Punctuated,
+    Error, Ident, ItemStruct, Token,
+};
+
+/// Configuration options for the `#[lz_contract]` macro.
+#[derive(Debug, Default)]
+pub struct LzContractConfig {
+    /// If true, adds `#[upgradeable]` for contract upgrade support.
+    pub upgradeable: bool,
+    /// If true, uses `#[multisig]` instead of `#[ownable]` for auth.
+    pub multisig: bool,
+}
+
+impl Parse for LzContractConfig {
+    fn parse(input: ParseStream) -> syn::Result<Self> {
+        if input.is_empty() {
+            return Ok(Self::default());
+        }
+
+        let idents = Punctuated::<Ident, Token![,]>::parse_terminated(input)?;
+        let mut config = Self::default();
+
+        for ident in idents {
+            match ident.to_string().as_str() {
+                "upgradeable" => config.upgradeable = true,
+                "multisig" => config.multisig = true,
+                _ => {
+                    return Err(Error::new(ident.span(), "expected one of `upgradeable`, `multisig`"));
+                }
+            }
+        }
+
+        Ok(config)
+    }
+}
+
+/// Generates a complete LayerZero contract with common macro attributes.
+///
+/// # Default (no options)
+/// Generates:
+/// - `#[soroban_sdk::contract]` - Soroban contract
+/// - `#[common_macros::ttl_configurable]` - TTL configuration with auth
+/// - `#[common_macros::ttl_extendable]` - Manual TTL extension
+/// - `#[common_macros::ownable]` - Single-owner access control
+///
+/// # Options
+/// - `upgradeable` - Adds `#[common_macros::upgradeable]` for contract upgrade support
+/// - `multisig` - Uses `#[common_macros::multisig]` instead of `#[common_macros::ownable]`
+pub fn generate_lz_contract(attr: TokenStream, input: TokenStream) -> TokenStream {
+    let config: LzContractConfig =
+        syn::parse2(attr).unwrap_or_else(|e| panic!("failed to parse lz_contract config: {}", e));
+    let item: ItemStruct = syn::parse2(input).unwrap_or_else(|e| panic!("failed to parse struct: {}", e));
+
+    let auth = if config.multisig {
+        quote! { #[common_macros::multisig] }
+    } else {
+        quote! { #[common_macros::ownable] }
+    };
+
+    let upgrade = if config.upgradeable {
+        quote! { #[common_macros::upgradeable] }
+    } else {
+        quote! {}
+    };
+
+    quote! {
+        #[soroban_sdk::contract]
+        #[common_macros::ttl_configurable]
+        #[common_macros::ttl_extendable]
+        #auth
+        #upgrade
+        #item
+    }
+}

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

@@ -306,7 +306,7 @@ fn gen_ttl_extension(storage_type: &StorageType, use_stored_config: bool) -> Tok
     if use_stored_config {
         let method = format_ident!("{}", storage_type.accessor_name());
         quote! {
-            if let Some(utils::ttl::TtlConfig { threshold, extend_to }) = utils::ttl::TtlConfigStorage::#method(env) {
+            if let Some(utils::ttl_configurable::TtlConfig { threshold, extend_to }) = utils::ttl_configurable::TtlConfigStorage::#method(env) {
                 #extend_call
             }
         }

package/contracts/common-macros/src/tests/{ownable.rs → auth.rs}

@@ -2,6 +2,7 @@ use proc_macro2::TokenStream;
 use quote::quote;
 
 use crate::tests::test_helpers::{assert_panics_contains, non_struct_item_inputs};
+
 // ============================================
 // Snapshot Test: Ownable Code Generation
 // ============================================
@@ -11,21 +12,40 @@ fn snapshot_generated_ownable_code() {
     let input = quote! {
         pub struct MyContract;
     };
-    let result = crate::ownable::generate_ownable_impl(input);
+    let result = crate::auth::generate_ownable_impl(input);
+    let formatted = prettyplease::unparse(&syn::parse2::<syn::File>(result).expect("failed to parse generated code"));
+
+    insta::assert_snapshot!(formatted);
+}
+
+// ============================================
+// Snapshot Test: Multisig Code Generation
+// ============================================
+
+#[test]
+fn snapshot_generated_multisig_code() {
+    let input = quote! {
+        pub struct MyContract;
+    };
+    let result = crate::auth::generate_multisig_impl(input);
     let formatted = prettyplease::unparse(&syn::parse2::<syn::File>(result).expect("failed to parse generated code"));
 
     insta::assert_snapshot!(formatted);
 }
 
+// ============================================
+// Snapshot Test: Only Auth Macro
+// ============================================
+
 #[test]
-fn snapshot_only_owner_preserves_function_signature() {
+fn snapshot_only_auth_preserves_function_signature() {
     // 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_borrowed = crate::ownable::prepend_only_owner_check(input_borrowed);
+    let result_borrowed = crate::auth::prepend_only_auth_check(input_borrowed);
     let formatted_borrowed =
         prettyplease::unparse(&syn::parse2::<syn::File>(result_borrowed).expect("failed to parse generated code"));
 
@@ -35,7 +55,7 @@ fn snapshot_only_owner_preserves_function_signature() {
             Ok(value.clone())
         }
     };
-    let result_owned = crate::ownable::prepend_only_owner_check(input_owned);
+    let result_owned = crate::auth::prepend_only_auth_check(input_owned);
     let formatted_owned =
         prettyplease::unparse(&syn::parse2::<syn::File>(result_owned).expect("failed to parse generated code"));
 
@@ -49,30 +69,30 @@ fn snapshot_only_owner_preserves_function_signature() {
 }
 
 // ============================================
-// prepend_only_owner_check Tests
+// prepend_only_auth_check Tests
 // ============================================
 
-/// Helper function to verify that the owner check is correctly inserted at the beginning of a function.
-fn assert_owner_check_inserted(input: TokenStream, expected_env_ref: &str, test_name: &str) {
-    let result_tokens = crate::ownable::prepend_only_owner_check(input);
+/// Helper function to verify that the auth check is correctly inserted at the beginning of a function.
+fn assert_auth_check_inserted(input: TokenStream, expected_env_ref: &str, test_name: &str) {
+    let result_tokens = crate::auth::prepend_only_auth_check(input);
     let output_fn: syn::ItemFn =
         syn::parse2(result_tokens).unwrap_or_else(|e| panic!("{}: failed to parse output function: {}", test_name, e));
 
     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 = format!("utils::ownable::require_owner_auth::<Self>({});", expected_env_ref);
+    let expected_stmt = format!("utils::auth::require_auth::<Self>({});", expected_env_ref);
     let actual_stmt = quote::quote!(#first_stmt).to_string().replace(" ", "");
 
     assert_eq!(
         actual_stmt, expected_stmt,
-        "{}: expected owner check statement '{}', but got '{}'",
+        "{}: expected auth check statement '{}', but got '{}'",
         test_name, expected_stmt, actual_stmt
     );
 }
 
 #[test]
-fn test_only_owner_inserts_correct_code_at_the_beginning() {
+fn test_only_auth_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![
@@ -88,12 +108,12 @@ fn test_only_owner_inserts_correct_code_at_the_beginning() {
     ];
 
     for (description, input, expected_env_ref) in test_cases {
-        assert_owner_check_inserted(input, expected_env_ref, description);
+        assert_auth_check_inserted(input, expected_env_ref, description);
     }
 }
 
 #[test]
-fn test_only_owner_requires_env_param() {
+fn test_only_auth_requires_env_param() {
     // ============================================
     // Error Cases: Missing/Invalid Env Argument Patterns
     // ============================================
@@ -109,7 +129,7 @@ fn test_only_owner_requires_env_param() {
 
     for (case, input) in cases {
         assert_panics_contains(case, "function must have an Env argument", || {
-            crate::ownable::prepend_only_owner_check(input.clone());
+            crate::auth::prepend_only_auth_check(input.clone());
         });
     }
 }
@@ -122,7 +142,20 @@ fn test_only_owner_requires_env_param() {
 fn test_ownable_rejects_non_struct_inputs() {
     for (case, input) in non_struct_item_inputs() {
         assert_panics_contains(case, "failed to parse struct", || {
-            crate::ownable::generate_ownable_impl(input.clone());
+            crate::auth::generate_ownable_impl(input.clone());
+        });
+    }
+}
+
+// ============================================
+// Error Cases: multisig macro non-struct input
+// ============================================
+
+#[test]
+fn test_multisig_rejects_non_struct_inputs() {
+    for (case, input) in non_struct_item_inputs() {
+        assert_panics_contains(case, "failed to parse struct", || {
+            crate::auth::generate_multisig_impl(input.clone());
         });
     }
 }