@layerzerolabs/protocol-stellar-v2 0.2.8

package/Cargo.toml

@@ -0,0 +1,63 @@
+[workspace]
+resolver = "2"
+members = [
+    "contracts/*", 
+    "contracts/message-libs/*", 
+    "contracts/oapps/*", 
+    "contracts/workers/*", 
+    "tools/*",    
+]
+
+[workspace.package]
+edition = "2021"
+license = "MIT"
+version = "0.0.1"
+
+[workspace.dependencies]
+soroban-sdk = {version = "23.3.0", features = ["hazmat-address"]}
+cfg-if = { version = "1.0", default-features = false }
+hex-literal = "1.0.0"
+endpoint-v2 = { path = "contracts/endpoint-v2", default-features = false }
+utils = { path = "contracts/utils" }
+common-macros = { path = "contracts/common-macros" }
+oapp-macros = { path = "contracts/oapp-macros" }
+message-lib-common = { path = "contracts/message-libs/message-lib-common" }
+oapp = { path = "contracts/oapps/oapp" }
+simple-message-lib = { path = "contracts/message-libs/simple-message-lib" }
+treasury = { path = "contracts/message-libs/treasury" }
+worker-common = { path = "contracts/workers/worker-common" }
+executor = { path = "contracts/workers/executor" }
+stellar-access = "0.5.0"
+stellar-macros = "0.5.0"
+stellar-contract-utils = "0.5.0"
+insta = "1.44.3"
+
+# Fast dev builds for testing
+[profile.dev]
+opt-level = 0
+incremental = true
+codegen-units = 256
+
+# Optimize dependencies even in dev (compile once, run many tests)
+[profile.dev.package."*"]
+opt-level = 2
+
+# Test profile optimizations
+[profile.test]
+opt-level = 1
+incremental = true
+
+[profile.release]
+opt-level = "z"
+overflow-checks = true
+debug = 0
+strip = "symbols"
+debug-assertions = false
+panic = "abort"
+codegen-units = 1
+lto = true
+
+# For more information about this profile see https://soroban.stellar.org/docs/basic-tutorials/logging#cargotoml-profile
+[profile.release-with-logs]
+inherits = "release"
+debug-assertions = true

package/clippy.toml

@@ -0,0 +1,7 @@
+# Clippy configuration for Stellar protocol contracts
+
+# Set the too_many_arguments threshold to 11.
+# This aligns with Stellar: contract functions are limited to 10 parameters, plus 1 for 'env'.
+# (Default is 7; raised here to prevent unnecessary clippy warnings on valid contract interfaces.)
+too-many-arguments-threshold = 11
+

package/contracts/common-macros/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "common-macros"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish = false
+
+[lib]
+proc-macro = true
+
+[dependencies]
+proc-macro2 = "1.0"
+quote = "1.0"
+syn = { version = "2.0", features = ["full", "extra-traits"] }
+heck = "0.5"
+itertools = "0.14"
+prettyplease = "0.2.37"
+
+[dev-dependencies]
+insta = { workspace = true }

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

@@ -0,0 +1,53 @@
+use proc_macro::TokenStream;
+use quote::quote;
+use syn::{parse_macro_input, parse_quote, spanned::Spanned, ExprLit, Fields, ItemEnum, Lit, Token};
+
+/// The default starting value for error enum discriminants when no explicit value is provided.
+/// This ensures error codes start from 1 instead of 0.
+const DEFAULT_OFFSET: u32 = 1;
+
+pub fn generate_error(attr: TokenStream, item: TokenStream) -> TokenStream {
+    assert!(attr.is_empty(), "contract_error attribute is not supported");
+
+    let mut data_enum = parse_macro_input!(item as ItemEnum);
+
+    let mut current_value = DEFAULT_OFFSET;
+    for variant in &mut data_enum.variants {
+        assert!(matches!(variant.fields, Fields::Unit), "Error enum variants must be unit variants");
+
+        // Handle variant discriminant assignment
+        if let Some((_, disc)) = &variant.discriminant {
+            // Explicit discriminant - validate it's greater than previous and update counter
+            let val = parse_discriminant_value(disc);
+            assert!(
+                val >= current_value,
+                "Error enum discriminant must be greater than or equal to the previous discriminant"
+            );
+            current_value = val + 1;
+        } else {
+            // No discriminant - assign the next sequential value
+            variant.discriminant = Some((Token![=](variant.span()), parse_quote!(#current_value)));
+            current_value += 1;
+        }
+    }
+
+    quote! {
+        #[soroban_sdk::contracterror]
+        #[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
+        #[repr(u32)]
+        #data_enum
+    }
+    .into()
+}
+
+/// Parses a discriminant value from a variant, returning the u32 value if valid.
+/// Panics if the discriminant is not a valid integer literal.
+fn parse_discriminant_value(disc: &syn::Expr) -> u32 {
+    if let syn::Expr::Lit(ExprLit { lit: Lit::Int(lit_int), .. }) = disc {
+        lit_int.base10_parse().expect("Error enum discriminant must be a valid u32 integer")
+    } else {
+        panic!("Error enum discriminant must be an integer literal")
+    }
+}
+
+// TODO: add test for this

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

@@ -0,0 +1,16 @@
+use proc_macro::TokenStream;
+use quote::quote;
+use syn::{parse_macro_input, DeriveInput};
+
+pub fn generate_event(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(item as DeriveInput);
+    let struct_name = input.ident.to_string();
+
+    let expanded = quote! {
+        #[soroban_sdk::contractevent(topics = [#struct_name])]
+        #[derive(Clone, Debug, Eq, PartialEq)]
+        #input
+    };
+
+    TokenStream::from(expanded)
+}

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

@@ -0,0 +1,255 @@
+//! Common procedural macros for Stellar smart contracts.
+//!
+//! This crate provides foundational macros for Stellar contract development:
+//! - **Storage macros** - Strongly-typed contract storage API generation
+//! - **Event macros** - Contract event generation with proper derives
+//! - **Error macros** - Contract error enum generation
+//! - **Ownable macros** - Owner-based access control implementation
+//!
+//! # Quick Links
+//! - [`storage`] - Storage enum to API macro
+//! - [`event`] - Event struct generation macro
+//! - [`contract_error`] - Error enum generation macro
+//! - [`ownable`] - Ownable trait implementation macro
+//! - [`only_owner`] - Owner-only access control attribute macro
+//!
+//!
+use proc_macro::TokenStream;
+use quote::quote;
+use syn::{parse_macro_input, ItemFn, ItemStruct};
+
+mod error;
+mod event;
+mod ownable;
+mod storage;
+mod ttl_configurable;
+
+#[cfg(test)]
+mod tests;
+
+// ============================================================================
+// Storage Macro
+// ============================================================================
+
+/// Generates strongly-typed storage API from enum variants.
+///
+/// Transforms a storage enum into getter/setter/remove/set_or_remove/has/extend_ttl methods with TTL support.
+///
+/// # Example
+/// ```ignore
+/// #[storage(MyTtlProvider)]
+/// pub enum DataKey {
+///     #[instance(u32)]
+///     Counter,
+///
+///     #[persistent(Address)]
+///     #[default(0)]
+///     Nonce { user: Address },
+///
+///     #[temporary(BytesN<32>)]
+///     #[no_auto_ttl_extension]
+///     TempData,
+/// }
+///
+/// // Generated API:
+/// DataKey::counter(&env)                          // -> Option<u32>
+/// DataKey::set_counter(&env, &value)              // set value
+/// DataKey::has_counter(&env)                      // -> bool
+/// DataKey::remove_counter(&env)                   // remove entry
+/// DataKey::set_or_remove_counter(&env, &opt)      // set if Some, remove if None
+/// DataKey::extend_ttl_counter(&env, threshold, extend_to)  // manual TTL extension
+///
+/// // With fields (keyed storage):
+/// DataKey::nonce(&env, user)                      // -> u64 (has default)
+/// DataKey::set_nonce(&env, user, &value)
+/// DataKey::set_or_remove_nonce(&env, user, &opt)  // conditionally set or remove
+/// ```
+///
+/// # Storage Types (required, exactly one per variant)
+/// - `#[instance(Type)]` - Stored with contract instance
+/// - `#[persistent(Type)]` - Durable ledger entries
+/// - `#[temporary(Type)]` - Short-lived entries
+///
+/// # Variant Attributes (optional)
+/// - `#[default(expr)]` - Default value; changes getter return from `Option<T>` to `T`
+/// - `#[no_auto_ttl_extension]` - Disables automatic TTL extension on access
+/// - `#[name("custom")]` - Override the generated function name base
+#[proc_macro_attribute]
+pub fn storage(attr: TokenStream, item: TokenStream) -> TokenStream {
+    storage::generate_storage(attr.into(), item.into()).into()
+}
+
+// ============================================================================
+// Event Macro
+// ============================================================================
+
+/// Generates a contract event struct with necessary derives.
+///
+/// Combines `#[contractevent]` from soroban-sdk with standard derives
+/// required for events (Clone, Debug, Eq, PartialEq).
+///
+/// Automatically uses the struct name as the topic.
+///
+/// # Example
+/// ```ignore
+/// #[event]
+/// pub struct MyEvent {
+///     pub data: u32,
+/// }
+/// ```
+///
+/// Generated code:
+/// ```ignore
+/// #[contractevent(topics = ["MyEvent"])]
+/// #[derive(Clone, Debug, Eq, PartialEq)]
+/// pub struct MyEvent {
+///     pub data: u32,
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn event(attr: TokenStream, item: TokenStream) -> TokenStream {
+    event::generate_event(attr, item)
+}
+
+// ============================================================================
+// Error Macro
+// ============================================================================
+
+/// Generates a contract error enum with necessary derives.
+///
+/// Combines `#[contracterror]` from soroban-sdk with standard derives
+/// required for errors (Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)
+/// and `#[repr(u32)]`.
+///
+/// # Example
+/// ```ignore
+/// #[contract_error]
+/// pub enum MyError {
+///     MyError1 = 1,
+///     MyError2 = 2,
+/// }
+/// ```
+///
+/// Generated code:
+/// ```ignore
+/// #[contracterror]
+/// #[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
+/// #[repr(u32)]
+/// pub enum MyError {
+///     MyError1 = 1,
+///     MyError2 = 2,
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn contract_error(attr: TokenStream, item: TokenStream) -> TokenStream {
+    error::generate_error(attr, item)
+}
+
+// ============================================================================
+// Ownable Macro
+// ============================================================================
+
+/// Generates ownable implementation with owner-based access control.
+///
+/// Implements the `Ownable` trait and provides owner initialization and
+/// ownership transfer functionality.
+///
+/// # Example
+/// ```ignore
+/// #[ownable]
+/// pub struct MyContract;
+/// ```
+///
+/// Generated code includes:
+/// - `__init_owner(env, owner)` - Internal method to initialize owner
+/// - `owner(env)` - Get current owner
+/// - `transfer_ownership(env, new_owner)` - Transfer ownership
+#[proc_macro_attribute]
+pub fn ownable(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(item as ItemStruct);
+
+    // Generate the ownable implementation
+    let ownable_impl = ownable::generate_ownable_impl(&input.ident);
+
+    TokenStream::from(quote! {
+        #input
+        #ownable_impl
+    })
+}
+
+// ============================================================================
+// Only Owner Macro
+// ============================================================================
+
+/// Restricts function access to the contract owner 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.
+///
+/// # Requirements
+/// - The function must have an `Env` parameter (by value or reference)
+/// - The containing contract must implement the `Ownable` trait (use `#[ownable]`)
+///
+/// # Example
+/// ```ignore
+/// #[ownable]
+/// pub struct MyContract;
+///
+/// #[soroban_sdk::contractimpl]
+/// impl MyContract {
+///     #[only_owner]
+///     pub fn admin_action(env: Env) {
+///         // Only the owner can execute this
+///     }
+/// }
+/// ```
+///
+/// Generated code (conceptual):
+/// ```ignore
+/// pub fn admin_action(env: Env) {
+///     utils::ownable::require_owner_auth::<Self>(&env);
+///     // Original function body
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn only_owner(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    let input_fn = parse_macro_input!(item as ItemFn);
+    ownable::prepend_only_owner_check(input_fn).into()
+}
+
+// ============================================================================
+// TTL Configuration Macro
+// ============================================================================
+
+/// Generates TtlConfigurable trait implementation with ownable support.
+///
+/// This macro automatically applies `#[ownable]` for owner management.:
+/// - `#[ownable]` - Applies the ownable macro for owner management
+/// - TtlConfigurable trait implementation - TTL configuration with freeze support
+///
+/// # Example
+/// ```ignore
+/// #[ttl_configurable]
+/// pub struct MyContract;
+///
+/// #[contractimpl]
+/// impl MyContract {
+///     pub fn __constructor(env: &Env, owner: &Address) {
+///         Self::__init_owner(env, owner);
+///     }
+/// }
+/// ```
+///
+/// Generated code includes:
+/// - `#[ownable]` attribute on the struct (provides owner management)
+/// - `set_ttl_config(env, instance, persistent, temporary)` - Set TTL config (owner only)
+/// - `ttl_config(env)` - Get current TTL configuration (instance, persistent, temporary)
+/// - `freeze_ttl_config(env)` - Permanently freeze TTL config (owner only)
+/// - `is_ttl_config_frozen(env)` - Check if TTL config is frozen
+///
+/// See [`ownable`] for the owner management methods also generated.
+#[proc_macro_attribute]
+pub fn ttl_configurable(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(item as ItemStruct);
+    ttl_configurable::generate_ttl_configurable_impl(&input).into()
+}

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

@@ -0,0 +1,63 @@
+use proc_macro2::{Ident, TokenStream};
+use quote::{quote, ToTokens};
+use syn::{parse_quote, FnArg, ItemFn, Pat, Type, TypePath};
+
+pub fn generate_ownable_impl(name: &Ident) -> TokenStream {
+    quote! {
+        use utils::ownable::Ownable as _;
+
+        impl #name {
+            /// Initialize the contract owner. Should be called during contract initialization.
+            pub(crate) fn __init_owner(env: &soroban_sdk::Env, owner: &soroban_sdk::Address) {
+                utils::ownable::DefaultOwnable::init_owner(env, owner);
+            }
+        }
+
+        /// Implement the Ownable trait for the contract.
+        #[soroban_sdk::contractimpl]
+        impl utils::ownable::Ownable for #name {
+            fn owner(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
+                utils::ownable::DefaultOwnable::owner(env)
+            }
+
+            fn transfer_ownership(env: &soroban_sdk::Env, new_owner: &soroban_sdk::Address) {
+                utils::ownable::DefaultOwnable::transfer_ownership(env, new_owner)
+            }
+
+            fn renounce_ownership(env: &soroban_sdk::Env) {
+                utils::ownable::DefaultOwnable::renounce_ownership(env)
+            }
+        }
+    }
+}
+
+/// Prepends an owner authentication check to a method.
+pub fn prepend_only_owner_check(mut input_fn: ItemFn) -> TokenStream {
+    // Find the Env argument in the function signature
+    let env_ident = input_fn
+        .sig
+        .inputs
+        .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)
+        })
+        .expect("function must have an Env argument");
+
+    // Insert the owner authentication check at the beginning of the function body
+    input_fn.block.stmts.insert(0, parse_quote!(utils::ownable::require_owner_auth::<Self>(#env_ident);));
+    input_fn.into_token_stream()
+}
+
+/// Checks if a type is an `Env` type.
+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,
+    }
+}