@layerzerolabs/protocol-stellar-v2 0.2.8 → 0.2.9

package/contracts/oapps/oft/src/oft_types/lock_unlock.rs

@@ -0,0 +1,50 @@
+//! LockUnlock type implementation for OFT.
+//!
+//! This OFT type locks tokens in the contract on debit (send) and unlocks
+//! tokens from the contract on credit (receive).
+//! Used for OFT adapters that wrap existing tokens.
+
+use soroban_sdk::{token::TokenClient, Address, Env};
+
+use crate::oft::OFT;
+use crate::types::OFTReceipt;
+
+/// Debit tokens using LockUnlock OFT type (locks tokens in contract).
+///
+/// # Parameters
+/// * `env` - The Soroban environment
+/// * `sender` - Address of the token sender
+/// * `amount_ld` - Amount to debit in local decimals
+/// * `min_amount_ld` - Minimum amount that must be received (for slippage protection)
+/// * `dst_eid` - Destination endpoint ID
+///
+/// # Returns
+/// `OFTReceipt` containing the amount sent and amount received
+pub fn debit<T: OFT>(env: &Env, sender: &Address, amount_ld: i128, min_amount_ld: i128, dst_eid: u32) -> OFTReceipt {
+    let receipt: OFTReceipt = T::__debit_view(env, amount_ld, min_amount_ld, dst_eid);
+    TokenClient::new(env, &T::token(env)).transfer(sender, env.current_contract_address(), &receipt.amount_sent_ld);
+    receipt
+}
+
+/// Credit tokens using LockUnlock OFT type (unlocks tokens from contract).
+///
+/// # Parameters
+/// * `env` - The Soroban environment
+/// * `to` - Address of the token recipient
+/// * `amount_ld` - Amount to credit in local decimals
+/// * `_src_eid` - Source endpoint ID (unused)
+///
+/// # Returns
+/// The amount credited
+pub fn credit<T: OFT>(env: &Env, to: &Address, amount_ld: i128, _src_eid: u32) -> i128 {
+    TokenClient::new(env, &T::token(env)).transfer(&env.current_contract_address(), to, &amount_ld);
+    amount_ld
+}
+
+/// Returns whether approval is required for LockUnlock OFT type.
+///
+/// # Returns
+/// Always `false` - approval not needed for transfer operations
+pub fn approval_required() -> bool {
+    false
+}

package/contracts/oapps/oft/src/oft_types/mint_burn.rs

@@ -0,0 +1,50 @@
+//! MintBurn type implementation for OFT.
+//!
+//! This OFT type burns tokens on debit (send) and mints tokens on credit (receive).
+//! Used when the OFT contract has mint/burn authority over the token.
+
+use soroban_sdk::{Address, Env};
+
+use crate::interfaces::MintBurnTokenClient;
+use crate::oft::OFT;
+use crate::types::OFTReceipt;
+
+/// Debit tokens using MintBurn OFT type (burns tokens from sender).
+///
+/// # Parameters
+/// * `env` - The Soroban environment
+/// * `sender` - Address of the token sender
+/// * `amount_ld` - Amount to debit in local decimals
+/// * `min_amount_ld` - Minimum amount that must be received (for slippage protection)
+/// * `dst_eid` - Destination endpoint ID
+///
+/// # Returns
+/// `OFTReceipt` containing the amount sent and amount received
+pub fn debit<T: OFT>(env: &Env, sender: &Address, amount_ld: i128, min_amount_ld: i128, dst_eid: u32) -> OFTReceipt {
+    let receipt = T::__debit_view(env, amount_ld, min_amount_ld, dst_eid);
+    MintBurnTokenClient::new(env, &T::token(env)).burn(sender, &receipt.amount_sent_ld);
+    receipt
+}
+
+/// Credit tokens using MintBurn OFT type (mints tokens to recipient).
+///
+/// # Parameters
+/// * `env` - The Soroban environment
+/// * `to` - Address of the token recipient
+/// * `amount_ld` - Amount to credit in local decimals
+/// * `_src_eid` - Source endpoint ID (unused)
+///
+/// # Returns
+/// The amount credited
+pub fn credit<T: OFT>(env: &Env, to: &Address, amount_ld: i128, _src_eid: u32) -> i128 {
+    MintBurnTokenClient::new(env, &T::token(env)).mint(to, &amount_ld);
+    amount_ld
+}
+
+/// Returns whether approval is required for MintBurn OFT type.
+///
+/// # Returns
+/// Always `false` - approval not needed for mint/burn operations.
+pub fn approval_required() -> bool {
+    false
+}

package/contracts/oapps/oft/src/oft_types/mod.rs

@@ -0,0 +1,10 @@
+//! OFT types implementations.
+//!
+//! This module provides reference implementations for the two main OFT types:
+//!
+//! - **MintBurn**: Burns tokens on send, mints on receive. Approval not required.
+//! - **LockUnlock**: Locks tokens on send, unlocks on receive. Approval not required.
+//!
+
+pub mod lock_unlock;
+pub mod mint_burn;

package/contracts/oapps/oft/src/storage.rs

@@ -0,0 +1,11 @@
+use common_macros::storage;
+use soroban_sdk::Address;
+
+#[storage]
+pub enum OFTStorage {
+    #[instance(i128)]
+    DecimalConversionRate,
+
+    #[instance(Address)]
+    Token,
+}

package/contracts/oapps/oft/src/tests/mod.rs

@@ -0,0 +1,13 @@
+pub mod test_utils;
+
+pub mod test_oft_compose_msg_codec;
+pub mod test_oft_msg_codec;
+
+pub mod test_decimals;
+pub mod test_lz_receive;
+pub mod test_oft_version;
+pub mod test_quote_oft;
+pub mod test_quote_send;
+pub mod test_resolve_address;
+pub mod test_send;
+pub mod test_token;

package/contracts/oapps/oft/src/tests/test_decimals.rs

@@ -0,0 +1,89 @@
+use super::test_utils::OFTTestSetup;
+use crate::{
+    tests::test_utils::OFTTestSetupBuilder,
+    utils::{to_ld, to_sd},
+};
+use soroban_sdk::Env;
+
+#[test]
+fn test_decimal_conversion_rate() {
+    let env = Env::default();
+    let setup = OFTTestSetup::new(&env);
+
+    // SAC has 7 decimals, shared decimals is 6
+    // conversion_rate = 10^(7-6) = 10
+    let rate = setup.oft.decimal_conversion_rate();
+    assert_eq!(rate, 10_i128.pow(setup.token_decimals - setup.shared_decimals));
+}
+
+#[test]
+#[should_panic(expected = "Error(Contract, #2100)")] // InvalidLocalDecimals
+fn test_invalid_local_decimals() {
+    let env = Env::default();
+    OFTTestSetupBuilder::new(&env).with_token_decimals(5).with_shared_decimals(6).build();
+}
+
+#[test]
+#[should_panic]
+fn test_to_ld_overflow() {
+    // 10^38 * 10 > i128::MAX - should overflow
+    let conversion_rate = 10_i128.pow(38);
+    let amount_sd = 10u64;
+
+    to_ld(amount_sd, conversion_rate);
+}
+
+#[test]
+#[should_panic(expected = "Error(Contract, #2101)")] // Overflow
+fn test_to_sd_overflow() {
+    let env = Env::default();
+
+    // u64::MAX + 1 exceeds u64 range - should overflow
+    let conversion_rate = 1i128;
+    let amount_ld = u64::MAX as i128 + 1;
+
+    to_sd(&env, amount_ld, conversion_rate);
+}
+
+// ==================== Positive Conversion Tests ====================
+
+#[test]
+fn test_to_ld_basic() {
+    // Conversion rate = 10 (7 decimals - 6 shared = 1 decimal difference)
+    let conversion_rate = 10i128;
+
+    assert_eq!(to_ld(0, conversion_rate), 0);
+    assert_eq!(to_ld(1, conversion_rate), 10);
+    assert_eq!(to_ld(100, conversion_rate), 1_000);
+    assert_eq!(to_ld(1_000_000, conversion_rate), 10_000_000);
+}
+
+#[test]
+fn test_to_sd_basic() {
+    let env = Env::default();
+
+    // Conversion rate = 10 (7 decimals - 6 shared = 1 decimal difference)
+    let conversion_rate = 10i128;
+
+    assert_eq!(to_sd(&env, 0, conversion_rate), 0);
+    assert_eq!(to_sd(&env, 10, conversion_rate), 1);
+    assert_eq!(to_sd(&env, 1_000, conversion_rate), 100);
+    assert_eq!(to_sd(&env, 10_000_000, conversion_rate), 1_000_000);
+}
+
+#[test]
+fn test_to_sd_truncates_dust() {
+    let env = Env::default();
+
+    // Conversion rate = 10
+    let conversion_rate = 10i128;
+
+    // 15 LD → 1 SD (5 is dust, truncated via division)
+    assert_eq!(to_sd(&env, 15, conversion_rate), 1);
+
+    // 19 LD → 1 SD (9 is dust, truncated)
+    assert_eq!(to_sd(&env, 19, conversion_rate), 1);
+
+    // 20 LD → 2 SD (exact)
+    assert_eq!(to_sd(&env, 20, conversion_rate), 2);
+}

package/contracts/oapps/oft/src/tests/test_lz_receive.rs

@@ -0,0 +1,282 @@
+use super::test_utils::OFTTestSetup;
+use crate::{
+    events::OFTReceived,
+    tests::test_utils::{
+        create_origin, create_recipient_address, encode_oft_message, encode_oft_message_with_compose,
+        generate_g_address, OFTTestSetupBuilder,
+    },
+    utils::address_to_bytes32,
+};
+use endpoint_v2::LayerZeroReceiverClient;
+use soroban_sdk::{testutils::Address as _, Address, Bytes, BytesN, Env};
+use utils::testing_utils::assert_event;
+
+// Helper function to reduce code duplication for lz_receive tests
+fn run_lz_receive_test(setup: &OFTTestSetup, recipient: &Address, amount_sd: u64) {
+    let env = setup.env;
+    let executor = Address::generate(env);
+
+    let src_eid = 100u32;
+    let peer = BytesN::from_array(env, &[2u8; 32]);
+    setup.set_peer(src_eid, &peer);
+
+    // Check initial balance
+    let initial_balance = setup.token_client.balance(recipient);
+    let initial_oft_balance =
+        if setup.is_lock_unlock() { Some(setup.token_client.balance(&setup.oft.address)) } else { None };
+
+    // Create OFT message
+    let recipient_bytes32 = address_to_bytes32(recipient);
+    let message = encode_oft_message(env, &recipient_bytes32, amount_sd);
+
+    let guid = BytesN::from_array(env, &[1u8; 32]);
+    let origin = create_origin(src_eid, &peer, 1);
+    let extra_data = Bytes::new(env);
+
+    // Verify recipient received tokens
+    let conversion_rate = setup.oft.decimal_conversion_rate();
+    let expected_amount_ld = (amount_sd as i128) * conversion_rate;
+    setup.lz_receive(&executor, &origin, &guid, &message, &extra_data, 0);
+    assert_event(
+        env,
+        &setup.oft.address,
+        OFTReceived { guid: guid.clone(), src_eid, to: recipient.clone(), amount_received_ld: expected_amount_ld },
+    );
+    if setup.issuer == *recipient {
+        assert_eq!(setup.token_client.balance(recipient), i64::MAX as i128);
+    } else {
+        assert_eq!(setup.token_client.balance(recipient), initial_balance + expected_amount_ld);
+    }
+
+    // For LockUnlock strategy, verify OFT contract balance decreased
+    if let Some(initial_oft) = initial_oft_balance {
+        assert_eq!(setup.token_client.balance(&setup.oft.address), initial_oft - expected_amount_ld);
+    }
+}
+
+// ==================== MintBurn Strategy Tests ====================
+
+#[test]
+fn test_mint_burn_sac_lz_receive_to_c_address() {
+    let env = Env::default();
+    let recipient = create_recipient_address(&env);
+    let setup = OFTTestSetupBuilder::new(&env).with_sac().build();
+    run_lz_receive_test(&setup, &recipient, 1_000_000u64);
+}
+
+#[test]
+fn test_mint_burn_contract_token_lz_receive_to_c_address() {
+    let env = Env::default();
+    let recipient = create_recipient_address(&env);
+    let setup = OFTTestSetup::new(&env);
+    run_lz_receive_test(&setup, &recipient, 1_000_000u64);
+}
+
+#[test]
+#[should_panic(expected = "HostError: Error(Contract, #13)")] // trustline entry is missing for account
+fn test_mint_burn_sac_lz_receive_to_g_address_with_no_trustline() {
+    let env = Env::default();
+    let recipient = generate_g_address(&env);
+    let setup = OFTTestSetupBuilder::new(&env).with_sac().build();
+    run_lz_receive_test(&setup, &recipient, 1_000_000u64);
+}
+
+#[test]
+#[should_panic(expected = "HostError: Error(Contract, #2)")] // operation invalid on issuer
+fn test_mint_burn_sac_lz_receive_to_issuer() {
+    let env = Env::default();
+    let setup = OFTTestSetupBuilder::new(&env).with_sac().build();
+    run_lz_receive_test(&setup, &setup.issuer, 1_000_000u64);
+}
+
+#[test]
+fn test_mint_burn_contract_token_lz_receive_to_g_address() {
+    let env = Env::default();
+    let recipient = generate_g_address(&env);
+    let setup = OFTTestSetup::new(&env);
+    run_lz_receive_test(&setup, &recipient, 1_000_000u64);
+}
+
+#[test]
+fn test_mint_burn_lz_receive_with_compose() {
+    let env = Env::default();
+    let setup = OFTTestSetup::new(&env);
+
+    let executor = Address::generate(&env);
+    let recipient = create_recipient_address(&env);
+    let sender_on_src = Address::generate(&env);
+
+    let src_eid = 100u32;
+    let peer = BytesN::from_array(&env, &[2u8; 32]);
+    setup.set_peer(src_eid, &peer);
+
+    // Create OFT message with compose
+    let recipient_bytes32 = address_to_bytes32(&recipient);
+    let compose_from = address_to_bytes32(&sender_on_src);
+    let compose_msg = Bytes::from_array(&env, b"test compose payload");
+    let amount_sd = 1000000u64;
+    let message = encode_oft_message_with_compose(&env, &recipient_bytes32, amount_sd, &compose_from, &compose_msg);
+
+    let guid = BytesN::from_array(&env, &[1u8; 32]);
+    let origin = create_origin(src_eid, &peer, 1);
+    let extra_data = Bytes::new(&env);
+
+    // Verify compose not called yet
+    assert!(!setup.endpoint_client.was_composed());
+
+    // Execute lz_receive
+    setup.lz_receive(&executor, &origin, &guid, &message, &extra_data, 0);
+
+    // Verify tokens were credited
+    let conversion_rate = setup.oft.decimal_conversion_rate();
+    let expected_amount_ld = (amount_sd as i128) * conversion_rate;
+    assert_eq!(setup.token_client.balance(&recipient), expected_amount_ld);
+
+    // Verify compose was called
+    assert!(setup.endpoint_client.was_composed());
+
+    // Verify compose recipient
+    let compose_to = setup.endpoint_client.get_compose_to().unwrap();
+    assert_eq!(compose_to, recipient);
+}
+
+#[test]
+fn test_mint_burn_lz_receive_zero_amount() {
+    let env = Env::default();
+    let recipient = create_recipient_address(&env);
+    let setup = OFTTestSetup::new(&env);
+    run_lz_receive_test(&setup, &recipient, 0u64);
+}
+
+// ==================== Lock/Unlock Strategy Tests ====================
+
+#[test]
+fn test_lock_unlock_sac_lz_receive_to_c_address() {
+    let env = Env::default();
+    let recipient = create_recipient_address(&env);
+    let setup = OFTTestSetupBuilder::new(&env).lock_unlock().with_sac().build();
+    run_lz_receive_test(&setup, &recipient, 1_000_000u64);
+}
+
+#[test]
+fn test_lock_unlock_contract_token_lz_receive_to_c_address() {
+    let env = Env::default();
+    let recipient = create_recipient_address(&env);
+    let setup = OFTTestSetupBuilder::new(&env).lock_unlock().build();
+    run_lz_receive_test(&setup, &recipient, 1_000_000u64);
+}
+
+#[test]
+#[should_panic(expected = "HostError: Error(Contract, #13)")] // trustline entry is missing for account
+fn test_lock_unlock_sac_lz_receive_to_g_address_with_no_trustline() {
+    let env = Env::default();
+    let recipient = generate_g_address(&env);
+    let setup = OFTTestSetupBuilder::new(&env).lock_unlock().with_sac().build();
+    run_lz_receive_test(&setup, &recipient, 1_000_000u64);
+}
+
+#[test]
+fn test_lock_unlock_sac_lz_receive_to_issuer() {
+    let env = Env::default();
+    let setup = OFTTestSetupBuilder::new(&env).lock_unlock().with_sac().build();
+    run_lz_receive_test(&setup, &setup.issuer, 1_000_000u64);
+}
+
+#[test]
+fn test_lock_unlock_contract_token_lz_receive_to_g_address() {
+    let env = Env::default();
+    let recipient = generate_g_address(&env);
+    let setup = OFTTestSetupBuilder::new(&env).lock_unlock().build();
+    run_lz_receive_test(&setup, &recipient, 1_000_000u64);
+}
+
+#[test]
+fn test_lock_unlock_lz_receive_with_compose() {
+    let env = Env::default();
+    let setup = OFTTestSetupBuilder::new(&env).lock_unlock().build();
+
+    let executor = Address::generate(&env);
+    let recipient = create_recipient_address(&env);
+    let sender_on_src = Address::generate(&env);
+
+    let src_eid = 100u32;
+    let peer = BytesN::from_array(&env, &[2u8; 32]);
+    setup.set_peer(src_eid, &peer);
+
+    // Create OFT message with compose
+    let recipient_bytes32 = address_to_bytes32(&recipient);
+    let compose_from = address_to_bytes32(&sender_on_src);
+    let compose_msg = Bytes::from_array(&env, b"test compose payload");
+    let amount_sd = 1000000u64;
+    let message = encode_oft_message_with_compose(&env, &recipient_bytes32, amount_sd, &compose_from, &compose_msg);
+
+    let guid = BytesN::from_array(&env, &[1u8; 32]);
+    let origin = create_origin(src_eid, &peer, 1);
+    let extra_data = Bytes::new(&env);
+
+    // Verify compose not called yet
+    assert!(!setup.endpoint_client.was_composed());
+
+    // Execute lz_receive
+    setup.lz_receive(&executor, &origin, &guid, &message, &extra_data, 0);
+
+    // Verify tokens were credited
+    let conversion_rate = setup.oft.decimal_conversion_rate();
+    let expected_amount_ld = (amount_sd as i128) * conversion_rate;
+    assert_eq!(setup.token_client.balance(&recipient), expected_amount_ld);
+
+    // Verify compose was called
+    assert!(setup.endpoint_client.was_composed());
+
+    // Verify compose recipient
+    let compose_to = setup.endpoint_client.get_compose_to().unwrap();
+    assert_eq!(compose_to, recipient);
+}
+
+#[test]
+fn test_lock_unlock_lz_receive_zero_amount() {
+    let env = Env::default();
+    let recipient = create_recipient_address(&env);
+    let setup = OFTTestSetupBuilder::new(&env).lock_unlock().build();
+    run_lz_receive_test(&setup, &recipient, 0u64);
+}
+
+// ==================== Authorizations Tests ====================
+
+#[test]
+#[should_panic(expected = "HostError: Error(Auth, InvalidAction)")]
+fn test_lz_receive_without_giving_authorization() {
+    let env = Env::default();
+    let setup = OFTTestSetup::new(&env);
+
+    let executor = Address::generate(&env);
+    let recipient = create_recipient_address(&env);
+
+    // Set peer
+    let src_eid = 100u32;
+    let peer = BytesN::from_array(&env, &[2u8; 32]);
+    setup.set_peer(src_eid, &peer);
+
+    // Check initial balance
+    assert_eq!(setup.token_client.balance(&recipient), 0);
+
+    // Create OFT message
+    let recipient_bytes32 = address_to_bytes32(&recipient);
+    let amount_sd = 1000000u64; // 1 token in shared decimals
+    let message = encode_oft_message(&env, &recipient_bytes32, amount_sd);
+
+    // Create origin
+    let guid = BytesN::from_array(&env, &[1u8; 32]);
+    let origin = create_origin(src_eid, &peer, 1);
+    let extra_data = Bytes::new(&env);
+
+    // Execute lz_receive
+    LayerZeroReceiverClient::new(setup.env, &setup.oft.address).lz_receive(
+        &executor,
+        &origin,
+        &guid,
+        &message,
+        &extra_data,
+        &0i128,
+    );
+}

package/contracts/oapps/oft/src/tests/test_oft_compose_msg_codec.rs

@@ -0,0 +1,68 @@
+use crate::codec::oft_compose_msg_codec::OFTComposeMsg;
+use soroban_sdk::{Bytes, BytesN, Env};
+
+#[test]
+fn test_encode_and_decode_basic() {
+    let env = Env::default();
+    let nonce = 12345u64;
+    let src_eid = 101u32;
+    let amount_ld = 1_000_000_000i128; // 1 token with 9 decimals
+    let compose_from = BytesN::from_array(&env, &[0x42u8; 32]);
+    let compose_msg = Bytes::from_array(&env, b"test compose message");
+
+    let msg = OFTComposeMsg {
+        nonce,
+        src_eid,
+        amount_ld,
+        compose_from: compose_from.clone(),
+        compose_msg: compose_msg.clone(),
+    };
+
+    let encoded = msg.encode(&env);
+    let decoded = OFTComposeMsg::decode(&encoded);
+
+    assert_eq!(decoded.nonce, nonce);
+    assert_eq!(decoded.src_eid, src_eid);
+    assert_eq!(decoded.amount_ld, amount_ld);
+    assert_eq!(decoded.compose_from, compose_from);
+    assert_eq!(decoded.compose_msg, compose_msg);
+}
+
+#[test]
+fn test_encode_with_empty_compose_msg() {
+    let env = Env::default();
+    let nonce = 123u64;
+    let src_eid = 1u32;
+    let amount_ld = 1_000_000i128;
+    let compose_from = BytesN::from_array(&env, &[0x11u8; 32]);
+    let compose_msg = Bytes::new(&env); // Empty
+
+    let msg = OFTComposeMsg { nonce, src_eid, amount_ld, compose_from: compose_from.clone(), compose_msg };
+
+    let encoded = msg.encode(&env);
+    let decoded = OFTComposeMsg::decode(&encoded);
+
+    assert_eq!(decoded.nonce, nonce);
+    assert_eq!(decoded.src_eid, src_eid);
+    assert_eq!(decoded.amount_ld, amount_ld);
+    assert_eq!(decoded.compose_from, compose_from);
+    assert_eq!(decoded.compose_msg.len(), 0);
+}
+
+#[test]
+#[should_panic]
+fn test_decode_panic_on_empty_data() {
+    let env = Env::default();
+    let data = Bytes::new(&env);
+    OFTComposeMsg::decode(&data);
+}
+
+#[test]
+#[should_panic]
+fn test_decode_panic_on_insufficient_data() {
+    let env = Env::default();
+    let mut data = Bytes::new(&env);
+    // Only 30 bytes - not enough for nonce(8) + src_eid(4) + amount_ld(16) + compose_from(32) = 60 bytes minimum
+    data.extend_from_array(&[0u8; 30]);
+    OFTComposeMsg::decode(&data);
+}