@layerzerolabs/protocol-stellar-v2 0.2.15 → 0.2.18

package/contracts/oapps/oapp-macros/src/generators.rs

@@ -0,0 +1,128 @@
+//! Code generators for OApp trait implementations.
+
+use crate::CustomImpls;
+use heck::ToSnakeCase;
+use proc_macro2::TokenStream;
+use quote::quote;
+use syn::{Ident, ItemStruct};
+
+/// Generates a complete OApp implementation with contract attributes and trait implementations.
+///
+/// This function creates:
+/// - `#[common_macros::lz_contract]` - Wrapper macro that combines:
+///   - `#[soroban_sdk::contract]` - Makes the struct a Soroban contract
+///   - `#[common_macros::ttl_configurable]` - Adds TTL configuration with auth
+///   - `#[common_macros::ttl_extendable]` - Adds manual TTL extension support
+///   - `#[common_macros::ownable]` - Adds single-owner access control
+/// - OAppCore, OAppSenderInternal, OAppReceiver, and OAppOptionsType3 trait implementations
+///
+/// The `custom` parameter controls which trait implementations are generated vs.
+/// expected to be provided by the user.
+pub fn generate_oapp(item: ItemStruct, custom: CustomImpls) -> TokenStream {
+    let core_impl = generate_oapp_core(&item.ident, custom.core);
+    let sender_impl = generate_oapp_sender(&item.ident, custom.sender);
+    let receiver_impl = generate_oapp_receiver(&item.ident, custom.receiver);
+    let options_type3_impl = generate_oapp_options_type3(&item.ident, custom.options_type3);
+    quote! {
+        #[common_macros::lz_contract]
+        #item
+
+        #core_impl
+        #sender_impl
+        #receiver_impl
+        #options_type3_impl
+    }
+}
+
+/// Generates the `OAppCore` trait implementation.
+///
+/// When `custom` is false, generates an empty `impl OAppCore` that uses the trait's
+/// default implementations for peer management and endpoint access.
+fn generate_oapp_core(name: &Ident, custom: bool) -> TokenStream {
+    if custom {
+        return TokenStream::new();
+    }
+
+    let impl_mod = impl_mod_ident(name, "core");
+
+    quote! {
+        #[doc(hidden)]
+        mod #impl_mod {
+            use super::*;
+            use oapp::oapp_core::OAppCore;
+
+            #[soroban_sdk::contractimpl(contracttrait)]
+            impl OAppCore for #name {}
+        }
+    }
+}
+
+/// Generates the `OAppSenderInternal` trait implementation.
+///
+/// When `custom` is false, generates an empty `impl OAppSenderInternal` that uses the
+/// trait's default implementations for `__lz_quote` and `__lz_send`.
+fn generate_oapp_sender(name: &Ident, custom: bool) -> TokenStream {
+    if custom {
+        TokenStream::new()
+    } else {
+        quote! {
+            use oapp::oapp_sender::OAppSenderInternal as _;
+
+            impl oapp::oapp_sender::OAppSenderInternal for #name {}
+        }
+    }
+}
+
+/// Generates the `OAppReceiver` trait implementation.
+///
+/// When `custom` is false, generates an empty `impl OAppReceiver` that uses the trait's default
+/// `lz_receive` implementation (which calls `clear_payload_and_transfer` then `__lz_receive`).
+///
+/// Users must implement `LzReceiveInternal` themselves to provide the `__lz_receive` method.
+fn generate_oapp_receiver(name: &Ident, custom: bool) -> TokenStream {
+    if custom {
+        return TokenStream::new();
+    }
+
+    let impl_mod = impl_mod_ident(name, "receiver");
+
+    quote! {
+        #[doc(hidden)]
+        mod #impl_mod {
+            use super::*;
+            use oapp::oapp_receiver::OAppReceiver;
+
+            #[soroban_sdk::contractimpl(contracttrait)]
+            impl OAppReceiver for #name {}
+        }
+    }
+}
+
+/// Generates the `OAppOptionsType3` trait implementation.
+///
+/// When `custom` is false, generates an empty `impl OAppOptionsType3` that uses the
+/// trait's default implementations for enforced options management.
+fn generate_oapp_options_type3(name: &Ident, custom: bool) -> TokenStream {
+    if custom {
+        return TokenStream::new();
+    }
+
+    let impl_mod = impl_mod_ident(name, "options_type3");
+
+    quote! {
+        #[doc(hidden)]
+        mod #impl_mod {
+            use super::*;
+            use soroban_sdk::Vec;
+            use oapp::oapp_options_type3::{EnforcedOptionParam, OAppOptionsType3};
+
+            #[soroban_sdk::contractimpl(contracttrait)]
+            impl OAppOptionsType3 for #name {}
+        }
+    }
+}
+
+/// Creates a unique hidden module identifier for trait implementations.
+fn impl_mod_ident(struct_name: &Ident, trait_name: &str) -> Ident {
+    Ident::new(&format!("__oapp_{}_impl_{}", trait_name, struct_name.to_string().to_snake_case()), struct_name.span())
+}

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

@@ -8,53 +8,51 @@
 //! The OApp framework provides full bidirectional cross-chain communication:
 //!
 //! - **OAppCore**: Foundation for all OApp functionality (peer management, endpoint access)
-//! - **OAppSender**: Enables sending cross-chain messages through LayerZero
-//! - **OAppReceiver**: Handles incoming cross-chain messages
+//! - **OAppSenderInternal**: Enables sending cross-chain messages through LayerZero
+//! - **LzReceiveInternal**: Internal trait for message handling logic
+//! - **OAppReceiver**: Handles incoming cross-chain messages (has default `lz_receive` impl)
 //! - **OAppOptionsType3**: Manages enforced options for message execution parameters
 //!
-//! ## Available Macros
+//! ## Usage
 //!
 //! ### `#[oapp]`
 //! 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
-//! by the user instead of using default implementations.
+//! ### Custom Implementations
 //!
-//! ## Manual Implementation Control
-//!
-//! By default, `#[oapp]` generates default trait implementations. Use `#[oapp_manual_impl(...)]`
-//! to customize specific behaviors:
+//! By default, `#[oapp]` generates default trait implementations. Use `#[oapp(custom = [...])]`
+//! to provide your own custom implementations for specific traits:
 //!
 //! Supported options:
-//! - `core` - Manually implement `OAppCore`
-//! - `sender` - Manually implement `OAppSender`
-//! - `receiver` - Manually implement `OAppReceiver` (useful for custom `next_nonce`, etc.)
-//! - `options_type3` - Manually implement `OAppOptionsType3`
+//! - `core` - Custom implement `OAppCore`
+//! - `sender` - Custom implement `OAppSenderInternal`
+//! - `receiver` - Custom implement `OAppReceiver` (useful for custom `next_nonce`, etc.)
+//! - `options_type3` - Custom implement `OAppOptionsType3`
 //!
 //! ## Examples
 //!
 //! ### Full OApp with Default Implementations
 //!
 //! ```ignore
+//! use oapp::oapp_receiver::LzReceiveInternal;
 //! use oapp_macros::oapp;
 //!
 //! #[oapp]
 //! struct MyOApp;
 //!
-//! // Only __lz_receive must be implemented as an inherent method
-//! impl MyOApp {
+//! // Implement LzReceiveInternal to handle incoming messages
+//! impl LzReceiveInternal for MyOApp {
 //!     fn __lz_receive(
 //!         env: &Env,
-//!         executor: &Address,
 //!         origin: &Origin,
 //!         guid: &BytesN<32>,
 //!         message: &Bytes,
 //!         extra_data: &Bytes,
+//!         executor: &Address,
 //!         value: i128,
 //!     ) {
-//!         // Your message handling logic (verify_and_clear_payload already called)
+//!         // Your message handling logic (clear_payload_and_transfer already called)
 //!     }
 //! }
 //! ```
@@ -62,8 +60,9 @@
 //! ### OApp with Custom Core Version
 //!
 //! ```ignore
-//! #[oapp]
-//! #[oapp_manual_impl(core)]
+//! use oapp::oapp_receiver::LzReceiveInternal;
+//!
+//! #[oapp(custom = [core])]
 //! struct MyOApp;
 //!
 //! #[contractimpl(contracttrait)]
@@ -74,7 +73,7 @@
 //!     }
 //! }
 //!
-//! impl MyOApp {
+//! impl LzReceiveInternal for MyOApp {
 //!     fn __lz_receive(...) { /* ... */ }
 //! }
 //! ```
@@ -82,73 +81,131 @@
 //! ### OApp with Custom Receiver (e.g., ordered delivery)
 //!
 //! ```ignore
-//! use oapp::oapp_receiver::{OAppReceiver, verify_and_clear_payload};
+//! use oapp::oapp_receiver::{LzReceiveInternal, OAppReceiver};
 //!
-//! #[oapp]
-//! #[oapp_manual_impl(receiver)]
+//! #[oapp(custom = [receiver])]
 //! struct MyOrderedOApp;
 //!
+//! impl LzReceiveInternal for MyOrderedOApp {
+//!     fn __lz_receive(env: &Env, origin: &Origin, guid: &BytesN<32>, ...) {
+//!         // Your message handling logic
+//!     }
+//! }
+//!
 //! #[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
-//!     }
+//!     // lz_receive uses default impl which calls clear_payload_and_transfer then __lz_receive
 //! }
 //! ```
 //!
-//! ### OApp with Multiple Manual Implementations
+//! ### OApp with Multiple Custom Implementations
 //!
 //! ```ignore
-//! #[oapp]
-//! #[oapp_manual_impl(core, sender, options_type3)]
+//! use oapp::oapp_receiver::LzReceiveInternal;
+//!
+//! #[oapp(custom = [core, sender, options_type3])]
 //! struct MyCustomOApp;
 //!
 //! #[contractimpl(contracttrait)]
 //! #[common_macros::ownable]
 //! impl OAppCore for MyCustomOApp { /* ... */ }
-//! impl OAppSender for MyCustomOApp { /* ... */ }
+//! impl OAppSenderInternal for MyCustomOApp { /* ... */ }
 //! #[contractimpl(contracttrait)]
 //! impl OAppOptionsType3 for MyCustomOApp { /* ... */ }
 //!
-//! impl MyCustomOApp {
+//! impl LzReceiveInternal for MyCustomOApp {
 //!     fn __lz_receive(...) { /* ... */ }
 //! }
 //! ```
 
-use crate::util::parse_struct;
-use proc_macro::TokenStream;
+mod generators;
 
-mod oapp_core;
-mod oapp_full;
-mod oapp_options_type3;
-mod oapp_receiver;
-mod oapp_sender;
-mod util;
+use proc_macro::TokenStream;
+use syn::{
+    bracketed,
+    parse::{Parse, ParseStream},
+    punctuated::Punctuated,
+    Error, Ident, ItemStruct, Token,
+};
 
 /// Derives a complete OApp: `#[contract]` + `#[ownable]` + Core + Sender + Receiver + OptionsType3.
 ///
-/// You must implement `__lz_receive` as an inherent method. See module docs for examples.
+/// ## Usage
+///
+/// ```ignore
+/// // Default: generates all trait implementations
+/// #[oapp]
+/// struct MyOApp;
+///
+/// // Provide custom implementations for specific traits
+/// #[oapp(custom = [core, receiver])]
+/// struct MyCustomOApp;
+/// ```
+///
+/// ## Custom Options
+/// - `core` - Manually implement `OAppCore`
+/// - `sender` - Manually implement `OAppSenderInternal`
+/// - `receiver` - Manually implement `OAppReceiver`
+/// - `options_type3` - Manually implement `OAppOptionsType3`
+///
+/// You must implement `LzReceiveInternal` for your struct. 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) {
-        Ok(result) => result,
-        Err(e) => return e,
-    };
-    oapp_full::generate_impl(&name, item, disable_config).into()
+pub fn oapp(attr: TokenStream, item: TokenStream) -> TokenStream {
+    let custom = syn::parse_macro_input!(attr as CustomImpls);
+    let item_struct = syn::parse_macro_input!(item as ItemStruct);
+    generators::generate_oapp(item_struct, custom).into()
 }
 
-/// Marker attribute to skip generating specific trait implementations.
-///
-/// Supported options: `core`, `sender`, `receiver`, `options_type3`
+/// Specifies which OApp trait implementations the user will provide themselves.
 ///
-/// 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
+/// Parsed from `#[oapp(custom = [...])]`. When a field is `true`, the macro skips
+/// generating that trait implementation, allowing the user to provide their own.
+#[derive(Debug, Clone, Copy, Default)]
+struct CustomImpls {
+    pub core: bool,
+    pub sender: bool,
+    pub receiver: bool,
+    pub options_type3: bool,
+}
+
+impl Parse for CustomImpls {
+    fn parse(input: ParseStream) -> syn::Result<Self> {
+        if input.is_empty() {
+            return Ok(Self::default());
+        }
+
+        let key: Ident = input.parse()?;
+        if key != "custom" {
+            return Err(Error::new(key.span(), "expected `custom`"));
+        }
+
+        input.parse::<Token![=]>()?;
+
+        let content;
+        bracketed!(content in input);
+
+        let idents = Punctuated::<Ident, Token![,]>::parse_terminated(&content)?;
+        let mut custom_impls = Self::default();
+
+        for ident in idents {
+            match ident.to_string().as_str() {
+                "core" => custom_impls.core = true,
+                "sender" => custom_impls.sender = true,
+                "receiver" => custom_impls.receiver = true,
+                "options_type3" => custom_impls.options_type3 = true,
+                _ => {
+                    return Err(Error::new(
+                        ident.span(),
+                        "expected one of `core`, `sender`, `receiver`, `options_type3`",
+                    ));
+                }
+            }
+        }
+
+        Ok(custom_impls)
+    }
 }

package/contracts/oapps/oft/integration-tests/setup.rs

@@ -7,14 +7,18 @@ extern crate std;
 
 use crate::integration_tests::utils::{address_to_peer_bytes32, peer_bytes32_to_address};
 use common_macros::contract_impl;
-use endpoint_v2::{EndpointV2, EndpointV2Client, ILayerZeroComposer};
-use oft::oft::{oft_initialize, OFTClient, OFTInternal, OFT};
-use oft::storage::OFTStorage;
-use oft::types::OFTReceipt;
+use endpoint_v2::{EndpointV2, EndpointV2Client, ILayerZeroComposer, Origin};
+use oapp::oapp_receiver::LzReceiveInternal;
+use oft::{
+    initialize_oft,
+    oft::{OFTClient, OFTInternal, OFT},
+    oft_impl,
+    storage::OFTStorage,
+    types::OFTReceipt,
+};
 use simple_message_lib::{SimpleMessageLib, SimpleMessageLibClient};
-use soroban_sdk::contractimpl;
 use soroban_sdk::{
-    contract, contracttype, log, symbol_short,
+    contract, contractimpl, contracttype, log, symbol_short,
     testutils::{Address as _, MockAuth, MockAuthInvoke},
     token::{StellarAssetClient, TokenClient},
     Address, Bytes, BytesN, Env, IntoVal,
@@ -27,6 +31,20 @@ use soroban_sdk::{
 #[oapp_macros::oapp]
 pub struct TestOFT;
 
+impl LzReceiveInternal for TestOFT {
+    fn __lz_receive(
+        env: &Env,
+        origin: &Origin,
+        guid: &BytesN<32>,
+        message: &Bytes,
+        extra_data: &Bytes,
+        executor: &Address,
+        value: i128,
+    ) {
+        oft_impl::lz_receive::<Self>(env, executor, origin, guid, message, extra_data, value)
+    }
+}
+
 #[contract_impl]
 impl TestOFT {
     pub fn __constructor(
@@ -37,7 +55,7 @@ impl TestOFT {
         delegate: &Option<Address>,
         shared_decimals: u32,
     ) {
-        oft_initialize::<Self>(env, owner, token, endpoint, delegate, shared_decimals)
+        initialize_oft::<Self>(env, owner, token, endpoint, delegate, shared_decimals)
     }
 }
 

package/contracts/oapps/oft/src/errors.rs

@@ -1,8 +1,13 @@
 use common_macros::contract_error;
 
+// OFT library error codes: 3000-3099
+// See ERROR_SPEC.md for allocation rules
+
+/// OFTError: 3000-3099
 #[contract_error]
 pub enum OFTError {
-    InvalidLocalDecimals = 2100,
+    InvalidLocalDecimals = 3000,
+    NotInitialized,
     Overflow,
     SlippageExceeded,
 }

package/contracts/oapps/oft/src/extensions/oft_fee.rs

@@ -1,5 +1,5 @@
-use common_macros::{contract_error, only_owner, storage};
-use soroban_sdk::{assert_with_error, contractevent, contracttrait, token::TokenClient, Address, Env};
+use common_macros::{contract_error, contract_trait, only_auth, storage};
+use soroban_sdk::{assert_with_error, contractevent, token::TokenClient, Address, Env};
 use utils::{option_ext::OptionExt, ownable::Ownable};
 
 /// Base fee in basis points (10,000 BPS = 100%)
@@ -52,9 +52,9 @@ pub struct FeeDepositAddressSet {
     pub fee_deposit_address: Address,
 }
 
-#[contracttrait]
+#[contract_trait]
 pub trait OFTFee: OFTFeeInternal + Ownable + Sized {
-    #[only_owner]
+    #[only_auth]
     fn set_default_fee_bps(env: &Env, default_fee_bps: u64) {
         assert_with_error!(env, default_fee_bps <= BASE_FEE_BPS, OFTFeeError::InvalidFeeBps);
         let current_default = OFTFeeStorage::default_fee_bps(env);
@@ -63,7 +63,7 @@ pub trait OFTFee: OFTFeeInternal + Ownable + Sized {
         DefaultFeeBpsSet { fee_bps: default_fee_bps }.publish(env);
     }
 
-    #[only_owner]
+    #[only_auth]
     fn set_fee_bps(env: &Env, dst_eid: u32, fee_bps: u64) {
         assert_with_error!(env, fee_bps <= BASE_FEE_BPS, OFTFeeError::InvalidFeeBps);
         if OFTFeeStorage::has_fee_bps(env, dst_eid) {
@@ -74,14 +74,14 @@ pub trait OFTFee: OFTFeeInternal + Ownable + Sized {
         FeeBpsSet { dst_eid, fee_bps }.publish(env);
     }
 
-    #[only_owner]
+    #[only_auth]
     fn unset_fee_bps(env: &Env, dst_eid: u32) {
         assert_with_error!(env, OFTFeeStorage::has_fee_bps(env, dst_eid), OFTFeeError::NotFound);
         OFTFeeStorage::remove_fee_bps(env, dst_eid);
         FeeBpsUnset { dst_eid }.publish(env);
     }
 
-    #[only_owner]
+    #[only_auth]
     fn set_fee_deposit_address(env: &Env, fee_deposit_address: Address) {
         if let Some(current_address) = OFTFeeStorage::fee_deposit_address(env) {
             assert_with_error!(env, current_address != fee_deposit_address, OFTFeeError::SameValue);
@@ -155,7 +155,7 @@ pub trait OFTFeeInternal {
     /// * `sender` - The sender address to transfer fee from
     /// * `fee_amount` - The fee amount to transfer
     fn __charge_fee(env: &Env, token: &Address, sender: &Address, fee_amount: i128) {
-        if fee_amount > 0 {
+        if fee_amount != 0 {
             assert_with_error!(
                 env,
                 OFTFeeStorage::fee_deposit_address(env).is_some(),

package/contracts/oapps/oft/src/extensions/pausable.rs

@@ -1,5 +1,5 @@
-use common_macros::{contract_error, only_owner, storage};
-use soroban_sdk::{assert_with_error, contractevent, contracttrait, Env};
+use common_macros::{contract_error, contract_trait, only_auth, storage};
+use soroban_sdk::{assert_with_error, contractevent, Env};
 use utils::ownable::Ownable;
 
 #[storage]
@@ -21,9 +21,9 @@ pub struct PausedSet {
     pub paused: bool,
 }
 
-#[contracttrait]
+#[contract_trait]
 pub trait OFTPausable: OFTPausableInternal + Ownable + Sized {
-    #[only_owner]
+    #[only_auth]
     fn set_paused(env: &Env, paused: bool) {
         let current_paused = OFTPausableStorage::paused(env);
         assert_with_error!(env, current_paused != paused, OFTPausableError::PauseStatusUnchanged);

package/contracts/oapps/oft/src/extensions/rate_limiter.rs

@@ -1,5 +1,5 @@
-use common_macros::{contract_error, only_owner, storage};
-use soroban_sdk::{assert_with_error, contractevent, contracttrait, contracttype, panic_with_error, Env};
+use common_macros::{contract_error, contract_trait, only_auth, storage};
+use soroban_sdk::{assert_with_error, contractevent, contracttype, panic_with_error, Env};
 use utils::ownable::Ownable;
 
 #[contracttype]
@@ -87,9 +87,9 @@ fn checkpoint_rate_limit_in_flight(env: &Env, direction: &Direction, eid: u32) {
     RateLimitStorage::set_rate_limit(env, direction, eid, &rate_limit);
 }
 
-#[contracttrait]
+#[contract_trait]
 pub trait RateLimiter: RateLimiterInternal + Ownable + Sized {
-    #[only_owner]
+    #[only_auth]
     fn set_rate_limit(env: &Env, direction: &Direction, eid: u32, limit: i128, window_seconds: u64) {
         assert_with_error!(env, limit > 0, RateLimitError::InvalidLimit);
         assert_with_error!(env, window_seconds > 0, RateLimitError::InvalidWindowSeconds);
@@ -122,7 +122,7 @@ pub trait RateLimiter: RateLimiterInternal + Ownable + Sized {
         }
     }
 
-    #[only_owner]
+    #[only_auth]
     fn unset_rate_limit(env: &Env, direction: &Direction, eid: u32) {
         assert_with_error!(env, RateLimitStorage::has_rate_limit(env, direction, eid), RateLimitError::SameValue);
         RateLimitStorage::remove_rate_limit(env, direction, eid);

package/contracts/oapps/oft/src/lib.rs

@@ -1,18 +1,20 @@
 #![no_std]
 
 pub mod codec;
-pub mod constants;
-pub mod default_oft_impl;
 pub mod errors;
 pub mod events;
 pub mod extensions;
 pub mod interfaces;
 pub mod oft;
+pub mod oft_impl;
 pub mod oft_types;
 pub mod storage;
 pub mod types;
 pub mod utils;
 
+// Re-export commonly used items
+pub use oft_impl::initialize_oft;
+
 #[cfg(test)]
 #[path = "../integration-tests/mod.rs"]
 pub mod integration_tests;