@layerzerolabs/protocol-stellar-v2 0.2.8

package/contracts/endpoint-v2/src/tests/mock.rs

@@ -0,0 +1,132 @@
+use crate::{interfaces::MessagingFee, FeeRecipient, FeesAndPacket, MessageLibType, Origin, OutboundPacket};
+use soroban_sdk::{contract, contractimpl, vec, Address, Bytes, Env, Symbol, Vec};
+
+// ============================================================================
+// Mock Receiver Contract for Testing
+// ============================================================================
+
+#[contract]
+pub struct MockReceiver;
+
+#[contractimpl]
+impl MockReceiver {
+    pub fn allow_initialize_path(_env: soroban_sdk::Env, _origin: Origin) -> bool {
+        // Default mock implementation returns true
+        true
+    }
+}
+
+#[contract]
+pub struct MockReceiverReject;
+
+#[contractimpl]
+impl MockReceiverReject {
+    pub fn allow_initialize_path(_env: soroban_sdk::Env, _origin: Origin) -> bool {
+        // Mock implementation that rejects initialization
+        false
+    }
+}
+
+#[contract]
+pub struct MockValidMessageLib;
+
+#[contractimpl]
+impl MockValidMessageLib {
+    pub fn message_lib_type(_env: &Env) -> MessageLibType {
+        MessageLibType::Send
+    }
+}
+
+// Configurable mock message library for testing
+#[contract]
+pub struct MockMessageLib;
+
+#[contractimpl]
+impl MockMessageLib {
+    pub fn setup(env: Env, lib_type: MessageLibType, supported_eids: Vec<u32>) {
+        env.storage().instance().set(&Symbol::new(&env, "lib_type"), &lib_type);
+        env.storage().instance().set(&Symbol::new(&env, "supported_eids"), &supported_eids);
+    }
+
+    pub fn message_lib_type(env: Env) -> MessageLibType {
+        env.storage().instance().get(&Symbol::new(&env, "lib_type")).unwrap_or(MessageLibType::Send)
+    }
+
+    pub fn is_supported_eid(env: Env, eid: u32) -> bool {
+        let supported_eids: Vec<u32> =
+            env.storage().instance().get(&Symbol::new(&env, "supported_eids")).unwrap_or(vec![&env]);
+        supported_eids.contains(eid)
+    }
+}
+
+// Mock send library for testing send/quote operations
+#[contract]
+pub struct MockSendLib;
+
+#[contractimpl]
+impl MockSendLib {
+    pub fn setup(env: Env, supported_eids: Vec<u32>, native_fee: i128, zro_fee: i128, fee_recipient: Address) {
+        env.storage().instance().set(&Symbol::new(&env, "supported_eids"), &supported_eids);
+        env.storage().instance().set(&Symbol::new(&env, "native_fee"), &native_fee);
+        env.storage().instance().set(&Symbol::new(&env, "zro_fee"), &zro_fee);
+        env.storage().instance().set(&Symbol::new(&env, "fee_recipient"), &fee_recipient);
+    }
+
+    pub fn message_lib_type(_env: Env) -> MessageLibType {
+        MessageLibType::Send
+    }
+
+    pub fn is_supported_eid(env: Env, eid: u32) -> bool {
+        let supported_eids: Vec<u32> =
+            env.storage().instance().get(&Symbol::new(&env, "supported_eids")).unwrap_or(vec![&env]);
+        supported_eids.contains(eid)
+    }
+
+    pub fn quote(env: Env, _packet: OutboundPacket, _options: Bytes, _pay_in_zro: bool) -> MessagingFee {
+        let native_fee = env.storage().instance().get(&Symbol::new(&env, "native_fee")).unwrap_or(100);
+        let zro_fee = env.storage().instance().get(&Symbol::new(&env, "zro_fee")).unwrap_or(0);
+        MessagingFee { native_fee, zro_fee }
+    }
+
+    pub fn send(env: Env, packet: OutboundPacket, _options: Bytes, _pay_in_zro: bool) -> FeesAndPacket {
+        let native_fee = env.storage().instance().get(&Symbol::new(&env, "native_fee")).unwrap_or(100);
+        let zro_fee = env.storage().instance().get(&Symbol::new(&env, "zro_fee")).unwrap_or(0);
+        let fee_recipient: Address = env.storage().instance().get(&Symbol::new(&env, "fee_recipient")).unwrap();
+
+        let mut native_fee_recipients = Vec::new(&env);
+        if native_fee > 0 {
+            native_fee_recipients.push_back(FeeRecipient { amount: native_fee, address: fee_recipient.clone() });
+        }
+
+        let mut zro_fee_recipients = Vec::new(&env);
+        if zro_fee > 0 {
+            zro_fee_recipients.push_back(FeeRecipient { amount: zro_fee, address: fee_recipient });
+        }
+
+        // Create a simple encoded payload (just the message for simplicity)
+        let encoded_packet = packet.message.clone();
+
+        FeesAndPacket { native_fee_recipients, zro_fee_recipients, encoded_packet }
+    }
+}
+
+// Mock receive library for testing verify operations
+#[contract]
+pub struct MockReceiveLib;
+
+#[contractimpl]
+impl MockReceiveLib {
+    pub fn setup(env: Env, supported_eids: Vec<u32>) {
+        env.storage().instance().set(&Symbol::new(&env, "supported_eids"), &supported_eids);
+    }
+
+    pub fn message_lib_type(_env: Env) -> MessageLibType {
+        MessageLibType::Receive
+    }
+
+    pub fn is_supported_eid(env: Env, eid: u32) -> bool {
+        let supported_eids: Vec<u32> =
+            env.storage().instance().get(&Symbol::new(&env, "supported_eids")).unwrap_or(vec![&env]);
+        supported_eids.contains(eid)
+    }
+}

package/contracts/endpoint-v2/src/tests/mod.rs

@@ -0,0 +1,12 @@
+mod endpoint_setup;
+mod endpoint_v2;
+mod mock;
+
+#[allow(non_snake_case)]
+mod util;
+
+mod messaging_channel;
+
+mod message_lib_manager;
+
+mod messaging_composer;

package/contracts/endpoint-v2/src/tests/util/build_payload.rs

@@ -0,0 +1,126 @@
+use crate::{tests::endpoint_setup::setup, util::build_payload};
+use soroban_sdk::{Bytes, BytesN};
+
+#[test]
+fn test_build_payload_basic() {
+    let context = setup();
+    let env = &context.env;
+
+    let guid = BytesN::from_array(env, &[1u8; 32]);
+    let message = Bytes::from_array(env, &[1, 2, 3, 4, 5]);
+
+    let payload = build_payload(env, &guid, &message);
+
+    // Payload should be 32 bytes (guid) + message length
+    assert_eq!(payload.len(), 32 + 5);
+}
+
+#[test]
+fn test_build_payload() {
+    let context = setup();
+    let env = &context.env;
+
+    // Create a guid with 32 periods (ASCII 46 = '.')
+    let guid_bytes = [46u8; 32];
+    let guid = BytesN::from_array(env, &guid_bytes);
+
+    // Create message with bytes [18, 19, 20]
+    let message = Bytes::from_array(env, &[18, 19, 20]);
+
+    let payload = build_payload(env, &guid, &message);
+
+    // Expected payload: 32 bytes of guid + 3 bytes of message
+    let expected_bytes: [u8; 35] = [
+        46, 46, 46, 46, 46, 46, 46, 46, // guid bytes 0-7
+        46, 46, 46, 46, 46, 46, 46, 46, // guid bytes 8-15
+        46, 46, 46, 46, 46, 46, 46, 46, // guid bytes 16-23
+        46, 46, 46, 46, 46, 46, 46, 46, // guid bytes 24-31 (32 periods)
+        18, 19, 20, // message
+    ];
+    let expected = Bytes::from_array(env, &expected_bytes);
+
+    assert_eq!(payload, expected);
+}
+
+
+#[test]
+fn test_build_payload_empty_message() {
+    let context = setup();
+    let env = &context.env;
+
+    let guid = BytesN::from_array(env, &[1u8; 32]);
+    let message = Bytes::new(env);
+
+    let payload = build_payload(env, &guid, &message);
+
+    // Payload should be just the 32 bytes of GUID
+    assert_eq!(payload.len(), 32);
+}
+
+#[test]
+fn test_build_payload_large_message() {
+    let context = setup();
+    let env = &context.env;
+
+    let guid = BytesN::from_array(env, &[1u8; 32]);
+    let message = Bytes::from_array(env, &[255u8; 1000]);
+
+    let payload = build_payload(env, &guid, &message);
+
+    // Payload should be 32 bytes (guid) + 1000 bytes (message)
+    assert_eq!(payload.len(), 32 + 1000);
+}
+
+
+#[test]
+fn test_build_payload_all_zero_guid() {
+    let context = setup();
+    let env = &context.env;
+
+    let guid = BytesN::from_array(env, &[0u8; 32]);
+    let message = Bytes::from_array(env, &[1, 2, 3]);
+
+    let payload = build_payload(env, &guid, &message);
+
+    // Should successfully build payload with all-zero GUID
+    assert_eq!(payload.len(), 32 + 3);
+
+    // First 32 bytes should be zeros
+    for i in 0..32 {
+        assert_eq!(payload.get(i).unwrap(), 0u8);
+    }
+}
+
+
+#[test]
+fn test_build_payload_single_byte_message() {
+    let context = setup();
+    let env = &context.env;
+
+    let guid = BytesN::from_array(env, &[1u8; 32]);
+    let message = Bytes::from_array(env, &[42]);
+
+    let payload = build_payload(env, &guid, &message);
+
+    // Payload should be 32 bytes (guid) + 1 byte (message)
+    assert_eq!(payload.len(), 33);
+    assert_eq!(payload.get(32).unwrap(), 42u8);
+}
+
+
+#[test]
+fn test_build_payload_preserves_message_order() {
+    let context = setup();
+    let env = &context.env;
+
+    let guid = BytesN::from_array(env, &[0u8; 32]);
+    let message = Bytes::from_array(env, &[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+
+    let payload = build_payload(env, &guid, &message);
+
+    // Verify message bytes are preserved in order after GUID
+    for i in 0..10 {
+        assert_eq!(payload.get(32 + i).unwrap(), (i + 1) as u8);
+    }
+}
+

package/contracts/endpoint-v2/src/tests/util/compute_guid.rs

@@ -0,0 +1,82 @@
+use crate::{tests::endpoint_setup::setup, util::compute_guid};
+use hex_literal::hex;
+use soroban_sdk::{address_payload::AddressPayload, testutils::Address as _, Address, BytesN, Env};
+
+#[test]
+fn test_compute_guid_basic() {
+    let context = setup();
+    let env = &context.env;
+
+    let nonce = 1u64;
+    let src_eid = 1u32;
+    let sender = Address::generate(env);
+    let dst_eid = 2u32;
+    let receiver = BytesN::from_array(env, &[1u8; 32]);
+
+    let guid = compute_guid(env, nonce, src_eid, &sender, dst_eid, &receiver);
+
+    // Verify that GUID is 32 bytes
+    assert_eq!(guid.len(), 32);
+}
+
+#[test]
+fn test_compute_guid() {
+    let env = Env::default();
+
+    let src_eid: u32 = 1;
+    let dst_eid: u32 = 2;
+    let nonce: u64 = 0x1234;
+
+    // Create sender address from bytes32 (0x00...03)
+    let sender_bytes = hex!("0000000000000000000000000000000000000000000000000000000000000003");
+    let sender = Address::from_payload(&env, AddressPayload::ContractIdHash(BytesN::from_array(&env, &sender_bytes)));
+
+    // Create receiver bytes32 (0x00...04)
+    let receiver_bytes = hex!("0000000000000000000000000000000000000000000000000000000000000004");
+    let receiver = BytesN::from_array(&env, &receiver_bytes);
+
+    let guid = compute_guid(&env, nonce, src_eid, &sender, dst_eid, &receiver);
+
+    // Expected GUID: 4e80f6fdccb10b2634b15fd900819c9d609ae2c61047ed47718f1dcca05587e4
+    // (generated from Aptos)
+    let expected_guid =
+        BytesN::from_array(&env, &hex!("4e80f6fdccb10b2634b15fd900819c9d609ae2c61047ed47718f1dcca05587e4"));
+
+    assert_eq!(guid, expected_guid);
+}
+
+#[test]
+fn test_compute_guid_deterministic() {
+    let context = setup();
+    let env = &context.env;
+
+    let nonce = 1u64;
+    let src_eid = 1u32;
+    let sender = Address::generate(env);
+    let dst_eid = 2u32;
+    let receiver = BytesN::from_array(env, &[1u8; 32]);
+
+    // Compute GUID twice with same parameters
+    let guid1 = compute_guid(env, nonce, src_eid, &sender, dst_eid, &receiver);
+    let guid2 = compute_guid(env, nonce, src_eid, &sender, dst_eid, &receiver);
+
+    // Should produce the same GUID
+    assert_eq!(guid1, guid2);
+}
+
+#[test]
+fn test_compute_guid_different_nonces() {
+    let context = setup();
+    let env = &context.env;
+
+    let src_eid = 1u32;
+    let sender = Address::generate(env);
+    let dst_eid = 2u32;
+    let receiver = BytesN::from_array(env, &[1u8; 32]);
+
+    let guid1 = compute_guid(env, 1, src_eid, &sender, dst_eid, &receiver);
+    let guid2 = compute_guid(env, 2, src_eid, &sender, dst_eid, &receiver);
+
+    // Different nonces should produce different GUIDs
+    assert_ne!(guid1, guid2);
+}

package/contracts/endpoint-v2/src/tests/util/keccak256.rs

@@ -0,0 +1,115 @@
+use crate::{tests::endpoint_setup::setup, util::keccak256};
+use soroban_sdk::Bytes;
+
+#[test]
+fn test_keccak256_basic() {
+    let context = setup();
+    let env = &context.env;
+
+    let message = Bytes::from_array(env, &[1, 2, 3, 4, 5]);
+
+    let hash = keccak256(env, &message);
+
+    // Hash should be 32 bytes
+    assert_eq!(hash.len(), 32);
+}
+
+#[test]
+fn test_keccak256_empty_message() {
+    let context = setup();
+    let env = &context.env;
+
+    let message = Bytes::new(env);
+
+    let hash = keccak256(env, &message);
+
+    // Hash of empty message should still be 32 bytes
+    assert_eq!(hash.len(), 32);
+}
+
+#[test]
+fn test_keccak256_deterministic() {
+    let context = setup();
+    let env = &context.env;
+
+    let message = Bytes::from_array(env, &[1, 2, 3, 4, 5]);
+
+    // Hash the same message twice
+    let hash1 = keccak256(env, &message);
+    let hash2 = keccak256(env, &message);
+
+    // Should produce the same hash
+    assert_eq!(hash1, hash2);
+}
+
+#[test]
+fn test_keccak256_different_messages() {
+    let context = setup();
+    let env = &context.env;
+
+    let message1 = Bytes::from_array(env, &[1, 2, 3]);
+    let message2 = Bytes::from_array(env, &[4, 5, 6]);
+
+    let hash1 = keccak256(env, &message1);
+    let hash2 = keccak256(env, &message2);
+
+    // Different messages should produce different hashes
+    assert_ne!(hash1, hash2);
+}
+
+#[test]
+fn test_keccak256_single_byte() {
+    let context = setup();
+    let env = &context.env;
+
+    let message = Bytes::from_array(env, &[42]);
+
+    let hash = keccak256(env, &message);
+
+    // Hash should be 32 bytes
+    assert_eq!(hash.len(), 32);
+}
+
+#[test]
+fn test_keccak256_large_message() {
+    let context = setup();
+    let env = &context.env;
+
+    let message = Bytes::from_array(env, &[255u8; 1000]);
+
+    let hash = keccak256(env, &message);
+
+    // Hash should still be 32 bytes
+    assert_eq!(hash.len(), 32);
+}
+
+#[test]
+fn test_keccak256_all_zeros() {
+    let context = setup();
+    let env = &context.env;
+
+    let message = Bytes::from_array(env, &[0u8; 100]);
+
+    let hash = keccak256(env, &message);
+
+    // Hash should be 32 bytes
+    assert_eq!(hash.len(), 32);
+}
+
+#[test]
+fn test_keccak256_very_long_message() {
+    let context = setup();
+    let env = &context.env;
+
+    // Create a very long message (e.g., 10000 bytes)
+    let mut data = [0u8; 10000];
+    for i in 0..10000 {
+        data[i] = (i % 256) as u8;
+    }
+    let message = Bytes::from_array(env, &data);
+
+    let hash = keccak256(env, &message);
+
+    // Hash should still be 32 bytes regardless of input size
+    assert_eq!(hash.len(), 32);
+}

package/contracts/endpoint-v2/src/tests/util/mod.rs

@@ -0,0 +1,3 @@
+mod build_payload;
+mod compute_guid;
+mod keccak256;

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

@@ -0,0 +1,52 @@
+use soroban_sdk::{Address, Bytes, BytesN, Env};
+use utils::buffer_writer::BufferWriter;
+
+/// Computes a globally unique identifier (GUID) for cross-chain messages.
+///
+/// # Arguments
+/// * `nonce` - The nonce of the message
+/// * `src_eid` - The source endpoint ID
+/// * `sender` - The sender OApp address on the source chain
+/// * `dst_eid` - The destination endpoint ID
+/// * `receiver` - The receiver OApp address on the destination chain
+///
+/// # Returns
+/// * `BytesN<32>` - The GUID
+pub fn compute_guid(
+    env: &Env,
+    nonce: u64,
+    src_eid: u32,
+    sender: &Address,
+    dst_eid: u32,
+    receiver: &BytesN<32>,
+) -> BytesN<32> {
+    let mut writer = BufferWriter::new(env);
+    writer.write_u64(nonce).write_u32(src_eid).write_address_payload(sender).write_u32(dst_eid).write_bytes_n(receiver);
+    keccak256(env, &writer.to_bytes())
+}
+
+/// Builds a payload from a GUID and message.
+///
+/// # Arguments
+/// * `env` - The environment
+/// * `guid` - The GUID
+/// * `message` - The message
+///
+/// # Returns
+/// * `Bytes` - The payload
+pub fn build_payload(env: &Env, guid: &BytesN<32>, message: &Bytes) -> Bytes {
+    let mut data = Bytes::from_array(env, &guid.to_array());
+    data.append(message);
+    data
+}
+
+/// Computes the Keccak-256 hash of a message.
+///
+/// # Arguments
+/// * `message` - The message
+///
+/// # Returns
+/// * `BytesN<32>` - The hash
+pub fn keccak256(env: &Env, message: &Bytes) -> BytesN<32> {
+    env.crypto().keccak256(message).into()
+}

package/contracts/message-libs/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "message-libs"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish = false
+
+[lib]
+path = "lib.rs"
+
+[dependencies]
+

package/contracts/message-libs/block-message-lib/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "block-message-lib"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+doctest = false
+
+[dependencies]
+soroban-sdk = { workspace = true }
+# workspace dependencies
+endpoint-v2 = { workspace = true, features = ["library"] }
+common-macros = { workspace = true }
+
+[dev-dependencies]
+soroban-sdk = { workspace = true, features = ["testutils"] }

package/contracts/message-libs/block-message-lib/src/lib.rs

@@ -0,0 +1,70 @@
+//! # Block Message Library
+//!
+//! A special message library that blocks all messaging operations.
+//!
+//! This library is used as a blocklist mechanism to prevent OApps from sending
+//! or receiving cross-chain messages. When assigned as an OApp's send or receive
+//! library, all quote, send, and config operations will fail.
+//!
+//! Use cases:
+//! - Temporarily disable messaging for an OApp
+//! - Emergency circuit breaker for cross-chain communication
+
+#![no_std]
+
+use common_macros::contract_error;
+use endpoint_v2::{
+    FeesAndPacket, IMessageLib, ISendLib, MessageLibType, MessageLibVersion, MessagingFee, OutboundPacket,
+    SetConfigParam,
+};
+use soroban_sdk::{contract, contractimpl, panic_with_error, Address, Bytes, Env, Vec};
+
+#[contract_error]
+enum BlockMessageLibError {
+    NotImplemented,
+}
+
+/// Block Message Library contract that rejects all messaging operations.
+#[contract]
+pub struct BlockMessageLib;
+
+#[contractimpl]
+impl IMessageLib for BlockMessageLib {
+    /// Always panics - config retrieval is not supported.
+    fn get_config(env: &Env, _eid: u32, _oapp: &Address, _config_type: u32) -> Bytes {
+        panic_with_error!(&env, BlockMessageLibError::NotImplemented);
+    }
+
+    /// Returns true for all EIDs to allow assignment as a blocking library.
+    fn is_supported_eid(_env: &Env, _eid: u32) -> bool {
+        true
+    }
+
+    /// Returns SendAndReceive to indicate it can block both directions.
+    fn message_lib_type(_env: &Env) -> MessageLibType {
+        MessageLibType::SendAndReceive
+    }
+
+    /// Always panics - config modification is not supported.
+    fn set_config(env: &Env, _oapp: &Address, _param: &Vec<SetConfigParam>) {
+        panic_with_error!(&env, BlockMessageLibError::NotImplemented);
+    }
+
+    /// Returns max version to ensure it's recognized as a valid library.
+    fn version(_env: &Env) -> MessageLibVersion {
+        MessageLibVersion { major: u64::MAX, minor: u8::MAX as u32, endpoint_version: 2 }
+    }
+}
+
+#[contractimpl]
+impl ISendLib for BlockMessageLib {
+    /// Always panics - quoting is blocked.
+    fn quote(env: &Env, _packet: &OutboundPacket, _options: &Bytes, _pay_in_zro: bool) -> MessagingFee {
+        panic_with_error!(&env, BlockMessageLibError::NotImplemented);
+    }
+
+    /// Always panics - sending is blocked.
+    fn send(env: &Env, _packet: &OutboundPacket, _options: &Bytes, _pay_in_zro: bool) -> FeesAndPacket {
+        panic_with_error!(&env, BlockMessageLibError::NotImplemented);
+    }
+}

package/contracts/message-libs/lib.rs

@@ -0,0 +1,2 @@
+#![no_std]
+// This is an empty library crate that serves as a parent for message-lib packages

package/contracts/message-libs/message-lib-common/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "message-lib-common"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[lib]
+crate-type = ["rlib"]
+doctest = false
+
+[features]
+testutils = []
+
+[dependencies]
+cfg-if = "1.0"
+soroban-sdk = { workspace = true }
+# workspace dependencies
+utils = { workspace = true }
+common-macros = { workspace = true }
+endpoint-v2 = { workspace = true, features = ["library"] }
+
+[dev-dependencies]
+soroban-sdk = { workspace = true, features = ["testutils"] }
+hex-literal = { workspace = true }

package/contracts/message-libs/message-lib-common/src/errors.rs

@@ -0,0 +1,20 @@
+use common_macros::contract_error;
+
+#[contract_error]
+pub enum PacketCodecV1Error {
+    InvalidPacketVersion = 11001,
+    InvalidPacketHeader,
+}
+
+#[contract_error]
+pub enum WorkerOptionsError {
+    InvalidOptions = 11101,
+    InvalidWorkerId,
+    InvalidLegacyOptionsType1,
+    LegacyOptionsType1GasOverflow,
+    InvalidLegacyOptionsType2,
+    LegacyOptionsType2GasOverflow,
+    LegacyOptionsType2AmountOverflow,
+    InvalidOptionType,
+    InvalidBytesLength,
+}