@layerzerolabs/protocol-stellar-v2 0.2.20 → 0.2.22

package/contracts/oapps/oft-core/src/oft_core.rs

@@ -1,10 +1,9 @@
 //! OFT - traits and implementations for Omnichain Fungible Tokens.
 //!
 //! This module provides:
-//! - `OFTInternal`: Internal methods NOT exposed as contract entrypoints (`__debit`, `__credit`, `__initialize_oft`, etc.)
+//! - `OFTInternal`: Internal methods NOT exposed as contract entrypoints (`__debit`, `__credit`, `__initialize_oft`, `__receive`, etc.)
 //! - `OFTCore`: Public methods exposed as contract entrypoints (using `#[contracttrait]`)
 //! - `impl_oft_lz_receive!`: Macro to implement `LzReceiveInternal` with default OFT receive logic
-//! - Helper functions: `lz_receive` for handling incoming cross-chain transfers
 //!
 //! ## Usage
 //!
@@ -48,14 +47,15 @@ use crate::{
     self as oft_core,
     codec::{oft_compose_msg_codec::OFTComposeMsg, oft_msg_codec::OFTMessage},
     errors::OFTError,
-    events::{self, OFTSent},
+    events::{self, MsgInspectorSet, OFTSent},
     storage::OFTStorage,
     types::{self, OFTFeeDetail, OFTLimit, OFTReceipt, SendParam},
     utils as oft_utils,
 };
-use common_macros::contract_trait;
+use common_macros::{contract_trait, only_auth};
 use endpoint_v2::{MessagingComposerClient, MessagingFee, MessagingReceipt};
 use oapp::{
+    interfaces::OAppMsgInspectorClient,
     oapp_core::{initialize_oapp, OAppCore},
     oapp_options_type3::OAppOptionsType3,
     oapp_receiver::OAppReceiver,
@@ -120,7 +120,7 @@ pub trait OFTInternal: OAppCore + OAppReceiver + OAppSenderInternal + OAppOption
 
         // Initialize OFT storage
         OFTStorage::set_token(env, token);
-        OFTStorage::set_decimal_conversion_rate(env, &10_i128.pow(local_decimals - shared_decimals));
+        OFTStorage::set_decimals_diff(env, &(local_decimals - shared_decimals));
     }
 
     // =========================================================================
@@ -167,6 +167,8 @@ pub trait OFTInternal: OAppCore + OAppReceiver + OAppSenderInternal + OAppOption
     /// # Returns
     /// A tuple of (transfer limits, fee details, estimated receipt)
     fn __quote_oft(env: &Env, send_param: &SendParam) -> (OFTLimit, Vec<OFTFeeDetail>, OFTReceipt) {
+        assert_with_error!(env, send_param.amount_ld >= 0, OFTError::InvalidAmount);
+
         let limit = OFTLimit { min_amount_ld: 0, max_amount_ld: i128::MAX };
         let fee_details = vec![env];
         let oft_receipt = Self::__debit_view(env, send_param.amount_ld, send_param.min_amount_ld, send_param.dst_eid);
@@ -183,6 +185,8 @@ pub trait OFTInternal: OAppCore + OAppReceiver + OAppSenderInternal + OAppOption
     /// # Returns
     /// The messaging fee required for the transfer
     fn __quote_send(env: &Env, from: &Address, send_param: &SendParam, pay_in_zro: bool) -> MessagingFee {
+        assert_with_error!(env, send_param.amount_ld >= 0, OFTError::InvalidAmount);
+
         let OFTReceipt { amount_received_ld, .. } =
             Self::__debit_view(env, send_param.amount_ld, send_param.min_amount_ld, send_param.dst_eid);
 
@@ -214,6 +218,8 @@ pub trait OFTInternal: OAppCore + OAppReceiver + OAppSenderInternal + OAppOption
     ) -> (MessagingReceipt, OFTReceipt) {
         from.require_auth();
 
+        assert_with_error!(env, send_param.amount_ld >= 0, OFTError::InvalidAmount);
+
         let oft_receipt = Self::__debit(env, from, send_param.amount_ld, send_param.min_amount_ld, send_param.dst_eid);
 
         let (msg, options) = Self::__build_msg_and_options(env, from, send_param, oft_receipt.amount_received_ld);
@@ -261,10 +267,13 @@ pub trait OFTInternal: OAppCore + OAppReceiver + OAppSenderInternal + OAppOption
 
     /// Builds OFT message and combines options for cross-chain transfer.
     ///
+    /// If a message inspector is set, it will be called to validate the message and options.
+    /// The inspector should panic if the message or options are invalid.
+    ///
     /// # Arguments
     /// * `from` - The address initiating the transfer
     /// * `send_param` - The send parameters including destination, recipient, and options
-    /// * `receive_amount_ld` - The amount to be received in local decimals (after dust removal)
+    /// * `amount_receive_ld` - The amount to be received in local decimals (after dust removal)
     ///
     /// # Returns
     /// A tuple of (encoded message, combined options)
@@ -272,20 +281,26 @@ pub trait OFTInternal: OAppCore + OAppReceiver + OAppSenderInternal + OAppOption
         env: &Env,
         from: &Address,
         send_param: &SendParam,
-        receive_amount_ld: i128,
+        amount_receive_ld: i128,
     ) -> (Bytes, Bytes) {
         let has_compose = !send_param.compose_msg.is_empty();
         let conversion_rate = Self::__decimal_conversion_rate(env);
         let (msg, _) = OFTMessage {
             send_to: send_param.to.clone(),
-            amount_sd: oft_utils::to_sd(env, receive_amount_ld, conversion_rate),
+            amount_sd: oft_utils::to_sd(env, amount_receive_ld, conversion_rate),
             compose_from: if has_compose { Some(oft_utils::address_payload(from)) } else { None },
             compose_msg: if has_compose { Some(send_param.compose_msg.clone()) } else { None },
         }
         .encode(env);
         let msg_type = if has_compose { types::SEND_AND_CALL } else { types::SEND };
+        let options = Self::combine_options(env, send_param.dst_eid, msg_type, &send_param.extra_options);
+
+        // Optionally inspect message and options if inspector is set
+        if let Some(inspector) = Self::__msg_inspector(env) {
+            OAppMsgInspectorClient::new(env, &inspector).inspect(&env.current_contract_address(), &msg, &options);
+        }
 
-        (msg, Self::combine_options(env, send_param.dst_eid, msg_type, &send_param.extra_options))
+        (msg, options)
     }
 
     // ----- Storage Accessors -----
@@ -297,15 +312,81 @@ pub trait OFTInternal: OAppCore + OAppReceiver + OAppSenderInternal + OAppOption
 
     /// Retrieves the decimal conversion rate used for cross-chain normalization.
     fn __decimal_conversion_rate(env: &Env) -> i128 {
-        OFTStorage::decimal_conversion_rate(env).unwrap_or_panic(env, OFTError::NotInitialized)
+        let decimals_diff = OFTStorage::decimals_diff(env).unwrap_or_panic(env, OFTError::NotInitialized);
+        10_i128.pow(decimals_diff)
     }
 
     /// Retrieves the shared decimals used for cross-chain normalization.
     fn __shared_decimals(env: &Env) -> u32 {
-        let token = Self::__token(env);
-        let local_decimals = TokenClient::new(env, &token).decimals();
+        let local_decimals = TokenClient::new(env, &Self::__token(env)).decimals();
+        let decimals_diff = OFTStorage::decimals_diff(env).unwrap_or_panic(env, OFTError::NotInitialized);
+        local_decimals - decimals_diff
+    }
+
+    /// Returns the message inspector address if set.
+    fn __msg_inspector(env: &Env) -> Option<Address> {
+        OFTStorage::msg_inspector(env)
+    }
+
+    /// Sets or removes the message inspector address.
+    ///
+    /// The message inspector is an optional contract that validates outgoing messages
+    /// and options before they are sent cross-chain. If set, the inspector's `inspect`
+    /// method will be called during `send` and `quote_send` operations.
+    ///
+    /// # Arguments
+    /// * `inspector` - The address of the inspector contract, or None to remove
+    fn __set_msg_inspector(env: &Env, inspector: &Option<Address>) {
+        OFTStorage::set_or_remove_msg_inspector(env, inspector);
+        MsgInspectorSet { inspector: inspector.clone() }.publish(env);
+    }
+
+    // ----- Receive Handler -----
+
+    /// Handles incoming cross-chain OFT transfer from LayerZero endpoint.
+    ///
+    /// Credits tokens to the recipient and optionally queues a compose message.
+    /// Override this method to implement custom receive logic (e.g., pausable, rate limiting).
+    ///
+    /// # Arguments
+    /// * `origin` - The origin information (source chain, sender, nonce)
+    /// * `guid` - The unique message identifier
+    /// * `message` - The encoded OFT message payload
+    /// * `extra_data` - Additional data (unused in default implementation)
+    /// * `executor` - The address of the executor handling the message (unused in default implementation)
+    /// * `value` - The native token value sent with the message (unused in default implementation)
+    fn __receive(
+        env: &Env,
+        origin: &endpoint_v2::Origin,
+        guid: &soroban_sdk::BytesN<32>,
+        message: &Bytes,
+        _extra_data: &Bytes,
+        _executor: &Address,
+        _value: i128,
+    ) {
+        let oft_msg = OFTMessage::decode(message);
+        let send_to = oft_utils::resolve_address(env, &oft_msg.send_to);
+
         let conversion_rate = Self::__decimal_conversion_rate(env);
-        local_decimals - conversion_rate.ilog10()
+        let amount_received_ld =
+            Self::__credit(env, &send_to, oft_utils::to_ld(oft_msg.amount_sd, conversion_rate), origin.src_eid);
+
+        if oft_msg.is_composed() {
+            let compose_msg = OFTComposeMsg {
+                nonce: origin.nonce,
+                src_eid: origin.src_eid,
+                amount_ld: amount_received_ld,
+                compose_from: oft_msg.compose_from.unwrap(),
+                compose_msg: oft_msg.compose_msg.unwrap(),
+            }
+            .encode(env);
+
+            let endpoint_client = MessagingComposerClient::new(env, &Self::endpoint(env));
+            endpoint_client.send_compose(&env.current_contract_address(), &send_to, guid, &0, &compose_msg);
+        }
+
+        events::OFTReceived { guid: guid.clone(), src_eid: origin.src_eid, to: send_to, amount_received_ld }
+            .publish(env);
     }
 }
 
@@ -352,6 +433,24 @@ pub trait OFTCore: OFTInternal {
         false
     }
 
+    /// Returns the message inspector address if set.
+    fn msg_inspector(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
+        Self::__msg_inspector(env)
+    }
+
+    /// Sets or removes the message inspector address.
+    ///
+    /// The message inspector is an optional contract that validates outgoing messages
+    /// and options before they are sent cross-chain. If set, the inspector's `inspect`
+    /// method will be called during `send` and `quote_send` operations.
+    ///
+    /// # Arguments
+    /// * `inspector` - The address of the inspector contract, or None to remove
+    #[only_auth]
+    fn set_msg_inspector(env: &soroban_sdk::Env, inspector: &Option<soroban_sdk::Address>) {
+        Self::__set_msg_inspector(env, inspector);
+    }
+
     /// Quotes an OFT transfer without executing.
     ///
     /// # Returns
@@ -397,8 +496,8 @@ pub trait OFTCore: OFTInternal {
 /// Implements `LzReceiveInternal` for an OFT contract using the default OFT receive logic.
 ///
 /// This macro generates the boilerplate `LzReceiveInternal` implementation that delegates
-/// to `oft_core::lz_receive`, which handles decoding the OFT message, crediting tokens
-/// to the recipient, and optionally queuing compose messages.
+/// to `OFTInternal::__receive`, which handles decoding the OFT message, crediting
+/// tokens to the recipient, and optionally queuing compose messages.
 ///
 /// # Usage
 ///
@@ -428,52 +527,8 @@ macro_rules! impl_oft_lz_receive {
                 executor: &soroban_sdk::Address,
                 value: i128,
             ) {
-                oft_core::lz_receive::<Self>(env, executor, origin, guid, message, extra_data, value)
+                <Self as oft_core::OFTInternal>::__receive(env, origin, guid, message, extra_data, executor, value)
             }
         }
     };
 }
-
-/// Handles incoming cross-chain OFT transfer from LayerZero endpoint.
-///
-/// Credits tokens to the recipient and optionally queues a compose message.
-///
-/// # Arguments
-/// * `executor` - The address of the executor handling the message (unused in default implementation)
-/// * `origin` - The origin information (source chain, sender, nonce)
-/// * `guid` - The unique message identifier
-/// * `message` - The encoded OFT message payload
-/// * `extra_data` - Additional data (unused in default implementation)
-/// * `value` - The native token value sent with the message (unused in default implementation)
-pub fn lz_receive<T: OFTInternal>(
-    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,
-) {
-    let oft_msg = OFTMessage::decode(message);
-    let send_to = oft_utils::resolve_address(env, &oft_msg.send_to);
-
-    let conversion_rate = T::__decimal_conversion_rate(env);
-    let amount_received_ld =
-        T::__credit(env, &send_to, oft_utils::to_ld(oft_msg.amount_sd, conversion_rate), origin.src_eid);
-
-    if oft_msg.is_composed() {
-        let compose_msg = OFTComposeMsg {
-            nonce: origin.nonce,
-            src_eid: origin.src_eid,
-            amount_ld: amount_received_ld,
-            compose_from: oft_msg.compose_from.unwrap(),
-            compose_msg: oft_msg.compose_msg.unwrap(),
-        }
-        .encode(env);
-
-        let endpoint_client = MessagingComposerClient::new(env, &T::endpoint(env));
-        endpoint_client.send_compose(&env.current_contract_address(), &send_to, guid, &0, &compose_msg);
-    }
-
-    events::OFTReceived { guid: guid.clone(), src_eid: origin.src_eid, to: send_to, amount_received_ld }.publish(env);
-}

package/contracts/oapps/oft-core/src/storage.rs

@@ -3,11 +3,15 @@ use soroban_sdk::Address;
 
 #[storage]
 pub enum OFTStorage {
-    /// The decimal conversion rate used for cross-chain normalization
-    #[instance(i128)]
-    DecimalConversionRate,
+    /// The difference between local and shared decimals (local_decimals - shared_decimals)
+    #[instance(u32)]
+    DecimalsDiff,
 
     /// The address of the underlying token contract
     #[instance(Address)]
     Token,
+
+    /// The optional message inspector contract address
+    #[instance(Address)]
+    MsgInspector,
 }

package/contracts/oapps/oft-core/src/tests/mod.rs

@@ -5,6 +5,7 @@ pub mod test_oft_msg_codec;
 
 pub mod test_decimals;
 pub mod test_lz_receive;
+pub mod test_msg_inspector;
 pub mod test_oft_version;
 pub mod test_quote_oft;
 pub mod test_quote_send;

package/contracts/oapps/oft-core/src/tests/test_decimals.rs

@@ -17,7 +17,7 @@ fn test_decimal_conversion_rate() {
 }
 
 #[test]
-#[should_panic(expected = "Error(Contract, #3000)")] // InvalidLocalDecimals
+#[should_panic(expected = "Error(Contract, #3001)")] // InvalidLocalDecimals
 fn test_invalid_local_decimals() {
     let env = Env::default();
     OFTTestSetupBuilder::new(&env).with_token_decimals(5).with_shared_decimals(6).build();
@@ -34,7 +34,7 @@ fn test_to_ld_overflow() {
 }
 
 #[test]
-#[should_panic(expected = "Error(Contract, #3002)")] // Overflow
+#[should_panic(expected = "Error(Contract, #3003)")] // Overflow
 fn test_to_sd_overflow() {
     let env = Env::default();
 
@@ -87,3 +87,38 @@ fn test_to_sd_truncates_dust() {
     // 20 LD → 2 SD (exact)
     assert_eq!(to_sd(&env, 20, conversion_rate), 2);
 }
+
+// ==================== Shared Decimals Tests ====================
+
+#[test]
+fn test_shared_decimals_default() {
+    let env = Env::default();
+    let setup = OFTTestSetup::new(&env);
+
+    // Default setup: 7 local decimals, 6 shared decimals
+    let shared = setup.oft.shared_decimals();
+    assert_eq!(shared, setup.shared_decimals);
+    assert_eq!(shared, 6);
+}
+
+#[test]
+fn test_shared_decimals_equal_to_local() {
+    let env = Env::default();
+    // When shared_decimals == local_decimals, conversion_rate = 1
+    let setup = OFTTestSetupBuilder::new(&env).with_token_decimals(8).with_shared_decimals(8).build();
+
+    let shared = setup.oft.shared_decimals();
+    assert_eq!(shared, 8);
+    assert_eq!(setup.oft.decimal_conversion_rate(), 1);
+}
+
+#[test]
+fn test_shared_decimals_large_difference() {
+    let env = Env::default();
+    // 18 local decimals, 6 shared decimals → conversion_rate = 10^12
+    let setup = OFTTestSetupBuilder::new(&env).with_token_decimals(18).with_shared_decimals(6).build();
+
+    let shared = setup.oft.shared_decimals();
+    assert_eq!(shared, 6);
+    assert_eq!(setup.oft.decimal_conversion_rate(), 10_i128.pow(12));
+}

package/contracts/oapps/oft-core/src/tests/test_lz_receive.rs

@@ -9,7 +9,7 @@ use crate::{
 };
 use endpoint_v2::LayerZeroReceiverClient;
 use soroban_sdk::{testutils::Address as _, Address, Bytes, BytesN, Env};
-use utils::testing_utils::assert_event;
+use utils::testing_utils::assert_contains_event;
 
 // Helper function to reduce code duplication for lz_receive tests
 fn run_lz_receive_test(setup: &OFTTestSetup, recipient: &Address, amount_sd: u64) {
@@ -37,7 +37,7 @@ fn run_lz_receive_test(setup: &OFTTestSetup, recipient: &Address, amount_sd: u64
     let conversion_rate = setup.oft.decimal_conversion_rate();
     let expected_amount_ld = (amount_sd as i128) * conversion_rate;
     setup.lz_receive(&executor, &origin, &guid, &message, &extra_data, 0);
-    assert_event(
+    assert_contains_event(
         env,
         &setup.oft.address,
         OFTReceived { guid: guid.clone(), src_eid, to: recipient.clone(), amount_received_ld: expected_amount_ld },