@layerzerolabs/protocol-starknet-v2 0.0.34

package/layerzero/src/workers/executor/interface.cairo

@@ -0,0 +1,131 @@
+//! Executor interface
+
+use starknet::{ClassHash, ContractAddress};
+use crate::Origin;
+use crate::workers::executor::structs::{
+    ComposeParams, DstConfig, ExecuteParams, NativeDropParams, SetDstConfigParams,
+};
+
+/// Interface for the executor contract
+#[starknet::interface]
+pub trait IExecutor<TContractState> {
+    // ================================== Only Owner =====================================
+
+    /// Upgrades the contract
+    ///
+    /// # Arguments
+    /// * `new_class_hash` - The new class hash to upgrade to
+    ///
+    /// # Events
+    /// * `Upgraded` - Emitted when the contract is upgraded (from OpenZeppelin's
+    /// [`UpgradeableComponent`])
+    ///
+    /// @dev This function is only callable by the owner.
+    fn upgrade(ref self: TContractState, new_class_hash: ClassHash);
+
+    /// Upgrades the contract and calls a function
+    ///
+    /// # Arguments
+    /// * `new_class_hash` - The new class hash to upgrade to
+    /// * `selector` - The selector to call
+    /// * `data` - The data to pass to the function
+    ///
+    /// # Returns
+    /// * `Span<felt252>` - The response data from the function call
+    ///
+    /// # Events
+    /// * `Upgraded` - Emitted when the contract is upgraded (from OpenZeppelin's
+    /// [`UpgradeableComponent`])
+    ///
+    /// @dev This function is only callable by the owner.
+    fn upgrade_and_call(
+        ref self: TContractState,
+        new_class_hash: ClassHash,
+        selector: felt252,
+        calldata: Span<felt252>,
+    ) -> Span<felt252>;
+
+    // ================================== Only Admin =====================================
+
+    /// Sets the destination configurations for one or more endpoint IDs.
+    ///
+    /// # Arguments
+    /// * `params` - An array of `SetDstConfigParams` structs, each specifying a destination EID and
+    /// its configuration.
+    ///
+    /// # Events
+    /// * `DstConfigSet` - Emitted when the destination configurations are set.
+    ///
+    /// @dev This function is only callable by the admin.
+    fn set_dst_config(ref self: TContractState, params: Array<SetDstConfigParams>);
+
+    /// Execute a job
+    ///
+    /// # Arguments
+    /// * `params` - The execution parameters
+    ///
+    /// # Events
+    /// * `ExecuteFailed` - Emitted when the job execution fails
+    ///
+    /// @dev This function is only callable by the admin.
+    fn execute(ref self: TContractState, params: ExecuteParams);
+
+    /// Compose a message
+    ///
+    /// # Arguments
+    /// * `params` - The composition parameters
+    ///
+    /// # Events
+    /// * `ComposeFailed` - Emitted when the message composition fails
+    ///
+    /// @dev This function is only callable by the admin.
+    fn compose(ref self: TContractState, params: ComposeParams);
+
+    /// Drop native tokens to receivers.
+    ///
+    /// # Arguments
+    /// * `origin` - The message origin
+    /// * `oapp` - The OApp address
+    /// * `native_drop_params` - The native drop parameters.
+    ///
+    /// # Events
+    /// * `NativeDropFailed` - Emitted when the native drop fails
+    ///
+    /// @dev This function is only callable by the admin.
+    fn native_drop(
+        ref self: TContractState,
+        origin: Origin,
+        oapp: ContractAddress,
+        native_drop_params: Array<NativeDropParams>,
+    );
+
+    /// Drop native tokens to receivers and execute a message.
+    ///
+    /// # Arguments
+    /// * `native_drop_params` - The native drop parameters.
+    /// * `execute_params` - The execution parameters.
+    ///
+    /// # Events
+    /// * `NativeDropFailed` - Emitted when the native drop fails
+    /// * `ExecuteFailed` - Emitted when the job execution fails
+    ///
+    /// @dev This function is only callable by the admin.
+    fn native_drop_and_execute(
+        ref self: TContractState,
+        native_drop_params: Array<NativeDropParams>,
+        execute_params: ExecuteParams,
+    );
+
+    // ================================== View ==========================================
+
+    /// Get the destination configuration
+    ///
+    /// # Arguments
+    /// * `dst_eid` - The destination endpoint ID
+    ///
+    /// # Returns
+    /// * `DstConfig` - The destination configuration
+    ///
+    /// @dev This function is only callable by anyone.
+    fn get_dst_config(self: @TContractState, dst_eid: u32) -> DstConfig;
+}

package/layerzero/src/workers/executor/options.cairo

@@ -0,0 +1,244 @@
+//! Executor options
+
+use alexandria_bytes::byte_array_ext::ByteArrayTraitExt;
+use core::byte_array::{ByteArray, ByteArrayTrait};
+use starkware_utils::errors::assert_with_byte_array;
+use crate::workers::executor::errors;
+use crate::workers::executor::structs::{
+    ExecutorOption, LzComposeOption, LzReadOption, LzReceiveOption, NativeDropOption,
+};
+
+// Constants
+pub const OPTION_TYPE_LZRECEIVE: u8 = 1;
+pub const OPTION_TYPE_NATIVE_DROP: u8 = 2;
+pub const OPTION_TYPE_LZCOMPOSE: u8 = 3;
+pub const OPTION_TYPE_ORDERED_EXECUTION: u8 = 4;
+pub const OPTION_TYPE_LZREAD: u8 = 5;
+
+pub const EXECUTOR_WORKER_ID: u8 = 1;
+
+// This struct holds the aggregated values from parsing the executor options.
+#[derive(Default, Drop, Serde, Debug)]
+pub struct ExecutorOptionsAggregated {
+    // The total native value to be sent with the message.
+    pub total_value: u128,
+    // The total gas limit for the message execution.
+    pub total_gas: u128,
+    // A flag indicating if ordered execution is requested.
+    pub ordered: bool,
+    // The number of `lz_compose` options.
+    pub num_lz_compose: u32,
+    // The size of the calldata.
+    pub calldata_size: u32,
+    // The gas for `lzReceive`.
+    pub lz_receive_gas: u128,
+}
+
+// This struct holds the decoded/calculated values needed for quoting.
+#[derive(Copy, Drop, Serde, Debug, PartialEq)]
+pub struct PriceFeedParams {
+    // The total native value to be sent with the message.
+    pub total_value: u256,
+    // The total gas limit for the message execution.
+    pub total_gas: u256,
+    // The size of the calldata.
+    pub calldata_size: u32,
+}
+
+pub fn _decode_executor_options(
+    is_read: bool,
+    is_v1_eid: bool,
+    lz_receive_base_gas: u256,
+    lz_compose_base_gas: u256,
+    native_cap: u128,
+    options: @ByteArray,
+) -> PriceFeedParams {
+    let parsed_options = _parse_options_to_array(options);
+    let agg_options = _aggregate_options(parsed_options.span(), is_read, is_v1_eid, native_cap);
+
+    // lz receive only called once
+    // lz compose can be called multiple times, based on unique index
+    // to simplify the quoting, we add lzComposeBaseGas for each lzComposeOption received
+    // if the same index has multiple compose options, the gas will be added multiple times
+    let mut total_gas: u256 = lz_receive_base_gas
+        + agg_options.total_gas.into()
+        + lz_compose_base_gas * agg_options.num_lz_compose.into();
+    if agg_options.ordered {
+        total_gas = (total_gas * 102) / 100;
+    }
+
+    PriceFeedParams {
+        total_value: agg_options.total_value.into(),
+        total_gas: total_gas,
+        calldata_size: agg_options.calldata_size,
+    }
+}
+
+
+pub fn _parse_options_to_array(options_bytes: @ByteArray) -> Array<ExecutorOption> {
+    assert_with_byte_array(options_bytes.len() > 0, errors::err_no_options());
+
+    let mut options_arr = array![];
+    let mut cursor: usize = 0;
+    let total_len = options_bytes.len();
+
+    while cursor != total_len {
+        assert_with_byte_array(cursor < total_len, errors::err_malformed_options());
+        // skip worker id
+        cursor += 1;
+
+        let (cursor_after_len, option_len_total_u16) = options_bytes.read_u16(cursor);
+        let option_len_total: usize = option_len_total_u16.into();
+        cursor = cursor_after_len;
+
+        // ensure we have at least one byte for the option type
+        assert_with_byte_array(cursor < total_len, errors::err_malformed_options());
+        let (cursor_after_type, option_type) = options_bytes.read_u8(cursor);
+        cursor = cursor_after_type;
+
+        // option_len_total includes the type byte; payload length excludes it
+        assert_with_byte_array(option_len_total > 0, errors::err_malformed_options());
+        let option_len: usize = option_len_total - 1;
+
+        let option_data_start_offset = cursor;
+        // ensure payload fits within the total buffer
+        assert_with_byte_array(
+            option_data_start_offset + option_len <= total_len, errors::err_malformed_options(),
+        );
+
+        if option_type == OPTION_TYPE_LZRECEIVE {
+            let lz_receive_option = _read_lz_receive_option(
+                options_bytes, option_data_start_offset, option_len,
+            );
+            options_arr.append(ExecutorOption::LzReceive(lz_receive_option));
+        } else if option_type == OPTION_TYPE_NATIVE_DROP {
+            let native_drop_option = _read_native_drop_option(
+                options_bytes, option_data_start_offset, option_len,
+            );
+            options_arr.append(ExecutorOption::NativeDrop(native_drop_option));
+        } else if option_type == OPTION_TYPE_LZCOMPOSE {
+            let lz_compose_option = _read_lz_compose_option(
+                options_bytes, option_data_start_offset, option_len,
+            );
+            options_arr.append(ExecutorOption::LzCompose(lz_compose_option));
+        } else if option_type == OPTION_TYPE_ORDERED_EXECUTION {
+            options_arr.append(ExecutorOption::OrderedExecution);
+        } else {
+            assert_with_byte_array(
+                option_type == OPTION_TYPE_LZREAD, errors::err_unsupported_option_type(),
+            );
+            let lz_read_option = _read_lz_read_option(
+                options_bytes, option_data_start_offset, option_len,
+            );
+            options_arr.append(ExecutorOption::LzRead(lz_read_option));
+        }
+        cursor = option_data_start_offset + option_len;
+    }
+
+    options_arr
+}
+
+// equivalent to _parseExecutorOptions in ExecutorFeeLib.sol
+pub fn _aggregate_options(
+    options_span: Span<ExecutorOption>, is_read: bool, is_v1_eid: bool, native_cap: u128,
+) -> ExecutorOptionsAggregated {
+    let mut options = ExecutorOptionsAggregated {
+        total_value: 0,
+        total_gas: 0,
+        ordered: false,
+        num_lz_compose: 0,
+        calldata_size: 0,
+        lz_receive_gas: 0,
+    };
+
+    let mut temp_options = options_span;
+    while let Option::Some(option) = temp_options.pop_front() {
+        match option {
+            ExecutorOption::LzReceive(lz_receive_option) => {
+                assert_with_byte_array(!is_read, errors::err_unsupported_option_lz_receive());
+                assert_with_byte_array(
+                    !is_v1_eid || *lz_receive_option.value == 0,
+                    errors::err_unsupported_receive_with_value(),
+                );
+                options.total_value += *lz_receive_option.value;
+                options.lz_receive_gas += *lz_receive_option.gas;
+            },
+            ExecutorOption::NativeDrop(native_drop_option) => {
+                assert_with_byte_array(!is_read, errors::err_unsupported_option_native_drop());
+                options.total_value += *native_drop_option.amount;
+            },
+            ExecutorOption::LzCompose(lz_compose_option) => {
+                assert_with_byte_array(!is_v1_eid, errors::err_unsupported_option_lz_compose());
+                assert_with_byte_array(
+                    *lz_compose_option.gas > 0, errors::err_zero_lz_compose_gas(),
+                );
+                options.total_value += *lz_compose_option.value;
+                options.total_gas += *lz_compose_option.gas;
+                options.num_lz_compose += 1;
+            },
+            ExecutorOption::OrderedExecution => { options.ordered = true; },
+            ExecutorOption::LzRead(lz_read_option) => {
+                assert_with_byte_array(is_read, errors::err_unsupported_option_lz_read());
+                options.total_value += *lz_read_option.value;
+                options.lz_receive_gas += *lz_read_option.gas;
+                options.calldata_size += *lz_read_option.size;
+            },
+        }
+    }
+
+    assert_with_byte_array(
+        options.total_value <= native_cap, errors::err_native_amount_exceeds_cap(),
+    );
+    assert_with_byte_array(options.lz_receive_gas > 0, errors::err_zero_lz_receive_gas());
+    if is_read {
+        assert_with_byte_array(options.calldata_size > 0, errors::err_zero_calldata_size());
+    }
+    options.total_gas += options.lz_receive_gas;
+    options
+}
+
+// Decoding helper functions
+pub fn _read_lz_receive_option(b: @ByteArray, offset: usize, len: usize) -> LzReceiveOption {
+    assert_with_byte_array(len == 16 || len == 32, errors::err_invalid_lz_receive_option());
+    let (offset, gas) = b.read_u128(offset);
+    let value = if len == 32 {
+        let (_, value) = b.read_u128(offset);
+        value
+    } else {
+        0
+    };
+    LzReceiveOption { gas, value }
+}
+
+pub fn _read_native_drop_option(b: @ByteArray, offset: usize, len: usize) -> NativeDropOption {
+    assert_with_byte_array(len == 48, errors::err_invalid_native_drop_option());
+    let (offset, amount) = b.read_u128(offset);
+    let (_, receiver) = b.read_u256(offset);
+    NativeDropOption { amount, receiver: receiver.into() }
+}
+
+pub fn _read_lz_compose_option(b: @ByteArray, offset: usize, len: usize) -> LzComposeOption {
+    assert_with_byte_array(len == 18 || len == 34, errors::err_invalid_lz_compose_option());
+    let (offset, index) = b.read_u16(offset);
+    let (offset, gas) = b.read_u128(offset);
+    let value = if len == 34 {
+        let (_, value) = b.read_u128(offset);
+        value
+    } else {
+        0
+    };
+    LzComposeOption { index, gas, value }
+}
+
+pub fn _read_lz_read_option(b: @ByteArray, offset: usize, len: usize) -> LzReadOption {
+    assert_with_byte_array(len == 20 || len == 36, errors::err_invalid_lz_read_option());
+    let (offset, gas) = b.read_u128(offset);
+    let (offset, size) = b.read_u32(offset);
+    let value = if len == 36 {
+        let (_, value) = b.read_u128(offset);
+        value
+    } else {
+        0
+    };
+    LzReadOption { gas, size, value }
+}

package/layerzero/src/workers/executor/structs.cairo

@@ -0,0 +1,119 @@
+//! Executor structs
+
+use lz_utils::bytes::Bytes32;
+use starknet::ContractAddress;
+use crate::Origin;
+
+#[derive(Copy, Drop, Serde, starknet::Store, PartialEq, Default, Debug)]
+pub struct DstConfig {
+    /// The base gas for `lz_receive`
+    pub lz_receive_base_gas: u64,
+    /// The gas multiplier in basis points
+    pub multiplier_bps: u16,
+    /// The floor margin in USD (uses priceFeed PRICE_RATIO_DENOMINATOR)
+    pub floor_margin_usd: u128,
+    /// The native token cap
+    pub native_cap: u128,
+    /// The base gas for `lz_compose`
+    pub lz_compose_base_gas: u64,
+}
+
+#[derive(Copy, Drop, Serde, PartialEq)]
+pub struct SetDstConfigParams {
+    /// The destination endpoint ID
+    pub dst_eid: u32,
+    /// The destination configuration
+    pub config: DstConfig,
+}
+
+#[derive(Drop, Serde, Clone)]
+pub struct ExecuteParams {
+    /// The address of the receiver contract
+    pub receiver: ContractAddress,
+    /// The origin information of the message
+    pub origin: Origin,
+    /// The globally unique identifier for the message
+    pub guid: Bytes32,
+    /// The amount of native tokens to be sent with the message
+    pub value: u256,
+    /// The message payload
+    pub message: ByteArray,
+    /// The gas limit for the execution
+    pub gas_limit: u256,
+    /// Extra data for the execution
+    pub extra_data: ByteArray,
+}
+
+#[derive(Drop, Serde, Clone)]
+pub struct ComposeParams {
+    /// The address of the receiver contract
+    pub receiver: ContractAddress,
+    /// The address of the sender contract
+    pub sender: ContractAddress,
+    /// The globally unique identifier for the message
+    pub guid: Bytes32,
+    /// The index for composing messages
+    pub index: u16,
+    /// The amount of native tokens to be sent with the message
+    pub value: u256,
+    /// The message payload
+    pub message: ByteArray,
+    /// Extra data for composing the message
+    pub extra_data: ByteArray,
+    /// The gas limit for the composition
+    pub gas_limit: u256,
+}
+
+#[derive(Drop, Serde)]
+pub enum ExecutorOption {
+    LzReceive: LzReceiveOption,
+    NativeDrop: NativeDropOption,
+    LzCompose: LzComposeOption,
+    OrderedExecution,
+    LzRead: LzReadOption,
+}
+
+#[derive(Debug, Drop, Serde, Clone)]
+pub struct LzReceiveOption {
+    /// The gas limit for `lz_receive`
+    pub gas: u128,
+    /// The native token value to be sent with `lz_receive`
+    pub value: u128,
+}
+
+#[derive(Drop, Serde, Clone)]
+pub struct NativeDropOption {
+    /// The amount of native tokens to drop
+    pub amount: u128,
+    /// The recipient address for the native drop
+    pub receiver: Bytes32,
+}
+
+/// Native drop parameters.
+#[derive(Drop, Serde, Clone)]
+pub struct NativeDropParams {
+    /// Amount of the native tokens
+    pub amount: u256,
+    /// Receiver of the native tokens
+    pub receiver: ContractAddress,
+}
+
+#[derive(Debug, Drop, Serde, Clone)]
+pub struct LzComposeOption {
+    /// The index for composing messages
+    pub index: u16,
+    /// The gas limit for `lz_compose`
+    pub gas: u128,
+    /// The native token value to be sent with `lz_compose`
+    pub value: u128,
+}
+
+#[derive(Drop, Serde, Clone)]
+pub struct LzReadOption {
+    /// The gas limit for the read operation
+    pub gas: u128,
+    /// The size of the data to be read
+    pub size: u32,
+    /// The native token value to be sent with the read operation
+    pub value: u128,
+}

package/layerzero/src/workers/interface.cairo

@@ -0,0 +1,32 @@
+//! ILayerZeroWorker interface used by the DVN and Executor workers
+
+use crate::workers::base::structs::QuoteParams;
+
+#[starknet::interface]
+pub trait ILayerZeroWorker<TContractState> {
+    // ================================== Only Message Lib =====================================
+
+    /// Assign a job
+    ///
+    /// # Arguments
+    /// * `params` - Parameters for assigning a job
+    ///
+    /// # Returns
+    /// * `u256` - The fee for the job
+    ///
+    /// @dev This function is only callable by message libs.
+    fn assign_job(ref self: TContractState, params: QuoteParams) -> u256;
+
+    // ================================== View =====================================
+
+    /// Quote the fee for a job
+    ///
+    /// # Arguments
+    /// * `params` - Parameters for quoting the fee
+    ///
+    /// # Returns
+    /// * `u256` - The fee for the job
+    ///
+    /// @dev This function is callable by anyone.
+    fn quote(self: @TContractState, params: QuoteParams) -> u256;
+}

package/layerzero/src/workers/price_feed/constants.cairo

@@ -0,0 +1,7 @@
+//! Price feed constants
+
+/// Price ratio denominator (10^20)
+pub const PRICE_RATIO_DENOMINATOR: u128 = 100_000_000_000_000_000_000_u128;
+
+/// Arbitrum compression percent
+pub const ARBITRUM_COMPRESSION_PERCENT: u32 = 47;

package/layerzero/src/workers/price_feed/errors.cairo

@@ -0,0 +1,28 @@
+use lz_utils::error::{Error, format_error};
+
+#[derive(Drop)]
+pub enum PriceFeedError {
+    OnlyPriceUpdater,
+    NotAnOpStack,
+}
+
+impl ErrorNameImpl of Error<PriceFeedError> {
+    fn prefix() -> ByteArray {
+        "LZ_PRICE_FEED"
+    }
+
+    fn name(self: PriceFeedError) -> ByteArray {
+        match self {
+            PriceFeedError::OnlyPriceUpdater => "ONLY_PRICE_UPDATER",
+            PriceFeedError::NotAnOpStack => "NOT_AN_OP_STACK",
+        }
+    }
+}
+
+pub fn err_lz_price_feed_only_price_updater() -> ByteArray {
+    format_error(PriceFeedError::OnlyPriceUpdater, "")
+}
+
+pub fn err_lz_pricefeed_not_an_op_stack() -> ByteArray {
+    format_error(PriceFeedError::NotAnOpStack, "")
+}

package/layerzero/src/workers/price_feed/events.cairo

@@ -0,0 +1,13 @@
+//! Price feed events
+
+use starknet::ContractAddress;
+
+/// Event emitted when fees are withdrawn
+#[derive(Drop, starknet::Event)]
+pub struct FeeWithdrawn {
+    #[key]
+    pub token_address: ContractAddress,
+    #[key]
+    pub to: ContractAddress,
+    pub amount: u256,
+}