@layerzerolabs/protocol-starknet-v2 0.0.34

package/layerzero/src/endpoint/message_lib_manager/errors.cairo

@@ -0,0 +1,95 @@
+//! Message lib manager errors
+
+use lz_utils::error::{Error, format_error};
+
+#[derive(Drop)]
+pub enum MessageLibManagerError {
+    /// Triggered when attempting to register a message library that is already registered.
+    AlreadyRegistered,
+    /// Triggered when the default send library is required but not set.
+    DefaultSendLibUnavailable,
+    /// Triggered when the default receive library is required but not set.
+    DefaultReceiveLibUnavailable,
+    /// Triggered when an invalid expiry value is provided.
+    InvalidExpiry,
+    /// Triggered when a default library is used where a non-default library is required.
+    OnlyNonDefaultLib,
+    /// Triggered when a library that is not a receive library is used in a receive-only context.
+    OnlyReceiveLib,
+    /// Triggered when an unregistered library is used.
+    OnlyRegisteredLib,
+    /// Triggered when a library that is not registered or a default library is used.
+    OnlyRegisteredOrDefaultLib,
+    /// Triggered when a library that is not a send library is used in a send-only context.
+    OnlySendLib,
+    /// Triggered when a new value is the same as the current value.
+    SameValue,
+    /// Triggered when an unsupported endpoint ID is used.
+    UnsupportedEid,
+}
+
+impl ErrorNameImpl of Error<MessageLibManagerError> {
+    fn prefix() -> ByteArray {
+        "LZ_MESSAGE_LIB_MANAGER"
+    }
+
+    fn name(self: MessageLibManagerError) -> ByteArray {
+        match self {
+            MessageLibManagerError::AlreadyRegistered => "ALREADY_REGISTERED",
+            MessageLibManagerError::DefaultSendLibUnavailable => "DEFAULT_SEND_LIB_UNAVAILABLE",
+            MessageLibManagerError::DefaultReceiveLibUnavailable => "DEFAULT_RECEIVE_LIB_UNAVAILABLE",
+            MessageLibManagerError::InvalidExpiry => "INVALID_EXPIRY",
+            MessageLibManagerError::OnlyNonDefaultLib => "ONLY_NON_DEFAULT_LIB",
+            MessageLibManagerError::OnlyReceiveLib => "ONLY_RECEIVE_LIB",
+            MessageLibManagerError::OnlyRegisteredLib => "ONLY_REGISTERED_LIB",
+            MessageLibManagerError::OnlyRegisteredOrDefaultLib => "ONLY_REGISTERED_OR_DEFAULT_LIB",
+            MessageLibManagerError::OnlySendLib => "ONLY_SEND_LIB",
+            MessageLibManagerError::SameValue => "SAME_VALUE",
+            MessageLibManagerError::UnsupportedEid => "UNSUPPORTED_EID",
+        }
+    }
+}
+
+pub fn err_already_registered() -> ByteArray {
+    format_error(MessageLibManagerError::AlreadyRegistered, "")
+}
+
+pub fn err_default_send_lib_unavailable() -> ByteArray {
+    format_error(MessageLibManagerError::DefaultSendLibUnavailable, "")
+}
+
+pub fn err_default_receive_lib_unavailable() -> ByteArray {
+    format_error(MessageLibManagerError::DefaultReceiveLibUnavailable, "")
+}
+
+pub fn err_invalid_expiry() -> ByteArray {
+    format_error(MessageLibManagerError::InvalidExpiry, "")
+}
+
+pub fn err_only_non_default_lib() -> ByteArray {
+    format_error(MessageLibManagerError::OnlyNonDefaultLib, "")
+}
+
+pub fn err_only_receive_lib() -> ByteArray {
+    format_error(MessageLibManagerError::OnlyReceiveLib, "")
+}
+
+pub fn err_only_registered_lib() -> ByteArray {
+    format_error(MessageLibManagerError::OnlyRegisteredLib, "")
+}
+
+pub fn err_only_registered_or_default_lib() -> ByteArray {
+    format_error(MessageLibManagerError::OnlyRegisteredOrDefaultLib, "")
+}
+
+pub fn err_only_send_lib() -> ByteArray {
+    format_error(MessageLibManagerError::OnlySendLib, "")
+}
+
+pub fn err_same_value() -> ByteArray {
+    format_error(MessageLibManagerError::SameValue, "")
+}
+
+pub fn err_unsupported_eid(eid: u32) -> ByteArray {
+    format_error(MessageLibManagerError::UnsupportedEid, format!("EID: {}", eid))
+}

package/layerzero/src/endpoint/message_lib_manager/events.cairo

@@ -0,0 +1,90 @@
+//! Message lib manager events
+
+use starknet::ContractAddress;
+
+/// Emitted when a new message library is registered.
+#[derive(Drop, 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, 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, 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 a default send library is set for a specific EID.
+#[derive(Drop, starknet::Event)]
+pub struct DefaultSendLibrarySet {
+    /// The EID for which the default send library is set.
+    #[key]
+    pub eid: u32,
+    /// The address of the default send library.
+    #[key]
+    pub library: ContractAddress,
+}
+
+/// Emitted when a default receive library is set for a specific EID.
+#[derive(Drop, starknet::Event)]
+pub struct DefaultReceiveLibrarySet {
+    /// The EID for which the default receive library is set.
+    #[key]
+    pub eid: u32,
+    /// The address of the default receive library.
+    #[key]
+    pub library: ContractAddress,
+}
+
+/// Emitted when a timeout is set for a receive library.
+#[derive(Drop, starknet::Event)]
+pub struct ReceiveLibraryTimeoutSet {
+    /// The OApp's address.
+    #[key]
+    pub oapp: ContractAddress,
+    /// The EID for which the timeout is set.
+    #[key]
+    pub eid: u32,
+    /// The address of the receive library.
+    #[key]
+    pub library: ContractAddress,
+    /// The expiry timestamp for the timeout.
+    pub expiry: u64,
+}
+
+/// Emitted when a timeout is set for a default receive library.
+#[derive(Drop, starknet::Event)]
+pub struct DefaultReceiveLibraryTimeoutSet {
+    /// The EID for which the timeout is set.
+    #[key]
+    pub eid: u32,
+    /// The address of the default receive library.
+    #[key]
+    pub library: ContractAddress,
+    /// The expiry timestamp for the timeout.
+    pub expiry: u64,
+}

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

@@ -0,0 +1,449 @@
+use starknet::ContractAddress;
+use crate::endpoint::message_lib_manager::structs::{GetLibraryResponse, Timeout};
+use crate::message_lib::structs::SetConfigParam;
+
+/// # `IMessageLibManager` Interface
+///
+/// The `IMessageLibManager` is responsible for managing the lifecycle and configuration of
+/// message libraries within the LayerZero protocol. It handles both default (system-wide)
+/// and custom (OApp-specific) library configurations for sending and receiving messages.
+///
+/// ## Key responsibilities
+/// - Library registration and validation
+/// - Default library management for the protocol
+/// - Per-OApp library configuration
+/// - Grace period management for library upgrades
+/// - Configuration delegation to message libraries
+#[starknet::interface]
+pub trait IMessageLibManager<TContractState> {
+    // ========================= Library Registration =========================
+
+    /// Register a new message library with the endpoint (owner only)
+    ///
+    /// Only registered libraries can be used as send/receive libraries or set as defaults.
+    /// The library must support the IMessageLib interface to be registered.
+    ///
+    /// # Arguments
+    /// * `lib` - The contract address of the message library to register
+    ///
+    /// # Panics
+    /// * If caller is not the owner
+    /// * If library is already registered
+    /// * If library doesn't implement the required interface
+    fn register_library(ref self: TContractState, lib: ContractAddress);
+
+    /// Get all registered message libraries
+    ///
+    /// Returns a list of all libraries that have been registered with the endpoint.
+    /// This includes both active libraries and any that may be deprecated but still
+    /// registered for backward compatibility.
+    ///
+    /// # Returns
+    /// * `Array<ContractAddress>` - Array of all registered library addresses
+    fn get_registered_libraries(self: @TContractState) -> Array<ContractAddress>;
+
+    /// Check if a library is registered
+    ///
+    /// Returns true if the library has been registered with the endpoint.
+    ///
+    /// # Arguments
+    /// * `lib` - The library address to check
+    ///
+    /// # Returns
+    /// * `bool` - True if the library is registered, false otherwise
+    fn is_registered_library(self: @TContractState, lib: ContractAddress) -> bool;
+
+    // ========================= Send Library Management =========================
+
+    /// Set the send library for the calling OApp and destination endpoint
+    ///
+    /// The send library is responsible for encoding and transmitting messages to the
+    /// destination chain. If not set, the OApp will use the default send library.
+    /// Only the OApp itself can set its send library.
+    ///
+    /// # Arguments
+    /// * `eid` - The destination endpoint ID
+    /// * `lib` - The message library address (or DEFAULT_LIB to use default)
+    ///
+    /// # Panics
+    /// * If library is not registered (unless DEFAULT_LIB)
+    /// * If library doesn't support sending
+    /// * If library doesn't support the specified endpoint
+    /// * If the same library is already set (no-op protection)
+    fn set_send_library(
+        ref self: TContractState, oapp: ContractAddress, eid: u32, lib: ContractAddress,
+    );
+
+    /// Get the send library for a specific sender and destination endpoint
+    ///
+    /// If the sender hasn't set a custom send library, this resolves to the default
+    /// send library configured by LayerZero. The library returned by this function
+    /// will be used to process outbound messages.
+    ///
+    /// # Arguments
+    /// * `sender` - The OApp address that wants to send messages
+    /// * `dst_eid` - The destination endpoint ID
+    ///
+    /// # Returns
+    /// * `ContractAddress` - The resolved send library address
+    ///
+    /// # Panics
+    /// * If no default send library is configured for the endpoint
+    fn get_send_library(
+        self: @TContractState, oapp: ContractAddress, dst_eid: u32,
+    ) -> GetLibraryResponse;
+
+    /// Get the raw send library for a specific sender and destination endpoint
+    ///
+    /// Returns the raw send library for the given sender and destination endpoint.
+    ///
+    /// # Arguments
+    /// * `sender` - The OApp address that wants to send messages
+    /// * `dst_eid` - The destination endpoint ID
+    ///
+    /// # Returns
+    /// * `ContractAddress` - The raw send library address
+    fn get_raw_send_library(
+        self: @TContractState, oapp: ContractAddress, dst_eid: u32,
+    ) -> ContractAddress;
+
+    /// Check if an OApp is using the default send library
+    ///
+    /// Returns true if the OApp hasn't set a custom send library for the given
+    /// destination, meaning it will use the protocol's default send library.
+    ///
+    /// # Arguments
+    /// * `sender` - The OApp address to check
+    /// * `dst_eid` - The destination endpoint ID
+    ///
+    /// # Returns
+    /// * `bool` - True if using default library, false if using custom library
+    fn is_default_send_library(self: @TContractState, oapp: ContractAddress, dst_eid: u32) -> bool;
+
+    /// Set the default send library for an endpoint (owner only)
+    ///
+    /// The default send library is used by OApps that haven't configured a custom
+    /// send library. This is a protocol-level configuration that affects all OApps.
+    ///
+    /// # Arguments
+    /// * `eid` - The destination endpoint ID
+    /// * `lib` - The message library address to set as default
+    ///
+    /// # Panics
+    /// * If caller is not the owner
+    /// * If library is not registered
+    /// * If library doesn't support sending
+    /// * If library doesn't support the specified endpoint
+    /// * If the same library is already set as default
+    fn set_default_send_library(ref self: TContractState, eid: u32, lib: ContractAddress);
+
+
+    /// Get the default send library for an endpoint
+    ///
+    /// Returns the default send library for the given endpoint.
+    ///
+    /// # Arguments
+    /// * `eid` - The destination endpoint ID
+    ///
+    /// # Returns
+    /// * `ContractAddress` - The default send library address
+    fn get_default_send_library(self: @TContractState, eid: u32) -> ContractAddress;
+
+    // ========================= Receive Library Management =========================
+
+    /// Set the receive library for the calling OApp and source endpoint
+    ///
+    /// The receive library is responsible for verifying and processing incoming messages
+    /// from the source chain. An optional grace period can be specified to allow the
+    /// old library to remain valid during the transition.
+    ///
+    /// # Arguments
+    /// * `eid` - The source endpoint ID
+    /// * `lib` - The message library address (or DEFAULT_LIB to use default)
+    /// * `grace_period` - Number of blocks to keep the old library valid (0 for immediate switch)
+    ///
+    /// # Panics
+    /// * If library is not registered (unless DEFAULT_LIB)
+    /// * If library doesn't support receiving
+    /// * If library doesn't support the specified endpoint
+    /// * If the same library is already set (no-op protection)
+    /// * If grace_period > 0 but either old or new library is DEFAULT_LIB
+    fn set_receive_library(
+        ref self: TContractState,
+        oapp: ContractAddress,
+        eid: u32,
+        lib: ContractAddress,
+        grace_period: u64,
+    );
+
+    /// Get the receive library for a specific receiver and source endpoint
+    ///
+    /// If the receiver hasn't set a custom receive library, this resolves to the default
+    /// receive library configured by LayerZero. The boolean indicates whether the
+    /// default library is being used.
+    ///
+    /// # Arguments
+    /// * `receiver` - The OApp address that will receive messages
+    /// * `src_eid` - The source endpoint ID
+    ///
+    /// # Returns
+    /// * `(ContractAddress, bool)` - Tuple of (library_address, is_using_default)
+    ///
+    /// # Panics
+    /// * If no default receive library is configured for the endpoint
+    fn get_receive_library(
+        self: @TContractState, oapp: ContractAddress, src_eid: u32,
+    ) -> GetLibraryResponse;
+
+    /// Get the raw receive library for a specific receiver and source endpoint
+    ///
+    /// Returns the raw receive library for the given receiver and source endpoint.
+    ///
+    /// # Arguments
+    /// * `receiver` - The OApp address that will receive messages
+    /// * `src_eid` - The source endpoint ID
+    ///
+    /// # Returns
+    /// * `Array<felt252>` - The raw receive library address
+    fn get_raw_receive_library(
+        self: @TContractState, oapp: ContractAddress, src_eid: u32,
+    ) -> ContractAddress;
+
+    /// Check if a receive library is valid for processing messages
+    ///
+    /// This validates whether the specified library can be used to verify messages
+    /// for the given receiver and source endpoint. It considers both the currently
+    /// configured library and any libraries in their grace period.
+    ///
+    /// # Arguments
+    /// * `receiver` - The OApp address that will receive messages
+    /// * `src_eid` - The source endpoint ID
+    /// * `lib_address` - The library address attempting to verify the message
+    ///
+    /// # Returns
+    /// * `bool` - True if the library is valid for verification, false otherwise
+    fn is_valid_receive_library(
+        self: @TContractState, oapp: ContractAddress, src_eid: u32, lib: ContractAddress,
+    ) -> bool;
+
+    /// Set the default receive library for an endpoint (owner only)
+    ///
+    /// The default receive library is used by OApps that haven't configured a custom
+    /// receive library. An optional grace period allows the old default library to
+    /// remain valid during the transition.
+    ///
+    /// # Arguments
+    /// * `eid` - The source endpoint ID
+    /// * `lib` - The message library address to set as default
+    /// * `grace_period` - Number of blocks to keep the old library valid (0 for immediate switch)
+    ///
+    /// # Panics
+    /// * If caller is not the owner
+    /// * If library is not registered
+    /// * If library doesn't support receiving
+    /// * If library doesn't support the specified endpoint
+    /// * If the same library is already set as default
+    fn set_default_receive_library(
+        ref self: TContractState, eid: u32, lib: ContractAddress, grace_period: u64,
+    );
+
+    /// Get the default receive library for an endpoint
+    ///
+    /// Returns the default receive library for the given endpoint.
+    ///
+    /// # Arguments
+    /// * `eid` - The source endpoint ID
+    ///
+    /// # Returns
+    /// * `ContractAddress` - The default receive library address
+    fn get_default_receive_library(self: @TContractState, eid: u32) -> ContractAddress;
+
+    /// Check if an OApp is using the default receive library
+    ///
+    /// Returns true if the OApp hasn't set a custom receive library for the given
+    /// source, meaning it will use the protocol's default receive library.
+    ///
+    /// # Arguments
+    fn is_default_receive_library(
+        self: @TContractState, oapp: ContractAddress, src_eid: u32,
+    ) -> bool;
+
+    /// Set a timeout for a receive library transition
+    ///
+    /// This allows fine-grained control over when libraries in grace period expire.
+    /// Can be used to extend, shorten, or remove grace periods for library transitions.
+    /// Only affects non-default library configurations.
+    ///
+    /// # Arguments
+    /// * `eid` - The source endpoint ID
+    /// * `lib` - The library address to set timeout for
+    /// * `expiry` - Block number when the library expires (0 to remove timeout)
+    ///
+    /// # Panics
+    /// * If library is not registered
+    /// * If library doesn't support receiving
+    /// * If library doesn't support the specified endpoint
+    /// * If OApp is using default library (can't set custom timeout)
+    /// * If expiry is not in the future (when setting non-zero expiry)
+    fn set_receive_library_timeout(
+        ref self: TContractState,
+        oapp: ContractAddress,
+        eid: u32,
+        lib: ContractAddress,
+        expiry: u64,
+    );
+
+    /// Get the timeout for a receive library
+    ///
+    /// Returns the timeout for the specified receive library.
+    ///
+    /// # Arguments
+    /// * `eid` - The source endpoint ID
+    /// * `lib` - The library address to get timeout for
+    ///
+    /// # Returns
+    /// * `Timeout` - The timeout for the specified library
+    fn get_receive_library_timeout(
+        self: @TContractState, oapp: ContractAddress, eid: u32, lib: ContractAddress,
+    ) -> Timeout;
+
+    /// Set a timeout for the default receive library (owner only)
+    ///
+    /// This controls the grace period for the protocol's default receive library.
+    /// Unlike the OApp-specific timeout, this affects all OApps using the default library.
+    ///
+    /// # Arguments
+    /// * `eid` - The source endpoint ID
+    /// * `lib` - The library address to set timeout for
+    /// * `expiry` - Block number when the library expires (0 to remove timeout)
+    ///
+    /// # Panics
+    /// * If caller is not the owner
+    /// * If library is not registered
+    /// * If library doesn't support receiving
+    /// * If library doesn't support the specified endpoint
+    /// * If expiry is not in the future (when setting non-zero expiry)
+    fn set_default_receive_library_timeout(
+        ref self: TContractState, eid: u32, lib: ContractAddress, expiry: u64,
+    );
+
+    /// Get the timeout for the default receive library
+    ///
+    /// Returns the timeout for the default receive library.
+    ///
+    /// # Arguments
+    /// * `eid` - The source endpoint ID
+    /// * `lib` - The library address to get timeout for
+    ///
+    /// # Returns
+    /// * `Timeout` - The timeout for the default library
+    fn get_default_receive_library_timeout(self: @TContractState, eid: u32) -> Timeout;
+
+    // ========================= Configuration Management =========================
+
+    /// Set send configuration for an OApp
+    ///
+    /// This function allows an OApp to set configuration parameters for its send library.
+    /// The configuration is specific to the message library and endpoint.
+    ///
+    /// # Arguments
+    /// * `oapp` - The OApp address setting configuration
+    /// * `lib` - The message library to set configuration for
+    /// * `params` - Array of configuration parameters to set
+    ///
+    /// # Panics
+    /// * If library is not registered
+    fn set_send_config(
+        ref self: TContractState,
+        oapp: ContractAddress,
+        lib: ContractAddress,
+        params: Array<SetConfigParam>,
+    );
+
+    /// Get send configuration from a message library
+    ///
+    /// This is a pass-through function that delegates configuration queries to the
+    /// specified message library. The configuration is OApp-specific and depends on
+    /// the library's implementation.
+    ///
+    /// Note: Configuration setting happens directly in the message library via setConfig.
+    ///
+    /// # Arguments
+    /// * `oapp` - The OApp address requesting configuration
+    /// * `lib` - The message library to query
+    /// * `eid` - The endpoint ID for the configuration
+    /// * `config_type` - The type of configuration being requested
+    ///
+    /// # Returns
+    /// * `Array<felt252>` - The encoded configuration data
+    ///
+    /// # Panics
+    /// * If library is not registered
+    fn get_send_config(
+        self: @TContractState,
+        oapp: ContractAddress,
+        lib: ContractAddress,
+        eid: u32,
+        config_type: u32,
+    ) -> Array<felt252>;
+
+    /// Set receive configuration for an OApp
+    ///
+    /// This function allows an OApp to set configuration parameters for its receive library.
+    /// The configuration is specific to the message library and endpoint.
+    ///
+    /// # Arguments
+    /// * `oapp` - The OApp address setting configuration
+    /// * `lib` - The message library to set configuration for
+    /// * `params` - Array of configuration parameters to set
+    ///
+    /// # Panics
+    /// * If library is not registered
+    fn set_receive_config(
+        ref self: TContractState,
+        oapp: ContractAddress,
+        lib: ContractAddress,
+        params: Array<SetConfigParam>,
+    );
+
+    /// Get receive configuration from a message library
+    ///
+    /// This is a pass-through function that delegates configuration queries to the
+    /// specified message library. The configuration is OApp-specific and depends on
+    /// the library's implementation.
+    ///
+    /// Note: Configuration setting happens directly in the message library via setConfig.
+    ///
+    /// # Arguments
+    /// * `oapp` - The OApp address requesting configuration
+    /// * `lib` - The message library to query
+    /// * `eid` - The endpoint ID for the configuration
+    /// * `config_type` - The type of configuration being requested
+    ///
+    /// # Returns
+    /// * `Array<felt252>` - The encoded configuration data
+    ///
+    /// # Panics
+    /// * If library is not registered
+    fn get_receive_config(
+        self: @TContractState,
+        oapp: ContractAddress,
+        lib: ContractAddress,
+        eid: u32,
+        config_type: u32,
+    ) -> Array<felt252>;
+
+    // ========================= Utility Functions =========================
+
+    /// Check if an endpoint is supported by the protocol
+    ///
+    /// An endpoint is considered supported if it has both default send and receive
+    /// libraries configured. This indicates that the endpoint is ready for general use.
+    ///
+    /// # Arguments
+    /// * `eid` - The endpoint ID to check
+    ///
+    /// # Returns
+    /// * `bool` - True if the endpoint has both default libraries configured
+    fn is_supported_eid(self: @TContractState, eid: u32) -> bool;
+}