@layerzerolabs/protocol-stellar-v2 0.2.12 → 0.2.15

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

@@ -1,14 +1,36 @@
 use common_macros::{contract_impl, storage};
 use oapp_macros::oapp;
-use oft::oft::{oft_initialize, OFTInner, OFT};
-use oft::oft_types::{lock_unlock, mint_burn};
-use oft::types::OFTReceipt;
-use soroban_sdk::{Address, Env};
+use oft::{
+    default_oft_impl::{default_quote_oft, default_quote_send},
+    errors::OFTError,
+    extensions::{
+        oft_fee::{OFTFee, OFTFeeInternal},
+        pausable::{OFTPausable, OFTPausableInternal},
+        rate_limiter::{Direction, RateLimiter, RateLimiterInternal},
+    },
+    oft::{oft_initialize, OFTInternal, OFT},
+    oft_types::{lock_unlock, mint_burn},
+    storage::OFTStorage,
+    types::{OFTFeeDetail, OFTLimit, OFTReceipt, SendParam},
+    utils::remove_dust,
+};
+use soroban_sdk::{assert_with_error, contracttype, Address, Env, Vec};
+
+/// The mode of operation for the OFT contract
+#[contracttype]
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[repr(u8)]
+pub enum OFTMode {
+    /// Lock tokens on send, unlock on receive
+    LockUnlock = 0,
+    /// Burn tokens on send, mint on receive
+    MintBurn = 1,
+}
 
 #[storage]
 enum OFTStdStorage {
-    #[instance(bool)]
-    IsLockUnlock,
+    #[instance(OFTMode)]
+    Mode,
 }
 
 #[oapp]
@@ -23,37 +45,112 @@ impl OFTStd {
         endpoint: &Address,
         delegate: &Option<Address>,
         shared_decimals: u32,
-        is_lock_unlock: bool,
+        mode: OFTMode,
     ) {
         oft_initialize::<Self>(env, owner, token, endpoint, delegate, shared_decimals);
-        OFTStdStorage::set_is_lock_unlock(env, &is_lock_unlock);
+        OFTStdStorage::set_mode(env, &mode);
     }
 
-    /// Whether this OFT uses lock/unlock mode (true) or mint/burn mode (false)
-    pub fn is_lock_unlock(env: &Env) -> bool {
-        OFTStdStorage::is_lock_unlock(env).unwrap()
+    /// Returns the mode of operation for this OFT (LockUnlock or MintBurn)
+    pub fn mode(env: &Env) -> OFTMode {
+        OFTStdStorage::mode(env).unwrap()
     }
 }
 
-/// OFT trait implementation for standard OFT
+/// OFT trait implementation for standard OFT with extensions
 #[contract_impl(contracttrait)]
-impl OFT for OFTStd {}
+impl OFT for OFTStd {
+    fn quote_oft(env: &Env, send_param: &SendParam) -> (OFTLimit, Vec<OFTFeeDetail>, OFTReceipt) {
+        Self::__assert_not_paused(env);
+        let (_, fee_details, oft_receipt) = default_quote_oft::<Self>(env, send_param);
+        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)
+    }
+
+    fn quote_send(env: &Env, sender: &Address, send_param: &SendParam, pay_in_zro: bool) -> endpoint_v2::MessagingFee {
+        Self::__assert_not_paused(env);
+        default_quote_send::<Self>(env, sender, send_param, pay_in_zro)
+    }
+}
 
-/// OFT behavior for standard OFT
-impl OFTInner for OFTStd {
+/// OFT behavior for standard OFT with extension hooks
+impl OFTInternal for OFTStd {
     fn __debit(env: &Env, sender: &Address, amount_ld: i128, min_amount_ld: i128, dst_eid: u32) -> OFTReceipt {
-        if Self::is_lock_unlock(env) {
-            lock_unlock::debit::<Self>(env, sender, amount_ld, min_amount_ld, dst_eid)
-        } else {
-            mint_burn::debit::<Self>(env, sender, amount_ld, min_amount_ld, dst_eid)
-        }
+        // 1. Pausable check
+        Self::__assert_not_paused(env);
+
+        // 2. Core debit logic (based on mode)
+        let oft_receipt = match Self::mode(env) {
+            OFTMode::LockUnlock => lock_unlock::debit::<Self>(env, sender, amount_ld, min_amount_ld, dst_eid),
+            OFTMode::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 (amount_sent_ld - amount_received_ld)
+        Self::__charge_fee(env, &Self::token(env), sender, oft_receipt.amount_sent_ld - oft_receipt.amount_received_ld);
+
+        oft_receipt
     }
 
     fn __credit(env: &Env, to: &Address, amount_ld: i128, src_eid: u32) -> i128 {
-        if Self::is_lock_unlock(env) {
-            lock_unlock::credit::<Self>(env, to, amount_ld, src_eid)
-        } else {
-            mint_burn::credit::<Self>(env, to, amount_ld, src_eid)
-        }
+        // 1. Pausable check
+        Self::__assert_not_paused(env);
+
+        // 2. Core credit logic (based on mode)
+        let amount_credited = match Self::mode(env) {
+            OFTMode::LockUnlock => lock_unlock::credit::<Self>(env, to, amount_ld, src_eid),
+            OFTMode::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
+    }
+
+    fn __debit_view(env: &Env, amount_ld: i128, min_amount_ld: i128, dst_eid: u32) -> OFTReceipt {
+        let conversion_rate = OFTStorage::decimal_conversion_rate(env).unwrap();
+
+        // CRITICAL: Apply fee first, then remove dust
+        let amount_after_fee = Self::__fee_view(env, dst_eid, amount_ld);
+        let amount_received_ld = remove_dust(amount_after_fee, conversion_rate);
+
+        // amount_sent_ld logic:
+        // - If no fee: amount_sent_ld = amount_received_ld (both reduced by dust)
+        // - If fee applied: amount_sent_ld = original amount_ld (unchanged)
+        // This is to align the behavior with the fee extensions on other VMs
+        let amount_sent_ld = if amount_after_fee == amount_ld { amount_received_ld } else { amount_ld };
+
+        assert_with_error!(env, amount_received_ld >= min_amount_ld, OFTError::SlippageExceeded);
+
+        OFTReceipt { amount_sent_ld, amount_received_ld }
     }
 }
+
+// ==================== Extension Trait Implementations ====================
+
+/// Pausable extension - allows pausing/unpausing the OFT
+/// Default state: unpaused (all operations allowed)
+#[contract_impl(contracttrait)]
+impl OFTPausable for OFTStd {}
+
+impl OFTPausableInternal for OFTStd {}
+
+/// OFT Fee extension - allows collecting fees on transfers
+/// Default state: 0 BPS (no fee collected)
+#[contract_impl(contracttrait)]
+impl OFTFee for OFTStd {}
+
+impl OFTFeeInternal for OFTStd {}
+
+/// Rate Limiter extension - allows rate limiting transfers
+/// Default state: not set (rate_limit_capacity returns i128::MAX)
+#[contract_impl(contracttrait)]
+impl RateLimiter for OFTStd {}
+
+impl RateLimiterInternal for OFTStd {}

package/contracts/upgrader/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "upgrader"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish = false
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+doctest = false
+
+[dependencies]
+soroban-sdk = { workspace = true }
+utils = { workspace = true }
+common-macros = { workspace = true }
+
+[dev-dependencies]
+soroban-sdk = { workspace = true, features = ["testutils"] }
+

package/contracts/upgrader/src/lib.rs

@@ -0,0 +1,96 @@
+#![no_std]
+
+//! # Upgrader Contract
+//!
+//! A stateless utility contract for performing upgrade and migrate operations on upgradeable contracts.
+//!
+//! This contract provides a convenient way to upgrade other contracts, especially useful for
+//! performing upgrade+migrate atomically in a single transaction.
+//!
+//! ## Security Model
+//!
+//! The Upgrader is a permissionless utility - anyone can call it, but security is enforced
+//! by the target contract's ownership checks. When you call `upgrader.upgrade()`, the target
+//! contract's `#[only_owner]` guard ensures only the target's owner can successfully upgrade it.
+//!
+//! ## Usage
+//!
+//! Deploy this contract once, then anyone can use it to upgrade contracts they own.
+//!
+//! ```ignore
+//! // Deploy upgrader (no initialization needed)
+//! let upgrader_id = env.register(Upgrader, ());
+//! let upgrader = UpgraderClient::new(&env, &upgrader_id);
+//!
+//! // Upgrade a contract (you must be the target contract's owner)
+//! upgrader.upgrade(&target_contract, &new_wasm_hash);
+//!
+//! // Or upgrade and migrate in one transaction
+//! let migration_data = vec![&env, val1, val2];
+//! upgrader.upgrade_and_migrate(&target_contract, &new_wasm_hash, migration_data);
+//! ```
+
+use soroban_sdk::{contract, contractclient, contractimpl, symbol_short, Address, BytesN, Env, Symbol, Vec};
+
+/// Symbol for the migrate function call
+pub const MIGRATE: Symbol = symbol_short!("migrate");
+
+/// Trait representing an upgradeable contract's interface
+#[contractclient(name = "UpgradeableContractClient")]
+pub trait UpgradeableContract {
+    /// Upgrades the contract to new WASM bytecode
+    fn upgrade(env: &Env, new_wasm_hash: BytesN<32>);
+}
+
+/// Upgrader contract for managing upgrades of other contracts.
+///
+/// This is a stateless utility contract that anyone can use.
+/// Security is enforced by the target contract's ownership checks.
+#[contract]
+pub struct Upgrader;
+
+#[contractimpl]
+impl Upgrader {
+    /// Upgrade a target contract and run its migration in a single transaction
+    ///
+    /// The caller must be authorized as the owner of the target contract.
+    /// This is enforced by the target contract's `#[only_owner]` check.
+    ///
+    /// This is useful for atomic upgrades where you want to ensure the migration
+    /// happens immediately after the upgrade, or the entire operation fails.
+    ///
+    /// # Arguments
+    /// * `contract_address` - The address of the contract to upgrade
+    /// * `wasm_hash` - The hash of the new WASM bytecode
+    /// * `migration_data` - A vector of values to pass to the migrate function.
+    ///   The types of these values depend on the target contract's MigrationData type.
+    ///
+    /// # Example
+    /// ```ignore
+    /// // For a contract with MigrationData = (u32, bool)
+    /// let migration_data = vec![
+    ///     &env,
+    ///     42u32.into_val(&env),
+    ///     true.into_val(&env),
+    /// ];
+    /// upgrader.upgrade_and_migrate(&contract_addr, &wasm_hash, migration_data);
+    /// ```
+    pub fn upgrade_and_migrate(
+        env: &Env,
+        contract_address: &Address,
+        wasm_hash: BytesN<32>,
+        migration_data: Vec<soroban_sdk::Val>,
+    ) {
+        let contract_client = UpgradeableContractClient::new(env, contract_address);
+
+        // First upgrade the contract
+        contract_client.upgrade(&wasm_hash);
+
+        // Then call migrate with the provided data
+        // We use invoke_contract because the migration data type is unknown to this contract
+        env.invoke_contract::<()>(contract_address, &MIGRATE, migration_data);
+    }
+}
+
+#[cfg(test)]
+mod tests;

package/contracts/upgrader/src/tests/mod.rs

@@ -0,0 +1 @@
+pub mod test_upgrader;

package/contracts/upgrader/src/tests/test_upgrader.rs

@@ -0,0 +1,120 @@
+extern crate std;
+
+use soroban_sdk::{contractclient, testutils::Address as _, Address, BytesN, Env, TryIntoVal};
+
+use crate::{Upgrader, UpgraderClient};
+
+#[allow(dead_code)]
+#[contractclient(name = "TestUpgradeableContractClient")]
+trait TestUpgradeableContract {
+    fn counter(env: &Env) -> u32;
+}
+
+#[allow(dead_code)]
+#[contractclient(name = "TestUpgradeableContractClient2")]
+trait TestUpgradeableContract2 {
+    fn counter2(env: &Env) -> u32;
+}
+
+mod contract_v1 {
+    // #[contract]
+    // #[upgradeable]
+    // #[ownable]
+    // pub struct TestUpgradeableContract;
+
+    // impl UpgradeableInternal for TestUpgradeableContract {
+    //     type MigrationData = ();
+
+    //     fn _migrate(env: &Env, _migration_data: &Self::MigrationData) {
+    //         env.storage().instance().set(&Symbol::new(env, "counter"), &2);
+    //     }
+    // }
+
+    // #[contractclient(name = "TestUpgradeableClient")]
+    // trait TestUpgradeable {
+    //     fn counter(env: &Env) -> u32;
+    // }
+
+    // #[contract_impl]
+    // impl TestUpgradeable for TestUpgradeableContract {
+    //     fn counter(env: &Env) -> u32 {
+    //         env.storage().instance().get(&Symbol::new(env, "counter")).unwrap_or(0)
+    //     }
+    // }
+
+    // #[contract_impl]
+    // impl TestUpgradeableContract {
+    //     pub fn __constructor(env: &Env, owner: &Address) {
+    //         Self::init_owner(env, owner);
+    //         env.storage().instance().set(&Symbol::new(env, "counter"), &1_u32);
+    //     }
+    // }
+    use super::MigrationData;
+    soroban_sdk::contractimport!(file = "./src/tests/test_data/test_upgradeable_contract1.wasm");
+}
+mod contract_v2 {
+    // #[contract]
+    // #[upgradeable]
+    // #[ownable]
+    // pub struct TestUpgradeableContract;
+
+    // impl UpgradeableInternal for TestUpgradeableContract {
+    //     type MigrationData = ();
+
+    //     fn _migrate(env: &Env, _migration_data: &Self::MigrationData) {
+    //         env.storage().instance().set(&Symbol::new(env, "counter2"), &2_u32);
+    //     }
+    // }
+
+    // #[contractclient(name = "TestUpgradeableClient")]
+    // trait TestUpgradeable {
+    //     fn counter(env: &Env) -> u32;
+    //     fn counter2(env: &Env) -> u32;
+    // }
+
+    // #[contract_impl]
+    // impl TestUpgradeable for TestUpgradeableContract {
+    //     fn counter(env: &Env) -> u32 {
+    //         env.storage().instance().get(&Symbol::new(env, "counter")).unwrap_or(0)
+    //     }
+
+    //     fn counter2(env: &Env) -> u32 {
+    //         env.storage().instance().get(&Symbol::new(env, "counter2")).unwrap_or(0)
+    //     }
+    // }
+    use super::MigrationData;
+    soroban_sdk::contractimport!(file = "./src/tests/test_data/test_upgradeable_contract2.wasm");
+}
+
+fn install_new_wasm(e: &Env) -> BytesN<32> {
+    e.deployer().upload_contract_wasm(contract_v2::WASM)
+}
+
+#[allow(dead_code)]
+type MigrationData = ();
+
+#[test]
+fn test_upgrade_with_upgrader() {
+    let e = Env::default();
+    e.mock_all_auths_allowing_non_root_auth();
+
+    let owner = Address::generate(&e);
+    let contract_id = e.register(contract_v1::WASM, (&owner,));
+    let client_v1 = TestUpgradeableContractClient::new(&e, &contract_id);
+    assert_eq!(client_v1.counter(), 1);
+
+    let upgrader = e.register(Upgrader, ());
+    let upgrader_client = UpgraderClient::new(&e, &upgrader);
+
+    let new_wasm_hash = install_new_wasm(&e);
+
+    upgrader_client.upgrade_and_migrate(
+        &contract_id,
+        &new_wasm_hash,
+        &soroban_sdk::vec![&e, ().try_into_val(&e).unwrap()],
+    );
+
+    let client_v2 = TestUpgradeableContractClient2::new(&e, &contract_id);
+
+    assert_eq!(client_v2.counter2(), 2);
+}

package/contracts/utils/src/errors.rs

@@ -12,7 +12,7 @@ pub enum BufferWriterError {
 }
 
 #[contract_error]
-pub enum TtlError {
+pub enum TtlConfigurableError {
     InvalidTtlConfig = 1200,
     TtlConfigFrozen,
     TtlConfigAlreadyFrozen,
@@ -28,3 +28,8 @@ pub enum OwnableError {
 pub enum BytesExtError {
     LengthMismatch = 1400,
 }
+
+#[contract_error]
+pub enum UpgradeableError {
+    MigrationNotAllowed = 1500,
+}

package/contracts/utils/src/lib.rs

@@ -6,7 +6,8 @@ pub mod bytes_ext;
 pub mod errors;
 pub mod option_ext;
 pub mod ownable;
-pub mod ttl;
+pub mod ttl_configurable;
+pub mod upgradeable;
 
 #[cfg(test)]
 mod tests;

package/contracts/utils/src/ownable.rs

@@ -1,47 +1,11 @@
 use crate::errors::OwnableError;
 use crate::option_ext::OptionExt;
 use common_macros::storage;
-use soroban_sdk::{assert_with_error, contractclient, contractevent, Address, Env};
+use soroban_sdk::{assert_with_error, contractevent, contracttrait, Address, Env};
 
-// ============================================
-// Ownable Initializer Interface
-// ============================================
-
-/// Trait for initializing contract ownership.
-pub trait OwnableInitializer {
-    /// Initializes the owner. Should only be called once at contract initialization.
-    fn init_owner(env: &Env, owner: &Address);
-}
-
-// ============================================
-// Ownable Interface
-// ============================================
-
-/// Trait for contracts with single-owner access control.
-#[contractclient(name = "OwnableClient")]
-pub trait Ownable {
-    /// Returns the current owner address, or None if no owner is set.
-    fn owner(env: &Env) -> Option<Address>;
-
-    /// Transfers ownership to a new address. Requires current owner authorization.
-    fn transfer_ownership(env: &Env, new_owner: &Address);
-
-    /// Permanently renounces ownership. Requires current owner authorization.
-    fn renounce_ownership(env: &Env);
-}
-
-/// Enforces owner authorization and returns the owner address.
-/// Panics if no owner is set or authorization fails.
-pub fn enforce_owner_auth<T: Ownable>(env: &Env) -> Address {
-    let owner = T::owner(env).unwrap_or_panic(env, OwnableError::OwnerNotSet);
-    owner.require_auth();
-    owner
-}
-
-/// Enforces owner authorization without returning the address.
-pub fn require_owner_auth<T: Ownable>(env: &Env) {
-    let _ = enforce_owner_auth::<T>(env);
-}
+// ===========================================================================
+// Ownable events
+// ===========================================================================
 
 /// Event emitted when ownership is transferred.
 #[contractevent]
@@ -58,41 +22,65 @@ pub struct OwnershipRenounced {
     pub old_owner: Address,
 }
 
-// ============================================
-// Default Ownable Implementation
-// ============================================
-
-/// Default implementation of the Ownable trait using instance storage.
-pub struct DefaultOwnable;
+// ===========================================================================
+// Ownable storage for default implementation
+// ===========================================================================
 
-/// Storage keys for DefaultOwnable.
+/// Storage keys for Ownable.
 #[storage]
-pub enum DefaultOwnableStorage {
+pub enum OwnableStorage {
     #[instance(Address)]
     Owner,
 }
 
-impl Ownable for DefaultOwnable {
-    fn owner(env: &Env) -> Option<Address> {
-        DefaultOwnableStorage::owner(env)
+// ===========================================================================
+// Ownable trait with default implementation
+// ===========================================================================
+
+/// Trait for contracts with single-owner access control.
+#[contracttrait]
+pub trait Ownable: Sized {
+    /// Returns the current owner address, or None if no owner is set.
+    fn owner(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
+        OwnableStorage::owner(env)
     }
 
-    fn transfer_ownership(env: &Env, new_owner: &Address) {
-        let old_owner = Self::owner(env).unwrap_or_panic(env, OwnableError::OwnerNotSet);
-        DefaultOwnableStorage::set_owner(env, new_owner);
+    /// Transfers ownership to a new address. Requires current owner authorization.
+    fn transfer_ownership(env: &soroban_sdk::Env, new_owner: &soroban_sdk::Address) {
+        let old_owner = enforce_owner_auth::<Self>(env);
+        OwnableStorage::set_owner(env, new_owner);
         OwnershipTransferred { old_owner, new_owner: new_owner.clone() }.publish(env);
     }
 
-    fn renounce_ownership(env: &Env) {
-        let old_owner = Self::owner(env).unwrap_or_panic(env, OwnableError::OwnerNotSet);
-        DefaultOwnableStorage::remove_owner(env);
+    /// Permanently renounces ownership. Requires current owner authorization.
+    fn renounce_ownership(env: &soroban_sdk::Env) {
+        let old_owner = enforce_owner_auth::<Self>(env);
+        OwnableStorage::remove_owner(env);
         OwnershipRenounced { old_owner }.publish(env);
     }
 }
 
-impl OwnableInitializer for DefaultOwnable {
-    fn init_owner(env: &Env, owner: &Address) {
-        assert_with_error!(env, !DefaultOwnableStorage::has_owner(env), OwnableError::OwnerAlreadySet);
-        DefaultOwnableStorage::set_owner(env, owner);
+/// Trait for initializing the owner of the contract.
+pub trait OwnableInitializer {
+    fn init_owner(env: &soroban_sdk::Env, owner: &soroban_sdk::Address) {
+        assert_with_error!(env, !OwnableStorage::has_owner(env), OwnableError::OwnerAlreadySet);
+        OwnableStorage::set_owner(env, owner);
     }
 }
+
+// ===========================================================================
+// Ownable helper functions
+// ===========================================================================
+
+/// Enforces owner authorization and returns the owner address.
+/// Panics if no owner is set or authorization fails.
+pub fn enforce_owner_auth<T: Ownable>(env: &Env) -> Address {
+    let owner = T::owner(env).unwrap_or_panic(env, OwnableError::OwnerNotSet);
+    owner.require_auth();
+    owner
+}
+
+/// Enforces owner authorization without returning the address.
+pub fn require_owner_auth<T: Ownable>(env: &Env) {
+    let _ = enforce_owner_auth::<T>(env);
+}

package/contracts/utils/src/tests/mod.rs

@@ -1,7 +1,9 @@
 mod buffer_reader;
 mod buffer_writer;
 mod bytes_ext;
+mod option_ext;
 mod ownable;
 mod test_helper;
 mod testing_utils;
-mod ttl;
+mod ttl_configurable;
+mod upgradeable;

package/contracts/utils/src/tests/option_ext.rs

@@ -0,0 +1,21 @@
+use soroban_sdk::Env;
+
+use crate::{errors::OwnableError, option_ext::OptionExt};
+
+use crate::tests::test_helper::assert_panics_contains;
+
+#[test]
+fn unwrap_or_panic_some_returns_value() {
+    let env = Env::default();
+    let got = Some(123u32).unwrap_or_panic(&env, OwnableError::OwnerNotSet);
+    assert_eq!(got, 123);
+}
+
+#[test]
+fn unwrap_or_panic_none_panics_with_error() {
+    const EXPECTED: &str = "Error(Contract, #1301)";
+    assert_panics_contains("none unwrap_or_panic", EXPECTED, || {
+        let env = Env::default();
+        let _got: u32 = None::<u32>.unwrap_or_panic(&env, OwnableError::OwnerNotSet);
+    });
+}