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

package/Cargo.toml

@@ -0,0 +1,21 @@
+# @layerzerolabs/common-utils-macros-stellar-contracts. Proc-macro crate; self-contained
+# version/edition/deps so it builds as a path dep and vendors cleanly into consumers.
+[package]
+name = "common-macros"
+version = "0.0.1"
+edition = "2021"
+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"
+
+[dev-dependencies]
+insta = "1.44.3"
+prettyplease = "0.2.37"

package/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2026 - LayerZero Labs Ltd.
+
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

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/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@layerzerolabs/common-utils-macros-stellar-contracts",
+  "version": "0.2.122",
+  "private": false,
+  "description": "Stellar common-utils procedural macros",
+  "license": "MIT",
+  "files": [
+    "LICENSE",
+    "src",
+    "Cargo.toml",
+    "rust-toolchain.toml",
+    "rustfmt.toml",
+    "clippy.toml"
+  ],
+  "devDependencies": {
+    "@layerzerolabs/vm-tooling-stellar": "0.2.122"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "externalRepoConfig": {
+    "targets": [
+      "audit-external",
+      "console-pen-test",
+      "monorepo-external",
+      "onesig-client"
+    ]
+  },
+  "scripts": {
+    "build": "pnpm exec lz-tool --script \"cargo build\" stellar",
+    "clean": "rm -rf ./target ./node_modules",
+    "format": "pnpm exec lz-tool --script \"cargo fmt\" stellar",
+    "lint": "pnpm exec lz-tool --script \"cargo clippy -- -D warnings\" stellar",
+    "test": "pnpm exec lz-tool --script \"cargo nextest run\" stellar"
+  }
+}

package/rust-toolchain.toml

@@ -0,0 +1,4 @@
+[toolchain]
+channel = "1.90.0"
+targets = ["wasm32v1-none"]
+components = ["rustfmt", "clippy"]

package/rustfmt.toml

@@ -0,0 +1,15 @@
+format_macro_bodies = true
+max_width = 120
+format_macro_matchers = true
+format_strings = true
+imports_granularity = "Crate"
+match_arm_blocks = false
+reorder_impl_items = true
+group_imports = "StdExternalCrate"
+use_field_init_shorthand = true
+use_small_heuristics = "Max"
+wrap_comments = true
+format_code_in_doc_comments = true
+
+# most of these are unstable, so we enable them
+unstable_features = true

package/src/auth.rs

@@ -0,0 +1,95 @@
+//! Authorization macros for Stellar contracts.
+//!
+//! This module provides macros for implementing authorization patterns:
+//! - `#[ownable]` - Owner-based access control (external owner address)
+//! - `#[multisig]` - MultiSig-based access control (self-owning pattern)
+//! - `#[only_auth]` - Authorization check attribute for functions
+
+use crate::utils;
+use proc_macro2::TokenStream;
+use quote::{quote, ToTokens};
+use syn::{parse_quote, ItemFn, ItemStruct};
+
+// ============================================================================
+// Ownable Macro Implementation
+// ============================================================================
+
+/// Generates the ownable implementation from the `#[ownable]` attribute macro.
+///
+/// This macro implements `OwnableInitializer`, `Auth`, and `Ownable` traits for the contract:
+/// - `OwnableInitializer` provides `init_owner()` for constructor use
+/// - `Auth::authorizer()` returns the stored owner address
+/// - `Ownable` provides ownership management (transfer, accept, renounce)
+pub fn generate_ownable_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::{auth::Auth as _, ownable::{Ownable as _, OwnableInitializer as _}};
+
+        impl utils::ownable::OwnableInitializer for #name {}
+
+        #[common_macros::contract_impl]
+        impl utils::auth::Auth for #name {
+            fn authorizer(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
+                <Self as utils::ownable::Ownable>::owner(env)
+            }
+        }
+
+        #[common_macros::contract_impl(contracttrait)]
+        impl utils::ownable::Ownable for #name {}
+    }
+}
+
+// ============================================================================
+// MultiSig Macro Implementation
+// ============================================================================
+
+/// Generates the multisig implementation from the `#[multisig]` attribute macro.
+///
+/// This macro implements both `Auth` and `MultiSig` traits for the contract:
+/// - `Auth::authorizer()` returns the contract's own address (self-owning pattern)
+/// - `MultiSig` provides signature verification and signer management
+pub fn generate_multisig_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::{auth::Auth as _, multisig::MultiSig as _};
+
+        #[common_macros::contract_impl]
+        impl utils::auth::Auth for #name {
+            fn authorizer(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
+                Some(env.current_contract_address())
+            }
+        }
+
+        #[common_macros::contract_impl(contracttrait)]
+        impl utils::multisig::MultiSig for #name {}
+    }
+}
+
+// ============================================================================
+// Only Auth Macro Implementation
+// ============================================================================
+
+/// Prepends an auth check to a method using the `Auth` trait.
+///
+/// Works with any contract that implements the `Auth` trait, including both
+/// `Ownable` and `MultiSig` contracts.
+pub fn prepend_only_auth_check(input: TokenStream) -> TokenStream {
+    let mut input_fn: ItemFn = syn::parse2(input).unwrap_or_else(|e| panic!("failed to parse function: {}", e));
+
+    let env_param = utils::expect_env_param(&input_fn.sig.inputs);
+
+    // Get a reference to env (handles both `Env` and `&Env` parameter types)
+    let env_ref = env_param.as_ref_tokens();
+
+    // Insert the auth check at the beginning of the function body
+    input_fn.block.stmts.insert(0, parse_quote!(utils::auth::require_auth::<Self>(#env_ref);));
+    input_fn.into_token_stream()
+}

package/src/contract_ttl.rs

@@ -0,0 +1,92 @@
+use crate::utils;
+use proc_macro2::TokenStream;
+use quote::quote;
+use syn::{ImplItem, ItemImpl, ItemTrait, TraitItem, Visibility};
+
+/// Generates a `#[soroban_sdk::contractimpl]` with automatic instance TTL extension.
+///
+/// - For `__constructor` methods: injects `ttl_configurable::init_default_ttl_configs(env)`
+/// - For other methods: injects TTL extension logic to extend instance TTL if configured
+pub fn contractimpl_with_ttl(attr: TokenStream, input: TokenStream) -> TokenStream {
+    let mut impl_block: ItemImpl = syn::parse2(input).unwrap_or_else(|e| panic!("failed to parse impl block: {}", e));
+
+    let is_trait_impl = impl_block.trait_.is_some();
+
+    for item in &mut impl_block.items {
+        let ImplItem::Fn(method) = item else { continue };
+
+        // For trait impls, process all methods; for inherent impls, only public methods
+        if !is_trait_impl && !matches!(method.vis, Visibility::Public(_)) {
+            continue;
+        }
+
+        // Skip methods without Env parameter
+        let Some(env_param) = utils::find_env_param(&method.sig.inputs) else { continue };
+
+        if method.sig.ident == "__constructor" {
+            // Inject default TTL config initialization in constructor
+            method.block.stmts.insert(0, init_default_ttl_configs_stmt(&env_param));
+        } else {
+            // Inject TTL extension at the start of other methods
+            method.block.stmts.insert(0, extend_instance_ttl_stmt(&env_param));
+        }
+    }
+
+    let contract_attr = if attr.is_empty() {
+        quote! { #[soroban_sdk::contractimpl]}
+    } else {
+        quote! { #[soroban_sdk::contractimpl(#attr)] }
+    };
+    quote! {
+        #contract_attr
+        #impl_block
+    }
+}
+
+/// Generates a `#[soroban_sdk::contracttrait]` with automatic instance TTL extension.
+///
+/// This macro processes trait definitions and injects TTL extension logic into
+/// default method implementations that have an `Env` parameter.
+pub fn contracttrait_with_ttl(attr: TokenStream, input: TokenStream) -> TokenStream {
+    let mut trait_def: ItemTrait =
+        syn::parse2(input).unwrap_or_else(|e| panic!("failed to parse trait definition: {}", e));
+
+    for item in &mut trait_def.items {
+        let TraitItem::Fn(method) = item else { continue };
+
+        // Only process methods with default implementations (have a body)
+        let Some(ref mut block) = method.default else { continue };
+
+        // Skip methods without Env parameter
+        let Some(env_param) = utils::find_env_param(&method.sig.inputs) else { continue };
+
+        // Inject TTL extension at the start of the method body
+        block.stmts.insert(0, extend_instance_ttl_stmt(&env_param));
+    }
+
+    let trait_attr = if attr.is_empty() {
+        quote! { #[soroban_sdk::contracttrait]}
+    } else {
+        quote! { #[soroban_sdk::contracttrait(#attr)] }
+    };
+    quote! {
+        #trait_attr
+        #trait_def
+    }
+}
+
+/// Generates a statement that initializes default TTL configs in the constructor.
+fn init_default_ttl_configs_stmt(env_param: &utils::EnvParam<'_>) -> syn::Stmt {
+    let env_ref = env_param.as_ref_tokens();
+    syn::parse_quote! {
+        utils::ttl_configurable::init_default_ttl_configs(#env_ref);
+    }
+}
+
+/// Generates a statement that extends instance TTL if configured.
+fn extend_instance_ttl_stmt(env_param: &utils::EnvParam<'_>) -> syn::Stmt {
+    let env_ref = env_param.as_ref_tokens();
+    syn::parse_quote! {
+        utils::ttl_configurable::extend_instance_ttl(#env_ref);
+    }
+}

package/src/error.rs

@@ -0,0 +1,43 @@
+use proc_macro2::TokenStream;
+use quote::quote;
+use syn::{parse_quote, spanned::Spanned, ExprLit, Fields, ItemEnum, Lit, Token};
+
+pub fn generate_error(item: TokenStream) -> TokenStream {
+    let mut data_enum: ItemEnum = syn::parse2(item).unwrap_or_else(|e| panic!("failed to parse enum: {}", e));
+
+    // For variants without an explicit discriminant, assign sequential error codes starting at 1
+    // (by initializing the counter to 0 and incrementing before assignment).
+    let mut current_value = 0;
+    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 the previous discriminant");
+            current_value = val;
+        } else {
+            // No discriminant - assign the next sequential value
+            current_value += 1;
+            variant.discriminant = Some((Token![=](variant.span()), parse_quote!(#current_value)));
+        }
+    }
+
+    quote! {
+        #[soroban_sdk::contracterror]
+        #[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
+        #[repr(u32)]
+        #data_enum
+    }
+}
+
+/// 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")
+    }
+}