@layerzerolabs/protocol-stellar-v2 0.2.8 → 0.2.9

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

@@ -1,14 +1,13 @@
 //! # OApp Procedural Macros
 //!
-//! This crate provides procedural macros for implementing LayerZero OApp (Omnichain Application)
-//! functionality on Soroban smart contracts. These macros simplify the process of creating
-//! cross-chain applications by automatically generating the necessary trait implementations.
+//! This crate provides the `#[oapp]` procedural macro for implementing LayerZero OApp
+//! (Omnichain Application) functionality on Soroban smart contracts.
 //!
 //! ## Overview
 //!
-//! The OApp framework consists of several core components:
+//! The OApp framework provides full bidirectional cross-chain communication:
 //!
-//! - **OAppCore**: Foundation for all OApp functionality, providing peer management and endpoint access
+//! - **OAppCore**: Foundation for all OApp functionality (peer management, endpoint access)
 //! - **OAppSender**: Enables sending cross-chain messages through LayerZero
 //! - **OAppReceiver**: Handles incoming cross-chain messages
 //! - **OAppOptionsType3**: Manages enforced options for message execution parameters
@@ -16,21 +15,8 @@
 //! ## Available Macros
 //!
 //! ### `#[oapp]`
-//! A convenience macro that combines Core + Sender + Receiver functionality. This is the most
-//! common choice for  cross-chain communication.
-//!
-//! ### `#[oapp_core]`
-//! Derives only the core OApp functionality (peer management, endpoint access).
-//!
-//! ### `#[oapp_sender]`
-//! Derives Core + Sender functionality for applications that only need to send messages.
-//!
-//! ### `#[oapp_receiver]`
-//! Derives Core + Receiver functionality for applications that only need to receive messages.
-//!
-//! ### `#[oapp_options_type3]`
-//! Derives the Options Type 3 functionality for managing enforced message options.
-//! Can be combined with other macros.
+//! The main macro that provides Core + Sender + Receiver + OptionsType3 functionality.
+//! This is the only macro you need for cross-chain communication.
 //!
 //! ### `#[oapp_manual_impl(...)]`
 //! A marker attribute to indicate which trait implementations should be manually provided
@@ -38,28 +24,14 @@
 //!
 //! ## Manual Implementation Control
 //!
-//! By default, macros generate default trait implementations. Use `#[oapp_manual_impl(...)]`
+//! By default, `#[oapp]` generates default trait implementations. Use `#[oapp_manual_impl(...)]`
 //! to customize specific behaviors:
 //!
-//! ```ignore
-//! #[oapp_core]
-//! #[oapp_manual_impl(core)]
-//! struct MyOApp;
-//!
-//! impl OAppCoreOverrides for MyOApp {
-//!     fn __oapp_version(_env: &Env) -> (u64, u64) {
-//!         (1, 1) // Custom version
-//!     }
-//! }
-//! ```
-//!
 //! Supported options:
-//! - `core` - Manually implement `OAppCoreOverrides`
-//! - `sender` - Manually implement `OAppSenderOverrides`
-//! - `options_type3` - Manually implement `OAppOptionsType3Overrides`
-//!
-//! **Note**: There is no `receiver` option because `OAppReceiverOverrides::__lz_receive`
-//! **must always** be manually implemented by the user to define custom message handling logic.
+//! - `core` - Manually implement `OAppCore`
+//! - `sender` - Manually implement `OAppSender`
+//! - `receiver` - Manually implement `OAppReceiver` (useful for custom `next_nonce`, etc.)
+//! - `options_type3` - Manually implement `OAppOptionsType3`
 //!
 //! ## Examples
 //!
@@ -67,13 +39,12 @@
 //!
 //! ```ignore
 //! use oapp_macros::oapp;
-//! use oapp::oapp_receiver::OAppReceiverOverrides;
 //!
 //! #[oapp]
 //! struct MyOApp;
 //!
-//! // Only __lz_receive must be implemented
-//! impl OAppReceiverOverrides for MyOApp {
+//! // Only __lz_receive must be implemented as an inherent method
+//! impl MyOApp {
 //!     fn __lz_receive(
 //!         env: &Env,
 //!         executor: &Address,
@@ -83,49 +54,70 @@
 //!         extra_data: &Bytes,
 //!         value: i128,
 //!     ) {
-//!         // Your custom message handling logic
+//!         // Your message handling logic (verify_and_clear_payload already called)
 //!     }
 //! }
 //! ```
 //!
-//! ### Full OApp with Custom Core Implementation
+//! ### OApp with Custom Core Version
 //!
 //! ```ignore
 //! #[oapp]
 //! #[oapp_manual_impl(core)]
-//! struct MyCustomOApp;
+//! struct MyOApp;
 //!
-//! impl OAppCoreOverrides for MyCustomOApp {
-//!     fn __oapp_version(_env: &Env) -> (u64, u64) {
-//!         (2, 1) // Custom version
+//! #[contractimpl(contracttrait)]
+//! #[common_macros::ownable]
+//! impl OAppCore for MyOApp {
+//!     fn oapp_version(_env: &Env) -> (u64, u64) {
+//!         (1, 1) // Custom version
 //!     }
-//!     // Other methods use defaults
 //! }
 //!
-//! impl OAppReceiverOverrides for MyCustomOApp {
+//! impl MyOApp {
 //!     fn __lz_receive(...) { /* ... */ }
 //! }
 //! ```
 //!
-//! ### Sender-Only OApp
+//! ### OApp with Custom Receiver (e.g., ordered delivery)
 //!
 //! ```ignore
-//! #[oapp_sender]
-//! struct MySenderOApp;
-//! // Uses all defaults, no manual implementation needed
+//! use oapp::oapp_receiver::{OAppReceiver, verify_and_clear_payload};
+//!
+//! #[oapp]
+//! #[oapp_manual_impl(receiver)]
+//! struct MyOrderedOApp;
+//!
+//! #[contractimpl(contracttrait)]
+//! impl OAppReceiver for MyOrderedOApp {
+//!     fn next_nonce(env: &Env, src_eid: u32, sender: &BytesN<32>) -> u64 {
+//!         // Custom nonce logic for ordered delivery
+//!         Storage::max_received_nonce(env, src_eid, sender) + 1
+//!     }
+//!     fn lz_receive(env: &Env, executor: &Address, origin: &Origin, ...) {
+//!         verify_and_clear_payload::<Self>(env, executor, origin, guid, message, value);
+//!         // Your message handling logic
+//!     }
+//! }
 //! ```
 //!
-//! ### OApp with Options Type 3
+//! ### OApp with Multiple Manual Implementations
 //!
 //! ```ignore
 //! #[oapp]
-//! #[oapp_options_type3]
-//! struct MyOAppWithOptions;
+//! #[oapp_manual_impl(core, sender, options_type3)]
+//! struct MyCustomOApp;
+//!
+//! #[contractimpl(contracttrait)]
+//! #[common_macros::ownable]
+//! impl OAppCore for MyCustomOApp { /* ... */ }
+//! impl OAppSender for MyCustomOApp { /* ... */ }
+//! #[contractimpl(contracttrait)]
+//! impl OAppOptionsType3 for MyCustomOApp { /* ... */ }
 //!
-//! impl OAppReceiverOverrides for MyOAppWithOptions {
+//! impl MyCustomOApp {
 //!     fn __lz_receive(...) { /* ... */ }
 //! }
-//! // OAppOptionsType3Overrides uses defaults
 //! ```
 
 use crate::util::parse_struct;
@@ -138,162 +130,9 @@ mod oapp_receiver;
 mod oapp_sender;
 mod util;
 
-/// Derives OAppCore implementation, providing the foundation for OApp functionality.
+/// Derives a complete OApp: `#[contract]` + `#[ownable]` + Core + Sender + Receiver + OptionsType3.
 ///
-/// This macro generates:
-/// - `#[soroban_sdk::contract]` attribute
-/// - `#[common_macros::ownable]` attribute for ownership management
-/// - Implementation of `OAppCore` trait with methods delegating to `OAppCoreOverrides`
-///
-/// By default, an empty `OAppCoreOverrides` implementation is generated. Use
-/// `#[oapp_manual_impl(core)]` to provide custom implementations.
-///
-/// # Example
-///
-/// ```ignore
-/// #[oapp_core]
-/// struct MyOApp;
-/// // Uses default OAppCore implementation
-/// ```
-///
-/// # Example with Manual Implementation
-///
-/// ```ignore
-/// #[oapp_core]
-/// #[oapp_manual_impl(core)]
-/// struct MyCustomOApp;
-///
-/// impl OAppCoreOverrides for MyCustomOApp {
-///     fn __oapp_version(_env: &Env) -> (u64, u64) {
-///         (1, 2)
-///     }
-/// }
-/// ```
-#[proc_macro_attribute]
-pub fn oapp_core(_attr: TokenStream, item: TokenStream) -> TokenStream {
-    let (name, item, disable_config) = match parse_struct(item) {
-        Ok(result) => result,
-        Err(e) => return e,
-    };
-    oapp_core::generate_impl(&name, item, disable_config.core).into()
-}
-
-/// Derives OAppSender implementation, providing cross-chain message sending capabilities.
-///
-/// This macro automatically includes `#[oapp_core]` functionality, generating both
-/// Core and Sender implementations. By default, an empty `OAppSenderOverrides`
-/// implementation is generated. Use `#[oapp_manual_impl(sender)]` or
-/// `#[oapp_manual_impl(core, sender)]` for custom implementations.
-///
-/// # Example
-///
-/// ```ignore
-/// #[oapp_sender]
-/// struct MySender;
-/// // Can now send cross-chain messages using default implementations
-/// ```
-///
-/// # Example with Manual Sender Implementation
-///
-/// ```ignore
-/// #[oapp_sender]
-/// #[oapp_manual_impl(sender)]
-/// struct MyCustomSender;
-///
-/// impl OAppSenderOverrides for MyCustomSender {
-///     // Custom sender logic
-/// }
-/// ```
-#[proc_macro_attribute]
-pub fn oapp_sender(_attr: TokenStream, item: TokenStream) -> TokenStream {
-    let (name, item, disable_config) = match parse_struct(item) {
-        Ok(result) => result,
-        Err(e) => return e,
-    };
-    oapp_sender::generate_impl_with_core(&name, item, disable_config).into()
-}
-
-/// Derives OAppReceiver implementation, providing receive capabilities
-///
-/// **Important**: Unlike other OApp macros, this macro does NOT support `manual_impl`
-/// configuration because the `__lz_receive` method in `OAppReceiverOverrides` trait
-/// has no default implementation. Users **MUST** always manually implement
-/// `OAppReceiverOverrides::__lz_receive` to define their custom message handling logic.
-///
-/// # Example
-/// ```ignore
-/// #[oapp_receiver]
-/// struct MyReceiver;
-///
-/// impl OAppReceiverOverrides for MyReceiver {
-///     fn __lz_receive(
-///         env: &Env,
-///         executor: &Address,
-///         origin: &Origin,
-///         guid: &BytesN<32>,
-///         message: &Bytes,
-///         extra_data: &Bytes,
-///         value: i128,
-///     ) {
-///         // Your custom message handling logic here
-///     }
-/// }
-/// ```
-#[proc_macro_attribute]
-pub fn oapp_receiver(_attr: TokenStream, item: TokenStream) -> TokenStream {
-    let (name, item, disable_config) = match parse_struct(item) {
-        Ok(result) => result,
-        Err(e) => return e,
-    };
-    oapp_receiver::generate_impl_with_core(&name, item, disable_config).into()
-}
-
-/// Derives a complete OApp implementation with Core + Sender + Receiver functionality.
-///
-/// This is a convenience macro that combines all three core OApp components. It's the
-/// most common choice for applications that need full bidirectional cross-chain communication.
-///
-/// **Important**: You **must** always implement `OAppReceiverOverrides::__lz_receive` to
-/// define your custom message handling logic, as it has no default implementation.
-///
-/// # Example
-///
-/// ```ignore
-/// #[oapp]
-/// struct MyFullOApp;
-///
-/// impl OAppReceiverOverrides for MyFullOApp {
-///     fn __lz_receive(
-///         env: &Env,
-///         executor: &Address,
-///         origin: &Origin,
-///         guid: &BytesN<32>,
-///         message: &Bytes,
-///         extra_data: &Bytes,
-///         value: i128,
-///     ) {
-///         // Your message handling logic here
-///     }
-/// }
-/// ```
-///
-/// # Example with Manual Core Implementation
-///
-/// ```ignore
-/// #[oapp]
-/// #[oapp_manual_impl(core)]
-/// struct MyCustomFullOApp;
-///
-/// impl OAppCoreOverrides for MyCustomFullOApp {
-///     fn __oapp_version(_env: &Env) -> (u64, u64) {
-///         (2, 0)
-///     }
-/// }
-///
-/// impl OAppReceiverOverrides for MyCustomFullOApp {
-///     fn __lz_receive(...) { /* ... */ }
-/// }
-/// ```
+/// You must implement `__lz_receive` as an inherent method. See module docs for examples.
 #[proc_macro_attribute]
 pub fn oapp(_attr: TokenStream, item: TokenStream) -> TokenStream {
     let (name, item, disable_config) = match parse_struct(item) {
@@ -303,105 +142,12 @@ pub fn oapp(_attr: TokenStream, item: TokenStream) -> TokenStream {
     oapp_full::generate_impl(&name, item, disable_config).into()
 }
 
-/// Derives OAppOptionsType3 implementation for managing enforced message options.
-///
-/// This macro provides fine-grained control over message execution parameters per endpoint
-/// and message type. Unlike other OApp macros, this does **not** automatically add the
-/// `#[soroban_sdk::contract]` attribute, so it can be used standalone or combined with
-/// other OApp macros.
-///
-/// By default, an empty `OAppOptionsType3Overrides` implementation is generated. Use
-/// `#[oapp_manual_impl(options_type3)]` for custom implementations.
-///
-/// # Example - Standalone
-///
-/// ```ignore
-/// #[contract]
-/// #[ownable]
-/// #[oapp_options_type3]
-/// struct MyOptions;
-/// // Uses default options implementation
-/// ```
-///
-/// # Example - Combined with Full OApp
-///
-/// ```ignore
-/// #[oapp]
-/// #[oapp_options_type3]
-/// struct MyOAppWithOptions;
-///
-/// impl OAppReceiverOverrides for MyOAppWithOptions {
-///     fn __lz_receive(...) { /* ... */ }
-/// }
-/// ```
-///
-/// # Example with Manual Implementation
-///
-/// ```ignore
-/// #[contract]
-/// #[ownable]
-/// #[oapp_options_type3]
-/// #[oapp_manual_impl(options_type3)]
-/// struct MyCustomOptions;
-///
-/// impl OAppOptionsType3Overrides for MyCustomOptions {
-///     fn __enforced_options(env: &Env, eid: u32, msg_type: u32) -> Bytes {
-///         // Custom enforced options logic
-///     }
-/// }
-/// ```
-#[proc_macro_attribute]
-pub fn oapp_options_type3(_attr: TokenStream, item: TokenStream) -> TokenStream {
-    let (name, item, disable_config) = match parse_struct(item) {
-        Ok(result) => result,
-        Err(e) => return e,
-    };
-    oapp_options_type3::generate_impl(&name, item, disable_config.options_type3).into()
-}
-
-/// Marker attribute to specify which trait implementations should be manually provided.
-///
-/// Use this attribute together with OApp macros to indicate that you will provide
-/// custom implementations instead of using the default ones.
-///
-/// # Supported Options
-///
-/// - `core` - Manually implement `OAppCoreOverrides`
-/// - `sender` - Manually implement `OAppSenderOverrides`
-/// - `options_type3` - Manually implement `OAppOptionsType3Overrides`
-///
-/// **Note**: There is no `receiver` option because `OAppReceiverOverrides::__lz_receive`
-/// must **always** be manually implemented (it has no default implementation).
-///
-/// # Examples
-///
-/// ```ignore
-/// // Manual core implementation
-/// #[oapp_core]
-/// #[oapp_manual_impl(core)]
-/// struct MyOApp;
-///
-/// impl OAppCoreOverrides for MyOApp {
-///     fn __oapp_version(_env: &Env) -> (u64, u64) {
-///         (1, 1)
-///     }
-/// }
-/// ```
+/// Marker attribute to skip generating specific trait implementations.
 ///
-/// ```ignore
-/// // Multiple manual implementations
-/// #[oapp]
-/// #[oapp_options_type3]
-/// #[oapp_manual_impl(core, sender, options_type3)]
-/// struct MyFullCustomOApp;
+/// Supported options: `core`, `sender`, `receiver`, `options_type3`
 ///
-/// impl OAppCoreOverrides for MyFullCustomOApp { /* ... */ }
-/// impl OAppSenderOverrides for MyFullCustomOApp { /* ... */ }
-/// impl OAppReceiverOverrides for MyFullCustomOApp {
-///     fn __lz_receive(...) { /* required */ }
-/// }
-/// impl OAppOptionsType3Overrides for MyFullCustomOApp { /* ... */ }
-/// ```
+/// Example: `#[oapp_manual_impl(core, receiver)]` skips generating
+/// `OAppCore` and `OAppReceiver` implementations.
 #[proc_macro_attribute]
 pub fn oapp_manual_impl(_attr: TokenStream, item: TokenStream) -> TokenStream {
     item

package/contracts/oapp-macros/src/oapp_core.rs

@@ -1,49 +1,40 @@
+use heck::ToSnakeCase;
 use proc_macro2::TokenStream;
 use quote::quote;
 use syn::{Ident, ItemStruct};
 
+/// Generates the `OAppCore` trait implementation and adds `#[contract]` + `#[ownable]` to the struct.
+///
+/// When `manual_impl_core` is false, generates an empty `impl OAppCore`
+/// that uses the trait's default implementations for peer management and endpoint access.
 pub fn generate_impl(name: &Ident, item_struct: ItemStruct, manual_impl_core: bool) -> TokenStream {
+    // Create a unique module name to avoid import conflicts when multiple structs
+    // use oapp macros in the same module. The import must be `OAppCore`
+    // (not an alias) because Soroban SDK's #[contractimpl(contracttrait)] generates
+    // a macro call `OAppCore!(...)` that needs to resolve to the macro
+    // exported by #[contracttrait].
+    let impl_mod = syn::Ident::new(&format!("__oapp_impl_{}", name.to_string().to_snake_case()), name.span());
+
     let manual_impl = (!manual_impl_core).then(|| {
         quote! {
-            use oapp::oapp_core::OAppCoreOverrides as _;
-
-            impl oapp::oapp_core::OAppCoreOverrides for #name {}
+            #[doc(hidden)]
+            mod #impl_mod {
+                use super::*;
+                // Import types used by OAppCore trait's default implementations
+                use soroban_sdk::{Address, BytesN, Env};
+                use oapp::oapp_core::OAppCore;
+
+                #[soroban_sdk::contractimpl(contracttrait)]
+                impl OAppCore for #name {}
+            }
         }
     });
 
     quote! {
-        use oapp::oapp_core::OAppCore as _;
-
-        #[soroban_sdk::contract]
         #[common_macros::ownable]
+        #[soroban_sdk::contract]
         #item_struct
 
-        #[soroban_sdk::contractimpl]
-        impl oapp::oapp_core::OAppCore for #name {
-            #[common_macros::only_owner]
-            fn set_peer(env: &soroban_sdk::Env, eid: u32, peer: &Option<soroban_sdk::BytesN<32>>) {
-                <Self as oapp::oapp_core::OAppCoreOverrides>::__set_peer(env, eid, peer)
-            }
-
-            #[common_macros::only_owner]
-            fn set_delegate(env: &soroban_sdk::Env, delegate: &Option<soroban_sdk::Address>) {
-                <Self as oapp::oapp_core::OAppCoreOverrides>::__set_delegate(env, delegate)
-            }
-
-            fn peer(env: &soroban_sdk::Env, eid: u32) -> Option<soroban_sdk::BytesN<32>> {
-                <Self as oapp::oapp_core::OAppCoreOverrides>::__peer(env, eid)
-            }
-
-            fn oapp_version(env: &soroban_sdk::Env) -> (u64, u64) {
-                <Self as oapp::oapp_core::OAppCoreOverrides>::__oapp_version(env)
-            }
-
-            fn endpoint(env: &soroban_sdk::Env) -> soroban_sdk::Address {
-                <Self as oapp::oapp_core::OAppCoreOverrides>::__endpoint(env)
-            }
-
-        }
-
         #manual_impl
     }
 }

package/contracts/oapp-macros/src/oapp_full.rs

@@ -1,15 +1,21 @@
-use crate::{oapp_core, oapp_receiver, oapp_sender, util::ManualImplConfig};
+use crate::{oapp_core, oapp_options_type3, oapp_receiver, oapp_sender, util::ManualImplConfig};
 use proc_macro2::TokenStream;
 use quote::quote;
 use syn::{Ident, ItemStruct};
 
+/// Generates the full OApp implementation: Core + Sender + Receiver + OptionsType3.
+///
+/// Combines all OApp components. Use `manual_impl_config` to skip generating
+/// specific trait implementations when custom implementations are needed.
 pub fn generate_impl(name: &Ident, item: ItemStruct, manual_impl_config: ManualImplConfig) -> TokenStream {
     let core_impl = oapp_core::generate_impl(name, item, manual_impl_config.core);
     let sender_impl = oapp_sender::generate_impl(name, manual_impl_config.sender);
-    let receiver_impl = oapp_receiver::generate_impl(name);
+    let receiver_impl = oapp_receiver::generate_impl(name, manual_impl_config.receiver);
+    let options_type3_impl = oapp_options_type3::generate_impl(name, manual_impl_config.options_type3);
     quote! {
         #core_impl
         #sender_impl
         #receiver_impl
+        #options_type3_impl
     }
 }

package/contracts/oapp-macros/src/oapp_options_type3.rs

@@ -1,46 +1,31 @@
+use heck::ToSnakeCase;
 use proc_macro2::TokenStream;
 use quote::quote;
-use syn::{Ident, ItemStruct};
+use syn::Ident;
 
-pub fn generate_impl(name: &Ident, item_struct: ItemStruct, manual_impl_options_type3: bool) -> TokenStream {
-    let manual_impl = (!manual_impl_options_type3).then(|| {
-        quote! {
-            use oapp::oapp_options_type3::OAppOptionsType3Overrides as _;
+/// Generates the `OAppOptionsType3` trait implementation.
+///
+/// When `manual_impl_options_type3` is false, generates an empty `impl OAppOptionsType3`
+/// that uses the trait's default implementations for enforced options management.
+pub fn generate_impl(name: &Ident, manual_impl_options_type3: bool) -> TokenStream {
+    let impl_mod =
+        syn::Ident::new(&format!("__oapp_options_type3_impl_{}", name.to_string().to_snake_case()), name.span());
 
-            impl oapp::oapp_options_type3::OAppOptionsType3Overrides for #name {}
+    let options_type3_impl = (!manual_impl_options_type3).then(|| {
+        quote! {
+            #[doc(hidden)]
+            mod #impl_mod {
+                use super::*;
+                use soroban_sdk::{Env, Bytes, Vec};
+                use oapp::oapp_options_type3::{OAppOptionsType3, EnforcedOptionParam};
+
+                #[soroban_sdk::contractimpl(contracttrait)]
+                impl OAppOptionsType3 for #name {}
+            }
         }
     });
 
     quote! {
-        use oapp::oapp_options_type3::OAppOptionsType3 as _;
-
-        #item_struct
-
-        #[soroban_sdk::contractimpl]
-        impl oapp::oapp_options_type3::OAppOptionsType3 for #name
-        {
-            #[common_macros::only_owner]
-            fn set_enforced_options(
-                env: &soroban_sdk::Env,
-                options: soroban_sdk::Vec<oapp::oapp_options_type3::EnforcedOptionParam>,
-            ) {
-                <Self as oapp::oapp_options_type3::OAppOptionsType3Overrides>::__set_enforced_options(env, options)
-            }
-
-            fn combine_options(
-                env: &soroban_sdk::Env,
-                eid: u32,
-                msg_type: u32,
-                extra_options: &soroban_sdk::Bytes,
-            ) -> soroban_sdk::Bytes {
-                <Self as oapp::oapp_options_type3::OAppOptionsType3Overrides>::__combine_options(env, eid, msg_type, extra_options)
-            }
-
-            fn enforced_options(env: &soroban_sdk::Env, eid: u32, msg_type: u32) -> soroban_sdk::Bytes {
-                <Self as oapp::oapp_options_type3::OAppOptionsType3Overrides>::__enforced_options(env, eid, msg_type)
-            }
-        }
-
-        #manual_impl
+        #options_type3_impl
     }
 }