@layerzerolabs/protocol-stellar-v2 0.2.13 → 0.2.18

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);
+}

package/contracts/utils/src/ownable.rs

@@ -1,47 +1,10 @@
-use crate::errors::OwnableError;
-use crate::option_ext::OptionExt;
-use common_macros::storage;
-use soroban_sdk::{assert_with_error, contractclient, contractevent, Address, Env};
+use crate::{self as utils, auth::Auth, errors::OwnableError, option_ext::OptionExt};
+use common_macros::{contract_trait, storage};
+use soroban_sdk::{assert_with_error, contractevent, 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 +21,68 @@ 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 {
+// ===========================================================================
+// Ownable trait with default implementation
+// ===========================================================================
+
+/// Trait for contracts with single-owner access control.
+///
+/// Extends `Auth` to provide owner-based authorization. The `Auth::authorizer()`
+/// implementation should return the owner address for Ownable contracts.
+#[contract_trait]
+pub trait Ownable: Sized + Auth {
+    /// Returns the current owner address, or None if no owner is set.
     fn owner(env: &Env) -> Option<Address> {
-        DefaultOwnableStorage::owner(env)
+        OwnableStorage::owner(env)
     }
 
+    /// Transfers ownership to a new address. Requires current owner authorization.
     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);
+        let old_owner = enforce_owner_auth::<Self>(env);
+        OwnableStorage::set_owner(env, new_owner);
         OwnershipTransferred { old_owner, new_owner: new_owner.clone() }.publish(env);
     }
 
+    /// Permanently renounces ownership. Requires current owner authorization.
     fn renounce_ownership(env: &Env) {
-        let old_owner = Self::owner(env).unwrap_or_panic(env, OwnableError::OwnerNotSet);
-        DefaultOwnableStorage::remove_owner(env);
+        let old_owner = enforce_owner_auth::<Self>(env);
+        OwnableStorage::remove_owner(env);
         OwnershipRenounced { old_owner }.publish(env);
     }
 }
 
-impl OwnableInitializer for DefaultOwnable {
+/// Trait for initializing the owner of the contract.
+pub trait OwnableInitializer {
     fn init_owner(env: &Env, owner: &Address) {
-        assert_with_error!(env, !DefaultOwnableStorage::has_owner(env), OwnableError::OwnerAlreadySet);
-        DefaultOwnableStorage::set_owner(env, owner);
+        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/buffer_reader.rs

@@ -1,11 +1,11 @@
+use crate::{
+    buffer_reader::BufferReader,
+    buffer_writer::BufferWriter,
+    bytes_ext::BytesExt,
+    tests::test_helper::{assert_address_payload_matches, assert_panics_contains},
+};
 use soroban_sdk::{address_payload::AddressPayload, testutils::Address as _, Address, Bytes, BytesN, Env};
 
-use crate::buffer_reader::BufferReader;
-use crate::buffer_writer::BufferWriter;
-use crate::bytes_ext::BytesExt;
-
-use crate::tests::test_helper::{assert_address_payload_matches, assert_panics_contains};
-
 type ReaderStep = fn(&mut BufferReader);
 
 fn assert_reader_panics_contains(case: &str, raw: &[u8], step: ReaderStep, expected_substring: &str) {

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

@@ -1,11 +1,11 @@
+use crate::{
+    buffer_reader::BufferReader,
+    buffer_writer::BufferWriter,
+    bytes_ext::BytesExt,
+    tests::test_helper::assert_address_payload_matches,
+};
 use soroban_sdk::{address_payload::AddressPayload, testutils::Address as _, Address, Bytes, BytesN, Env, U256};
 
-use crate::buffer_reader::BufferReader;
-use crate::buffer_writer::BufferWriter;
-use crate::bytes_ext::BytesExt;
-
-use crate::tests::test_helper::assert_address_payload_matches;
-
 /// Helper to test U256 write/read roundtrip
 fn test_u256_roundtrip(env: &Env, value: &soroban_sdk::U256) {
     let mut writer = BufferWriter::new(env);

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

@@ -1,15 +1,13 @@
+use crate::{bytes_ext::BytesExt, tests::test_helper::assert_panics_contains};
 use soroban_sdk::{Bytes, Env};
 
-use crate::bytes_ext::BytesExt;
-use crate::tests::test_helper::assert_panics_contains;
-
 // ============================================
 // Helper functions
 // ============================================
 
 /// Helper to assert that `to_array::<N>()` panics with BytesExtError::LengthMismatch (1400)
 fn assert_to_array_panics<const N: usize>(case: &str, raw: &[u8]) {
-    const EXPECTED: &str = "Error(Contract, #1400)";
+    const EXPECTED: &str = "Error(Contract, #1040)"; // LengthMismatch
     assert_panics_contains(case, EXPECTED, || {
         let env = Env::default();
         let bytes = Bytes::from_slice(&env, raw);

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

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