@layerzerolabs/protocol-stellar-v2 0.2.15 → 0.2.18

package/Cargo.lock

@@ -332,14 +332,26 @@ version = "0.0.1"
 dependencies = [
  "assert_unordered",
  "common-macros",
+ "dvn",
+ "dvn-fee-lib",
+ "ed25519-dalek",
  "endpoint-v2",
  "executor",
+ "executor-fee-lib",
+ "executor-helper",
+ "k256",
  "message-lib-common",
  "oapp",
  "oapp-macros",
+ "price-feed",
+ "rand",
+ "sha3",
  "simple-message-lib",
  "soroban-sdk",
+ "treasury",
+ "uln302",
  "utils",
+ "worker",
 ]
 
 [[package]]

package/Cargo.toml

@@ -30,6 +30,9 @@ worker = { path = "contracts/workers/worker" }
 executor = { path = "contracts/workers/executor" }
 executor-helper = { path = "contracts/workers/executor-helper" }
 executor-fee-lib = { path = "contracts/workers/executor-fee-lib" }
+dvn = { path = "contracts/workers/dvn" }
+dvn-fee-lib = { path = "contracts/workers/dvn-fee-lib" }
+price-feed = { path = "contracts/workers/price-feed" }
 oft = { path = "contracts/oapps/oft" }
 stellar-macros = { git = "https://github.com/OpenZeppelin/stellar-contracts.git", tag = "v0.5.1" }
 stellar-tokens = { git = "https://github.com/OpenZeppelin/stellar-contracts.git", tag = "v0.5.1" }

package/contracts/ERROR_SPEC.md

@@ -0,0 +1,44 @@
+# Stellar LayerZero Protocol - Error Code Specification
+
+This document defines the error code allocation strategy for the Stellar LayerZero contracts.
+
+## Purpose
+
+Each library has a unique error code range to:
+
+- **Prevent collisions**: Avoid error code conflicts between different libraries
+- **Enable traceability**: Quickly identify which library an error originated from based on its code
+- **Simplify debugging**: Error codes are globally unique, making it easier to track and diagnose issues
+
+## Allocation Rules
+
+- **Library allocation**: Each library is allocated a 100-unit block (e.g., 1000-1099, 1100-1199). Total errors in one library should not exceed 100.
+- **Sub-range allocation**: Each error type within a library is allocated a 10-unit block. Example from `utils` (1000-1099):
+
+    - BufferReaderError: 1000-1009
+    - BufferWriterError: 1010-1019
+    - TtlConfigurableError: 1020-1029
+    - OwnableError: 1030-1039
+    - BytesExtError: 1040-1049
+    - UpgradeableError: 1050-1059
+    - MultisigError: 1060-1069
+
+    If an error type exceeds 10 errors (e.g., 12 errors), it extends into the next block but the following error type should start at the next 10-unit boundary (e.g., if errors are 1000-1011, next sub-range starts at 1020).
+
+- **Auto-increment**: Within each error enum, values auto-increment from the starting value.
+
+## Error Code Ranges
+
+| Range       | Category        | Library            | Description                                                  |
+| ----------- | --------------- | ------------------ | ------------------------------------------------------------ |
+| 1 - 999     | Contract Errors | -                  | Application-specific contract errors (auto-increment from 1) |
+| 1000 - 1099 | Protocol Lib    | utils              | `utils/src/errors.rs`                                        |
+| 1100 - 1199 | Protocol Lib    | message-lib-common | `message-libs/message-lib-common/src/errors.rs`              |
+| 1200 - 1299 | Protocol Lib    | worker             | `workers/worker/src/errors.rs`                               |
+| 1300 - 1999 | Protocol Lib    | (reserved)         | Future protocol libs                                         |
+| 2000 - 2099 | OApp Lib        | oapp               | `oapps/oapp/src/errors.rs`                                   |
+| 2100 - 2999 | OApp Lib        | (reserved)         | Future OApp libs                                             |
+| 3000 - 3099 | OFT Lib         | oft                | `oapps/oft/src/errors.rs`                                    |
+| 3100 - 3999 | OFT Lib         | (reserved)         | Future OFT libs                                              |
+
+---

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

@@ -0,0 +1,113 @@
+//! 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 both `Auth` and `Ownable` traits for the contract:
+/// - `Auth::authorizer()` returns the stored owner address
+/// - `Ownable` provides ownership management (transfer, 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;
+    let impl_mod = utils::impl_mod_ident(name, "ownable");
+
+    quote! {
+        #item_struct
+
+        use utils::{auth::Auth as _, ownable::{Ownable as _, OwnableInitializer as _}};
+
+        #[doc(hidden)]
+        mod #impl_mod {
+            use super::*;
+            use utils::{
+                auth::Auth,
+                errors::OwnableError,
+                option_ext::OptionExt as _,
+                ownable::{Ownable, OwnableInitializer},
+            };
+
+            impl OwnableInitializer for #name {}
+
+            #[common_macros::contract_impl]
+            impl Auth for #name {
+                fn authorizer(env: &soroban_sdk::Env) -> soroban_sdk::Address {
+                    <Self as Ownable>::owner(env).unwrap_or_panic(env, OwnableError::OwnerNotSet)
+                }
+            }
+
+            #[common_macros::contract_impl(contracttrait)]
+            impl 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;
+    let impl_mod = utils::impl_mod_ident(name, "multisig");
+
+    quote! {
+        #item_struct
+
+        use utils::{auth::Auth as _, multisig::Multisig as _};
+
+        #[doc(hidden)]
+        mod #impl_mod {
+            use super::*;
+            use utils::{auth::Auth, multisig::Multisig};
+
+            #[common_macros::contract_impl]
+            impl Auth for #name {
+                fn authorizer(env: &soroban_sdk::Env) -> soroban_sdk::Address {
+                    env.current_contract_address()
+                }
+            }
+
+            #[common_macros::contract_impl(contracttrait)]
+            impl 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/contracts/common-macros/src/contract_ttl.rs

@@ -0,0 +1,84 @@
+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.
+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 the constructor as TTL config is typically not set during initialization
+        if method.sig.ident == "__constructor" {
+            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
+        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 extends instance TTL if configured.
+fn extend_instance_ttl_stmt(env_param: &utils::EnvParam<'_>) -> syn::Stmt {
+    let env_ref = env_param.as_ref_tokens();
+    let env_ident = env_param.ident;
+    syn::parse_quote! {
+        if let Some(instance_ttl) = utils::ttl_configurable::TtlConfigStorage::instance(#env_ref) {
+            #env_ident.storage().instance().extend_ttl(instance_ttl.threshold, instance_ttl.extend_to);
+        }
+    }
+}

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

@@ -3,26 +3,33 @@
 //! 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;
 
@@ -142,46 +149,74 @@ 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()
 }
 
 // ============================================================================
-// Only Owner Macro
+// Multisig Macro
 // ============================================================================
 
-/// Restricts function access to the contract owner only.
+/// Generates multisig implementation with self-owning access control.
 ///
-/// 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.
+/// 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 Auth Macro
+// ============================================================================
+
+/// Restricts function access to the contract authorizer only.
+///
+/// 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()
 }
 
 // ============================================================================
@@ -191,14 +226,14 @@ pub fn only_owner(_attr: TokenStream, item: TokenStream) -> TokenStream {
 /// Generates TtlConfigurable trait implementation.
 ///
 /// This macro implements the `TtlConfigurable` trait for a contract struct,
-/// providing TTL configuration management with owner-only access control.
+/// providing TTL configuration management with auth-based access control.
 ///
 /// # Requirements
-/// The contract must implement the `Ownable` trait (typically via `#[ownable]`).
+/// The contract must implement the `Auth` trait (typically via `#[ownable]` or `Multisig`).
 ///
 /// # Example
 /// ```ignore
-/// #[ownable]
+/// #[ownable]  // or implement Multisig for self-owning contracts
 /// #[ttl_configurable]
 /// pub struct MyContract;
 ///
@@ -211,15 +246,39 @@ pub fn only_owner(_attr: TokenStream, item: TokenStream) -> TokenStream {
 /// ```
 ///
 /// Generated code includes:
-/// - `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
 #[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
 // ============================================================================
@@ -267,24 +326,77 @@ 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 owner-based access control.
+/// Generates upgradeable implementation with auth-based access control.
 ///
 /// Implements the `Upgradeable` trait for contract upgrade and migration functionality.
 ///
 /// # Requirements
-/// - The contract must have `#[ownable]` applied for owner management
+/// - The contract must implement the `Auth` trait (via `#[ownable]` or `Multisig`)
 /// - The contract must implement `UpgradeableInternal` trait with migration logic
 ///
 /// # Example
 /// ```ignore
-/// #[ownable]
+/// #[ownable]  // or implement Multisig for self-owning contracts
 /// #[upgradeable]
 /// pub struct MyContract;
 ///
@@ -298,10 +410,49 @@ pub fn contract_impl(attr: TokenStream, item: TokenStream) -> TokenStream {
 /// ```
 ///
 /// Generated code includes:
-/// - `upgrade(env, new_wasm_hash)` - Upgrades the contract WASM (owner only)
-/// - `migrate(env, migration_data)` - Runs migration after upgrade (owner only)
+/// - `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()
+}