@layerzerolabs/protocol-stellar-v2 0.2.20 → 0.2.22

package/contracts/macro-integration-tests/tests/ui/oapp/pass/custom_single_trait.rs

@@ -0,0 +1,96 @@
+// UI (trybuild) test: each single-trait `custom` option compiles.
+//
+// These are merged into one file to reduce test count while still covering:
+// - `custom = [core]`
+// - `custom = [sender]`
+// - `custom = [receiver]`
+// - `custom = [options_type3]`
+
+use endpoint_v2::Origin;
+use oapp::oapp_core::OAppCore;
+use oapp::oapp_options_type3::OAppOptionsType3;
+use oapp::oapp_receiver::{LzReceiveInternal, OAppReceiver};
+use oapp::oapp_sender::OAppSenderInternal;
+use oapp_macros::oapp;
+use soroban_sdk::{contractimpl, Address, Bytes, BytesN, Env};
+
+#[oapp(custom = [core])]
+pub struct MyOAppCustomCore;
+
+impl LzReceiveInternal for MyOAppCustomCore {
+    fn __lz_receive(
+        _env: &Env,
+        _origin: &Origin,
+        _guid: &BytesN<32>,
+        _message: &Bytes,
+        _extra_data: &Bytes,
+        _executor: &Address,
+        _value: i128,
+    ) {
+    }
+}
+
+#[contractimpl(contracttrait)]
+impl OAppCore for MyOAppCustomCore {
+    fn oapp_version(_env: &Env) -> (u64, u64) {
+        (9, 9)
+    }
+}
+
+#[oapp(custom = [sender])]
+pub struct MyOAppCustomSender;
+
+impl LzReceiveInternal for MyOAppCustomSender {
+    fn __lz_receive(
+        _env: &Env,
+        _origin: &Origin,
+        _guid: &BytesN<32>,
+        _message: &Bytes,
+        _extra_data: &Bytes,
+        _executor: &Address,
+        _value: i128,
+    ) {
+    }
+}
+
+impl OAppSenderInternal for MyOAppCustomSender {}
+
+#[oapp(custom = [receiver])]
+pub struct MyOAppCustomReceiver;
+
+impl LzReceiveInternal for MyOAppCustomReceiver {
+    fn __lz_receive(
+        _env: &Env,
+        _origin: &Origin,
+        _guid: &BytesN<32>,
+        _message: &Bytes,
+        _extra_data: &Bytes,
+        _executor: &Address,
+        _value: i128,
+    ) {
+    }
+}
+
+#[contractimpl(contracttrait)]
+impl OAppReceiver for MyOAppCustomReceiver {}
+
+#[oapp(custom = [options_type3])]
+pub struct MyOAppCustomOptionsType3;
+
+impl LzReceiveInternal for MyOAppCustomOptionsType3 {
+    fn __lz_receive(
+        _env: &Env,
+        _origin: &Origin,
+        _guid: &BytesN<32>,
+        _message: &Bytes,
+        _extra_data: &Bytes,
+        _executor: &Address,
+        _value: i128,
+    ) {
+    }
+}
+
+#[contractimpl(contracttrait)]
+impl OAppOptionsType3 for MyOAppCustomOptionsType3 {}
+
+fn main() {}

package/contracts/macro-integration-tests/tests/ui/oapp/pass/minimal_contract.rs

@@ -0,0 +1,64 @@
+// UI (trybuild) test: minimal `#[oapp]` usage compiles.
+//
+// Purpose:
+// - Verifies `#[oapp]` applies `#[common_macros::lz_contract]` and generates default
+//   contract-trait implementations for `OAppCore`, `OAppReceiver`, and `OAppOptionsType3`.
+// - Verifies the user must implement `LzReceiveInternal` and that the implementation is usable.
+
+use endpoint_v2::Origin;
+use oapp::oapp_receiver::LzReceiveInternal;
+use oapp_macros::oapp;
+use soroban_sdk::{contractimpl, Address, Bytes, BytesN, Env};
+
+#[oapp]
+pub struct MyOApp;
+
+impl LzReceiveInternal for MyOApp {
+    fn __lz_receive(
+        _env: &Env,
+        _origin: &Origin,
+        _guid: &BytesN<32>,
+        _message: &Bytes,
+        _extra_data: &Bytes,
+        _executor: &Address,
+        _value: i128,
+    ) {
+        // No-op.
+    }
+}
+
+#[contractimpl]
+impl MyOApp {
+    pub fn init(env: Env, owner: Address, endpoint: Address) {
+        // `lz_contract` (applied by `#[oapp]`) provides ownable helpers.
+        Self::init_owner(&env, &owner);
+        oapp::oapp_core::OAppCoreStorage::set_endpoint(&env, &endpoint);
+
+        // Type-check: the trait impls exist.
+        let _ = <Self as oapp::oapp_core::OAppCore>::oapp_version(&env);
+        let _ = <Self as oapp::oapp_receiver::OAppReceiver>::next_nonce(
+            &env,
+            1,
+            &BytesN::<32>::from_array(&env, &[0u8; 32]),
+        );
+    }
+}
+
+#[oapp(custom = [])]
+pub struct MyOAppCustomEmpty;
+
+impl LzReceiveInternal for MyOAppCustomEmpty {
+    fn __lz_receive(
+        _env: &Env,
+        _origin: &Origin,
+        _guid: &BytesN<32>,
+        _message: &Bytes,
+        _extra_data: &Bytes,
+        _executor: &Address,
+        _value: i128,
+    ) {
+        // No-op.
+    }
+}
+
+fn main() {}

package/contracts/macro-integration-tests/tests/ui/oapp/pass/struct_with_fields.rs

@@ -0,0 +1,46 @@
+// UI (trybuild) test: `#[oapp]` preserves struct attributes + fields.
+
+use endpoint_v2::Origin;
+use oapp::oapp_receiver::LzReceiveInternal;
+use oapp_macros::oapp;
+use soroban_sdk::{Address, Bytes, BytesN, Env};
+
+#[oapp]
+#[derive(Clone, Debug)]
+pub struct MyOApp {
+    pub x: u32,
+}
+
+impl LzReceiveInternal for MyOApp {
+    fn __lz_receive(
+        _env: &Env,
+        _origin: &Origin,
+        _guid: &BytesN<32>,
+        _message: &Bytes,
+        _extra_data: &Bytes,
+        _executor: &Address,
+        _value: i128,
+    ) {
+    }
+}
+
+#[oapp]
+pub struct MyOAppTuple(u32, bool);
+
+impl LzReceiveInternal for MyOAppTuple {
+    fn __lz_receive(
+        _env: &Env,
+        _origin: &Origin,
+        _guid: &BytesN<32>,
+        _message: &Bytes,
+        _extra_data: &Bytes,
+        _executor: &Address,
+        _value: i128,
+    ) {
+    }
+}
+
+fn main() {
+    // Ensure tuple fields are preserved by macro expansion.
+    let _ = MyOAppTuple(1, true);
+}

package/contracts/macro-integration-tests/tests/ui/ownable/fail/only_auth_missing_env.stderr

@@ -6,6 +6,14 @@ error: custom attribute panicked
    |
    = help: message: function must have an Env argument
 
+warning: unused import: `Address`
+ --> tests/ui/ownable/fail/only_auth_missing_env.rs:7:43
+  |
+7 | use soroban_sdk::{contract, contractimpl, Address};
+  |                                           ^^^^^^^
+  |
+  = note: `#[warn(unused_imports)]` on by default
+
 error[E0599]: no function or associated item named `bad` found for struct `MyContract` in the current scope
   --> tests/ui/ownable/fail/only_auth_missing_env.rs:17:12
    |

package/contracts/macro-integration-tests/tests/ui/ownable/pass/namespacing_and_imports.rs

@@ -4,7 +4,7 @@
 // - Ensures a downstream crate can use the generated `Ownable` trait impl via a fully-qualified path
 //   without importing `utils::ownable::Ownable` into scope.
 
-use soroban_sdk::{contract, contractimpl, Address, Env};
+use soroban_sdk::{contract, contractimpl, Env};
 
 #[contract]
 #[common_macros::ownable]

package/contracts/macro-integration-tests/tests/ui/ownable/pass/only_auth_env_param_variants.rs

@@ -5,7 +5,7 @@
 //   even when `Env` is not the first parameter.
 // - Uses `&Env` forms to match the most common `require_auth` signature shape.
 
-use soroban_sdk::{contract, Address, Env};
+use soroban_sdk::{contract, Env};
 
 #[contract]
 #[common_macros::ownable]

package/contracts/macro-integration-tests/tests/ui_oapp.rs

@@ -0,0 +1,11 @@
+#[test]
+fn ui_oapp() {
+    // Important: set this before trybuild::TestCases::new() so each shard has
+    // its own trybuild project directory + lock + artifacts.
+    let target_dir = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("target/trybuild-shards/ui_oapp");
+    std::env::set_var("CARGO_TARGET_DIR", target_dir.as_os_str());
+
+    let t = trybuild::TestCases::new();
+    t.pass("tests/ui/oapp/**/pass/*.rs");
+    t.compile_fail("tests/ui/oapp/**/fail/*.rs");
+}

package/contracts/message-libs/message-lib-common/Cargo.toml

@@ -12,7 +12,6 @@ doctest = false
 testutils = []
 
 [dependencies]
-cfg-if = "1.0"
 soroban-sdk = { workspace = true }
 # workspace dependencies
 utils = { workspace = true }

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

@@ -1,7 +1,7 @@
 use common_macros::contract_error;
 
 // Message Lib Common error codes: 1100-1199
-// See ERROR_SPEC.md for allocation rules
+// See docs/error-spec.md for allocation rules
 
 /// PacketCodecV1Error: 1100-1109
 #[contract_error]

package/contracts/message-libs/treasury/Cargo.toml

@@ -18,10 +18,8 @@ cfg-if = { workspace = true }
 soroban-sdk = { workspace = true }
 common-macros = { workspace = true }
 utils = { workspace = true }
-endpoint-v2 = { workspace = true, features = ["library"] }
 message-lib-common = { workspace = true }
 
 [dev-dependencies]
 soroban-sdk = { workspace = true, features = ["testutils"] }
 utils = { workspace = true, features = ["testutils"] }
-insta = { workspace = true }

package/contracts/message-libs/treasury/src/tests/treasury_tests.rs

@@ -455,14 +455,14 @@ fn test_withdraw_token_events_emitted() {
     setup.mint_tokens(&token, &setup.treasury.address, amount);
 
     // Count events before withdrawal
-    let events_before = setup.env.events().all().len();
+    let events_before = setup.env.events().all().events().len();
 
     // Withdraw tokens and check that events are emitted
     setup.mock_owner_auth("withdraw_token", (&token, &recipient, &amount));
     setup.treasury.withdraw_token(&token, &recipient, &amount);
 
     // Verify that new events were published
-    let events_after = setup.env.events().all().len();
+    let events_after = setup.env.events().all().events().len();
     assert!(events_after > events_before, "TokenWithdrawn event should be emitted");
 }
 

package/contracts/message-libs/uln-302/src/tests/receive_uln302/effective_receive_uln_config.rs

@@ -8,7 +8,7 @@ use crate::{
 };
 use endpoint_v2::SetConfigParam;
 use soroban_sdk::{log, testutils::Address as _, vec, xdr::ToXdr, Address, Env};
-use utils::testing_utils::assert_event;
+use utils::testing_utils::assert_eq_event;
 
 #[test]
 fn test_effective_receive_uln_config_with_default_only() {
@@ -57,7 +57,7 @@ fn test_effective_receive_uln_config_with_custom_config() {
     endpoint.set_config(&Address::generate(&env), &oapp, &uln302.address, &params);
 
     // Assert ReceiveUlnConfigSet event was published immediately after the setter
-    assert_event(
+    assert_eq_event(
         &env,
         &uln302.address,
         ReceiveUlnConfigSet { config: custom_config.clone(), receiver: oapp.clone(), src_eid: eid },

package/contracts/message-libs/uln-302/src/tests/receive_uln302/set_default_receive_uln_configs.rs

@@ -9,7 +9,7 @@ use soroban_sdk::{
     testutils::{MockAuth, MockAuthInvoke},
     vec, IntoVal,
 };
-use utils::testing_utils::assert_event;
+use utils::testing_utils::assert_eq_event;
 
 #[test]
 fn test_set_default_receive_uln_configs() {
@@ -33,7 +33,7 @@ fn test_set_default_receive_uln_configs() {
     uln302.set_default_receive_uln_configs(&oapp_receive_uln_configs);
 
     // Assert DefaultReceiveUlnConfigSet event was published with all params
-    assert_event(&env, &uln302.address, DefaultReceiveUlnConfigsSet { params: oapp_receive_uln_configs.clone() });
+    assert_eq_event(&env, &uln302.address, DefaultReceiveUlnConfigsSet { params: oapp_receive_uln_configs.clone() });
 
     let uln302_receive_client = ReceiveUln302Client::new(&env, &uln302.address);
     for config in oapp_receive_uln_configs.clone() {

package/contracts/message-libs/uln-302/src/tests/receive_uln302/verify.rs

@@ -2,7 +2,7 @@ use soroban_sdk::{
     testutils::{Address as _, MockAuth, MockAuthInvoke},
     Address, IntoVal,
 };
-use utils::testing_utils::assert_event;
+use utils::testing_utils::assert_eq_event;
 
 use crate::{
     events::PayloadVerified,
@@ -165,7 +165,7 @@ fn test_verify_emits_event() {
     receive_client.verify(&dvn, &packet_header, &payload_hash, &CONFIRMATIONS);
 
     // Verify PayloadVerified event was emitted
-    assert_event(
+    assert_eq_event(
         &env,
         &uln302.address,
         PayloadVerified { dvn, header: packet_header, proof_hash: payload_hash, confirmations: CONFIRMATIONS },

package/contracts/message-libs/uln-302/src/tests/send_uln302/effective_executor_config.rs

@@ -8,7 +8,7 @@ use crate::{
 };
 use endpoint_v2::SetConfigParam;
 use soroban_sdk::{log, testutils::Address as _, vec, xdr::ToXdr, Address, Env};
-use utils::testing_utils::assert_event;
+use utils::testing_utils::assert_eq_event;
 
 #[test]
 fn test_effective_executor_config_with_default_only() {
@@ -57,7 +57,7 @@ fn test_effective_executor_config_with_custom_executor() {
 
     // Assert ExecutorConfigSet event was published immediately after the setter
 
-    assert_event(
+    assert_eq_event(
         &setup.env,
         &setup.uln302.address,
         ExecutorConfigSet { config: custom_config.clone(), dst_eid: eid, sender: oapp.clone() },

package/contracts/message-libs/uln-302/src/tests/send_uln302/effective_send_uln_config.rs

@@ -9,7 +9,7 @@ use crate::{
 };
 use endpoint_v2::SetConfigParam;
 use soroban_sdk::{log, testutils::Address as _, vec, xdr::ToXdr, Address, Env};
-use utils::testing_utils::assert_event;
+use utils::testing_utils::assert_eq_event;
 
 #[test]
 fn test_effective_send_uln_config_with_default_only() {
@@ -65,7 +65,7 @@ fn test_effective_send_uln_config_with_custom_config() {
     endpoint.set_config(&Address::generate(&env), &oapp, &uln302.address, &params);
 
     // Assert SendUlnConfigSet event was published immediately after the setter
-    assert_event(
+    assert_eq_event(
         &env,
         &uln302.address,
         SendUlnConfigSet { config: custom_config.clone(), dst_eid: eid, sender: oapp.clone() },

package/contracts/message-libs/uln-302/src/tests/send_uln302/send.rs

@@ -14,7 +14,7 @@ use soroban_sdk::{
     vec, Bytes, BytesN, IntoVal,
 };
 use soroban_sdk::{Address, Env, Vec};
-use utils::testing_utils::{assert_events, IntoExpectedEvent};
+use utils::testing_utils::assert_eq_events;
 
 // Note that all the hot paths and assertions are covered in the quote test so here we only test the events emittance
 #[test]
@@ -72,22 +72,12 @@ fn test_send_events_emittance() {
     let send_result = setup.uln302.send(&packet, &options, &pay_in_zro);
     let native_fee_recipients = &send_result.native_fee_recipients;
     let zro_fee_recipients = &send_result.zro_fee_recipients;
-    assert_events(
+    assert_eq_events(
         &setup.env,
         &setup.uln302.address,
         &[
-            ExecutorFeePaid {
-                executor: executor.clone(),
-                guid: packet.guid.clone(),
-                fee: native_fee_recipients.get(0).unwrap().clone(),
-            }
-            .expected(&setup.env),
-            DVNFeePaid {
-                guid: packet.guid.clone(),
-                dvns: dvns.slice(0..2).clone(),
-                fees: native_fee_recipients.slice(1..3).clone(),
-            }
-            .expected(&setup.env),
+            &ExecutorFeePaid {  guid: packet.guid.clone(),executor: executor.clone(), fee: native_fee_recipients.get(0).unwrap().clone() },
+            &DVNFeePaid { guid: packet.guid.clone(),dvns: dvns.slice(0..2).clone(), fees: native_fee_recipients.slice(1..3).clone() },
         ],
     );
 
@@ -170,22 +160,12 @@ fn test_send_events_emittance_with_zro() {
     let native_fee_recipients = &send_result.native_fee_recipients;
     let zro_fee_recipients = &send_result.zro_fee_recipients;
 
-    assert_events(
+    assert_eq_events(
         &setup.env,
         &setup.uln302.address,
         &[
-            ExecutorFeePaid {
-                executor: executor.clone(),
-                guid: packet.guid.clone(),
-                fee: native_fee_recipients.get(0).unwrap().clone(),
-            }
-            .expected(&setup.env),
-            DVNFeePaid {
-                guid: packet.guid.clone(),
-                dvns: dvns.slice(0..2).clone(),
-                fees: native_fee_recipients.slice(1..3).clone(),
-            }
-            .expected(&setup.env),
+            &ExecutorFeePaid {  guid: packet.guid.clone(), executor: executor.clone(), fee: native_fee_recipients.get(0).unwrap().clone() },
+            &DVNFeePaid { guid: packet.guid.clone(), dvns: dvns.slice(0..2).clone(), fees: native_fee_recipients.slice(1..3).clone() },
         ],
     );
 

package/contracts/message-libs/uln-302/src/tests/send_uln302/set_default_executor_configs.rs

@@ -3,7 +3,7 @@ use soroban_sdk::{
     testutils::{Address as _, MockAuth, MockAuthInvoke},
     vec, Address, IntoVal,
 };
-use utils::testing_utils::assert_event;
+use utils::testing_utils::assert_eq_event;
 
 use crate::{
     errors::Uln302Error,
@@ -44,7 +44,7 @@ fn test_set_default_executor_configs() {
     uln302.set_default_executor_configs(&executor_configs);
 
     // Assert DefaultExecutorConfigSet event was published with all params
-    assert_event(&env, &uln302.address, DefaultExecutorConfigsSet { params: executor_configs.clone() });
+    assert_eq_event(&env, &uln302.address, DefaultExecutorConfigsSet { params: executor_configs.clone() });
 
     let uln302_send_client = SendUln302Client::new(&env, &uln302.address);
     for config_param in executor_configs.clone() {

package/contracts/message-libs/uln-302/src/tests/send_uln302/set_default_send_uln_configs.rs

@@ -3,7 +3,7 @@ use soroban_sdk::{
     testutils::{MockAuth, MockAuthInvoke},
     vec, IntoVal,
 };
-use utils::testing_utils::assert_event;
+use utils::testing_utils::assert_eq_event;
 
 use crate::{
     errors::Uln302Error,
@@ -34,7 +34,7 @@ fn test_set_default_send_uln_configs() {
     uln302.set_default_send_uln_configs(&oapp_send_uln_configs);
 
     // Assert DefaultSendUlnConfigSet event was published with all params
-    assert_event(&env, &uln302.address, DefaultSendUlnConfigsSet { params: oapp_send_uln_configs.clone() });
+    assert_eq_event(&env, &uln302.address, DefaultSendUlnConfigsSet { params: oapp_send_uln_configs.clone() });
 
     let uln302_send_client = SendUln302Client::new(&env, &uln302.address);
     for config in oapp_send_uln_configs.clone() {

package/contracts/oapps/counter/Cargo.toml

@@ -18,7 +18,6 @@ oapp-macros = { workspace = true }
 
 [dev-dependencies]
 soroban-sdk = { workspace = true, features = ["testutils"] }
-assert_unordered = "0.3.5"
 simple-message-lib = { workspace = true }
 message-lib-common = { workspace = true, features = ["testutils"] }
 endpoint-v2 = { workspace = true, features = ["testutils"] }
@@ -27,13 +26,12 @@ uln302 = { workspace = true, features = ["testutils"] }
 dvn = { workspace = true, features = ["testutils"] }
 dvn-fee-lib = { workspace = true }
 executor-fee-lib = { workspace = true }
-worker = { workspace = true }
 treasury = { workspace = true, features = ["testutils"] }
 price-feed = { workspace = true }
 fee-lib-interfaces = { workspace = true }
 executor-helper = { workspace = true }
 # For real DVN signature verification in integration tests
-k256 = "0.13"
-sha3 = "0.10"
-rand = "0.8"
-ed25519-dalek = "2"
+k256 = { workspace = true }
+sha3 = { workspace = true }
+rand = { workspace = true }
+ed25519-dalek = { workspace = true }

package/contracts/oapps/counter/integration_tests/utils.rs

@@ -11,6 +11,7 @@ use soroban_sdk::{
     Address, Bytes, BytesN, Env, IntoVal, Map, Symbol, Val, Vec,
 };
 use utils::buffer_reader::BufferReader;
+use utils::testing_utils::decode_event_topics_data;
 
 /// Trait for common fields in chain setup structs.
 /// Both SML and ULN302 ChainSetup implement this trait.
@@ -215,13 +216,15 @@ pub fn validate_packet<'a, C: ChainSetupCommon<'a>>(
 
 /// Scans for the latest packet_sent event and returns (encoded_payload, options, send_library).
 pub fn scan_packet_sent_event(env: &Env, endpoint: &Address) -> Option<(Bytes, Bytes, Address)> {
-    let events = env.events().all();
+    let events = env.events().all().filter_by_contract(endpoint);
     let packet_sent_symbol = Symbol::new(env, "packet_sent").to_val();
 
     // Iterate in reverse to find the most recent packet sent event
-    for i in (0..events.len()).rev() {
-        let (emitter, topics, data) = events.get(i).unwrap();
-        if emitter == *endpoint && topics.contains(packet_sent_symbol) {
+    for event in events.events().iter().rev() {
+        let Some((topics, data)) = decode_event_topics_data(env, event) else {
+            continue;
+        };
+        if topics.contains(packet_sent_symbol) {
             let map: Map<Symbol, Val> = data.into_val(env);
 
             let encoded_payload: Bytes = map.get(Symbol::new(env, "encoded_packet")).unwrap().into_val(env);
@@ -240,13 +243,15 @@ pub fn scan_packet_sent_event(env: &Env, endpoint: &Address) -> Option<(Bytes, B
 /// Use this only after all messages have been sent in a single "transaction" or collect events incrementally.
 #[allow(dead_code)]
 pub fn scan_all_packet_sent_events(env: &Env, endpoint: &Address) -> Vec<(Bytes, Bytes, Address)> {
-    let events = env.events().all();
+    let events = env.events().all().filter_by_contract(endpoint);
     let packet_sent_symbol = Symbol::new(env, "packet_sent").to_val();
     let mut result = Vec::new(env);
 
-    for i in 0..events.len() {
-        let (emitter, topics, data) = events.get(i).unwrap();
-        if emitter == *endpoint && topics.contains(packet_sent_symbol) {
+    for event in events.events().iter() {
+        let Some((topics, data)) = decode_event_topics_data(env, event) else {
+            continue;
+        };
+        if topics.contains(packet_sent_symbol) {
             let map: Map<Symbol, Val> = data.into_val(env);
 
             let encoded_payload: Bytes = map.get(Symbol::new(env, "encoded_packet")).unwrap().into_val(env);
@@ -265,13 +270,15 @@ pub type ComposeSentEvent = (Address, Address, BytesN<32>, u32, Bytes);
 
 /// Scans for the latest compose_sent event and returns (from, to, guid, index, message).
 pub fn scan_compose_sent_event(env: &Env, endpoint: &Address) -> Option<ComposeSentEvent> {
-    let events = env.events().all();
+    let events = env.events().all().filter_by_contract(endpoint);
     let compose_sent_symbol = Symbol::new(env, "compose_sent").to_val();
 
     // Iterate in reverse to find the most recent compose sent event
-    for i in (0..events.len()).rev() {
-        let (emitter, topics, data) = events.get(i).unwrap();
-        if emitter == *endpoint && topics.contains(compose_sent_symbol) {
+    for event in events.events().iter().rev() {
+        let Some((topics, data)) = decode_event_topics_data(env, event) else {
+            continue;
+        };
+        if topics.contains(compose_sent_symbol) {
             let map: Map<Symbol, Val> = data.into_val(env);
             let from: Address = topics.get(1).unwrap().into_val(env);
             let to: Address = topics.get(2).unwrap().into_val(env);

package/contracts/oapps/oapp/src/errors.rs

@@ -1,7 +1,7 @@
 use common_macros::contract_error;
 
 // OApp library error codes: 2000-2099
-// See ERROR_SPEC.md for allocation rules
+// See docs/error-spec.md for allocation rules
 
 /// OAppError: 2000-2099
 #[contract_error]

package/contracts/oapps/oapp/src/interfaces/mod.rs

@@ -0,0 +1,3 @@
+mod oapp_msg_inspector;
+
+pub use oapp_msg_inspector::*;

package/contracts/oapps/oapp/src/interfaces/oapp_msg_inspector.rs

@@ -0,0 +1,47 @@
+//! OApp Message Inspector interface.
+//!
+//! This module defines the `IOAppMsgInspector` trait that external inspector contracts
+//! must implement to validate outgoing LayerZero messages and options.
+//!
+//! ## Usage
+//!
+//! Inspector contracts should implement this trait and panic if inspection fails:
+//!
+//! ```ignore
+//! use oapp::interfaces::IOAppMsgInspector;
+//!
+//! pub struct MyInspector;
+//!
+//! #[contractimpl]
+//! impl IOAppMsgInspector for MyInspector {
+//!     fn inspect(env: &Env, oapp: &Address, message: &Bytes, options: &Bytes) {
+//!         // Validate message and options
+//!         // Panic if invalid
+//!         if !is_valid(message, options) {
+//!             panic_with_error!(env, MyError::InspectionFailed);
+//!         }
+//!     }
+//! }
+//! ```
+
+use soroban_sdk::{contractclient, Address, Bytes, Env};
+
+/// Interface for OApp message inspectors.
+///
+/// Contracts implementing this trait can be set as message inspectors on OFT contracts
+/// to validate outgoing messages and options before they are sent cross-chain.
+///
+/// If inspection fails, the implementation should panic to revert the transaction.
+#[contractclient(name = "OAppMsgInspectorClient")]
+pub trait IOAppMsgInspector {
+    /// Inspects the LayerZero message and options before sending.
+    ///
+    /// # Arguments
+    /// * `oapp` - The address of the OApp contract sending the message
+    /// * `message` - The encoded message payload to be sent
+    /// * `options` - The LayerZero options for the message
+    ///
+    /// # Panics
+    /// Should panic if the message or options are invalid, reverting the transaction.
+    fn inspect(env: &Env, oapp: &Address, message: &Bytes, options: &Bytes);
+}

package/contracts/oapps/oapp/src/lib.rs

@@ -1,6 +1,7 @@
 #![no_std]
 
 pub mod errors;
+pub mod interfaces;
 pub mod oapp_core;
 pub mod oapp_options_type3;
 pub mod oapp_receiver;