@layerzerolabs/protocol-starknet-v2 0.0.34

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

@@ -0,0 +1,32 @@
+//! Executor events
+
+use starknet::ContractAddress;
+use crate::Origin;
+use crate::workers::executor::structs::{NativeDropParams, SetDstConfigParams};
+
+/// Emitted when a destination configuration is set or updated.
+/// @dev Triggered by the `set_dst_config` function.
+#[derive(Drop, starknet::Event)]
+pub struct DstConfigSet {
+    /// The destination configurations that were set.
+    pub dst_config_set: Span<SetDstConfigParams>,
+}
+
+/// Emitted when a native token drop is applied.
+/// @dev Triggered by the `_apply_native_drop` internal function.
+#[derive(Drop, starknet::Event)]
+pub struct NativeDropApplied {
+    /// The origin information of the message.
+    #[key]
+    pub origin: Origin,
+    /// The destination endpoint ID.
+    #[key]
+    pub dst_eid: u32,
+    /// The OApp that received the native drop.
+    #[key]
+    pub oapp: ContractAddress,
+    /// The parameters for the native drop.
+    pub native_drop_params: Array<NativeDropParams>,
+    /// An array indicating the success of each native drop.
+    pub success: Array<bool>,
+}

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

@@ -0,0 +1,392 @@
+//! Executor contract
+
+/// # Executor contract
+///
+/// This contract is responsible for executing LayerZero messages and native token drops.
+/// It also provides a quote function for the worker to use when assigning a job.
+#[starknet::contract]
+pub mod Executor {
+    use core::num::traits::Zero;
+    use openzeppelin::access::accesscontrol::AccessControlComponent;
+    use openzeppelin::access::ownable::OwnableComponent;
+    use openzeppelin::introspection::src5::SRC5Component;
+    use openzeppelin::security::ReentrancyGuardComponent;
+    use openzeppelin::security::pausable::PausableComponent;
+    use openzeppelin::token::erc20::interface::{
+        IERC20Dispatcher, IERC20DispatcherTrait, IERC20SafeDispatcher, IERC20SafeDispatcherTrait,
+    };
+    use openzeppelin::upgrades::upgradeable::UpgradeableComponent;
+    use starknet::storage::{
+        Map, StorageMapReadAccess, StorageMapWriteAccess, StoragePointerReadAccess,
+        StoragePointerWriteAccess,
+    };
+    use starknet::{ClassHash, ContractAddress};
+    use starkware_utils::errors::assert_with_byte_array;
+    use crate::Origin;
+    use crate::common::conversions::FeltArrayIntoByteArrayImpl;
+    use crate::endpoint::interfaces::endpoint::{
+        IEndpointDispatcher, IEndpointDispatcherTrait, IEndpointSafeDispatcher,
+        IEndpointSafeDispatcherTrait,
+    };
+    use crate::endpoint::messaging_composer::interface::{
+        IMessagingComposerSafeDispatcher, IMessagingComposerSafeDispatcherTrait,
+    };
+    use crate::workers::base::base::WorkerBaseComponent;
+    use crate::workers::base::structs::QuoteParams;
+    use crate::workers::executor::errors;
+    use crate::workers::executor::events::{DstConfigSet, NativeDropApplied};
+    use crate::workers::executor::fee_lib::interface::{
+        FeeParams, IExecutorFeeLibDispatcher, IExecutorFeeLibDispatcherTrait,
+    };
+    use crate::workers::executor::interface::IExecutor;
+    use crate::workers::executor::structs::{
+        ComposeParams, DstConfig, ExecuteParams, NativeDropParams, SetDstConfigParams,
+    };
+    use crate::workers::interface::ILayerZeroWorker;
+
+    ////////////////
+    // Components //
+    ////////////////
+
+    // Base worker component
+    component!(path: WorkerBaseComponent, storage: worker_base, event: WorkerBaseEvent);
+
+    // Access control components
+    component!(path: AccessControlComponent, storage: access_control, event: AccessControlEvent);
+    component!(path: SRC5Component, storage: src5, event: SRC5Event);
+
+    // Upgradeable component
+    component!(path: UpgradeableComponent, storage: upgradeable, event: UpgradeableEvent);
+
+    /// Declares the reentrancy guard component which provides:
+    /// - Reentrancy guard to prevent reentrancy attacks during transaction execution,
+    ///   similar to the nonReentrant modifier in EVM implementations
+    component!(
+        path: ReentrancyGuardComponent, storage: reentrancy_guard, event: ReentrancyGuardEvent,
+    );
+
+    // Pausable component
+    component!(path: PausableComponent, storage: pausable, event: PausableEvent);
+
+    // Ownable component
+    component!(path: OwnableComponent, storage: ownable, event: OwnableEvent);
+
+    ////////////////
+    // Embeddings //
+    ////////////////
+
+    #[abi(embed_v0)]
+    impl WorkerBaseImpl = WorkerBaseComponent::WorkerBaseImpl<ContractState>;
+    impl WorkerBaseInternalImpl = WorkerBaseComponent::InternalImpl<ContractState>;
+
+    #[abi(embed_v0)]
+    impl AccessControlImpl = WorkerBaseComponent::AccessControlImpl<ContractState>;
+    impl AccessControlInternalImpl = AccessControlComponent::InternalImpl<ContractState>;
+
+    #[abi(embed_v0)]
+    impl PausableImpl = PausableComponent::PausableImpl<ContractState>;
+
+    /// Upgradeable component internal implementation
+    impl UpgradeableInternalImpl = UpgradeableComponent::InternalImpl<ContractState>;
+
+    /// Implements the reentrancy guard component which provides:
+    /// - Reentrancy guard to prevent reentrancy attacks during transaction execution,
+    ///   similar to the nonReentrant modifier in EVM implementations
+    impl ReentrancyGuardInternalImpl = ReentrancyGuardComponent::InternalImpl<ContractState>;
+
+    #[abi(embed_v0)]
+    impl OwnableImpl = OwnableComponent::OwnableImpl<ContractState>;
+    impl OwnableInternalImpl = OwnableComponent::InternalImpl<ContractState>;
+
+    #[storage]
+    struct Storage {
+        #[substorage(v0)]
+        worker_base: WorkerBaseComponent::Storage,
+        #[substorage(v0)]
+        reentrancy_guard: ReentrancyGuardComponent::Storage,
+        #[substorage(v0)]
+        access_control: AccessControlComponent::Storage,
+        #[substorage(v0)]
+        src5: SRC5Component::Storage,
+        #[substorage(v0)]
+        pausable: PausableComponent::Storage,
+        #[substorage(v0)]
+        upgradeable: UpgradeableComponent::Storage,
+        #[substorage(v0)]
+        ownable: OwnableComponent::Storage,
+        /// A map of destination endpoint IDs to their configurations.
+        dst_configs: Map<u32, DstConfig>,
+        /// The address of the LayerZero Endpoint contract.
+        endpoint: ContractAddress,
+        /// The address of the native token contract.
+        native_token_address: ContractAddress,
+        /// The endpoint ID of the current chain.
+        eid: u32,
+    }
+
+    #[event]
+    #[derive(Drop, starknet::Event)]
+    pub enum Event {
+        #[flat]
+        WorkerBaseEvent: WorkerBaseComponent::Event,
+        #[flat]
+        ReentrancyGuardEvent: ReentrancyGuardComponent::Event,
+        #[flat]
+        AccessControlEvent: AccessControlComponent::Event,
+        #[flat]
+        SRC5Event: SRC5Component::Event,
+        #[flat]
+        UpgradeableEvent: UpgradeableComponent::Event,
+        #[flat]
+        PausableEvent: PausableComponent::Event,
+        #[flat]
+        OwnableEvent: OwnableComponent::Event,
+        /// Executor-specific events
+        DstConfigSet: DstConfigSet,
+        NativeDropApplied: NativeDropApplied,
+    }
+
+    #[constructor]
+    fn constructor(
+        ref self: ContractState,
+        endpoint: ContractAddress,
+        message_libs: Array<ContractAddress>,
+        price_feed: ContractAddress,
+        default_multiplier_bps: u16,
+        role_admin: ContractAddress,
+        admins: Array<ContractAddress>,
+        native_token_address: ContractAddress,
+        owner: ContractAddress,
+    ) {
+        self.eid.write(IEndpointDispatcher { contract_address: endpoint }.get_eid());
+
+        // Initialize access control and ownable components
+        self.ownable.initializer(owner);
+        self.access_control.initializer();
+
+        // Initialize base worker
+        self
+            .worker_base
+            .initializer(message_libs, price_feed, default_multiplier_bps, role_admin, admins);
+
+        // Initialize addresses
+        self.endpoint.write(endpoint);
+        self.native_token_address.write(native_token_address);
+    }
+
+    #[abi(embed_v0)]
+    impl ExecutorImpl of IExecutor<ContractState> {
+        // ================================== Only Owner =====================================
+
+        fn upgrade(ref self: ContractState, new_class_hash: ClassHash) {
+            self.ownable.assert_only_owner();
+            self.upgradeable.upgrade(new_class_hash);
+        }
+
+        fn upgrade_and_call(
+            ref self: ContractState,
+            new_class_hash: ClassHash,
+            selector: felt252,
+            calldata: Span<felt252>,
+        ) -> Span<felt252> {
+            self.ownable.assert_only_owner();
+            self.upgradeable.upgrade_and_call(new_class_hash, selector, calldata)
+        }
+
+        // ================================== Only Admin =====================================
+
+        fn set_dst_config(ref self: ContractState, params: Array<SetDstConfigParams>) {
+            self.worker_base._assert_only_admin();
+
+            let dst_config_set = params.span();
+            for param in params.into_iter() {
+                self.dst_configs.write(param.dst_eid, param.config);
+            }
+
+            self.emit(DstConfigSet { dst_config_set });
+        }
+
+        fn execute(ref self: ContractState, params: ExecuteParams) {
+            self.worker_base._assert_only_admin();
+            self.reentrancy_guard.start();
+            self._execute(params);
+            self.reentrancy_guard.end();
+        }
+
+        fn compose(ref self: ContractState, params: ComposeParams) {
+            self.worker_base._assert_only_admin();
+            self.reentrancy_guard.start();
+            self._compose(params);
+            self.reentrancy_guard.end();
+        }
+
+        fn native_drop(
+            ref self: ContractState,
+            origin: Origin,
+            oapp: ContractAddress,
+            native_drop_params: Array<NativeDropParams>,
+        ) {
+            self.worker_base._assert_only_admin();
+            self._native_drop(origin, oapp, native_drop_params);
+        }
+
+        fn native_drop_and_execute(
+            ref self: ContractState,
+            native_drop_params: Array<NativeDropParams>,
+            execute_params: ExecuteParams,
+        ) {
+            self.worker_base._assert_only_admin();
+            self.reentrancy_guard.start();
+            self
+                ._native_drop(
+                    execute_params.origin.clone(), execute_params.receiver, native_drop_params,
+                );
+            self._execute(execute_params);
+            self.reentrancy_guard.end();
+        }
+
+        // ================================== View ==========================================
+
+        fn get_dst_config(self: @ContractState, dst_eid: u32) -> DstConfig {
+            self.dst_configs.read(dst_eid)
+        }
+    }
+
+    #[abi(embed_v0)]
+    impl LayerZeroWorkerImpl of ILayerZeroWorker<ContractState> {
+        // ================================== Only Message Lib =====================================
+
+        /// This executor implementation does not require any additional steps beyond providing
+        /// the quote when assigning a job
+        fn assign_job(ref self: ContractState, params: QuoteParams) -> u256 {
+            self.worker_base._assert_not_paused();
+            self.worker_base._assert_only_message_lib();
+            self.quote(params)
+        }
+
+        // ================================== View =====================================
+
+        fn quote(self: @ContractState, params: QuoteParams) -> u256 {
+            self.worker_base._assert_not_paused();
+
+            let QuoteParams { dst_eid, sender, calldata_size, options, .. } = params;
+
+            // Assert price feed is set
+            let price_feed = self.worker_base.get_price_feed();
+            assert_with_byte_array(price_feed.is_non_zero(), errors::err_price_feed_not_set());
+
+            // Assert worker fee lib is set
+            let worker_fee_lib_addr = self.worker_base.get_worker_fee_lib();
+            assert_with_byte_array(
+                worker_fee_lib_addr.is_non_zero(), errors::err_worker_fee_lib_not_set(),
+            );
+
+            let fee_params = FeeParams {
+                price_feed,
+                dst_eid,
+                sender,
+                calldata_size,
+                default_multiplier_bps: self.worker_base.get_default_multiplier_bps(),
+            };
+
+            // Call fee lib to get the quote
+            let fee_lib = IExecutorFeeLibDispatcher { contract_address: worker_fee_lib_addr };
+            fee_lib.get_fee(fee_params, self.dst_configs.read(dst_eid), options)
+        }
+    }
+
+    #[generate_trait]
+    impl InternalImpl of InternalTrait {
+        #[feature("safe_dispatcher")]
+        fn _execute(ref self: ContractState, params: ExecuteParams) {
+            let ExecuteParams {
+                origin, receiver, guid, message, value, extra_data, gas_limit, ..,
+            } = params;
+
+            let endpoint_address = self.endpoint.read();
+
+            // Sender gives approval to the endpoint for the specified amount
+            if value > 0 {
+                let token = IERC20Dispatcher { contract_address: self.native_token_address.read() };
+                token.approve(endpoint_address, value);
+            }
+
+            let endpoint = IEndpointSafeDispatcher { contract_address: endpoint_address };
+            if let Err(reason) = endpoint
+                .lz_receive(
+                    origin.clone(), receiver, guid, message.clone(), value, extra_data.clone(),
+                ) {
+                endpoint
+                    .lz_receive_alert(
+                        origin, receiver, guid, gas_limit, value, message, extra_data, reason,
+                    )
+                    .expect('Alert event emitted');
+            }
+        }
+
+        #[feature("safe_dispatcher")]
+        fn _native_drop(
+            ref self: ContractState,
+            origin: Origin,
+            oapp: ContractAddress,
+            native_drop_params: Array<NativeDropParams>,
+        ) {
+            let mut success = array![];
+
+            for params in @native_drop_params {
+                // Because the OpenZeppelin implementation of ERC-20 reverts with an error or
+                // returns `true` always on the `transfer` function call, we need to use the safe
+                // dispatcher and check the `Result` values.
+                // https://docs.openzeppelin.com/contracts-cairo/1.0.0/erc20#erc20_compatibility
+                let result = IERC20SafeDispatcher {
+                    contract_address: self.native_token_address.read(),
+                }
+                    .transfer(*params.receiver, *params.amount);
+
+                success.append(result.is_ok());
+            }
+
+            self
+                .emit(
+                    NativeDropApplied {
+                        origin, dst_eid: self.eid.read(), oapp, native_drop_params, success,
+                    },
+                );
+        }
+
+        #[feature("safe_dispatcher")]
+        fn _compose(ref self: ContractState, params: ComposeParams) {
+            let ComposeParams {
+                sender, receiver, guid, index, message, gas_limit, extra_data, value,
+            } = params;
+
+            let endpoint_address = self.endpoint.read();
+
+            // Sender gives approval to the endpoint for the specified amount
+            if value > 0 {
+                let token = IERC20Dispatcher { contract_address: self.native_token_address.read() };
+                token.approve(endpoint_address, value);
+            }
+
+            let composer = IMessagingComposerSafeDispatcher { contract_address: endpoint_address };
+            if let Err(reason) = composer
+                .lz_compose(
+                    sender, receiver, guid, index, message.clone(), extra_data.clone(), value,
+                ) {
+                composer
+                    .lz_compose_alert(
+                        sender,
+                        receiver,
+                        guid,
+                        index,
+                        gas_limit,
+                        value,
+                        message,
+                        extra_data,
+                        reason,
+                    )
+                    .expect('Alert event emitted');
+            }
+        }
+    }
+}

package/layerzero/src/workers/executor/fee_lib/executor_fee_lib.cairo

@@ -0,0 +1,160 @@
+//! Executor Fee Library contract implementation
+
+/// # Executor Fee Library contract
+///
+/// This contract handles fee calculations for executor operations, separated from the main executor
+/// logic to provide modularity and easier maintenance of fee-related functionality.
+#[starknet::contract]
+pub mod ExecutorFeeLib {
+    use openzeppelin::access::ownable::OwnableComponent;
+    use openzeppelin::token::erc20::interface::{IERC20Dispatcher, IERC20DispatcherTrait};
+    use starknet::ContractAddress;
+    use starknet::storage::StoragePointerWriteAccess;
+    use starkware_utils::errors::assert_with_byte_array;
+    use crate::common::constants::MAX_V1_EID;
+    use crate::workers::common::{
+        apply_premium_and_floor_margin, convert_and_apply_premium_to_value,
+    };
+    use crate::workers::executor::errors;
+    use crate::workers::executor::fee_lib::interface::{FeeParams, IExecutorFeeLib};
+    use crate::workers::executor::options::_decode_executor_options;
+    use crate::workers::executor::structs::DstConfig;
+    use crate::workers::price_feed::interface::{
+        ILayerZeroPriceFeedDispatcher, ILayerZeroPriceFeedDispatcherTrait,
+    };
+
+    ////////////////
+    // Components //
+    ////////////////
+
+    component!(path: OwnableComponent, storage: ownable, event: OwnableEvent);
+
+    ////////////////
+    // Embeddings //
+    ////////////////
+
+    #[abi(embed_v0)]
+    impl OwnableImpl = OwnableComponent::OwnableImpl<ContractState>;
+    impl OwnableInternalImpl = OwnableComponent::InternalImpl<ContractState>;
+
+    #[storage]
+    struct Storage {
+        #[substorage(v0)]
+        ownable: OwnableComponent::Storage,
+        /// Local endpoint ID v2
+        local_eid_v2: u32,
+    }
+
+    #[event]
+    #[derive(Drop, starknet::Event)]
+    pub enum Event {
+        #[flat]
+        OwnableEvent: OwnableComponent::Event,
+    }
+
+    #[constructor]
+    fn constructor(ref self: ContractState, local_eid_v2: u32, owner: ContractAddress) {
+        // Initialize ownable component
+        self.ownable.initializer(owner);
+
+        // Set immutable values
+        self.local_eid_v2.write(local_eid_v2);
+    }
+
+    #[abi(embed_v0)]
+    impl ExecutorFeeLibImpl of IExecutorFeeLib<ContractState> {
+        // ================================== Only Owner =====================================
+
+        fn withdraw_token(
+            ref self: ContractState,
+            token_address: ContractAddress,
+            to: ContractAddress,
+            amount: u256,
+        ) {
+            self.ownable.assert_only_owner();
+            let token_dispatcher = IERC20Dispatcher { contract_address: token_address };
+
+            // NOTE: (from https://docs.openzeppelin.com/contracts-cairo/1.0.0/erc20)
+            // transfer, transfer_from and approve will never return anything different from true
+            // because they will revert on any error.
+            token_dispatcher.transfer(to, amount);
+        }
+
+        // ================================== External =====================================
+
+        fn get_fee_on_send(
+            ref self: ContractState, params: FeeParams, dst_config: DstConfig, options: ByteArray,
+        ) -> u256 {
+            self.get_fee(params, dst_config, options)
+        }
+
+        // ================================== View =====================================
+
+        fn get_fee(
+            self: @ContractState, params: FeeParams, dst_config: DstConfig, options: ByteArray,
+        ) -> u256 {
+            // Check if destination is supported
+            assert_with_byte_array(
+                dst_config.lz_receive_base_gas != 0, errors::err_eid_not_supported(),
+            );
+
+            // Decode executor options
+            let price_feed_params = _decode_executor_options(
+                false,
+                self._is_v1_eid(params.dst_eid),
+                dst_config.lz_receive_base_gas.into(),
+                dst_config.lz_compose_base_gas.into(),
+                dst_config.native_cap,
+                @options,
+            );
+
+            // Get price feed estimate
+            let price_feed = ILayerZeroPriceFeedDispatcher { contract_address: params.price_feed };
+            let estimated_fee = price_feed
+                .estimate_fee_on_send(
+                    params.dst_eid, params.calldata_size, price_feed_params.total_gas,
+                );
+
+            // Apply premium to gas fee
+            let mut fee = apply_premium_and_floor_margin(
+                estimated_fee.gas_fee,
+                dst_config.multiplier_bps,
+                params.default_multiplier_bps,
+                dst_config.floor_margin_usd,
+                estimated_fee.native_price_usd,
+            );
+
+            // Apply premium to value
+            fee +=
+                convert_and_apply_premium_to_value(
+                    price_feed_params.total_value,
+                    estimated_fee.price_ratio,
+                    estimated_fee.price_ratio_denominator,
+                    dst_config.multiplier_bps,
+                    params.default_multiplier_bps,
+                );
+
+            fee
+        }
+
+        fn version(self: @ContractState) -> (u64, u8) {
+            (1, 1)
+        }
+    }
+
+    #[generate_trait]
+    impl InternalImpl of InternalTrait {
+        /// Check if EID is v1 (endpoint v1)
+        ///
+        /// # Arguments
+        ///
+        /// * `eid` - The endpoint ID to check
+        ///
+        /// # Returns
+        ///
+        /// * `bool` - True if the EID is of an endpoint v1, false otherwise
+        fn _is_v1_eid(self: @ContractState, eid: u32) -> bool {
+            eid < MAX_V1_EID
+        }
+    }
+}

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

@@ -0,0 +1,87 @@
+//! Executor Fee Lib interface
+
+use starknet::ContractAddress;
+use crate::workers::executor::structs::DstConfig;
+
+/// Fee parameters for executor fee calculation
+#[derive(Drop, Clone, Serde)]
+pub struct FeeParams {
+    /// The address of the price feed contract
+    pub price_feed: ContractAddress,
+    /// The destination endpoint ID
+    pub dst_eid: u32,
+    /// The address of the sender
+    pub sender: ContractAddress,
+    /// The size of the calldata
+    pub calldata_size: u32,
+    /// The default multiplier basis points
+    pub default_multiplier_bps: u16,
+}
+
+/// # Executor Fee Library Interface
+///
+/// This interface defines the standard functions for a LayerZero Executor Fee Library.
+///
+/// ## Key Responsibilities
+/// 1.  **Fee Calculation:** Calculating the cost of message execution on a destination chain.
+///     The fee is determined by factors such as the destination endpoint ID (EID), the size of the
+///     message payload, and the gas price on the destination chain, which is obtained from a price
+///     feed.
+/// 2.  **Versioning:** Exposing its version number to allow for upgrades and compatibility checks.
+///
+/// The fee calculation can be performed in two ways:
+/// - `get_fee`: A view function that returns the fee without any state changes. This is useful for
+/// quoting.
+/// - `get_fee_on_send`: An external function that calculates the fee and may perform state changes,
+///   for example, to record fee-related data.
+#[starknet::interface]
+pub trait IExecutorFeeLib<TContractState> {
+    // ================================== Only Owner =====================================
+
+    /// Withdraws tokens from the fee library.
+    /// Enables recovery of funds accidentally sent
+    ///
+    /// # Arguments
+    /// * `token_address` - The address of the token to withdraw
+    /// * `to` - The address to send the withdrawn tokens to
+    /// * `amount` - The amount of tokens to withdraw
+    fn withdraw_token(
+        ref self: TContractState, token_address: ContractAddress, to: ContractAddress, amount: u256,
+    );
+
+    // ================================== External =====================================
+
+    /// Gets the fee for sending a message, potentially changing state.
+    ///
+    /// # Arguments
+    /// * `params` - The fee parameters
+    /// * `dst_config` - The destination configuration
+    /// * `options` - The message options
+    ///
+    /// # Returns
+    /// * `u256` - The calculated fee
+    fn get_fee_on_send(
+        ref self: TContractState, params: FeeParams, dst_config: DstConfig, options: ByteArray,
+    ) -> u256;
+
+    // ================================== View =====================================
+
+    /// Gets the fee for a message without changing state.
+    ///
+    /// # Arguments
+    /// * `params` - The fee parameters
+    /// * `dst_config` - The destination configuration
+    /// * `options` - The message options
+    ///
+    /// # Returns
+    /// * `u256` - The calculated fee
+    fn get_fee(
+        self: @TContractState, params: FeeParams, dst_config: DstConfig, options: ByteArray,
+    ) -> u256;
+
+    /// Gets the version of the fee library.
+    ///
+    /// # Returns
+    /// * `(u64, u8)` - The major and minor version numbers
+    fn version(self: @TContractState) -> (u64, u8);
+}