@layerzerolabs/protocol-stellar-v2 0.2.8

package/contracts/message-libs/uln-302/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "uln302"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+doctest = false
+
+[features]
+library = []
+testutils = []
+
+[dependencies]
+cfg-if = { workspace = true }
+soroban-sdk = { workspace = true }
+# workspace dependencies
+utils = { workspace = true }
+common-macros = { workspace = true }
+endpoint-v2 = { workspace = true, features = ["library"] }
+message-lib-common = { workspace = true }
+
+[dev-dependencies]
+soroban-sdk = { workspace = true, features = ["testutils"] }
+message-lib-common = { workspace = true, features = ["testutils"] }
+utils = { workspace = true, features = ["testutils"] }

package/contracts/message-libs/uln-302/src/config_validation.rs

@@ -0,0 +1,173 @@
+use crate::errors::Uln302Error;
+use crate::interfaces::{ExecutorConfig, OAppUlnConfig, UlnConfig};
+use crate::OAppExecutorConfig;
+use soroban_sdk::{assert_with_error, map, vec, Env, IntoVal, TryFromVal, Val, Vec};
+
+/// Maximum number of DVNs allowed in a configuration.
+pub const MAX_DVNS: u32 = 127;
+
+// ================================================
+// Uln Config Validation
+// ================================================
+
+impl UlnConfig {
+    /// Validates the required DVNs configuration.
+    ///
+    /// Checks:
+    /// - No duplicate addresses in the required DVNs list
+    /// - Required DVNs count does not exceed MAX_DVNS limit
+    pub fn validate_required_dvns(&self, env: &Env) {
+        assert_with_error!(env, !has_duplicates(env, &self.required_dvns), Uln302Error::DuplicateRequiredDVNs);
+        assert_with_error!(env, self.required_dvns.len() <= MAX_DVNS, Uln302Error::InvalidRequiredDVNCount);
+    }
+
+    /// Validates the optional DVNs configuration and threshold.
+    ///
+    /// Checks:
+    /// - No duplicate addresses in the optional DVNs list
+    /// - Optional DVNs count does not exceed MAX_DVNS limit
+    /// - Threshold is valid: either (0 threshold with 0 DVNs) or (threshold between 1 and DVN count)
+    pub fn validate_optional_dvns(&self, env: &Env) {
+        assert_with_error!(env, !has_duplicates(env, &self.optional_dvns), Uln302Error::DuplicateOptionalDVNs);
+        assert_with_error!(env, self.optional_dvns.len() <= MAX_DVNS, Uln302Error::InvalidOptionalDVNCount);
+        assert_with_error!(
+            env,
+            (self.optional_dvn_threshold == 0 && self.optional_dvns.is_empty())
+                || (self.optional_dvn_threshold > 0 && self.optional_dvn_threshold <= self.optional_dvns.len()),
+            Uln302Error::InvalidOptionalDVNThreshold
+        );
+    }
+
+    /// Validates a UlnConfig for using as a default config.
+    ///
+    /// Performs comprehensive validation including:
+    /// - Required DVNs validation (no duplicates, within limits)
+    /// - Optional DVNs validation (no duplicates, within limits, valid threshold)
+    /// - At least one DVN requirement (either required or optional with threshold > 0)
+    pub fn validate_default_config(&self, env: &Env) {
+        self.validate_required_dvns(env);
+        self.validate_optional_dvns(env);
+        self.validate_at_least_one_dvn(env);
+    }
+
+    /// Validates that the configuration has at least one DVN for verification.
+    ///
+    /// A valid configuration must have either:
+    /// - At least one required DVN, OR
+    /// - An optional DVN threshold greater than 0
+    pub fn validate_at_least_one_dvn(&self, env: &Env) {
+        assert_with_error!(
+            env,
+            !self.required_dvns.is_empty() || self.optional_dvn_threshold > 0,
+            Uln302Error::UlnAtLeastOneDVN
+        );
+    }
+}
+
+impl OAppUlnConfig {
+    /// Creates a default OAppUlnConfig that uses all default values.
+    pub fn default(env: &Env) -> Self {
+        OAppUlnConfig {
+            use_default_confirmations: true,
+            use_default_required_dvns: true,
+            use_default_optional_dvns: true,
+            uln_config: UlnConfig {
+                confirmations: 0,
+                required_dvns: vec![&env],
+                optional_dvns: vec![&env],
+                optional_dvn_threshold: 0,
+            },
+        }
+    }
+
+    /// Validates an OAppUlnConfig for correctness.
+    ///
+    /// Checks:
+    /// - When using defaults, corresponding config values must be empty/zero
+    /// - When not using defaults, the provided values must be valid
+    pub fn validate_oapp_config(&self, env: &Env) {
+        assert_with_error!(
+            env,
+            !self.use_default_confirmations || self.uln_config.confirmations == 0,
+            Uln302Error::InvalidConfirmations
+        );
+
+        if self.use_default_required_dvns {
+            assert_with_error!(env, self.uln_config.required_dvns.is_empty(), Uln302Error::InvalidRequiredDVNs);
+        } else {
+            self.uln_config.validate_required_dvns(env);
+        }
+
+        if self.use_default_optional_dvns {
+            assert_with_error!(
+                env,
+                self.uln_config.optional_dvn_threshold == 0 && self.uln_config.optional_dvns.is_empty(),
+                Uln302Error::InvalidOptionalDVNs
+            );
+        } else {
+            self.uln_config.validate_optional_dvns(env);
+        }
+    }
+
+    /// Merges this OAppUlnConfig with a default UlnConfig to produce the effective config.
+    pub fn apply_default_config(&self, default_config: &UlnConfig) -> UlnConfig {
+        let confirmations =
+            if self.use_default_confirmations { default_config.confirmations } else { self.uln_config.confirmations };
+        let required_dvns = if self.use_default_required_dvns {
+            default_config.required_dvns.clone()
+        } else {
+            self.uln_config.required_dvns.clone()
+        };
+        let (optional_dvns, optional_dvn_threshold) = if self.use_default_optional_dvns {
+            (default_config.optional_dvns.clone(), default_config.optional_dvn_threshold)
+        } else {
+            (self.uln_config.optional_dvns.clone(), self.uln_config.optional_dvn_threshold)
+        };
+
+        UlnConfig { confirmations, required_dvns, optional_dvns, optional_dvn_threshold }
+    }
+}
+
+// ================================================
+// Executor Config Validation
+// ================================================
+
+impl ExecutorConfig {
+    /// Validates the executor config for use as a default configuration.
+    pub fn validate_default_config(&self, env: &Env) {
+        assert_with_error!(env, self.max_message_size != 0, Uln302Error::ZeroMessageSize);
+    }
+}
+
+impl OAppExecutorConfig {
+    /// Merges this OAppExecutorConfig with a default ExecutorConfig to produce the effective config.
+    pub fn apply_default_config(&self, default_config: &ExecutorConfig) -> ExecutorConfig {
+        ExecutorConfig {
+            max_message_size: if self.max_message_size != 0 {
+                self.max_message_size
+            } else {
+                default_config.max_message_size
+            },
+            executor: self.executor.clone().unwrap_or(default_config.executor.clone()),
+        }
+    }
+}
+
+// ================================================
+// Helper Functions
+// ================================================
+
+/// Checks if a vector contains duplicate elements.
+fn has_duplicates<T>(env: &Env, items: &Vec<T>) -> bool
+where
+    T: IntoVal<Env, Val> + TryFromVal<Env, Val> + Clone,
+{
+    let mut seen = map![env];
+    for item in items {
+        if seen.contains_key(item.clone()) {
+            return true;
+        }
+        seen.set(item, true);
+    }
+    false
+}

package/contracts/message-libs/uln-302/src/errors.rs

@@ -0,0 +1,29 @@
+use common_macros::contract_error;
+
+#[contract_error]
+pub enum Uln302Error {
+    DefaultExecutorConfigNotFound,
+    DefaultReceiveUlnConfigNotFound,
+    DefaultSendUlnConfigNotFound,
+    DuplicateOptionalDVNs,
+    DuplicateRequiredDVNs,
+    InvalidConfig,
+    InvalidConfigType,
+    InvalidConfirmations,
+    InvalidEID,
+    InvalidMessageSize,
+    InvalidOptionalDVNCount,
+    InvalidOptionalDVNs,
+    InvalidOptionalDVNThreshold,
+    InvalidPacketHeader,
+    InvalidRequiredDVNCount,
+    InvalidRequiredDVNs,
+    OAppExecutorConfigNotFound,
+    OAppReceiveUlnConfigNotFound,
+    OAppSendUlnConfigNotFound,
+    OnlyEndpoint,
+    UlnAtLeastOneDVN,
+    UnsupportedEid,
+    Verifying,
+    ZeroMessageSize,
+}

package/contracts/message-libs/uln-302/src/events.rs

@@ -0,0 +1,72 @@
+use crate::{
+    interfaces::{OAppExecutorConfig, OAppUlnConfig, SetDefaultUlnConfigParam},
+    SetDefaultExecutorConfigParam,
+};
+use common_macros::event;
+use endpoint_v2::FeeRecipient;
+use soroban_sdk::{Address, Bytes, BytesN, Vec};
+
+#[event]
+pub struct ExecutorConfigSet {
+    #[topic]
+    pub sender: Address,
+    #[topic]
+    pub dst_eid: u32,
+    pub config: OAppExecutorConfig,
+}
+
+#[event]
+pub struct UlnSendConfigSet {
+    #[topic]
+    pub sender: Address,
+    #[topic]
+    pub dst_eid: u32,
+    pub config: OAppUlnConfig,
+}
+
+#[event]
+pub struct UlnReceiveConfigSet {
+    #[topic]
+    pub receiver: Address,
+    #[topic]
+    pub src_eid: u32,
+    pub config: OAppUlnConfig,
+}
+
+#[event]
+pub struct DefaultExecutorConfigSet {
+    pub params: Vec<SetDefaultExecutorConfigParam>,
+}
+
+#[event]
+pub struct DefaultUlnSendConfigSet {
+    pub params: Vec<SetDefaultUlnConfigParam>,
+}
+
+#[event]
+pub struct DefaultUlnReceiveConfigSet {
+    pub params: Vec<SetDefaultUlnConfigParam>,
+}
+
+#[event]
+pub struct ExecutorFeePaid {
+    #[topic]
+    pub executor: Address,
+    pub fee: FeeRecipient,
+}
+
+#[event]
+pub struct DVNFeePaid {
+    #[topic]
+    pub dvns: Vec<Address>,
+    pub fees: Vec<FeeRecipient>,
+}
+
+#[event]
+pub struct PayloadVerified {
+    #[topic]
+    pub dvn: Address,
+    pub header: Bytes,
+    pub confirmations: u64,
+    pub proof_hash: BytesN<32>,
+}

package/contracts/message-libs/uln-302/src/interfaces/mod.rs

@@ -0,0 +1,5 @@
+pub mod receive;
+pub mod send;
+
+pub use receive::*;
+pub use send::*;

package/contracts/message-libs/uln-302/src/interfaces/receive.rs

@@ -0,0 +1,82 @@
+use crate::interfaces::{OAppUlnConfig, SetDefaultUlnConfigParam, UlnConfig};
+use soroban_sdk::{contractclient, Address, Bytes, BytesN, Env, Vec};
+
+/// Interface for ULN302 receive library functions.
+///
+/// Handles DVN verification and message commitment on the receiving chain.
+#[contractclient(name = "ReceiveUln302Client")]
+pub trait IReceiveUln302 {
+    /// Called by a DVN to verify a message with a specific number of confirmations.
+    ///
+    /// # Arguments
+    /// * `dvn` - The DVN address
+    /// * `packet_header` - The raw packet header bytes
+    /// * `payload_hash` - The hash of the message payload
+    /// * `confirmations` - The number of block confirmations the DVN has observed
+    fn verify(env: &Env, dvn: &Address, packet_header: &Bytes, payload_hash: &BytesN<32>, confirmations: u64);
+
+    /// Returns the block confirmations a DVN has reported for a message.
+    ///
+    /// # Arguments
+    /// * `dvn` - The DVN address
+    /// * `header_hash` - The hash of the packet header
+    /// * `payload_hash` - The hash of the message payload
+    fn confirmations(env: &Env, dvn: &Address, header_hash: &BytesN<32>, payload_hash: &BytesN<32>) -> Option<u64>;
+
+    /// Checks if a message has been verified by enough DVNs to be committed.
+    ///
+    /// Evaluates whether all required DVNs and the threshold of optional DVNs
+    /// have verified the message with sufficient block confirmations.
+    ///
+    /// # Arguments
+    /// * `packet_header` - The raw packet header bytes
+    /// * `payload_hash` - The hash of the message payload
+    ///
+    /// # Returns
+    /// True if the message has been verified by enough DVNs to be committed, false otherwise
+    fn verifiable(env: &Env, packet_header: &Bytes, payload_hash: &BytesN<32>) -> bool;
+
+    /// Permissonless to commit a verified message to the endpoint after sufficient DVN verification.
+    ///
+    /// Checks that all required DVNs and the optional DVN threshold have verified
+    /// the message, then calls `verify` on the endpoint to make the message executable.
+    ///
+    /// # Arguments
+    /// * `packet_header` - The raw packet header bytes
+    /// * `payload_hash` - The hash of the message payload
+    fn commit_verification(env: &Env, packet_header: &Bytes, payload_hash: &BytesN<32>);
+
+    /// Sets default receive ULN configurations for multiple source endpoints.
+    ///
+    /// # Arguments
+    /// * `params` - A vector of `SetDefaultUlnConfigParam`, each containing a source EID and its ULN config
+    fn set_default_receive_uln_configs(env: &Env, params: &Vec<SetDefaultUlnConfigParam>);
+
+    /// Returns the default receive ULN configuration for a source endpoint.
+    ///
+    /// # Arguments
+    /// * `src_eid` - The source endpoint ID
+    fn default_receive_uln_config(env: &Env, src_eid: u32) -> Option<UlnConfig>;
+
+    /// Returns the OApp-specific receive ULN configuration for a specific source endpoint.
+    ///
+    /// # Arguments
+    /// * `receiver` - The receiver OApp address
+    /// * `src_eid` - The source endpoint ID
+    fn oapp_receive_uln_config(env: &Env, receiver: &Address, src_eid: u32) -> Option<OAppUlnConfig>;
+
+    /// Gets the effective receive ULN configuration.
+    ///
+    /// Merges the OApp-specific config with the default config. OApp settings take precedence.
+    ///
+    /// # Arguments
+    /// * `receiver` - The receiver OApp address
+    /// * `src_eid` - The source endpoint ID
+    ///
+    /// # Returns
+    /// The effective receive ULN configuration
+    ///
+    /// # Panics
+    /// Panics if the default receive ULN configuration is not set for the source endpoint.
+    fn effective_receive_uln_config(env: &Env, receiver: &Address, src_eid: u32) -> UlnConfig;
+}

package/contracts/message-libs/uln-302/src/interfaces/send.rs

@@ -0,0 +1,159 @@
+use endpoint_v2::ISendLib;
+use soroban_sdk::{contractclient, contracttype, Address, Env, Vec};
+
+// ================================================
+// Config Types
+// ================================================
+
+/// Ultra Light Node configuration for message verification.
+#[contracttype]
+#[derive(Clone, Eq, PartialEq, Debug)]
+pub struct UlnConfig {
+    /// Number of block confirmations required before message verification begins.
+    pub confirmations: u64,
+    /// List of DVN addresses that must ALL verify the message (no threshold).
+    pub required_dvns: Vec<Address>,
+    /// List of DVN addresses from which a threshold number must verify.
+    pub optional_dvns: Vec<Address>,
+    /// Minimum number of optional DVNs required to verify.
+    pub optional_dvn_threshold: u32,
+}
+
+/// OApp-specific ULN configuration with default override flags.
+#[contracttype]
+#[derive(Clone, Eq, PartialEq, Debug)]
+pub struct OAppUlnConfig {
+    /// Whether to use default confirmations.
+    pub use_default_confirmations: bool,
+    /// Whether to use default required DVNs.
+    pub use_default_required_dvns: bool,
+    /// Whether to use default optional DVNs.
+    pub use_default_optional_dvns: bool,
+    /// OApp-specific ULN configuration (used when defaults are not applied).
+    pub uln_config: UlnConfig,
+}
+
+/// Parameter for setting default ULN configuration for a destination/source endpoint.
+#[contracttype]
+#[derive(Clone, Eq, PartialEq, Debug)]
+pub struct SetDefaultUlnConfigParam {
+    /// The destination endpoint ID (for send) or source endpoint ID (for receive).
+    pub dst_eid: u32,
+    /// The ULN configuration to set as default.
+    pub config: UlnConfig,
+}
+
+// === Executor Config Types ===
+
+/// Executor configuration for message delivery.
+#[contracttype]
+#[derive(Clone, Eq, PartialEq, Debug)]
+pub struct ExecutorConfig {
+    /// Maximum size of messages that can be executed (in bytes).
+    pub max_message_size: u32,
+    /// Address of the executor contract responsible for message execution.
+    pub executor: Address,
+}
+
+/// OApp-specific executor configuration.
+///
+/// If executor is `None`, the default executor is used.
+#[contracttype]
+#[derive(Clone, Default, Eq, PartialEq, Debug)]
+pub struct OAppExecutorConfig {
+    /// Maximum size of messages that can be executed (in bytes). 0 means use default configuration.
+    pub max_message_size: u32,
+    /// Address of the executor contract to be used for message execution. None means use default configuration.
+    pub executor: Option<Address>,
+}
+
+/// Parameter for setting default executor configuration for a destination endpoint.
+#[contracttype]
+#[derive(Clone, Eq, PartialEq, Debug)]
+pub struct SetDefaultExecutorConfigParam {
+    /// The destination endpoint ID.
+    pub dst_eid: u32,
+    /// The executor configuration to set as default.
+    pub config: ExecutorConfig,
+}
+
+// ================================================
+// ISendUln302 Trait
+// ================================================
+
+/// Interface for ULN302 send library functions.
+///
+/// Extends `ISendLib` with ULN-specific configuration management for executors and DVNs.
+#[contractclient(name = "SendUln302Client")]
+pub trait ISendUln302: ISendLib {
+    /// Returns the treasury address for fee collection.
+    fn treasury(env: &Env) -> Address;
+
+    /// Sets default executor configurations for multiple destination endpoints.
+    ///
+    /// # Arguments
+    /// * `params` - A vector of `SetDefaultExecutorConfigParam`, each containing a destination EID and its executor config
+    fn set_default_executor_configs(env: &Env, params: &Vec<SetDefaultExecutorConfigParam>);
+
+    /// Returns the default executor configuration for a destination endpoint.
+    ///
+    /// # Arguments
+    /// * `dst_eid` - The destination endpoint ID
+    fn default_executor_config(env: &Env, dst_eid: u32) -> Option<ExecutorConfig>;
+
+    /// Returns the OApp-specific executor configuration for a specific destination endpoint.
+    ///
+    /// # Arguments
+    /// * `sender` - The sender OApp address
+    /// * `dst_eid` - The destination endpoint ID
+    fn oapp_executor_config(env: &Env, sender: &Address, dst_eid: u32) -> Option<OAppExecutorConfig>;
+
+    /// Gets the effective executor configuration (OApp config merged with default).
+    ///
+    /// Merges the OApp-specific config with the default config. OApp settings take precedence.
+    ///
+    /// # Arguments
+    /// * `sender` - The sender OApp address
+    /// * `dst_eid` - The destination endpoint ID
+    ///
+    /// # Returns
+    /// The effective executor configuration
+    ///
+    /// # Panics
+    /// Panics if the default executor configuration is not set for the destination endpoint.
+    fn effective_executor_config(env: &Env, sender: &Address, dst_eid: u32) -> ExecutorConfig;
+
+    /// Sets default send ULN configurations for multiple destination endpoints.
+    ///
+    /// # Arguments
+    /// * `params` - A vector of `SetDefaultUlnConfigParam`, each containing a destination EID and its ULN config
+    fn set_default_send_uln_configs(env: &Env, params: &Vec<SetDefaultUlnConfigParam>);
+
+    /// Returns the default send ULN configuration for a destination endpoint.
+    ///
+    /// # Arguments
+    /// * `dst_eid` - The destination endpoint ID
+    fn default_send_uln_config(env: &Env, dst_eid: u32) -> Option<UlnConfig>;
+
+    /// Returns the OApp-specific send ULN configuration for a specific destination endpoint.
+    ///
+    /// # Arguments
+    /// * `sender` - The sender OApp address
+    /// * `dst_eid` - The destination endpoint ID
+    fn oapp_send_uln_config(env: &Env, sender: &Address, dst_eid: u32) -> Option<OAppUlnConfig>;
+
+    /// Gets the effective send ULN configuration (OApp config merged with default).
+    ///
+    /// Merges the OApp-specific config with the default config. OApp settings take precedence.
+    ///
+    /// # Arguments
+    /// * `sender` - The sender OApp address
+    /// * `dst_eid` - The destination endpoint ID
+    ///
+    /// # Returns
+    /// The effective send ULN configuration
+    ///
+    /// # Panics
+    /// Panics if the default send ULN configuration is not set for the destination endpoint.
+    fn effective_send_uln_config(env: &Env, sender: &Address, dst_eid: u32) -> UlnConfig;
+}

package/contracts/message-libs/uln-302/src/lib.rs

@@ -0,0 +1,20 @@
+#![no_std]
+
+mod interfaces;
+
+pub use interfaces::*;
+
+cfg_if::cfg_if! {
+    if #[cfg(any(not(feature = "library"), feature = "testutils"))] {
+        mod config_validation;
+        mod errors;
+        mod events;
+        mod storage;
+        mod uln302;
+
+        pub use uln302::{Uln302, Uln302Client};
+    }
+}
+
+#[cfg(test)]
+mod tests;