@layerzerolabs/protocol-stellar-v2 0.2.8

package/contracts/oapps/oapp/src/tests/test_oapp_sender.rs

@@ -0,0 +1,283 @@
+use crate as oapp;
+use crate::{errors::OAppError, oapp_core::OAppCore};
+use endpoint_v2::{MessagingFee, MessagingParams, MessagingReceipt};
+use soroban_sdk::{
+    contract, contractimpl, symbol_short,
+    testutils::{Address as _, MockAuth, MockAuthInvoke},
+    token::{StellarAssetClient, TokenClient},
+    Address, Bytes, BytesN, Env, IntoVal,
+};
+use utils::ownable::Ownable;
+
+// Mock Endpoint contract
+#[contract]
+pub struct MockEndpoint;
+
+#[contractimpl]
+impl MockEndpoint {
+    pub fn __constructor(env: Env, zro_token: &Address, native_token: &Address) {
+        env.storage().instance().set(&symbol_short!("zro"), zro_token);
+        env.storage().instance().set(&symbol_short!("ntk"), native_token);
+    }
+
+    pub fn set_delegate(_env: Env, _oapp: Address, _delegate: Option<Address>) {
+        // do nothing in mock
+    }
+
+    pub fn quote(_env: Env, _sender: Address, params: MessagingParams) -> MessagingFee {
+        MessagingFee { native_fee: 1000, zro_fee: if params.pay_in_zro { 500 } else { 0 } }
+    }
+
+    pub fn send(env: Env, _sender: Address, params: MessagingParams, _refund_address: Address) -> MessagingReceipt {
+        // Return mock receipt
+        MessagingReceipt {
+            guid: BytesN::from_array(&env, &[1u8; 32]),
+            nonce: 1,
+            fee: MessagingFee { native_fee: 1000, zro_fee: if params.pay_in_zro { 500 } else { 0 } },
+        }
+    }
+
+    pub fn zro(env: Env) -> Option<Address> {
+        // Return a mock ZRO token address
+        env.storage().instance().get(&symbol_short!("zro")).unwrap()
+    }
+
+    pub fn native_token(env: Env) -> Address {
+        env.storage().instance().get(&symbol_short!("ntk")).unwrap()
+    }
+}
+
+#[oapp_macros::oapp_sender]
+pub struct DummyOAppSender;
+
+#[contractimpl]
+impl DummyOAppSender {
+    pub fn __constructor(env: &Env, owner: &Address, endpoint: &Address) {
+        Self::__init_owner(env, owner);
+        Self::__oapp_initialize(env, endpoint, &None);
+    }
+
+    pub fn quote(env: &Env, dst_eid: u32, message: &Bytes, options: &Bytes, pay_in_zro: bool) -> MessagingFee {
+        Self::__quote(env, dst_eid, message, options, pay_in_zro)
+    }
+
+    pub fn lz_send(
+        env: &Env,
+        sender: &Address,
+        dst_eid: u32,
+        message: &Bytes,
+        options: &Bytes,
+        fee: &MessagingFee,
+        refund_address: &Address,
+    ) -> MessagingReceipt {
+        sender.require_auth();
+        Self::__lz_send(env, sender, dst_eid, message, options, fee, refund_address)
+    }
+
+    pub fn pay_native(env: &Env, payer: &Address, native_fee: i128) {
+        payer.require_auth();
+        Self::__pay_native(env, payer, native_fee)
+    }
+
+    pub fn pay_zro(env: &Env, payer: &Address, zro_fee: i128) {
+        payer.require_auth();
+        Self::__pay_zro(env, payer, zro_fee)
+    }
+}
+
+const REMOTE_EID: u32 = 100;
+const UNSET_EID: u32 = 999;
+
+struct TestSetup<'a> {
+    env: Env,
+    #[allow(dead_code)]
+    token_admin: Address,
+    endpoint: Address,
+    #[allow(dead_code)]
+    owner: Address,
+    oapp_client: DummyOAppSenderClient<'a>,
+    native_token_client: TokenClient<'a>,
+    native_token_admin_client: StellarAssetClient<'a>,
+    zro_token_admin_client: StellarAssetClient<'a>,
+}
+
+fn setup<'a>() -> TestSetup<'a> {
+    let env = Env::default();
+
+    let owner = Address::generate(&env);
+
+    let token_admin = Address::generate(&env);
+    // Deploy mock tokens
+    let native_token_sac = env.register_stellar_asset_contract_v2(token_admin.clone());
+    let native_token = native_token_sac.address();
+    let native_token_client = TokenClient::new(&env, &native_token);
+    let native_token_admin_client = StellarAssetClient::new(&env, &native_token);
+
+    let zro_token_sac = env.register_stellar_asset_contract_v2(token_admin.clone());
+    let zro_token = zro_token_sac.address();
+    let zro_token_admin_client = StellarAssetClient::new(&env, &zro_token);
+
+    // Deploy mock endpoint
+    let endpoint = env.register(MockEndpoint, (&zro_token, &native_token));
+
+    // Deploy OApp
+    let oapp = env.register(DummyOAppSender, (&owner, &endpoint));
+    let oapp_client = DummyOAppSenderClient::new(&env, &oapp);
+
+    TestSetup {
+        env,
+        endpoint,
+        token_admin,
+        native_token_client,
+        native_token_admin_client,
+        zro_token_admin_client,
+        owner,
+        oapp_client,
+    }
+}
+
+#[test]
+fn test_quote_with_peer_set() {
+    let TestSetup { env, owner, oapp_client, .. } = setup();
+
+    // Set peer for destination
+    let peer = BytesN::from_array(&env, &[1; 32]);
+    let peer_option = Some(peer.clone());
+    env.mock_auths(&[MockAuth {
+        address: &owner,
+        invoke: &MockAuthInvoke {
+            contract: &oapp_client.address,
+            fn_name: "set_peer",
+            args: (&REMOTE_EID, &peer_option).into_val(&env),
+            sub_invokes: &[],
+        },
+    }]);
+    oapp_client.set_peer(&REMOTE_EID, &peer_option);
+
+    let message = Bytes::from_array(&env, &[1, 2, 3, 4, 5]);
+    let options = Bytes::from_array(&env, &[6, 7, 8]);
+
+    // Test quote without ZRO
+    let fee = oapp_client.quote(&REMOTE_EID, &message, &options, &false);
+    assert!(fee.native_fee > 0);
+    assert_eq!(fee.zro_fee, 0);
+
+    // Test quote with ZRO
+    let fee_with_zro = oapp_client.quote(&REMOTE_EID, &message, &options, &true);
+    assert!(fee_with_zro.native_fee > 0);
+    assert!(fee_with_zro.zro_fee > 0);
+}
+
+#[test]
+fn test_quote_without_peer_panics() {
+    let TestSetup { env, oapp_client, .. } = setup();
+
+    let message = Bytes::from_array(&env, &[1, 2, 3]);
+    let options = Bytes::from_array(&env, &[]);
+
+    // This should panic because no peer is set for UNSET_EID
+    let result = oapp_client.try_quote(&UNSET_EID, &message, &options, &false);
+    assert_eq!(result.err().unwrap().ok().unwrap(), OAppError::NoPeer.into());
+}
+
+#[test]
+fn test_lz_send_native_only() {
+    let TestSetup { env, oapp_client, endpoint, native_token_client, native_token_admin_client, .. } = setup();
+
+    env.mock_all_auths();
+
+    // Setup peer
+    let peer = BytesN::from_array(&env, &[2; 32]);
+    oapp_client.set_peer(&REMOTE_EID, &Some(peer));
+
+    // Setup sender with funds
+    let sender = Address::generate(&env);
+    let initial_balance = 10000i128;
+    native_token_admin_client.mint(&sender, &initial_balance);
+
+    let message = Bytes::from_array(&env, &[1, 2, 3]);
+    let options = Bytes::from_array(&env, &[]);
+    let refund_address = Address::generate(&env);
+
+    let fee = MessagingFee { native_fee: 1000, zro_fee: 0 };
+
+    // Send message (auth is mocked automatically)
+    let receipt = oapp_client.lz_send(&sender, &REMOTE_EID, &message, &options, &fee, &refund_address);
+
+    // Verify receipt
+    assert_eq!(receipt.nonce, 1);
+    assert_eq!(receipt.fee.native_fee, fee.native_fee);
+
+    // Verify native token was transferred to endpoint
+    let sender_balance = native_token_client.balance(&sender);
+    assert_eq!(sender_balance, initial_balance - fee.native_fee);
+
+    let endpoint_balance = native_token_client.balance(&endpoint);
+    assert_eq!(endpoint_balance, fee.native_fee);
+}
+
+#[test]
+fn test_lz_send_with_zro() {
+    let TestSetup { env, oapp_client, native_token_admin_client, zro_token_admin_client, .. } = setup();
+
+    env.mock_all_auths();
+
+    // Setup peer
+    let peer = BytesN::from_array(&env, &[3; 32]);
+    oapp_client.set_peer(&REMOTE_EID, &Some(peer));
+
+    // Setup sender with both native and ZRO funds
+    let fee = MessagingFee { native_fee: 1000, zro_fee: 500 };
+
+    let sender = Address::generate(&env);
+    native_token_admin_client.mint(&sender, &fee.native_fee);
+    zro_token_admin_client.mint(&sender, &fee.zro_fee);
+
+    let message = Bytes::from_array(&env, &[1, 2, 3, 4]);
+    let options = Bytes::from_array(&env, &[5]);
+    let refund_address = Address::generate(&env);
+
+    // Send message with ZRO payment
+    let receipt = oapp_client.lz_send(&sender, &REMOTE_EID, &message, &options, &fee, &refund_address);
+
+    assert_eq!(receipt.fee.zro_fee, fee.zro_fee);
+}
+
+#[test]
+fn test_pay_native() {
+    let TestSetup { env, oapp_client, endpoint, native_token_admin_client, .. } = setup();
+
+    env.mock_all_auths();
+
+    let payer = Address::generate(&env);
+    let payment_amount = 2000i128;
+
+    // Fund the payer
+    native_token_admin_client.mint(&payer, &payment_amount);
+
+    // Make payment
+    oapp_client.pay_native(&payer, &payment_amount);
+
+    // Verify balances
+    assert_eq!(native_token_admin_client.balance(&payer), 0);
+    assert_eq!(native_token_admin_client.balance(&endpoint), payment_amount);
+}
+
+#[test]
+#[should_panic(expected = "balance is not sufficient to spend")]
+fn test_pay_native_insufficient_balance() {
+    let TestSetup { env, oapp_client, native_token_admin_client, .. } = setup();
+
+    env.mock_all_auths();
+
+    let balance = 500i128;
+    let payment_amount = 1000i128;
+
+    let payer = Address::generate(&env);
+
+    // Fund with less than required
+    native_token_admin_client.mint(&payer, &balance);
+
+    // This should panic due to insufficient balance
+    oapp_client.pay_native(&payer, &payment_amount);
+}

package/contracts/utils/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "utils"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish = false
+
+[lib]
+crate-type = ["rlib"]
+doctest = false
+
+[features]
+testutils = []
+
+[dependencies]
+soroban-sdk = { workspace = true }
+common-macros = { workspace = true }
+
+[dev-dependencies]
+soroban-sdk = { workspace = true, features = ["testutils"] }
+stellar-strkey = "0.0.14"

package/contracts/utils/src/buffer_reader.rs

@@ -0,0 +1,143 @@
+use soroban_sdk::{
+    address_payload::AddressPayload, assert_with_error, panic_with_error, Address, Bytes, BytesN, Env, U256,
+};
+
+use crate::{
+    buffer_writer::{ACCOUNT_PAYLOAD_TYPE, CONTRACT_PAYLOAD_TYPE},
+    bytes_ext::BytesExt,
+    errors::BufferReaderError,
+};
+
+/// Macro to generate read methods for primitive integer types (big-endian).
+macro_rules! impl_read_uint {
+    ($($method:ident, $type:ty, $len:expr);* $(;)?) => {
+        $(
+            pub fn $method(&mut self) -> $type {
+                <$type>::from_be_bytes(self.read_bytes($len).to_array())
+            }
+        )*
+    };
+}
+
+/// A sequential reader for parsing binary data from a byte buffer.
+///
+/// Maintains a position cursor that advances as data is read.
+/// All integer reads are big-endian.
+pub struct BufferReader<'a> {
+    buffer: &'a Bytes,
+    pos: u32,
+}
+
+impl<'a> BufferReader<'a> {
+    /// Creates a new reader starting at position 0.
+    pub fn new(buffer: &'a Bytes) -> Self {
+        Self { buffer, pos: 0 }
+    }
+
+    // TODO: should we pass and return a self instead of mutable reference?
+    /// Sets the absolute position in the buffer.
+    pub fn set_position(&mut self, pos: u32) -> &mut Self {
+        assert_with_error!(self.buffer.env(), pos <= self.buffer.len(), BufferReaderError::InvalidLength);
+        self.pos = pos;
+        self
+    }
+
+    /// Advances the position by `len` bytes without reading.
+    pub fn skip(&mut self, len: u32) -> &mut Self {
+        self.set_position(self.pos + len)
+    }
+
+    /// Moves the position backwards by `len` bytes.
+    pub fn rewind(&mut self, len: u32) -> &mut Self {
+        assert_with_error!(self.buffer.env(), self.pos >= len, BufferReaderError::InvalidLength);
+        self.pos -= len;
+        self
+    }
+
+    // Generates: read_u8 (1 byte), read_u16 (2 bytes), read_u32 (4 bytes), read_u64 (8 bytes), read_u128 (16 bytes)
+    impl_read_uint!(read_u8, u8, 1; read_u16, u16, 2; read_u32, u32, 4; read_u64, u64, 8; read_u128, u128, 16);
+
+    /// Reads a boolean (1 byte, non-zero = true).
+    pub fn read_bool(&mut self) -> bool {
+        self.read_u8() != 0
+    }
+
+    /// Reads a U256 (32 bytes, big-endian).
+    pub fn read_u256(&mut self) -> U256 {
+        U256::from_be_bytes(self.buffer.env(), &self.read_bytes(32))
+    }
+
+    /// Reads a Stellar address (33 bytes: 1 type + 32 payload).
+    pub fn read_address(&mut self) -> Address {
+        let payload_type = self.read_u8();
+        let payload = self.read_address_payload();
+        self.compose_address(payload_type, payload)
+    }
+
+    /// Reads an address payload only from the buffer (32 bytes).
+    pub fn read_address_payload(&mut self) -> BytesN<32> {
+        self.read_bytes_n()
+    }
+
+    /// Reads N bytes as a fixed-size BytesN<N>.
+    pub fn read_bytes_n<const N: usize>(&mut self) -> BytesN<N> {
+        BytesN::<N>::from_array(self.buffer.env(), &self.read_bytes(N as u32).to_array())
+    }
+
+    /// Reads `len` bytes from current position and advances.
+    pub fn read_bytes(&mut self, len: u32) -> Bytes {
+        let end = self.pos + len;
+        assert_with_error!(self.buffer.env(), self.buffer.len() >= end, BufferReaderError::InvalidLength);
+
+        let value = self.buffer.slice(self.pos..end);
+        self.pos = end;
+        value
+    }
+
+    /// Reads all remaining bytes from current position to end.
+    pub fn read_bytes_until_end(&mut self) -> Bytes {
+        self.read_bytes(self.remaining())
+    }
+
+    /// Returns the current read position.
+    pub fn position(&self) -> u32 {
+        self.pos
+    }
+
+    /// Returns a reference to the underlying buffer.
+    pub fn buffer(&self) -> &Bytes {
+        self.buffer
+    }
+
+    /// Returns the total length of the buffer.
+    pub fn len(&self) -> u32 {
+        self.buffer.len()
+    }
+
+    /// Returns true if the buffer is empty.
+    pub fn is_empty(&self) -> bool {
+        self.buffer.is_empty()
+    }
+
+    /// Returns the number of bytes remaining after current position.
+    pub fn remaining(&self) -> u32 {
+        self.buffer.len() - self.pos
+    }
+
+    /// Returns the Soroban environment reference.
+    pub fn env(&self) -> &Env {
+        self.buffer.env()
+    }
+
+    // === Internal Functions ===
+
+    /// Compose an address from its type byte and 32-byte payload.
+    fn compose_address(&self, payload_type: u8, payload: BytesN<32>) -> Address {
+        let addr_payload = match payload_type {
+            ACCOUNT_PAYLOAD_TYPE => AddressPayload::AccountIdPublicKeyEd25519(payload),
+            CONTRACT_PAYLOAD_TYPE => AddressPayload::ContractIdHash(payload),
+            _ => panic_with_error!(self.buffer.env(), BufferReaderError::InvalidAddressPayload),
+        };
+        Address::from_payload(self.buffer.env(), addr_payload)
+    }
+}

package/contracts/utils/src/buffer_writer.rs

@@ -0,0 +1,117 @@
+use soroban_sdk::{address_payload::AddressPayload, Address, Bytes, BytesN, Env, U256};
+
+use crate::{errors::BufferWriterError, option_ext::OptionExt};
+
+/// Macro to generate write methods for primitive integer types (big-endian).
+macro_rules! impl_write_uint {
+    ($($method:ident, $type:ty);* $(;)?) => {
+        $(
+            pub fn $method(&mut self, value: $type) -> &mut Self {
+                self.buffer.extend_from_slice(&value.to_be_bytes());
+                self
+            }
+        )*
+    };
+}
+
+pub const ACCOUNT_PAYLOAD_TYPE: u8 = 0;
+pub const CONTRACT_PAYLOAD_TYPE: u8 = 1;
+
+/// A writer for serializing data to a byte buffer.
+///
+/// The writer maintains an internal byte buffer and provides methods to write
+/// various data types in big-endian format. All write operations return a
+/// mutable reference to the writer, enabling method chaining.
+///
+/// # Example
+/// ```ignore
+/// let mut writer = BufferWriter::new(&env);
+/// writer.write_u32(0x12345678)
+///       .write_bool(true)
+///       .write_bytes32(&bytes32);
+/// let bytes = writer.to_bytes();
+/// ```
+pub struct BufferWriter {
+    buffer: Bytes,
+}
+
+impl BufferWriter {
+    /// Create a new empty writer.
+    pub fn new(env: &Env) -> Self {
+        Self { buffer: Bytes::new(env) }
+    }
+
+    /// Create a new writer initialized with existing data.
+    pub fn from_bytes(buffer: Bytes) -> Self {
+        Self { buffer }
+    }
+
+    // Generates: write_u8 (1 byte), write_u16 (2 bytes), write_u32 (4 bytes), write_u64 (8 bytes), write_u128 (16 bytes)
+    impl_write_uint!(write_u8, u8; write_u16, u16; write_u32, u32; write_u64, u64; write_u128, u128);
+
+    /// Write a boolean value to the buffer (true as 1, false as 0).
+    pub fn write_bool(&mut self, value: bool) -> &mut Self {
+        self.write_u8(if value { 1 } else { 0 })
+    }
+
+    /// Write an unsigned 256-bit integer in big-endian format.
+    pub fn write_u256(&mut self, value: U256) -> &mut Self {
+        self.buffer.append(&value.to_be_bytes());
+        self
+    }
+
+    /// Write a byte slice to the buffer (appends without length prefix).
+    pub fn write_bytes(&mut self, bytes: &Bytes) -> &mut Self {
+        self.buffer.append(bytes);
+        self
+    }
+
+    /// Write a fixed-size BytesN<N> to the buffer.
+    pub fn write_bytes_n<const N: usize>(&mut self, bytes_n: &BytesN<N>) -> &mut Self {
+        self.buffer.extend_from_array(&bytes_n.to_array());
+        self
+    }
+
+    /// Write an address type and payload to the buffer (33 bytes: 1 type + 32 payload).
+    pub fn write_address(&mut self, address: &Address) -> &mut Self {
+        let (payload_type, payload) = self.decompose_address(address);
+        self.write_u8(payload_type).write_bytes_n(&payload)
+    }
+
+    /// Write an address payload only to the buffer (32 bytes).
+    pub fn write_address_payload(&mut self, address: &Address) -> &mut Self {
+        let (_, payload) = self.decompose_address(address);
+        self.write_bytes_n(&payload)
+    }
+
+    /// Get the complete buffer as a Bytes, consuming the writer.
+    pub fn to_bytes(self) -> Bytes {
+        let Self { buffer } = self;
+        buffer
+    }
+
+    /// Get the current length of the buffer.
+    pub fn len(&self) -> u32 {
+        self.buffer.len()
+    }
+
+    /// Check if the buffer is empty.
+    pub fn is_empty(&self) -> bool {
+        self.buffer.is_empty()
+    }
+
+    /// Get the environment from the buffer.
+    pub fn env(&self) -> &Env {
+        self.buffer.env()
+    }
+
+    // === Internal Functions ===
+
+    /// Decompose an address into its type byte and 32-byte payload.
+    fn decompose_address(&self, address: &Address) -> (u8, BytesN<32>) {
+        match address.to_payload().unwrap_or_panic(self.buffer.env(), BufferWriterError::InvalidAddressPayload) {
+            AddressPayload::AccountIdPublicKeyEd25519(p) => (ACCOUNT_PAYLOAD_TYPE, p),
+            AddressPayload::ContractIdHash(p) => (CONTRACT_PAYLOAD_TYPE, p),
+        }
+    }
+}

package/contracts/utils/src/bytes_ext.rs

@@ -0,0 +1,19 @@
+use soroban_sdk::{assert_with_error, Bytes};
+
+use crate::errors::BytesExtError;
+
+/// Extension trait for `Bytes` to convert to fixed-size arrays
+pub trait BytesExt {
+    /// Copies the entire bytes into a fixed-size array.
+    /// Panics if bytes length != N.
+    fn to_array<const N: usize>(&self) -> [u8; N];
+}
+
+impl BytesExt for Bytes {
+    fn to_array<const N: usize>(&self) -> [u8; N] {
+        assert_with_error!(self.env(), self.len() == N as u32, BytesExtError::LengthMismatch);
+        let mut buf = [0u8; N];
+        self.copy_into_slice(&mut buf);
+        buf
+    }
+}

package/contracts/utils/src/errors.rs

@@ -0,0 +1,30 @@
+use common_macros::contract_error;
+
+#[contract_error]
+pub enum BufferReaderError {
+    InvalidLength = 10000,
+    InvalidAddressPayload,
+}
+
+#[contract_error]
+pub enum BufferWriterError {
+    InvalidAddressPayload = 10100,
+}
+
+#[contract_error]
+pub enum TtlError {
+    InvalidTtlConfig = 10200,
+    TtlConfigFrozen,
+    TtlConfigAlreadyFrozen,
+}
+
+#[contract_error]
+pub enum OwnableError {
+    OwnerAlreadySet = 10300,
+    OwnerNotSet,
+}
+
+#[contract_error]
+pub enum BytesExtError {
+    LengthMismatch = 10400,
+}

package/contracts/utils/src/lib.rs

@@ -0,0 +1,15 @@
+#![no_std]
+
+pub mod buffer_reader;
+pub mod buffer_writer;
+pub mod bytes_ext;
+pub mod errors;
+pub mod option_ext;
+pub mod ownable;
+pub mod ttl;
+
+#[cfg(test)]
+mod tests;
+
+#[cfg(any(test, feature = "testutils"))]
+pub mod testing_utils;

package/contracts/utils/src/option_ext.rs

@@ -0,0 +1,38 @@
+use soroban_sdk::{panic_with_error, Env};
+
+/// Extension trait for `Option<T>` that provides Soroban-specific unwrapping utilities.
+///
+/// This trait extends the standard `Option` type with methods that integrate with
+/// Soroban's error handling system, allowing for more descriptive panics when
+/// unwrapping fails.
+pub trait OptionExt<T> {
+    /// Unwraps the `Option`, returning the contained value if `Some`,
+    /// or panics with the provided error if `None`.
+    ///
+    /// # Arguments
+    /// * `env` - The Soroban environment, required for error propagation.
+    /// * `error` - The error to emit if the `Option` is `None`. Must be convertible into a `soroban_sdk::Error`.
+    ///
+    /// # Returns
+    /// The contained value if `Some`.
+    ///
+    /// # Panics
+    /// Panics with the specified error if the `Option` is `None`.
+    fn unwrap_or_panic<E>(self, env: &Env, error: E) -> T
+    where
+        E: Into<soroban_sdk::Error>;
+}
+
+impl<T> OptionExt<T> for Option<T> {
+    fn unwrap_or_panic<E>(self, env: &Env, error: E) -> T
+    where
+        E: Into<soroban_sdk::Error>,
+    {
+        match self {
+            // Return the inner value if present
+            Some(val) => val,
+            // Panic with the provided error if None, using Soroban's error macro
+            None => panic_with_error!(env, error),
+        }
+    }
+}