@layerzerolabs/protocol-stellar-v2 0.2.19 → 0.2.21

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

@@ -1,15 +1,15 @@
 //! OFT - traits and implementations for Omnichain Fungible Tokens.
 //!
 //! This module provides:
-//! - `OFTInternal`: Internal methods NOT exposed as contract entrypoints (`__debit`, `__credit`, etc.)
+//! - `OFTInternal`: Internal methods NOT exposed as contract entrypoints (`__debit`, `__credit`, `__initialize_oft`, `__receive`, etc.)
 //! - `OFTCore`: Public methods exposed as contract entrypoints (using `#[contracttrait]`)
-//! - Core functions: `initialize_oft`, `lz_receive`, and other helpers
+//! - `impl_oft_lz_receive!`: Macro to implement `LzReceiveInternal` with default OFT receive logic
 //!
 //! ## Usage
 //!
 //! ```ignore
-//! use oapp_macros::{oapp, oapp_options_type3};
-//! use oft_core::{OFTInternal, OFTCore, initialize_oft};
+//! use oapp_macros::oapp;
+//! use oft_core::{OFTInternal, OFTCore, impl_oft_lz_receive};
 //!
 //! #[oapp]
 //! pub struct MyOFT;
@@ -17,7 +17,7 @@
 //! #[contractimpl]
 //! impl MyOFT {
 //!     pub fn __constructor(env: &Env, token: &Address, owner: &Address, endpoint: &Address, delegate: &Option<Address>) {
-//!         initialize_oft::<Self>(env, owner, token, endpoint, delegate, 6)
+//!         Self::__initialize_oft(env, owner, token, endpoint, delegate, 6)
 //!     }
 //! }
 //!
@@ -38,26 +38,30 @@
 //!         oft_core::oft_types::mint_burn::credit::<Self>(env, to, amount_ld, src_eid)
 //!     }
 //! }
+//!
+//! // LzReceiveInternal - use the macro for default OFT receive logic
+//! impl_oft_lz_receive!(MyOFT);
 //! ```
 
 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 endpoint_v2::{MessagingComposerClient, MessagingFee, MessagingReceipt, Origin};
+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,
     oapp_sender::OAppSenderInternal,
 };
-use soroban_sdk::{assert_with_error, token::TokenClient, vec, Address, Bytes, BytesN, Env, Vec};
+use soroban_sdk::{assert_with_error, token::TokenClient, vec, Address, Bytes, Env, Vec};
 use utils::{option_ext::OptionExt, ownable::OwnableInitializer};
 
 // ===========================================================================
@@ -78,11 +82,47 @@ use utils::{option_ext::OptionExt, ownable::OwnableInitializer};
 /// impl OFTInternal for MyOFT { ... }
 /// ```
 ///
-/// Internal OFT trait for token debit/credit operations.
-///
-/// This trait contains only the internal token operations. The OApp supertraits
-/// are on `OFTCore` instead, keeping this trait focused on token logic.
-pub trait OFTInternal: OAppCore + OAppOptionsType3 {
+/// This trait extends all OApp supertraits and contains both the token operations
+/// and the internal sending logic. `OFTCore` serves only as an entrypoint wrapper.
+pub trait OFTInternal: OAppCore + OAppReceiver + OAppSenderInternal + OAppOptionsType3 + OwnableInitializer {
+    // =========================================================================
+    // Initialization
+    // =========================================================================
+
+    /// Initializes the OFT (Omnichain Fungible Token) contract.
+    ///
+    /// Sets up the OApp infrastructure and configures decimal conversion for cross-chain transfers.
+    /// The `shared_decimals` parameter defines the common decimal precision used across all chains,
+    /// enabling consistent token amounts regardless of each chain's native token decimals.
+    ///
+    /// # Arguments
+    /// * `owner` - The address that will own this OFT contract
+    /// * `token` - The underlying token contract address (must implement SEP-41 token interface)
+    /// * `endpoint` - The LayerZero endpoint address for cross-chain messaging
+    /// * `delegate` - Optional delegate address for endpoint configuration permissions
+    /// * `shared_decimals` - The shared decimal precision for cross-chain compatibility (must be <= local decimals)
+    ///
+    /// # Panics
+    /// * `OFTError::InvalidLocalDecimals` - If the token's local decimals are less than `shared_decimals`
+    fn __initialize_oft(
+        env: &Env,
+        owner: &Address,
+        token: &Address,
+        endpoint: &Address,
+        delegate: &Option<Address>,
+        shared_decimals: u32,
+    ) {
+        // Initialize OApp (includes owner initialization)
+        initialize_oapp::<Self>(env, owner, endpoint, delegate);
+
+        let local_decimals = TokenClient::new(env, token).decimals();
+        assert_with_error!(env, local_decimals >= shared_decimals, OFTError::InvalidLocalDecimals);
+
+        // Initialize OFT storage
+        OFTStorage::set_token(env, token);
+        OFTStorage::set_decimals_diff(env, &(local_decimals - shared_decimals));
+    }
+
     // =========================================================================
     // Required Methods (no defaults - user MUST implement)
     // =========================================================================
@@ -114,19 +154,239 @@ pub trait OFTInternal: OAppCore + OAppOptionsType3 {
     // Optional Methods (have defaults - override as needed)
     // =========================================================================
 
-    /// Calculates debit amounts without executing (view function).
-    fn __debit_view(env: &Env, amount_ld: i128, min_amount_ld: i128, dst_eid: u32) -> OFTReceipt {
-        debit_view(env, amount_ld, min_amount_ld, dst_eid)
+    // ----- Quote Methods -----
+
+    /// Quotes an OFT transfer without executing.
+    ///
+    /// The default implementation has no send limits (`min_amount_ld: 0`, `max_amount_ld: i128::MAX`)
+    /// and no fee details (empty vector). Override this method to implement custom limits or fees.
+    ///
+    /// # Arguments
+    /// * `send_param` - The send parameters to quote
+    ///
+    /// # 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);
+        (limit, fee_details, oft_receipt)
+    }
+
+    /// Quotes the LayerZero messaging fee for a send operation.
+    ///
+    /// # Arguments
+    /// * `from` - The address initiating the transfer
+    /// * `send_param` - The send parameters to quote
+    /// * `pay_in_zro` - Whether to pay the fee in ZRO token
+    ///
+    /// # 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);
+
+        let (msg, options) = Self::__build_msg_and_options(env, from, send_param, amount_received_ld);
+        Self::__quote(env, send_param.dst_eid, &msg, &options, pay_in_zro)
+    }
+
+    // ----- Send Method -----
+
+    /// Executes a cross-chain token transfer via LayerZero.
+    ///
+    /// Debits tokens from the `from` address, builds the message, and sends via the endpoint.
+    /// The `from` address must be authenticated.
+    ///
+    /// # Arguments
+    /// * `from` - The address sending tokens (must authorize)
+    /// * `send_param` - The send parameters (destination, recipient, amount, options)
+    /// * `fee` - The messaging fee to pay
+    /// * `refund_address` - The address to refund excess fees to
+    ///
+    /// # Returns
+    /// A tuple of (messaging receipt, OFT receipt with amounts)
+    fn __send(
+        env: &Env,
+        from: &Address,
+        send_param: &SendParam,
+        fee: &MessagingFee,
+        refund_address: &Address,
+    ) -> (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);
+        let msg_receipt = Self::__lz_send(env, send_param.dst_eid, &msg, &options, from, fee, refund_address);
+
+        OFTSent {
+            guid: msg_receipt.guid.clone(),
+            dst_eid: send_param.dst_eid,
+            from: from.clone(),
+            amount_sent_ld: oft_receipt.amount_sent_ld,
+            amount_received_ld: oft_receipt.amount_received_ld,
+        }
+        .publish(env);
+
+        (msg_receipt, oft_receipt)
+    }
+
+    // ----- View/Helper Methods -----
+
+    /// Simulates a debit operation without executing, used for quoting.
+    ///
+    /// The default implementation does not charge any fee, so `amount_sent_ld` equals
+    /// `amount_received_ld` (after dust removal). Override this method to implement
+    /// custom fee logic.
+    ///
+    /// # Arguments
+    /// * `amount_ld` - The amount of tokens to send in local decimals
+    /// * `min_amount_ld` - The minimum amount to send in local decimals (slippage protection)
+    /// * `dst_eid` - The destination chain ID (unused in default implementation)
+    ///
+    /// # Returns
+    /// `OFTReceipt` containing the amount sent and amount received after dust removal
+    ///
+    /// # Panics
+    /// * `OFTError::SlippageExceeded` - If `amount_received_ld` is less than `min_amount_ld`
+    fn __debit_view(env: &Env, amount_ld: i128, min_amount_ld: i128, _dst_eid: u32) -> OFTReceipt {
+        let conversion_rate = Self::__decimal_conversion_rate(env);
+        let amount_sent_ld = oft_utils::remove_dust(amount_ld, conversion_rate);
+        let amount_received_ld = amount_sent_ld;
+
+        assert_with_error!(env, amount_received_ld >= min_amount_ld, OFTError::SlippageExceeded);
+
+        OFTReceipt { amount_sent_ld, amount_received_ld }
     }
 
     /// 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
+    /// * `amount_receive_ld` - The amount to be received in local decimals (after dust removal)
+    ///
+    /// # Returns
+    /// A tuple of (encoded message, combined options)
     fn __build_msg_and_options(
         env: &Env,
         from: &Address,
-        send_param: &oft_core::types::SendParam,
-        receive_amount_ld: i128,
+        send_param: &SendParam,
+        amount_receive_ld: i128,
     ) -> (Bytes, Bytes) {
-        build_msg_and_options::<Self>(env, from, send_param, receive_amount_ld)
+        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, 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, options)
+    }
+
+    // ----- Storage Accessors -----
+
+    /// Retrieves the token address associated with this OFT.
+    fn __token(env: &Env) -> Address {
+        OFTStorage::token(env).unwrap_or_panic(env, OFTError::NotInitialized)
+    }
+
+    /// Retrieves the decimal conversion rate used for cross-chain normalization.
+    fn __decimal_conversion_rate(env: &Env) -> i128 {
+        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 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);
+        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);
     }
 }
 
@@ -139,13 +399,12 @@ pub trait OFTInternal: OAppCore + OAppOptionsType3 {
 /// This trait is marked with `#[contracttrait]` so all its methods are exposed as
 /// contract entrypoints. Users implement this with `#[contractimpl(contracttrait)]`.
 ///
-/// Internal methods like `__debit`, `__credit`, `__debit_view`, and `__build_msg_and_options`
-/// are in the `OFTInternal` trait and are NOT exposed as contract entrypoints.
+/// This trait only exposes entrypoints. All internal logic is in `OFTInternal`.
 #[contract_trait(client_name = "OFTClient")]
-pub trait OFTCore: OFTInternal + OAppReceiver + OAppSenderInternal + OAppOptionsType3 {
+pub trait OFTCore: OFTInternal {
     /// Retrieves the token address associated with this OFT.
     fn token(env: &soroban_sdk::Env) -> soroban_sdk::Address {
-        token(env)
+        Self::__token(env)
     }
 
     /// Returns OFT version as (major, minor).
@@ -155,12 +414,12 @@ pub trait OFTCore: OFTInternal + OAppReceiver + OAppSenderInternal + OAppOptions
 
     /// Retrieves the shared decimals used for cross-chain normalization.
     fn shared_decimals(env: &soroban_sdk::Env) -> u32 {
-        shared_decimals(env)
+        Self::__shared_decimals(env)
     }
 
     /// Retrieves the decimal conversion rate used for cross-chain normalization.
     fn decimal_conversion_rate(env: &soroban_sdk::Env) -> i128 {
-        decimal_conversion_rate(env)
+        Self::__decimal_conversion_rate(env)
     }
 
     /// Whether a separate token approval is required before sending.
@@ -174,6 +433,24 @@ pub trait OFTCore: OFTInternal + OAppReceiver + OAppSenderInternal + OAppOptions
         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
@@ -182,258 +459,76 @@ pub trait OFTCore: OFTInternal + OAppReceiver + OAppSenderInternal + OAppOptions
         env: &soroban_sdk::Env,
         send_param: &oft_core::types::SendParam,
     ) -> (oft_core::types::OFTLimit, soroban_sdk::Vec<oft_core::types::OFTFeeDetail>, oft_core::types::OFTReceipt) {
-        quote_oft::<Self>(env, send_param)
+        Self::__quote_oft(env, send_param)
     }
 
     /// Quotes a send operation including LayerZero messaging fees.
     fn quote_send(
         env: &soroban_sdk::Env,
-        sender: &soroban_sdk::Address,
+        from: &soroban_sdk::Address,
         send_param: &oft_core::types::SendParam,
         pay_in_zro: bool,
     ) -> endpoint_v2::MessagingFee {
-        quote_send::<Self>(env, sender, send_param, pay_in_zro)
+        Self::__quote_send(env, from, send_param, pay_in_zro)
     }
 
     /// Sends tokens cross-chain to another endpoint.
     ///
-    /// Sender must be authenticated.
+    /// From must be authenticated.
     ///
     /// # Returns
     /// (MessagingReceipt, OFTReceipt)
     fn send(
         env: &soroban_sdk::Env,
-        sender: &soroban_sdk::Address,
+        from: &soroban_sdk::Address,
         send_param: &oft_core::types::SendParam,
         fee: &endpoint_v2::MessagingFee,
         refund_address: &soroban_sdk::Address,
     ) -> (endpoint_v2::MessagingReceipt, oft_core::types::OFTReceipt) {
-        send::<Self>(env, sender, send_param, fee, refund_address)
+        Self::__send(env, from, send_param, fee, refund_address)
     }
 }
 
 // ===========================================================================
-// Initialization
+// LzReceive Handler (called by OAppReceiver)
 // ===========================================================================
 
-/// Initializes the OFT (Omnichain Fungible Token) contract.
-///
-/// Sets up the OApp infrastructure and configures decimal conversion for cross-chain transfers.
-/// The `shared_decimals` parameter defines the common decimal precision used across all chains,
-/// enabling consistent token amounts regardless of each chain's native token decimals.
-///
-/// # Arguments
-/// * `owner` - The address that will own this OFT contract
-/// * `token` - The underlying token contract address (must implement SEP-41 token interface)
-/// * `endpoint` - The LayerZero endpoint address for cross-chain messaging
-/// * `delegate` - Optional delegate address for endpoint configuration permissions
-/// * `shared_decimals` - The shared decimal precision for cross-chain compatibility (must be <= local decimals)
+/// Implements `LzReceiveInternal` for an OFT contract using the default OFT receive logic.
 ///
-/// # Panics
-/// * `OFTError::InvalidLocalDecimals` - If the token's local decimals are less than `shared_decimals`
-pub fn initialize_oft<T: OFTCore + OwnableInitializer>(
-    env: &Env,
-    owner: &Address,
-    token: &Address,
-    endpoint: &Address,
-    delegate: &Option<Address>,
-    shared_decimals: u32,
-) {
-    // Initialize OApp (includes owner initialization)
-    initialize_oapp::<T>(env, owner, endpoint, delegate);
-
-    let local_decimals = TokenClient::new(env, token).decimals();
-    assert_with_error!(env, local_decimals >= shared_decimals, OFTError::InvalidLocalDecimals);
-
-    // Initialize OFT storage
-    OFTStorage::set_token(env, token);
-    OFTStorage::set_decimal_conversion_rate(env, &10_i128.pow(local_decimals - shared_decimals));
-}
-
-// ===========================================================================
-// Implementation Functions
-// ===========================================================================
-
-/// Simulates a debit operation without executing, used for quoting.
+/// This macro generates the boilerplate `LzReceiveInternal` implementation that delegates
+/// to `OFTInternal::__receive`, which handles decoding the OFT message, crediting
+/// tokens to the recipient, and optionally queuing compose messages.
 ///
-/// # Arguments
-/// * `amount_ld` - The amount of tokens to send in local decimals
-/// * `min_amount_ld` - The minimum amount to send in local decimals (slippage protection)
-/// * `dst_eid` - The destination chain ID (unused in default implementation)
+/// # Usage
 ///
-/// # Returns
-/// `OFTReceipt` containing the amount sent and amount received after dust removal
-pub fn debit_view(env: &Env, amount_ld: i128, min_amount_ld: i128, _dst_eid: u32) -> OFTReceipt {
-    let conversion_rate = decimal_conversion_rate(env);
-    let amount_sent_ld = oft_utils::remove_dust(amount_ld, conversion_rate);
-    let amount_received_ld = amount_sent_ld;
-
-    assert_with_error!(env, amount_received_ld >= min_amount_ld, OFTError::SlippageExceeded);
-
-    OFTReceipt { amount_sent_ld, amount_received_ld }
-}
-
-/// Builds the OFT message payload and combines enforced options for cross-chain transfer.
-///
-/// # 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)
-///
-/// # Returns
-/// A tuple of (encoded message, combined options)
-pub fn build_msg_and_options<T: OAppOptionsType3>(
-    env: &Env,
-    from: &Address,
-    send_param: &SendParam,
-    receive_amount_ld: i128,
-) -> (Bytes, Bytes) {
-    let has_compose = !send_param.compose_msg.is_empty();
-    let conversion_rate = 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),
-        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 };
-
-    (msg, T::combine_options(env, send_param.dst_eid, msg_type, &send_param.extra_options))
-}
-
-/// Quotes an OFT transfer without executing.
-///
-/// # Arguments
-/// * `send_param` - The send parameters to quote
-///
-/// # Returns
-/// A tuple of (transfer limits, fee details, estimated receipt)
-pub fn quote_oft<T: OFTInternal>(env: &Env, send_param: &SendParam) -> (OFTLimit, Vec<OFTFeeDetail>, OFTReceipt) {
-    let limit = OFTLimit { min_amount_ld: 0, max_amount_ld: i128::MAX }; // No limits in default implementation
-    let fee_details = vec![env]; // No fee details in default implementation
-    let oft_receipt = T::__debit_view(env, send_param.amount_ld, send_param.min_amount_ld, send_param.dst_eid);
-    (limit, fee_details, oft_receipt)
-}
-
-/// Quotes the LayerZero messaging fee for a send operation.
-///
-/// # Arguments
-/// * `from` - The address initiating the transfer
-/// * `send_param` - The send parameters to quote
-/// * `pay_in_zro` - Whether to pay the fee in ZRO token
-///
-/// # Returns
-/// The messaging fee required for the transfer
-pub fn quote_send<T: OFTCore>(env: &Env, from: &Address, send_param: &SendParam, pay_in_zro: bool) -> MessagingFee {
-    let OFTReceipt { amount_received_ld, .. } =
-        T::__debit_view(env, send_param.amount_ld, send_param.min_amount_ld, send_param.dst_eid);
-
-    let (msg, options) = build_msg_and_options::<T>(env, from, send_param, amount_received_ld);
-    T::__quote(env, send_param.dst_eid, &msg, &options, pay_in_zro)
-}
-
-/// Executes a cross-chain token transfer via LayerZero.
-///
-/// Debits tokens from the `from` address, builds the message, and sends via the endpoint.
-/// The `from` address must be authenticated.
-///
-/// # Arguments
-/// * `from` - The address sending tokens (must authorize)
-/// * `send_param` - The send parameters (destination, recipient, amount, options)
-/// * `fee` - The messaging fee to pay
-/// * `refund_address` - The address to refund excess fees to
+/// ```ignore
+/// use oft_core::impl_oft_lz_receive;
 ///
-/// # Returns
-/// A tuple of (messaging receipt, OFT receipt with amounts)
-pub fn send<T: OFTCore>(
-    env: &Env,
-    from: &Address,
-    send_param: &SendParam,
-    fee: &MessagingFee,
-    refund_address: &Address,
-) -> (MessagingReceipt, OFTReceipt) {
-    from.require_auth();
-
-    let oft_receipt = T::__debit(env, from, send_param.amount_ld, send_param.min_amount_ld, send_param.dst_eid);
-
-    let (msg, options) = build_msg_and_options::<T>(env, from, send_param, oft_receipt.amount_received_ld);
-    let msg_receipt = T::__lz_send(env, send_param.dst_eid, &msg, &options, from, fee, refund_address);
-
-    OFTSent {
-        guid: msg_receipt.guid.clone(),
-        dst_eid: send_param.dst_eid,
-        from: from.clone(),
-        amount_sent_ld: oft_receipt.amount_sent_ld,
-        amount_received_ld: oft_receipt.amount_received_ld,
-    }
-    .publish(env);
-
-    (msg_receipt, oft_receipt)
-}
-
-/// Retrieves the decimal conversion rate used for cross-chain normalization.
-pub fn decimal_conversion_rate(env: &Env) -> i128 {
-    OFTStorage::decimal_conversion_rate(env).unwrap_or_panic(env, OFTError::NotInitialized)
-}
-
-/// Retrieves the token address associated with this OFT.
-pub fn token(env: &Env) -> Address {
-    OFTStorage::token(env).unwrap_or_panic(env, OFTError::NotInitialized)
-}
-
-/// Retrieves the shared decimals used for cross-chain normalization.
-pub fn shared_decimals(env: &Env) -> u32 {
-    let token = token(env);
-    let local_decimals = TokenClient::new(env, &token).decimals();
-    let conversion_rate = decimal_conversion_rate(env);
-    local_decimals - conversion_rate.ilog10()
-}
-
-// ===========================================================================
-// LzReceive Handler (called by OAppReceiver)
-// ===========================================================================
-
-/// Handles incoming cross-chain OFT transfer from LayerZero endpoint.
+/// #[oapp]
+/// pub struct MyOFT;
 ///
-/// Credits tokens to the recipient and optionally queues a compose message.
+/// impl OFTInternal for MyOFT {
+///     // ... implement __debit and __credit ...
+/// }
 ///
-/// # 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: &Env,
-    _executor: &Address,
-    origin: &Origin,
-    guid: &BytesN<32>,
-    message: &Bytes,
-    _extra_data: &Bytes,
-    _value: i128,
-) {
-    let oft_msg = OFTMessage::decode(message);
-    let send_to = oft_utils::resolve_address(env, &oft_msg.send_to);
-
-    let conversion_rate = 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(),
+/// // Instead of manually implementing LzReceiveInternal:
+/// impl_oft_lz_receive!(MyOFT);
+/// ```
+#[macro_export]
+macro_rules! impl_oft_lz_receive {
+    ($contract:ty) => {
+        impl oapp::oapp_receiver::LzReceiveInternal for $contract {
+            fn __lz_receive(
+                env: &soroban_sdk::Env,
+                origin: &endpoint_v2::Origin,
+                guid: &soroban_sdk::BytesN<32>,
+                message: &soroban_sdk::Bytes,
+                extra_data: &soroban_sdk::Bytes,
+                executor: &soroban_sdk::Address,
+                value: i128,
+            ) {
+                <Self as oft_core::OFTInternal>::__receive(env, origin, guid, message, extra_data, executor, value)
+            }
         }
-        .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);
+    };
 }