@layerzerolabs/protocol-stellar-v2 0.2.39 → 0.2.41

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

@@ -457,23 +457,27 @@ pub fn contract_trait(attr: TokenStream, item: TokenStream) -> TokenStream {
 // Upgradeable Macro
 // ============================================================================
 
-/// Generates upgradeable implementation using the `Upgradeable` trait's default methods.
+/// Generates upgradeable implementation using `Upgradeable` or `UpgradeableRbac` traits.
 ///
-/// This macro implements `Upgradeable` using the trait's default methods (which include auth).
+/// `Upgradeable` uses Auth directly; `UpgradeableRbac` layers RoleBased
+/// access control on top of Auth.
 ///
 /// # Requirements
-/// - The contract must implement the `Auth` trait (via `#[ownable]` or `#[multisig]`)
+/// - `Upgradeable` (default): contract must implement `Auth` (via `#[ownable]` or `#[multisig]`)
+/// - `UpgradeableRbac` (with `rbac`): contract must implement both `Auth` and `RoleBasedAccessControl` (e.g. from OApp)
 /// - By default, requires manual `UpgradeableInternal` implementation
 /// - With `no_migration` flag, auto-generates a no-op `UpgradeableInternal` impl
 ///
 /// # Options
-/// - `#[upgradeable]` - Requires manual `UpgradeableInternal` implementation (safety by default)
-/// - `#[upgradeable(no_migration)]` - Auto-generates no-op `UpgradeableInternal` (for initial deployment)
+/// - `#[upgradeable]` - Implements Upgradeable, requires manual `UpgradeableInternal` (safety by default)
+/// - `#[upgradeable(no_migration)]` - Implements Upgradeable, auto-generates no-op `UpgradeableInternal`
+/// - `#[upgradeable(rbac)]` - Implements UpgradeableRbac, requires manual `UpgradeableInternal`
+/// - `#[upgradeable(rbac, no_migration)]` - Implements UpgradeableRbac, auto-generates no-op `UpgradeableInternal`
 ///
 /// # Example
 /// ```ignore
-/// // Requires manual UpgradeableInternal implementation (default)
-/// #[ownable]  // or #[multisig]
+/// // Implements Upgradeable (default)
+/// #[ownable]
 /// #[upgradeable]
 /// pub struct MyContract;
 ///
@@ -485,16 +489,32 @@ pub fn contract_trait(attr: TokenStream, item: TokenStream) -> TokenStream {
 ///     }
 /// }
 ///
-/// // Auto-generates no-op UpgradeableInternal (for initial deployment)
-/// #[ownable]  // or #[multisig]
+/// // Implements Upgradeable (no migration)
+/// #[ownable]
 /// #[upgradeable(no_migration)]
-/// pub struct MyContract;
-/// // No UpgradeableInternal impl needed!
+/// pub struct SimpleContract;
+///
+/// // Implements UpgradeableRbac (layered)
+/// #[ownable]
+/// #[upgradeable(rbac)]
+/// pub struct RbacContract;
+///
+/// impl utils::upgradeable::UpgradeableInternal for RbacContract {
+///     type MigrationData = MyMigrationParams;
+///
+///     fn __migrate(env: &Env, migration_data: &Self::MigrationData) {
+///         // Custom migration logic here
+///     }
+/// }
+///
+/// // Implements UpgradeableRbac (no migration)
+/// #[ownable]
+/// #[upgradeable(rbac, no_migration)]
+/// pub struct SimpleRbacContract;
 /// ```
 ///
 /// Generated code includes:
-/// - `upgrade(env, new_wasm_hash)` - Upgrades the contract WASM (auth required)
-/// - `migrate(env, migration_data)` - Runs migration after upgrade (auth required, XDR-decodes `Bytes` to `MigrationData`)
+/// - `upgrade` / `migrate` - Auth-based or Auth + RoleBased depending on options
 /// - `contractmeta!` with `binver` set to the Cargo package version (if not 0.0.0)
 #[proc_macro_attribute]
 pub fn upgradeable(attr: TokenStream, item: TokenStream) -> TokenStream {
@@ -518,8 +538,7 @@ pub fn upgradeable(attr: TokenStream, item: TokenStream) -> TokenStream {
 /// - `#[ownable]` - Single-owner access control
 ///
 /// # Options
-/// - `upgradeable` - Adds `#[upgradeable]`, requires manual `UpgradeableInternal` impl
-/// - `upgradeable(no_migration)` - Adds `#[upgradeable(no_migration)]`, auto-generates no-op impl
+/// - `upgradeable(...)` - Adds `#[upgradeable(...)]`; content is passed verbatim to the upgradeable macro
 /// - `multisig` - Uses `#[multisig]` instead of `#[ownable]`
 ///
 /// # Examples
@@ -536,6 +555,10 @@ pub fn upgradeable(attr: TokenStream, item: TokenStream) -> TokenStream {
 /// #[lz_contract(upgradeable(no_migration))]
 /// pub struct DVNFeeLib;
 ///
+/// // Contract with RBAC-based upgrade support
+/// #[lz_contract(upgradeable(rbac))]
+/// pub struct RbacOft;
+///
 /// // Contract with multisig auth and upgrade support (no migration)
 /// #[lz_contract(multisig, upgradeable(no_migration))]
 /// pub struct DVN;

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

@@ -16,21 +16,20 @@ use syn::{
 pub struct LzContractConfig {
     /// If true, adds `#[upgradeable]` for contract upgrade support.
     pub upgradeable: bool,
-    /// If true, generates a default no-op `UpgradeableInternal` implementation.
-    /// Only valid when `upgradeable` is also true.
-    pub no_migration: bool,
+    /// Raw tokens inside `upgradeable(...)`, passed verbatim to the upgradeable macro.
+    /// Empty when `upgradeable` has no parentheses.
+    pub upgradeable_attr: TokenStream,
     /// If true, uses `#[multisig]` instead of `#[ownable]` for auth.
     pub multisig: bool,
 }
 
 impl Parse for LzContractConfig {
     fn parse(input: ParseStream) -> syn::Result<Self> {
+        let mut config = Self::default();
         if input.is_empty() {
-            return Ok(Self::default());
+            return Ok(config);
         }
 
-        let mut config = Self::default();
-
         // Parse comma-separated items, handling nested parentheses for upgradeable(no_migration)
         while !input.is_empty() {
             let ident: Ident = input.parse()?;
@@ -38,19 +37,11 @@ impl Parse for LzContractConfig {
             match ident.to_string().as_str() {
                 "upgradeable" => {
                     config.upgradeable = true;
-                    // Check for optional (no_migration) suffix
+                    // Pass through optional (...) content verbatim to the upgradeable macro
                     if input.peek(syn::token::Paren) {
                         let content;
                         parenthesized!(content in input);
-                        let inner_ident: Ident = content.parse()?;
-                        if inner_ident == "no_migration" {
-                            config.no_migration = true;
-                        } else {
-                            return Err(Error::new(inner_ident.span(), "expected `no_migration`"));
-                        }
-                        if !content.is_empty() {
-                            return Err(Error::new(content.span(), "unexpected tokens in `upgradeable(...)`"));
-                        }
+                        config.upgradeable_attr = content.parse()?;
                     }
                 }
                 "multisig" => config.multisig = true,
@@ -79,8 +70,7 @@ impl Parse for LzContractConfig {
 /// - `#[common_macros::ownable]` - Single-owner access control
 ///
 /// # Options
-/// - `upgradeable` - Adds `#[upgradeable]`, requires manual `UpgradeableInternal` impl
-/// - `upgradeable(no_migration)` - Adds `#[upgradeable(no_migration)]`, auto-generates no-op impl
+/// - `upgradeable(...)` - Adds `#[upgradeable(...)]`; content is passed verbatim to the upgradeable macro
 /// - `multisig` - Uses `#[multisig]` instead of `#[ownable]`
 pub fn generate_lz_contract(attr: TokenStream, input: TokenStream) -> TokenStream {
     let config: LzContractConfig =
@@ -94,10 +84,11 @@ pub fn generate_lz_contract(attr: TokenStream, input: TokenStream) -> TokenStrea
     };
 
     let upgrade = if config.upgradeable {
-        if config.no_migration {
-            quote! { #[common_macros::upgradeable(no_migration)] }
-        } else {
+        if config.upgradeable_attr.is_empty() {
             quote! { #[common_macros::upgradeable] }
+        } else {
+            let upgradeable_attr = &config.upgradeable_attr;
+            quote! { #[common_macros::upgradeable(#upgradeable_attr)] }
         }
     } else {
         quote! {}

package/contracts/common-macros/src/tests/lz_contract.rs

@@ -30,9 +30,24 @@ fn snapshot_generated_lz_contract_code() {
         &syn::parse2::<syn::File>(upgradeable_no_migration_result).expect("failed to parse generated code"),
     );
 
+    let upgradeable_rbac_result =
+        crate::lz_contract::generate_lz_contract(quote! { upgradeable(rbac) }, quote! { pub struct MyContract; });
+    let upgradeable_rbac_formatted = prettyplease::unparse(
+        &syn::parse2::<syn::File>(upgradeable_rbac_result).expect("failed to parse generated code"),
+    );
+
+    // Pass-through: order and content preserved verbatim
+    let upgradeable_rbac_no_migration_result = crate::lz_contract::generate_lz_contract(
+        quote! { upgradeable(rbac, no_migration) },
+        quote! { pub struct MyContract; },
+    );
+    let upgradeable_rbac_no_migration_formatted = prettyplease::unparse(
+        &syn::parse2::<syn::File>(upgradeable_rbac_no_migration_result).expect("failed to parse generated code"),
+    );
+
     let combined = format!(
-        "// === Default (ownable) ===\n\n{}\n\n// === MultiSig + Upgradeable ===\n\n{}\n\n// === Upgradeable (no_migration) ===\n\n{}",
-        default_formatted, multisig_upgradeable_formatted, upgradeable_no_migration_formatted
+        "// === Default (ownable) ===\n\n{}\n\n// === MultiSig + Upgradeable ===\n\n{}\n\n// === Upgradeable (no_migration) ===\n\n{}\n\n// === Upgradeable (rbac) ===\n\n{}\n\n// === Upgradeable (rbac, no_migration) pass-through ===\n\n{}",
+        default_formatted, multisig_upgradeable_formatted, upgradeable_no_migration_formatted, upgradeable_rbac_formatted, upgradeable_rbac_no_migration_formatted
     );
 
     insta::assert_snapshot!(combined);
@@ -49,12 +64,6 @@ fn test_lz_contract_invalid_config_table_driven() {
     let cases: Vec<(&str, TokenStream, &str)> = vec![
         ("unknown option", quote! { not_a_real_option }, "expected one of `upgradeable`, `multisig`"),
         ("invalid attr syntax", quote! { 123 }, "failed to parse lz_contract config"),
-        ("upgradeable(bad_inner)", quote! { upgradeable(not_migration) }, "expected `no_migration`"),
-        (
-            "upgradeable(extra_tokens)",
-            quote! { upgradeable(no_migration, extra) },
-            "unexpected tokens in `upgradeable(...)`",
-        ),
     ];
 
     for (case, attr, expected_substring) in cases {

package/contracts/common-macros/src/tests/snapshots/common_macros__tests__lz_contract__snapshot_generated_lz_contract_code.snap

@@ -29,3 +29,23 @@ pub struct MyContract;
 #[common_macros::ownable]
 #[common_macros::upgradeable(no_migration)]
 pub struct MyContract;
+
+
+// === Upgradeable (rbac) ===
+
+#[soroban_sdk::contract]
+#[common_macros::ttl_configurable]
+#[common_macros::ttl_extendable]
+#[common_macros::ownable]
+#[common_macros::upgradeable(rbac)]
+pub struct MyContract;
+
+
+// === Upgradeable (rbac, no_migration) pass-through ===
+
+#[soroban_sdk::contract]
+#[common_macros::ttl_configurable]
+#[common_macros::ttl_extendable]
+#[common_macros::ownable]
+#[common_macros::upgradeable(rbac, no_migration)]
+pub struct MyContract;

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));
+}