@layerzerolabs/protocol-stellar-v2 0.2.15 → 0.2.19

package/contracts/oapps/{oft → oft-core}/src/tests/test_utils.rs

@@ -2,17 +2,19 @@
 //!
 //! This module provides common test contracts and helpers used across multiple test files.
 
-use crate::codec::oft_msg_codec::OFTMessage;
-use crate::oft::OFTClient;
-use crate::types::{OFTReceipt, SendParam};
+use crate::{
+    codec::oft_msg_codec::OFTMessage,
+    oft_core::OFTClient,
+    types::{OFTReceipt, SendParam},
+};
 use endpoint_v2::{LayerZeroReceiverClient, MessagingFee, MessagingParams, MessagingReceipt, Origin};
 use oapp::oapp_core::OAppCoreClient;
-use soroban_sdk::{address_payload::AddressPayload, log, String};
 use soroban_sdk::{
-    bytes, contract, contractimpl, symbol_short,
+    address_payload::AddressPayload,
+    bytes, contract, contractimpl, log, symbol_short,
     testutils::{Address as _, MockAuth, MockAuthInvoke},
     token::{StellarAssetClient, TokenClient},
-    Address, Bytes, BytesN, Env, IntoVal, Symbol,
+    Address, Bytes, BytesN, Env, IntoVal, String, Symbol,
 };
 use stellar_macros::default_impl;
 use stellar_tokens::fungible::{Base, FungibleToken};
@@ -102,11 +104,21 @@ pub fn create_origin(src_eid: u32, sender: &BytesN<32>, nonce: u64) -> Origin {
 // ==================== Test OFT Contracts ====================
 
 mod test_mint_burn_oft {
-    extern crate self as oft;
+    use crate::{
+        self as oft_core,
+        oft_core::{initialize_oft, lz_receive, OFTCore, OFTInternal},
+        types::OFTReceipt,
+    };
+    use endpoint_v2::Origin;
+    use oapp::oapp_receiver::LzReceiveInternal;
+    use soroban_sdk::{contractclient, contractimpl, Address, Bytes, BytesN, Env};
 
-    use crate::oft::{oft_initialize, OFTInternal, OFT};
-    use crate::types::OFTReceipt;
-    use soroban_sdk::{contractimpl, Address, Env};
+    #[contractclient(name = "MintBurnTokenClient")]
+    #[allow(dead_code)]
+    trait MintBurnToken {
+        fn mint(env: Env, to: Address, amount: i128);
+        fn burn(env: Env, from: Address, amount: i128);
+    }
 
     #[oapp_macros::oapp]
     pub struct TestMintBurnOFT;
@@ -121,37 +133,55 @@ mod test_mint_burn_oft {
             delegate: &Option<Address>,
             shared_decimals: u32,
         ) {
-            oft_initialize::<Self>(env, owner, token, endpoint, delegate, shared_decimals)
+            initialize_oft::<Self>(env, owner, token, endpoint, delegate, shared_decimals)
         }
     }
 
     #[contractimpl(contracttrait)]
-    impl OFT for TestMintBurnOFT {}
+    impl OFTCore for TestMintBurnOFT {}
+
+    impl LzReceiveInternal for TestMintBurnOFT {
+        fn __lz_receive(
+            env: &Env,
+            origin: &Origin,
+            guid: &BytesN<32>,
+            message: &Bytes,
+            extra_data: &Bytes,
+            executor: &Address,
+            value: i128,
+        ) {
+            lz_receive::<Self>(env, executor, origin, guid, message, extra_data, value)
+        }
+    }
 
     impl OFTInternal for TestMintBurnOFT {
         fn __debit(env: &Env, sender: &Address, amount_ld: i128, min_amount_ld: i128, dst_eid: u32) -> OFTReceipt {
-            crate::oft_types::mint_burn::debit::<Self>(env, sender, amount_ld, min_amount_ld, dst_eid)
+            // Inline mint_burn::debit implementation
+            let receipt = Self::__debit_view(env, amount_ld, min_amount_ld, dst_eid);
+            MintBurnTokenClient::new(env, &Self::token(env)).burn(sender, &receipt.amount_received_ld);
+            receipt
         }
 
-        fn __credit(env: &Env, to: &Address, amount_ld: i128, src_eid: u32) -> i128 {
-            crate::oft_types::mint_burn::credit::<Self>(env, to, amount_ld, src_eid)
+        fn __credit(env: &Env, to: &Address, amount_ld: i128, _src_eid: u32) -> i128 {
+            // Inline mint_burn::credit implementation
+            MintBurnTokenClient::new(env, &Self::token(env)).mint(to, &amount_ld);
+            amount_ld
         }
     }
 }
 pub use test_mint_burn_oft::TestMintBurnOFT;
 
 mod test_lock_unlock_oft {
-    extern crate self as oft;
-
-    use crate::oft::{oft_initialize, OFTInternal, OFT};
-    use crate::types::OFTReceipt;
+    use crate::{
+        self as oft_core,
+        oft_core::{initialize_oft, lz_receive, OFTCore, OFTInternal},
+        types::OFTReceipt,
+    };
     use endpoint_v2::Origin;
-    use oapp::oapp_receiver::OAppReceiver;
-    use oapp_macros::oapp_manual_impl;
-    use soroban_sdk::{contractimpl, Address, Bytes, BytesN, Env};
+    use oapp::oapp_receiver::{LzReceiveInternal, OAppReceiver};
+    use soroban_sdk::{contractimpl, token::TokenClient, Address, Bytes, BytesN, Env};
 
-    #[oapp_macros::oapp]
-    #[oapp_manual_impl(receiver)]
+    #[oapp_macros::oapp(custom = [receiver])]
     pub struct TestLockUnlockOFT;
 
     #[contractimpl]
@@ -164,36 +194,47 @@ mod test_lock_unlock_oft {
             delegate: &Option<Address>,
             shared_decimals: u32,
         ) {
-            oft_initialize::<Self>(env, owner, token, endpoint, delegate, shared_decimals)
+            initialize_oft::<Self>(env, owner, token, endpoint, delegate, shared_decimals)
         }
     }
 
     #[contractimpl(contracttrait)]
-    impl OFT for TestLockUnlockOFT {}
+    impl OFTCore for TestLockUnlockOFT {}
 
-    #[contractimpl(contracttrait)]
-    impl OAppReceiver for TestLockUnlockOFT {
-        fn lz_receive(
+    impl LzReceiveInternal for TestLockUnlockOFT {
+        fn __lz_receive(
             env: &Env,
-            executor: &Address,
             origin: &Origin,
             guid: &BytesN<32>,
             message: &Bytes,
             extra_data: &Bytes,
+            executor: &Address,
             value: i128,
         ) {
-            oapp::oapp_receiver::verify_and_clear_payload::<Self>(env, executor, origin, guid, message, value);
-            Self::__lz_receive(env, executor, origin, guid, message, extra_data, value);
+            lz_receive::<Self>(env, executor, origin, guid, message, extra_data, value)
         }
     }
 
+    // Custom receiver to demonstrate overriding next_nonce or other methods
+    #[contractimpl(contracttrait)]
+    impl OAppReceiver for TestLockUnlockOFT {}
+
     impl OFTInternal for TestLockUnlockOFT {
         fn __debit(env: &Env, sender: &Address, amount_ld: i128, min_amount_ld: i128, dst_eid: u32) -> OFTReceipt {
-            crate::oft_types::lock_unlock::debit::<Self>(env, sender, amount_ld, min_amount_ld, dst_eid)
+            // Inline lock_unlock::debit implementation
+            let receipt: OFTReceipt = Self::__debit_view(env, amount_ld, min_amount_ld, dst_eid);
+            TokenClient::new(env, &Self::token(env)).transfer(
+                sender,
+                env.current_contract_address(),
+                &receipt.amount_received_ld,
+            );
+            receipt
         }
 
-        fn __credit(env: &Env, to: &Address, amount_ld: i128, src_eid: u32) -> i128 {
-            crate::oft_types::lock_unlock::credit::<Self>(env, to, amount_ld, src_eid)
+        fn __credit(env: &Env, to: &Address, amount_ld: i128, _src_eid: u32) -> i128 {
+            // Inline lock_unlock::credit implementation
+            TokenClient::new(env, &Self::token(env)).transfer(&env.current_contract_address(), to, &amount_ld);
+            amount_ld
         }
     }
 }
@@ -265,12 +306,12 @@ impl MockEndpointWithCompose {
         env.storage().instance().set(&symbol_short!("zro"), &zro_token);
     }
 
-    /// Returns the native token address (required by OAppSender)
+    /// Returns the native token address (required by OAppSenderInternal)
     pub fn native_token(env: Env) -> Address {
         env.storage().instance().get(&symbol_short!("ntk")).unwrap()
     }
 
-    /// Returns the ZRO token address (required by OAppSender)
+    /// Returns the ZRO token address (required by OAppSenderInternal)
     pub fn zro(env: Env) -> Option<Address> {
         env.storage().instance().get(&symbol_short!("zro"))
     }

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

@@ -0,0 +1,58 @@
+use soroban_sdk::{contracttype, Bytes, BytesN};
+
+/// Message type for simple OFT send
+pub const SEND: u32 = 1;
+
+/// Message type for OFT send with compose functionality
+pub const SEND_AND_CALL: u32 = 2;
+
+/// Parameters for sending OFT tokens cross-chain
+#[contracttype]
+#[derive(Clone, PartialEq, Eq, Debug)]
+pub struct SendParam {
+    /// The destination endpoint ID
+    pub dst_eid: u32,
+    /// The recipient address on the destination chain (32 bytes)
+    pub to: BytesN<32>,
+    /// The amount to send in local decimals
+    pub amount_ld: i128,
+    /// The minimum amount to receive in local decimals (slippage protection)
+    pub min_amount_ld: i128,
+    /// Additional options for the LayerZero message (Optional)
+    pub extra_options: Bytes,
+    /// Compose message to execute on the destination (Optional)
+    pub compose_msg: Bytes,
+    /// OFT command for custom behavior (Optional)
+    pub oft_cmd: Bytes,
+}
+
+/// Transfer limits for OFT operations
+#[contracttype]
+#[derive(Clone, PartialEq, Eq, Debug)]
+pub struct OFTLimit {
+    /// The minimum amount to send in local decimals
+    pub min_amount_ld: i128,
+    /// The maximum amount to send in local decimals
+    pub max_amount_ld: i128,
+}
+
+/// Receipt containing amounts sent and received in an OFT transfer
+#[contracttype]
+#[derive(Clone, PartialEq, Eq, Debug)]
+pub struct OFTReceipt {
+    /// The amount sent in local decimals
+    pub amount_sent_ld: i128,
+    /// The amount received in local decimals on the remote
+    pub amount_received_ld: i128,
+}
+
+/// Details about fees charged in an OFT operation
+#[contracttype]
+#[derive(Clone, PartialEq, Eq, Debug)]
+pub struct OFTFeeDetail {
+    /// The amount of the fee in local decimals. Positive values represent fees charged,
+    /// while negative values represent rewards given.
+    pub fee_amount_ld: i128,
+    /// The description of the fee
+    pub description: Bytes,
+}

package/contracts/oapps/{oft → oft-core}/src/utils.rs

@@ -38,7 +38,7 @@ pub fn remove_dust(amount_ld: i128, conversion_rate: i128) -> i128 {
 ///
 /// # Returns
 /// A 32-byte payload (contract ID hash or Ed25519 public key)
-pub fn address_to_bytes32(address: &Address) -> BytesN<32> {
+pub fn address_payload(address: &Address) -> BytesN<32> {
     match address.to_payload().unwrap() {
         AddressPayload::ContractIdHash(payload) => payload,
         AddressPayload::AccountIdPublicKeyEd25519(payload) => payload,

package/contracts/upgrader/src/lib.rs

@@ -10,8 +10,8 @@
 //! ## 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.
+//! 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
 //!
@@ -53,8 +53,8 @@ pub struct Upgrader;
 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.
+    /// 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.

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,35 +1,61 @@
 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 TtlConfigurableError {
-    InvalidTtlConfig = 1200,
+    InvalidTtlConfig = 1020,
     TtlConfigFrozen,
     TtlConfigAlreadyFrozen,
 }
 
+/// OwnableError: 1030-1039
 #[contract_error]
 pub enum OwnableError {
-    OwnerAlreadySet = 1300,
+    InvalidPendingOwner = 1030,
+    InvalidTtl,
+    NoPendingTransfer,
+    OwnerAlreadySet,
     OwnerNotSet,
+    TransferInProgress,
 }
 
+/// BytesExtError: 1040-1049
 #[contract_error]
 pub enum BytesExtError {
-    LengthMismatch = 1400,
+    LengthMismatch = 1040,
 }
 
+/// UpgradeableError: 1050-1059
 #[contract_error]
 pub enum UpgradeableError {
-    MigrationNotAllowed = 1500,
+    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,15 @@
 #![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_configurable;
+pub mod ttl_extendable;
 pub mod upgradeable;
 
 #[cfg(test)]

package/contracts/utils/src/multisig.rs

@@ -0,0 +1,211 @@
+use crate::{
+    self as utils, // Alias for #[storage] macro's generated `utils::ttl_configurable` path
+    auth::{self, Auth},
+    errors::MultisigError,
+};
+use common_macros::{contract_trait, storage};
+use soroban_sdk::{assert_with_error, contractevent, Bytes, BytesN, Env, Vec};
+
+// ===========================================================================
+// Multisig events
+// ===========================================================================
+
+/// Event emitted when a signer is added or removed.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SignerSet {
+    #[topic]
+    pub signer: BytesN<20>,
+    pub active: bool,
+}
+
+/// Event emitted when the signature threshold is changed.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ThresholdSet {
+    pub threshold: u32,
+}
+
+// ===========================================================================
+// Multisig storage
+// ===========================================================================
+
+/// Storage keys for Multisig.
+#[storage]
+pub enum MultisigStorage {
+    #[persistent(Vec<BytesN<20>>)]
+    #[default(Vec::new(env))]
+    Signers,
+
+    #[instance(u32)]
+    #[default(0)]
+    Threshold,
+}
+
+// ===========================================================================
+// Multisig trait with default implementation
+// ===========================================================================
+
+/// Trait for contracts with secp256k1 multisig signature verification.
+///
+/// Extends `Auth` to provide self-owning authorization. Contracts implementing
+/// `Multisig` should implement `Auth::authorizer()` to return `env.current_contract_address()`,
+/// allowing the multisig quorum to serve as the authorizer for owner-protected operations.
+#[contract_trait]
+pub trait Multisig: Auth {
+    // ===========================================================================
+    // Mutation functions, only callable by the contract itself
+    // ===========================================================================
+
+    /// Adds or removes a signer from the multisig. Requires owner authorization.
+    fn set_signer(env: &Env, signer: &BytesN<20>, active: bool) {
+        auth::require_auth::<Self>(env);
+        match active {
+            true => add_signer(env, signer),
+            false => remove_signer(env, signer),
+        }
+    }
+
+    /// Sets the signature threshold (quorum). Requires owner authorization.
+    fn set_threshold(env: &Env, threshold: u32) {
+        auth::require_auth::<Self>(env);
+        set_threshold(env, threshold);
+    }
+
+    // ===========================================================================
+    // View functions
+    // ===========================================================================
+
+    /// Returns all registered signers.
+    fn get_signers(env: &Env) -> Vec<BytesN<20>> {
+        MultisigStorage::signers(env)
+    }
+
+    /// Returns the total number of registered signers.
+    fn total_signers(env: &Env) -> u32 {
+        MultisigStorage::signers(env).len()
+    }
+
+    /// Checks if an address is a registered signer.
+    fn is_signer(env: &Env, signer: &BytesN<20>) -> bool {
+        MultisigStorage::signers(env).iter().any(|s| &s == signer)
+    }
+
+    /// Returns the current signature threshold (quorum).
+    fn threshold(env: &Env) -> u32 {
+        MultisigStorage::threshold(env)
+    }
+
+    // ===========================================================================
+    // Verification functions
+    // ===========================================================================
+
+    /// Verifies signatures against the configured threshold.
+    fn verify_signatures(env: &Env, digest: &BytesN<32>, signatures: &Vec<BytesN<65>>) {
+        Self::verify_n_signatures(env, digest, signatures, MultisigStorage::threshold(env));
+    }
+
+    /// Verifies signatures against a custom threshold.
+    fn verify_n_signatures(env: &Env, digest: &BytesN<32>, signatures: &Vec<BytesN<65>>, threshold: u32) {
+        assert_with_error!(env, threshold > 0, MultisigError::ZeroThreshold);
+        assert_with_error!(env, signatures.len() >= threshold, MultisigError::SignatureError);
+
+        let signers = MultisigStorage::signers(env);
+        let mut last_signer: Option<BytesN<20>> = None;
+        for signature in signatures.iter() {
+            let signer = recover_signer(env, digest, &signature);
+
+            assert_with_error!(
+                env,
+                last_signer.as_ref().is_none_or(|last| &signer > last),
+                MultisigError::UnsortedSigners
+            );
+            assert_with_error!(env, signers.iter().any(|s| s == signer), MultisigError::SignerNotFound);
+
+            last_signer = Some(signer);
+        }
+    }
+}
+
+// ===========================================================================
+// Public helper functions
+// ===========================================================================
+
+/// Initializes multisig with signers and threshold. Called from contract constructors.
+pub fn init_multisig(env: &Env, signers: &Vec<BytesN<20>>, threshold: u32) {
+    assert_with_error!(env, !MultisigStorage::has_signers(env), MultisigError::AlreadyInitialized);
+
+    signers.iter().for_each(|signer| add_signer(env, &signer));
+    set_threshold(env, threshold);
+}
+
+/// Recovers Ethereum-style signer address from secp256k1 signature (65 bytes: r + s + v).
+pub fn recover_signer(env: &Env, digest: &BytesN<32>, signature: &BytesN<65>) -> BytesN<20> {
+    let sig_bytes: Bytes = signature.into();
+    let v = sig_bytes.get(64).unwrap();
+    let recovery_id = if (27..=30).contains(&v) { v - 27 } else { v };
+    let sig_rs: BytesN<64> = sig_bytes.slice(0..64).try_into().unwrap();
+
+    let public_key = env.crypto_hazmat().secp256k1_recover(digest, &sig_rs, recovery_id as u32);
+
+    Bytes::from(env.crypto().keccak256(&Bytes::from(public_key).slice(1..65))).slice(12..32).try_into().unwrap()
+}
+
+// ===========================================================================
+// Private helper functions
+// ===========================================================================
+
+/// Adds a new signer to the multisig.
+fn add_signer(env: &Env, signer: &BytesN<20>) {
+    // Not allowed to add zero address as signer
+    assert_with_error!(env, signer != &BytesN::from_array(env, &[0u8; 20]), MultisigError::InvalidSigner);
+    // Not allowed to add same signer twice
+    let mut signers = MultisigStorage::signers(env);
+    assert_with_error!(env, !signers.iter().any(|s| &s == signer), MultisigError::SignerAlreadyExists);
+
+    // Add signer to list
+    signers.push_back(signer.clone());
+    MultisigStorage::set_signers(env, &signers);
+
+    SignerSet { signer: signer.clone(), active: true }.publish(env);
+}
+
+/// Removes a signer from the multisig.
+fn remove_signer(env: &Env, signer: &BytesN<20>) {
+    let mut signers = MultisigStorage::signers(env);
+    let index = signers.first_index_of(signer);
+    // Not allowed to remove non-existent signer
+    assert_with_error!(env, index.is_some(), MultisigError::SignerNotFound);
+
+    // Remove signer from list
+    signers.remove(index.unwrap());
+
+    // Not allowed to remove signer if it would violate the threshold
+    assert_with_error!(
+        env,
+        signers.len() >= MultisigStorage::threshold(env),
+        MultisigError::TotalSignersLessThanThreshold
+    );
+
+    // Update signers list
+    MultisigStorage::set_signers(env, &signers);
+
+    SignerSet { signer: signer.clone(), active: false }.publish(env);
+}
+
+/// Sets the signature threshold (quorum).
+fn set_threshold(env: &Env, threshold: u32) {
+    // Not allowed to set threshold to zero
+    assert_with_error!(env, threshold > 0, MultisigError::ZeroThreshold);
+    // Not allowed to set threshold to greater than the number of signers
+    assert_with_error!(
+        env,
+        MultisigStorage::signers(env).len() >= threshold,
+        MultisigError::TotalSignersLessThanThreshold
+    );
+
+    // Update threshold
+    MultisigStorage::set_threshold(env, &threshold);
+
+    ThresholdSet { threshold }.publish(env);
+}