@layerzerolabs/protocol-stellar-v2 0.2.8

package/contracts/message-libs/message-lib-common/src/interfaces/dvn.rs

@@ -0,0 +1,55 @@
+use endpoint_v2::FeeRecipient;
+use soroban_sdk::{contractclient, Address, Bytes, BytesN, Env};
+
+/// Interface for Decentralized Verifier Networks (DVNs) that verify cross-chain messages.
+#[allow(clippy::upper_case_acronyms)]
+#[contractclient(name = "LayerZeroDVNClient")]
+pub trait ILayerZeroDVN {
+    /// Quotes the fee for verifying a message.
+    ///
+    /// # Arguments
+    /// * `send_lib` - The send library address
+    /// * `sender` - The sender OApp address
+    /// * `dst_eid` - The destination endpoint ID
+    /// * `packet_header` - The packet header bytes
+    /// * `payload_hash` - The hash of the message payload
+    /// * `confirmations` - The number of block confirmations required
+    /// * `options` - DVN-specific options
+    ///
+    /// # Returns
+    /// The verification fee in native token
+    fn get_fee(
+        env: &Env,
+        send_lib: &Address,
+        sender: &Address,
+        dst_eid: u32,
+        packet_header: &Bytes,
+        payload_hash: &BytesN<32>,
+        confirmations: u64,
+        options: &Bytes,
+    ) -> i128;
+
+    /// Assigns a verification job to the DVN.
+    ///
+    /// # Arguments
+    /// * `send_lib` - The send library address
+    /// * `sender` - The sender OApp address
+    /// * `dst_eid` - The destination endpoint ID
+    /// * `packet_header` - The packet header bytes
+    /// * `payload_hash` - The hash of the message payload
+    /// * `confirmations` - The number of block confirmations required
+    /// * `options` - DVN-specific options
+    ///
+    /// # Returns
+    /// `FeeRecipient` containing the fee recipient address and fee amount
+    fn assign_job(
+        env: &Env,
+        send_lib: &Address,
+        sender: &Address,
+        dst_eid: u32,
+        packet_header: &Bytes,
+        payload_hash: &BytesN<32>,
+        confirmations: u64,
+        options: &Bytes,
+    ) -> FeeRecipient;
+}

package/contracts/message-libs/message-lib-common/src/interfaces/executor.rs

@@ -0,0 +1,46 @@
+use endpoint_v2::FeeRecipient;
+use soroban_sdk::{contractclient, Address, Bytes, Env};
+
+/// Interface for executors that handle message delivery on the destination chain.
+#[contractclient(name = "LayerZeroExecutorClient")]
+pub trait ILayerZeroExecutor {
+    /// Quotes the fee for executing a message on the destination chain.
+    ///
+    /// # Arguments
+    /// * `send_lib` - The send library address
+    /// * `sender` - The sender OApp address
+    /// * `dst_eid` - The destination endpoint ID
+    /// * `calldata_size` - The size of the calldata to execute
+    /// * `options` - Execution options (gas limit, airdrop, etc.)
+    ///
+    /// # Returns
+    /// The execution fee in native token
+    fn get_fee(
+        env: &Env,
+        send_lib: &Address,
+        sender: &Address,
+        dst_eid: u32,
+        calldata_size: u32,
+        options: &Bytes,
+    ) -> i128;
+
+    /// Assigns an execution job to the executor.
+    ///
+    /// # Arguments
+    /// * `send_lib` - The send library address
+    /// * `sender` - The sender OApp address
+    /// * `dst_eid` - The destination endpoint ID
+    /// * `calldata_size` - The size of the calldata to execute
+    /// * `options` - Execution options (gas limit, airdrop, etc.)
+    ///
+    /// # Returns
+    /// `FeeRecipient` containing the fee recipient address and fee amount
+    fn assign_job(
+        env: &Env,
+        send_lib: &Address,
+        sender: &Address,
+        dst_eid: u32,
+        calldata_size: u32,
+        options: &Bytes,
+    ) -> FeeRecipient;
+}

package/contracts/message-libs/message-lib-common/src/interfaces/mod.rs

@@ -0,0 +1,7 @@
+pub mod dvn;
+pub mod executor;
+pub mod treasury;
+
+pub use dvn::*;
+pub use executor::*;
+pub use treasury::*;

package/contracts/message-libs/message-lib-common/src/interfaces/treasury.rs

@@ -0,0 +1,17 @@
+use soroban_sdk::{contractclient, Address, Env};
+
+/// Interface for the treasury that collects protocol fees.
+#[contractclient(name = "LayerZeroTreasuryClient")]
+pub trait ILayerZeroTreasury {
+    /// Quotes the treasury fee for a message.
+    ///
+    /// # Arguments
+    /// * `sender` - The sender OApp address
+    /// * `dst_eid` - The destination endpoint ID
+    /// * `total_native_fee` - The total native fee for the message
+    /// * `pay_in_zro` - Whether to pay fees in ZRO token
+    ///
+    /// # Returns
+    /// The treasury fee amount
+    fn get_fee(env: &Env, sender: &Address, dst_eid: u32, total_native_fee: i128, pay_in_zro: bool) -> i128;
+}

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

@@ -0,0 +1,14 @@
+#![no_std]
+
+pub mod errors;
+pub mod interfaces;
+pub mod packet_codec_v1;
+pub mod worker_options;
+
+pub use interfaces::*;
+
+#[cfg(test)]
+mod tests;
+
+#[cfg(any(test, feature = "testutils"))]
+pub mod testing_utils;

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

@@ -0,0 +1,99 @@
+use endpoint_v2::{
+    util::{build_payload, keccak256},
+    OutboundPacket,
+};
+use soroban_sdk::{assert_with_error, Bytes, BytesN, Env};
+use utils::{buffer_reader::BufferReader, buffer_writer::BufferWriter};
+
+use crate::errors::PacketCodecV1Error;
+
+pub const PACKET_VERSION: u8 = 1;
+pub const HEADER_LENGTH: u32 = 81;
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct PacketHeader {
+    pub version: u8,
+    pub nonce: u64,
+    pub src_eid: u32,
+    pub sender: BytesN<32>,
+    pub dst_eid: u32,
+    pub receiver: BytesN<32>,
+}
+
+/// Encodes a complete outbound packet including header, GUID, and message.
+///
+/// Packet layout: [header (81 bytes)] + [guid (32 bytes)] + [message (variable)]
+///
+/// # Arguments
+/// * `packet` - The outbound packet containing routing info and message
+///
+/// # Returns
+/// Encoded packet bytes ready for cross-chain transmission
+pub fn encode_packet(env: &Env, packet: &OutboundPacket) -> Bytes {
+    let mut result = encode_packet_header(env, packet);
+    result.extend_from_array(&packet.guid.to_array());
+    result.append(&packet.message);
+    result
+}
+
+/// Encodes only the packet header from an outbound packet.
+///
+/// Header layout (81 bytes):
+/// - `[0]`: version (1 byte)
+/// - `[1..9]`: nonce (8 bytes, big-endian)
+/// - `[9..13]`: src_eid (4 bytes, big-endian)
+/// - `[13..45]`: sender (32 bytes)
+/// - `[45..49]`: dst_eid (4 bytes, big-endian)
+/// - `[49..81]`: receiver (32 bytes)
+///
+/// # Arguments
+/// * `packet` - The outbound packet to encode header from
+///
+/// # Returns
+/// Encoded 81-byte packet header
+pub fn encode_packet_header(env: &Env, packet: &OutboundPacket) -> Bytes {
+    let mut writer = BufferWriter::new(env);
+    writer
+        .write_u8(PACKET_VERSION)
+        .write_u64(packet.nonce)
+        .write_u32(packet.src_eid)
+        .write_address_payload(&packet.sender)
+        .write_u32(packet.dst_eid)
+        .write_bytes_n(&packet.receiver);
+    writer.to_bytes()
+}
+
+/// Decodes a byte vector into a packet header and validates the format.
+///
+/// Validates header length (81 bytes) and packet version before decoding.
+///
+/// # Arguments
+/// * `encoded_header` - The raw 81-byte packet header
+///
+/// # Returns
+/// Decoded `PacketHeader` struct with version, nonce, src_eid, sender, dst_eid, receiver
+pub fn decode_packet_header(env: &Env, encoded_header: &Bytes) -> PacketHeader {
+    assert_with_error!(env, encoded_header.len() == HEADER_LENGTH, PacketCodecV1Error::InvalidPacketHeader);
+
+    let mut reader = BufferReader::new(encoded_header);
+    let packet_version = reader.read_u8();
+    assert_with_error!(env, packet_version == PACKET_VERSION, PacketCodecV1Error::InvalidPacketVersion);
+
+    let nonce = reader.read_u64();
+    let src_eid = reader.read_u32();
+    let sender = reader.read_bytes_n();
+    let dst_eid = reader.read_u32();
+    let receiver = reader.read_bytes_n();
+
+    PacketHeader { version: PACKET_VERSION, nonce, src_eid, sender, dst_eid, receiver }
+}
+
+/// Returns the payload (GUID + message) from an outbound packet.
+pub fn payload(env: &Env, packet: &OutboundPacket) -> Bytes {
+    build_payload(env, &packet.guid, &packet.message)
+}
+
+/// Returns the keccak256 hash of the packet payload.
+pub fn payload_hash(env: &Env, packet: &OutboundPacket) -> BytesN<32> {
+    keccak256(env, &payload(env, packet))
+}

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

@@ -0,0 +1,27 @@
+use soroban_sdk::{bytes, Address, Bytes, Env, Vec};
+
+use crate::worker_options::{DVN_WORKER_ID, EXECUTOR_OPTION_TYPE_LZRECEIVE, EXECUTOR_WORKER_ID, OPTIONS_TYPE_3};
+
+pub fn create_type3_options(env: &Env, dvns: &Vec<Address>, enable_executor_option: bool) -> Bytes {
+    let mut result = bytes!(env);
+
+    result.extend_from_array(&OPTIONS_TYPE_3.to_be_bytes());
+
+    // append executor option
+    if enable_executor_option {
+        result.extend_from_array(&[EXECUTOR_WORKER_ID]);
+        result.extend_from_array(&17u16.to_be_bytes()); // option_size: option_type(1) + data(16) = 17 bytes
+        result.extend_from_array(&[EXECUTOR_OPTION_TYPE_LZRECEIVE]); // option_type (1 byte)
+        result.extend_from_array(&200000_u128.to_be_bytes()); // execution gas (16 bytes)
+    }
+
+    // append dvn options
+    for (idx, _dvn) in dvns.iter().enumerate() {
+        result.extend_from_array(&[DVN_WORKER_ID]);
+        result.extend_from_array(&5u16.to_be_bytes()); // idx(1) + data(4) = 5 bytes
+        result.extend_from_array(&[idx as u8]); // dvn_idx
+        result.extend_from_array(&1000_u32.to_be_bytes()); // custom data (4 bytes)
+    }
+
+    result
+}

package/contracts/message-libs/message-lib-common/src/tests/mod.rs

@@ -0,0 +1,2 @@
+mod packet_codec_v1;
+mod worker_options;

package/contracts/message-libs/message-lib-common/src/tests/packet_codec_v1.rs

@@ -0,0 +1,162 @@
+use crate::packet_codec_v1::*;
+use endpoint_v2::{
+    util::{compute_guid, keccak256},
+    OutboundPacket,
+};
+use hex_literal::hex;
+use soroban_sdk::{address_payload::AddressPayload, Address, Bytes, BytesN, Env};
+use utils::buffer_reader::BufferReader;
+
+// Test constants matching Sui's test values
+const TEST_SRC_EID: u32 = 101;
+const TEST_DST_EID: u32 = 102;
+const TEST_NONCE: u64 = 0x123456789abcdef0;
+const TEST_MESSAGE: [u8; 5] = hex!("0102030405");
+// @0x1234567890abcdef1234567890abcdef12345678 padded to 32 bytes
+const TEST_SENDER_BYTES: [u8; 32] = hex!("0000000000000000000000001234567890abcdef1234567890abcdef12345678");
+// @0x9876543210fedcba9876543210fedcba98765432 padded to 32 bytes
+const TEST_RECEIVER_BYTES: [u8; 32] = hex!("0000000000000000000000009876543210fedcba9876543210fedcba98765432");
+
+#[test]
+fn test_encode_decode_packet_header() {
+    let env = Env::default();
+    let packet = create_test_outbound_packet(&env);
+
+    // Encode the packet header
+    let encoded_header = encode_packet_header(&env, &packet);
+
+    // Verify the encoded header has the correct length
+    assert_eq!(encoded_header.len(), HEADER_LENGTH); // HEADER_LENGTH = 81
+
+    // Decode the header back
+    let decoded_header = decode_packet_header(&env, &encoded_header);
+
+    // Verify all fields match
+    assert_eq!(decoded_header.version, PACKET_VERSION);
+    assert_eq!(decoded_header.nonce, TEST_NONCE);
+    assert_eq!(decoded_header.src_eid, TEST_SRC_EID);
+    assert_eq!(decoded_header.dst_eid, TEST_DST_EID);
+    assert_eq!(decoded_header.sender, BytesN::from_array(&env, &TEST_SENDER_BYTES));
+    assert_eq!(decoded_header.receiver, BytesN::from_array(&env, &TEST_RECEIVER_BYTES));
+}
+
+#[test]
+fn test_payload_functions() {
+    let env = Env::default();
+    let packet = create_test_outbound_packet(&env);
+
+    // Test payload extraction
+    let payload_result = payload(&env, &packet);
+
+    // Expected payload is guid + message
+    let mut expected_payload = Bytes::new(&env);
+    expected_payload.extend_from_array(&packet.guid.to_array());
+    expected_payload.append(&packet.message);
+    assert_eq!(payload_result, expected_payload);
+
+    // Test payload hash
+    let hash_result = payload_hash(&env, &packet);
+    let expected_hash = keccak256(&env, &payload_result);
+    assert_eq!(hash_result, expected_hash);
+}
+
+#[test]
+#[should_panic(expected = "Error(Contract, #11002)")] // PacketCodecV1Error::InvalidPacketHeader
+fn test_invalid_header_length() {
+    let env = Env::default();
+    // Create a header with wrong length (too short) - only 3 bytes instead of 81
+    let invalid_header = Bytes::from_array(&env, &[0x01, 0x02, 0x03]);
+    decode_packet_header(&env, &invalid_header);
+}
+
+#[test]
+#[should_panic(expected = "Error(Contract, #11001)")] // PacketCodecV1Error::InvalidPacketVersion
+fn test_invalid_packet_version() {
+    let env = Env::default();
+    // Create a header with correct length but wrong version
+    let mut invalid_header_bytes: [u8; 81] = [0u8; HEADER_LENGTH as usize];
+    invalid_header_bytes[0] = 2; // Wrong version (should be 1)
+    let invalid_header = Bytes::from_array(&env, &invalid_header_bytes);
+    decode_packet_header(&env, &invalid_header);
+}
+
+#[test]
+fn test_header_getters() {
+    let env = Env::default();
+    let header = create_test_header(&env);
+    // Test all getter/field accesses
+    assert_eq!(header.version, PACKET_VERSION);
+    assert_eq!(header.nonce, TEST_NONCE);
+    assert_eq!(header.src_eid, TEST_SRC_EID);
+    assert_eq!(header.dst_eid, TEST_DST_EID);
+    assert_eq!(header.sender, BytesN::from_array(&env, &TEST_SENDER_BYTES));
+    assert_eq!(header.receiver, BytesN::from_array(&env, &TEST_RECEIVER_BYTES));
+}
+
+#[test]
+fn test_empty_message() {
+    let env = Env::default();
+    let empty_message = Bytes::new(&env);
+    let packet = create_test_outbound_packet_with_message(&env, empty_message);
+
+    // Test encoding and decoding with empty message
+    let encoded = encode_packet(&env, &packet);
+    let (header, decoded_guid, decoded_message) = decode_packet_for_test(&env, &encoded);
+
+    assert_eq!(header.src_eid, TEST_SRC_EID);
+    assert_eq!(decoded_guid, packet.guid);
+    assert_eq!(decoded_message.len(), 0);
+}
+
+#[test]
+fn test_large_message() {
+    let env = Env::default();
+
+    // Create a large message (1024 bytes, matching Sui's 1KB)
+    let mut large_msg_array = [0u8; 1024];
+    for (i, byte) in large_msg_array.iter_mut().enumerate() {
+        *byte = (i % 256) as u8;
+    }
+    let large_message = Bytes::from_slice(&env, &large_msg_array);
+    let packet = create_test_outbound_packet_with_message(&env, large_message.clone());
+
+    // Test encoding and decoding with large message
+    let encoded = encode_packet(&env, &packet);
+    let (header, decoded_guid, decoded_message) = decode_packet_for_test(&env, &encoded);
+
+    assert_eq!(header.src_eid, TEST_SRC_EID);
+    assert_eq!(decoded_guid, packet.guid);
+    assert_eq!(decoded_message.len(), 1024);
+    assert_eq!(decoded_message, large_message);
+}
+
+fn create_test_header(env: &Env) -> PacketHeader {
+    let mut header_bytes = Bytes::new(env);
+    header_bytes.extend_from_array(&[PACKET_VERSION]); // version
+    header_bytes.extend_from_array(&TEST_NONCE.to_be_bytes()); // nonce
+    header_bytes.extend_from_array(&TEST_SRC_EID.to_be_bytes()); // src_eid
+    header_bytes.extend_from_array(&TEST_SENDER_BYTES); // sender
+    header_bytes.extend_from_array(&TEST_DST_EID.to_be_bytes()); // dst_eid
+    header_bytes.extend_from_array(&TEST_RECEIVER_BYTES); // receiver
+    decode_packet_header(env, &header_bytes)
+}
+
+fn create_test_outbound_packet(env: &Env) -> OutboundPacket {
+    create_test_outbound_packet_with_message(env, Bytes::from_array(env, &TEST_MESSAGE))
+}
+
+fn create_test_outbound_packet_with_message(env: &Env, message: Bytes) -> OutboundPacket {
+    let sender =
+        Address::from_payload(env, AddressPayload::ContractIdHash(BytesN::from_array(env, &TEST_SENDER_BYTES)));
+    let receiver = BytesN::from_array(env, &TEST_RECEIVER_BYTES);
+    let guid = compute_guid(env, TEST_NONCE, TEST_SRC_EID, &sender, TEST_DST_EID, &receiver);
+    OutboundPacket { nonce: TEST_NONCE, src_eid: TEST_SRC_EID, sender, dst_eid: TEST_DST_EID, receiver, guid, message }
+}
+
+fn decode_packet_for_test(env: &Env, encoded: &Bytes) -> (PacketHeader, BytesN<32>, Bytes) {
+    let mut reader = BufferReader::new(encoded);
+    let header = decode_packet_header(env, &reader.read_bytes(HEADER_LENGTH));
+    let guid = reader.read_bytes_n();
+    let message = reader.read_bytes_until_end();
+    (header, guid, message)
+}