@layerzerolabs/protocol-stellar-v2 0.2.15 → 0.2.18

package/contracts/oapps/oapp/src/oapp_receiver.rs

@@ -1,43 +1,76 @@
-use crate::{errors::OAppError, oapp_core::OAppCore};
-use endpoint_v2::{LayerZeroEndpointV2Client, Origin};
-use soroban_sdk::{assert_with_error, contracttrait, token::TokenClient, Address, Bytes, BytesN, Env};
+use crate::{
+    errors::OAppError,
+    oapp_core::{endpoint_client, OAppCore},
+};
+use common_macros::contract_trait;
+use endpoint_v2::Origin;
+use soroban_sdk::{assert_with_error, token::TokenClient, Address, Bytes, BytesN, Env};
+
+// =====================================================
+// LzReceiveInternal Trait
+// =====================================================
+
+/// Application-specific handler for incoming LayerZero messages.
+///
+/// Implement this trait to define how your OApp processes cross-chain messages.
+/// The default `OAppReceiver::lz_receive` calls `clear_payload_and_transfer` first,
+/// then delegates to your `__lz_receive` implementation.
+///
+/// **Important:** Do NOT call `clear_payload_and_transfer` in your implementation -
+/// it is handled automatically by the default `lz_receive`.
+pub trait LzReceiveInternal {
+    /// Processes a verified cross-chain message.
+    ///
+    /// Called after payload verification. Implement your message handling logic here.
+    fn __lz_receive(
+        env: &Env,
+        origin: &Origin,
+        guid: &BytesN<32>,
+        message: &Bytes,
+        extra_data: &Bytes,
+        executor: &Address,
+        value: i128,
+    );
+}
 
 // =====================================================
 // OAppReceiver Trait
 // =====================================================
 
-/// Trait for OApps that can receive cross-chain messages from LayerZero.
+/// Receiver trait for OApps that accept cross-chain messages from LayerZero.
 ///
-/// This trait combines the functionality of `ILayerZeroReceiver` (from endpoint-v2) with
-/// OApp-specific features. It maintains the same function signatures as `ILayerZeroReceiver`
-/// for `allow_initialize_path`, `next_nonce`, and `lz_receive`, which allows the endpoint
-/// to call these methods via `LayerZeroReceiverClient` (client calls are resolved by function name).
+/// Mirrors `ILayerZeroReceiver` function signatures, allowing the executor to call
+/// these methods via `LayerZeroReceiverClient`.
 ///
 /// # Default Implementations
-/// - `allow_initialize_path`: Returns true if the origin's sender matches the configured peer
-/// - `next_nonce`: Returns 0 (no nonce ordering enforcement)
-/// - `is_compose_msg_sender`: Returns true if sender is the current contract
-///
-/// # Required Implementation
-/// - `lz_receive`: Must be implemented by each OApp to handle incoming messages
+/// | Method | Behavior |
+/// |--------|----------|
+/// | `allow_initialize_path` | Returns true if origin sender matches configured peer |
+/// | `next_nonce` | Returns 0 (unordered delivery) |
+/// | `lz_receive` | Verifies payload, then calls `LzReceiveInternal::__lz_receive` |
+/// | `is_compose_msg_sender` | Returns true if sender is current contract |
 ///
 /// # Usage
-/// When using `#[oapp_macros::oapp]`, the macro generates `lz_receive` that
-/// automatically calls `verify_and_clear_payload` before delegating to `__lz_receive`.
-/// **Do NOT call `verify_and_clear_payload` in your `__lz_receive` implementation.**
 ///
 /// ```ignore
+/// use oapp::oapp_receiver::LzReceiveInternal;
+///
 /// #[oapp_macros::oapp]
 /// pub struct MyOApp;
 ///
-/// impl MyOApp {
-///     pub fn __lz_receive(env: &Env, executor: &Address, origin: &Origin, ...) {
-///         // Handle the incoming message (verify_and_clear_payload already called)
+/// impl LzReceiveInternal for MyOApp {
+///     fn __lz_receive(env: &Env, origin: &Origin, guid: &BytesN<32>,
+///                     message: &Bytes, extra_data: &Bytes, executor: &Address, value: i128) {
+///         // Your message handling logic here
 ///     }
 /// }
 /// ```
-#[contracttrait(client_name = "OAppReceiverClient")]
-pub trait OAppReceiver: OAppCore {
+///
+/// # Customization
+/// For custom behavior (e.g., ordered nonce enforcement), use `#[oapp(custom = [receiver])]`
+/// and implement both `LzReceiveInternal` and `OAppReceiver`.
+#[contract_trait]
+pub trait OAppReceiver: OAppCore + LzReceiveInternal {
     /// Checks if a messaging path can be initialized for the given origin.
     ///
     /// # Arguments
@@ -50,24 +83,37 @@ pub trait OAppReceiver: OAppCore {
         peer.is_some_and(|peer| peer == origin.sender)
     }
 
-    /// Returns the next expected nonce for ordered message delivery.
-    /// 0 means there is NO nonce ordered enforcement.
+    /// Retrieves the next nonce for a given source endpoint and sender address.
+    ///
+    /// The path nonce starts from 1. If 0 is returned it means that there is NO nonce ordered enforcement.
+    /// This is required by the off-chain executor to determine if the OApp expects message execution to be ordered.
+    /// This is also enforced by the OApp.
+    /// By default this is NOT enabled, i.e. next_nonce is hardcoded to return 0.
     ///
     /// # Arguments
     /// * `src_eid` - The source endpoint ID
     /// * `sender` - The sender OApp address
+    ///
+    /// # Returns
+    /// The next nonce
     fn next_nonce(_env: &Env, _src_eid: u32, _sender: &BytesN<32>) -> u64 {
         0
     }
 
-    /// Receives and processes a cross-chain message.
+    /// Entry point for receiving messages or packets from the LayerZero endpoint.
+    ///
+    /// The default implementation calls `clear_payload_and_transfer` to validate the message
+    /// and clear it from the endpoint, then delegates to `__lz_receive` for application logic.
     ///
     /// # Arguments
-    /// * `executor` - The executor address delivering the message
-    /// * `origin` - The origin information (source EID, sender, nonce)
-    /// * `guid` - The message GUID
-    /// * `message` - The message content
-    /// * `extra_data` - Additional executor-provided data (untrusted)
+    /// * `executor` - The address of the executor for the received message
+    /// * `origin` - The origin information containing the source endpoint and sender address:
+    ///   - `src_eid`: The source chain endpoint ID
+    ///   - `sender`: The sender address on the source chain
+    ///   - `nonce`: The nonce of the message
+    /// * `guid` - The unique identifier for the received LayerZero message
+    /// * `message` - The payload of the received message
+    /// * `extra_data` - Additional arbitrary data provided by the corresponding executor
     /// * `value` - The native token value sent with the message
     fn lz_receive(
         env: &Env,
@@ -77,7 +123,10 @@ pub trait OAppReceiver: OAppCore {
         message: &Bytes,
         extra_data: &Bytes,
         value: i128,
-    );
+    ) {
+        clear_payload_and_transfer::<Self>(env, executor, origin, guid, message, value);
+        Self::__lz_receive(env, origin, guid, message, extra_data, executor, value)
+    }
 
     /// Indicates whether an address is an approved composeMsg sender to the Endpoint.
     ///
@@ -100,7 +149,16 @@ pub trait OAppReceiver: OAppCore {
 // Helper functions
 // =====================================================
 
-pub fn verify_and_clear_payload<T: OAppCore>(
+/// Clears the message payload from the endpoint and transfers native tokens from the executor to the oapp if has value.
+///
+/// # Arguments
+/// * `env` - The environment
+/// * `executor` - The address of the executor delivering the message
+/// * `origin` - The origin information (source EID, sender, nonce)
+/// * `guid` - The unique identifier for the LayerZero message to clear the payload from
+/// * `message` - The message payload to clear
+/// * `value` - The native token value to transfer from the executor to the oapp if has value
+pub fn clear_payload_and_transfer<T: OAppCore>(
     env: &Env,
     executor: &Address,
     origin: &Origin,
@@ -108,16 +166,23 @@ pub fn verify_and_clear_payload<T: OAppCore>(
     message: &Bytes,
     value: i128,
 ) {
-    executor.require_auth();
-    assert_with_error!(env, Some(origin.sender.clone()) == T::peer(env, origin.src_eid), OAppError::OnlyPeer);
-
-    let curr_address = env.current_contract_address();
-    let endpoint = LayerZeroEndpointV2Client::new(env, &T::endpoint(env));
-    endpoint.clear(&curr_address, origin, &curr_address, guid, message);
+    let this_address = env.current_contract_address();
+    let endpoint_client = endpoint_client::<T>(env);
 
+    // Require authorization from the executor and transfer the value from the executor to the oapp if has value
+    executor.require_auth();
     if value > 0 {
-        let native_token = endpoint.native_token();
-        let token_client = TokenClient::new(env, &native_token);
-        token_client.transfer(executor, &curr_address, &value);
+        let token_client = TokenClient::new(env, &endpoint_client.native_token());
+        token_client.transfer(executor, &this_address, &value);
     }
+
+    // Assert that the message is from the expected peer
+    assert_with_error!(
+        env,
+        T::peer(env, origin.src_eid).is_some_and(|peer| peer == origin.sender),
+        OAppError::OnlyPeer
+    );
+
+    // Clear the message payload from the endpoint
+    endpoint_client.clear(&this_address, origin, &this_address, guid, message);
 }

package/contracts/oapps/oapp/src/oapp_sender.rs

@@ -1,11 +1,14 @@
-use crate::{errors::OAppError, oapp_core::OAppCore};
-use endpoint_v2::{LayerZeroEndpointV2Client, MessagingFee, MessagingParams, MessagingReceipt};
+use crate::{
+    errors::OAppError,
+    oapp_core::{endpoint_client, OAppCore},
+};
+use endpoint_v2::{MessagingFee, MessagingParams, MessagingReceipt};
 use soroban_sdk::{token::TokenClient, Address, Bytes, Env};
 use utils::option_ext::OptionExt;
 
 /// A helper trait for sending cross-chain messages via LayerZero.
 ///
-/// Contracts should implement this trait to gain access to the `lz_quote` and `lz_send` helper
+/// Contracts should implement this trait to gain access to the `__lz_quote` and `__lz_send` helper
 /// methods for cross-chain messaging. This trait provides default implementations that handle
 /// fee payment and message dispatch through the LayerZero endpoint.
 ///
@@ -14,7 +17,7 @@ use utils::option_ext::OptionExt;
 /// methods as part of your contract's public interface (i.e., do not use `#[contractimpl]` on
 /// the implementation of this trait). Instead, call these methods internally from your
 /// contract's own public functions.
-pub trait OAppSender: OAppCore {
+pub trait OAppSenderInternal: OAppCore {
     /// Quote the messaging fee for sending a message to the other chain
     ///
     /// # Arguments
@@ -25,11 +28,9 @@ pub trait OAppSender: OAppCore {
     ///
     /// # Returns
     /// * `MessagingFee`: The messaging fee for the message
-    fn lz_quote(env: &Env, dst_eid: u32, message: &Bytes, options: &Bytes, pay_in_zro: bool) -> MessagingFee {
-        let endpoint = Self::endpoint(env);
-        let endpoint_client = LayerZeroEndpointV2Client::new(env, &endpoint);
+    fn __quote(env: &Env, dst_eid: u32, message: &Bytes, options: &Bytes, pay_in_zro: bool) -> MessagingFee {
         let receiver = Self::peer(env, dst_eid).unwrap_or_panic(env, OAppError::NoPeer);
-        endpoint_client.quote(
+        endpoint_client::<Self>(env).quote(
             &env.current_contract_address(),
             &MessagingParams { dst_eid, receiver, message: message.clone(), options: options.clone(), pay_in_zro },
         )
@@ -38,38 +39,37 @@ pub trait OAppSender: OAppCore {
     /// Send a message to the other chain
     ///
     /// # Arguments
-    /// * `payer`: The address of the payer
     /// * `dst_eid`: The destination endpoint ID
     /// * `message`: The message to send
     /// * `options`: The options for the message
+    /// * `fee_payer`: The address of the payer for paying the messaging fees
     /// * `fee`: The messaging fee
     /// * `refund_address`: The address to receive any excess fees
     ///
     /// # Returns
     /// * `MessagingReceipt`: The receipt for the sent message
-    fn lz_send(
+    fn __lz_send(
         env: &Env,
-        payer: &Address,
         dst_eid: u32,
         message: &Bytes,
         options: &Bytes,
+        fee_payer: &Address,
         fee: &MessagingFee,
         refund_address: &Address,
     ) -> MessagingReceipt {
         // Pay the messaging fees
-        Self::pay_native(env, payer, fee.native_fee);
-        if fee.zro_fee > 0 {
-            Self::pay_zro(env, payer, fee.zro_fee);
+        Self::__pay_native(env, fee_payer, fee.native_fee);
+        if fee.zro_fee != 0 {
+            Self::__pay_zro(env, fee_payer, fee.zro_fee);
         }
 
         // Send the message to the other chain
-        let endpoint_client = LayerZeroEndpointV2Client::new(env, &Self::endpoint(env));
-        let peer = Self::peer(env, dst_eid).unwrap_or_panic(env, OAppError::NoPeer);
-        endpoint_client.send(
+        let receiver = Self::peer(env, dst_eid).unwrap_or_panic(env, OAppError::NoPeer);
+        endpoint_client::<Self>(env).send(
             &env.current_contract_address(),
             &MessagingParams {
                 dst_eid,
-                receiver: peer,
+                receiver,
                 message: message.clone(),
                 options: options.clone(),
                 pay_in_zro: fee.zro_fee > 0,
@@ -81,28 +81,20 @@ pub trait OAppSender: OAppCore {
     /// Pay the native fee to the endpoint for sending a message to the other chain
     ///
     /// # Arguments
-    /// * `payer`: The address of the payer
+    /// * `fee_payer`: The address of the fee payer
     /// * `native_fee`: The native fee to pay
-    fn pay_native(env: &Env, payer: &Address, native_fee: i128) {
-        let endpoint = Self::endpoint(env);
-        let endpoint_client = LayerZeroEndpointV2Client::new(env, &endpoint);
-        let native_token = endpoint_client.native_token();
-        let token_client = TokenClient::new(env, &native_token);
-
-        token_client.transfer(payer, &endpoint, &native_fee);
+    fn __pay_native(env: &Env, fee_payer: &Address, native_fee: i128) {
+        let token_client = TokenClient::new(env, &endpoint_client::<Self>(env).native_token());
+        token_client.transfer(fee_payer, Self::endpoint(env), &native_fee);
     }
 
     /// Pay the ZRO fee to the endpoint for sending a message to the other chain
     ///
     /// # Arguments
-    /// * `payer`: The address of the payer
+    /// * `fee_payer`: The address of the fee payer
     /// * `zro_fee`: The ZRO fee to pay
-    fn pay_zro(env: &Env, payer: &Address, zro_fee: i128) {
-        let endpoint = Self::endpoint(env);
-        let endpoint_client = LayerZeroEndpointV2Client::new(env, &endpoint);
-        let zro_token = endpoint_client.zro().unwrap_or_panic(env, OAppError::ZROTokenUnavailable);
-        let token_client = TokenClient::new(env, &zro_token);
-
-        token_client.transfer(payer, &endpoint, &zro_fee);
+    fn __pay_zro(env: &Env, fee_payer: &Address, zro_fee: i128) {
+        let zro_token = endpoint_client::<Self>(env).zro().unwrap_or_panic(env, OAppError::ZroTokenUnavailable);
+        TokenClient::new(env, &zro_token).transfer(fee_payer, Self::endpoint(env), &zro_fee);
     }
 }

package/contracts/oapps/oapp/src/tests/test_oapp_core.rs

@@ -1,8 +1,9 @@
-use crate::{self as oapp, oapp_core::PeerSet};
+use crate::{self as oapp, oapp_core::PeerSet, oapp_receiver::LzReceiveInternal};
+use endpoint_v2::Origin;
 use soroban_sdk::{
     contract, contractimpl,
     testutils::{Address as _, MockAuth, MockAuthInvoke},
-    Address, BytesN, Env, IntoVal,
+    Address, Bytes, BytesN, Env, IntoVal,
 };
 use utils::testing_utils::assert_event;
 
@@ -19,14 +20,14 @@ impl DummyEndpoint {
 #[oapp_macros::oapp]
 pub struct DummyOApp;
 
-impl DummyOApp {
+impl LzReceiveInternal for DummyOApp {
     fn __lz_receive(
         _env: &Env,
-        _executor: &Address,
-        _origin: &endpoint_v2::Origin,
+        _origin: &Origin,
         _guid: &BytesN<32>,
-        _message: &soroban_sdk::Bytes,
-        _extra_data: &soroban_sdk::Bytes,
+        _message: &Bytes,
+        _extra_data: &Bytes,
+        _executor: &Address,
         _value: i128,
     ) {
         // Not used in core tests
@@ -36,7 +37,7 @@ impl DummyOApp {
 #[contractimpl]
 impl DummyOApp {
     pub fn __constructor(env: &Env, owner: &Address, endpoint: &Address) {
-        oapp::oapp_core::oapp_initialize::<Self>(env, owner, endpoint, &None);
+        oapp::oapp_core::initialize_oapp::<Self>(env, owner, endpoint, &None);
     }
 }
 

package/contracts/oapps/oapp/src/tests/test_oapp_options_type3.rs

@@ -1,12 +1,15 @@
-use crate as oapp;
-use crate::oapp_options_type3::EnforcedOptionParam;
-use crate::oapp_options_type3::EnforcedOptionSet;
+use crate::{
+    self as oapp,
+    oapp_core::OAppCore,
+    oapp_options_type3::{EnforcedOptionParam, EnforcedOptionSet},
+    oapp_receiver::{LzReceiveInternal, OAppReceiver},
+};
 use common_macros::contract_impl;
-use soroban_sdk::contract;
-use soroban_sdk::contractimpl;
+use endpoint_v2::Origin;
 use soroban_sdk::{
+    contract, contractimpl,
     testutils::{Address as _, MockAuth, MockAuthInvoke},
-    vec, Address, Bytes, Env, IntoVal,
+    vec, Address, Bytes, BytesN, Env, IntoVal,
 };
 use utils::testing_utils::assert_event;
 
@@ -26,31 +29,36 @@ impl DummyEndpoint {
     }
 }
 
-#[oapp_macros::oapp]
-#[oapp_macros::oapp_manual_impl(core, sender, receiver)]
+#[oapp_macros::oapp(custom = [core, sender, receiver])]
 pub struct DummyOAppOptionsType3;
 
-#[contract_impl]
-impl DummyOAppOptionsType3 {
-    pub fn __constructor(env: &Env, owner: &Address, endpoint: &Address, delegate: &Option<Address>) {
-        oapp::oapp_core::oapp_initialize::<Self>(env, owner, endpoint, delegate);
-    }
-}
+#[contract_impl(contracttrait)]
+impl OAppCore for DummyOAppOptionsType3 {}
 
-impl DummyOAppOptionsType3 {
+impl LzReceiveInternal for DummyOAppOptionsType3 {
     fn __lz_receive(
         _env: &Env,
-        _executor: &Address,
         _origin: &endpoint_v2::Origin,
-        _guid: &soroban_sdk::BytesN<32>,
+        _guid: &BytesN<32>,
         _message: &Bytes,
         _extra_data: &Bytes,
+        _executor: &Address,
         _value: i128,
     ) {
         // Dummy implementation for testing
     }
 }
 
+#[contract_impl(contracttrait)]
+impl OAppReceiver for DummyOAppOptionsType3 {}
+
+#[contract_impl]
+impl DummyOAppOptionsType3 {
+    pub fn __constructor(env: &Env, owner: &Address, endpoint: &Address, delegate: &Option<Address>) {
+        oapp::oapp_core::initialize_oapp::<Self>(env, owner, endpoint, delegate);
+    }
+}
+
 struct TestSetup<'a> {
     env: Env,
     owner: Address,

package/contracts/oapps/oapp/src/tests/test_oapp_receiver.rs

@@ -1,7 +1,7 @@
-use crate as oapp;
-use crate::errors::OAppError;
-use crate::oapp_core::OAppCoreStorage;
-use crate::tests::test_oapp_core::DummyEndpoint;
+use crate::{
+    self as oapp, errors::OAppError, oapp_core::OAppCoreStorage, oapp_receiver::LzReceiveInternal,
+    tests::test_oapp_core::DummyEndpoint,
+};
 use endpoint_v2::Origin;
 use soroban_sdk::{assert_with_error, contractimpl, testutils::Address as _, Address, Bytes, BytesN, Env};
 use utils::option_ext::OptionExt;
@@ -9,14 +9,14 @@ use utils::option_ext::OptionExt;
 #[oapp_macros::oapp]
 pub struct DummyOAppReceiver;
 
-impl DummyOAppReceiver {
+impl LzReceiveInternal for DummyOAppReceiver {
     fn __lz_receive(
         _env: &Env,
-        _executor: &Address,
         _origin: &Origin,
         _guid: &BytesN<32>,
         _message: &Bytes,
         _extra_data: &Bytes,
+        _executor: &Address,
         _value: i128,
     ) {
         // do nothing
@@ -26,7 +26,7 @@ impl DummyOAppReceiver {
 #[contractimpl]
 impl DummyOAppReceiver {
     pub fn __constructor(env: &Env, owner: &Address, endpoint: &Address) {
-        oapp::oapp_core::oapp_initialize::<Self>(env, owner, endpoint, &None);
+        oapp::oapp_core::initialize_oapp::<Self>(env, owner, endpoint, &None);
     }
 
     pub fn assert_allowed_peer(env: &Env, origin: &Origin) {

package/contracts/oapps/oapp/src/tests/test_oapp_sender.rs

@@ -1,6 +1,5 @@
-use crate as oapp;
-use crate::errors::OAppError;
-use endpoint_v2::{MessagingFee, MessagingParams, MessagingReceipt};
+use crate::{self as oapp, errors::OAppError, oapp_receiver::LzReceiveInternal};
+use endpoint_v2::{MessagingFee, MessagingParams, MessagingReceipt, Origin};
 use soroban_sdk::{
     contract, contractimpl, symbol_short,
     testutils::{Address as _, MockAuth, MockAuthInvoke},
@@ -49,14 +48,14 @@ impl MockEndpoint {
 #[oapp_macros::oapp]
 pub struct DummyOAppSender;
 
-impl DummyOAppSender {
+impl LzReceiveInternal for DummyOAppSender {
     fn __lz_receive(
         _env: &Env,
-        _executor: &Address,
-        _origin: &endpoint_v2::Origin,
+        _origin: &Origin,
         _guid: &BytesN<32>,
         _message: &Bytes,
         _extra_data: &Bytes,
+        _executor: &Address,
         _value: i128,
     ) {
         // Not used in sender tests
@@ -66,11 +65,11 @@ impl DummyOAppSender {
 #[contractimpl]
 impl DummyOAppSender {
     pub fn __constructor(env: &Env, owner: &Address, endpoint: &Address) {
-        oapp::oapp_core::oapp_initialize::<Self>(env, owner, endpoint, &None);
+        oapp::oapp_core::initialize_oapp::<Self>(env, owner, endpoint, &None);
     }
 
     pub fn quote(env: &Env, dst_eid: u32, message: &Bytes, options: &Bytes, pay_in_zro: bool) -> MessagingFee {
-        Self::lz_quote(env, dst_eid, message, options, pay_in_zro)
+        Self::__quote(env, dst_eid, message, options, pay_in_zro)
     }
 
     pub fn send(
@@ -83,17 +82,17 @@ impl DummyOAppSender {
         refund_address: &Address,
     ) -> MessagingReceipt {
         sender.require_auth();
-        Self::lz_send(env, sender, dst_eid, message, options, fee, refund_address)
+        Self::__lz_send(env, dst_eid, message, options, sender, fee, refund_address)
     }
 
-    pub fn pay_native_fee(env: &Env, payer: &Address, native_fee: i128) {
-        payer.require_auth();
-        Self::pay_native(env, payer, native_fee)
+    pub fn pay_native_fee(env: &Env, fee_payer: &Address, native_fee: i128) {
+        fee_payer.require_auth();
+        Self::__pay_native(env, fee_payer, native_fee)
     }
 
-    pub fn pay_zro_fee(env: &Env, payer: &Address, zro_fee: i128) {
-        payer.require_auth();
-        Self::pay_zro(env, payer, zro_fee)
+    pub fn pay_zro_fee(env: &Env, fee_payer: &Address, zro_fee: i128) {
+        fee_payer.require_auth();
+        Self::__pay_zro(env, fee_payer, zro_fee)
     }
 }