@layerzerolabs/protocol-stellar-v2 0.2.10 → 0.2.12

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

@@ -1,62 +1,86 @@
+//! Multisig functionality for the DVN contract.
+//!
+//! Provides secp256k1-based multisig signature verification using Ethereum-style
+//! 20-byte addresses derived from recovered public keys.
+
+use super::*;
+
 use crate::{
+    errors::DvnError,
     events::{SignerSet, ThresholdSet},
-    storage::MultisigStorage,
-    IMultisig,
+    storage::DvnStorage,
 };
+use soroban_sdk::assert_with_error;
+
+// ============================================================================
+// IMultisig Implementation
+// ============================================================================
 
-#[contractimpl]
-impl IMultisig for Dvn {
+#[contract_impl]
+impl IMultisig for LzDVN {
+    /// Adds or removes a signer. Requires contract self-authorization (quorum).
     fn set_signer(env: &Env, signer: &BytesN<20>, active: bool) {
         env.current_contract_address().require_auth();
-
         if active {
-            add_signer(env, signer);
+            Self::add_signer(env, signer);
         } else {
-            remove_signer(env, signer);
+            Self::remove_signer(env, signer);
         }
     }
 
+    /// Updates the signature threshold. Requires contract self-authorization (quorum).
     fn set_threshold(env: &Env, threshold: u32) {
         env.current_contract_address().require_auth();
 
-        set_threshold(env, threshold);
+        assert_with_error!(env, threshold > 0, DvnError::ZeroThreshold);
+        assert_with_error!(env, Self::total_signers(env) >= threshold, DvnError::TotalSignersLessThanThreshold);
+
+        DvnStorage::set_threshold(env, &threshold);
+
+        ThresholdSet { threshold }.publish(env);
     }
 
+    /// Returns the list of all registered signers.
     fn get_signers(env: &Env) -> Vec<BytesN<20>> {
-        MultisigStorage::signers(env)
+        DvnStorage::signers(env)
     }
 
+    /// Returns the total number of registered signers.
     fn total_signers(env: &Env) -> u32 {
-        MultisigStorage::signers(env).len()
+        DvnStorage::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)
+        DvnStorage::signers(env).iter().any(|s| &s == signer)
     }
 
+    /// Returns the current signature threshold.
     fn threshold(env: &Env) -> u32 {
-        MultisigStorage::threshold(env)
+        DvnStorage::threshold(env)
     }
 
+    /// Verifies signatures against the current threshold.
     fn verify_signatures(env: &Env, hash: &BytesN<32>, signatures: &Vec<BytesN<65>>) {
         Self::verify_n_signatures(env, hash, signatures, Self::threshold(env));
     }
 
+    /// Verifies that at least `threshold` valid signatures exist for the given hash.
+    ///
+    /// Signatures must be:
+    /// - From registered signers
+    /// - Sorted by signer address (ascending, no duplicates)
     fn verify_n_signatures(env: &Env, hash: &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);
+        assert_with_error!(env, threshold > 0, DvnError::ZeroThreshold);
+        assert_with_error!(env, signatures.len() >= threshold, DvnError::SignatureError);
 
         let mut last_signer: Option<BytesN<20>> = None;
         signatures.iter().for_each(|signature| {
-            let signer = recover_signer(env, hash, &signature);
+            let signer = Self::recover_signer(env, hash, &signature);
 
-            // Signers must be strictly increasing
-            assert_with_error!(
-                env,
-                last_signer.as_ref().is_none_or(|last| &signer > last),
-                MultisigError::UnsortedSigners
-            );
-            assert_with_error!(env, Self::is_signer(env, &signer), MultisigError::SignerNotFound);
+            // Signers must be strictly increasing (ensures no duplicates)
+            assert_with_error!(env, last_signer.as_ref().is_none_or(|last| &signer > last), DvnError::UnsortedSigners);
+            assert_with_error!(env, Self::is_signer(env, &signer), DvnError::SignerNotFound);
 
             last_signer = Some(signer);
         });
@@ -64,64 +88,66 @@ impl IMultisig for Dvn {
 }
 
 // ============================================================================
-// Internal Helper Functions
+// Internal Functions
 // ============================================================================
 
-fn add_signer(env: &Env, signer: &BytesN<20>) {
-    let zero_signer = BytesN::from_array(env, &[0u8; 20]);
-    assert_with_error!(env, signer != &zero_signer, MultisigError::InvalidSigner);
-
-    let mut signers = MultisigStorage::signers(env);
-    assert_with_error!(env, !signers.iter().any(|s| &s == signer), MultisigError::SignerAlreadyExists);
-    signers.push_back(signer.clone());
-    MultisigStorage::set_signers(env, &signers);
-
-    SignerSet { signer: signer.clone(), active: true }.publish(env);
-}
+impl LzDVN {
+    /// Initializes the multisig with a set of signers and threshold.
+    /// Called during contract construction.
+    pub fn init_multisig(env: &Env, signers: &Vec<BytesN<20>>, threshold: u32) {
+        signers.iter().for_each(|signer| Self::add_signer(env, &signer));
+        Self::set_threshold(env, threshold);
+    }
 
-fn remove_signer(env: &Env, signer: &BytesN<20>) {
-    let mut signers = MultisigStorage::signers(env);
-    let index = signers.first_index_of(signer);
-    assert_with_error!(env, index.is_some(), MultisigError::SignerNotFound);
-
-    signers.remove(index.unwrap());
-    // Check that removing didn't violate threshold constraint
-    assert_with_error!(
-        env,
-        signers.len() >= MultisigStorage::threshold(env),
-        MultisigError::TotalSignersLessThanThreshold
-    );
-    MultisigStorage::set_signers(env, &signers);
-
-    SignerSet { signer: signer.clone(), active: false }.publish(env);
-}
+    /// Adds a new signer to the multisig.
+    ///
+    /// # Errors
+    /// - `InvalidSigner` if the signer is the zero address
+    /// - `SignerAlreadyExists` if the signer is already registered
+    fn add_signer(env: &Env, signer: &BytesN<20>) {
+        let zero_signer = BytesN::from_array(env, &[0u8; 20]);
+        assert_with_error!(env, signer != &zero_signer, DvnError::InvalidSigner);
+
+        let mut signers = Self::get_signers(env);
+        assert_with_error!(env, !signers.iter().any(|s| &s == signer), DvnError::SignerAlreadyExists);
+        signers.push_back(signer.clone());
+        DvnStorage::set_signers(env, &signers);
+
+        SignerSet { signer: signer.clone(), active: true }.publish(env);
+    }
 
-fn set_threshold(env: &Env, threshold: u32) {
-    assert_with_error!(env, threshold > 0, MultisigError::ZeroThreshold);
-    assert_with_error!(
-        env,
-        MultisigStorage::signers(env).len() >= threshold,
-        MultisigError::TotalSignersLessThanThreshold
-    );
+    /// Removes a signer from the multisig.
+    ///
+    /// # Errors
+    /// - `SignerNotFound` if the signer is not registered
+    /// - `TotalSignersLessThanThreshold` if removal would violate threshold constraint
+    fn remove_signer(env: &Env, signer: &BytesN<20>) {
+        let mut signers = Self::get_signers(env);
+        let index = signers.first_index_of(signer);
+        assert_with_error!(env, index.is_some(), DvnError::SignerNotFound);
 
-    MultisigStorage::set_threshold(env, &threshold);
+        signers.remove(index.unwrap());
 
-    ThresholdSet { threshold }.publish(env);
-}
+        // Ensure removal doesn't violate threshold constraint
+        assert_with_error!(env, signers.len() >= Self::threshold(env), DvnError::TotalSignersLessThanThreshold);
+        DvnStorage::set_signers(env, &signers);
 
-fn init_multisig(env: &Env, signers: &Vec<BytesN<20>>, threshold: u32) {
-    signers.iter().for_each(|signer| add_signer(env, &signer));
-
-    set_threshold(env, threshold);
-}
+        SignerSet { signer: signer.clone(), active: false }.publish(env);
+    }
 
-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();
+    /// Recovers the Ethereum-style signer address from a secp256k1 signature.
+    ///
+    /// The signature format is 65 bytes: r (32) + s (32) + v (1).
+    /// Returns the last 20 bytes of keccak256(uncompressed_pubkey[1..65]).
+    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);
+        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()
+        // Derive Ethereum address: keccak256(pubkey[1..65])[12..32]
+        Bytes::from(env.crypto().keccak256(&Bytes::from(public_key).slice(1..65))).slice(12..32).try_into().unwrap()
+    }
 }

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

@@ -2,33 +2,30 @@ use crate::DstConfig;
 use common_macros::storage;
 use soroban_sdk::{BytesN, Vec};
 
-// ============================================================================
-// Multisig Storage
-// ============================================================================
-
+/// DVN contract storage keys.
 #[storage]
-pub enum MultisigStorage {
+pub enum DvnStorage {
+    // ======================== Multisig ========================
+    /// List of authorized signer addresses (20-byte Ethereum addresses).
     #[persistent(Vec<BytesN<20>>)]
     #[default(Vec::new(env))]
     Signers,
 
+    /// Minimum number of signatures required for multisig operations.
     #[instance(u32)]
     #[default(0)]
     Threshold,
-}
 
-// ============================================================================
-// DVN Storage
-// ============================================================================
-
-#[storage]
-pub enum DvnStorage {
+    // ======================== DVN ============================
+    /// Verifier ID - unique identifier for this DVN instance.
     #[instance(u32)]
     Vid,
 
+    /// Destination chain configuration, keyed by endpoint ID.
     #[persistent(DstConfig)]
     DstConfig { dst_eid: u32 },
 
+    /// Tracks used hashes for replay protection.
     #[persistent(bool)]
     #[default(false)]
     UsedHash { hash: BytesN<32> },

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

@@ -1,5 +1,8 @@
 use crate::tests::setup::{TestSetup, VID};
-use crate::{errors::DvnError, errors::MultisigError, TransactionAuthData};
+use crate::{
+    dvn::auth::{Sender, TransactionAuthData},
+    errors::DvnError,
+};
 use ed25519_dalek::{Signer, SigningKey};
 use rand::thread_rng;
 use soroban_sdk::{auth::Context, vec, Bytes, BytesN, Env, IntoVal, Vec};
@@ -49,13 +52,18 @@ fn test_check_auth_success() {
     let auth_contexts: Vec<Context> = Vec::new(&env);
 
     let payload = BytesN::from_array(&env, &[0u8; 32]);
-    let admin = admin_kp.public_key(&env);
-    let admin_signature = admin_kp.sign(&env, &payload.to_array());
+    let public_key = admin_kp.public_key(&env);
+    let signature = admin_kp.sign(&env, &payload.to_array());
 
     let hash = hash_auth_data(&env, VID, expiration, &auth_contexts);
     let sig = setup.key_pairs[0].sign_bytes(&env, &hash);
 
-    let tx_auth = TransactionAuthData { vid: VID, expiration, signatures: vec![&env, sig], admin, admin_signature };
+    let tx_auth = TransactionAuthData {
+        vid: VID,
+        expiration,
+        signatures: vec![&env, sig],
+        sender: Sender::Admin(public_key, signature),
+    };
 
     let res = env.try_invoke_contract_check_auth::<DvnError>(
         &setup.contract_id,
@@ -78,13 +86,18 @@ fn test_check_auth_not_admin() {
     let auth_contexts: Vec<Context> = Vec::new(&env);
 
     let payload = BytesN::from_array(&env, &[0u8; 32]);
-    let admin = non_admin_kp.public_key(&env);
-    let admin_signature = non_admin_kp.sign(&env, &payload.to_array());
+    let public_key = non_admin_kp.public_key(&env);
+    let signature = non_admin_kp.sign(&env, &payload.to_array());
 
     let hash = hash_auth_data(&env, VID, expiration, &auth_contexts);
     let sig = setup.key_pairs[0].sign_bytes(&env, &hash);
 
-    let tx_auth = TransactionAuthData { vid: VID, expiration, signatures: vec![&env, sig], admin, admin_signature };
+    let tx_auth = TransactionAuthData {
+        vid: VID,
+        expiration,
+        signatures: vec![&env, sig],
+        sender: Sender::Admin(public_key, signature),
+    };
 
     let res = env.try_invoke_contract_check_auth::<DvnError>(
         &setup.contract_id,
@@ -108,24 +121,28 @@ fn test_check_auth_wrong_signer_fails() {
     let auth_contexts: Vec<Context> = Vec::new(&env);
 
     let payload = BytesN::from_array(&env, &[0u8; 32]);
-    let admin = admin_kp.public_key(&env);
-    let admin_signature = admin_kp.sign(&env, &payload.to_array());
+    let public_key = admin_kp.public_key(&env);
+    let signature = admin_kp.sign(&env, &payload.to_array());
 
     let hash = hash_auth_data(&env, VID, expiration, &auth_contexts);
     let wrong_sig = crate::tests::key_pair::KeyPair::generate().sign_bytes(&env, &hash);
 
-    let tx_auth =
-        TransactionAuthData { vid: VID, expiration, signatures: vec![&env, wrong_sig], admin, admin_signature };
+    let tx_auth = TransactionAuthData {
+        vid: VID,
+        expiration,
+        signatures: vec![&env, wrong_sig],
+        sender: Sender::Admin(public_key, signature),
+    };
 
-    // verify_signatures panics with MultisigError::SignerNotFound when signer is not found
-    let res = env.try_invoke_contract_check_auth::<MultisigError>(
+    // verify_signatures panics with DvnError::SignerNotFound when signer is not found
+    let res = env.try_invoke_contract_check_auth::<DvnError>(
         &setup.contract_id,
         &payload,
         tx_auth.into_val(&env),
         &auth_contexts,
     );
 
-    assert_eq!(res, Err(Ok(MultisigError::SignerNotFound)));
+    assert_eq!(res, Err(Ok(DvnError::SignerNotFound)));
 }
 
 #[test]
@@ -141,14 +158,18 @@ fn test_check_auth_invalid_vid_fails() {
     let auth_contexts: Vec<Context> = Vec::new(&env);
 
     let payload = BytesN::from_array(&env, &[0u8; 32]);
-    let admin = admin_kp.public_key(&env);
-    let admin_signature = admin_kp.sign(&env, &payload.to_array());
+    let public_key = admin_kp.public_key(&env);
+    let signature = admin_kp.sign(&env, &payload.to_array());
 
     let hash = hash_auth_data(&env, wrong_vid, expiration, &auth_contexts);
     let sig = setup.key_pairs[0].sign_bytes(&env, &hash);
 
-    let tx_auth =
-        TransactionAuthData { vid: wrong_vid, expiration, signatures: vec![&env, sig], admin, admin_signature };
+    let tx_auth = TransactionAuthData {
+        vid: wrong_vid,
+        expiration,
+        signatures: vec![&env, sig],
+        sender: Sender::Admin(public_key, signature),
+    };
 
     let res = env.try_invoke_contract_check_auth::<DvnError>(
         &setup.contract_id,
@@ -172,13 +193,18 @@ fn test_check_auth_expired_fails() {
     let auth_contexts: Vec<Context> = Vec::new(&env);
 
     let payload = BytesN::from_array(&env, &[0u8; 32]);
-    let admin = admin_kp.public_key(&env);
-    let admin_signature = admin_kp.sign(&env, &payload.to_array());
+    let public_key = admin_kp.public_key(&env);
+    let signature = admin_kp.sign(&env, &payload.to_array());
 
     let hash = hash_auth_data(&env, VID, expiration, &auth_contexts);
     let sig = setup.key_pairs[0].sign_bytes(&env, &hash);
 
-    let tx_auth = TransactionAuthData { vid: VID, expiration, signatures: vec![&env, sig], admin, admin_signature };
+    let tx_auth = TransactionAuthData {
+        vid: VID,
+        expiration,
+        signatures: vec![&env, sig],
+        sender: Sender::Admin(public_key, signature),
+    };
 
     let res = env.try_invoke_contract_check_auth::<DvnError>(
         &setup.contract_id,
@@ -202,8 +228,8 @@ fn test_check_auth_hash_already_used_fails() {
     let auth_contexts: Vec<Context> = Vec::new(&env);
 
     let payload = BytesN::from_array(&env, &[0u8; 32]);
-    let admin = admin_kp.public_key(&env);
-    let admin_signature = admin_kp.sign(&env, &payload.to_array());
+    let public_key = admin_kp.public_key(&env);
+    let signature = admin_kp.sign(&env, &payload.to_array());
 
     let hash = hash_auth_data(&env, VID, expiration, &auth_contexts);
     let sig = setup.key_pairs[0].sign_bytes(&env, &hash);
@@ -212,8 +238,7 @@ fn test_check_auth_hash_already_used_fails() {
         vid: VID,
         expiration,
         signatures: vec![&env, sig.clone()],
-        admin: admin.clone(),
-        admin_signature: admin_signature.clone(),
+        sender: Sender::Admin(public_key.clone(), signature.clone()),
     };
 
     let res = env.try_invoke_contract_check_auth::<DvnError>(
@@ -224,7 +249,12 @@ fn test_check_auth_hash_already_used_fails() {
     );
     assert!(res.is_ok());
 
-    let tx_auth2 = TransactionAuthData { vid: VID, expiration, signatures: vec![&env, sig], admin, admin_signature };
+    let tx_auth2 = TransactionAuthData {
+        vid: VID,
+        expiration,
+        signatures: vec![&env, sig],
+        sender: Sender::Admin(public_key, signature),
+    };
 
     let res2 = env.try_invoke_contract_check_auth::<DvnError>(
         &setup.contract_id,