@layerzerolabs/protocol-starknet-v2 0.0.34

package/layerzero/src/endpoint/errors.cairo

@@ -0,0 +1,108 @@
+//! Endpoint errors
+
+use lz_utils::error::{Error, format_error};
+
+#[derive(Drop)]
+pub enum EndpointError {
+    /// Triggered when a message is committed by a contract that is not a valid receive library for
+    /// the given path.
+    InvalidReceiveLibrary,
+    /// Triggered when an attempt is made to commit a message to a path that has not been
+    /// initialized.
+    PathNotInitializable,
+    PathNotCommittable,
+    InvalidPayloadHash,
+    /// Triggered when a message with an invalid nonce is received.
+    InvalidNonce,
+    /// Triggered when the payload hash of a received message does not match the committed payload
+    /// hash.
+    PayloadHashNotFound,
+    /// Triggered when the value sent with `lz_receive` exceeds the executor's token allowance.
+    LzReceiveValueExceedsAllowance,
+    /// Triggered when an unauthorized address attempts to perform a restricted action.
+    Unauthorized,
+    /// Triggered when an attempt is made to pay fees in the LZ token, but no LZ token address is
+    /// set.
+    LzTokenUnavailable,
+    /// Triggered when an attempt is made to pay fees in the LZ token, but the fee is zero.
+    ZeroLzTokenFee,
+    /// Triggered when the fees provided are insufficient to cover the cost of the message.
+    InsufficientFee,
+}
+
+impl ErrorNameImpl of Error<EndpointError> {
+    fn prefix() -> ByteArray {
+        "LZ_ENDPOINT"
+    }
+
+    fn name(self: EndpointError) -> ByteArray {
+        match self {
+            EndpointError::InvalidReceiveLibrary => "INVALID_RECEIVE_LIBRARY",
+            EndpointError::PathNotInitializable => "PATH_NOT_INITIALIZABLE",
+            EndpointError::PathNotCommittable => "PATH_NOT_COMMITTABLE",
+            EndpointError::InvalidPayloadHash => "INVALID_PAYLOAD_HASH",
+            EndpointError::InvalidNonce => "INVALID_NONCE",
+            EndpointError::PayloadHashNotFound => "PAYLOAD_HASH_NOT_FOUND",
+            EndpointError::LzReceiveValueExceedsAllowance => "LZ_RECEIVE_VALUE_EXCEEDS_ALLOWANCE",
+            EndpointError::Unauthorized => "UNAUTHORIZED",
+            EndpointError::LzTokenUnavailable => "LZ_TOKEN_UNAVAILABLE",
+            EndpointError::ZeroLzTokenFee => "ZERO_LZ_TOKEN_FEE",
+            EndpointError::InsufficientFee => "INSUFFICIENT_FEE",
+        }
+    }
+}
+
+pub fn err_invalid_receive_library() -> ByteArray {
+    format_error(EndpointError::InvalidReceiveLibrary, "")
+}
+
+pub fn err_path_not_initializable() -> ByteArray {
+    format_error(EndpointError::PathNotInitializable, "")
+}
+
+pub fn err_path_not_committable() -> ByteArray {
+    format_error(EndpointError::PathNotCommittable, "")
+}
+
+pub fn err_invalid_payload_hash() -> ByteArray {
+    format_error(EndpointError::InvalidPayloadHash, "")
+}
+
+pub fn err_lz_receive_value_exceeds_allowance(
+    lz_receive_value: u256, allowance: u256,
+) -> ByteArray {
+    format_error(
+        EndpointError::LzReceiveValueExceedsAllowance,
+        format!("LZ receive value: {}, Allowance: {}", lz_receive_value, allowance),
+    )
+}
+
+pub fn err_unauthorized() -> ByteArray {
+    format_error(EndpointError::Unauthorized, "")
+}
+
+pub fn err_lz_token_unavailable() -> ByteArray {
+    format_error(EndpointError::LzTokenUnavailable, "")
+}
+
+pub fn err_zero_lz_token_fee() -> ByteArray {
+    format_error(EndpointError::ZeroLzTokenFee, "")
+}
+
+pub fn err_insufficient_fee(
+    required_native_fee: u256,
+    supplied_native_fee: u256,
+    required_lz_token_fee: u256,
+    supplied_lz_token_fee: u256,
+) -> ByteArray {
+    format_error(
+        EndpointError::InsufficientFee,
+        format!(
+            "Required native fee: {}, Supplied native fee: {}, Required lz token fee: {}, Supplied lz token fee: {}",
+            required_native_fee,
+            supplied_native_fee,
+            required_lz_token_fee,
+            supplied_lz_token_fee,
+        ),
+    )
+}

package/layerzero/src/endpoint/events.cairo

@@ -0,0 +1,124 @@
+//! Endpoint events
+
+use lz_utils::bytes::Bytes32;
+use starknet::ContractAddress;
+use crate::common::structs::packet::Origin;
+
+/// Emitted when a packet is sent from the Endpoint.
+#[derive(Drop, Debug, PartialEq, starknet::Event)]
+pub struct PacketSent {
+    /// The encoded packet data.
+    pub encoded_packet: ByteArray,
+    /// The options specified for the message.
+    pub options: ByteArray,
+    /// The address of the send library used.
+    #[key]
+    pub send_library: ContractAddress,
+}
+
+/// Emitted when a packet is committed for verification.
+#[derive(Drop, Debug, PartialEq, starknet::Event)]
+pub struct PacketCommitted {
+    /// The origin of the packet.
+    #[key]
+    pub origin: Origin,
+    /// The intended receiver of the packet.
+    #[key]
+    pub receiver: ContractAddress,
+    /// The hash of the packet's payload.
+    #[key]
+    pub payload_hash: Bytes32,
+}
+
+/// Emitted when a packet is successfully delivered to the receiver.
+#[derive(Drop, Debug, PartialEq, starknet::Event)]
+pub struct PacketDelivered {
+    /// The origin of the packet.
+    #[key]
+    pub origin: Origin,
+    /// The receiver of the packet.
+    #[key]
+    pub receiver: ContractAddress,
+}
+
+/// Emitted when a receive message fails.
+#[derive(Drop, Debug, PartialEq, starknet::Event)]
+pub struct LzReceiveAlert {
+    /// The origin of the message.
+    #[key]
+    pub origin: Origin,
+    /// The intended receiver of the message.
+    #[key]
+    pub receiver: ContractAddress,
+    /// The address of the executor that triggered the alert.
+    #[key]
+    pub executor: ContractAddress,
+    /// The GUID of the message.
+    #[key]
+    pub guid: Bytes32,
+    /// The gas amount related to the alert.
+    pub gas: u256,
+    /// The value sent with the message.
+    pub value: u256,
+    /// The message payload.
+    pub message: ByteArray,
+    /// Extra data provided with the alert.
+    pub extra_data: ByteArray,
+    /// The reason for the alert.
+    pub reason: Array<felt252>,
+}
+
+/// Emitted when a new message library is registered.
+#[derive(Drop, Debug, PartialEq, starknet::Event)]
+pub struct LibraryRegistered {
+    /// The address of the registered library.
+    #[key]
+    pub library: ContractAddress,
+}
+
+/// Emitted when a send library is set for a specific sender and destination EID.
+#[derive(Drop, Debug, PartialEq, starknet::Event)]
+pub struct SendLibrarySet {
+    /// The sender's address.
+    #[key]
+    pub sender: ContractAddress,
+    /// The destination EID.
+    #[key]
+    pub dst_eid: u32,
+    /// The address of the send library.
+    #[key]
+    pub library: ContractAddress,
+}
+
+/// Emitted when a receive library is set for a specific receiver and source EID.
+#[derive(Drop, Debug, PartialEq, starknet::Event)]
+pub struct ReceiveLibrarySet {
+    /// The receiver's address.
+    #[key]
+    pub receiver: ContractAddress,
+    /// The source EID.
+    #[key]
+    pub src_eid: u32,
+    /// The address of the receive library.
+    #[key]
+    pub library: ContractAddress,
+}
+
+/// Emitted when the LZ token address is set.
+#[derive(Drop, Debug, PartialEq, starknet::Event)]
+pub struct LzTokenSet {
+    /// The new address of the LZ token.
+    #[key]
+    pub lz_token_address: ContractAddress,
+}
+
+/// Emitted when a delegate is set for an OApp.
+#[derive(Drop, starknet::Event)]
+pub struct DelegateSet {
+    /// The OApp's address.
+    #[key]
+    pub oapp: ContractAddress,
+    /// The delegate's address.
+    #[key]
+    pub delegate: ContractAddress,
+}

package/layerzero/src/endpoint/interfaces/endpoint.cairo

@@ -0,0 +1,286 @@
+//! Endpoint interface
+
+use lz_utils::bytes::Bytes32;
+use starknet::ContractAddress;
+use crate::MessagingFee;
+use crate::common::structs::messaging::{MessageReceipt, MessagingParams};
+use crate::common::structs::packet::Origin;
+
+/// # `IEndpoint` Interface
+///
+/// The `IEndpoint` interface is the central component of the LayerZero protocol, designed to
+/// facilitate seamless, secure, and efficient cross-chain messaging. As the primary entry point for
+/// all LayerZero messages, the Endpoint contract manages the entire lifecycle of a message, from
+/// sending to receiving, while ensuring reliable delivery and robust security. It provides a
+/// comprehensive set of functionalities that enable developers to build sophisticated omnichain
+/// applications (OApps) with ease.
+///
+/// ## Key Features
+/// - **Message Sending and Receiving**: Core functions for sending and receiving messages across
+/// different blockchains,
+///   abstracting away the complexities of cross-chain communication.
+/// - **Configurable Security**: OApps can define their own security requirements by specifying a
+/// set of Data Verification
+///   Networks (DVNs) and a threshold of required verifications, ensuring that each message meets
+///   the application's security standards.
+/// - **Fee Quotation**: Provides a mechanism to quote the cost of sending a message, allowing
+/// applications to estimate
+///   and manage transaction fees transparently.
+/// - **Message Verification and Execution**: Verifies the authenticity of incoming messages through
+/// the configured DVNs
+///   and ensures that only valid messages are executed.
+/// - **Commit-Store-Execute Pattern**: Implements a secure message handling pattern where message
+/// commitments are stored
+///   on-chain and executed only after successful verification, preventing race conditions and other
+///   security vulnerabilities.
+/// - **Alerts and Error Handling**: Includes a system for receiving alerts about failed messages,
+/// enabling robust error
+///   handling and recovery mechanisms.
+/// - **Delegate and Token Management**: Supports delegation of OApp configuration management and
+/// allows for the use of
+///   a specific token for paying LayerZero fees.
+#[derive(Drop, Serde)]
+pub enum ExecutionState {
+    NotExecutable, // executor: waits for PayloadVerified event and starts polling for executable
+    VerifiedButNotExecutable, // executor: starts active polling for executable
+    Executable,
+    Executed,
+}
+
+#[starknet::interface]
+pub trait IEndpoint<TContractState> {
+    /// Sends a message to a remote OApp.
+    ///
+    /// # Arguments
+    ///
+    /// * `params` - A `MessagingParams` struct containing the destination EID, receiver address,
+    /// message payload,
+    ///   OApp-specific options, and whether to pay in the LZ token.
+    /// * `refund_address` - The address to which any remaining gas fees should be refunded.
+    ///
+    /// # Returns
+    ///
+    /// * `MessageReceipt` - A struct containing the GUID of the message and the nonce.
+    ///
+    /// @dev This function is the primary entry point for sending a message from a local OApp to a
+    /// remote OApp.
+    /// It encodes the message, calculates the required fee, and dispatches it to the LayerZero
+    /// network.
+    fn send(
+        ref self: TContractState, params: MessagingParams, refund_address: ContractAddress,
+    ) -> MessageReceipt;
+
+    /// Quotes the fee for sending a message.
+    ///
+    /// # Arguments
+    ///
+    /// * `params` - A `MessagingParams` struct containing the destination EID, receiver address,
+    /// message payload,
+    ///   OApp-specific options, and whether to pay in the LZ token.
+    /// * `sender` - The address of the OApp sending the message.
+    ///
+    /// # Returns
+    ///
+    /// * `MessagingFee` - A struct containing the native fee and the LZ token fee required to send
+    /// the message.
+    ///
+    /// @dev This function allows an OApp to estimate the cost of sending a message before actually
+    /// sending it.
+    /// The fee is calculated based on the message parameters and the current network conditions.
+    fn quote(
+        self: @TContractState, params: MessagingParams, sender: ContractAddress,
+    ) -> MessagingFee;
+
+    /// Commits a message to be verified by the DVNs.
+    ///
+    /// # Arguments
+    ///
+    /// * `origin` - An `Origin` struct containing the source EID and sender address.
+    /// * `receiver` - The address of the OApp that will receive the message.
+    /// * `payload_hash` - The Keccak-256 hash of the message payload.
+    ///
+    /// @dev This function is called by the LayerZero network to commit a message to the destination
+    /// Endpoint.
+    /// It stores a hash of the message payload, which will be used later for verification.
+    /// This is part of the commit-store-execute pattern to ensure secure message handling.
+    fn commit(
+        ref self: TContractState, origin: Origin, receiver: ContractAddress, payload_hash: Bytes32,
+    );
+
+    /// Receives and executes a message from a remote OApp.
+    ///
+    /// # Arguments
+    ///
+    /// * `origin` - An `Origin` struct containing the source EID and sender address.
+    /// * `receiver` - The address of the OApp that will receive the message.
+    /// * `guid` - The globally unique identifier of the message.
+    /// * `message` - The message payload.
+    /// * `value` - The value sent with the message.
+    /// * `extra_data` - Additional data provided by the DVNs.
+    ///
+    /// @dev This function is called by the LayerZero network after a message has been successfully
+    /// verified.
+    /// It decodes the message and calls the `lz_receive` function on the destination OApp.
+    fn lz_receive(
+        ref self: TContractState,
+        origin: Origin,
+        receiver: ContractAddress,
+        guid: Bytes32,
+        message: ByteArray,
+        // every payment is an ERC20 transfer on Starknet
+        value: u256,
+        extra_data: ByteArray,
+    );
+
+    /// Receives an alert about a failed message.
+    ///
+    /// # Arguments
+    ///
+    /// * `origin` - An `Origin` struct containing the source EID and sender address.
+    /// * `receiver` - The address of the OApp that was supposed to receive the message.
+    /// * `guid` - The GUID of the failed message.
+    /// * `gas` - The amount of gas used before the failure.
+    /// * `value` - The value sent with the message.
+    /// * `message` - The message payload.
+    /// * `extra_data` - Additional data provided by the DVNs.
+    /// * `reason` - An array of felts describing the reason for the failure.
+    ///
+    /// @dev This function is called by the LayerZero network when a message fails to be delivered
+    /// or executed.
+    /// It allows the OApp to handle the failure gracefully, for example, by retrying the message or
+    /// notifying a user.
+    fn lz_receive_alert(
+        ref self: TContractState,
+        origin: Origin,
+        receiver: ContractAddress,
+        guid: Bytes32,
+        gas: u256,
+        value: u256,
+        message: ByteArray,
+        extra_data: ByteArray,
+        reason: Array<felt252>,
+    );
+
+    /// Clears a stored message payload from the contract's storage.
+    ///
+    /// # Arguments
+    ///
+    /// * `origin` - An `Origin` struct containing the source EID and sender address.
+    /// * `receiver` - The address of the OApp that received the message.
+    /// * `guid` - The GUID of the message.
+    /// * `message` - The message payload.
+    ///
+    /// @dev This function is called by the LayerZero network after a message has been successfully
+    /// executed to remove the stored payload hash and free up storage space.
+    fn clear(
+        ref self: TContractState,
+        origin: Origin,
+        receiver: ContractAddress,
+        guid: Bytes32,
+        message: ByteArray,
+    );
+
+    /// Gets the address of the LZ token used for paying fees.
+    ///
+    /// # Returns
+    ///
+    /// * `lz_token_address` - The address of the LZ token contract.
+    ///
+    /// @dev The LZ token is an alternative to the native token for paying LayerZero fees.
+    /// This function returns the address of the LZ token contract.
+    fn get_lz_token(self: @TContractState) -> ContractAddress;
+
+    /// Gets the endpoint ID (EID) of the local chain.
+    ///
+    /// # Returns
+    ///
+    /// * `eid` - The EID of the local chain.
+    ///
+    /// @dev The EID is a unique identifier for each chain supported by LayerZero.
+    /// This function returns the EID of the chain where the Endpoint contract is deployed.
+    fn get_eid(self: @TContractState) -> u32;
+
+    /// Sets the address of the LZ token used for paying fees.
+    ///
+    /// # Arguments
+    ///
+    /// * `lz_token_address` - The new address of the LZ token contract.
+    fn set_lz_token(ref self: TContractState, lz_token_address: ContractAddress);
+
+    /// Sets the delegate for an OApp.
+    ///
+    /// # Arguments
+    /// * `delegate` - The address to be set as the delegate.
+    ///
+    /// @dev The delegate is an address that is authorized to manage the OApp's configurations,
+    /// such as the required DVNs and the verification threshold.
+    /// This allows for separation of concerns, where the OApp owner can delegate configuration
+    /// management to a separate address.
+    fn set_delegate(ref self: TContractState, delegate: ContractAddress);
+
+    /// Gets the delegate for an OApp.
+    ///
+    /// # Arguments
+    /// * `oapp` - The address of the OApp.
+    ///
+    /// # Returns
+    /// * `ContractAddress` - The address of the delegate.
+    fn get_delegate(self: @TContractState, oapp: ContractAddress) -> ContractAddress;
+
+
+    /// Checks if a message path is initializable.
+    ///
+    /// # Arguments
+    ///
+    /// * `origin` - An `Origin` struct containing the source EID and sender address.
+    /// * `receiver` - The address of the OApp that will receive the message.
+    ///
+    /// # Returns
+    /// * `bool` - `true` if the message path is initializable, `false` otherwise.
+    ///
+    /// @dev A message path is initializable if it has not been configured yet.
+    /// This function is used to determine if a new configuration can be set for a given message
+    /// path.
+    fn initializable(self: @TContractState, origin: Origin, receiver: ContractAddress) -> bool;
+
+    /// Check if the message is committable
+    ///
+    /// # Arguments
+    ///
+    /// * `origin`: The origin of the message
+    /// * `receiver`: The receiver of the message
+    ///
+    /// # Returns
+    /// * `bool` - True if the message is committable, false otherwise
+    fn committable(self: @TContractState, origin: Origin, receiver: ContractAddress) -> bool;
+
+    /// Check if the message is committable with a receive library
+    ///
+    /// # Arguments
+    ///
+    /// * `origin`: The origin of the message
+    /// * `receiver`: The receiver of the message
+    /// * `receive_lib`: The receive library of the message
+    ///
+    /// # Returns
+    /// * `bool` - True if the message is committable with a receive library, false otherwise
+    fn committable_with_receive_lib(
+        self: @TContractState,
+        origin: Origin,
+        receiver: ContractAddress,
+        receive_lib: ContractAddress,
+    ) -> bool;
+
+    /// Check if the message is executable
+    ///
+    /// # Arguments
+    ///
+    /// * `origin` - An `Origin` struct containing the source EID and sender address.
+    /// * `receiver` - The address of the OApp that will receive the message.
+    ///
+    /// # Returns
+    /// * `ExecutionState` - The execution state of the message
+    fn executable(
+        self: @TContractState, origin: Origin, receiver: ContractAddress,
+    ) -> ExecutionState;
+}

package/layerzero/src/endpoint/interfaces/layerzero_composer.cairo

@@ -0,0 +1,62 @@
+//! LayerZero composer interface
+
+use lz_utils::bytes::Bytes32;
+use starknet::ContractAddress;
+
+/// # `ILayerZeroComposer` Interface
+///
+/// The `ILayerZeroComposer` interface is responsible for receiving and processing compose payloads
+/// from LayerZero messages.
+/// It provides a function for handling the compose request and verifying the payload before
+/// executing it.
+///
+/// ## Key Features
+/// - **Compose Handling**: Receives and processes compose payloads from LayerZero messages.
+/// - **Verification**: Verifies the compose request and payload before executing it.
+/// - **Security**: Ensures that only valid compose requests are processed.
+///
+/// Contracts that wish to receive compose payloads must implement this
+/// interface. The endpoint's `MessagingComposer` component verifies the
+/// compose request and then invokes `lz_compose` on the target contract.
+///
+/// ## High-level flow
+/// - An OApp on the source chain requests a compose to a target contract
+///   on the destination chain
+/// - The destination endpoint's `MessagingComposer` validates the request,
+///   prevents reentrancy by marking the message as received, and, if
+///   `value > 0`, transfers the configured compose token to the target
+///   contract before calling `lz_compose`
+/// - The target contract handles the payload in `lz_compose`
+#[starknet::interface]
+pub trait ILayerZeroComposer<TContractState> {
+    /// Receives a compose payload for a previously delivered LayerZero message
+    ///
+    /// This function is called by the endpoint's `MessagingComposer` after it
+    /// has verified the compose request and optionally transferred value to
+    /// this contract. Implementations must not assume that the caller equals
+    /// `from`; the caller is the executor that relayed the compose.
+    ///
+    /// # Arguments
+    /// * `from` - The originating OApp address that initiated the compose on the
+    ///            source chain
+    /// * `guid` - Globally unique identifier of the original LayerZero message
+    /// * `message` - Opaque compose payload provided by the sender
+    /// * `executor` - The contract address that executed the compose on-chain
+    /// * `extra_data` - Additional metadata from the executor (e.g., execution
+    ///                  context or options); protocol-opaque
+    /// * `value` - Amount of compose token that was transferred to this
+    ///            contract immediately before this call (0 if none)
+    ///
+    /// # Panics
+    /// * Implementation-defined. Implementations should revert if the payload is invalid for this
+    /// contract or if execution preconditions are not met.
+    fn lz_compose(
+        ref self: TContractState,
+        from: ContractAddress,
+        guid: Bytes32,
+        message: ByteArray,
+        executor: ContractAddress,
+        extra_data: ByteArray,
+        value: u256,
+    );
+}

package/layerzero/src/endpoint/interfaces/layerzero_receiver.cairo

@@ -0,0 +1,63 @@
+//! LayerZero receiver interface
+
+use lz_utils::bytes::Bytes32;
+use starknet::ContractAddress;
+use crate::common::structs::packet::Origin;
+
+/// # `ILayerZeroReceiver` Interface
+///
+/// The `ILayerZeroReceiver` interface is responsible for receiving and processing LayerZero
+/// messages from other chains.
+/// It provides a function for handling the received message and executing the payload.
+///
+/// ## Key Features
+/// - **Message Receiving**: Receives and processes LayerZero messages from other chains.
+/// - **Execution**: Executes the received message payload.
+/// - **Security**: Ensures that only valid messages are processed.
+#[starknet::interface]
+pub trait ILayerZeroReceiver<TContractState> {
+    /// Receives and processes LayerZero messages from other chains
+    /// This is the main entry point for incoming cross-chain messages
+    ///
+    /// # Arguments
+    ///
+    /// * `origin`: The origin information containing source endpoint ID and sender
+    /// * `guid`: Globally unique identifier for this message
+    /// * `message`: The actual message payload as bytes
+    /// * `executor`: The contract address of the executor handling this message
+    /// * `extra_data`: Additional data that may be used for message processing
+    fn lz_receive(
+        ref self: TContractState,
+        origin: Origin,
+        guid: Bytes32,
+        message: ByteArray,
+        executor: ContractAddress,
+        value: u256,
+        extra_data: ByteArray,
+    );
+
+    /// Checks if a path can be initialized for the given origin
+    /// This is used to determine if a new communication path should be allowed
+    ///
+    /// # Arguments
+    ///
+    /// * `origin`: The origin information to check for path initialization
+    ///
+    /// # Returns
+    ///
+    /// True if the path can be initialized, false otherwise
+    fn allow_initialize_path(self: @TContractState, origin: Origin) -> bool;
+
+    /// Gets the next nonce value for a specific source endpoint and sender
+    /// Nonces are used to ensure message ordering and prevent replay attacks
+    ///
+    /// # Arguments
+    ///
+    /// * `src_eid`: The source endpoint ID
+    /// * `sender`: The sender address as a 32-byte value
+    ///
+    /// # Returns
+    ///
+    /// The next nonce value as a u64
+    fn next_nonce(self: @TContractState, src_eid: u32, sender: Bytes32) -> u64;
+}