@layerzerolabs/protocol-stellar-v2 0.2.40 → 0.2.43

package/contracts/common-macros/src/upgradeable.rs

@@ -4,7 +4,7 @@ use proc_macro2::TokenStream;
 use quote::quote;
 use syn::{
     parse::{Parse, ParseStream},
-    Ident, ItemStruct,
+    Ident, ItemStruct, Token,
 };
 
 /// Configuration options for the `#[upgradeable]` macro.
@@ -13,51 +13,52 @@ pub struct UpgradeableConfig {
     /// If true, generates a default no-op `UpgradeableInternal` implementation.
     /// Use this for initial deployments when no migration logic is needed yet.
     pub no_migration: bool,
+    /// If true, uses `UpgradeableRbac` (Auth + RoleBased) instead of `Upgradeable` (Auth only).
+    pub rbac: bool,
 }
 
 impl Parse for UpgradeableConfig {
     fn parse(input: ParseStream) -> syn::Result<Self> {
+        let mut config = Self::default();
         if input.is_empty() {
-            return Ok(Self::default());
+            return Ok(config);
         }
 
-        let ident: Ident = input.parse()?;
-        if ident == "no_migration" {
-            Ok(Self { no_migration: true })
-        } else {
-            Err(syn::Error::new(ident.span(), "expected `no_migration`"))
+        while !input.is_empty() {
+            let ident: Ident = input.parse()?;
+            match ident.to_string().as_str() {
+                "no_migration" => config.no_migration = true,
+                "rbac" => config.rbac = true,
+                _ => return Err(syn::Error::new(ident.span(), "expected `no_migration` or `rbac`")),
+            }
+
+            // Consume optional trailing comma
+            if input.peek(Token![,]) {
+                input.parse::<Token![,]>()?;
+            }
         }
+        Ok(config)
     }
 }
 
 /// Generates the upgradeable implementation from the `#[upgradeable]` attribute macro.
 ///
-/// This function generates the implementation of the `Upgradeable` trait for a
-/// given contract type, enabling the contract to be upgraded by replacing its
-/// WASM bytecode with migration support.
+/// Generates an impl of `Upgradeable` or `UpgradeableRbac` for a contract type,
+/// enabling upgrades by replacing WASM bytecode with migration support.
 ///
 /// # Behavior
 ///
-/// - Implements the `Upgradeable` trait using its default methods (which include auth).
+/// - By default implements `Upgradeable` (Auth-based, `#[only_auth]`). With `rbac`,
+///   implements `UpgradeableRbac` (Auth + RoleBased, `UPGRADER_ROLE`).
 /// - Sets the contract crate version as `"binver"` metadata using
-///   `soroban_sdk::contractmeta!`. Gets the crate version via the env variable
-///   `CARGO_PKG_VERSION` which corresponds to the "version" attribute in
-///   Cargo.toml. If no such attribute or if it is "0.0.0", skips this step.
-/// - By default, requires the contract to implement `UpgradeableInternal` trait.
-/// - With `no_migration` flag, generates a default no-op `UpgradeableInternal` impl.
-///
-/// # Example
-/// ```ignore
-/// // Requires manual UpgradeableInternal implementation (default, safety first)
-/// #[ownable]
-/// #[upgradeable]
-/// pub struct MyContract;
+///   `soroban_sdk::contractmeta!`. Uses `CARGO_PKG_VERSION` (from Cargo.toml
+///   `[package]` version). Skips if missing or `"0.0.0"`.
+/// - By default, requires the contract to implement `UpgradeableInternal`.
+/// - With `no_migration`, generates a no-op `UpgradeableInternal` impl.
+/// - With `rbac`, uses `UpgradeableRbac` (requires `RoleBasedAccessControl`, which
+///   extends `Auth`) instead of `Upgradeable` (requires `Auth`).
 ///
-/// // Auto-generates no-op UpgradeableInternal (for initial deployment)
-/// #[ownable]
-/// #[upgradeable(no_migration)]
-/// pub struct MyContract;
-/// ```
+/// See the `#[upgradeable]` macro documentation for full examples.
 pub fn generate_upgradeable_impl(attr: TokenStream, input: TokenStream) -> TokenStream {
     let config: UpgradeableConfig =
         syn::parse2(attr).unwrap_or_else(|e| panic!("failed to parse upgradeable config: {}", e));
@@ -78,17 +79,23 @@ pub fn generate_upgradeable_impl(attr: TokenStream, input: TokenStream) -> Token
         quote! {}
     };
 
+    let trait_path = if config.rbac {
+        quote! { utils::upgradeable::UpgradeableRbac }
+    } else {
+        quote! { utils::upgradeable::Upgradeable }
+    };
+
     quote! {
         #item_struct
 
-        use utils::upgradeable::Upgradeable as _;
+        use #trait_path as _;
 
         #binver
 
         #default_internal_impl
 
         #[common_macros::contract_impl(contracttrait)]
-        impl utils::upgradeable::Upgradeable for #name {}
+        impl #trait_path for #name {}
     }
 }
 

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

@@ -52,7 +52,7 @@ impl ILayerZeroEndpointV2 for EndpointV2 {
         let packet = Self::build_outbound_packet(env, sender, *dst_eid, receiver, message, nonce);
 
         let fee = SendLibClient::new(env, &send_lib).quote(&packet, options, pay_in_zro);
-        assert_with_error!(env, fee.native_fee >= 0 && fee.zro_fee >= 0, EndpointError::InvalidFeeAmount);
+        assert_with_error!(env, fee.native_fee >= 0 && fee.zro_fee >= 0, EndpointError::InvalidAmount);
 
         fee
     }
@@ -127,6 +127,7 @@ impl ILayerZeroEndpointV2 for EndpointV2 {
         reason: &Bytes,
     ) {
         executor.require_auth();
+        assert_with_error!(env, gas >= 0 && value >= 0, EndpointError::InvalidAmount);
         LzReceiveAlert {
             receiver: receiver.clone(),
             executor: executor.clone(),
@@ -257,7 +258,7 @@ impl EndpointV2 {
             // Fee amounts are modeled as non-negative values. The field type is i128 for
             // compatibility with token APIs, but negative fees are always invalid and rejected
             // here, while zero amounts are treated as a no-op (skipped by the check below).
-            assert_with_error!(env, r.amount >= 0, EndpointError::InvalidFeeAmount);
+            assert_with_error!(env, r.amount >= 0, EndpointError::InvalidAmount);
             if r.amount > 0 {
                 assert_with_error!(env, native_fee_supplied >= r.amount, EndpointError::InsufficientNativeFee);
                 native_fee_supplied -= r.amount;
@@ -286,7 +287,7 @@ impl EndpointV2 {
                 // Fee amounts are modeled as non-negative values. The field type is i128 for
                 // compatibility with token APIs, but negative fees are always invalid and rejected
                 // here, while zero amounts are treated as a no-op (skipped by the check below).
-                assert_with_error!(env, r.amount >= 0, EndpointError::InvalidFeeAmount);
+                assert_with_error!(env, r.amount >= 0, EndpointError::InvalidAmount);
                 if r.amount > 0 {
                     assert_with_error!(env, zro_fee_supplied >= r.amount, EndpointError::InsufficientZroFee);
                     zro_fee_supplied -= r.amount;

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

@@ -18,8 +18,8 @@ pub enum EndpointError {
     InsufficientZroFee,
     /// Timeout expiry is invalid (already expired)
     InvalidExpiry,
-    /// Fee amount is invalid (negative)
-    InvalidFeeAmount,
+    /// Amount is invalid (negative)
+    InvalidAmount,
     /// Compose index exceeds maximum allowed value
     InvalidIndex,
     /// Nonce is invalid for the requested operation

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

@@ -322,5 +322,16 @@ mod test {
         ) {
             Self::clear_payload(env, receiver, src_eid, sender, nonce, payload)
         }
+
+        /// Test-only wrapper for insert_and_drain_pending_nonces.
+        pub fn insert_and_drain_pending_nonces_for_test(
+            env: &Env,
+            receiver: &Address,
+            src_eid: u32,
+            sender: &BytesN<32>,
+            new_nonce: u64,
+        ) {
+            Self::insert_and_drain_pending_nonces(env, receiver, src_eid, sender, new_nonce)
+        }
     }
 }

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

@@ -73,6 +73,7 @@ impl IMessagingComposer for EndpointV2 {
         reason: &Bytes,
     ) {
         executor.require_auth();
+        assert_with_error!(env, gas >= 0 && value >= 0, EndpointError::InvalidAmount);
         assert_compose_index(env, index);
         LzComposeAlert {
             executor: executor.clone(),

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

@@ -92,33 +92,18 @@ fn test_clear_removes_inbound_payload_hash() {
     // Now clear the payload
     clear_packet_with_auth(&context, &receiver, &origin, &receiver, &guid, &message);
 
+    // Verify PacketDelivered event was emitted.
+    assert_eq_event(
+        env,
+        &endpoint_client.address,
+        PacketDelivered { origin: origin.clone(), receiver: receiver.clone() },
+    );
+
     // Verify payload hash was removed via public interface
     let stored_hash = endpoint_client.inbound_payload_hash(&receiver, &src_eid, &sender, &nonce);
     assert_eq!(stored_hash, None);
 }
 
-// Event emission
-#[test]
-fn test_clear_emits_packet_delivered_event() {
-    let context = setup();
-    let env = &context.env;
-    let endpoint_client = &context.endpoint_client;
-
-    let src_eid = 2u32;
-    let sender = BytesN::from_array(env, &[1u8; 32]);
-    let receiver = env.register(MockReceiver, ());
-    let nonce = 1u64;
-
-    let message = Bytes::from_array(env, &[1, 2, 3, 4]);
-    let guid = BytesN::from_array(env, &[5u8; 32]);
-    let (_receive_lib, origin, _payload_hash) =
-        arrange_verified_packet_with_auth(&context, src_eid, &sender, &receiver, nonce, &guid, &message);
-
-    clear_packet_with_auth(&context, &receiver, &origin, &receiver, &guid, &message);
-
-    assert_eq_event(env, &endpoint_client.address, PacketDelivered { origin: origin.clone(), receiver: receiver.clone() });
-}
-
 // Inbound nonce is advanced during verify, not during clear
 #[test]
 fn test_clear_does_not_change_inbound_nonce() {
@@ -147,7 +132,7 @@ fn test_clear_does_not_change_inbound_nonce() {
 
 // Sequential nonce behavior
 #[test]
-fn test_clear_success_sequential_nonces_update_lazy_nonce_to_latest() {
+fn test_clear_success_sequential_nonces_keep_inbound_nonce_at_latest_verified() {
     let context = setup();
     let env = &context.env;
     let endpoint_client = &context.endpoint_client;
@@ -175,8 +160,10 @@ fn test_clear_success_sequential_nonces_update_lazy_nonce_to_latest() {
     let origin2 = Origin { src_eid, sender: sender.clone(), nonce: 2 };
 
     verify_packet_with_auth(&context, &receive_lib, &origin2, &receiver, &payload_hash2);
-    clear_packet_with_auth(&context, &receiver, &origin2, &receiver, &guid2, &message2);
 
+    assert_eq!(endpoint_client.inbound_nonce(&receiver, &src_eid, &sender), 2);
+
+    clear_packet_with_auth(&context, &receiver, &origin2, &receiver, &guid2, &message2);
     // Verify advanced inbound nonce.
     assert_eq!(endpoint_client.inbound_nonce(&receiver, &src_eid, &sender), 2);
 }
@@ -382,7 +369,7 @@ fn test_clear_failure_missing_intermediate_nonce() {
 }
 
 #[test]
-fn test_clear_does_not_advance_lazy_nonce_when_clearing_older_nonce() {
+fn test_clear_does_not_advance_inbound_nonce_when_clearing_older_nonce() {
     let context = setup();
     let env = &context.env;
     let endpoint_client = &context.endpoint_client;

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

@@ -20,7 +20,7 @@ fn test_initializable_new_path_receiver_allows() {
     let sender = BytesN::from_array(&context.env, &[1u8; 32]);
     let origin = Origin { src_eid, sender, nonce: 1 };
 
-    // For a new path (lazy nonce is 0), initializable depends on receiver contract.
+    // For a new path (inbound_nonce is 0), initializable depends on receiver contract.
     let result = endpoint_client.initializable(&origin, &receiver);
     assert!(result);
 }
@@ -36,12 +36,12 @@ fn test_initializable_new_path_receiver_rejects() {
     let sender = BytesN::from_array(&context.env, &[1u8; 32]);
     let origin = Origin { src_eid, sender, nonce: 1 };
 
-    // For a new path (lazy nonce is 0), initializable depends on receiver contract.
+    // For a new path (inbound_nonce is 0), initializable depends on receiver contract.
     let result = endpoint_client.initializable(&origin, &receiver);
     assert!(!result);
 }
 
-// Established paths always return true (lazy nonce > 0)
+// Established paths always return true (inbound_nonce > 0)
 #[test]
 fn test_initializable_established_path_always_true() {
     let context = setup();
@@ -58,7 +58,7 @@ fn test_initializable_established_path_always_true() {
     context.mock_auth(&receiver, "skip", (&receiver, &receiver, &src_eid, &sender, &nonce));
     context.endpoint_client.skip(&receiver, &receiver, &src_eid, &sender, &nonce);
 
-    // Now the path is established (lazy_nonce > 0), it should return true regardless of receiver.
+    // Now the path is established (inbound_nonce > 0), it should return true regardless of receiver.
     let origin2 = Origin { src_eid, sender, nonce: 2 };
     let result = endpoint_client.initializable(&origin2, &receiver);
     assert!(result);

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

@@ -37,7 +37,7 @@ fn test_verifiable_new_path_nonce_1_true() {
 
 // Established path => verifiable when origin.nonce is in (inbound_nonce, inbound_nonce + 256]
 #[test]
-fn test_verifiable_after_skip_nonce_gt_lazy_true() {
+fn test_verifiable_after_skip_nonce_gt_inbound_nonce_true() {
     let context = setup();
     let env = &context.env;
     let endpoint_client = &context.endpoint_client;
@@ -54,9 +54,9 @@ fn test_verifiable_after_skip_nonce_gt_lazy_true() {
     assert!(result);
 }
 
-// Nonce <= lazy is still verifiable when inbound payload hash exists
+// Nonce <= inbound_nonce is still verifiable when an inbound payload hash exists
 #[test]
-fn test_verifiable_true_when_nonce_leq_lazy_but_payload_hash_exists() {
+fn test_verifiable_true_when_nonce_leq_inbound_nonce_but_payload_hash_exists() {
     let context = setup();
     let env = &context.env;
     let endpoint_client = &context.endpoint_client;
@@ -68,28 +68,28 @@ fn test_verifiable_true_when_nonce_leq_lazy_but_payload_hash_exists() {
     // Setup receive library (needed to store a payload hash via verify).
     let receive_lib = context.setup_default_receive_lib(src_eid, 0);
 
-    // Establish the path by skipping nonce 1 (lazy becomes 1).
+    // Establish the path by skipping nonce 1 (inbound_nonce becomes 1).
     skip_with_auth(&context, &receiver, src_eid, &sender, 1);
 
-    // Verify nonce 2 (allowed because 2 > lazy 1) which stores inbound payload hash for nonce 2.
+    // Verify nonce 2 (allowed because 2 > inbound_nonce 1) which stores inbound payload hash for nonce 2.
     let origin2 = Origin { src_eid, sender: sender.clone(), nonce: 2u64 };
     let payload_hash2 = BytesN::from_array(env, &[0x33u8; 32]);
     verify_with_auth(&context, &receive_lib, &origin2, &receiver, &payload_hash2);
 
-    // Advance lazy nonce to 3 while keeping payload hash for 2 (skip sets lazy nonce only).
+    // Advance inbound_nonce to 3 while keeping payload hash for 2 (skip doesn't clear payload hashes).
     skip_with_auth(&context, &receiver, src_eid, &sender, 3);
 
     // Sanity: inbound nonce was advanced, and the payload hash for nonce 2 still exists.
     assert_eq!(endpoint_client.inbound_nonce(&receiver, &src_eid, &sender), 3);
     assert!(endpoint_client.inbound_payload_hash(&receiver, &src_eid, &sender, &2u64).is_some());
 
-    // Now nonce 2 <= lazy 3, but payload hash exists -> verifiable should be true.
+    // Now nonce 2 <= inbound_nonce 3, but payload hash exists -> verifiable should be true.
     assert!(endpoint_client.verifiable(&origin2, &receiver));
 }
 
-// Boundary case (nonce == lazy)
+// Boundary case (nonce == inbound_nonce)
 #[test]
-fn test_verifiable_nonce_eq_lazy_false_without_payload_hash() {
+fn test_verifiable_nonce_eq_inbound_nonce_false_without_payload_hash() {
     let context = setup();
     let env = &context.env;
     let endpoint_client = &context.endpoint_client;
@@ -103,7 +103,7 @@ fn test_verifiable_nonce_eq_lazy_false_without_payload_hash() {
     skip_with_auth(&context, &receiver, src_eid, &sender, 2);
     assert_eq!(endpoint_client.inbound_nonce(&receiver, &src_eid, &sender), 2);
 
-    // nonce == lazy and payload hash missing -> verifiable should be false.
+    // nonce == inbound_nonce and payload hash missing -> verifiable should be false.
     let origin2 = Origin { src_eid, sender: sender.clone(), nonce: 2u64 };
     assert!(endpoint_client.inbound_payload_hash(&receiver, &src_eid, &sender, &2u64).is_none());
     assert!(!endpoint_client.verifiable(&origin2, &receiver));
@@ -145,3 +145,43 @@ fn test_verifiable_upper_bound_is_enforced_when_inbound_nonce_nonzero() {
     assert!(endpoint_client.verifiable(&ok, &receiver));
     assert!(!endpoint_client.verifiable(&too_far, &receiver));
 }
+
+
+#[test]
+fn test_verifiable_true_when_payload_hash_exists_even_if_nonce_outside_window() {
+    let context = setup();
+    let env = &context.env;
+    let endpoint_client = &context.endpoint_client;
+
+    let src_eid = 2u32;
+    let sender = BytesN::from_array(env, &[1u8; 32]);
+    let receiver = soroban_sdk::Address::generate(env);
+
+    // NOTE: This state should be unreachable in normal execution flows.
+    //
+    // In production, payload hashes are written by `verify()` -> `inbound()`. For *new* nonces
+    // (`nonce > inbound_nonce`), `inbound()` calls `insert_and_drain_pending_nonces()` which enforces
+    // the pending window bound (`nonce <= inbound_nonce + 256`).
+    //
+    // Therefore, with `inbound_nonce == 0`, a payload hash at a "far" nonce (e.g. 999) cannot be
+    // created through valid contract calls (it would fail `verifiable()` and/or the pending window
+    // bound on insertion).
+    //
+    // We write storage directly here to simulate corrupted/invalid state and to ensure `verifiable()`
+    // preserves its OR semantics: if a payload hash exists for a nonce, `verifiable()` must return
+    // true even when the nonce is outside the pending window.
+
+    // Choose a nonce that is clearly outside the pending window when inbound_nonce == 0.
+    let far_nonce = 999u64;
+
+    // Write payload hash directly to storage to exercise the OR branch:
+    // `EndpointStorage::has_inbound_payload_hash(...) == true` should make verifiable() return true,
+    // even if the nonce is outside (inbound_nonce, inbound_nonce + 256].
+    let payload_hash = BytesN::from_array(env, &[0x42u8; 32]);
+    env.as_contract(&endpoint_client.address, || {
+        storage::EndpointStorage::set_inbound_payload_hash(env, &receiver, src_eid, &sender, far_nonce, &payload_hash)
+    });
+
+    let origin_far = Origin { src_eid, sender, nonce: far_nonce };
+    assert!(endpoint_client.verifiable(&origin_far, &receiver));
+}

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

@@ -63,35 +63,6 @@ fn test_verify_success() {
 }
 
 // Storage & Nonce Behavior
-#[test]
-fn test_verify_stores_payload_hash() {
-    let context = setup();
-    let env = &context.env;
-    let endpoint_client = &context.endpoint_client;
-
-    let src_eid = 2u32;
-    let sender = BytesN::from_array(env, &[1u8; 32]);
-    let receiver = env.register(MockReceiver, ());
-    let nonce = 1u64;
-
-    // Setup receive library
-    let receive_lib = context.setup_default_receive_lib(src_eid, 0);
-
-    // Create payload hash
-    let payload_hash = default_payload_hash(env);
-
-    let origin = Origin { src_eid, sender: sender.clone(), nonce };
-
-    // Mock auth for receive_lib
-    context.mock_auth(&receive_lib, "verify", (&receive_lib, &origin, &receiver, &payload_hash));
-
-    endpoint_client.verify(&receive_lib, &origin, &receiver, &payload_hash);
-
-    // Verify inbound payload hash was stored
-    let stored_hash = endpoint_client.inbound_payload_hash(&receiver, &src_eid, &sender, &nonce);
-    assert_eq!(stored_hash, Some(payload_hash));
-}
-
 #[test]
 fn test_verify_overwrites_payload_hash_for_same_nonce() {
     let context = setup();
@@ -262,7 +233,7 @@ fn test_verify_path_not_initializable() {
     context.mock_auth(&receive_lib, "verify", (&receive_lib, &origin, &receiver, &payload_hash));
 
     // Library validation passes (receive_lib matches default)
-    // initializable checks: lazy_inbound_nonce == 0, and receiver.allow_initialize_path(origin) == false
+    // initializable checks: inbound_nonce == 0, and receiver.allow_initialize_path(origin) == false
     // So initializable returns false, should panic with PathNotInitializable error
     let result = endpoint_client.try_verify(&receive_lib, &origin, &receiver, &payload_hash);
     assert_eq!(result.err().unwrap().ok().unwrap(), EndpointError::PathNotInitializable.into());
@@ -281,7 +252,7 @@ fn test_verify_path_not_verifiable() {
     // Setup receive library and set as default (so library validation passes)
     let receive_lib = context.setup_default_receive_lib(src_eid, 0);
 
-    // Skip nonce 1 to set lazy_inbound_nonce to 1 (so initializable passes: lazy_nonce > 0)
+    // Skip nonce 1 to advance inbound_nonce to 1 (so initializable passes: inbound_nonce > 0)
     context.mock_auth(&receiver, "skip", (&receiver, &receiver, &src_eid, &sender, &1u64));
     endpoint_client.skip(&receiver, &receiver, &src_eid, &sender, &1);
 
@@ -291,15 +262,15 @@ fn test_verify_path_not_verifiable() {
     let payload = build_payload(env, &guid, &message);
     let payload_hash = keccak256(env, &payload);
 
-    // Try to verify nonce 1, but lazy_nonce is already 1, so nonce 1 is not verifiable
-    // verifiable checks: nonce > lazy_inbound_nonce (1 > 1 is false) OR has payload hash (false)
+    // Try to verify nonce 1, but inbound_nonce is already 1, so nonce 1 is not verifiable
+    // verifiable checks: nonce > inbound_nonce (1 > 1 is false) OR has payload hash (false)
     let origin = Origin { src_eid, sender, nonce: 1 };
 
     // Mock auth for receive_lib
     context.mock_auth(&receive_lib, "verify", (&receive_lib, &origin, &receiver, &payload_hash));
 
-    // Library validation passes, initializable passes (lazy_nonce > 0)
-    // verifiable fails (nonce <= lazy_nonce and no payload hash), should panic with PathNotVerifiable error
+    // Library validation passes, initializable passes (inbound_nonce > 0)
+    // verifiable fails (nonce <= inbound_nonce and no payload hash), should panic with PathNotVerifiable error
     let result = endpoint_client.try_verify(&receive_lib, &origin, &receiver, &payload_hash);
     assert_eq!(result.err().unwrap().ok().unwrap(), EndpointError::PathNotVerifiable.into());
 }

package/contracts/endpoint-v2/src/tests/messaging_channel/burn.rs

@@ -258,9 +258,9 @@ fn test_burn_payload_hash_not_found_when_storage_none() {
     assert_eq!(result.err().unwrap().ok().unwrap(), EndpointError::PayloadHashNotFound.into());
 }
 
-// Failure when nonce is greater than lazy nonce
+// Failure when nonce is greater than `inbound_nonce`
 #[test]
-fn test_burn_invalid_nonce_when_greater_than_lazy_nonce() {
+fn test_burn_invalid_nonce_when_greater_than_inbound_nonce() {
     let context = setup();
     let env = &context.env;
 

package/contracts/endpoint-v2/src/tests/messaging_channel/clear_payload.rs

@@ -52,6 +52,8 @@ fn test_clear_payload_success() {
     let payload_hash = inbound_as_verified_from_payload(&context, &receiver, src_eid, &sender, nonce, &payload);
     assert_eq!(endpoint_client.inbound_payload_hash(&receiver, &src_eid, &sender, &nonce), Some(payload_hash.clone()));
 
+    assert_eq!(endpoint_client.inbound_nonce(&receiver, &src_eid, &sender), nonce);
+
     clear_payload(&context, &receiver, src_eid, &sender, nonce, &payload);
 
     assert_eq!(endpoint_client.inbound_payload_hash(&receiver, &src_eid, &sender, &nonce), None);
@@ -88,6 +90,42 @@ fn test_clear_payload_keeps_other_payload_hashes_intact() {
     let _ = hash3; // hash3 is only used to ensure it was computed and stored for nonce 3.
 }
 
+#[test]
+fn test_clear_payload_does_not_change_pending_inbound_nonces() {
+    let context = setup();
+    let env = &context.env;
+    let endpoint_client = &context.endpoint_client;
+
+    let receiver = Address::generate(env);
+    let src_eid = 2;
+    let sender = BytesN::from_array(env, &[1u8; 32]);
+
+    // Verify 1 and 2 consecutively, then verify 4 out-of-order.
+    // This produces: inbound_nonce = 2, pending_inbound_nonces = [4].
+    let payload1 = Bytes::from_array(env, &[0x01]);
+    let payload2 = Bytes::from_array(env, &[0x02]);
+    let payload4 = Bytes::from_array(env, &[0x04]);
+
+    let hash1 = inbound_as_verified_from_payload(&context, &receiver, src_eid, &sender, 1, &payload1);
+    let hash2 = inbound_as_verified_from_payload(&context, &receiver, src_eid, &sender, 2, &payload2);
+    let hash4 = inbound_as_verified_from_payload(&context, &receiver, src_eid, &sender, 4, &payload4);
+
+    assert_eq!(endpoint_client.inbound_nonce(&receiver, &src_eid, &sender), 2);
+    assert_eq!(endpoint_client.pending_inbound_nonces(&receiver, &src_eid, &sender), soroban_sdk::vec![env, 4u64]);
+
+    // Clear nonce 2. This must not affect pending nonces (which are > inbound_nonce).
+    clear_payload(&context, &receiver, src_eid, &sender, 2, &payload2);
+
+    assert_eq!(endpoint_client.inbound_nonce(&receiver, &src_eid, &sender), 2);
+    assert_eq!(endpoint_client.pending_inbound_nonces(&receiver, &src_eid, &sender), soroban_sdk::vec![env, 4u64]);
+
+    // Only nonce 2 is cleared; others remain.
+    assert_eq!(endpoint_client.inbound_payload_hash(&receiver, &src_eid, &sender, &2), None);
+    assert_eq!(endpoint_client.inbound_payload_hash(&receiver, &src_eid, &sender, &1), Some(hash1));
+    assert_eq!(endpoint_client.inbound_payload_hash(&receiver, &src_eid, &sender, &4), Some(hash4));
+    let _ = hash2; // hash2 is only used to ensure it was computed and stored for nonce 2.
+}
+
 // Clearing a nonce <= inbound nonce does not update inbound nonce
 #[test]
 fn test_clear_payload_does_not_update_inbound_nonce_when_nonce_is_not_greater() {
@@ -132,7 +170,7 @@ fn test_clear_payload_payload_hash_not_found_when_nonce_is_checkpointed_but_miss
     let src_eid = 2;
     let sender = BytesN::from_array(env, &[1u8; 32]);
 
-    // nonce <= lazy_nonce, so clear_payload will NOT run the "has_payload for all intermediate nonces" check.
+    // nonce <= inbound_nonce, so clear_payload will NOT run the "has_payload for all intermediate nonces" check.
     // It should fail at the payload hash check instead.
     env.as_contract(&endpoint_client.address, || {
         storage::EndpointStorage::set_inbound_nonce(env, &receiver, src_eid, &sender, &5u64)
@@ -186,6 +224,7 @@ fn test_clear_payload_not_stored() {
 fn test_clear_payload_missing_intermediate_nonce() {
     let context = setup();
     let env = &context.env;
+    let endpoint_client = &context.endpoint_client;
 
     let receiver = Address::generate(env);
     let src_eid = 2;
@@ -198,9 +237,19 @@ fn test_clear_payload_missing_intermediate_nonce() {
     let _ = inbound_as_verified_from_payload(&context, &receiver, src_eid, &sender, 1, &payload1);
     let _ = inbound_as_verified_from_payload(&context, &receiver, src_eid, &sender, 3, &payload3);
 
+    // inbound_nonce should be 1 (nonce 2 is missing), and nonce 3 should be pending.
+    assert_eq!(endpoint_client.inbound_nonce(&receiver, &src_eid, &sender), 1);
+    assert_eq!(
+        endpoint_client.pending_inbound_nonces(&receiver, &src_eid, &sender),
+        soroban_sdk::vec![env, 3u64]
+    );
+
     // Clearing nonce 1 succeeds.
     clear_payload(&context, &receiver, src_eid, &sender, 1, &payload1);
 
+    // clear_payload does not advance inbound_nonce; it remains 1.
+    assert_eq!(endpoint_client.inbound_nonce(&receiver, &src_eid, &sender), 1);
+
     // Try to clear nonce 3 - should panic because inbound_nonce is still 1 (nonce 3 is out-of-order).
     clear_payload(&context, &receiver, src_eid, &sender, 3, &payload3);
 }