@layerzerolabs/protocol-stellar-v2 0.2.8

package/contracts/endpoint-v2/src/endpoint_v2.rs

@@ -0,0 +1,305 @@
+use crate::{
+    constants::{
+        EMPTY_PAYLOAD_HASH_BYTES, MAX_COMPOSE_INDEX, NATIVE_TOKEN, NIL_PAYLOAD_HASH_BYTES, RECEIVED_MESSAGE_HASH_BYTES,
+        STELLAR_EID,
+    },
+    errors::EndpointError,
+    events::{
+        ComposeDelivered, ComposeSent, DefaultReceiveLibrarySet, DefaultReceiveLibraryTimeoutSet,
+        DefaultSendLibrarySet, DelegateSet, InboundNonceSkipped, LibraryRegistered, LzComposeAlert, LzReceiveAlert,
+        PacketBurnt, PacketDelivered, PacketNilified, PacketSent, PacketVerified, ReceiveLibrarySet,
+        ReceiveLibraryTimeoutSet, SendLibrarySet, ZROSet,
+    },
+    interfaces::{ILayerZeroEndpointV2, IMessageLibManager, IMessagingChannel, MessagingFee, MessagingReceipt, Origin},
+    storage::EndpointStorage,
+    util::{build_payload, compute_guid, keccak256},
+    FeeRecipient, FeesAndPacket, IMessagingComposer, LayerZeroReceiverClient, MessageLibClient, MessageLibType,
+    MessagingParams, OutboundPacket, ResolvedLibrary, SendLibClient, SetConfigParam, Timeout,
+};
+use common_macros::{only_owner, ttl_configurable};
+use soroban_sdk::{
+    assert_with_error, contract, contractimpl, token::TokenClient, vec, Address, Bytes, BytesN, Env, Vec,
+};
+use utils::option_ext::OptionExt;
+
+#[contract]
+#[ttl_configurable]
+pub struct EndpointV2;
+
+#[contractimpl]
+impl EndpointV2 {
+    pub fn __constructor(env: &Env, owner: &Address) {
+        Self::__init_owner(env, owner);
+    }
+
+    /// Recovers tokens sent to this contract by mistake.
+    ///
+    /// # Arguments
+    /// * `token` - The token address to recover
+    /// * `to` - The address to send the token to
+    /// * `amount` - The amount to send
+    #[only_owner]
+    pub fn recover_token(env: &Env, token: &Address, to: &Address, amount: i128) {
+        TokenClient::new(env, token).transfer(&env.current_contract_address(), to, &amount);
+    }
+}
+
+// ============================================================================
+// ILayerZeroEndpointV2 Implementation
+// ============================================================================
+
+#[contractimpl]
+impl ILayerZeroEndpointV2 for EndpointV2 {
+    /// Quotes the messaging fee for sending a cross-chain message.
+    fn quote(env: &Env, sender: &Address, params: &MessagingParams) -> MessagingFee {
+        assert_with_error!(env, !params.pay_in_zro || EndpointStorage::has_zro(env), EndpointError::ZROUnavailable);
+
+        let MessagingParams { dst_eid, receiver, message, options, pay_in_zro } = params;
+        let ResolvedLibrary { lib: send_lib, .. } = Self::get_send_library(env, sender, *dst_eid);
+
+        let nonce = Self::outbound_nonce(env, sender, *dst_eid, receiver) + 1;
+        let packet = Self::build_outbound_packet(env, sender, *dst_eid, receiver, message, nonce);
+
+        SendLibClient::new(env, &send_lib).quote(&packet, options, pay_in_zro)
+    }
+
+    /// Sends a cross-chain message to a destination endpoint.
+    ///
+    /// OApp sender needs to transfer the fees to the endpoint before sending the message
+    fn send(env: &Env, sender: &Address, params: &MessagingParams, refund_address: &Address) -> MessagingReceipt {
+        sender.require_auth();
+        assert_with_error!(env, !params.pay_in_zro || EndpointStorage::has_zro(env), EndpointError::ZROUnavailable);
+
+        let MessagingParams { dst_eid, receiver, message, options, pay_in_zro } = params;
+        let ResolvedLibrary { lib: send_library, .. } = Self::get_send_library(env, sender, *dst_eid);
+
+        // Send outbound packet
+        let nonce = Self::outbound(env, sender, *dst_eid, receiver);
+        let packet = Self::build_outbound_packet(env, sender, *dst_eid, receiver, message, nonce);
+
+        let FeesAndPacket { native_fee_recipients, zro_fee_recipients, encoded_packet } =
+            SendLibClient::new(env, &send_library).send(&packet, options, pay_in_zro);
+
+        // Pay and refund messaging fees
+        let fee =
+            Self::pay_messaging_fees(env, *pay_in_zro, &native_fee_recipients, &zro_fee_recipients, refund_address);
+
+        // Publish PacketSent event
+        PacketSent { encoded_packet, options: options.clone(), send_library }.publish(env);
+
+        MessagingReceipt { guid: packet.guid, nonce, fee }
+    }
+
+    /// Verifies an inbound cross-chain message from a configured receive library.
+    fn verify(env: &Env, receive_lib: &Address, origin: &Origin, receiver: &Address, payload_hash: &BytesN<32>) {
+        receive_lib.require_auth();
+        assert_with_error!(
+            env,
+            Self::is_valid_receive_library(env, receiver, origin.src_eid, receive_lib),
+            EndpointError::InvalidReceiveLibrary
+        );
+        assert_with_error!(env, Self::initializable(env, origin, receiver), EndpointError::PathNotInitializable);
+        assert_with_error!(env, Self::verifiable(env, origin, receiver), EndpointError::PathNotVerifiable);
+
+        Self::inbound(env, receiver, origin.src_eid, &origin.sender, origin.nonce, payload_hash);
+        PacketVerified { origin: origin.clone(), receiver: receiver.clone(), payload_hash: payload_hash.clone() }
+            .publish(env);
+    }
+
+    /// Clears a verified message from the endpoint.
+    ///
+    /// This is a PULL mode versus the PUSH mode of `lz_receive`.
+    fn clear(env: &Env, caller: &Address, origin: &Origin, receiver: &Address, guid: &BytesN<32>, message: &Bytes) {
+        Self::require_oapp_auth(env, caller, receiver);
+
+        let payload = build_payload(env, guid, message);
+        Self::clear_payload(env, receiver, origin.src_eid, &origin.sender, origin.nonce, &payload);
+        PacketDelivered { origin: origin.clone(), receiver: receiver.clone() }.publish(env);
+    }
+
+    /// Emits an alert event when `lz_receive` execution fails.
+    ///
+    /// Called by the executor to notify about failed message delivery attempts.
+    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,
+    ) {
+        executor.require_auth();
+        LzReceiveAlert {
+            receiver: receiver.clone(),
+            executor: executor.clone(),
+            origin: origin.clone(),
+            guid: guid.clone(),
+            gas,
+            value,
+            message: message.clone(),
+            extra_data: extra_data.clone(),
+            reason: reason.clone(),
+        }
+        .publish(env);
+    }
+
+    /// Sets the ZRO token address for fee payments.
+    #[only_owner]
+    fn set_zro(env: &Env, zro: &Address) {
+        EndpointStorage::set_zro(env, zro);
+        ZROSet { zro: zro.clone() }.publish(env);
+    }
+
+    /// Sets or removes a delegate address that can act on behalf of the OApp.
+    fn set_delegate(env: &Env, oapp: &Address, new_delegate: &Option<Address>) {
+        oapp.require_auth();
+        EndpointStorage::set_or_remove_delegate(env, oapp, new_delegate);
+        DelegateSet { oapp: oapp.clone(), delegate: new_delegate.clone() }.publish(env);
+    }
+
+    // === View Functions ===
+
+    /// Returns the endpoint ID.
+    fn eid(_env: &Env) -> u32 {
+        STELLAR_EID
+    }
+
+    /// Checks if a messaging path can be/has been initialized for the given origin and receiver.
+    fn initializable(env: &Env, origin: &Origin, receiver: &Address) -> bool {
+        let lazy_inbound_nonce = Self::lazy_inbound_nonce(env, receiver, origin.src_eid, &origin.sender);
+        lazy_inbound_nonce > 0 || LayerZeroReceiverClient::new(env, receiver).allow_initialize_path(origin)
+    }
+
+    /// Checks if a message can be verified for the given origin and receiver.
+    fn verifiable(env: &Env, origin: &Origin, receiver: &Address) -> bool {
+        let lazy_inbound_nonce = Self::lazy_inbound_nonce(env, receiver, origin.src_eid, &origin.sender);
+        origin.nonce > lazy_inbound_nonce
+            || EndpointStorage::has_inbound_payload_hash(env, receiver, origin.src_eid, &origin.sender, origin.nonce)
+    }
+
+    /// Returns the native token address used for fee payments.
+    fn native_token(env: &Env) -> Address {
+        Address::from_str(env, NATIVE_TOKEN)
+    }
+
+    /// Returns the ZRO token address if set.
+    fn zro(env: &Env) -> Option<Address> {
+        EndpointStorage::zro(env)
+    }
+
+    /// Returns the delegate address for an OApp if set.
+    fn delegate(env: &Env, oapp: &Address) -> Option<Address> {
+        EndpointStorage::delegate(env, oapp)
+    }
+}
+
+// ============================================================================
+// Internal Functions
+// ============================================================================
+
+impl EndpointV2 {
+    /// Builds an outbound packet with the given parameters.
+    fn build_outbound_packet(
+        env: &Env,
+        sender: &Address,
+        dst_eid: u32,
+        receiver: &BytesN<32>,
+        message: &Bytes,
+        nonce: u64,
+    ) -> OutboundPacket {
+        let src_eid = Self::eid(env);
+        let guid = compute_guid(env, nonce, src_eid, sender, dst_eid, receiver);
+        OutboundPacket {
+            nonce,
+            src_eid,
+            sender: sender.clone(),
+            dst_eid,
+            receiver: receiver.clone(),
+            guid,
+            message: message.clone(),
+        }
+    }
+
+    /// Requires authorization from either the OApp itself or its delegate.
+    pub(crate) fn require_oapp_auth(env: &Env, caller: &Address, oapp: &Address) {
+        assert_with_error!(
+            env,
+            caller == oapp || Self::delegate(env, oapp).as_ref() == Some(caller),
+            EndpointError::Unauthorized
+        );
+        caller.require_auth();
+    }
+
+    /// Distributes messaging fees to recipients and refunds any excess to the refund address.
+    ///
+    /// # Arguments
+    /// * `pay_in_zro` - Whether to pay in ZRO token
+    /// * `native_fee_recipients` - The recipients addresses and amounts of the native fees
+    /// * `zro_fee_recipients` - The recipients addresses and amounts of the ZRO fees
+    /// * `refund_address` - The address to receive any excess fee refunds
+    ///
+    /// # Returns
+    /// The total `MessagingFee` paid (native_fee + zro_fee)
+    pub(crate) fn pay_messaging_fees(
+        env: &Env,
+        pay_in_zro: bool,
+        native_fee_recipients: &Vec<FeeRecipient>,
+        zro_fee_recipients: &Vec<FeeRecipient>,
+        refund_address: &Address,
+    ) -> MessagingFee {
+        let this_contract = env.current_contract_address();
+        let mut fee_paid = MessagingFee { native_fee: 0, zro_fee: 0 };
+
+        // Pay native fees
+        let native_token_client = TokenClient::new(env, &Self::native_token(env));
+        let mut native_fee_supplied = native_token_client.balance(&this_contract);
+        native_fee_recipients.iter().filter(|r| r.amount > 0).for_each(|r| {
+            assert_with_error!(env, native_fee_supplied >= r.amount, EndpointError::InsufficientNativeFee);
+            native_token_client.transfer(&this_contract, &r.address, &r.amount);
+            native_fee_supplied -= r.amount;
+            fee_paid.native_fee += r.amount;
+        });
+        // Refund remaining native fees
+        if native_fee_supplied > 0 {
+            native_token_client.transfer(&this_contract, refund_address, &native_fee_supplied);
+        }
+
+        // Pay ZRO fees
+        if pay_in_zro {
+            let zro_addr = Self::zro(env).unwrap_or_panic(env, EndpointError::ZROUnavailable);
+            let zro_client = TokenClient::new(env, &zro_addr);
+
+            // If pay_in_zro is true, the supplied fee must be greater than 0 to prevent a race condition
+            // in which an OApp sending a message with ZRO token and the ZRO token is set to a new token between the tx
+            // being sent and the tx being mined. if the required zro fee is 0 and the old zro token would be
+            // locked in the contract instead of being refunded
+            let mut zro_fee_supplied = zro_client.balance(&this_contract);
+            assert_with_error!(env, zro_fee_supplied > 0, EndpointError::ZeroZROFee);
+
+            zro_fee_recipients.iter().filter(|r| r.amount > 0).for_each(|r| {
+                assert_with_error!(env, zro_fee_supplied >= r.amount, EndpointError::InsufficientZROFee);
+                zro_client.transfer(&this_contract, &r.address, &r.amount);
+                zro_fee_supplied -= r.amount;
+                fee_paid.zro_fee += r.amount;
+            });
+            // Refund remaining ZRO fees
+            if zro_fee_supplied > 0 {
+                zro_client.transfer(&this_contract, refund_address, &zro_fee_supplied);
+            }
+        }
+
+        fee_paid
+    }
+}
+
+// ============================================================================
+// Include Modules
+// ============================================================================
+
+include!("message_lib_manager.rs");
+include!("messaging_channel.rs");
+include!("messaging_composer.rs");

package/contracts/endpoint-v2/src/errors.rs

@@ -0,0 +1,29 @@
+use common_macros::contract_error;
+
+#[contract_error]
+pub enum EndpointError {
+    AlreadyRegistered,
+    ComposeExists,
+    ComposeNotFound,
+    DefaultReceiveLibUnavailable,
+    DefaultSendLibUnavailable,
+    InsufficientNativeFee,
+    InsufficientZROFee,
+    InvalidExpiry,
+    InvalidIndex,
+    InvalidNonce,
+    InvalidPayloadHash,
+    InvalidReceiveLibrary,
+    OnlyNonDefaultLib,
+    OnlyReceiveLib,
+    OnlyRegisteredLib,
+    OnlySendLib,
+    PathNotInitializable,
+    PathNotVerifiable,
+    PayloadHashNotFound,
+    SameValue,
+    Unauthorized,
+    UnsupportedEid,
+    ZeroZROFee,
+    ZROUnavailable,
+}

package/contracts/endpoint-v2/src/events.rs

@@ -0,0 +1,207 @@
+use crate::{Origin, Timeout};
+use common_macros::event;
+use soroban_sdk::{Address, Bytes, BytesN};
+
+// ============================================================================
+// EndpointV2 Events
+// ============================================================================
+
+#[event]
+pub struct PacketSent {
+    pub encoded_packet: Bytes,
+    pub options: Bytes,
+    pub send_library: Address,
+}
+
+#[event]
+pub struct PacketVerified {
+    #[topic]
+    pub origin: Origin,
+    #[topic]
+    pub receiver: Address,
+    pub payload_hash: BytesN<32>,
+}
+
+#[event]
+pub struct PacketDelivered {
+    #[topic]
+    pub origin: Origin,
+    #[topic]
+    pub receiver: Address,
+}
+
+#[event]
+pub struct LzReceiveAlert {
+    #[topic]
+    pub receiver: Address,
+    #[topic]
+    pub executor: Address,
+    #[topic]
+    pub origin: Origin,
+    #[topic]
+    pub guid: BytesN<32>,
+    pub gas: i128,
+    pub value: i128,
+    pub message: Bytes,
+    pub extra_data: Bytes,
+    pub reason: Bytes,
+}
+
+#[event]
+pub struct ZROSet {
+    pub zro: Address,
+}
+
+#[event]
+pub struct DelegateSet {
+    #[topic]
+    pub oapp: Address,
+    pub delegate: Option<Address>,
+}
+
+// ============================================================================
+// Messaging Channel Events
+// ============================================================================
+
+#[event]
+pub struct InboundNonceSkipped {
+    #[topic]
+    pub src_eid: u32,
+    #[topic]
+    pub sender: BytesN<32>,
+    #[topic]
+    pub receiver: Address,
+    #[topic]
+    pub nonce: u64,
+}
+
+#[event]
+pub struct PacketNilified {
+    #[topic]
+    pub src_eid: u32,
+    #[topic]
+    pub sender: BytesN<32>,
+    #[topic]
+    pub receiver: Address,
+    #[topic]
+    pub nonce: u64,
+    pub payload_hash: Option<BytesN<32>>,
+}
+
+#[event]
+pub struct PacketBurnt {
+    #[topic]
+    pub src_eid: u32,
+    #[topic]
+    pub sender: BytesN<32>,
+    #[topic]
+    pub receiver: Address,
+    #[topic]
+    pub nonce: u64,
+    pub payload_hash: BytesN<32>,
+}
+
+// ============================================================================
+// Message Lib Manager Events
+// ============================================================================
+
+#[event]
+pub struct LibraryRegistered {
+    pub new_lib: Address,
+}
+
+#[event]
+pub struct DefaultSendLibrarySet {
+    #[topic]
+    pub dst_eid: u32,
+    pub new_lib: Address,
+}
+
+#[event]
+pub struct DefaultReceiveLibrarySet {
+    #[topic]
+    pub src_eid: u32,
+    pub new_lib: Address,
+}
+
+#[event]
+pub struct DefaultReceiveLibraryTimeoutSet {
+    #[topic]
+    pub src_eid: u32,
+    pub timeout: Option<Timeout>,
+}
+
+#[event]
+pub struct SendLibrarySet {
+    #[topic]
+    pub sender: Address,
+    #[topic]
+    pub dst_eid: u32,
+    pub new_lib: Option<Address>,
+}
+
+#[event]
+pub struct ReceiveLibrarySet {
+    #[topic]
+    pub receiver: Address,
+    #[topic]
+    pub src_eid: u32,
+    pub new_lib: Option<Address>,
+}
+
+#[event]
+pub struct ReceiveLibraryTimeoutSet {
+    #[topic]
+    pub receiver: Address,
+    #[topic]
+    pub eid: u32,
+    pub timeout: Option<Timeout>,
+}
+
+// ============================================================================
+// Message Composer Events
+// ============================================================================
+
+#[event]
+pub struct ComposeSent {
+    #[topic]
+    pub from: Address,
+    #[topic]
+    pub to: Address,
+    #[topic]
+    pub guid: BytesN<32>,
+    #[topic]
+    pub index: u32,
+    pub message: Bytes,
+}
+
+#[event]
+pub struct ComposeDelivered {
+    #[topic]
+    pub from: Address,
+    #[topic]
+    pub to: Address,
+    #[topic]
+    pub guid: BytesN<32>,
+    #[topic]
+    pub index: u32,
+}
+
+#[event]
+pub struct LzComposeAlert {
+    #[topic]
+    pub from: Address,
+    #[topic]
+    pub to: Address,
+    #[topic]
+    pub executor: Address,
+    #[topic]
+    pub guid: BytesN<32>,
+    #[topic]
+    pub index: u32,
+    pub gas: i128,
+    pub value: i128,
+    pub message: Bytes,
+    pub extra_data: Bytes,
+    pub reason: Bytes,
+}

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

@@ -0,0 +1,26 @@
+use soroban_sdk::{contractclient, Address, Bytes, BytesN, Env};
+
+/// Interface for contracts that can receive composed messages.
+#[contractclient(name = "LayerZeroComposerClient")]
+pub trait ILayerZeroComposer {
+    /// Receives and processes a composed message from an OApp.
+    ///
+    /// # Arguments
+    /// * `executor` - The executor address delivering the message
+    /// * `from` - The OApp address that sent the composed message
+    /// * `guid` - The message GUID
+    /// * `index` - The compose message index
+    /// * `message` - The composed message content
+    /// * `extra_data` - Additional executor-provided data
+    /// * `value` - The native token value sent with the message
+    fn lz_compose(
+        env: &Env,
+        executor: &Address,
+        from: &Address,
+        guid: &BytesN<32>,
+        index: u32,
+        message: &Bytes,
+        extra_data: &Bytes,
+        value: i128,
+    );
+}