@layerzerolabs/protocol-starknet-v2 0.0.34

package/layerzero/src/endpoint/messaging_composer/interface.cairo

@@ -0,0 +1,132 @@
+//! Messaging composer interface
+
+use lz_utils::bytes::Bytes32;
+use starknet::ContractAddress;
+
+/// # `IMessagingComposer` Interface
+///
+/// The `IMessagingComposer` manages compose payloads that are sent after a LayerZero message has
+/// been delivered.
+///
+/// ## Key features
+/// - Queueing of compose payloads by the originating OApp
+/// - Verified delivery of compose payloads to a target contract
+/// - Optional value transfer (ERC20) to the target prior to callback
+/// - Alerting hooks for off-chain/executor reporting
+/// - Introspection of the compose queue state
+#[starknet::interface]
+pub trait IMessagingComposer<TContractState> {
+    /// Queue a compose payload for later delivery
+    ///
+    /// Records the keccak hash of `message` keyed by (sender, `to`, `guid`, `index`).
+    /// A corresponding delivery will be executed via `lz_compose` by an executor.
+    ///
+    /// # Arguments
+    /// * `to` - Target contract that will receive the compose callback
+    /// * `guid` - Unique identifier of the original LayerZero message
+    /// * `index` - Compose index associated with the original message
+    /// * `message` - Opaque compose payload
+    ///
+    /// # Emits
+    /// * ComposeSent
+    ///
+    /// # Panics
+    /// * If a compose payload is already queued for the given (sender, `to`, `guid`, `index`)
+    fn send_compose(
+        ref self: TContractState,
+        to: ContractAddress,
+        guid: Bytes32,
+        index: u16,
+        message: ByteArray,
+    );
+
+    /// Deliver a previously queued compose payload to the target contract
+    ///
+    /// Verifies that the provided `message` matches the queued hash, marks the
+    /// compose as received to prevent reentrancy, optionally transfers compose
+    /// value (ERC20) from the executor to `to`, then calls `ILayerZeroComposer.lz_compose`.
+    ///
+    /// Note: The caller is expected to be the executor. Do not assume `from == caller`.
+    ///
+    /// # Arguments
+    /// * `from` - Originating OApp that queued the compose on source chain
+    /// * `to` - Target contract that implements `ILayerZeroComposer`
+    /// * `guid` - Unique identifier of the original LayerZero message
+    /// * `index` - Compose index associated with the original message
+    /// * `message` - Compose payload; must match the queued hash
+    /// * `extra_data` - Executor-provided metadata (protocol-opaque)
+    /// * `value` - Amount of compose token to transfer to `to` prior to callback
+    ///
+    /// # Emits
+    /// * ComposeDelivered
+    ///
+    /// # Panics
+    /// * If no compose is found or the hash does not match
+    /// * If `value > 0` and executor allowance is insufficient
+    fn lz_compose(
+        ref self: TContractState,
+        from: ContractAddress,
+        to: ContractAddress,
+        guid: Bytes32,
+        index: u16,
+        message: ByteArray,
+        extra_data: ByteArray,
+        value: u256,
+    );
+
+    /// Report an alert related to compose execution
+    ///
+    /// Allows the executor to emit a structured alert event that associates
+    /// telemetry or failure information with a compose attempt. Does not modify
+    /// queue state.
+    ///
+    /// # Arguments
+    /// * `from` - Originating OApp
+    /// * `to` - Target contract
+    /// * `guid` - Message GUID
+    /// * `index` - Compose index
+    /// * `gas` - Gas usage or gas limit context provided by the executor
+    /// * `value` - Intended compose token value
+    /// * `message` - Compose payload (for correlation)
+    /// * `extra_data` - Executor-provided metadata
+    /// * `reason` - Opaque reason for the alert
+    ///
+    /// # Emits
+    /// * LzComposeAlert
+    fn lz_compose_alert(
+        ref self: TContractState,
+        from: ContractAddress,
+        to: ContractAddress,
+        guid: Bytes32,
+        index: u16,
+        gas: u256,
+        value: u256,
+        message: ByteArray,
+        extra_data: ByteArray,
+        reason: Array<felt252>,
+    );
+
+    /// Inspect the compose queue
+    ///
+    /// Returns the stored value for a compose entry keyed by (`sender`, `to`, `guid`, `index`).
+    /// Semantics of the returned `Bytes32`:
+    /// - `0` — no compose queued
+    /// - `1` — compose has been delivered (RECEIVED_MESSAGE_HASH)
+    /// - otherwise — keccak hash of the queued `message`
+    ///
+    /// # Arguments
+    /// * `sender` - Originating OApp that called `send_compose`
+    /// * `to` - Target contract
+    /// * `guid` - Message GUID
+    /// * `index` - Compose index
+    ///
+    /// # Returns
+    /// * `Bytes32` - Encoded queue state or message hash as described above
+    fn get_compose_queue(
+        self: @TContractState,
+        sender: ContractAddress,
+        to: ContractAddress,
+        guid: Bytes32,
+        index: u16,
+    ) -> Bytes32;
+}

package/layerzero/src/endpoint/messaging_composer/messaging_composer.cairo

@@ -0,0 +1,223 @@
+//! Messaging composer component
+
+/// # `MessagingComposerComponent`
+///
+/// The `MessagingComposerComponent` is responsible for the lifecycle of "compose"
+/// payloads that are requested by an OApp after a LayerZero message has been
+/// delivered. It provides a minimal, verifiable queue keyed by the originating
+/// OApp, target contract, message GUID, and compose index. The executor later
+/// triggers delivery to the target contract implementing `ILayerZeroComposer`.
+///
+/// ## High-level responsibilities
+/// - Queue compose payloads by recording their keccak hash
+/// - Verify and deliver compose payloads to the target contract
+/// - Optionally transfer an ERC20 compose token to the target prior to callback
+/// - Emit alert events to aid off-chain/executor diagnostics
+/// - Expose read accessors for compose queue inspection
+///
+/// ## Security considerations
+/// - Delivery marks a compose entry as received using a sentinel value to
+///   prevent reentrancy or replay, rather than deleting the entry
+/// - Value transfer requires sufficient allowance from the executor to the
+///   composer contract
+/// - The executor is the caller of `lz_compose`; do not assume `from == caller`
+///
+/// ## Events emitted by the implementation
+/// - `ComposeSent(from, to, guid, index, message)`
+/// - `ComposeDelivered(from, to, guid, index)`
+/// - `LzComposeAlert(from, to, executor, guid, index, gas, value, message, extra_data, reason)`
+#[starknet::component]
+pub mod MessagingComposerComponent {
+    use lz_utils::bytes::Bytes32;
+    use lz_utils::keccak::keccak256;
+    use openzeppelin::token::erc20::interface::{IERC20Dispatcher, IERC20DispatcherTrait};
+    use starknet::storage::{
+        Map, StoragePathEntry, StoragePointerReadAccess, StoragePointerWriteAccess,
+    };
+    use starknet::{ContractAddress, get_caller_address, get_contract_address};
+    use starkware_utils::errors::assert_with_byte_array;
+    use crate::endpoint::constants::EMPTY_PAYLOAD_HASH;
+    use crate::endpoint::interfaces::layerzero_composer::{
+        ILayerZeroComposerDispatcher, ILayerZeroComposerDispatcherTrait,
+    };
+    use crate::endpoint::messaging_composer::errors::{
+        err_lz_compose_already_exists, err_lz_compose_not_found,
+        err_lz_compose_value_exceeds_allowance,
+    };
+    use crate::endpoint::messaging_composer::events::{
+        ComposeDelivered, ComposeSent, LzComposeAlert,
+    };
+    use crate::endpoint::messaging_composer::interface::IMessagingComposer;
+
+    /// Sentinel value written to the compose queue when a compose has been
+    /// successfully delivered. Used to prevent reentrancy/replay.
+    const RECEIVED_MESSAGE_HASH: Bytes32 = Bytes32 { value: 0x1 };
+
+    #[storage]
+    pub struct Storage {
+        /// ERC20 token used for value transfer on compose
+        compose_token_address: ContractAddress,
+        /// Compose queue mapping structure that stores the keccak hash of the
+        /// queued payload, or `RECEIVED_MESSAGE_HASH` once delivered.
+        /// uses keccak hash
+        ///
+        /// from => to => guid => index => messageHash
+        compose_queue: Map<ContractAddress, Map<ContractAddress, Map<Bytes32, Map<u16, Bytes32>>>>,
+    }
+
+    #[event]
+    #[derive(Drop, starknet::Event)]
+    pub enum Event {
+        ComposeSent: ComposeSent,
+        ComposeDelivered: ComposeDelivered,
+        LzComposeAlert: LzComposeAlert,
+    }
+
+    #[embeddable_as(MessagingComposerImpl)]
+    impl MessagingComposerImplImpl<
+        TContractState, +HasComponent<TContractState>,
+    > of IMessagingComposer<ComponentState<TContractState>> {
+        /// Queue a compose payload for later delivery
+        ///
+        /// Stores the keccak hash of `message` under the key composed of
+        /// `(sender, to, guid, index)`. Reverts if an entry already exists.
+        ///
+        /// Emits: `ComposeSent`
+        ///
+        /// Panics:
+        /// - If a compose payload is already queued for the given key
+        fn send_compose(
+            ref self: ComponentState<TContractState>,
+            to: ContractAddress,
+            guid: Bytes32,
+            index: u16,
+            message: ByteArray,
+        ) {
+            let sender = get_caller_address();
+            let entry = self.compose_queue.entry(sender).entry(to).entry(guid).entry(index);
+            let current_hash = entry.read();
+            assert_with_byte_array(
+                current_hash == EMPTY_PAYLOAD_HASH, err_lz_compose_already_exists(),
+            );
+            // Hash message and store it in the compose queue
+            // Note: No endianness conversion is required; this is not cross-chain dependent
+            let message_hash = keccak256(@message);
+            entry.write(message_hash);
+            self.emit(ComposeSent { from: sender, to, guid, index, message });
+        }
+
+        /// Deliver a previously queued compose payload to the target contract
+        ///
+        /// Verifies the provided `message` against the queued hash. Marks the
+        /// queue entry as received using `RECEIVED_MESSAGE_HASH` to prevent
+        /// reentrancy/replay. If `value > 0`, transfers compose token from the
+        /// executor (caller) to the target prior to invoking
+        /// `ILayerZeroComposer.lz_compose`.
+        ///
+        /// Emits: `ComposeDelivered`
+        ///
+        /// Panics:
+        /// - If the compose entry is missing or the hash does not match
+        /// - If `value > 0` and the executor's allowance is insufficient
+        fn lz_compose(
+            ref self: ComponentState<TContractState>,
+            from: ContractAddress,
+            to: ContractAddress,
+            guid: Bytes32,
+            index: u16,
+            message: ByteArray,
+            extra_data: ByteArray,
+            value: u256,
+        ) {
+            let entry = self.compose_queue.entry(from).entry(to).entry(guid).entry(index);
+            let expected_hash = entry.read();
+            let actual_hash = keccak256(@message);
+            assert_with_byte_array(
+                expected_hash == actual_hash, err_lz_compose_not_found(expected_hash, actual_hash),
+            );
+
+            // marks the message as received to prevent reentrancy
+            // cannot just delete the value, otherwise the message can be sent again and could
+            // result in some undefined behaviour even though the sender(composing Oapp) is
+            // implicitly fully trusted by the composer.
+            // eg. sender may not even realize it has such a bug
+            entry.write(RECEIVED_MESSAGE_HASH);
+
+            let executor = get_caller_address();
+
+            // Verify allowance and transfer only when value > 0
+            if value > 0 {
+                let compose_token_dispatcher = IERC20Dispatcher {
+                    contract_address: self.compose_token_address.read(),
+                };
+                let allowance = compose_token_dispatcher
+                    .allowance(executor, get_contract_address());
+                assert_with_byte_array(
+                    value <= allowance, err_lz_compose_value_exceeds_allowance(value, allowance),
+                );
+                compose_token_dispatcher.transfer_from(executor, to, value);
+            }
+
+            let composer_dispatcher = ILayerZeroComposerDispatcher { contract_address: to };
+            composer_dispatcher.lz_compose(from, guid, message, executor, extra_data, value);
+
+            self.emit(ComposeDelivered { from, to, guid, index });
+        }
+
+        /// Emit an alert related to compose execution
+        ///
+        /// Allows the executor to surface telemetry or failure information for a
+        /// compose attempt. This does not modify the compose queue state.
+        ///
+        /// Emits: `LzComposeAlert`
+        fn lz_compose_alert(
+            ref self: ComponentState<TContractState>,
+            from: ContractAddress,
+            to: ContractAddress,
+            guid: Bytes32,
+            index: u16,
+            gas: u256,
+            value: u256,
+            message: ByteArray,
+            extra_data: ByteArray,
+            reason: Array<felt252>,
+        ) {
+            let executor = get_caller_address();
+            self
+                .emit(
+                    LzComposeAlert {
+                        from, to, executor, guid, index, gas, value, message, extra_data, reason,
+                    },
+                );
+        }
+
+        /// Inspect a specific compose queue entry
+        ///
+        /// Returns the stored value for a compose entry keyed by
+        /// `(sender, to, guid, index)` with the following semantics:
+        /// - `0` — no compose queued
+        /// - `RECEIVED_MESSAGE_HASH` (1) — compose delivered
+        /// - otherwise — keccak hash of the queued `message`
+        fn get_compose_queue(
+            self: @ComponentState<TContractState>,
+            sender: ContractAddress,
+            to: ContractAddress,
+            guid: Bytes32,
+            index: u16,
+        ) -> Bytes32 {
+            self.compose_queue.entry(sender).entry(to).entry(guid).entry(index).read()
+        }
+    }
+
+    /// Internal functions for initialization
+    #[generate_trait]
+    pub impl InternalImpl<
+        TContractState, +HasComponent<TContractState>,
+    > of InternalTrait<TContractState> {
+        /// Initialize the MessagingComposer with the ERC20 token address used
+        /// for value transfers during compose delivery.
+        fn initializer(ref self: ComponentState<TContractState>, token_address: ContractAddress) {
+            self.compose_token_address.write(token_address);
+        }
+    }
+}

package/layerzero/src/lib.cairo

@@ -0,0 +1,189 @@
+//! # LayerZero Protocol Implementation for Starknet
+//!
+//! This project provides a comprehensive implementation of the LayerZero protocol for the Starknet
+//! ecosystem.
+//! It includes the core components necessary for enabling seamless cross-chain messaging, allowing
+//! developers to build sophisticated omnichain applications (OApps) that can interact with other
+//! blockchains.
+//!
+//! The project is structured into several modules, each responsible for a specific aspect of the
+//! LayerZero protocol:
+//! - **Common**: Contains shared data structures, constants, and utility functions used across the
+//! project.
+//! - **Endpoint**: The core of the LayerZero protocol, responsible for sending and receiving
+//! messages.
+//! - **MessageLib**: Defines the different message libraries that OApps can use to configure their
+//! security posture.
+//! - **Treasury**: Manages the fees collected by the protocol.
+//! - **Workers**: A collection of contracts that perform specific tasks, such as price feeds and
+//! data verification.
+//! - **OApps**: Example omnichain applications that demonstrate how to use the LayerZero protocol.
+
+pub mod common {
+    pub mod structs {
+        pub mod messaging;
+        pub mod packet;
+    }
+    pub mod constants;
+    pub mod conversions;
+    pub mod guid;
+    pub mod packet_v1_codec;
+}
+
+pub mod endpoint {
+    pub mod message_lib_manager {
+        pub mod errors;
+        pub mod events;
+        pub mod interface;
+        pub mod message_lib_manager;
+        pub mod structs;
+    }
+    pub mod messaging_channel {
+        pub mod errors;
+        pub mod events;
+        pub mod interface;
+        pub mod messaging_channel;
+    }
+    pub mod messaging_composer {
+        pub mod errors;
+        pub mod events;
+        pub mod interface;
+        pub mod messaging_composer;
+    }
+    pub mod interfaces {
+        pub mod endpoint;
+        pub mod layerzero_composer;
+        pub mod layerzero_receiver;
+    }
+    pub mod constants;
+    pub mod endpoint;
+    pub mod errors;
+    pub mod events;
+}
+
+pub mod message_lib {
+    pub mod interface;
+    pub mod sml {
+        pub mod errors;
+        pub mod events;
+        pub mod simple_message_lib;
+    }
+    pub mod structs;
+    pub mod uln {
+        pub mod errors;
+        pub mod events;
+        pub mod options;
+        pub mod structs {
+            pub mod executor_config;
+            pub mod payment_info;
+            pub mod uln_config;
+            pub mod uln_config_storage_node;
+            pub mod verification;
+        }
+        pub mod interface;
+        pub mod ultra_light_node;
+    }
+    pub mod blocked_message_lib;
+}
+
+pub mod treasury {
+    pub mod interfaces {
+        pub mod layerzero_treasury;
+        pub mod lz_token_fee_lib;
+        pub mod treasury_admin;
+    }
+    pub mod errors;
+    pub mod events;
+    pub mod treasury;
+}
+
+pub mod workers {
+    pub mod base {
+        pub mod base;
+        pub mod errors;
+        pub mod events;
+        pub mod interface;
+        pub mod structs;
+    }
+    pub mod executor {
+        pub mod errors;
+        pub mod events;
+        pub mod executor;
+        pub mod fee_lib {
+            pub mod executor_fee_lib;
+            pub mod interface;
+        }
+        pub mod interface;
+        pub mod options;
+        pub mod structs;
+    }
+    pub mod price_feed {
+        pub mod constants;
+        pub mod errors;
+        pub mod events;
+        pub mod interface;
+        pub mod price_feed;
+        pub mod structs;
+    }
+    pub mod dvn {
+        pub mod constants;
+        pub mod dvn;
+        pub mod errors;
+        pub mod events;
+        pub mod fee_lib {
+            pub mod dvn_fee_lib;
+            pub mod interface;
+        }
+        pub mod interface;
+        pub mod options;
+        pub mod structs;
+    }
+    pub mod access_control;
+    pub mod common;
+    pub mod interface;
+}
+
+pub mod oapps {
+    pub mod common {
+        pub mod oapp_options_type_3 {
+            pub mod errors;
+            pub mod events;
+            pub mod interface;
+            pub mod oapp_options_type_3;
+            pub mod structs;
+        }
+    }
+    pub mod oapp {
+        pub mod errors;
+        pub mod events;
+        pub mod interface;
+        pub mod oapp;
+        pub mod oapp_core;
+    }
+    pub mod oft {
+        pub mod errors;
+        pub mod events;
+        pub mod interface;
+        pub mod oft;
+        pub mod oft_adapter;
+        pub mod oft_compose_msg_codec;
+        pub mod oft_core;
+        pub mod oft_msg_codec;
+        pub mod structs;
+    }
+    pub mod counter {
+        pub mod constants;
+        pub mod counter;
+        pub mod interface;
+        pub mod structs;
+    }
+    pub mod message_inspector {
+        pub mod interface;
+    }
+}
+
+// Re-export commonly used types for easier access
+pub use common::structs::messaging::{MessageReceipt, MessagingFee, MessagingParams};
+pub use common::structs::packet::{Origin, Packet};
+pub use oapps::oapp::oapp_core::OAppCoreComponent;
+pub use workers::base::base::WorkerBaseComponent;

package/layerzero/src/message_lib/blocked_message_lib.cairo

@@ -0,0 +1,114 @@
+/// This is a message library that is used to block all messages from being sent or received.
+#[starknet::contract]
+pub mod BlockedMessageLib {
+    use core::panics::panic_with_byte_array;
+    use lz_utils::bytes::Bytes32;
+    use lz_utils::error::{Error, format_error};
+    use starknet::ContractAddress;
+    use crate::common::structs::messaging::{MessageLibSendResult, MessagingFee};
+    use crate::common::structs::packet::Packet;
+    use crate::message_lib::interface::{IMessageLib, VerificationState};
+    use crate::message_lib::structs::{MessageLibType, SetConfigParam};
+
+    // === Error Definitions ===
+    #[derive(Drop)]
+    pub enum BlockedMessageLibError {
+        NotImplemented,
+    }
+
+    impl ErrorNameImpl of Error<BlockedMessageLibError> {
+        fn prefix() -> ByteArray {
+            "LZ_BLOCKED_MESSAGE_LIB"
+        }
+
+        fn name(self: BlockedMessageLibError) -> ByteArray {
+            match self {
+                BlockedMessageLibError::NotImplemented => "NOT_IMPLEMENTED",
+            }
+        }
+    }
+
+    pub fn err_not_implemented() -> ByteArray {
+        format_error(BlockedMessageLibError::NotImplemented, "")
+    }
+
+    // === Storage ===
+    #[storage]
+    struct Storage {}
+
+    // === Constructor ===
+    #[constructor]
+    fn constructor(ref self: ContractState) { // No initialization needed
+    }
+
+    // === IMessageLib Implementation ===
+    #[abi(embed_v0)]
+    impl MessageLibImpl of IMessageLib<ContractState> {
+        fn send(
+            ref self: ContractState, packet: Packet, options: ByteArray, pay_in_lz_token: bool,
+        ) -> MessageLibSendResult {
+            panic_with_byte_array(@err_not_implemented());
+        }
+
+        fn verify(
+            ref self: ContractState,
+            packet_header: ByteArray,
+            payload_hash: Bytes32,
+            confirmations: u64,
+        ) {
+            panic_with_byte_array(@err_not_implemented());
+        }
+
+        fn commit(ref self: ContractState, packet_header: ByteArray, payload_hash: Bytes32) {
+            panic_with_byte_array(@err_not_implemented());
+        }
+
+        fn quote(
+            ref self: ContractState, packet: Packet, options: ByteArray, pay_in_lz_token: bool,
+        ) -> MessagingFee {
+            panic_with_byte_array(@err_not_implemented());
+        }
+
+        fn message_lib_type(self: @ContractState) -> MessageLibType {
+            MessageLibType::SendAndReceive
+        }
+
+        fn is_supported_send_eid(self: @ContractState, dst_eid: u32) -> bool {
+            true
+        }
+
+        fn is_supported_receive_eid(self: @ContractState, src_eid: u32) -> bool {
+            true
+        }
+
+        fn set_send_config(
+            ref self: ContractState, oapp: ContractAddress, params: Array<SetConfigParam>,
+        ) {
+            panic_with_byte_array(@err_not_implemented());
+        }
+
+        fn set_receive_config(
+            ref self: ContractState, oapp: ContractAddress, params: Array<SetConfigParam>,
+        ) {
+            panic_with_byte_array(@err_not_implemented());
+        }
+
+        fn get_send_config(
+            self: @ContractState, eid: u32, oapp: ContractAddress, config_type: u32,
+        ) -> Array<felt252> {
+            panic_with_byte_array(@err_not_implemented());
+        }
+
+        fn get_receive_config(
+            self: @ContractState, eid: u32, oapp: ContractAddress, config_type: u32,
+        ) -> Array<felt252> {
+            panic_with_byte_array(@err_not_implemented());
+        }
+
+        fn verifiable(
+            self: @ContractState, packet_header: ByteArray, payload_hash: Bytes32,
+        ) -> VerificationState {
+            VerificationState::NotInitializable
+        }
+    }
+}