@layerzerolabs/protocol-stellar-v2 0.2.11 → 0.2.12

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

@@ -1,23 +1,50 @@
+//! LayerZero Decentralized Verifier Network (DVN) contract.
+//!
+//! The DVN is responsible for verifying cross-chain messages by providing
+//! cryptographic attestations. It uses a multisig scheme with secp256k1
+//! signatures for authorization and implements Soroban's custom account
+//! interface for transaction signing.
+
 use crate::{
-    dvn::multisig::init_multisig, errors::DvnError, events::SetDstConfig, storage::DvnStorage, DstConfig,
-    DstConfigParam, IMultisig, IDVN,
+    errors::DvnError, events::SetDstConfig, storage::DvnStorage, Call, DstConfig, DstConfigParam, IMultisig, IDVN,
 };
 use common_macros::{contract_impl, ttl_configurable};
 use endpoint_v2::FeeRecipient;
 use message_lib_common::interfaces::ILayerZeroDVN;
-use soroban_sdk::{contract, Address, Bytes, BytesN, Env, Vec};
+use soroban_sdk::{contract, xdr::ToXdr, Address, Bytes, BytesN, Env, Vec};
+use utils::buffer_writer::BufferWriter;
 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,
+    set_admin_by_owner, DvnFeeLibClient, DvnFeeParams, Worker,
 };
 
+/// LayerZero DVN contract.
+///
+/// Implements multisig-based verification with custom account authorization.
+/// The contract owns itself, allowing the multisig quorum to authorize operations.
 #[contract]
 #[ttl_configurable]
-pub struct Dvn;
+pub struct LzDVN;
+
+// ============================================================================
+// Core Implementation
+// ============================================================================
 
 #[contract_impl]
-impl Dvn {
+impl LzDVN {
+    /// Initializes the DVN contract.
+    ///
+    /// # Arguments
+    /// * `vid` - Verifier ID, unique identifier for this DVN
+    /// * `signers` - Initial multisig signers (20-byte Ethereum addresses)
+    /// * `threshold` - Minimum signatures required for multisig operations
+    /// * `admins` - Initial admin addresses for operational functions
+    /// * `supported_msglibs` - Message libraries this DVN supports (e.g., ULN302)
+    /// * `price_feed` - Price feed contract for fee calculations
+    /// * `default_multiplier_bps` - Default fee multiplier (10000 = 1x)
+    /// * `worker_fee_lib` - Fee library contract for computing DVN fees
+    /// * `deposit_address` - Address to receive fee payments
     pub fn __constructor(
         env: &Env,
         vid: u32,
@@ -26,15 +53,22 @@ impl Dvn {
         admins: &Vec<Address>,
         supported_msglibs: &Vec<Address>,
         price_feed: &Address,
-        worker_fee_lib: &Address,
         default_multiplier_bps: u32,
+        worker_fee_lib: &Address,
         deposit_address: &Address,
     ) {
-        init_multisig(env, signers, threshold);
+        Self::init_multisig(env, signers, threshold);
         Self::init_owner(env, &env.current_contract_address());
-        init_worker::<Self>(env, admins, supported_msglibs, price_feed, default_multiplier_bps);
-        WorkerStorage::set_worker_fee_lib(env, worker_fee_lib);
-        WorkerStorage::set_deposit_address(env, deposit_address);
+        init_worker::<Self>(
+            env,
+            admins,
+            supported_msglibs,
+            price_feed,
+            default_multiplier_bps,
+            worker_fee_lib,
+            deposit_address,
+        );
+
         DvnStorage::set_vid(env, &vid);
     }
 
@@ -51,10 +85,13 @@ impl Dvn {
         set_admin_by_admin::<Self>(env, caller, admin, active);
     }
 
-    /// Function for quorum to change the admin without going through the execute function
+    /// Allows the quorum to add/remove admins without requiring an admin signature.
     ///
-    /// # Arguments
+    /// This function bypasses the normal admin verification in `__check_auth`,
+    /// requiring only multisig quorum signatures. Must be called as a single
+    /// operation (cannot be bundled with other calls).
     ///
+    /// # Arguments
     /// * `admin` - The address to set admin status for
     /// * `active` - `true` to add admin, `false` to remove
     pub fn quorum_change_admin(env: &Env, admin: &Address, active: bool) {
@@ -62,8 +99,13 @@ impl Dvn {
     }
 }
 
+// ============================================================================
+// IDVN Implementation
+// ============================================================================
+
 #[contract_impl]
-impl IDVN for Dvn {
+impl IDVN for LzDVN {
+    /// Sets destination chain configurations. Requires admin authorization.
     fn set_dst_config(env: &Env, admin: &Address, params: &Vec<DstConfigParam>) {
         require_admin_auth::<Self>(env, admin);
         for param in params {
@@ -73,17 +115,35 @@ impl IDVN for Dvn {
         SetDstConfig { params: params.clone() }.publish(env);
     }
 
+    /// Returns the destination configuration for a specific endpoint ID.
     fn dst_config(env: &Env, dst_eid: u32) -> Option<DstConfig> {
         DvnStorage::dst_config(env, dst_eid)
     }
 
+    /// Returns the Verifier ID for this DVN.
     fn vid(env: &Env) -> u32 {
         DvnStorage::vid(env).unwrap()
     }
+
+    /// Computes the hash of call data for multisig signing.
+    ///
+    /// Off-chain signers use this to compute the hash they need to sign.
+    fn hash_call_data(env: &Env, vid: u32, expiration: u64, calls: &Vec<Call>) -> BytesN<32> {
+        let mut writer = BufferWriter::new(env);
+        let data = writer.write_u32(vid).write_u64(expiration).write_bytes(&calls.to_xdr(env)).to_bytes();
+        env.crypto().keccak256(&data).into()
+    }
 }
 
+// ============================================================================
+// ILayerZeroDVN Implementation (Send Flow)
+// ============================================================================
+
 #[contract_impl]
-impl ILayerZeroDVN for Dvn {
+impl ILayerZeroDVN for LzDVN {
+    /// Calculates the verification fee for a cross-chain message.
+    ///
+    /// Called by the send library to quote DVN fees before sending.
     fn get_fee(
         env: &Env,
         _send_lib: &Address,
@@ -114,6 +174,10 @@ impl ILayerZeroDVN for Dvn {
         DvnFeeLibClient::new(env, &Self::worker_fee_lib(env)).get_fee(&env.current_contract_address(), &params)
     }
 
+    /// Assigns a verification job to this DVN and returns fee payment info.
+    ///
+    /// Called by the send library when a message is sent. The DVN will later
+    /// verify the message on the destination chain.
     fn assign_job(
         env: &Env,
         send_lib: &Address,
@@ -132,8 +196,12 @@ impl ILayerZeroDVN for Dvn {
     }
 }
 
+// ============================================================================
+// Worker Implementation
+// ============================================================================
+
 #[contract_impl(contracttrait)]
-impl Worker for Dvn {}
+impl Worker for LzDVN {}
 
 // ============================================================================
 // Include SubModules

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

@@ -1,21 +1,18 @@
 use common_macros::contract_error;
 
-#[contract_error]
-pub enum MultisigError {
-    ZeroThreshold,
-    TotalSignersLessThanThreshold,
-    InvalidSigner,
-    SignerAlreadyExists,
-    SignerNotFound,
-    UnsortedSigners,
-    SignatureError,
-}
-
 #[contract_error]
 pub enum DvnError {
-    InvalidVid,
     AuthDataExpired,
+    EidNotSupported,
     HashAlreadyUsed,
+    InvalidSigner,
+    InvalidVid,
+    NonContractInvoke,
     OnlyAdmin,
-    EidNotSupported,
+    SignatureError,
+    SignerAlreadyExists,
+    SignerNotFound,
+    TotalSignersLessThanThreshold,
+    UnsortedSigners,
+    ZeroThreshold,
 }

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

@@ -1,19 +1,21 @@
 use crate::DstConfigParam;
-use common_macros::event;
-use soroban_sdk::{BytesN, Vec};
+use soroban_sdk::{contractevent, BytesN, Vec};
 
-#[event]
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
 pub struct SignerSet {
     pub signer: BytesN<20>,
     pub active: bool,
 }
 
-#[event]
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
 pub struct ThresholdSet {
     pub threshold: u32,
 }
 
-#[event]
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
 pub struct SetDstConfig {
     pub params: Vec<DstConfigParam>,
 }

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

@@ -1,6 +1,6 @@
 use crate::IMultisig;
 use message_lib_common::interfaces::ILayerZeroDVN;
-use soroban_sdk::{contractclient, contracttype, Address, Env, Vec};
+use soroban_sdk::{contractclient, contracttype, Address, BytesN, Env, Symbol, Val, Vec};
 use worker::Worker;
 
 /// Configuration for a destination chain.
@@ -28,6 +28,20 @@ pub struct DstConfigParam {
     pub config: DstConfig,
 }
 
+/// Represents a single contract invocation for multisig authorization.
+///
+/// Used in `hash_call_data` to compute the hash that signers sign over.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct Call {
+    /// Target contract address.
+    pub to: Address,
+    /// Function name to invoke.
+    pub func: Symbol,
+    /// Function arguments.
+    pub args: Vec<Val>,
+}
+
 /// DVN (Decentralized Verifier Network) contract interface.
 ///
 /// Extends the LayerZero DVN interface with destination configuration management
@@ -54,4 +68,18 @@ pub trait IDVN: ILayerZeroDVN + Worker + IMultisig {
     ///
     /// The VID is a unique identifier used in multisig authentication.
     fn vid(env: &Env) -> u32;
+
+    /// Computes the hash of call data for multisig signing.
+    ///
+    /// Off-chain signers use this to compute the hash they need to sign.
+    /// The hash includes the VID, expiration, and the calls being authorized.
+    ///
+    /// # Arguments
+    /// * `vid` - Verifier ID (must match contract's VID)
+    /// * `expiration` - Expiration timestamp for the authorization
+    /// * `calls` - The contract calls being authorized
+    ///
+    /// # Returns
+    /// A 32-byte keccak256 hash to be signed by the multisig quorum
+    fn hash_call_data(env: &Env, vid: u32, expiration: u64, calls: &Vec<Call>) -> BytesN<32>;
 }

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

@@ -1,65 +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::MultisigError,
+    errors::DvnError,
     events::{SignerSet, ThresholdSet},
-    storage::MultisigStorage,
+    storage::DvnStorage,
 };
 use soroban_sdk::assert_with_error;
 
+// ============================================================================
+// IMultisig Implementation
+// ============================================================================
+
 #[contract_impl]
-impl IMultisig for Dvn {
+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);
         });
@@ -67,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);
 
-pub 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> },