@layerzerolabs/protocol-stellar-v2 0.2.8

package/contracts/endpoint-v2/src/interfaces/layerzero_endpoint_v2.rs

@@ -0,0 +1,170 @@
+use soroban_sdk::{contractclient, contracttype, Address, Bytes, BytesN, Env};
+
+use super::{IMessageLibManager, IMessagingChannel, IMessagingComposer};
+
+/// Parameters for sending a cross-chain message.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct MessagingParams {
+    /// Destination endpoint ID (chain identifier).
+    pub dst_eid: u32,
+    /// Receiver address on the destination chain (32 bytes).
+    pub receiver: BytesN<32>,
+    /// The message payload to send.
+    pub message: Bytes,
+    /// Encoded executor and DVN options.
+    pub options: Bytes,
+    /// Whether to pay fees in ZRO token instead of native token.
+    pub pay_in_zro: bool,
+}
+
+/// Source message information identifying where a cross-chain message came from.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct Origin {
+    /// Source endpoint ID (chain identifier).
+    pub src_eid: u32,
+    /// Sender address on the source chain (32 bytes).
+    pub sender: BytesN<32>,
+    /// Nonce for this pathway.
+    pub nonce: u64,
+}
+
+/// Fee structure for cross-chain messaging.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct MessagingFee {
+    /// Fee paid in native token (XLM).
+    pub native_fee: i128,
+    /// Fee paid in ZRO token (LayerZero token).
+    pub zro_fee: i128,
+}
+
+/// Receipt returned after successfully sending a cross-chain message.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct MessagingReceipt {
+    /// Globally unique identifier for the message.
+    pub guid: BytesN<32>,
+    /// The outbound nonce for this pathway.
+    pub nonce: u64,
+    /// The fees charged for sending the message.
+    pub fee: MessagingFee,
+}
+
+/// The main LayerZero Endpoint V2 interface for cross-chain messaging.
+#[contractclient(name = "LayerZeroEndpointV2Client")]
+pub trait ILayerZeroEndpointV2: IMessageLibManager + IMessagingChannel + IMessagingComposer {
+    /// Quotes the messaging fee for sending a cross-chain message.
+    ///
+    /// # Arguments
+    /// * `sender` - The sender OApp address
+    /// * `params` - The messaging parameters (destination, receiver, message, options)
+    ///
+    /// # Returns
+    /// `MessagingFee` containing estimated native and ZRO fees
+    fn quote(env: &Env, sender: &Address, params: &MessagingParams) -> MessagingFee;
+
+    /// Sends a cross-chain message to a destination endpoint.
+    ///
+    /// # Arguments
+    /// * `sender` - The sender OApp address, must provide authorization
+    /// * `params` - The messaging parameters (destination, receiver, message, options)
+    /// * `refund_address` - The address to receive any excess fee refunds
+    ///
+    /// # Returns
+    /// `MessagingReceipt` containing the message GUID, nonce, and fees paid
+    fn send(env: &Env, sender: &Address, params: &MessagingParams, refund_address: &Address) -> MessagingReceipt;
+
+    /// Verifies an inbound cross-chain message from a receive library.
+    ///
+    /// # Arguments
+    /// * `receive_lib` - The receive library address, must provide authorization
+    /// * `origin` - The origin information (source EID, sender, nonce)
+    /// * `receiver` - The OApp address receiving the message
+    /// * `payload_hash` - The hash of the message payload
+    fn verify(env: &Env, receive_lib: &Address, origin: &Origin, receiver: &Address, payload_hash: &BytesN<32>);
+
+    /// Checks if a message can be verified for the given origin and receiver.
+    ///
+    /// # Arguments
+    /// * `origin` - The origin of the message
+    /// * `receiver` - The OApp address
+    ///
+    /// # Returns
+    /// `true` if the message can be verified, `false` otherwise
+    fn verifiable(env: &Env, origin: &Origin, receiver: &Address) -> bool;
+
+    /// Checks if a messaging path is initializable for the given origin and receiver.
+    ///
+    /// # Arguments
+    /// * `origin` - The origin of the message
+    /// * `receiver` - The OApp address
+    ///
+    /// # Returns
+    /// `true` if the path can be initialized, `false` otherwise
+    fn initializable(env: &Env, origin: &Origin, receiver: &Address) -> bool;
+
+    /// Clears a verified message from the endpoint (PULL mode) by the OApp.
+    ///
+    /// # Arguments
+    /// * `caller` - The caller address, must be the OApp or its delegate
+    /// * `origin` - The origin of the message
+    /// * `receiver` - The OApp address receiving the message
+    /// * `guid` - The GUID of the message
+    /// * `message` - The message content
+    fn clear(env: &Env, caller: &Address, origin: &Origin, receiver: &Address, guid: &BytesN<32>, message: &Bytes);
+
+    /// Emits an alert event when `lz_receive` execution fails.
+    ///
+    /// # Arguments
+    /// * `executor` - The executor address, must provide authorization
+    /// * `origin` - The origin of the message
+    /// * `receiver` - The OApp address
+    /// * `guid` - The message GUID
+    /// * `gas` - The gas provided for execution
+    /// * `value` - The value provided for execution
+    /// * `message` - The message content
+    /// * `extra_data` - Additional data for execution
+    /// * `reason` - The failure reason
+    fn lz_receive_alert(
+        env: &Env,
+        executor: &Address,
+        origin: &Origin,
+        receiver: &Address,
+        guid: &BytesN<32>,
+        gas: i128,
+        value: i128,
+        message: &Bytes,
+        extra_data: &Bytes,
+        reason: &Bytes,
+    );
+
+    /// Returns the endpoint ID.
+    fn eid(env: &Env) -> u32;
+
+    /// Returns the native token address used for fee payments.
+    fn native_token(env: &Env) -> Address;
+
+    /// Sets the ZRO token address for fee payments.
+    ///
+    /// # Arguments
+    /// * `zro` - The ZRO token contract address
+    fn set_zro(env: &Env, zro: &Address);
+
+    /// Returns the ZRO token address if set.
+    fn zro(env: &Env) -> Option<Address>;
+
+    /// Sets or removes a delegate address for an OApp.
+    ///
+    /// # Arguments
+    /// * `oapp` - The OApp address, must provide authorization
+    /// * `new_delegate` - The delegate address, or `None` to remove
+    fn set_delegate(env: &Env, oapp: &Address, new_delegate: &Option<Address>);
+
+    /// Returns the delegate address for an OApp if set.
+    ///
+    /// # Arguments
+    /// * `oapp` - The OApp address
+    fn delegate(env: &Env, oapp: &Address) -> Option<Address>;
+}

package/contracts/endpoint-v2/src/interfaces/layerzero_receiver.rs

@@ -0,0 +1,43 @@
+use soroban_sdk::{contractclient, Address, Bytes, BytesN, Env};
+
+use crate::Origin;
+
+/// Interface for OApps that can receive cross-chain messages.
+#[contractclient(name = "LayerZeroReceiverClient")]
+pub trait ILayerZeroReceiver {
+    /// Checks if a messaging path can be initialized for the given origin.
+    ///
+    /// # Arguments
+    /// * `origin` - The origin of the message
+    ///
+    /// # Returns
+    /// True if the path can be initialized, false otherwise
+    fn allow_initialize_path(env: &Env, origin: &Origin) -> bool;
+
+    /// Returns the next expected nonce for ordered message delivery.
+    /// 0 means there is NO nonce ordered enforcement.
+    ///
+    /// # Arguments
+    /// * `src_eid` - The source endpoint ID
+    /// * `sender` - The sender OApp address
+    fn next_nonce(env: &Env, src_eid: u32, sender: &BytesN<32>) -> u64;
+
+    /// Receives and processes a cross-chain message.
+    ///
+    /// # Arguments
+    /// * `executor` - The executor address delivering the message
+    /// * `origin` - The origin information (source EID, sender, nonce)
+    /// * `guid` - The message GUID
+    /// * `message` - The message content
+    /// * `extra_data` - Additional executor-provided data (untrusted)
+    /// * `value` - The native token value sent with the message
+    fn lz_receive(
+        env: &Env,
+        executor: &Address,
+        origin: &Origin,
+        guid: &BytesN<32>,
+        message: &Bytes,
+        extra_data: &Bytes,
+        value: i128,
+    );
+}

package/contracts/endpoint-v2/src/interfaces/message_lib.rs

@@ -0,0 +1,62 @@
+use soroban_sdk::{contractclient, contracttype, Address, Bytes, Env, Vec};
+
+use crate::SetConfigParam;
+
+/// Type of message library indicating supported operations.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[repr(u8)]
+pub enum MessageLibType {
+    /// Supports only sending messages.
+    Send,
+    /// Supports only receiving messages.
+    Receive,
+    /// Supports both sending and receiving messages.
+    SendAndReceive,
+}
+
+/// Version information for a message library.
+///
+/// Note: `minor` and `endpoint_version` use `u32` instead of `u8` because Stellar does not
+/// support `u8` types in contract interface functions.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct MessageLibVersion {
+    /// Major version number.
+    pub major: u64,
+    /// Minor version number (should not exceed u8::MAX = 255).
+    pub minor: u32,
+    /// Endpoint version (should not exceed u8::MAX = 255).
+    pub endpoint_version: u32,
+}
+
+/// Interface for message libraries that handle cross-chain message verification and delivery.
+#[contractclient(name = "MessageLibClient")]
+pub trait IMessageLib {
+    /// Sets the configuration for an OApp by the Endpoint.
+    ///
+    /// # Arguments
+    /// * `oapp` - The OApp address
+    /// * `params` - Library-specific configuration parameters (e.g., DVN configs, executor configs)
+    fn set_config(env: &Env, oapp: &Address, params: &Vec<SetConfigParam>);
+
+    /// Returns the configuration for a specific endpoint ID and config type.
+    ///
+    /// # Arguments
+    /// * `eid` - The endpoint ID
+    /// * `oapp` - The OApp address
+    /// * `config_type` - The type of configuration
+    fn get_config(env: &Env, eid: u32, oapp: &Address, config_type: u32) -> Bytes;
+
+    /// Checks if an endpoint ID is supported by this library.
+    ///
+    /// # Arguments
+    /// * `eid` - The endpoint ID
+    fn is_supported_eid(env: &Env, eid: u32) -> bool;
+
+    /// Returns the version information of this library.
+    fn version(env: &Env) -> MessageLibVersion;
+
+    /// Returns the type of this message library.
+    fn message_lib_type(env: &Env) -> MessageLibType;
+}

package/contracts/endpoint-v2/src/interfaces/message_lib_manager.rs

@@ -0,0 +1,220 @@
+use soroban_sdk::{contractclient, contracttype, Address, Bytes, Env, Vec};
+
+/// Timeout configuration for receive library transitions.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct Timeout {
+    /// The new library address to transition to.
+    pub lib: Address,
+    /// Unix timestamp when the timeout expires.
+    pub expiry: u64,
+}
+
+impl Timeout {
+    /// Checks if the timeout has expired.
+    pub fn is_expired(&self, env: &Env) -> bool {
+        self.expiry <= env.ledger().timestamp()
+    }
+
+    /// Checks if the timeout is valid for the given library (matches and not expired).
+    pub fn is_valid_for(&self, env: &Env, lib: &Address) -> bool {
+        &self.lib == lib && !self.is_expired(env)
+    }
+}
+
+/// Parameters for setting message library configuration.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SetConfigParam {
+    /// The endpoint ID this config applies to.
+    pub eid: u32,
+    /// The type of configuration (e.g., executor, ULN).
+    pub config_type: u32,
+    /// XDR-encoded configuration data.
+    pub config: Bytes,
+}
+
+/// Resolved library information with default status.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ResolvedLibrary {
+    /// The resolved library address.
+    pub lib: Address,
+    /// Whether this is the default library (true) or OApp-specific (false).
+    pub is_default: bool,
+}
+
+/// EndpointV2's Interface for managing message libraries.
+#[contractclient(name = "MessageLibManagerClient")]
+pub trait IMessageLibManager {
+    /// Registers a new message library with the endpoint.
+    ///
+    /// # Arguments
+    /// * `new_lib` - The address of the message library to register
+    fn register_library(env: &Env, new_lib: &Address);
+
+    /// Checks if a message library is registered.
+    ///
+    /// # Arguments
+    /// * `lib` - The address of the message library to check
+    fn is_registered_library(env: &Env, lib: &Address) -> bool;
+
+    /// Returns the index of a message library.
+    ///
+    /// # Arguments
+    /// * `lib` - The address of the message library to check
+    ///
+    /// # Returns
+    /// * `Option<u32>` - The index of the message library, or `None` if the library is not registered
+    fn get_library_index(env: &Env, lib: &Address) -> Option<u32>;
+
+    /// Returns a list of registered message libraries within the specified range.
+    ///
+    /// # Arguments
+    /// * `start` - The starting index
+    /// * `max_count` - The maximum number of libraries to return
+    fn get_registered_libraries(env: &Env, start: u32, max_count: u32) -> Vec<Address>;
+
+    /// Returns the number of registered message libraries.
+    fn registered_libraries_count(env: &Env) -> u32;
+
+    /// Sets the default send library for a destination endpoint.
+    ///
+    /// # Arguments
+    /// * `dst_eid` - The destination endpoint ID
+    /// * `new_lib` - The library address to set as default
+    fn set_default_send_library(env: &Env, dst_eid: u32, new_lib: &Address);
+
+    /// Returns the default send library for a destination endpoint.
+    ///
+    /// # Arguments
+    /// * `dst_eid` - The destination endpoint ID
+    fn default_send_library(env: &Env, dst_eid: u32) -> Option<Address>;
+
+    /// Sets the default receive library for a source endpoint.
+    ///
+    /// # Arguments
+    /// * `src_eid` - The source endpoint ID
+    /// * `new_lib` - The library address to set as default
+    /// * `grace_period` - Time in seconds during which the old library remains valid
+    fn set_default_receive_library(env: &Env, src_eid: u32, new_lib: &Address, grace_period: u64);
+
+    /// Returns the default receive library for a source endpoint.
+    ///
+    /// # Arguments
+    /// * `src_eid` - The source endpoint ID
+    fn default_receive_library(env: &Env, src_eid: u32) -> Option<Address>;
+
+    /// Sets or removes the default receive library timeout for a source endpoint.
+    ///
+    /// This function provides the same functionality as `setDefaultReceiveLibraryTimeout` on EVM.
+    /// The function name has been shortened to `set_default_receive_lib_timeout` due to Stellar's
+    /// naming constraints.
+    ///
+    /// # Arguments
+    /// * `src_eid` - The source endpoint ID
+    /// * `timeout` - The timeout configuration, or `None` to remove it
+    fn set_default_receive_lib_timeout(env: &Env, src_eid: u32, timeout: &Option<Timeout>);
+
+    /// Returns the default receive library timeout for a source endpoint.
+    ///
+    /// # Arguments
+    /// * `src_eid` - The source endpoint ID
+    fn default_receive_library_timeout(env: &Env, src_eid: u32) -> Option<Timeout>;
+
+    /// Checks if an endpoint ID is supported (both send and receive libraries are set).
+    ///
+    /// # Arguments
+    /// * `eid` - The endpoint ID
+    fn is_supported_eid(env: &Env, eid: u32) -> bool;
+
+    /// Checks if a receive library is valid for an OApp and source endpoint.
+    ///
+    /// # Arguments
+    /// * `receiver` - The receiver OApp address
+    /// * `src_eid` - The source endpoint ID
+    /// * `lib` - The library address to check
+    fn is_valid_receive_library(env: &Env, receiver: &Address, src_eid: u32, lib: &Address) -> bool;
+
+    // === OApp Control Functions ===
+
+    /// Sets or removes a custom send library for an OApp.
+    ///
+    /// # Arguments
+    /// * `caller` - The caller address, must be the OApp or its delegate
+    /// * `sender` - The receiver OApp address
+    /// * `dst_eid` - The destination endpoint ID
+    /// * `new_lib` - The library address, or `None` to use the default
+    fn set_send_library(env: &Env, caller: &Address, sender: &Address, dst_eid: u32, new_lib: &Option<Address>);
+
+    /// Returns the effective send library for an OApp and destination endpoint.
+    ///
+    /// # Arguments
+    /// * `sender` - The receiver OApp address
+    /// * `dst_eid` - The destination endpoint ID
+    fn get_send_library(env: &Env, sender: &Address, dst_eid: u32) -> ResolvedLibrary;
+
+    /// Sets or removes a custom receive library for an OApp.
+    ///
+    /// # Arguments
+    /// * `caller` - The caller address, must be the OApp or its delegate
+    /// * `receiver` - The receiver OApp address
+    /// * `src_eid` - The source endpoint ID
+    /// * `new_lib` - The library address, or `None` to use the default
+    /// * `grace_period` - Time in seconds during which the old library remains valid
+    fn set_receive_library(
+        env: &Env,
+        caller: &Address,
+        receiver: &Address,
+        src_eid: u32,
+        new_lib: &Option<Address>,
+        grace_period: u64,
+    );
+
+    /// Returns the effective receive library for an OApp and source endpoint.
+    ///
+    /// # Arguments
+    /// * `receiver` - The receiver OApp address
+    /// * `src_eid` - The source endpoint ID
+    fn get_receive_library(env: &Env, receiver: &Address, src_eid: u32) -> ResolvedLibrary;
+
+    /// Sets or removes the receive library timeout for an OApp.
+    ///
+    /// # Arguments
+    /// * `caller` - The caller address, must be the OApp or its delegate
+    /// * `receiver` - The receiver OApp address
+    /// * `src_eid` - The source endpoint ID
+    /// * `timeout` - The timeout configuration, or `None` to remove
+    fn set_receive_library_timeout(
+        env: &Env,
+        caller: &Address,
+        receiver: &Address,
+        src_eid: u32,
+        timeout: &Option<Timeout>,
+    );
+
+    /// Returns the receive library timeout for an OApp and source endpoint.
+    ///
+    /// # Arguments
+    /// * `receiver` - The receiver OApp address
+    /// * `src_eid` - The source endpoint ID
+    fn receive_library_timeout(env: &Env, receiver: &Address, src_eid: u32) -> Option<Timeout>;
+
+    /// Sets the configuration for a message library.
+    ///
+    /// # Arguments
+    /// * `caller` - The caller address, must be the OApp or its delegate
+    /// * `oapp` - The OApp address
+    /// * `lib` - The message library address
+    /// * `params` - The configuration parameters
+    fn set_config(env: &Env, caller: &Address, oapp: &Address, lib: &Address, params: &Vec<SetConfigParam>);
+
+    /// Returns the configuration for a message library.
+    ///
+    /// # Arguments
+    /// * `oapp` - The OApp address
+    /// * `lib` - The message library address
+    /// * `eid` - The endpoint ID
+    /// * `config_type` - The type of configuration
+    fn get_config(env: &Env, oapp: &Address, lib: &Address, eid: u32, config_type: u32) -> Bytes;
+}

package/contracts/endpoint-v2/src/interfaces/messaging_channel.rs

@@ -0,0 +1,121 @@
+use soroban_sdk::{contractclient, Address, BytesN, Env};
+
+/// EndpointV2's Interface for managing messaging channels, nonces, and payload hashes.
+#[contractclient(name = "MessagingChannelClient")]
+pub trait IMessagingChannel {
+    /// Skips the next expected inbound nonce without verifying.
+    ///
+    /// Used to handle messages that should be bypassed (e.g., due to precrime alerts).
+    ///
+    /// # Arguments
+    /// * `caller` - The caller address, must be the OApp or its delegate
+    /// * `receiver` - The receiver OApp address
+    /// * `src_eid` - The source endpoint ID
+    /// * `sender` - The sender address on the source chain
+    /// * `nonce` - The nonce to skip (must be the next expected nonce)
+    fn skip(env: &Env, caller: &Address, receiver: &Address, src_eid: u32, sender: &BytesN<32>, nonce: u64);
+
+    /// Marks a verified message as nil, preventing execution until re-verified.
+    /// The message can be re-verified later by calling `verify` again.
+    /// A non-verified nonce can be nilified by passing `None` for `payload_hash`.
+    ///
+    /// # Arguments
+    /// * `caller` - The caller address, must be the OApp or its delegate
+    /// * `receiver` - The receiver OApp address
+    /// * `src_eid` - The source endpoint ID
+    /// * `sender` - The sender address on the source chain
+    /// * `nonce` - The nonce of the message to nilify
+    /// * `payload_hash` - The payload hash (must match the stored hash), or `None` for a non-verified nonce
+    fn nilify(
+        env: &Env,
+        caller: &Address,
+        receiver: &Address,
+        src_eid: u32,
+        sender: &BytesN<32>,
+        nonce: u64,
+        payload_hash: &Option<BytesN<32>>,
+    );
+
+    /// Marks a nonce as permanently unexecutable and un-verifiable.
+    /// The nonce can never be re-verified or executed after burning.
+    ///
+    /// # Arguments
+    /// * `caller` - The caller address, must be the OApp or its delegate
+    /// * `receiver` - The receiver OApp address
+    /// * `src_eid` - The source endpoint ID
+    /// * `sender` - The sender OApp address on the source chain
+    /// * `nonce` - The nonce to burn
+    /// * `payload_hash` - The payload hash (must match the stored hash)
+    fn burn(
+        env: &Env,
+        caller: &Address,
+        receiver: &Address,
+        src_eid: u32,
+        sender: &BytesN<32>,
+        nonce: u64,
+        payload_hash: &BytesN<32>,
+    );
+
+    /// Generates the next GUID for an outbound packet.
+    ///
+    /// # Arguments
+    /// * `sender` - The sender OApp address
+    /// * `dst_eid` - The destination endpoint ID
+    /// * `receiver` - The receiver OApp address on the destination chain
+    ///
+    /// # Returns
+    /// The next GUID computed from nonce, source EID, sender, destination EID, and receiver
+    fn next_guid(env: &Env, sender: &Address, dst_eid: u32, receiver: &BytesN<32>) -> BytesN<32>;
+
+    /// Returns the current outbound nonce for a specific path.
+    ///
+    /// # Arguments
+    /// * `sender` - The sender OApp address
+    /// * `dst_eid` - The destination endpoint ID
+    /// * `receiver` - The receiver OApp address on the destination chain
+    ///
+    /// # Returns
+    /// The current outbound nonce (0 if no messages sent yet)
+    fn outbound_nonce(env: &Env, sender: &Address, dst_eid: u32, receiver: &BytesN<32>) -> u64;
+
+    /// Returns the max index of the longest gapless sequence of verified nonces.
+    /// Example: `[1,2,3,4,6,7] => 4`, `[1,2,6,8,10] => 2`
+    ///
+    /// # Arguments
+    /// * `receiver` - The receiver OApp address
+    /// * `src_eid` - The source endpoint ID
+    /// * `sender` - The sender address on the source chain
+    ///
+    /// # Returns
+    /// The highest nonce in the gapless sequence starting from lazy_inbound_nonce
+    fn inbound_nonce(env: &Env, receiver: &Address, src_eid: u32, sender: &BytesN<32>) -> u64;
+
+    /// Returns the lazy inbound nonce (last checkpoint) for a specific path.
+    ///
+    /// # Arguments
+    /// * `receiver` - The receiver OApp address
+    /// * `src_eid` - The source endpoint ID
+    /// * `sender` - The sender OApp address on the source chain
+    ///
+    /// # Returns
+    /// The lazy inbound nonce, updated when messages are cleared/executed
+    fn lazy_inbound_nonce(env: &Env, receiver: &Address, src_eid: u32, sender: &BytesN<32>) -> u64;
+
+    /// Returns the payload hash for a specific inbound nonce.
+    ///
+    /// # Arguments
+    /// * `receiver` - The receiver OApp address
+    /// * `src_eid` - The source endpoint ID
+    /// * `sender` - The sender OApp address on the source chain
+    /// * `nonce` - The nonce to query
+    ///
+    /// # Returns
+    /// The payload hash if verified, `None` otherwise
+    fn inbound_payload_hash(
+        env: &Env,
+        receiver: &Address,
+        src_eid: u32,
+        sender: &BytesN<32>,
+        nonce: u64,
+    ) -> Option<BytesN<32>>;
+}

package/contracts/endpoint-v2/src/interfaces/messaging_composer.rs

@@ -0,0 +1,63 @@
+use soroban_sdk::{contractclient, Address, Bytes, BytesN, Env};
+
+/// EndpointV2's Interface for managing composed messages between OApps and composers.
+#[contractclient(name = "MessagingComposerClient")]
+pub trait IMessagingComposer {
+    /// Sends a composed message from an OApp to a composer.
+    /// The OApp can send compose to multiple composers with the same GUID.
+    ///
+    /// # Arguments
+    /// * `from` - The sender OApp address, must provide authorization
+    /// * `to` - The composer address that will receive the message
+    /// * `guid` - The message GUID
+    /// * `index` - The compose message index
+    /// * `message` - The composed message content
+    fn send_compose(env: &Env, from: &Address, to: &Address, guid: &BytesN<32>, index: u32, message: &Bytes);
+
+    /// Clears a composed message after execution by the composer.
+    /// This is PULL mode - the composer calls this after processing the message.
+    ///
+    /// # Arguments
+    /// * `composer` - The composer address, must provide authorization
+    /// * `from` - The sender OApp address
+    /// * `guid` - The message GUID
+    /// * `index` - The compose message index
+    /// * `message` - The composed message content (must match stored hash)
+    fn clear_compose(env: &Env, composer: &Address, from: &Address, guid: &BytesN<32>, index: u32, message: &Bytes);
+
+    /// Emits an alert event when `lz_compose` execution fails.
+    ///
+    /// # Arguments
+    /// * `executor` - The executor address, must provide authorization
+    /// * `from` - The sender OApp address
+    /// * `to` - The composer address
+    /// * `guid` - The message GUID
+    /// * `index` - The compose message index
+    /// * `gas` - The gas provided for execution
+    /// * `value` - The value provided for execution
+    /// * `message` - The composed message content
+    /// * `extra_data` - Additional data for execution
+    /// * `reason` - The failure reason
+    fn lz_compose_alert(
+        env: &Env,
+        executor: &Address,
+        from: &Address,
+        to: &Address,
+        guid: &BytesN<32>,
+        index: u32,
+        gas: i128, // TODO: should rename to fee cuz there's no gas in stellar
+        value: i128,
+        message: &Bytes,
+        extra_data: &Bytes,
+        reason: &Bytes,
+    );
+
+    /// Returns the stored hash for a composed message.
+    ///
+    /// # Arguments
+    /// * `from` - The sender OApp address
+    /// * `to` - The composer address
+    /// * `guid` - The message GUID
+    /// * `index` - The compose message index
+    fn compose_queue(env: &Env, from: &Address, to: &Address, guid: &BytesN<32>, index: u32) -> Option<BytesN<32>>;
+}