@layerzerolabs/common-utils-stellar-contracts 0.2.122

package/src/multisig.rs

@@ -0,0 +1,247 @@
+use crate::{
+    self as utils, // Alias for #[storage] macro's generated `utils::ttl_configurable` path
+    auth::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 {
+    /// List of authorized signers as Ethereum-style addresses (20 bytes).
+    ///
+    /// Practically, multisig has 2-5 signers, so storing them in a single `Vec` is fine.
+    /// This makes `get_signers` trivial (just read the Vec), while `set_signer` is slightly
+    /// more complex (read-modify-write). Since reads are frequent and writes are rare,
+    /// this trade-off is acceptable.
+    #[persistent(Vec<BytesN<20>>)]
+    #[default(Vec::new(env))]
+    Signers,
+
+    /// Minimum number of valid signatures required to authorize operations (quorum).
+    #[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: &soroban_sdk::Env, signer: &soroban_sdk::BytesN<20>, active: bool) {
+        enforce_multisig_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: &soroban_sdk::Env, threshold: u32) {
+        enforce_multisig_auth::<Self>(env);
+        set_threshold(env, threshold);
+    }
+
+    // ===========================================================================
+    // View functions
+    // ===========================================================================
+
+    /// Returns all registered signers.
+    fn get_signers(env: &soroban_sdk::Env) -> soroban_sdk::Vec<soroban_sdk::BytesN<20>> {
+        MultiSigStorage::signers(env)
+    }
+
+    /// Returns the total number of registered signers.
+    fn total_signers(env: &soroban_sdk::Env) -> u32 {
+        MultiSigStorage::signers(env).len()
+    }
+
+    /// Checks if an address is a registered signer.
+    fn is_signer(env: &soroban_sdk::Env, signer: &soroban_sdk::BytesN<20>) -> bool {
+        MultiSigStorage::signers(env).iter().any(|s| &s == signer)
+    }
+
+    /// Returns the current signature threshold (quorum).
+    fn threshold(env: &soroban_sdk::Env) -> u32 {
+        MultiSigStorage::threshold(env)
+    }
+
+    // ===========================================================================
+    // Verification functions
+    // ===========================================================================
+
+    /// Verifies signatures against the configured threshold.
+    fn verify_signatures(
+        env: &soroban_sdk::Env,
+        digest: &soroban_sdk::BytesN<32>,
+        signatures: &soroban_sdk::Vec<soroban_sdk::BytesN<65>>,
+    ) {
+        Self::verify_n_signatures(env, digest, signatures, MultiSigStorage::threshold(env));
+    }
+
+    /// Verifies signatures against a custom threshold.
+    fn verify_n_signatures(
+        env: &soroban_sdk::Env,
+        digest: &soroban_sdk::BytesN<32>,
+        signatures: &soroban_sdk::Vec<soroban_sdk::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();
+
+    // Extract recovery ID (v) - normalize from Ethereum's 27-30 range if needed
+    let v = sig_bytes.get(64).unwrap();
+    let recovery_id = if (27..=30).contains(&v) { v - 27 } else { v };
+
+    // Extract r,s components (first 64 bytes)
+    let sig_rs: BytesN<64> = sig_bytes.slice(0..64).try_into().unwrap();
+
+    // Recover uncompressed public key (65 bytes with 0x04 prefix)
+    let public_key = env.crypto_hazmat().secp256k1_recover(digest, &sig_rs, recovery_id as u32);
+
+    // Derive Ethereum address: keccak256(pubkey[1..65])[12..32]
+    let pubkey_body: Bytes = Bytes::from(public_key).slice(1..65);
+    let hash: Bytes = env.crypto().keccak256(&pubkey_body).into();
+    hash.slice(12..32).try_into().unwrap()
+}
+
+/// Enforces multisig authorization by requiring the contract's own address to authorize.
+/// Panics with `InvalidAuthorizer` if the authorizer is not the contract's own address.
+pub fn enforce_multisig_auth<T: MultiSig>(env: &Env) {
+    // Ensure the authorizer is the contract's own address
+    assert_with_error!(
+        env,
+        Some(env.current_contract_address()) == T::authorizer(env),
+        MultiSigError::InvalidAuthorizer
+    );
+    env.current_contract_address().require_auth();
+}
+
+// ===========================================================================
+// 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/src/option_ext.rs

@@ -0,0 +1,38 @@
+use soroban_sdk::{panic_with_error, Env, Error};
+
+/// Extension trait for `Option<T>` that provides Soroban-specific unwrapping utilities.
+///
+/// This trait extends the standard `Option` type with methods that integrate with
+/// Soroban's error handling system, allowing for more descriptive panics when
+/// unwrapping fails.
+pub trait OptionExt<T> {
+    /// Unwraps the `Option`, returning the contained value if `Some`,
+    /// or panics with the provided error if `None`.
+    ///
+    /// # Arguments
+    /// * `env` - The Soroban environment, required for error propagation.
+    /// * `error` - The error to emit if the `Option` is `None`. Must be convertible into a `soroban_sdk::Error`.
+    ///
+    /// # Returns
+    /// The contained value if `Some`.
+    ///
+    /// # Panics
+    /// Panics with the specified error if the `Option` is `None`.
+    fn unwrap_or_panic<E>(self, env: &Env, error: E) -> T
+    where
+        E: Into<Error>;
+}
+
+impl<T> OptionExt<T> for Option<T> {
+    fn unwrap_or_panic<E>(self, env: &Env, error: E) -> T
+    where
+        E: Into<Error>,
+    {
+        match self {
+            // Return the inner value if present
+            Some(val) => val,
+            // Panic with the provided error if None, using Soroban's error macro
+            None => panic_with_error!(env, error),
+        }
+    }
+}

package/src/ownable.rs

@@ -0,0 +1,227 @@
+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 events
+// ===========================================================================
+
+/// Event emitted when ownership is transferred (both single-step and two-step completion).
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct OwnershipTransferred {
+    pub old_owner: Address,
+    pub new_owner: Address,
+}
+
+/// Event emitted when a 2-step ownership transfer is proposed.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct OwnershipTransferring {
+    pub old_owner: Address,
+    pub new_owner: Address,
+    pub ttl: u32,
+}
+
+/// Event emitted when a 2-step ownership transfer is cancelled.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct OwnershipTransferCancelled {
+    pub owner: Address,
+    pub cancelled_pending_owner: Address,
+}
+
+/// Event emitted when ownership is renounced.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct OwnershipRenounced {
+    pub old_owner: Address,
+}
+
+// ===========================================================================
+// Ownable storage for default implementation
+// ===========================================================================
+
+/// Storage keys for Ownable.
+#[storage]
+pub enum OwnableStorage {
+    #[instance(Address)]
+    Owner,
+    /// Pending owner for 2-step transfer. Stored in temporary storage with TTL -
+    /// automatically expires if not accepted in time.
+    #[temporary(Address)]
+    PendingOwner,
+}
+
+// ===========================================================================
+// 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.
+///
+/// Supports both single-step and two-step ownership transfer:
+/// - Single-step: `transfer_ownership` - Immediate transfer (use with caution)
+/// - Two-step: `begin_ownership_transfer` + `accept_ownership` - Safer, requires new owner to accept
+#[contract_trait]
+pub trait Ownable: Auth {
+    // ===========================================================================
+    // View functions
+    // ===========================================================================
+
+    /// 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)
+    }
+
+    /// Returns the pending owner address for 2-step transfer, or None if no transfer is pending.
+    fn pending_owner(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
+        OwnableStorage::pending_owner(env)
+    }
+
+    // ===========================================================================
+    // Single-step transfer (immediate)
+    // ===========================================================================
+
+    /// Transfers ownership immediately to a new address.
+    ///
+    /// Use with caution - if you transfer to a wrong address, ownership is lost forever.
+    /// Consider using `begin_ownership_transfer` instead.
+    ///
+    /// # Panics
+    /// - `OwnerNotSet` if no owner is currently set
+    /// - `TransferInProgress` if a 2-step transfer is in progress
+    fn transfer_ownership(env: &soroban_sdk::Env, new_owner: &soroban_sdk::Address) {
+        let old_owner = enforce_owner_auth::<Self>(env);
+        assert_no_pending_transfer::<Self>(env);
+
+        OwnableStorage::set_owner(env, new_owner);
+        OwnershipTransferred { old_owner, new_owner: new_owner.clone() }.publish(env);
+    }
+
+    // ===========================================================================
+    // Two-step transfer (safer)
+    // ===========================================================================
+
+    /// Begins an ownership transfer to a new address.
+    ///
+    /// The new owner must call `accept_ownership()` within `ttl` ledgers
+    /// to complete the transfer. The pending transfer will automatically expire after.
+    ///
+    /// # Arguments
+    /// - `new_owner` - The proposed new owner
+    /// - `ttl` - Number of ledgers the new owner has to accept.
+    ///   Use `0` to cancel a pending transfer (new_owner must match pending).
+    ///
+    /// # Panics
+    /// - `OwnerNotSet` if no owner is currently set
+    /// - `NoPendingTransfer` when cancelling and no pending transfer exists
+    /// - `InvalidTtl` if ttl exceeds max TTL
+    /// - `InvalidPendingOwner` when cancelling with wrong new_owner address
+    fn begin_ownership_transfer(env: &soroban_sdk::Env, new_owner: &soroban_sdk::Address, ttl: u32) {
+        let old_owner = enforce_owner_auth::<Self>(env);
+
+        // Cancel case: ttl == 0
+        if ttl == 0 {
+            let pending = Self::pending_owner(env).unwrap_or_panic(env, OwnableError::NoPendingTransfer);
+
+            // Verify new_owner matches pending (prevents accidental cancellation)
+            assert_with_error!(env, pending == *new_owner, OwnableError::InvalidPendingOwner);
+
+            OwnableStorage::remove_pending_owner(env);
+            OwnershipTransferCancelled { owner: old_owner, cancelled_pending_owner: pending }.publish(env);
+            return;
+        }
+
+        // Initiate case: validate ttl
+        assert_with_error!(env, ttl <= env.storage().max_ttl(), OwnableError::InvalidTtl);
+
+        // Store pending owner with TTL
+        OwnableStorage::set_pending_owner(env, new_owner);
+        OwnableStorage::extend_pending_owner_ttl(env, ttl, ttl);
+
+        OwnershipTransferring { old_owner, new_owner: new_owner.clone(), ttl }.publish(env);
+    }
+
+    /// Accepts a pending 2-step ownership transfer.
+    ///
+    /// Must be called by the pending owner before the TTL expires.
+    ///
+    /// # Panics
+    /// - `NoPendingTransfer` if there is no pending transfer (or it expired)
+    fn accept_ownership(env: &soroban_sdk::Env) {
+        let new_owner = Self::pending_owner(env).unwrap_or_panic(env, OwnableError::NoPendingTransfer);
+
+        // Require authorization from the pending owner
+        new_owner.require_auth();
+
+        // Safe to unwrap: owner must exist if pending_owner exists because:
+        // 1. pending_owner can only be set via begin_ownership_transfer, which requires owner auth
+        // 2. renounce_ownership is blocked while a 2-step transfer is in progress
+        let old_owner = OwnableStorage::owner(env).unwrap();
+
+        // Transfer ownership
+        OwnableStorage::remove_pending_owner(env);
+        OwnableStorage::set_owner(env, &new_owner);
+
+        OwnershipTransferred { old_owner, new_owner }.publish(env);
+    }
+
+    // ===========================================================================
+    // Renounce
+    // ===========================================================================
+
+    /// Permanently renounces ownership.
+    ///
+    /// # Panics
+    /// - `OwnerNotSet` if no owner is currently set
+    /// - `TransferInProgress` if a 2-step transfer is in progress (cancel it first)
+    fn renounce_ownership(env: &soroban_sdk::Env) {
+        let old_owner = enforce_owner_auth::<Self>(env);
+        assert_no_pending_transfer::<Self>(env);
+
+        OwnableStorage::remove_owner(env);
+        OwnershipRenounced { old_owner }.publish(env);
+    }
+}
+
+/// Trait for initializing the owner of the contract.
+pub trait OwnableInitializer {
+    /// Initializes the owner of the contract.
+    ///
+    /// # Critical: constructor-only, never expose as a public entrypoint
+    ///
+    /// `init_owner` must **ONLY** be called from the contract constructor. Do not expose it
+    /// as a public function under the assumption that it will "simply fail" after initialization.
+    ///
+    /// After `renounce_ownership`, the owner is removed and `has_owner` returns false. If
+    /// `init_owner` were exposed publicly, anyone could call it post-renounce and become the
+    /// new owner, effectively undoing the renunciation. Always keep this logic internal to
+    /// the constructor.
+    fn init_owner(env: &Env, owner: &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);
+    // Ensure the owner is the same as the authorizer
+    assert_with_error!(env, Some(&owner) == T::authorizer(env).as_ref(), OwnableError::InvalidAuthorizer);
+    owner.require_auth();
+    owner
+}
+
+/// Asserts that no 2-step ownership transfer is in progress.
+/// Panics with `TransferInProgress` if a pending transfer exists.
+fn assert_no_pending_transfer<T: Ownable>(env: &Env) {
+    assert_with_error!(env, T::pending_owner(env).is_none(), OwnableError::TransferInProgress);
+}