@layerzerolabs/protocol-stellar-v2 0.2.29 → 0.2.30

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

@@ -16,8 +16,8 @@
 //!
 //! #[contractimpl]
 //! impl MyOFT {
-//!     pub fn __constructor(env: &Env, token: &Address, owner: &Address, endpoint: &Address, delegate: &Option<Address>) {
-//!         Self::__initialize_oft(env, owner, token, endpoint, delegate, 6)
+//!     pub fn __constructor(env: &Env, token: &Address, owner: &Address, endpoint: &Address, delegate: &Address) {
+//!         Self::__initialize_oft(env, token, 6, owner, endpoint, delegate)
 //!     }
 //! }
 //!
@@ -28,7 +28,7 @@
 //! // Internal methods - NOT exposed as contract entrypoints
 //! // IMPORTANT: Do NOT use #[contractimpl] here to keep methods internal
 //! impl OFTInternal for MyOFT {
-//!     fn __debit(env: &Env, sender: &Address, amount_ld: i128, min_amount_ld: i128, dst_eid: u32) -> OFTReceipt {
+//!     fn __debit(env: &Env, sender: &Address, amount_ld: i128, min_amount_ld: i128, dst_eid: u32) -> (i128, i128) {
 //!         // Your debit logic (e.g., burn or lock tokens)
 //!         oft_core::oft_types::mint_burn::debit::<Self>(env, sender, amount_ld, min_amount_ld, dst_eid)
 //!     }
@@ -45,21 +45,24 @@
 
 use crate::{
     self as oft_core,
-    codec::{oft_compose_msg_codec::OFTComposeMsg, oft_msg_codec::OFTMessage},
+    codec::{
+        oft_compose_msg_codec::OFTComposeMsg,
+        oft_msg_codec::{ComposeData, OFTMessage},
+    },
     errors::OFTError,
     events::{self, MsgInspectorSet, OFTSent},
     storage::OFTStorage,
-    types::{self, OFTFeeDetail, OFTLimit, OFTReceipt, SendParam},
+    types::{OFTFeeDetail, OFTLimit, OFTReceipt, SendParam, SEND, SEND_AND_CALL},
     utils as oft_utils,
 };
 use common_macros::{contract_trait, only_auth};
 use endpoint_v2::{MessagingComposerClient, MessagingFee, MessagingReceipt};
 use oapp::{
-    interfaces::OAppMsgInspectorClient,
-    oapp_core::{initialize_oapp, OAppCore},
+    oapp_core::initialize_oapp,
     oapp_options_type3::OAppOptionsType3,
     oapp_receiver::OAppReceiver,
-    oapp_sender::OAppSenderInternal,
+    oapp_sender::{FeePayer, OAppSenderInternal},
+    OAppMsgInspectorClient,
 };
 use soroban_sdk::{assert_with_error, token::TokenClient, vec, Address, Bytes, Env, Vec};
 use utils::{option_ext::OptionExt, ownable::OwnableInitializer};
@@ -84,7 +87,7 @@ use utils::{option_ext::OptionExt, ownable::OwnableInitializer};
 ///
 /// 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 {
+pub trait OFTInternal: OAppReceiver + OAppSenderInternal + OAppOptionsType3 + OwnableInitializer {
     // =========================================================================
     // Initialization
     // =========================================================================
@@ -96,21 +99,21 @@ pub trait OFTInternal: OAppCore + OAppReceiver + OAppSenderInternal + OAppOption
     /// 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)
+    /// * `owner` - The address that will own this OFT contract
+    /// * `endpoint` - The LayerZero endpoint address for cross-chain messaging
+    /// * `delegate` - The delegate address for endpoint configuration permissions
     ///
     /// # 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,
+        owner: &Address,
+        endpoint: &Address,
+        delegate: &Address,
     ) {
         // Initialize OApp (includes owner initialization)
         initialize_oapp::<Self>(env, owner, endpoint, delegate);
@@ -136,8 +139,9 @@ pub trait OFTInternal: OAppCore + OAppReceiver + OAppSenderInternal + OAppOption
     /// * `dst_eid` - The destination chain ID
     ///
     /// # Returns
-    /// `OFTReceipt` containing the amount sent and amount received
-    fn __debit(env: &Env, from: &Address, amount_ld: i128, min_amount_ld: i128, dst_eid: u32) -> OFTReceipt;
+    /// * `amount_sent_ld` - The amount sent in local decimals
+    /// * `amount_received_ld` - The amount received in local decimals on the remote
+    fn __debit(env: &Env, from: &Address, amount_ld: i128, min_amount_ld: i128, dst_eid: u32) -> (i128, i128);
 
     /// Credits tokens to recipient after receiving cross-chain transfer.
     ///
@@ -156,59 +160,33 @@ pub trait OFTInternal: OAppCore + OAppReceiver + OAppSenderInternal + OAppOption
 
     // ----- 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);
+    /// Quotes an OFT transfer without executing. Returns (limits, fee details, receipt).
+    fn __quote_oft(env: &Env, _from: &Address, send_param: &SendParam) -> (OFTLimit, Vec<OFTFeeDetail>, OFTReceipt) {
+        assert_nonnegative_amount(env, send_param);
 
-        let limit = OFTLimit { min_amount_ld: 0, max_amount_ld: i128::MAX };
+        let limit = OFTLimit { min_amount_ld: 0, max_amount_ld: u64::MAX as i128 };
         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)
+        let (amount_sent_ld, amount_received_ld) =
+            Self::__debit_view(env, send_param.amount_ld, send_param.min_amount_ld, send_param.dst_eid);
+        (limit, fee_details, OFTReceipt { amount_sent_ld, amount_received_ld })
     }
 
-    /// 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
+    /// Quotes the LayerZero messaging fee for a send. Builds the message internally
+    /// to get an accurate fee estimate from the endpoint.
     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);
+        assert_nonnegative_amount(env, send_param);
 
-        let OFTReceipt { amount_received_ld, .. } =
+        let (_amount_sent_ld, 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)
+        let (message, options) = Self::__build_msg_and_options(env, from, send_param, amount_received_ld);
+        Self::__quote(env, send_param.dst_eid, &message, &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)
+    /// Executes a cross-chain token transfer: debits `from`, builds the OFT message,
+    /// and dispatches it via the LayerZero endpoint.
     fn __send(
         env: &Env,
         from: &Address,
@@ -218,89 +196,85 @@ pub trait OFTInternal: OAppCore + OAppReceiver + OAppSenderInternal + OAppOption
     ) -> (MessagingReceipt, OFTReceipt) {
         from.require_auth();
 
-        assert_with_error!(env, send_param.amount_ld >= 0, OFTError::InvalidAmount);
+        assert_nonnegative_amount(env, send_param);
 
-        let oft_receipt = Self::__debit(env, from, send_param.amount_ld, send_param.min_amount_ld, send_param.dst_eid);
+        let (amount_sent_ld, amount_received_ld) =
+            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);
+        let (message, options) = Self::__build_msg_and_options(env, from, send_param, amount_received_ld);
+        let messaging_receipt = Self::__lz_send(
+            env,
+            send_param.dst_eid,
+            &message,
+            &options,
+            &FeePayer::Verified(from.clone()),
+            fee,
+            refund_address,
+        );
 
         OFTSent {
-            guid: msg_receipt.guid.clone(),
+            guid: messaging_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,
+            amount_sent_ld,
+            amount_received_ld,
         }
         .publish(env);
 
-        (msg_receipt, oft_receipt)
+        (messaging_receipt, OFTReceipt { amount_sent_ld, amount_received_ld })
     }
 
     // ----- 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)
+    /// Simulates a debit for quoting — removes dust but charges no fee by default.
+    /// Override to add custom fee logic. Panics with `SlippageExceeded` if the
+    /// resulting amount is below `min_amount_ld`.
     ///
     /// # 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 {
+    /// * `amount_sent_ld` - The amount sent in local decimals
+    /// * `amount_received_ld` - The amount received in local decimals on the remote
+    fn __debit_view(env: &Env, amount_ld: i128, min_amount_ld: i128, _dst_eid: u32) -> (i128, i128) {
         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 }
+        (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)
+    /// Encodes the OFT message payload and merges enforced + extra options.
+    /// Runs the message inspector (if set) before returning `(message, options)`.
     fn __build_msg_and_options(
         env: &Env,
         from: &Address,
         send_param: &SendParam,
-        amount_receive_ld: i128,
+        amount_received_ld: i128,
     ) -> (Bytes, Bytes) {
         let has_compose = !send_param.compose_msg.is_empty();
+        let compose_data = has_compose
+            .then(|| ComposeData { from: oft_utils::address_payload(env, from), msg: send_param.compose_msg.clone() });
+
+        // Build the OFT message
         let conversion_rate = Self::__decimal_conversion_rate(env);
-        let (msg, _) = OFTMessage {
+        let message = 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 },
+            amount_sd: oft_utils::to_sd(env, amount_received_ld, conversion_rate),
+            compose: compose_data,
         }
         .encode(env);
-        let msg_type = if has_compose { types::SEND_AND_CALL } else { types::SEND };
+
+        // Combine the options with the message type
+        let msg_type = if has_compose { SEND_AND_CALL } else { 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 it fails inspection, needs to revert in the implementation. ie. does not rely on return boolean
         if let Some(inspector) = Self::__msg_inspector(env) {
-            OAppMsgInspectorClient::new(env, &inspector).inspect(&env.current_contract_address(), &msg, &options);
+            OAppMsgInspectorClient::new(env, &inspector).inspect(&env.current_contract_address(), &message, &options);
         }
 
-        (msg, options)
+        (message, options)
     }
 
     // ----- Storage Accessors -----
@@ -310,17 +284,20 @@ pub trait OFTInternal: OAppCore + OAppReceiver + OAppSenderInternal + OAppOption
         OFTStorage::token(env).unwrap_or_panic(env, OFTError::NotInitialized)
     }
 
+    /// Retrieves the difference between local and shared decimals (`local_decimals - shared_decimals`).
+    fn __decimals_diff(env: &Env) -> u32 {
+        OFTStorage::decimals_diff(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)
+        10_i128.pow(Self::__decimals_diff(env))
     }
 
     /// 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
+        local_decimals - Self::__decimals_diff(env)
     }
 
     /// Returns the message inspector address if set.
@@ -329,13 +306,6 @@ pub trait OFTInternal: OAppCore + OAppReceiver + OAppSenderInternal + OAppOption
     }
 
     /// 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);
@@ -367,17 +337,19 @@ pub trait OFTInternal: OAppCore + OAppReceiver + OAppSenderInternal + OAppOption
         let oft_msg = OFTMessage::decode(message);
         let send_to = oft_utils::resolve_address(env, &oft_msg.send_to);
 
+        // Convert the amount to local decimals and credit the recipient
         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() {
+        // If there is a compose message, send it
+        if let Some(compose) = oft_msg.compose {
             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(),
+                compose_from: compose.from,
+                compose_msg: compose.msg,
             }
             .encode(env);
 
@@ -394,97 +366,167 @@ pub trait OFTInternal: OAppCore + OAppReceiver + OAppSenderInternal + OAppOption
 // OFTCore Trait (exposed as contract entrypoints)
 // ===========================================================================
 
-/// The public OFT trait defining the cross-chain token transfer interface.
+/// Public OFT (Omnichain Fungible Token) interface for cross-chain token transfers.
 ///
-/// This trait is marked with `#[contracttrait]` so all its methods are exposed as
-/// contract entrypoints. Users implement this with `#[contractimpl(contracttrait)]`.
+/// `OFTCore` defines the externally callable contract entrypoints for interacting with an
+/// OFT deployment. Every method in this trait becomes a Soroban contract function via
+/// `#[contract_trait]`. All business logic lives in [`OFTInternal`] — this trait is a
+/// thin entrypoint layer that delegates to the internal implementations.
 ///
-/// This trait only exposes entrypoints. All internal logic is in `OFTInternal`.
+/// # Typical Client Workflow
+///
+/// 1. Call [`quote_oft`](OFTCore::quote_oft) to preview transfer limits, fees, and the
+///    estimated receipt (amounts sent vs. received after dust removal and fees).
+/// 2. Call [`quote_send`](OFTCore::quote_send) to obtain the LayerZero messaging fee.
+/// 3. Call [`send`](OFTCore::send) to execute the cross-chain transfer, supplying the
+///    quoted fee and a refund address for any excess.
 #[contract_trait(client_name = "OFTClient")]
 pub trait OFTCore: OFTInternal {
-    /// Retrieves the token address associated with this OFT.
+    /// Returns the address of the underlying SEP-41 token managed by this OFT.
     fn token(env: &soroban_sdk::Env) -> soroban_sdk::Address {
         Self::__token(env)
     }
 
-    /// Returns OFT version as (major, minor).
+    /// Returns the OFT messaging protocol version as `(major, minor)`.
+    ///
+    /// The version is used by off-chain tooling and peer contracts to verify wire-format
+    /// compatibility.
     fn oft_version(_env: &soroban_sdk::Env) -> (u64, u64) {
         (1, 1)
     }
 
-    /// Retrieves the shared decimals used for cross-chain normalization.
+    /// Returns the **shared decimals** — the common decimal precision used in cross-chain
+    /// messages.
+    ///
+    /// Token amounts are normalized to this precision before encoding into LayerZero
+    /// messages, ensuring consistent values regardless of each chain's native token
+    /// decimals. For example, a token with 18 local decimals and 6 shared decimals has a
+    /// conversion rate of 10^12.
     fn shared_decimals(env: &soroban_sdk::Env) -> u32 {
         Self::__shared_decimals(env)
     }
 
-    /// Retrieves the decimal conversion rate used for cross-chain normalization.
+    /// Returns the **decimal conversion rate** (`10 ^ (local_decimals - shared_decimals)`).
+    ///
+    /// This multiplier converts between local-decimal amounts (used on-chain) and
+    /// shared-decimal amounts (used in cross-chain messages). Any sub-conversion-rate
+    /// remainder ("dust") is stripped before sending to avoid rounding discrepancies
+    /// across chains.
     fn decimal_conversion_rate(env: &soroban_sdk::Env) -> i128 {
         Self::__decimal_conversion_rate(env)
     }
 
-    /// Whether a separate token approval is required before sending.
+    /// Indicates whether the caller must approve a token allowance before calling [`send`](OFTCore::send).
     ///
-    /// Helps wallet implementers determine integration requirements.
+    /// - **`false`** (default) — the OFT contract itself controls the token (mint-burn model),
+    ///   so no prior approval is needed.
+    /// - **`true`** — the OFT locks externally owned tokens (adapter model), requiring the
+    ///   sender to call `token.approve(oft_address, amount)` beforehand.
     ///
-    /// # Returns
-    /// - `true` if a separate token approval step is required
-    /// - `false` if no separate approval is needed
+    /// Wallet and frontend integrators should check this to determine whether an approval
+    /// transaction must precede the send.
     fn approval_required(_env: &soroban_sdk::Env) -> bool {
         false
     }
 
-    /// Returns the message inspector address if set.
+    /// Returns the current message inspector contract address, or `None` if unset.
+    ///
+    /// When set, the inspector's `inspect` method is invoked during both
+    /// [`quote_send`](OFTCore::quote_send) and [`send`](OFTCore::send) to validate the
+    /// outgoing message payload and options before they reach the LayerZero endpoint.
     fn msg_inspector(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
         Self::__msg_inspector(env)
     }
 
-    /// Sets or removes the message inspector address.
+    /// Sets or removes the message inspector contract.
+    ///
+    /// The message inspector is an **optional** validation hook. When configured, every
+    /// outbound message (from both `send` and `quote_send`) is passed to the inspector
+    /// contract's `inspect(contract, message, options)` method. The inspector should
+    /// **panic** to reject invalid messages, acting as an on-chain policy gate.
+    ///
+    /// Pass `None` to remove the inspector and disable outbound validation.
     ///
-    /// 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.
+    /// # Authorization
+    /// Requires owner authentication (`#[only_auth]`).
     ///
     /// # Arguments
-    /// * `inspector` - The address of the inspector contract, or None to remove
+    /// * `inspector` - Address of the inspector contract, or `None` to remove it
     #[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.
+    /// Previews an OFT transfer **without executing** it.
     ///
-    /// # Returns
-    /// (OFTLimit, fee details, receipt with estimated amounts)
+    /// Use this to display transfer details to the user before they commit. Returns:
+    ///
+    /// - **`OFTLimit`** — the minimum and maximum transferable amounts in local decimals.
+    /// - **`Vec<OFTFeeDetail>`** — itemized fees (empty by default; populated when custom
+    ///   fee logic is implemented via [`OFTInternal::__quote_oft`]).
+    /// - **`OFTReceipt`** — estimated `amount_sent_ld` and `amount_received_ld` after
+    ///   dust removal and any fees.
+    ///
+    /// # Arguments
+    /// * `from` - The address that would initiate the transfer
+    /// * `send_param` - The proposed transfer parameters (destination, amount, options, etc.)
     fn quote_oft(
         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) {
-        Self::__quote_oft(env, send_param)
+        from: &soroban_sdk::Address,
+        send_param: &oft_core::SendParam,
+    ) -> (oft_core::OFTLimit, soroban_sdk::Vec<oft_core::OFTFeeDetail>, oft_core::OFTReceipt) {
+        Self::__quote_oft(env, from, send_param)
     }
 
-    /// Quotes a send operation including LayerZero messaging fees.
+    /// Quotes the **LayerZero messaging fee** required for a cross-chain send.
+    ///
+    /// Builds the outgoing message and options from `send_param`, then queries the
+    /// LayerZero endpoint for the corresponding fee. If a message inspector is set, it
+    /// will also validate the message at this stage.
+    ///
+    /// # Arguments
+    /// * `from` - The address that would initiate the transfer
+    /// * `send_param` - The proposed transfer parameters
+    /// * `pay_in_zro` - `true` to pay the messaging fee in the ZRO token; `false` to pay
+    ///   in the chain's native token
+    ///
+    /// # Returns
+    /// A [`MessagingFee`](endpoint_v2::MessagingFee) containing the `native_fee` and
+    /// `zro_fee` required by the endpoint. Pass this value (or a superset) to
+    /// [`send`](OFTCore::send).
     fn quote_send(
         env: &soroban_sdk::Env,
         from: &soroban_sdk::Address,
-        send_param: &oft_core::types::SendParam,
+        send_param: &oft_core::SendParam,
         pay_in_zro: bool,
     ) -> endpoint_v2::MessagingFee {
         Self::__quote_send(env, from, send_param, pay_in_zro)
     }
 
-    /// Sends tokens cross-chain to another endpoint.
+    /// Executes a cross-chain token transfer via the LayerZero endpoint.
+    ///
+    /// Builds the OFT message and options, then sends the message through the LayerZero endpoint.
     ///
-    /// From must be authenticated.
+    /// # Arguments
+    /// * `from` - The token sender (must authorize the call)
+    /// * `send_param` - Transfer parameters including destination chain (`dst_eid`),
+    ///   recipient (`to`), amount, slippage floor (`min_amount_ld`), extra options, and
+    ///   an optional compose message
+    /// * `fee` - The messaging fee to pay (obtain from [`quote_send`](OFTCore::quote_send))
+    /// * `refund_address` - Address to receive any excess fee refund
     ///
     /// # Returns
-    /// (MessagingReceipt, OFTReceipt)
+    /// * [`MessagingReceipt`](endpoint_v2::MessagingReceipt) — the LayerZero message GUID,
+    ///   nonce, and fee actually consumed
+    /// * [`OFTReceipt`](crate::types::OFTReceipt) — `amount_sent_ld` (debited) and
+    ///   `amount_received_ld` (credited on destination after dust removal / fees)
     fn send(
         env: &soroban_sdk::Env,
         from: &soroban_sdk::Address,
-        send_param: &oft_core::types::SendParam,
+        send_param: &oft_core::SendParam,
         fee: &endpoint_v2::MessagingFee,
         refund_address: &soroban_sdk::Address,
-    ) -> (endpoint_v2::MessagingReceipt, oft_core::types::OFTReceipt) {
+    ) -> (endpoint_v2::MessagingReceipt, oft_core::OFTReceipt) {
         Self::__send(env, from, send_param, fee, refund_address)
     }
 }
@@ -532,3 +574,18 @@ macro_rules! impl_oft_lz_receive {
         }
     };
 }
+
+// ===========================================================================
+// Helper Functions
+// ===========================================================================
+
+/// Asserts that the send amount and min_amount are nonnegative.
+/// # Arguments
+/// * `env` - The environment
+/// * `send_param` - The send parameters to assert
+///
+/// # Panics
+/// * `OFTError::InvalidAmount` - If the send amount or min_amount is negative
+pub fn assert_nonnegative_amount(env: &Env, send_param: &SendParam) {
+    assert_with_error!(env, send_param.amount_ld >= 0 && send_param.min_amount_ld >= 0, OFTError::InvalidAmount);
+}

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

@@ -3,11 +3,13 @@ use soroban_sdk::Address;
 
 #[storage]
 pub enum OFTStorage {
-    /// The difference between local and shared decimals (local_decimals - shared_decimals)
+    /// The difference between local and shared decimals (local_decimals - shared_decimals).
+    /// Immutable: set once during construction and never modified.
     #[instance(u32)]
     DecimalsDiff,
 
-    /// The address of the underlying token contract
+    /// The address of the underlying token contract.
+    /// Immutable: set once during construction and never modified.
     #[instance(Address)]
     Token,
 

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, #3001)")] // InvalidLocalDecimals
+#[should_panic(expected = "Error(Contract, #3002)")] // 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, #3003)")] // Overflow
+#[should_panic(expected = "Error(Contract, #3004)")] // Overflow
 fn test_to_sd_overflow() {
     let env = Env::default();