@layerzerolabs/protocol-stellar-v2 0.2.10 → 0.2.12

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

@@ -1,27 +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::{
-    errors::{DvnError, MultisigError},
-    events::SetDstConfig,
-    storage::DvnStorage,
-    types::{DstConfig, DstConfigParam},
-    IDVN,
+    errors::DvnError, events::SetDstConfig, storage::DvnStorage, Call, 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, 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;
 
-#[contractimpl]
-impl Dvn {
+// ============================================================================
+// Core Implementation
+// ============================================================================
+
+#[contract_impl]
+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,
@@ -30,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);
     }
 
@@ -55,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) {
@@ -66,8 +99,13 @@ impl Dvn {
     }
 }
 
-#[contractimpl]
-impl IDVN for Dvn {
+// ============================================================================
+// IDVN Implementation
+// ============================================================================
+
+#[contract_impl]
+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 {
@@ -77,17 +115,35 @@ 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)
+    /// 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()
+    }
 }
 
-#[contractimpl]
-impl ILayerZeroDVN for Dvn {
+// ============================================================================
+// ILayerZeroDVN Implementation (Send Flow)
+// ============================================================================
+
+#[contract_impl]
+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,
@@ -101,7 +157,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,9 +171,13 @@ 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)
     }
 
+    /// 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,
@@ -136,8 +196,18 @@ impl ILayerZeroDVN for Dvn {
     }
 }
 
-#[contractimpl(contracttrait)]
-impl Worker for Dvn {}
+// ============================================================================
+// Worker Implementation
+// ============================================================================
+
+#[contract_impl(contracttrait)]
+impl Worker for LzDVN {}
+
+// ============================================================================
+// Include SubModules
+// ============================================================================
 
-include!("multisig.rs");
-include!("auth.rs");
+#[path = "auth.rs"]
+pub mod auth;
+#[path = "multisig.rs"]
+pub mod multisig;

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,12 +1,85 @@
-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, BytesN, Env, Symbol, Val, 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,
+}
+
+/// 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
+/// 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;
+
+    /// 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/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);
 }

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

@@ -1,24 +1,22 @@
 #![no_std]
-#[cfg(test)]
-extern crate std;
 
-mod errors;
+pub mod errors;
 pub mod events;
-mod interfaces;
-mod types;
+pub mod interfaces;
 
-pub use errors::*;
 pub use interfaces::*;
-pub use types::*;
 
 cfg_if::cfg_if! {
     if #[cfg(any(not(feature = "library"), feature = "testutils"))] {
         mod storage;
         mod dvn;
 
-        pub use dvn::Dvn;
+        pub use dvn::*;
     }
 }
 
+#[cfg(test)]
+extern crate std;
+
 #[cfg(test)]
 mod tests;