@layerzerolabs/oapp-stellar-contracts 0.2.122

package/src/oapp_receiver.rs

@@ -0,0 +1,195 @@
+use crate::{
+    errors::OAppError,
+    oapp_core::{endpoint_client, get_peer_or_panic, OAppCore},
+};
+use common_macros::contract_trait;
+use endpoint_v2::Origin;
+use soroban_sdk::{assert_with_error, token::TokenClient, Address, Bytes, BytesN, Env};
+
+/// The version of the OAppReceiver implementation.
+/// Version is bumped when changes are made to this contract.
+pub const RECEIVER_VERSION: u64 = 1;
+
+// =====================================================
+// 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
+// =====================================================
+
+/// Receiver trait for OApps that accept cross-chain messages from LayerZero.
+///
+/// Mirrors `ILayerZeroReceiver` function signatures, allowing the executor to call
+/// these methods via `LayerZeroReceiverClient`.
+///
+/// # Default Implementations
+/// | 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
+///
+/// ```ignore
+/// use oapp::oapp_receiver::LzReceiveInternal;
+///
+/// #[common_macros::lz_contract]
+/// #[oapp_macros::oapp]
+/// pub struct MyOApp;
+///
+/// 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
+///     }
+/// }
+/// ```
+///
+/// # 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
+    /// * `origin` - The origin of the message
+    ///
+    /// # Returns
+    /// True if the path can be initialized, false otherwise
+    fn allow_initialize_path(env: &soroban_sdk::Env, origin: &endpoint_v2::Origin) -> bool {
+        let peer = Self::peer(env, origin.src_eid);
+        peer.is_some_and(|peer| peer == origin.sender)
+    }
+
+    /// 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: &soroban_sdk::Env, _src_eid: u32, _sender: &soroban_sdk::BytesN<32>) -> u64 {
+        0
+    }
+
+    /// 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 address of the executor for the received message
+    /// * `origin` - The origin information containing the source endpoint and sender address:
+    ///   - `src_eid`: The source 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: &soroban_sdk::Env,
+        executor: &soroban_sdk::Address,
+        origin: &endpoint_v2::Origin,
+        guid: &soroban_sdk::BytesN<32>,
+        message: &soroban_sdk::Bytes,
+        extra_data: &soroban_sdk::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.
+    ///
+    /// Applications can optionally choose to implement separate composeMsg senders that are NOT the bridging layer.
+    /// The default sender IS the OAppReceiver implementer.
+    ///
+    /// # Arguments
+    /// * `origin` - The origin information containing the source endpoint and sender address
+    /// * `message` - The lzReceive payload
+    /// * `sender` - The sender address to check
+    ///
+    /// # Returns
+    /// True if the sender is a valid composeMsg sender, false otherwise
+    fn is_compose_msg_sender(
+        env: &soroban_sdk::Env,
+        _origin: &endpoint_v2::Origin,
+        _message: &soroban_sdk::Bytes,
+        sender: &soroban_sdk::Address,
+    ) -> bool {
+        env.current_contract_address() == *sender
+    }
+}
+
+// =====================================================
+// Helper functions
+// =====================================================
+
+/// 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,
+    guid: &BytesN<32>,
+    message: &Bytes,
+    value: i128,
+) {
+    // Require authorization from the executor and transfer the value from the executor to the oapp if has value
+    executor.require_auth();
+    // Assert that the message is from the expected peer
+    assert_with_error!(env, get_peer_or_panic::<T>(env, origin.src_eid) == origin.sender, OAppError::OnlyPeer);
+
+    let this_address = env.current_contract_address();
+    let endpoint_client = endpoint_client::<T>(env);
+
+    // Transfer the value from the executor to the oapp if has value
+    if value != 0 {
+        let token_client = TokenClient::new(env, &endpoint_client.native_token());
+        token_client.transfer(executor, &this_address, &value);
+    }
+
+    // Clear the message payload from the endpoint
+    endpoint_client.clear(&this_address, origin, &this_address, guid, message);
+}

package/src/oapp_sender.rs

@@ -0,0 +1,152 @@
+use crate::{
+    errors::OAppError,
+    oapp_core::{endpoint_client, get_peer_or_panic, OAppCore},
+};
+use endpoint_v2::{MessagingFee, MessagingParams, MessagingReceipt};
+use soroban_sdk::{contracttype, token::TokenClient, Address, Bytes, Env};
+use utils::option_ext::OptionExt;
+
+/// The version of the OAppSender implementation.
+/// Version is bumped when changes are made to this contract.
+pub const SENDER_VERSION: u64 = 1;
+
+/// Represents a fee payer address with explicit authorization state.
+///
+/// This enum forces callers of `__lz_send` to explicitly declare whether
+/// `require_auth()` has already been called for the fee payer address.
+/// This prevents the common mistake of forgetting to authorize the fee payer.
+///
+/// # Variants
+/// - `Unverified` — Safe default. `__lz_send` will call `require_auth()` on the address.
+///   Use this when the caller has **not** already authorized the fee payer.
+/// - `Verified` — Caller asserts that `require_auth()` has already been called.
+///   Use this to avoid a duplicate `require_auth()` node in the Soroban auth tree
+///   (e.g., when the same address was already authorized as the message sender).
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum FeePayer {
+    /// The fee payer has **not** been authorized yet.
+    /// `__lz_send` will call `fee_payer.require_auth()` before transferring fees.
+    /// This is the safe default — use this if unsure.
+    Unverified(Address),
+
+    /// The fee payer has **already** been authorized by the caller via `require_auth()`.
+    /// `__lz_send` will skip the auth check to avoid creating a duplicate auth node
+    /// in the Soroban authorization tree.
+    ///
+    /// # Safety
+    /// Only use this variant if you have already called `require_auth()` on this address
+    /// in the current contract invocation. Misuse may allow unauthorized fee deductions.
+    Verified(Address),
+}
+
+impl FeePayer {
+    /// Returns a reference to the underlying address.
+    pub fn address(&self) -> &Address {
+        match self {
+            FeePayer::Unverified(addr) | FeePayer::Verified(addr) => addr,
+        }
+    }
+}
+
+/// A helper trait for sending cross-chain messages via LayerZero.
+///
+/// Contracts should implement this trait to gain access to the `__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.
+///
+/// # Important
+/// This trait is intended to be used as an **internal helper** only. Do **NOT** expose these
+/// methods as part of your contract's public interface (i.e., do not use `#[contract_impl]` on
+/// the implementation of this trait). Instead, call these methods internally from your
+/// contract's own public functions.
+pub trait OAppSenderInternal: OAppCore {
+    /// Quote the messaging fee for sending a message to the other chain
+    ///
+    /// # Arguments
+    /// * `dst_eid`: The destination endpoint ID
+    /// * `message`: The message to send
+    /// * `options`: The options for the message
+    /// * `pay_in_zro`: Whether to pay the fee in ZRO
+    ///
+    /// # Returns
+    /// * `MessagingFee`: The messaging fee for the message
+    fn __quote(env: &Env, dst_eid: u32, message: &Bytes, options: &Bytes, pay_in_zro: bool) -> MessagingFee {
+        let receiver = get_peer_or_panic::<Self>(env, dst_eid);
+        endpoint_client::<Self>(env).quote(
+            &env.current_contract_address(),
+            &MessagingParams { dst_eid, receiver, message: message.clone(), options: options.clone(), pay_in_zro },
+        )
+    }
+
+    /// Send a message to the other chain
+    ///
+    /// # Arguments
+    /// * `dst_eid`: The destination endpoint ID
+    /// * `message`: The message to send
+    /// * `options`: The options for the message
+    /// * `fee_payer`: The fee payer, wrapped in [`FeePayer`] to indicate authorization state.
+    ///   Use `FeePayer::Unverified(addr)` if auth has not been checked (safe default),
+    ///   or `FeePayer::Verified(addr)` if `addr.require_auth()` was already called by the caller.
+    /// * `fee`: The messaging fee
+    /// * `refund_address`: The address to receive any excess fees
+    ///
+    /// # Returns
+    /// * `MessagingReceipt`: The receipt for the sent message
+    fn __lz_send(
+        env: &Env,
+        dst_eid: u32,
+        message: &Bytes,
+        options: &Bytes,
+        fee_payer: &FeePayer,
+        fee: &MessagingFee,
+        refund_address: &Address,
+    ) -> MessagingReceipt {
+        // Enforce fee payer authorization if not already verified by the caller
+        let payer = match fee_payer {
+            FeePayer::Unverified(addr) => {
+                addr.require_auth();
+                addr
+            }
+            FeePayer::Verified(addr) => addr,
+        };
+
+        // Pay the messaging fees
+        Self::__pay_native(env, payer, fee.native_fee);
+        // Skip the ZRO payment call only when the fee is exactly zero. Using `!= 0` instead of
+        // `> 0` so that an invalid negative value still reaches `__pay_zro` and fails loudly
+        // rather than being silently ignored.
+        let pay_in_zro = fee.zro_fee != 0;
+        if pay_in_zro {
+            Self::__pay_zro(env, payer, fee.zro_fee);
+        }
+
+        // Send the message to the other chain
+        let receiver = get_peer_or_panic::<Self>(env, dst_eid);
+        endpoint_client::<Self>(env).send(
+            &env.current_contract_address(),
+            &MessagingParams { dst_eid, receiver, message: message.clone(), options: options.clone(), pay_in_zro },
+            refund_address,
+        )
+    }
+
+    /// Pay the native fee to the endpoint for sending a message to the other chain
+    ///
+    /// # Arguments
+    /// * `fee_payer`: The address of the fee payer
+    /// * `native_fee`: The native fee to pay
+    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
+    /// * `fee_payer`: The address of the fee payer
+    /// * `zro_fee`: The ZRO fee to pay
+    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/src/tests/mod.rs

@@ -0,0 +1,5 @@
+mod oapp_core;
+mod oapp_options_type3;
+mod oapp_receiver;
+mod oapp_sender;
+mod test_macros;

package/src/tests/oapp_core.rs

@@ -0,0 +1,225 @@
+use crate::{self as oapp, oapp_core::PeerSet, oapp_receiver::LzReceiveInternal};
+use endpoint_v2::Origin;
+use soroban_sdk::{
+    contract, contractimpl, contracttype,
+    testutils::{Address as _, MockAuth, MockAuthInvoke},
+    Address, Bytes, BytesN, Env, IntoVal,
+};
+use utils::testing_utils::assert_eq_event;
+
+#[contract]
+pub struct DummyEndpoint;
+
+#[derive(Clone)]
+#[contracttype]
+enum DummyEndpointDataKey {
+    Delegate(Address),
+}
+
+#[contractimpl]
+impl DummyEndpoint {
+    pub fn set_delegate(env: Env, oapp: &Address, delegate: &Option<Address>) {
+        let key = DummyEndpointDataKey::Delegate(oapp.clone());
+        match delegate {
+            Some(d) => env.storage().persistent().set(&key, d),
+            None => env.storage().persistent().remove(&key),
+        }
+    }
+
+    pub fn get_delegate(env: Env, oapp: Address) -> Option<Address> {
+        env.storage().persistent().get(&DummyEndpointDataKey::Delegate(oapp))
+    }
+}
+
+#[oapp_macros::oapp]
+#[common_macros::lz_contract]
+pub struct DummyOApp;
+
+impl LzReceiveInternal for DummyOApp {
+    fn __lz_receive(
+        _env: &Env,
+        _origin: &Origin,
+        _guid: &BytesN<32>,
+        _message: &Bytes,
+        _extra_data: &Bytes,
+        _executor: &Address,
+        _value: i128,
+    ) {
+        // Not used in core tests
+    }
+}
+
+#[contractimpl]
+impl DummyOApp {
+    pub fn __constructor(env: &Env, owner: &Address, endpoint: &Address) {
+        oapp::oapp_core::init_ownable_oapp::<Self>(env, owner, endpoint, owner);
+    }
+}
+
+const REMOTE_EID: u32 = 100;
+const UNSET_EID: u32 = 999;
+
+struct TestSetup<'a> {
+    env: Env,
+    owner: Address,
+    endpoint: Address,
+    oapp_client: DummyOAppClient<'a>,
+}
+
+fn setup<'a>() -> TestSetup<'a> {
+    let env = Env::default();
+
+    let owner = Address::generate(&env);
+    soroban_sdk::log!(&env, "owner: {}", owner);
+    let endpoint = env.register(DummyEndpoint, ());
+    soroban_sdk::log!(&env, "endpoint: {}", endpoint);
+    let oapp = env.register(DummyOApp, (&owner, &endpoint));
+    soroban_sdk::log!(&env, "oapp: {}", oapp);
+    let oapp_client = DummyOAppClient::new(&env, &oapp);
+
+    TestSetup { env, owner, endpoint, oapp_client }
+}
+
+fn set_peer_with_auth(
+    env: &Env,
+    signer: &Address,
+    oapp_client: &DummyOAppClient<'_>,
+    eid: u32,
+    peer: &Option<BytesN<32>>,
+) {
+    env.mock_auths(&[MockAuth {
+        address: signer,
+        invoke: &MockAuthInvoke {
+            contract: &oapp_client.address,
+            fn_name: "set_peer",
+            args: (&eid, peer, signer).into_val(env),
+            sub_invokes: &[],
+        },
+    }]);
+    oapp_client.set_peer(&eid, peer, signer);
+}
+
+fn set_delegate_with_auth(env: &Env, signer: &Address, oapp_client: &DummyOAppClient<'_>, delegate: &Option<Address>) {
+    env.mock_auths(&[MockAuth {
+        address: signer,
+        invoke: &MockAuthInvoke {
+            contract: &oapp_client.address,
+            fn_name: "set_delegate",
+            args: (delegate, signer).into_val(env),
+            sub_invokes: &[],
+        },
+    }]);
+    oapp_client.set_delegate(delegate, signer);
+}
+
+#[test]
+fn test_constructor_initializes_owner_and_endpoint_and_delegate() {
+    let TestSetup { env, owner, endpoint, oapp_client } = setup();
+
+    // owner initialized via oapp_initialize -> init_owner
+    assert_eq!(Some(owner.clone()), oapp_client.owner());
+
+    // endpoint stored via OAppCoreStorage::set_endpoint
+    assert_eq!(endpoint, oapp_client.endpoint());
+
+    // delegate set via oapp_initialize(..., owner) -> endpoint.set_delegate(..., Some(owner))
+    let endpoint_client = DummyEndpointClient::new(&env, &endpoint);
+    assert_eq!(Some(owner), endpoint_client.get_delegate(&oapp_client.address));
+}
+
+#[test]
+fn test_oapp_version_defaults_to_zero() {
+    let TestSetup { oapp_client, .. } = setup();
+    assert_eq!((1, 1), oapp_client.oapp_version());
+}
+
+#[test]
+fn test_peer_lifecycle_set_get_update_remove_and_events() {
+    let TestSetup { env, owner, oapp_client, .. } = setup();
+
+    // Unset cases
+    assert_eq!(None, oapp_client.peer(&UNSET_EID));
+    assert_eq!(None, oapp_client.peer(&REMOTE_EID));
+
+    // Set peer v1
+    let peer_v1: BytesN<32> = BytesN::from_array(&env, &[33; 32]);
+    let peer_v1_option = Some(peer_v1.clone());
+    set_peer_with_auth(&env, &owner, &oapp_client, REMOTE_EID, &peer_v1_option);
+
+    assert_eq_event(&env, &oapp_client.address, PeerSet { eid: REMOTE_EID, peer: Some(peer_v1.clone()) });
+    assert_eq!(Some(peer_v1), oapp_client.peer(&REMOTE_EID));
+    assert_eq!(None, oapp_client.peer(&UNSET_EID));
+
+    // Update to peer v2
+    let peer_v2: BytesN<32> = BytesN::from_array(&env, &[2; 32]);
+    let peer_v2_option = Some(peer_v2.clone());
+    set_peer_with_auth(&env, &owner, &oapp_client, REMOTE_EID, &peer_v2_option);
+
+    assert_eq_event(&env, &oapp_client.address, PeerSet { eid: REMOTE_EID, peer: Some(peer_v2.clone()) });
+    assert_eq!(Some(peer_v2), oapp_client.peer(&REMOTE_EID));
+
+    // Remove peer
+    let none_peer: Option<BytesN<32>> = None;
+    set_peer_with_auth(&env, &owner, &oapp_client, REMOTE_EID, &none_peer);
+    assert_eq_event(&env, &oapp_client.address, PeerSet { eid: REMOTE_EID, peer: None });
+    assert_eq!(None, oapp_client.peer(&REMOTE_EID));
+}
+
+#[test]
+#[should_panic(expected = "HostError: Error(Auth, InvalidAction)")]
+fn test_set_peer_unauthorized() {
+    let TestSetup { env, owner, oapp_client, .. } = setup();
+
+    let test_peer: BytesN<32> = BytesN::from_array(&env, &[33; 32]);
+    oapp_client.set_peer(&REMOTE_EID, &Some(test_peer), &owner);
+}
+
+#[test]
+#[should_panic(expected = "Error(Contract, #1086)")] // RbacError::Unauthorized
+fn test_set_peer_non_owner_authorized() {
+    let TestSetup { env, owner, oapp_client, .. } = setup();
+    let non_owner = Address::generate(&env);
+    assert!(non_owner != owner);
+
+    let peer: BytesN<32> = BytesN::from_array(&env, &[33; 32]);
+    let peer_option = Some(peer);
+    set_peer_with_auth(&env, &non_owner, &oapp_client, REMOTE_EID, &peer_option);
+}
+
+#[test]
+fn test_set_delegate_updates_and_clears_endpoint_delegate() {
+    let TestSetup { env, owner, endpoint, oapp_client } = setup();
+
+    let delegate = Address::generate(&env);
+    let delegate_option = Some(delegate.clone());
+    set_delegate_with_auth(&env, &owner, &oapp_client, &delegate_option);
+
+    let endpoint_client = DummyEndpointClient::new(&env, &endpoint);
+    assert_eq!(Some(delegate), endpoint_client.get_delegate(&oapp_client.address));
+
+    // Clear delegate
+    let none_delegate: Option<Address> = None;
+    set_delegate_with_auth(&env, &owner, &oapp_client, &none_delegate);
+    assert_eq!(None, endpoint_client.get_delegate(&oapp_client.address));
+}
+
+#[test]
+#[should_panic(expected = "HostError: Error(Auth, InvalidAction)")]
+fn test_set_delegate_unauthorized() {
+    let TestSetup { env, owner, oapp_client, .. } = setup();
+
+    let delegate = Address::generate(&env);
+    oapp_client.set_delegate(&Some(delegate), &owner);
+}
+
+#[test]
+#[should_panic(expected = "Error(Contract, #1086)")] // RbacError::Unauthorized
+fn test_set_delegate_non_owner_authorized() {
+    let TestSetup { env, owner, oapp_client, .. } = setup();
+    let non_owner = Address::generate(&env);
+    assert!(non_owner != owner);
+
+    let delegate = Address::generate(&env);
+    let delegate_option = Some(delegate);
+    set_delegate_with_auth(&env, &non_owner, &oapp_client, &delegate_option);
+}