@layerzerolabs/protocol-stellar-v2 0.2.18 → 0.2.19

package/contracts/oapps/oft/src/oft.rs

@@ -1,211 +1,173 @@
-//! OFT traits - the main interface for OFT contracts.
-//!
-//! This module provides two traits:
-//! - `OFTInternal`: Internal methods NOT exposed as contract endpoints (`__debit`, `__credit`, etc.)
-//! - `OFT`: Public methods exposed as contract endpoints (using `#[contracttrait]`)
-//!
-//! ## Usage
-//!
-//! ```ignore
-//! use oapp_macros::{oapp, oapp_options_type3};
-//! use oft::oft::{OFTInternal, OFT};
-//! use oft::initialize_oft;
-//!
-//! #[oapp]
-//! pub struct MyOFT;
-//!
-//! #[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)
-//!     }
-//! }
-//!
-//! // Public methods - exposed as contract endpoints
-//! #[contractimpl(contracttrait)]
-//! impl OFT for MyOFT {}
-//!
-//! // Internal methods - NOT exposed as contract endpoints
-//! // 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 {
-//!         // Your debit logic (e.g., burn or lock tokens)
-//!         oft::oft_types::mint_burn::debit::<Self>(env, sender, amount_ld, min_amount_ld, dst_eid)
-//!     }
-//!
-//!     fn __credit(env: &Env, to: &Address, amount_ld: i128, src_eid: u32) -> i128 {
-//!         // Your credit logic (e.g., mint or unlock tokens)
-//!         oft::oft_types::mint_burn::credit::<Self>(env, to, amount_ld, src_eid)
-//!     }
-//! }
-//! ```
-
-// Alias for the current crate, allowing `oft::types::SendParam` paths to work both
-// inside this crate and in external crates implementing the OFT trait.
-extern crate self as oft;
-
-use crate::{oft_impl, storage::OFTStorage, types::OFTReceipt};
-use common_macros::contract_trait;
-use oapp::{
-    oapp_core::OAppCore, oapp_options_type3::OAppOptionsType3, oapp_receiver::OAppReceiver,
-    oapp_sender::OAppSenderInternal,
+use crate::{
+    extensions::{
+        oft_fee::{OFTFee, OFTFeeInternal},
+        pausable::{OFTPausable, OFTPausableInternal},
+        rate_limiter::{Direction, RateLimiter, RateLimiterInternal},
+    },
+    oft_types::{lock_unlock, mint_burn, OftType},
 };
-use soroban_sdk::{Address, Bytes, Env};
-
-// =====================================================
-// OFTInternal Trait (NOT exposed as contract endpoints)
-// =====================================================
-
-/// Internal OFT trait containing methods that should NOT be exposed as contract endpoints.
-///
-/// **IMPORTANT**: Implement this trait WITHOUT the `#[contractimpl]` macro to keep
-/// `__debit`, `__credit`, and other internal methods private to the contract.
-///
-/// ```ignore
-/// // Correct - methods stay internal
-/// impl OFTInternal for MyOFT { ... }
-///
-/// // WRONG - would expose methods as endpoints
-/// #[contractimpl]
-/// 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 `OFT` instead, keeping this trait focused on token logic.
-pub trait OFTInternal: OAppCore {
-    // =========================================================================
-    // Required Methods (no defaults - user MUST implement)
-    // =========================================================================
-
-    /// Debits tokens from the specified address for cross-chain transfer.
-    ///
-    /// # Arguments
-    /// * `from` - The address to debit the tokens from
-    /// * `amount_ld` - The amount of tokens to send in local decimals
-    /// * `min_amount_ld` - The minimum amount to send in local decimals
-    /// * `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;
-
-    /// Credits tokens to recipient after receiving cross-chain transfer.
-    ///
-    /// # Arguments
-    /// * `to` - The address to credit tokens to
-    /// * `amount_ld` - Amount in local decimals to credit
-    /// * `src_eid` - Source endpoint ID
-    ///
-    /// # Returns
-    /// The amount actually credited
-    fn __credit(env: &Env, to: &Address, amount_ld: i128, src_eid: u32) -> i128;
-
-    // =========================================================================
-    // 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 {
-        oft_impl::debit_view(env, amount_ld, min_amount_ld, dst_eid)
-    }
+use common_macros::{contract_impl, storage};
+use endpoint_v2::{MessagingFee, Origin};
+use oapp::oapp_receiver::LzReceiveInternal;
+use oapp_macros::oapp;
+use oft_core::{
+    errors::OFTError,
+    types::{OFTFeeDetail, OFTLimit, OFTReceipt, SendParam},
+    utils as oft_utils, OFTCore, OFTInternal,
+};
+use soroban_sdk::{assert_with_error, vec, Address, Bytes, BytesN, Env, Vec};
+
+#[storage]
+enum OFTStorage {
+    #[instance(OftType)]
+    OftType,
+}
 
-    /// Builds OFT message and combines options for cross-chain transfer.
-    fn __build_msg_and_options(
+#[oapp]
+pub struct OFT;
+
+#[contract_impl]
+impl OFT {
+    pub fn __constructor(
         env: &Env,
-        from: &Address,
-        send_param: &oft::types::SendParam,
-        receive_amount_ld: i128,
-    ) -> (Bytes, Bytes)
-    where
-        Self: OAppOptionsType3,
-    {
-        oft_impl::build_msg_and_options::<Self>(env, from, send_param, receive_amount_ld)
+        token: &Address,
+        owner: &Address,
+        endpoint: &Address,
+        delegate: &Option<Address>,
+        shared_decimals: u32,
+        oft_type: OftType,
+    ) {
+        oft_core::initialize_oft::<Self>(env, owner, token, endpoint, delegate, shared_decimals);
+        OFTStorage::set_oft_type(env, &oft_type);
+    }
+
+    /// Returns the type of operation for this OFT (LockUnlock or MintBurn)
+    pub fn oft_type(env: &Env) -> OftType {
+        OFTStorage::oft_type(env).unwrap()
     }
 }
 
-// =====================================================
-// OFT Trait (exposed as contract endpoints)
-// =====================================================
-
-/// The public OFT trait defining the cross-chain token transfer interface.
-///
-/// This trait is marked with `#[contracttrait]` so all its methods are exposed as
-/// contract endpoints. 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 endpoints.
-#[contract_trait]
-pub trait OFT: OFTInternal + OAppReceiver + OAppSenderInternal + OAppOptionsType3 {
-    /// Retrieves the token address associated with this OFT.
-    fn token(env: &Env) -> Address {
-        OFTStorage::token(env).unwrap()
+/// OFTCore trait implementation for standard OFT with extensions
+#[contract_impl(contracttrait)]
+impl OFTCore for OFT {
+    fn quote_oft(env: &Env, send_param: &SendParam) -> (OFTLimit, Vec<OFTFeeDetail>, OFTReceipt) {
+        Self::__assert_not_paused(env);
+
+        let oft_receipt = Self::__debit_view(env, send_param.amount_ld, send_param.min_amount_ld, send_param.dst_eid);
+
+        // fee details (only include if there's an actual fee)
+        let fee_amount_ld = oft_receipt.amount_sent_ld - oft_receipt.amount_received_ld;
+        let fee_details = if fee_amount_ld > 0 {
+            vec![env, OFTFeeDetail { fee_amount_ld, description: Bytes::from_slice(env, b"OFT Fee") }]
+        } else {
+            vec![env]
+        };
+
+        // rate limit capacity
+        let capacity = Self::rate_limit_capacity(env, &Direction::Outbound, send_param.dst_eid);
+        let oft_limit = OFTLimit { min_amount_ld: 0, max_amount_ld: capacity };
+
+        (oft_limit, fee_details, oft_receipt)
     }
 
-    /// Returns OFT version as (major, minor).
-    fn oft_version(_env: &Env) -> (u64, u64) {
-        (1, 1)
+    fn quote_send(env: &Env, sender: &Address, send_param: &SendParam, pay_in_zro: bool) -> MessagingFee {
+        Self::__assert_not_paused(env);
+        oft_core::quote_send::<Self>(env, sender, send_param, pay_in_zro)
     }
+}
 
-    /// Retrieves the shared decimals used for cross-chain normalization.
-    fn shared_decimals(env: &Env) -> u32 {
-        let token = Self::token(env);
-        let local_decimals = soroban_sdk::token::TokenClient::new(env, &token).decimals();
+/// OFT behavior for standard OFT with extension hooks
+impl OFTInternal for OFT {
+    fn __debit_view(env: &Env, amount_ld: i128, min_amount_ld: i128, dst_eid: u32) -> OFTReceipt {
         let conversion_rate = Self::decimal_conversion_rate(env);
-        local_decimals - conversion_rate.ilog10()
-    }
 
-    /// Retrieves the decimal conversion rate used for cross-chain normalization.
-    fn decimal_conversion_rate(env: &Env) -> i128 {
-        OFTStorage::decimal_conversion_rate(env).unwrap()
-    }
+        // Apply the fee before dust removal to ensure the fee is calculated on the full amount and dust is not transferred
+        let fee = Self::__fee_view(env, dst_eid, amount_ld);
+        let amount_after_fee = amount_ld - fee;
+        let amount_received_ld = oft_utils::remove_dust(amount_after_fee, conversion_rate);
+
+        // amount_sent_ld = what recipient receives + fee charged
+        // Dust is excluded (stays with sender)
+        let amount_sent_ld = amount_received_ld + fee;
+
+        assert_with_error!(env, amount_received_ld >= min_amount_ld, OFTError::SlippageExceeded);
 
-    /// Whether a separate token approval is required before sending.
-    ///
-    /// Helps wallet implementers determine integration requirements.
-    ///
-    /// # Returns
-    /// - `true` if a separate token approval step is required
-    /// - `false` if no separate approval is needed
-    fn approval_required(_env: &Env) -> bool {
-        false
+        OFTReceipt { amount_sent_ld, amount_received_ld }
     }
 
-    /// Quotes an OFT transfer without executing.
-    ///
-    /// # Returns
-    /// (OFTLimit, fee details, receipt with estimated amounts)
-    fn quote_oft(
-        env: &Env,
-        send_param: &oft::types::SendParam,
-    ) -> (oft::types::OFTLimit, soroban_sdk::Vec<oft::types::OFTFeeDetail>, oft::types::OFTReceipt) {
-        oft_impl::quote_oft::<Self>(env, send_param)
+    fn __debit(env: &Env, sender: &Address, amount_ld: i128, min_amount_ld: i128, dst_eid: u32) -> OFTReceipt {
+        // 1. Pausable check
+        Self::__assert_not_paused(env);
+
+        // 2. Core debit logic (based on oft_type)
+        let oft_receipt = match Self::oft_type(env) {
+            OftType::LockUnlock => lock_unlock::debit::<Self>(env, sender, amount_ld, min_amount_ld, dst_eid),
+            OftType::MintBurn => mint_burn::debit::<Self>(env, sender, amount_ld, min_amount_ld, dst_eid),
+        };
+
+        // 3. Rate limit checks (using amount_received_ld - the actual cross-chain amount)
+        Self::__consume_rate_limit_capacity(env, &Direction::Outbound, dst_eid, oft_receipt.amount_received_ld);
+        Self::__release_rate_limit_capacity(env, &Direction::Inbound, dst_eid, oft_receipt.amount_received_ld);
+
+        // 4. Charge fee
+        let fee = oft_receipt.amount_sent_ld - oft_receipt.amount_received_ld;
+        Self::__charge_fee(env, &Self::token(env), sender, fee);
+
+        oft_receipt
     }
 
-    /// Quotes a send operation including LayerZero messaging fees.
-    fn quote_send(
-        env: &Env,
-        sender: &Address,
-        send_param: &oft::types::SendParam,
-        pay_in_zro: bool,
-    ) -> endpoint_v2::MessagingFee {
-        oft_impl::quote_send::<Self>(env, sender, send_param, pay_in_zro)
+    fn __credit(env: &Env, to: &Address, amount_ld: i128, src_eid: u32) -> i128 {
+        // 1. Pausable check
+        Self::__assert_not_paused(env);
+
+        // 2. Core credit logic (based on mode)
+        let amount_credited = match Self::oft_type(env) {
+            OftType::LockUnlock => lock_unlock::credit::<Self>(env, to, amount_ld, src_eid),
+            OftType::MintBurn => mint_burn::credit::<Self>(env, to, amount_ld, src_eid),
+        };
+
+        // 3. Rate limit checks (using amount_credited - the actual credited amount)
+        Self::__consume_rate_limit_capacity(env, &Direction::Inbound, src_eid, amount_credited);
+        Self::__release_rate_limit_capacity(env, &Direction::Outbound, src_eid, amount_credited);
+
+        amount_credited
     }
+}
 
-    /// Sends tokens cross-chain to another endpoint.
-    ///
-    /// Sender must be authenticated.
-    ///
-    /// # Returns
-    /// (MessagingReceipt, OFTReceipt)
-    fn send(
+/// LzReceiveInternal implementation using default OFT receive logic
+impl LzReceiveInternal for OFT {
+    fn __lz_receive(
         env: &Env,
-        sender: &Address,
-        send_param: &oft::types::SendParam,
-        fee: &endpoint_v2::MessagingFee,
-        refund_address: &Address,
-    ) -> (endpoint_v2::MessagingReceipt, oft::types::OFTReceipt) {
-        oft_impl::send::<Self>(env, sender, send_param, fee, refund_address)
+        origin: &Origin,
+        guid: &BytesN<32>,
+        message: &Bytes,
+        extra_data: &Bytes,
+        executor: &Address,
+        value: i128,
+    ) {
+        oft_core::lz_receive::<Self>(env, executor, origin, guid, message, extra_data, value)
     }
 }
+
+// ==================== Extension Trait Implementations ====================
+
+/// Pausable extension - allows pausing/unpausing the OFT
+/// Default state: unpaused (all operations allowed)
+#[contract_impl(contracttrait)]
+impl OFTPausable for OFT {}
+
+impl OFTPausableInternal for OFT {}
+
+/// OFT Fee extension - allows collecting fees on transfers
+/// Default state: 0 BPS (no fee collected)
+#[contract_impl(contracttrait)]
+impl OFTFee for OFT {}
+
+impl OFTFeeInternal for OFT {}
+
+/// Rate Limiter extension - allows rate limiting transfers
+/// Default state: not set (rate_limit_capacity returns i128::MAX)
+#[contract_impl(contracttrait)]
+impl RateLimiter for OFT {}
+
+impl RateLimiterInternal for OFT {}

package/contracts/oapps/oft/src/oft_types/lock_unlock.rs

@@ -4,7 +4,7 @@
 //! tokens from the contract on credit (receive).
 //! Used for OFT adapters that wrap existing tokens.
 
-use crate::{oft::OFT, types::OFTReceipt};
+use oft_core::{oft_core::OFTCore, types::OFTReceipt};
 use soroban_sdk::{token::TokenClient, Address, Env};
 
 /// Debit tokens using LockUnlock OFT type (locks tokens in contract).
@@ -18,7 +18,13 @@ use soroban_sdk::{token::TokenClient, Address, Env};
 ///
 /// # Returns
 /// `OFTReceipt` containing the amount sent and amount received
-pub fn debit<T: OFT>(env: &Env, sender: &Address, amount_ld: i128, min_amount_ld: i128, dst_eid: u32) -> OFTReceipt {
+pub fn debit<T: OFTCore>(
+    env: &Env,
+    sender: &Address,
+    amount_ld: i128,
+    min_amount_ld: i128,
+    dst_eid: u32,
+) -> OFTReceipt {
     let receipt: OFTReceipt = T::__debit_view(env, amount_ld, min_amount_ld, dst_eid);
     TokenClient::new(env, &T::token(env)).transfer(sender, env.current_contract_address(), &receipt.amount_received_ld);
     receipt
@@ -34,15 +40,7 @@ pub fn debit<T: OFT>(env: &Env, sender: &Address, amount_ld: i128, min_amount_ld
 ///
 /// # Returns
 /// The amount credited
-pub fn credit<T: OFT>(env: &Env, to: &Address, amount_ld: i128, _src_eid: u32) -> i128 {
+pub fn credit<T: OFTCore>(env: &Env, to: &Address, amount_ld: i128, _src_eid: u32) -> i128 {
     TokenClient::new(env, &T::token(env)).transfer(&env.current_contract_address(), to, &amount_ld);
     amount_ld
 }
-
-/// Returns whether approval is required for LockUnlock OFT type.
-///
-/// # Returns
-/// Always `false` - approval not needed for transfer operations
-pub fn approval_required() -> bool {
-    false
-}

package/contracts/oapps/oft/src/oft_types/mint_burn.rs

@@ -3,8 +3,30 @@
 //! This OFT type burns tokens on debit (send) and mints tokens on credit (receive).
 //! Used when the OFT contract has mint/burn authority over the token.
 
-use crate::{interfaces::MintBurnTokenClient, oft::OFT, types::OFTReceipt};
-use soroban_sdk::{Address, Env};
+use oft_core::{oft_core::OFTCore, types::OFTReceipt};
+use soroban_sdk::{contractclient, Address, Env};
+
+/// Contract interface for mint and burn token operations.
+///
+/// This interface abstracts the token mint/burn functionality, allowing different
+/// token implementations (e.g., StellarAssetContract, custom tokens) to be used
+/// with the MintBurn OFT.
+#[contractclient(name = "MintBurnTokenClient")]
+pub trait MintBurnToken {
+    /// Mints tokens to the specified address.
+    ///
+    /// # Parameters
+    /// * `to` - The address to mint tokens to
+    /// * `amount` - The amount of tokens to mint (must be non-negative)
+    fn mint(env: Env, to: Address, amount: i128);
+
+    /// Burns tokens from the specified address.
+    ///
+    /// # Parameters
+    /// * `from` - The address to burn tokens from
+    /// * `amount` - The amount of tokens to burn (must be non-negative)
+    fn burn(env: Env, from: Address, amount: i128);
+}
 
 /// Debit tokens using MintBurn OFT type (burns tokens from sender).
 ///
@@ -17,7 +39,13 @@ use soroban_sdk::{Address, Env};
 ///
 /// # Returns
 /// `OFTReceipt` containing the amount sent and amount received
-pub fn debit<T: OFT>(env: &Env, sender: &Address, amount_ld: i128, min_amount_ld: i128, dst_eid: u32) -> OFTReceipt {
+pub fn debit<T: OFTCore>(
+    env: &Env,
+    sender: &Address,
+    amount_ld: i128,
+    min_amount_ld: i128,
+    dst_eid: u32,
+) -> OFTReceipt {
     let receipt = T::__debit_view(env, amount_ld, min_amount_ld, dst_eid);
     MintBurnTokenClient::new(env, &T::token(env)).burn(sender, &receipt.amount_received_ld);
     receipt
@@ -33,15 +61,7 @@ pub fn debit<T: OFT>(env: &Env, sender: &Address, amount_ld: i128, min_amount_ld
 ///
 /// # Returns
 /// The amount credited
-pub fn credit<T: OFT>(env: &Env, to: &Address, amount_ld: i128, _src_eid: u32) -> i128 {
+pub fn credit<T: OFTCore>(env: &Env, to: &Address, amount_ld: i128, _src_eid: u32) -> i128 {
     MintBurnTokenClient::new(env, &T::token(env)).mint(to, &amount_ld);
     amount_ld
 }
-
-/// Returns whether approval is required for MintBurn OFT type.
-///
-/// # Returns
-/// Always `false` - approval not needed for mint/burn operations.
-pub fn approval_required() -> bool {
-    false
-}

package/contracts/oapps/oft/src/oft_types/mod.rs

@@ -6,5 +6,18 @@
 //! - **LockUnlock**: Locks tokens on send, unlocks on receive. Approval not required.
 //!
 
+use soroban_sdk::contracttype;
+
 pub mod lock_unlock;
 pub mod mint_burn;
+
+/// The type of OFT operation mode
+#[contracttype]
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[repr(u8)]
+pub enum OftType {
+    /// Lock tokens on send, unlock on receive
+    LockUnlock = 0,
+    /// Burn tokens on send, mint on receive
+    MintBurn = 1,
+}

package/contracts/oapps/{oft-std → oft-core}/Cargo.toml

@@ -1,11 +1,11 @@
 [package]
-name = "oft-std"
+name = "oft-core"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
 
 [lib]
-crate-type = ["cdylib"]
+crate-type = ["rlib"]
 doctest = false
 
 [dependencies]
@@ -14,8 +14,6 @@ endpoint-v2 = { workspace = true, features = ["library"] }
 utils = { workspace = true }
 oapp = { workspace = true }
 common-macros = { workspace = true }
-oapp-macros = { workspace = true }
-oft = { workspace = true }
 
 [dev-dependencies]
 soroban-sdk = { workspace = true, features = ["testutils"] }
@@ -23,3 +21,7 @@ simple-message-lib = { workspace = true }
 message-lib-common = { workspace = true, features = ["testutils"] }
 endpoint-v2 = { workspace = true, features = ["testutils"] }
 utils = { workspace = true, features = ["testutils"] }
+insta = { workspace = true }
+oapp-macros = { workspace = true }
+stellar-macros = { workspace = true }
+stellar-tokens = { workspace = true }

package/contracts/oapps/{oft-std → oft-core}/integration-tests/mod.rs

@@ -1,3 +1,3 @@
-pub mod extensions;
 pub mod setup;
+pub mod test_with_sml;
 pub mod utils;