@layerzerolabs/protocol-stellar-v2 0.2.13 → 0.2.18

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

@@ -1,14 +1,39 @@
 use common_macros::{contract_impl, storage};
+use endpoint_v2::Origin;
+use oapp::oapp_receiver::LzReceiveInternal;
 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::{
+    errors::OFTError,
+    extensions::{
+        oft_fee::{OFTFee, OFTFeeInternal},
+        pausable::{OFTPausable, OFTPausableInternal},
+        rate_limiter::{Direction, RateLimiter, RateLimiterInternal},
+    },
+    initialize_oft,
+    oft::{OFTInternal, OFT},
+    oft_impl,
+    oft_types::{lock_unlock, mint_burn},
+    storage::OFTStorage,
+    types::{OFTFeeDetail, OFTLimit, OFTReceipt, SendParam},
+    utils::remove_dust,
+};
+use soroban_sdk::{assert_with_error, contracttype, Address, Bytes, BytesN, 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 +48,127 @@ 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);
+        initialize_oft::<Self>(env, owner, token, endpoint, delegate, shared_decimals);
+        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
+/// LzReceiveInternal implementation using default OFT receive logic
+impl LzReceiveInternal for OFTStd {
+    fn __lz_receive(
+        env: &Env,
+        origin: &Origin,
+        guid: &BytesN<32>,
+        message: &Bytes,
+        extra_data: &Bytes,
+        executor: &Address,
+        value: i128,
+    ) {
+        oft_impl::lz_receive::<Self>(env, executor, origin, guid, message, extra_data, value)
+    }
+}
+
+/// 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) = oft_impl::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)
+    }
 
-/// OFT behavior for standard OFT
-impl OFTInner for OFTStd {
+    fn quote_send(env: &Env, sender: &Address, send_param: &SendParam, pay_in_zro: bool) -> endpoint_v2::MessagingFee {
+        Self::__assert_not_paused(env);
+        oft_impl::quote_send::<Self>(env, sender, send_param, pay_in_zro)
+    }
+}
+
+/// 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 authorization checks. When you call `upgrader.upgrade()`, the target
+//! contract's `#[only_auth]` guard ensures only the target's authorizer 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 authorizer of the target contract.
+    /// This is enforced by the target contract's `#[only_auth]` 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/auth.rs

@@ -0,0 +1,44 @@
+//! Base authorization trait for owner-protected operations.
+//!
+//! The `Auth` trait provides a common interface for authorization that can be
+//! implemented by different access control patterns (e.g., single owner, multisig).
+
+use soroban_sdk::{contractclient, Address, Env};
+
+// ===========================================================================
+// Auth trait
+// ===========================================================================
+
+/// Base trait for authorization.
+///
+/// Provides the authorizer address for owner-protected operations. This trait
+/// is implemented by both `Ownable` (external owner) and `Multisig` (self-owning).
+#[contractclient(name = "AuthClient")]
+pub trait Auth: Sized {
+    /// Returns the address that authorizes owner-protected operations.
+    ///
+    /// For `Ownable` contracts, this returns the stored owner address.
+    /// For `Multisig` contracts, this returns the contract's own address
+    /// (self-owning pattern).
+    fn authorizer(env: &Env) -> Address;
+}
+
+// ===========================================================================
+// Auth helper functions
+// ===========================================================================
+
+/// Enforces authorization from the authorizer and returns the authorizer address.
+///
+/// Panics if the authorizer has not provided authorization for this invocation.
+pub fn enforce_auth<T: Auth>(env: &Env) -> Address {
+    let authorizer = T::authorizer(env);
+    authorizer.require_auth();
+    authorizer
+}
+
+/// Requires authorization from the authorizer.
+///
+/// Panics if the authorizer has not provided authorization for this invocation.
+pub fn require_auth<T: Auth>(env: &Env) {
+    let _ = enforce_auth::<T>(env);
+}

package/contracts/utils/src/errors.rs

@@ -1,30 +1,57 @@
 use common_macros::contract_error;
 
+// Utils library error codes: 1000-1099
+// See ERROR_SPEC.md for allocation rules
+
+/// BufferReaderError: 1000-1009
 #[contract_error]
 pub enum BufferReaderError {
     InvalidLength = 1000,
     InvalidAddressPayload,
 }
 
+/// BufferWriterError: 1010-1019
 #[contract_error]
 pub enum BufferWriterError {
-    InvalidAddressPayload = 1100,
+    InvalidAddressPayload = 1010,
 }
 
+/// TtlConfigurableError: 1020-1029
 #[contract_error]
-pub enum TtlError {
-    InvalidTtlConfig = 1200,
+pub enum TtlConfigurableError {
+    InvalidTtlConfig = 1020,
     TtlConfigFrozen,
     TtlConfigAlreadyFrozen,
 }
 
+/// OwnableError: 1030-1039
 #[contract_error]
 pub enum OwnableError {
-    OwnerAlreadySet = 1300,
+    OwnerAlreadySet = 1030,
     OwnerNotSet,
 }
 
+/// BytesExtError: 1040-1049
 #[contract_error]
 pub enum BytesExtError {
-    LengthMismatch = 1400,
+    LengthMismatch = 1040,
+}
+
+/// UpgradeableError: 1050-1059
+#[contract_error]
+pub enum UpgradeableError {
+    MigrationNotAllowed = 1050,
+}
+
+/// MultisigError: 1060-1069
+#[contract_error]
+pub enum MultisigError {
+    AlreadyInitialized = 1060,
+    InvalidSigner,
+    SignatureError,
+    SignerAlreadyExists,
+    SignerNotFound,
+    TotalSignersLessThanThreshold,
+    UnsortedSigners,
+    ZeroThreshold,
 }

package/contracts/utils/src/lib.rs

@@ -1,12 +1,16 @@
 #![no_std]
 
+pub mod auth;
 pub mod buffer_reader;
 pub mod buffer_writer;
 pub mod bytes_ext;
 pub mod errors;
+pub mod multisig;
 pub mod option_ext;
 pub mod ownable;
-pub mod ttl;
+pub mod ttl_configurable;
+pub mod ttl_extendable;
+pub mod upgradeable;
 
 #[cfg(test)]
 mod tests;