@layerzerolabs/protocol-stellar-v2 0.2.10 → 0.2.11

package/contracts/oapps/oft/src/tests/mod.rs

@@ -11,3 +11,5 @@ pub mod test_quote_send;
 pub mod test_resolve_address;
 pub mod test_send;
 pub mod test_token;
+
+pub mod extensions;

package/contracts/oapps/oft/src/tests/test_utils.rs

@@ -110,8 +110,15 @@ pub struct TestMintBurnOFT;
 
 #[contractimpl]
 impl TestMintBurnOFT {
-    pub fn __constructor(env: &Env, token: &Address, owner: &Address, endpoint: &Address, delegate: &Option<Address>) {
-        oft_initialize::<Self>(env, owner, token, endpoint, delegate)
+    pub fn __constructor(
+        env: &Env,
+        token: &Address,
+        owner: &Address,
+        endpoint: &Address,
+        delegate: &Option<Address>,
+        shared_decimals: u32,
+    ) {
+        oft_initialize::<Self>(env, owner, token, endpoint, delegate, shared_decimals)
     }
 }
 
@@ -134,8 +141,15 @@ pub struct TestLockUnlockOFT;
 
 #[contractimpl]
 impl TestLockUnlockOFT {
-    pub fn __constructor(env: &Env, token: &Address, owner: &Address, endpoint: &Address, delegate: &Option<Address>) {
-        oft_initialize::<Self>(env, owner, token, endpoint, delegate)
+    pub fn __constructor(
+        env: &Env,
+        token: &Address,
+        owner: &Address,
+        endpoint: &Address,
+        delegate: &Option<Address>,
+        shared_decimals: u32,
+    ) {
+        oft_initialize::<Self>(env, owner, token, endpoint, delegate, shared_decimals)
     }
 }
 
@@ -477,8 +491,12 @@ impl<'a> OFTTestSetupBuilder<'a> {
         // Register OFT based on type
         let delegate: Option<Address> = Some(owner.clone());
         let oft_address = match oft_type {
-            OFTType::MintBurn => env.register(TestMintBurnOFT, (&token, &owner, &endpoint_address, &delegate)),
-            OFTType::LockUnlock => env.register(TestLockUnlockOFT, (&token, &owner, &endpoint_address, &delegate)),
+            OFTType::MintBurn => {
+                env.register(TestMintBurnOFT, (&token, &owner, &endpoint_address, &delegate, &self.shared_decimals))
+            }
+            OFTType::LockUnlock => {
+                env.register(TestLockUnlockOFT, (&token, &owner, &endpoint_address, &delegate, &self.shared_decimals))
+            }
         };
         let oft = OFTClient::new(env, &oft_address);
 

package/contracts/oapps/{oft-mint-burn → oft-std}/Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "oft-mint-burn"
+name = "oft-std"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
@@ -17,10 +17,3 @@ common-macros = { workspace = true }
 oapp-macros = { workspace = true }
 oft = { workspace = true }
 
-[dev-dependencies]
-soroban-sdk = { workspace = true, features = ["testutils"] }
-assert_unordered = "0.3.5"
-simple-message-lib = { workspace = true }
-message-lib-common = { workspace = true, features = ["testutils"] }
-endpoint-v2 = { workspace = true, features = ["testutils"] }
-executor = { workspace = true, features = ["testutils"] }

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

@@ -0,0 +1,5 @@
+#![no_std]
+
+mod oft;
+
+pub use oft::*;

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

@@ -0,0 +1,59 @@
+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};
+
+#[storage]
+enum OFTStdStorage {
+    #[instance(bool)]
+    IsLockUnlock,
+}
+
+#[oapp]
+pub struct OFTStd;
+
+#[contract_impl]
+impl OFTStd {
+    pub fn __constructor(
+        env: &Env,
+        token: &Address,
+        owner: &Address,
+        endpoint: &Address,
+        delegate: &Option<Address>,
+        shared_decimals: u32,
+        is_lock_unlock: bool,
+    ) {
+        oft_initialize::<Self>(env, owner, token, endpoint, delegate, shared_decimals);
+        OFTStdStorage::set_is_lock_unlock(env, &is_lock_unlock);
+    }
+
+    /// 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()
+    }
+}
+
+/// OFT trait implementation for standard OFT
+#[contract_impl(contracttrait)]
+impl OFT for OFTStd {}
+
+/// OFT behavior for standard OFT
+impl OFTInner 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)
+        }
+    }
+
+    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)
+        }
+    }
+}

package/contracts/utils/src/ownable.rs

@@ -76,13 +76,13 @@ impl Ownable for DefaultOwnable {
     }
 
     fn transfer_ownership(env: &Env, new_owner: &Address) {
-        let old_owner = enforce_owner_auth::<Self>(env);
+        let old_owner = Self::owner(env).unwrap_or_panic(env, OwnableError::OwnerNotSet);
         DefaultOwnableStorage::set_owner(env, new_owner);
         OwnershipTransferred { old_owner, new_owner: new_owner.clone() }.publish(env);
     }
 
     fn renounce_ownership(env: &Env) {
-        let old_owner = enforce_owner_auth::<Self>(env);
+        let old_owner = Self::owner(env).unwrap_or_panic(env, OwnableError::OwnerNotSet);
         DefaultOwnableStorage::remove_owner(env);
         OwnershipRenounced { old_owner }.publish(env);
     }

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

@@ -186,20 +186,6 @@ fn transfer_ownership_to_same_owner() {
     assert_eq!(client.owner(), Some(owner));
 }
 
-#[test]
-#[should_panic(expected = "Error(Auth, InvalidAction)")]
-fn transfer_ownership_requires_auth() {
-    let env = Env::default();
-    let owner = Address::generate(&env);
-    let new_owner = Address::generate(&env);
-
-    let contract = env.register(Contract, (&owner,));
-    let client = ContractClient::new(&env, &contract);
-
-    // Try to transfer without auth should fail
-    client.transfer_ownership(&new_owner);
-}
-
 #[test]
 #[should_panic(expected = "Error(Contract, #1301)")]
 fn transfer_after_renounce_fails() {
@@ -264,19 +250,6 @@ fn renounce_ownership_with_event() {
     assert_eq!(client.owner(), None);
 }
 
-#[test]
-#[should_panic(expected = "Error(Auth, InvalidAction)")]
-fn renounce_ownership_requires_auth() {
-    let env = Env::default();
-    let owner = Address::generate(&env);
-
-    let contract = env.register(Contract, (&owner,));
-    let client = ContractClient::new(&env, &contract);
-
-    // Try to renounce without auth should fail
-    client.renounce_ownership();
-}
-
 #[test]
 #[should_panic(expected = "Error(Contract, #1301)")]
 fn renounce_after_renounce_fails() {
@@ -352,42 +325,6 @@ fn chain_new_owner_can_transfer() {
     assert_eq!(client.owner(), Some(third_owner));
 }
 
-#[test]
-#[should_panic(expected = "Error(Auth, InvalidAction)")]
-fn chain_old_owner_cannot_transfer_after_transfer() {
-    let env = Env::default();
-    let owner = Address::generate(&env);
-    let new_owner = Address::generate(&env);
-    let third_owner = Address::generate(&env);
-
-    let contract = env.register(Contract, (&owner,));
-    let client = ContractClient::new(&env, &contract);
-
-    // Transfer to new_owner
-    env.mock_auths(&[MockAuth {
-        address: &owner,
-        invoke: &MockAuthInvoke {
-            contract: &contract,
-            args: (&new_owner,).into_val(&env),
-            fn_name: "transfer_ownership",
-            sub_invokes: &[],
-        },
-    }]);
-    client.transfer_ownership(&new_owner);
-
-    // Old owner tries to transfer again - should fail
-    env.mock_auths(&[MockAuth {
-        address: &owner,
-        invoke: &MockAuthInvoke {
-            contract: &contract,
-            args: (&third_owner,).into_val(&env),
-            fn_name: "transfer_ownership",
-            sub_invokes: &[],
-        },
-    }]);
-    client.transfer_ownership(&third_owner);
-}
-
 // ============================================
 // init: DefaultOwnable::init_owner tests
 // ============================================

package/contracts/utils/src/ttl.rs

@@ -1,4 +1,5 @@
 use crate::errors::TtlError;
+use common_macros::event;
 use soroban_sdk::{assert_with_error, contractclient, contracttype, Env};
 
 /// Number of ledgers per day (~5 second ledger close time).
@@ -85,6 +86,8 @@ impl TtlConfigurable for DefaultTtlConfigurable {
 
         TtlConfigStorage::set_or_remove_instance(env, instance);
         TtlConfigStorage::set_or_remove_persistent(env, persistent);
+
+        TtlConfigsSet { instance: *instance, persistent: *persistent }.publish(env);
     }
 
     fn ttl_configs(env: &Env) -> (Option<TtlConfig>, Option<TtlConfig>) {
@@ -94,6 +97,8 @@ impl TtlConfigurable for DefaultTtlConfigurable {
     fn freeze_ttl_configs(env: &Env) {
         assert_with_error!(env, !Self::is_ttl_configs_frozen(env), TtlError::TtlConfigAlreadyFrozen);
         TtlConfigStorage::set_frozen(env, &true);
+
+        TtlConfigsFrozen {}.publish(env);
     }
 
     fn is_ttl_configs_frozen(env: &Env) -> bool {
@@ -101,4 +106,17 @@ impl TtlConfigurable for DefaultTtlConfigurable {
     }
 }
 
-// TODO: add events
+// ============================================
+// Events
+// ============================================
+
+/// Event emitted when TTL configs are set.
+#[event]
+pub struct TtlConfigsSet {
+    pub instance: Option<TtlConfig>,
+    pub persistent: Option<TtlConfig>,
+}
+
+/// Event emitted when TTL configs are frozen.
+#[event]
+pub struct TtlConfigsFrozen {}

package/contracts/workers/dvn/src/auth.rs

@@ -1,15 +1,57 @@
-use crate::TransactionAuthData;
+use super::*;
+
 use soroban_sdk::{
     address_payload::AddressPayload,
     auth::{Context, CustomAccountInterface},
+    contractimpl, contracttype,
+    crypto::Hash,
+    xdr::ToXdr,
 };
+use utils::buffer_writer::BufferWriter;
+
+// ============================================================================
+// Authentication Data Types
+// ============================================================================
+
+/// Authentication data for DVN contract transactions.
+///
+/// This struct is used with Soroban's custom account interface to authorize
+/// transactions through a combination of admin signature and multisig quorum.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct TransactionAuthData {
+    /// Verifier ID - must match the DVN's configured VID.
+    pub vid: u32,
+    /// Expiration timestamp (ledger time) after which this auth is invalid.
+    pub expiration: u64,
+    /// Signatures from multisig signers (secp256k1, 65 bytes each).
+    pub signatures: Vec<BytesN<65>>,
+    /// Admin's Ed25519 public key (32 bytes).
+    pub admin: BytesN<32>,
+    /// Admin's Ed25519 signature over the signature payload (64 bytes).
+    pub admin_signature: BytesN<64>,
+}
+
+// ============================================================================
+// Custom Account Interface Implementation
+// ============================================================================
 
 #[contractimpl]
 impl CustomAccountInterface for Dvn {
     type Signature = TransactionAuthData;
     type Error = DvnError;
 
-    #[allow(non_snake_case)]
+    /// Validates authorization for DVN contract operations.
+    ///
+    /// This implements Soroban's custom account interface, allowing the DVN
+    /// contract to act as its own account with multisig authorization.
+    ///
+    /// # Validation Steps
+    /// 1. Verify the admin signature is from a registered admin
+    /// 2. Check the VID matches the contract's configured VID
+    /// 3. Ensure the auth data hasn't expired
+    /// 4. Verify the auth contexts hash hasn't been used (replay protection)
+    /// 5. Verify multisig signatures meet the threshold
     fn __check_auth(
         env: Env,
         signature_payload: Hash<32>,
@@ -18,49 +60,71 @@ impl CustomAccountInterface for Dvn {
     ) -> Result<(), Self::Error> {
         let TransactionAuthData { vid, expiration, signatures, admin, admin_signature } = auth_data;
 
-        verify_admin(&env, &admin, &admin_signature, &signature_payload)?;
+        // Verify the admin signature is valid and from a registered admin.
+        Self::verify_admin(&env, &admin, &admin_signature, &signature_payload)?;
 
-        let stored_vid = DvnStorage::vid(&env).unwrap();
+        // Verify the VID matches the contract's configured VID.
+        let stored_vid = Self::vid(&env);
         if vid != stored_vid {
             return Err(DvnError::InvalidVid);
         }
-
+        // Ensure the auth data hasn't expired.
         if expiration <= env.ledger().timestamp() {
             return Err(DvnError::AuthDataExpired);
         }
 
-        let hash = hash_auth_data(&env, vid, expiration, &auth_contexts);
-
+        // Compute the hash of the auth data for replay protection.
+        let hash = Self::hash_auth_data(&env, vid, expiration, &auth_contexts);
+        // Verify the hash hasn't been used (replay protection) and set it as used.
         if DvnStorage::used_hash(&env, &hash) {
             return Err(DvnError::HashAlreadyUsed);
         }
-
-        Dvn::verify_signatures(&env, &hash, &signatures);
-
         DvnStorage::set_used_hash(&env, &hash, &true);
 
+        // Verify the multisig signatures meet the threshold.
+        Self::verify_signatures(&env, &hash, &signatures);
+
         Ok(())
     }
 }
 
-fn verify_admin(
-    env: &Env,
-    admin: &BytesN<32>,
-    admin_signature: &BytesN<64>,
-    signature_payload: &Hash<32>,
-) -> Result<(), DvnError> {
-    let admin_address = Address::from_payload(env, AddressPayload::AccountIdPublicKeyEd25519(admin.clone()));
-    if !Dvn::is_admin(env, &admin_address) {
-        return Err(DvnError::OnlyAdmin);
-    }
+// ============================================================================
+// Internal Helper Functions
+// ============================================================================
 
-    env.crypto().ed25519_verify(admin, &signature_payload.clone().into(), admin_signature);
+impl Dvn {
+    /// Verifies that the admin signature is valid and from a registered admin.
+    ///
+    /// # Arguments
+    /// * `admin` - The admin's Ed25519 public key
+    /// * `admin_signature` - The admin's signature over the signature payload
+    /// * `signature_payload` - The payload that was signed
+    ///
+    /// # Errors
+    /// Returns `DvnError::OnlyAdmin` if the signer is not a registered admin.
+    fn verify_admin(
+        env: &Env,
+        admin: &BytesN<32>,
+        admin_signature: &BytesN<64>,
+        signature_payload: &Hash<32>,
+    ) -> Result<(), DvnError> {
+        let admin_address = Address::from_payload(env, AddressPayload::AccountIdPublicKeyEd25519(admin.clone()));
+        if !Self::is_admin(env, &admin_address) {
+            return Err(DvnError::OnlyAdmin);
+        }
 
-    Ok(())
-}
+        env.crypto().ed25519_verify(admin, &signature_payload.clone().into(), admin_signature);
 
-fn hash_auth_data(env: &Env, vid: u32, expiration: u64, auth_contexts: &Vec<Context>) -> BytesN<32> {
-    let mut writer = BufferWriter::new(env);
-    let data = writer.write_u32(vid).write_u64(expiration).write_bytes(&auth_contexts.to_xdr(env)).to_bytes();
-    env.crypto().keccak256(&data).into()
+        Ok(())
+    }
+
+    /// Computes the hash of auth data for replay protection.
+    ///
+    /// Creates a unique hash from the VID, expiration, and auth contexts
+    /// to prevent the same authorization from being used multiple times.
+    fn hash_auth_data(env: &Env, vid: u32, expiration: u64, auth_contexts: &Vec<Context>) -> BytesN<32> {
+        let mut writer = BufferWriter::new(env);
+        let data = writer.write_u32(vid).write_u64(expiration).write_bytes(&auth_contexts.to_xdr(env)).to_bytes();
+        env.crypto().keccak256(&data).into()
+    }
 }

package/contracts/workers/dvn/src/dvn.rs

@@ -1,26 +1,22 @@
 use crate::{
-    errors::{DvnError, MultisigError},
-    events::SetDstConfig,
-    storage::DvnStorage,
-    types::{DstConfig, DstConfigParam},
-    IDVN,
+    dvn::multisig::init_multisig, errors::DvnError, events::SetDstConfig, storage::DvnStorage, DstConfig,
+    DstConfigParam, IMultisig, IDVN,
 };
-use common_macros::ttl_configurable;
+use common_macros::{contract_impl, ttl_configurable};
 use endpoint_v2::FeeRecipient;
 use message_lib_common::interfaces::ILayerZeroDVN;
-use soroban_sdk::{
-    assert_with_error, contract, contractimpl, crypto::Hash, xdr::ToXdr, Address, Bytes, BytesN, Env, Vec,
-};
-use utils::{buffer_writer::BufferWriter, option_ext::OptionExt};
+use soroban_sdk::{contract, Address, Bytes, BytesN, Env, Vec};
+use utils::option_ext::OptionExt;
 use worker::{
     assert_acl, assert_not_paused, assert_supported_message_lib, init_worker, require_admin_auth, set_admin_by_admin,
     set_admin_by_owner, storage::WorkerStorage, DvnFeeLibClient, DvnFeeParams, Worker,
 };
+
 #[contract]
 #[ttl_configurable]
 pub struct Dvn;
 
-#[contractimpl]
+#[contract_impl]
 impl Dvn {
     pub fn __constructor(
         env: &Env,
@@ -66,7 +62,7 @@ impl Dvn {
     }
 }
 
-#[contractimpl]
+#[contract_impl]
 impl IDVN for Dvn {
     fn set_dst_config(env: &Env, admin: &Address, params: &Vec<DstConfigParam>) {
         require_admin_auth::<Self>(env, admin);
@@ -77,8 +73,8 @@ impl IDVN for Dvn {
         SetDstConfig { params: params.clone() }.publish(env);
     }
 
-    fn dst_config(env: &Env, dst_eid: u32) -> DstConfig {
-        DvnStorage::dst_config(env, dst_eid).unwrap_or_panic(env, DvnError::EidNotSupported)
+    fn dst_config(env: &Env, dst_eid: u32) -> Option<DstConfig> {
+        DvnStorage::dst_config(env, dst_eid)
     }
 
     fn vid(env: &Env) -> u32 {
@@ -86,7 +82,7 @@ impl IDVN for Dvn {
     }
 }
 
-#[contractimpl]
+#[contract_impl]
 impl ILayerZeroDVN for Dvn {
     fn get_fee(
         env: &Env,
@@ -101,7 +97,7 @@ impl ILayerZeroDVN for Dvn {
         assert_not_paused::<Self>(env);
         assert_acl::<Self>(env, sender);
 
-        let dst_config = Self::dst_config(env, dst_eid);
+        let dst_config = Self::dst_config(env, dst_eid).unwrap_or_panic(env, DvnError::EidNotSupported);
         let params = DvnFeeParams {
             sender: sender.clone(),
             dst_eid,
@@ -115,7 +111,7 @@ impl ILayerZeroDVN for Dvn {
             floor_margin_usd: dst_config.floor_margin_usd,
         };
 
-        DvnFeeLibClient::new(env, &Self::worker_fee_lib(env)).get_fee(&params)
+        DvnFeeLibClient::new(env, &Self::worker_fee_lib(env)).get_fee(&env.current_contract_address(), &params)
     }
 
     fn assign_job(
@@ -136,8 +132,14 @@ impl ILayerZeroDVN for Dvn {
     }
 }
 
-#[contractimpl(contracttrait)]
+#[contract_impl(contracttrait)]
 impl Worker for Dvn {}
 
-include!("multisig.rs");
-include!("auth.rs");
+// ============================================================================
+// Include SubModules
+// ============================================================================
+
+#[path = "auth.rs"]
+pub mod auth;
+#[path = "multisig.rs"]
+pub mod multisig;

package/contracts/workers/dvn/src/interfaces/dvn.rs

@@ -1,12 +1,57 @@
-use crate::types::{DstConfig, DstConfigParam};
 use crate::IMultisig;
 use message_lib_common::interfaces::ILayerZeroDVN;
-use soroban_sdk::{contractclient, Address, Env, Vec};
+use soroban_sdk::{contractclient, contracttype, Address, Env, Vec};
 use worker::Worker;
 
+/// Configuration for a destination chain.
+///
+/// Contains fee calculation parameters specific to each destination endpoint.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct DstConfig {
+    /// Gas for verification on the destination chain.
+    pub gas: u128,
+    /// Fee multiplier in basis points (10000 = 100%).
+    /// If 0, the default multiplier from worker config is used.
+    pub multiplier_bps: u32,
+    /// Minimum fee margin in USD (scaled by native decimals rate).
+    pub floor_margin_usd: u128,
+}
+
+/// Parameter for setting destination chain configuration.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct DstConfigParam {
+    /// The destination endpoint ID.
+    pub dst_eid: u32,
+    /// The configuration for this destination.
+    pub config: DstConfig,
+}
+
+/// DVN (Decentralized Verifier Network) contract interface.
+///
+/// Extends the LayerZero DVN interface with destination configuration management
+/// and multisig capabilities for secure cross-chain message verification.
 #[contractclient(name = "DVNClient")]
 pub trait IDVN: ILayerZeroDVN + Worker + IMultisig {
+    /// Sets the configuration for one or more destination chains.
+    ///
+    /// # Arguments
+    /// * `admin` - The admin address (must provide authorization)
+    /// * `params` - List of destination configurations to set
     fn set_dst_config(env: &Env, admin: &Address, params: &Vec<DstConfigParam>);
-    fn dst_config(env: &Env, dst_eid: u32) -> DstConfig;
+
+    /// Gets the configuration for a destination chain.
+    ///
+    /// # Arguments
+    /// * `dst_eid` - The destination endpoint ID
+    ///
+    /// # Returns
+    /// The destination configuration, or `None` if not configured
+    fn dst_config(env: &Env, dst_eid: u32) -> Option<DstConfig>;
+
+    /// Returns the verifier ID (VID) of this DVN.
+    ///
+    /// The VID is a unique identifier used in multisig authentication.
     fn vid(env: &Env) -> u32;
 }

package/contracts/workers/dvn/src/interfaces/multisig.rs

@@ -1,15 +1,56 @@
 use soroban_sdk::{contractclient, BytesN, Env, Vec};
 
+/// Length of an ECDSA signature (64 bytes) plus recovery ID (1 byte).
 pub const SIGNATURE_LENGTH: usize = 65;
 
+/// Multisig interface for threshold-based signature verification.
+///
+/// Provides functionality to manage signers and verify that a sufficient
+/// number of valid signatures (meeting the threshold) have signed a message.
 #[contractclient(name = "MultiSigClient")]
 pub trait IMultisig {
+    /// Adds or removes a signer from the multisig.
+    ///
+    /// # Arguments
+    /// * `signer` - The 20-byte signer address (derived from secp256k1 public key)
+    /// * `active` - `true` to add, `false` to remove
     fn set_signer(env: &Env, signer: &BytesN<20>, active: bool);
+
+    /// Returns all registered signers.
     fn get_signers(env: &Env) -> Vec<BytesN<20>>;
+
+    /// Returns the total number of registered signers.
     fn total_signers(env: &Env) -> u32;
+
+    /// Checks if an address is a registered signer.
     fn is_signer(env: &Env, signer: &BytesN<20>) -> bool;
+
+    /// Returns the current signature threshold (quorum).
     fn threshold(env: &Env) -> u32;
+
+    /// Sets the signature threshold (quorum).
+    ///
+    /// The threshold must be greater than 0 and not exceed total signers.
     fn set_threshold(env: &Env, threshold: u32);
+
+    /// Verifies signatures against the configured threshold.
+    ///
+    /// # Arguments
+    /// * `hash` - The 32-byte message hash that was signed
+    /// * `signatures` - List of signatures to verify
+    ///
+    /// # Panics
+    /// If fewer than `threshold` valid signatures from registered signers are provided.
     fn verify_signatures(env: &Env, hash: &BytesN<32>, signatures: &Vec<BytesN<SIGNATURE_LENGTH>>);
+
+    /// Verifies signatures against a custom threshold.
+    ///
+    /// # Arguments
+    /// * `hash` - The 32-byte message hash that was signed
+    /// * `signatures` - List of signatures to verify
+    /// * `threshold` - Custom threshold to use instead of the configured one
+    ///
+    /// # Panics
+    /// If fewer than `threshold` valid signatures from registered signers are provided.
     fn verify_n_signatures(env: &Env, hash: &BytesN<32>, signatures: &Vec<BytesN<SIGNATURE_LENGTH>>, threshold: u32);
 }