@layerzerolabs/protocol-starknet-v2 0.0.34

package/layerzero/src/message_lib/uln/interface.cairo

@@ -0,0 +1,83 @@
+//! Ultra light node admin interface
+
+use layerzero::message_lib::uln::structs::executor_config::ExecutorConfig;
+use layerzero::message_lib::uln::structs::uln_config::{SetDefaultUlnConfigParam, UlnConfig};
+use lz_utils::bytes::Bytes32;
+use starknet::ContractAddress;
+
+#[starknet::interface]
+pub trait IUltraLightNodeAdmin<TContractState> {
+    // -- Setter functions for configuration
+    /// Sets the default ULN send configuration for multiple destination endpoints
+    fn set_default_uln_send_config(
+        ref self: TContractState, configs: Array<SetDefaultUlnConfigParam>,
+    );
+
+    /// Sets the default ULN receive configuration for multiple destination endpoints
+    fn set_default_uln_receive_config(
+        ref self: TContractState, configs: Array<SetDefaultUlnConfigParam>,
+    );
+
+    /// Sets the default executor configuration for a specific destination endpoint
+    fn set_default_executor_config(ref self: TContractState, dst_eid: u32, config: ExecutorConfig);
+
+    // -- Getter functions for verification
+    /// Gets the default ULN send configuration for a destination endpoint
+    fn get_default_uln_send_config(self: @TContractState, dst_eid: u32) -> UlnConfig;
+
+    /// Gets the default ULN receive configuration for a destination endpoint
+    fn get_default_uln_receive_config(self: @TContractState, src_eid: u32) -> UlnConfig;
+
+    /// Gets the raw (stored) ULN send configuration for a specific OApp
+    fn get_raw_oapp_uln_send_config(
+        self: @TContractState, oapp: ContractAddress, dst_eid: u32,
+    ) -> UlnConfig;
+
+    /// Gets the raw (stored) ULN receive configuration for a specific OApp
+    fn get_raw_oapp_uln_receive_config(
+        self: @TContractState, oapp: ContractAddress, src_eid: u32,
+    ) -> UlnConfig;
+
+    /// Gets the effective ULN send configuration for a specific OApp
+    fn get_oapp_uln_send_config(
+        self: @TContractState, oapp: ContractAddress, dst_eid: u32,
+    ) -> UlnConfig;
+
+    /// Gets the effective ULN receive configuration for a specific OApp
+    fn get_oapp_uln_receive_config(
+        self: @TContractState, oapp: ContractAddress, src_eid: u32,
+    ) -> UlnConfig;
+
+    /// Gets the default executor configuration for a destination endpoint
+    fn get_default_executor_config(self: @TContractState, dst_eid: u32) -> ExecutorConfig;
+
+    /// Gets the raw (stored) executor configuration for a specific OApp
+    fn get_raw_oapp_executor_config(
+        self: @TContractState, oapp: ContractAddress, dst_eid: u32,
+    ) -> ExecutorConfig;
+
+    /// Gets the effective executor configuration for a specific OApp
+    fn get_oapp_executor_config(
+        self: @TContractState, oapp: ContractAddress, dst_eid: u32,
+    ) -> ExecutorConfig;
+
+    /// Gets the current treasury contract address
+    fn get_treasury(self: @TContractState) -> ContractAddress;
+
+    /// Sets the treasury floor fee
+    fn set_treasury_native_fee_cap(ref self: TContractState, native_fee_cap: u256);
+
+    /// Gets the treasury native fee cap
+    fn get_treasury_native_fee_cap(self: @TContractState) -> u256;
+
+    /// Checks if the payload has been signed by a DVN
+    ///
+    /// # Arguments
+    ///
+    /// * `header_hash`: The header hash of the payload
+    /// * `payload_hash`: The payload hash
+    /// * `dvn`: The DVN contract address
+    fn has_payload_signed(
+        self: @TContractState, header_hash: Bytes32, payload_hash: Bytes32, dvn: ContractAddress,
+    ) -> bool;
+}

package/layerzero/src/message_lib/uln/options.cairo

@@ -0,0 +1,64 @@
+use alexandria_bytes::byte_array_ext::ByteArrayTraitExt;
+use core::byte_array::{ByteArray, ByteArrayTrait};
+use starkware_utils::errors::assert_with_byte_array;
+
+// Import error functions
+use crate::message_lib::uln::errors::{
+    err_invalid_worker_id, err_invalid_worker_options, err_unsupported_option_type,
+};
+use crate::workers::dvn::options::DVN_WORKER_ID;
+use crate::workers::executor::options::EXECUTOR_WORKER_ID;
+
+// Option type constants
+pub const TYPE_3: u16 = 3;
+
+/// Decode the options into executor_options and dvn_options
+///
+/// # Arguments
+/// * `options` - The options can be either legacy options (type 1 or 2) or type 3 options
+///
+/// # Returns
+/// * `(executor_options, dvn_options)` - The executor options and DVN options in type 3 format
+pub fn split_options(options: @ByteArray) -> (ByteArray, ByteArray) {
+    // At least 2 bytes for the option type, but can have no options
+    assert_with_byte_array(options.len() >= 2, err_invalid_worker_options(0));
+
+    // we don't support legacy options here, only allowing option type 3
+    let (mut cursor, options_type) = options.read_u16(0);
+    assert_with_byte_array(options_type == TYPE_3, err_unsupported_option_type(options_type));
+
+    // Type3 options: [worker_option][worker_option]...
+    // worker_option: [worker_id][option_size][option]
+    // worker_id: u8, option_size: u16, option: bytes
+
+    let mut executor_options: ByteArray = Default::default();
+    let mut dvn_options: ByteArray = Default::default();
+
+    while cursor != options.len() {
+        // worker_id can't be zero
+        let (new_cursor, worker_id) = options.read_u8(cursor);
+        assert_with_byte_array(worker_id != 0, err_invalid_worker_id(0));
+
+        let (new_cursor, options_size) = options.read_u16(new_cursor);
+        assert_with_byte_array(options_size != 0, err_invalid_worker_options(new_cursor));
+
+        let (new_cursor, option) = options.read_bytes(new_cursor, options_size.into());
+
+        if worker_id == EXECUTOR_WORKER_ID {
+            executor_options.append_u8(EXECUTOR_WORKER_ID);
+            executor_options.append_u16(options_size);
+            executor_options.append(@option);
+        } else if worker_id == DVN_WORKER_ID {
+            dvn_options.append_u8(DVN_WORKER_ID);
+            dvn_options.append_u16(options_size);
+            dvn_options.append(@option);
+        }
+
+        cursor = new_cursor;
+
+        // The cursor must never exceed option length
+        assert_with_byte_array(cursor <= options.len(), err_invalid_worker_options(cursor));
+    }
+
+    (executor_options, dvn_options)
+}

package/layerzero/src/message_lib/uln/structs/executor_config.cairo

@@ -0,0 +1,35 @@
+//! Executor configuration struct
+
+use starknet::ContractAddress;
+use crate::common::constants::ZERO_ADDRESS;
+
+#[derive(Drop, Serde, Clone, PartialEq, starknet::Store)]
+pub struct ExecutorConfig {
+    pub max_message_size: u32,
+    pub executor: ContractAddress,
+}
+
+impl ExecutorConfigDefault of Default<ExecutorConfig> {
+    fn default() -> ExecutorConfig {
+        ExecutorConfig { max_message_size: 0, executor: ZERO_ADDRESS }
+    }
+}
+
+pub trait ExecutorConfigResolver {
+    /// Resolves a ULN configuration by merging default and custom configurations
+    /// Following the same logic as getUlnConfig in the Solidity implementation
+    fn resolve(default_config: @ExecutorConfig, custom_config: @ExecutorConfig) -> ExecutorConfig;
+}
+
+pub impl ExecutorConfigResolverImpl of ExecutorConfigResolver {
+    fn resolve(default_config: @ExecutorConfig, custom_config: @ExecutorConfig) -> ExecutorConfig {
+        let mut resolved_config: ExecutorConfig = default_config.clone();
+        if *custom_config.max_message_size != 0 {
+            resolved_config.max_message_size = *custom_config.max_message_size;
+        }
+        if !(*custom_config.executor == ZERO_ADDRESS) {
+            resolved_config.executor = *custom_config.executor;
+        }
+        resolved_config
+    }
+}

package/layerzero/src/message_lib/uln/structs/payment_info.cairo

@@ -0,0 +1,7 @@
+use crate::common::structs::messaging::Payee;
+
+#[derive(Drop, Serde, PartialEq, Clone, Debug)]
+pub struct DvnPaymentInfo {
+    pub payees: Array<Payee>,
+    pub total_native_fee: u256,
+}

package/layerzero/src/message_lib/uln/structs/uln_config.cairo

@@ -0,0 +1,155 @@
+use starknet::ContractAddress;
+use starkware_utils::errors::assert_with_byte_array;
+use crate::message_lib::uln::errors::{
+    err_invalid_confirmations, err_invalid_optional_dvn_threshold, err_must_have_at_least_one_dvn,
+    err_too_many_dvns, err_unsorted_dvns,
+};
+
+#[derive(Debug, Drop, Serde, Clone, PartialEq)]
+pub struct UlnConfig {
+    // Using the has_* method instead of *_is_null (as we did in TON), because
+    // The Starknet Map<Key, Value> will always fall back to the default of <Value> if
+    // we haven't explicitly set the relevant <Key> in there.
+    // If we use the *_is_null method, all of the unset custom configurations will
+    // fall back to being not_null, which means an unset custom OApp configuration will overwrite
+    // the set default configuration
+    // the has_* fields are ignored in the `defaultConfig` variations.
+    pub confirmations: u64,
+    pub has_confirmations: bool,
+    // no duplicates. sorted in ascending order. allowed overlap with optionalDVNs
+    pub required_dvns: Array<ContractAddress>,
+    pub has_required_dvns: bool,
+    // no duplicates. sorted in ascending order. allowed overlap with requiredDVNs
+    pub optional_dvns: Array<ContractAddress>,
+    pub optional_dvn_threshold: u8, // (0, optionalDvnCount]
+    pub has_optional_dvns: bool,
+}
+
+// TODO: This number should be the maximum possible in this VM
+// We will need to profile it to see if it can be lower/higher
+// (main limitation being having to call this amount of DVNs to quote/assignJob)
+pub const MAX_DVN_COUNT: u32 = 255;
+
+#[derive(Drop, Serde, Clone, PartialEq)]
+pub struct SetDefaultUlnConfigParam {
+    pub eid: u32, // endpoint ID
+    pub config: UlnConfig,
+}
+
+pub trait UlnConfigUtils {
+    /// Resolves a ULN configuration by merging default and custom configurations
+    /// Following the same logic as getUlnConfig in the Solidity implementation
+    fn resolve(default_config: @UlnConfig, custom_config: @UlnConfig) -> UlnConfig;
+
+    /// Asserts that both dvn arrays of the config have no duplicates
+    fn assert_no_duplicate_dvns(config: @UlnConfig);
+
+    /// Asserts that DVNs are sorted in ascending order with no duplicates
+    fn assert_no_duplicates_in_dvn_array(dvns: @Array<ContractAddress>);
+
+    /// Asserts that at least one DVN is configured
+    fn assert_at_least_one_dvn(config: @UlnConfig);
+
+    /// Asserts that the optional DVN threshold is valid
+    fn assert_valid_optional_threshold(config: @UlnConfig);
+
+    /// Asserts that the total DVN count doesn't exceed the maximum
+    fn assert_max_dvn_count(config: @UlnConfig);
+
+    /// Asserts that the config confirmations are valid
+    fn assert_valid_confirmations(confirmations: u64);
+
+    // Asserts that a standalone config (post-resolve / default) is valid
+    fn assert_valid_standalone_config(config: @UlnConfig);
+}
+
+pub impl UlnConfigUtilsImpl of UlnConfigUtils {
+    fn resolve(default_config: @UlnConfig, custom_config: @UlnConfig) -> UlnConfig {
+        let mut resolved_config = default_config.clone();
+
+        // Resolve confirmations
+        if *custom_config.has_confirmations {
+            resolved_config.confirmations = *custom_config.confirmations;
+        }
+
+        // Resolve required DVNs
+        if *custom_config.has_required_dvns {
+            resolved_config.required_dvns = custom_config.required_dvns.clone();
+        }
+
+        // Resolve optional DVNs
+        if *custom_config.has_optional_dvns {
+            resolved_config.optional_dvns = custom_config.optional_dvns.clone();
+            resolved_config.optional_dvn_threshold = *custom_config.optional_dvn_threshold;
+        }
+
+        Self::assert_valid_standalone_config(@resolved_config);
+
+        resolved_config
+    }
+
+    fn assert_no_duplicate_dvns(config: @UlnConfig) {
+        Self::assert_no_duplicates_in_dvn_array(config.required_dvns);
+        Self::assert_no_duplicates_in_dvn_array(config.optional_dvns);
+    }
+
+    fn assert_no_duplicates_in_dvn_array(dvns: @Array<ContractAddress>) {
+        let mut last_dvn: ContractAddress = 0.try_into().unwrap();
+        let mut i = 0;
+
+        while i != dvns.len() {
+            let current_dvn = *dvns.at(i);
+
+            // Check if current DVN is less than or equal to the last DVN
+            // This ensures both sorting and no duplicates
+            assert_with_byte_array(current_dvn > last_dvn.into(), err_unsorted_dvns());
+
+            last_dvn = current_dvn;
+            i += 1;
+        }
+    }
+
+    fn assert_at_least_one_dvn(config: @UlnConfig) {
+        let required_count = config.required_dvns.len();
+        let optional_threshold = *config.optional_dvn_threshold;
+
+        assert_with_byte_array(
+            !(required_count == 0 && optional_threshold == 0), err_must_have_at_least_one_dvn(),
+        );
+    }
+
+    fn assert_valid_optional_threshold(config: @UlnConfig) {
+        let optional_count = config.optional_dvns.len();
+        let threshold = *config.optional_dvn_threshold;
+
+        assert_with_byte_array(
+            (optional_count >= threshold.into()),
+            err_invalid_optional_dvn_threshold(optional_count, threshold),
+        );
+
+        assert_with_byte_array(
+            !((optional_count > 0) && (threshold <= 0)),
+            err_invalid_optional_dvn_threshold(optional_count, threshold),
+        );
+    }
+
+    fn assert_max_dvn_count(config: @UlnConfig) {
+        let required_count = config.required_dvns.len();
+        let optional_count = config.optional_dvns.len();
+
+        assert_with_byte_array(
+            (optional_count + required_count <= MAX_DVN_COUNT),
+            err_too_many_dvns(required_count, optional_count),
+        );
+    }
+
+    fn assert_valid_confirmations(confirmations: u64) {
+        assert_with_byte_array(confirmations > 0, err_invalid_confirmations());
+    }
+
+    fn assert_valid_standalone_config(config: @UlnConfig) {
+        Self::assert_at_least_one_dvn(config);
+        Self::assert_valid_optional_threshold(config);
+        Self::assert_max_dvn_count(config);
+    }
+}

package/layerzero/src/message_lib/uln/structs/uln_config_storage_node.cairo

@@ -0,0 +1,91 @@
+// UlnConfigStorageNode - Storage-compatible version of UlnConfig
+//
+// This is a different version of UlnConfig specifically designed for contract storage.
+// While UlnConfig uses Array<ContractAddress> for DVN lists (which are suitable for
+// function parameters and return values), UlnConfigStorageNode uses Vec<ContractAddress>
+// which is the proper storage type in Starknet for dynamic arrays.
+//
+// Key differences:
+// - UlnConfig: Uses Array<ContractAddress> - suitable for function parameters/returns
+// - UlnConfigStorageNode: Uses Vec<ContractAddress> - required for contract storage
+//
+// We need both because:
+// 1. Arrays cannot be directly stored in contract storage in Starknet
+// 2. Vecs are storage-native but cannot be used in function signatures
+// 3. This provides conversion methods between the two representations
+// 4. Allows efficient storage operations while maintaining clean external interfaces
+
+use starknet::ContractAddress;
+use starknet::storage::{
+    Mutable, MutableVecTrait, StoragePath, StoragePointerReadAccess, StoragePointerWriteAccess, Vec,
+    VecTrait,
+};
+use crate::message_lib::uln::structs::uln_config::UlnConfig;
+
+#[starknet::storage_node]
+pub struct UlnConfigStorageNode {
+    pub confirmations: u64,
+    pub has_confirmations: bool,
+    // no duplicates. sorted in ascending order. allowed overlap with optionalDVNs
+    pub required_dvns: Vec<ContractAddress>,
+    pub has_required_dvns: bool,
+    // no duplicates. sorted in ascending order. allowed overlap with requiredDVNs
+    pub optional_dvns: Vec<ContractAddress>,
+    pub optional_dvn_threshold: u8, // (0, optionalDvnCount]
+    pub has_optional_dvns: bool,
+}
+
+#[generate_trait]
+pub impl UlnConfigStorageNodeImpl of UlnConfigStorageNodeTrait {
+    // This function is used to take in a UlnConfig and store in a
+    // contract storage which has a ConfigNode for storing the config.
+    fn set_uln_config(self: StoragePath<Mutable<UlnConfigStorageNode>>, config: UlnConfig) {
+        self.confirmations.write(config.confirmations);
+        self.has_confirmations.write(config.has_confirmations);
+        self.optional_dvn_threshold.write(config.optional_dvn_threshold);
+        self.has_required_dvns.write(config.has_required_dvns);
+        self.has_optional_dvns.write(config.has_optional_dvns);
+
+        // convert from Array to Vec
+        self._clear_dvns();
+        for dvn in config.required_dvns {
+            self.required_dvns.push(dvn);
+        }
+        for dvn in config.optional_dvns {
+            self.optional_dvns.push(dvn);
+        }
+    }
+
+    fn _clear_dvns(self: StoragePath<Mutable<UlnConfigStorageNode>>) {
+        while self.required_dvns.len() != 0 {
+            let _ = self.required_dvns.pop();
+        }
+        while self.optional_dvns.len() != 0 {
+            let _ = self.optional_dvns.pop();
+        }
+    }
+
+    // This function is used to get the UlnConfig from a
+    // contract storage which has a ConfigNode for storing the config.
+    fn get_uln_config(self: StoragePath<UlnConfigStorageNode>) -> UlnConfig {
+        let mut required_dvns_array = array![];
+        let mut optional_dvns_array = array![];
+
+        for i in 0..self.required_dvns.len() {
+            required_dvns_array.append(self.required_dvns.at(i).read());
+        }
+        for i in 0..self.optional_dvns.len() {
+            optional_dvns_array.append(self.optional_dvns.at(i).read());
+        }
+
+        UlnConfig {
+            confirmations: self.confirmations.read(),
+            has_confirmations: self.has_confirmations.read(),
+            required_dvns: required_dvns_array,
+            has_required_dvns: self.has_required_dvns.read(),
+            optional_dvns: optional_dvns_array,
+            optional_dvn_threshold: self.optional_dvn_threshold.read(),
+            has_optional_dvns: self.has_optional_dvns.read(),
+        }
+    }
+}

package/layerzero/src/message_lib/uln/structs/verification.cairo

@@ -0,0 +1,7 @@
+//! ULN verification struct
+
+#[derive(Debug, Drop, Serde, starknet::Store, Default, PartialEq)]
+pub struct Verification {
+    pub submitted: bool,
+    pub confirmations: u64,
+}