@layerzerolabs/protocol-stellar-v2 0.2.15 → 0.2.19

package/contracts/oapps/oapp/src/macro_tests/test_macros.rs

@@ -5,20 +5,21 @@ mod test_full_default {
     extern crate self as oapp;
 
     use endpoint_v2::Origin;
+    use oapp::oapp_receiver::LzReceiveInternal;
     use oapp_macros::oapp;
     use soroban_sdk::{Address, Bytes, BytesN, Env};
 
     #[oapp]
     struct TestFullDefault;
 
-    impl TestFullDefault {
+    impl LzReceiveInternal for TestFullDefault {
         fn __lz_receive(
             _env: &Env,
-            _executor: &Address,
             _origin: &Origin,
             _guid: &BytesN<32>,
             _message: &Bytes,
             _extra_data: &Bytes,
+            _executor: &Address,
             _value: i128,
         ) {
             // Default behavior
@@ -34,11 +35,11 @@ mod test_full_manual_core {
 
     use endpoint_v2::Origin;
     use oapp::oapp_core::OAppCore;
-    use oapp_macros::{oapp, oapp_manual_impl};
+    use oapp::oapp_receiver::LzReceiveInternal;
+    use oapp_macros::oapp;
     use soroban_sdk::{contractimpl, Address, Bytes, BytesN, Env};
 
-    #[oapp]
-    #[oapp_manual_impl(core)]
+    #[oapp(custom = [core])]
     struct TestFullManualCore;
 
     #[contractimpl(contracttrait)]
@@ -48,14 +49,14 @@ mod test_full_manual_core {
         }
     }
 
-    impl TestFullManualCore {
+    impl LzReceiveInternal for TestFullManualCore {
         fn __lz_receive(
             _env: &Env,
-            _executor: &Address,
             _origin: &Origin,
             _guid: &BytesN<32>,
             _message: &Bytes,
             _extra_data: &Bytes,
+            _executor: &Address,
             _value: i128,
         ) {
             // Custom logic
@@ -70,26 +71,26 @@ mod test_full_manual_sender {
     extern crate self as oapp;
 
     use endpoint_v2::Origin;
-    use oapp::oapp_sender::OAppSender;
-    use oapp_macros::{oapp, oapp_manual_impl};
+    use oapp::oapp_receiver::LzReceiveInternal;
+    use oapp::oapp_sender::OAppSenderInternal;
+    use oapp_macros::oapp;
     use soroban_sdk::{Address, Bytes, BytesN, Env};
 
-    #[oapp]
-    #[oapp_manual_impl(sender)]
+    #[oapp(custom = [sender])]
     struct TestFullManualSender;
 
-    impl OAppSender for TestFullManualSender {
+    impl OAppSenderInternal for TestFullManualSender {
         // Custom sender implementation
     }
 
-    impl TestFullManualSender {
+    impl LzReceiveInternal for TestFullManualSender {
         fn __lz_receive(
             _env: &Env,
-            _executor: &Address,
             _origin: &Origin,
             _guid: &BytesN<32>,
             _message: &Bytes,
             _extra_data: &Bytes,
+            _executor: &Address,
             _value: i128,
         ) {
             // Implementation
@@ -104,14 +105,27 @@ mod test_full_manual_receiver {
     extern crate self as oapp;
 
     use endpoint_v2::Origin;
-    use oapp::oapp_receiver::OAppReceiver;
-    use oapp_macros::{oapp, oapp_manual_impl};
+    use oapp::oapp_receiver::{LzReceiveInternal, OAppReceiver};
+    use oapp_macros::oapp;
     use soroban_sdk::{contractimpl, Address, Bytes, BytesN, Env};
 
-    #[oapp]
-    #[oapp_manual_impl(receiver)]
+    #[oapp(custom = [receiver])]
     struct TestFullManualReceiver;
 
+    impl LzReceiveInternal for TestFullManualReceiver {
+        fn __lz_receive(
+            _env: &Env,
+            _origin: &Origin,
+            _guid: &BytesN<32>,
+            _message: &Bytes,
+            _extra_data: &Bytes,
+            _executor: &Address,
+            _value: i128,
+        ) {
+            // Custom implementation
+        }
+    }
+
     #[contractimpl(contracttrait)]
     impl OAppReceiver for TestFullManualReceiver {
         fn is_compose_msg_sender(_env: &Env, _origin: &Origin, _message: &Bytes, _sender: &Address) -> bool {
@@ -125,18 +139,6 @@ mod test_full_manual_receiver {
         fn next_nonce(_env: &Env, _src_eid: u32, _sender: &BytesN<32>) -> u64 {
             1 // Ordered delivery
         }
-
-        fn lz_receive(
-            _env: &Env,
-            _executor: &Address,
-            _origin: &Origin,
-            _guid: &BytesN<32>,
-            _message: &Bytes,
-            _extra_data: &Bytes,
-            _value: i128,
-        ) {
-            // Custom implementation - verify_and_clear_payload must be called manually
-        }
     }
 }
 
@@ -148,21 +150,21 @@ mod test_full_manual_options {
 
     use endpoint_v2::Origin;
     use oapp::oapp_options_type3::{EnforcedOptionParam, OAppOptionsType3};
-    use oapp_macros::{oapp, oapp_manual_impl};
+    use oapp::oapp_receiver::LzReceiveInternal;
+    use oapp_macros::oapp;
     use soroban_sdk::{contractimpl, Address, Bytes, BytesN, Env, Vec};
 
-    #[oapp]
-    #[oapp_manual_impl(options_type3)]
+    #[oapp(custom = [options_type3])]
     struct TestFullManualOptions;
 
-    impl TestFullManualOptions {
+    impl LzReceiveInternal for TestFullManualOptions {
         fn __lz_receive(
             _env: &Env,
-            _executor: &Address,
             _origin: &Origin,
             _guid: &BytesN<32>,
             _message: &Bytes,
             _extra_data: &Bytes,
+            _executor: &Address,
             _value: i128,
         ) {
             // Implementation
@@ -182,12 +184,11 @@ mod test_full_manual_core_sender {
     extern crate self as oapp;
 
     use endpoint_v2::Origin;
-    use oapp::{oapp_core::OAppCore, oapp_sender::OAppSender};
-    use oapp_macros::{oapp, oapp_manual_impl};
+    use oapp::{oapp_core::OAppCore, oapp_receiver::LzReceiveInternal, oapp_sender::OAppSenderInternal};
+    use oapp_macros::oapp;
     use soroban_sdk::{contractimpl, Address, Bytes, BytesN, Env};
 
-    #[oapp]
-    #[oapp_manual_impl(core, sender)]
+    #[oapp(custom = [core, sender])]
     struct TestFullManualCoreSender;
 
     #[contractimpl(contracttrait)]
@@ -197,18 +198,18 @@ mod test_full_manual_core_sender {
         }
     }
 
-    impl OAppSender for TestFullManualCoreSender {
+    impl OAppSenderInternal for TestFullManualCoreSender {
         // Custom sender implementation
     }
 
-    impl TestFullManualCoreSender {
+    impl LzReceiveInternal for TestFullManualCoreSender {
         fn __lz_receive(
             _env: &Env,
-            _executor: &Address,
             _origin: &Origin,
             _guid: &BytesN<32>,
             _message: &Bytes,
             _extra_data: &Bytes,
+            _executor: &Address,
             _value: i128,
         ) {
             // Implementation
@@ -223,12 +224,14 @@ mod test_full_manual_core_receiver {
     extern crate self as oapp;
 
     use endpoint_v2::Origin;
-    use oapp::{oapp_core::OAppCore, oapp_receiver::OAppReceiver};
-    use oapp_macros::{oapp, oapp_manual_impl};
+    use oapp::{
+        oapp_core::OAppCore,
+        oapp_receiver::{LzReceiveInternal, OAppReceiver},
+    };
+    use oapp_macros::oapp;
     use soroban_sdk::{contractimpl, Address, Bytes, BytesN, Env};
 
-    #[oapp]
-    #[oapp_manual_impl(core, receiver)]
+    #[oapp(custom = [core, receiver])]
     struct TestFullManualCoreReceiver;
 
     #[contractimpl(contracttrait)]
@@ -238,20 +241,22 @@ mod test_full_manual_core_receiver {
         }
     }
 
-    #[contractimpl(contracttrait)]
-    impl OAppReceiver for TestFullManualCoreReceiver {
-        fn lz_receive(
+    impl LzReceiveInternal for TestFullManualCoreReceiver {
+        fn __lz_receive(
             _env: &Env,
-            _executor: &Address,
             _origin: &Origin,
             _guid: &BytesN<32>,
             _message: &Bytes,
             _extra_data: &Bytes,
+            _executor: &Address,
             _value: i128,
         ) {
             // Custom receiver implementation
         }
     }
+
+    #[contractimpl(contracttrait)]
+    impl OAppReceiver for TestFullManualCoreReceiver {}
 }
 
 // ============================================================================
@@ -261,32 +266,36 @@ mod test_full_manual_sender_receiver {
     extern crate self as oapp;
 
     use endpoint_v2::Origin;
-    use oapp::{oapp_receiver::OAppReceiver, oapp_sender::OAppSender};
-    use oapp_macros::{oapp, oapp_manual_impl};
+    use oapp::{
+        oapp_receiver::{LzReceiveInternal, OAppReceiver},
+        oapp_sender::OAppSenderInternal,
+    };
+    use oapp_macros::oapp;
     use soroban_sdk::{contractimpl, Address, Bytes, BytesN, Env};
 
-    #[oapp]
-    #[oapp_manual_impl(sender, receiver)]
+    #[oapp(custom = [sender, receiver])]
     struct TestFullManualSenderReceiver;
 
-    impl OAppSender for TestFullManualSenderReceiver {
+    impl OAppSenderInternal for TestFullManualSenderReceiver {
         // Custom sender implementation
     }
 
-    #[contractimpl(contracttrait)]
-    impl OAppReceiver for TestFullManualSenderReceiver {
-        fn lz_receive(
+    impl LzReceiveInternal for TestFullManualSenderReceiver {
+        fn __lz_receive(
             _env: &Env,
-            _executor: &Address,
             _origin: &Origin,
             _guid: &BytesN<32>,
             _message: &Bytes,
             _extra_data: &Bytes,
+            _executor: &Address,
             _value: i128,
         ) {
             // Custom receiver implementation
         }
     }
+
+    #[contractimpl(contracttrait)]
+    impl OAppReceiver for TestFullManualSenderReceiver {}
 }
 
 // ============================================================================
@@ -296,12 +305,15 @@ mod test_full_manual_all_except_options {
     extern crate self as oapp;
 
     use endpoint_v2::Origin;
-    use oapp::{oapp_core::OAppCore, oapp_receiver::OAppReceiver, oapp_sender::OAppSender};
-    use oapp_macros::{oapp, oapp_manual_impl};
+    use oapp::{
+        oapp_core::OAppCore,
+        oapp_receiver::{LzReceiveInternal, OAppReceiver},
+        oapp_sender::OAppSenderInternal,
+    };
+    use oapp_macros::oapp;
     use soroban_sdk::{contractimpl, Address, Bytes, BytesN, Env};
 
-    #[oapp]
-    #[oapp_manual_impl(core, sender, receiver)]
+    #[oapp(custom = [core, sender, receiver])]
     struct TestFullManualAllExceptOptions;
 
     #[contractimpl(contracttrait)]
@@ -311,24 +323,26 @@ mod test_full_manual_all_except_options {
         }
     }
 
-    impl OAppSender for TestFullManualAllExceptOptions {
+    impl OAppSenderInternal for TestFullManualAllExceptOptions {
         // Custom sender implementation
     }
 
-    #[contractimpl(contracttrait)]
-    impl OAppReceiver for TestFullManualAllExceptOptions {
-        fn lz_receive(
+    impl LzReceiveInternal for TestFullManualAllExceptOptions {
+        fn __lz_receive(
             _env: &Env,
-            _executor: &Address,
             _origin: &Origin,
             _guid: &BytesN<32>,
             _message: &Bytes,
             _extra_data: &Bytes,
+            _executor: &Address,
             _value: i128,
         ) {
             // Custom receiver implementation
         }
     }
+
+    #[contractimpl(contracttrait)]
+    impl OAppReceiver for TestFullManualAllExceptOptions {}
 }
 
 // ============================================================================
@@ -341,14 +355,13 @@ mod test_full_manual_all {
     use oapp::{
         oapp_core::OAppCore,
         oapp_options_type3::{EnforcedOptionParam, OAppOptionsType3},
-        oapp_receiver::OAppReceiver,
-        oapp_sender::OAppSender,
+        oapp_receiver::{LzReceiveInternal, OAppReceiver},
+        oapp_sender::OAppSenderInternal,
     };
-    use oapp_macros::{oapp, oapp_manual_impl};
+    use oapp_macros::oapp;
     use soroban_sdk::{contractimpl, Address, Bytes, BytesN, Env, Vec};
 
-    #[oapp]
-    #[oapp_manual_impl(core, sender, receiver, options_type3)]
+    #[oapp(custom = [core, sender, receiver, options_type3])]
     struct TestFullManualAll;
 
     #[contractimpl(contracttrait)]
@@ -358,25 +371,27 @@ mod test_full_manual_all {
         }
     }
 
-    impl OAppSender for TestFullManualAll {
+    impl OAppSenderInternal for TestFullManualAll {
         // Custom sender implementation
     }
 
-    #[contractimpl(contracttrait)]
-    impl OAppReceiver for TestFullManualAll {
-        fn lz_receive(
+    impl LzReceiveInternal for TestFullManualAll {
+        fn __lz_receive(
             _env: &Env,
-            _executor: &Address,
             _origin: &Origin,
             _guid: &BytesN<32>,
             _message: &Bytes,
             _extra_data: &Bytes,
+            _executor: &Address,
             _value: i128,
         ) {
             // Custom receiver implementation
         }
     }
 
+    #[contractimpl(contracttrait)]
+    impl OAppReceiver for TestFullManualAll {}
+
     #[contractimpl(contracttrait)]
     impl OAppOptionsType3 for TestFullManualAll {
         // Custom options implementation

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

@@ -1,10 +1,19 @@
-use common_macros::{only_owner, storage};
+use common_macros::{contract_trait, only_auth, storage};
 use endpoint_v2::LayerZeroEndpointV2Client;
-use soroban_sdk::{contractevent, contracttrait, Address, BytesN, Env};
-use utils::ownable::Ownable;
-use utils::ownable::OwnableInitializer;
+use soroban_sdk::{contractevent, Address, BytesN, Env};
+use utils::ownable::{Ownable, OwnableInitializer};
 
-pub fn oapp_initialize<T: OAppCore + OwnableInitializer>(
+/// Initializes the OApp with the specified configuration.
+///
+/// This function sets up the OApp by initializing ownership, storing the LayerZero endpoint,
+/// and optionally setting a delegate address for the endpoint.
+///
+/// # Arguments
+/// * `env` - The Soroban environment
+/// * `owner` - The address that will own this OApp
+/// * `endpoint` - The LayerZero endpoint address to associate with this OApp
+/// * `delegate` - Optional delegate address to set on the endpoint for this OApp
+pub fn initialize_oapp<T: OAppCore + OwnableInitializer>(
     env: &Env,
     owner: &Address,
     endpoint: &Address,
@@ -12,17 +21,16 @@ pub fn oapp_initialize<T: OAppCore + OwnableInitializer>(
 ) {
     T::init_owner(env, owner);
     OAppCoreStorage::set_endpoint(env, endpoint);
-
-    let endpoint_client = endpoint_v2::LayerZeroEndpointV2Client::new(env, endpoint);
-    endpoint_client.set_delegate(&env.current_contract_address(), delegate);
+    LayerZeroEndpointV2Client::new(env, endpoint).set_delegate(&env.current_contract_address(), delegate);
 }
 
 // =====================================================
-// OAppCore Storage, Events, and Interface
+// OAppCore Storage and Events
 // =====================================================
 
 #[storage]
 pub enum OAppCoreStorage {
+    // Immutable endpoint address
     #[instance(Address)]
     Endpoint,
 
@@ -37,22 +45,26 @@ pub struct PeerSet {
     pub peer: Option<BytesN<32>>,
 }
 
-#[contracttrait(client_name = "OAppCoreClient")]
-pub trait OAppCore: Ownable + Sized {
+// =====================================================
+// OAppCore Interface and Default Implementation
+// =====================================================
+
+#[contract_trait]
+pub trait OAppCore: Ownable {
     /// Retrieves the OApp version information.
     ///
     /// # Returns
     /// A tuple containing:
-    /// - `sender_version`: The version of the OAppSender implementation
-    /// - `receiver_version`: The version of the OAppReceiver implementation
+    /// - `sender_version`: The version of the OAppSender
+    /// - `receiver_version`: The version of the OAppReceiver
     fn oapp_version(_env: &Env) -> (u64, u64) {
-        (0, 0)
+        (1, 1)
     }
 
-    /// Retrieves the LayerZero endpoint associated with the OApp.
+    /// Retrieves the LayerZero endpoint address associated with the OApp.
     ///
     /// # Returns
-    /// The LayerZero endpoint client
+    /// The LayerZero endpoint address
     fn endpoint(env: &Env) -> Address {
         OAppCoreStorage::endpoint(env).unwrap()
     }
@@ -73,7 +85,7 @@ pub trait OAppCore: Ownable + Sized {
     /// # Arguments
     /// * `eid` - The endpoint ID
     /// * `peer` - The address of the peer to be associated with the corresponding endpoint, or None to remove the peer
-    #[only_owner]
+    #[only_auth]
     fn set_peer(env: &Env, eid: u32, peer: &Option<BytesN<32>>) {
         OAppCoreStorage::set_or_remove_peer(env, eid, peer);
         PeerSet { eid, peer: peer.clone() }.publish(env);
@@ -83,10 +95,13 @@ pub trait OAppCore: Ownable + Sized {
     ///
     /// # Arguments
     /// * `delegate` - The address of the delegate to be set, or None to remove the delegate
-    #[only_owner]
+    #[only_auth]
     fn set_delegate(env: &Env, delegate: &Option<Address>) {
-        let endpoint = Self::endpoint(env);
-        let endpoint_client = LayerZeroEndpointV2Client::new(env, &endpoint);
-        endpoint_client.set_delegate(&env.current_contract_address(), delegate);
+        endpoint_client::<Self>(env).set_delegate(&env.current_contract_address(), delegate);
     }
 }
+
+/// Returns a client for the LayerZero endpoint.
+pub fn endpoint_client<'a, T: OAppCore>(env: &'a Env) -> LayerZeroEndpointV2Client<'a> {
+    LayerZeroEndpointV2Client::new(env, &T::endpoint(env))
+}

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

@@ -1,9 +1,9 @@
 use crate::errors::OAppError;
-use common_macros::{only_owner, storage};
-use soroban_sdk::{assert_with_error, contractevent, contracttrait, contracttype, panic_with_error, Bytes, Env, Vec};
-use utils::ownable::Ownable;
+use common_macros::{contract_trait, only_auth, storage};
+use soroban_sdk::{assert_with_error, contractevent, contracttype, panic_with_error, Bytes, Env, Vec};
+use utils::{buffer_reader::BufferReader, ownable::Ownable};
 
-pub const OPTION_TYPE3: u32 = 3;
+pub const OPTION_TYPE3: u16 = 3;
 
 #[contracttype]
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -30,13 +30,31 @@ pub struct EnforcedOptionSet {
 // OAppOptionsType3 Trait and Default Implementation
 // =========================================================================
 
-#[contracttrait(client_name = "OAppOptionsType3Client")]
-pub trait OAppOptionsType3: Ownable + Sized {
+#[contract_trait]
+pub trait OAppOptionsType3: Ownable {
+    /// Retrieves the enforced options for a given endpoint and message type.
+    ///
+    /// # Arguments
+    /// * `eid` - The endpoint ID
+    /// * `msg_type` - The OApp message type
+    ///
+    /// # Returns
+    /// The enforced options for the given endpoint and message type
     fn enforced_options(env: &Env, eid: u32, msg_type: u32) -> Bytes {
         OAppOptionsType3Storage::enforced_options(env, eid, msg_type)
     }
 
-    #[only_owner]
+    /// Sets the enforced options for specific endpoint and message type combinations.
+    ///
+    /// Only the `authorizer` of the OApp can call this function.
+    /// Provides a way for the OApp to enforce things like paying for PreCrime, AND/OR minimum dst lzReceive gas amounts etc.
+    /// These enforced options can vary as the potential options/execution on the remote may differ as per the msg_type.
+    /// e.g. Amount of lzReceive() gas necessary to deliver a lzCompose() message adds overhead you don't want to pay
+    /// if you are only making a standard LayerZero message ie. lzReceive() WITHOUT sendCompose().
+    ///
+    /// # Arguments
+    /// * `options` - A vector of EnforcedOptionParam structures specifying enforced options
+    #[only_auth]
     fn set_enforced_options(env: &Env, options: Vec<EnforcedOptionParam>) {
         for option in &options {
             assert_option_type3(env, &option.options);
@@ -45,6 +63,20 @@ pub trait OAppOptionsType3: Ownable + Sized {
         EnforcedOptionSet { enforced_option_params: options }.publish(env);
     }
 
+    /// Combines options for a given endpoint and message type.
+    ///
+    /// If there is an enforced lzReceive option:
+    /// - {gas_limit: 200k, value: 1 XLM} AND a caller supplies a lzReceive option: {gas_limit: 100k, value: 0.5 XLM}
+    /// - The resulting options will be {gas_limit: 300k, value: 1.5 XLM} when the message is executed on the remote lz_receive() function.
+    /// The presence of duplicated options is handled off-chain in the verifier/executor.
+    ///
+    /// # Arguments
+    /// * `eid` - The endpoint ID
+    /// * `msg_type` - The OApp message type
+    /// * `extra_options` - Additional options passed by the caller
+    ///
+    /// # Returns
+    /// The combination of caller specified options AND enforced options
     fn combine_options(env: &Env, eid: u32, msg_type: u32, extra_options: &Bytes) -> Bytes {
         let mut enforced_options = Self::enforced_options(env, eid, msg_type);
 
@@ -71,10 +103,14 @@ pub trait OAppOptionsType3: Ownable + Sized {
 // Helpers Functions
 // =========================================================================
 
+/// Asserts that the provided options are of type 3.
+///
+/// # Arguments
+/// * `options` - The options to be checked
+///
+/// # Panics
+/// If the options are not of type 3
 pub fn assert_option_type3(env: &Env, options: &Bytes) {
-    let mut options_version_bytes = [0u8; 2];
-    options.slice(0..2).copy_into_slice(&mut options_version_bytes);
-    let options_version = u16::from_be_bytes(options_version_bytes);
-
-    assert_with_error!(env, options_version as u32 == OPTION_TYPE3, OAppError::InvalidOptions);
+    let options_type = BufferReader::new(options).read_u16();
+    assert_with_error!(env, options_type == OPTION_TYPE3, OAppError::InvalidOptions);
 }