@layerzerolabs/protocol-stellar-v2 0.2.19 → 0.2.21

package/contracts/upgrader/src/lib.rs

@@ -2,45 +2,25 @@
 
 //! # Upgrader Contract
 //!
-//! A stateless utility contract for performing upgrade and migrate operations on upgradeable contracts.
-//!
-//! This contract provides a convenient way to upgrade other contracts, especially useful for
-//! performing upgrade+migrate atomically in a single transaction.
+//! A stateless utility contract for performing atomic upgrade and migrate operations
+//! on contracts implementing the [`Upgradeable`](utils::upgradeable::Upgradeable) trait.
 //!
 //! ## Security Model
 //!
-//! The Upgrader is a permissionless utility - anyone can call it, but security is enforced
-//! by the target contract's authorization checks. When you call `upgrader.upgrade()`, the target
-//! contract's `#[only_auth]` guard ensures only the target's authorizer can successfully upgrade it.
+//! The Upgrader is permissionless - anyone can call it, but security is enforced by the
+//! target contract's authorization checks. The target contract's `#[only_auth]` guard
+//! ensures only its authorizer can successfully upgrade it.
 //!
 //! ## Usage
 //!
-//! Deploy this contract once, then anyone can use it to upgrade contracts they own.
-//!
 //! ```ignore
-//! // Deploy upgrader (no initialization needed)
-//! let upgrader_id = env.register(Upgrader, ());
 //! let upgrader = UpgraderClient::new(&env, &upgrader_id);
-//!
-//! // Upgrade a contract (you must be the target contract's owner)
-//! upgrader.upgrade(&target_contract, &new_wasm_hash);
-//!
-//! // Or upgrade and migrate in one transaction
-//! let migration_data = vec![&env, val1, val2];
-//! upgrader.upgrade_and_migrate(&target_contract, &new_wasm_hash, migration_data);
+//! let migration_data = my_data.to_xdr(&env);
+//! upgrader.upgrade_and_migrate(&target_contract, &new_wasm_hash, &migration_data);
 //! ```
 
-use soroban_sdk::{contract, contractclient, contractimpl, symbol_short, Address, BytesN, Env, Symbol, Vec};
-
-/// Symbol for the migrate function call
-pub const MIGRATE: Symbol = symbol_short!("migrate");
-
-/// Trait representing an upgradeable contract's interface
-#[contractclient(name = "UpgradeableContractClient")]
-pub trait UpgradeableContract {
-    /// Upgrades the contract to new WASM bytecode
-    fn upgrade(env: &Env, new_wasm_hash: BytesN<32>);
-}
+use soroban_sdk::{contract, contractimpl, xdr::ToXdr, Address, Bytes, BytesN, Env};
+use utils::upgradeable::UpgradeableClient;
 
 /// Upgrader contract for managing upgrades of other contracts.
 ///
@@ -51,46 +31,39 @@ pub struct Upgrader;
 
 #[contractimpl]
 impl Upgrader {
-    /// Upgrade a target contract and run its migration in a single transaction
+    /// Upgrades a target contract without custom migration data.
+    ///
+    /// This is a convenience wrapper that calls `upgrade_and_migrate` with empty migration data.
+    ///
+    /// # Arguments
+    /// * `contract_address` - The address of the contract to upgrade
+    /// * `wasm_hash` - The hash of the new WASM bytecode
+    pub fn upgrade(env: &Env, contract_address: &Address, wasm_hash: &BytesN<32>) {
+        Self::upgrade_and_migrate(env, contract_address, wasm_hash, &().to_xdr(env));
+    }
+
+    /// Upgrades a target contract and runs its migration in a single transaction.
     ///
     /// The caller must be authorized as the authorizer of the target contract.
     /// This is enforced by the target contract's `#[only_auth]` check.
     ///
-    /// This is useful for atomic upgrades where you want to ensure the migration
-    /// happens immediately after the upgrade, or the entire operation fails.
-    ///
     /// # Arguments
     /// * `contract_address` - The address of the contract to upgrade
     /// * `wasm_hash` - The hash of the new WASM bytecode
-    /// * `migration_data` - A vector of values to pass to the migrate function.
-    ///   The types of these values depend on the target contract's MigrationData type.
+    /// * `migration_data` - XDR-encoded bytes to pass to the migrate function.
+    ///   Use `value.to_xdr(&env)` to encode the target contract's MigrationData type.
     ///
     /// # Example
     /// ```ignore
-    /// // For a contract with MigrationData = (u32, bool)
-    /// let migration_data = vec![
-    ///     &env,
-    ///     42u32.into_val(&env),
-    ///     true.into_val(&env),
-    /// ];
-    /// upgrader.upgrade_and_migrate(&contract_addr, &wasm_hash, migration_data);
+    /// let migration_data = my_data.to_xdr(&env);
+    /// upgrader.upgrade_and_migrate(&contract_addr, &wasm_hash, &migration_data);
     /// ```
-    pub fn upgrade_and_migrate(
-        env: &Env,
-        contract_address: &Address,
-        wasm_hash: BytesN<32>,
-        migration_data: Vec<soroban_sdk::Val>,
-    ) {
-        let contract_client = UpgradeableContractClient::new(env, contract_address);
-
-        // First upgrade the contract
-        contract_client.upgrade(&wasm_hash);
-
-        // Then call migrate with the provided data
-        // We use invoke_contract because the migration data type is unknown to this contract
-        env.invoke_contract::<()>(contract_address, &MIGRATE, migration_data);
+    pub fn upgrade_and_migrate(env: &Env, contract_address: &Address, wasm_hash: &BytesN<32>, migration_data: &Bytes) {
+        let client = UpgradeableClient::new(env, contract_address);
+        client.upgrade(wasm_hash);
+        client.migrate(migration_data);
     }
 }
 
 #[cfg(test)]
-mod tests;
+mod tests;

package/contracts/upgrader/src/tests/test_upgrader.rs

@@ -1,6 +1,6 @@
 extern crate std;
 
-use soroban_sdk::{contractclient, testutils::Address as _, Address, BytesN, Env, TryIntoVal};
+use soroban_sdk::{contractclient, testutils::Address as _, xdr::ToXdr, Address, BytesN, Env};
 
 use crate::{Upgrader, UpgraderClient};
 
@@ -17,16 +17,20 @@ trait TestUpgradeableContract2 {
 }
 
 mod contract_v1 {
-    // #[contract]
-    // #[upgradeable]
-    // #[ownable]
-    // pub struct TestUpgradeableContract;
+    //#![no_std]
 
-    // impl UpgradeableInternal for TestUpgradeableContract {
-    //     type MigrationData = ();
+    // use soroban_sdk::{contractimpl, Env, Symbol, Address, contractclient};
+    // use utils::{ upgradeable::UpgradeableInternal};
+    // use common_macros::lz_contract;
 
-    //     fn _migrate(env: &Env, _migration_data: &Self::MigrationData) {
-    //         env.storage().instance().set(&Symbol::new(env, "counter"), &2);
+    // #[lz_contract(upgradeable)]
+    // pub struct DummyContract;
+
+    // impl UpgradeableInternal for DummyContract {
+    //     type MigrationData = u32;
+
+    //     fn __migrate(env: &Env, migration_data: &Self::MigrationData) {
+    //         env.storage().instance().set(&Symbol::new(env, "counter2"), migration_data);
     //     }
     // }
 
@@ -35,34 +39,37 @@ mod contract_v1 {
     //     fn counter(env: &Env) -> u32;
     // }
 
-    // #[contract_impl]
-    // impl TestUpgradeable for TestUpgradeableContract {
+    // #[contractimpl]
+    // impl TestUpgradeable for DummyContract {
     //     fn counter(env: &Env) -> u32 {
     //         env.storage().instance().get(&Symbol::new(env, "counter")).unwrap_or(0)
     //     }
     // }
 
-    // #[contract_impl]
-    // impl TestUpgradeableContract {
+    // #[contractimpl]
+    // impl DummyContract {
     //     pub fn __constructor(env: &Env, owner: &Address) {
     //         Self::init_owner(env, owner);
     //         env.storage().instance().set(&Symbol::new(env, "counter"), &1_u32);
     //     }
     // }
-    use super::MigrationData;
     soroban_sdk::contractimport!(file = "./src/tests/test_data/test_upgradeable_contract1.wasm");
 }
 mod contract_v2 {
-    // #[contract]
-    // #[upgradeable]
-    // #[ownable]
-    // pub struct TestUpgradeableContract;
+    //#![no_std]
+
+    // use soroban_sdk::{contractimpl, Env, Symbol, Address, contractclient};
+    // use utils::{ upgradeable::UpgradeableInternal};
+    // use common_macros::lz_contract;
+
+    // #[lz_contract(upgradeable)]
+    // pub struct DummyContract;
 
-    // impl UpgradeableInternal for TestUpgradeableContract {
-    //     type MigrationData = ();
+    // impl UpgradeableInternal for DummyContract {
+    //     type MigrationData = u32;
 
-    //     fn _migrate(env: &Env, _migration_data: &Self::MigrationData) {
-    //         env.storage().instance().set(&Symbol::new(env, "counter2"), &2_u32);
+    //     fn __migrate(env: &Env, migration_data: &Self::MigrationData) {
+    //         env.storage().instance().set(&Symbol::new(env, "counter2"), migration_data);
     //     }
     // }
 
@@ -72,8 +79,8 @@ mod contract_v2 {
     //     fn counter2(env: &Env) -> u32;
     // }
 
-    // #[contract_impl]
-    // impl TestUpgradeable for TestUpgradeableContract {
+    // #[contractimpl]
+    // impl TestUpgradeable for DummyContract {
     //     fn counter(env: &Env) -> u32 {
     //         env.storage().instance().get(&Symbol::new(env, "counter")).unwrap_or(0)
     //     }
@@ -82,7 +89,14 @@ mod contract_v2 {
     //         env.storage().instance().get(&Symbol::new(env, "counter2")).unwrap_or(0)
     //     }
     // }
-    use super::MigrationData;
+
+    // #[contractimpl]
+    // impl DummyContract {
+    //     pub fn __constructor(env: &Env, owner: &Address) {
+    //         Self::init_owner(env, owner);
+    //         env.storage().instance().set(&Symbol::new(env, "counter"), &1_u32);
+    //     }
+    // }
     soroban_sdk::contractimport!(file = "./src/tests/test_data/test_upgradeable_contract2.wasm");
 }
 
@@ -90,9 +104,6 @@ fn install_new_wasm(e: &Env) -> BytesN<32> {
     e.deployer().upload_contract_wasm(contract_v2::WASM)
 }
 
-#[allow(dead_code)]
-type MigrationData = ();
-
 #[test]
 fn test_upgrade_with_upgrader() {
     let e = Env::default();
@@ -107,14 +118,12 @@ fn test_upgrade_with_upgrader() {
     let upgrader_client = UpgraderClient::new(&e, &upgrader);
 
     let new_wasm_hash = install_new_wasm(&e);
-
-    upgrader_client.upgrade_and_migrate(
-        &contract_id,
-        &new_wasm_hash,
-        &soroban_sdk::vec![&e, ().try_into_val(&e).unwrap()],
-    );
+    let counter_value = 2_u32;
+    // Encode migration data as XDR bytes
+    let migration_data = counter_value.to_xdr(&e);
+    upgrader_client.upgrade_and_migrate(&contract_id, &new_wasm_hash, &migration_data);
 
     let client_v2 = TestUpgradeableContractClient2::new(&e, &contract_id);
 
-    assert_eq!(client_v2.counter2(), 2);
+    assert_eq!(client_v2.counter2(), counter_value);
 }

package/contracts/utils/Cargo.toml

@@ -18,4 +18,3 @@ common-macros = { workspace = true }
 
 [dev-dependencies]
 soroban-sdk = { workspace = true, features = ["testutils"] }
-stellar-strkey = "0.0.14"

package/contracts/utils/src/buffer_reader.rs

@@ -92,6 +92,7 @@ impl<'a> BufferReader<'a> {
         value
     }
 
+    /// Reads all bytes from current position to the end of the buffer.
     pub fn read_bytes_until_end(&mut self) -> Bytes {
         self.read_bytes(self.remaining_len())
     }

package/contracts/utils/src/errors.rs

@@ -1,7 +1,7 @@
 use common_macros::contract_error;
 
 // Utils library error codes: 1000-1099
-// See ERROR_SPEC.md for allocation rules
+// See docs/error-spec.md for allocation rules
 
 /// BufferReaderError: 1000-1009
 #[contract_error]
@@ -44,7 +44,9 @@ pub enum BytesExtError {
 /// UpgradeableError: 1050-1059
 #[contract_error]
 pub enum UpgradeableError {
-    MigrationNotAllowed = 1050,
+    InvalidMigrationData = 1050,
+    MigrationNotAllowed,
+    UpgradesFrozen,
 }
 
 /// MultisigError: 1060-1069

package/contracts/utils/src/multisig.rs

@@ -58,7 +58,7 @@ pub trait Multisig: Auth {
     // ===========================================================================
 
     /// Adds or removes a signer from the multisig. Requires owner authorization.
-    fn set_signer(env: &Env, signer: &BytesN<20>, active: bool) {
+    fn set_signer(env: &soroban_sdk::Env, signer: &soroban_sdk::BytesN<20>, active: bool) {
         auth::require_auth::<Self>(env);
         match active {
             true => add_signer(env, signer),
@@ -67,7 +67,7 @@ pub trait Multisig: Auth {
     }
 
     /// Sets the signature threshold (quorum). Requires owner authorization.
-    fn set_threshold(env: &Env, threshold: u32) {
+    fn set_threshold(env: &soroban_sdk::Env, threshold: u32) {
         auth::require_auth::<Self>(env);
         set_threshold(env, threshold);
     }
@@ -77,22 +77,22 @@ pub trait Multisig: Auth {
     // ===========================================================================
 
     /// Returns all registered signers.
-    fn get_signers(env: &Env) -> Vec<BytesN<20>> {
+    fn get_signers(env: &soroban_sdk::Env) -> soroban_sdk::Vec<soroban_sdk::BytesN<20>> {
         MultisigStorage::signers(env)
     }
 
     /// Returns the total number of registered signers.
-    fn total_signers(env: &Env) -> u32 {
+    fn total_signers(env: &soroban_sdk::Env) -> u32 {
         MultisigStorage::signers(env).len()
     }
 
     /// Checks if an address is a registered signer.
-    fn is_signer(env: &Env, signer: &BytesN<20>) -> bool {
+    fn is_signer(env: &soroban_sdk::Env, signer: &soroban_sdk::BytesN<20>) -> bool {
         MultisigStorage::signers(env).iter().any(|s| &s == signer)
     }
 
     /// Returns the current signature threshold (quorum).
-    fn threshold(env: &Env) -> u32 {
+    fn threshold(env: &soroban_sdk::Env) -> u32 {
         MultisigStorage::threshold(env)
     }
 
@@ -101,12 +101,21 @@ pub trait Multisig: Auth {
     // ===========================================================================
 
     /// Verifies signatures against the configured threshold.
-    fn verify_signatures(env: &Env, digest: &BytesN<32>, signatures: &Vec<BytesN<65>>) {
+    fn verify_signatures(
+        env: &soroban_sdk::Env,
+        digest: &soroban_sdk::BytesN<32>,
+        signatures: &soroban_sdk::Vec<soroban_sdk::BytesN<65>>,
+    ) {
         Self::verify_n_signatures(env, digest, signatures, MultisigStorage::threshold(env));
     }
 
     /// Verifies signatures against a custom threshold.
-    fn verify_n_signatures(env: &Env, digest: &BytesN<32>, signatures: &Vec<BytesN<65>>, threshold: u32) {
+    fn verify_n_signatures(
+        env: &soroban_sdk::Env,
+        digest: &soroban_sdk::BytesN<32>,
+        signatures: &soroban_sdk::Vec<soroban_sdk::BytesN<65>>,
+        threshold: u32,
+    ) {
         assert_with_error!(env, threshold > 0, MultisigError::ZeroThreshold);
         assert_with_error!(env, signatures.len() >= threshold, MultisigError::SignatureError);
 

package/contracts/utils/src/ownable.rs

@@ -64,12 +64,12 @@ pub trait Ownable: Sized + Auth {
     // ===========================================================================
 
     /// Returns the current owner address, or None if no owner is set.
-    fn owner(env: &Env) -> Option<Address> {
+    fn owner(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
         OwnableStorage::owner(env)
     }
 
     /// Returns the pending owner address for 2-step transfer, or None if no transfer is pending.
-    fn pending_owner(env: &Env) -> Option<Address> {
+    fn pending_owner(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
         OwnableStorage::pending_owner(env)
     }
 
@@ -85,7 +85,7 @@ pub trait Ownable: Sized + Auth {
     /// # Panics
     /// - `OwnerNotSet` if no owner is currently set
     /// - `TransferInProgress` if a 2-step transfer is in progress
-    fn transfer_ownership(env: &Env, new_owner: &Address) {
+    fn transfer_ownership(env: &soroban_sdk::Env, new_owner: &soroban_sdk::Address) {
         let old_owner = enforce_owner_auth::<Self>(env);
         assert_no_pending_transfer::<Self>(env);
 
@@ -112,7 +112,7 @@ pub trait Ownable: Sized + Auth {
     /// - `NoPendingTransfer` when cancelling and no pending transfer exists
     /// - `InvalidTtl` if ttl exceeds max TTL
     /// - `InvalidPendingOwner` when cancelling with wrong new_owner address
-    fn propose_ownership_transfer(env: &Env, new_owner: &Address, ttl: u32) {
+    fn propose_ownership_transfer(env: &soroban_sdk::Env, new_owner: &soroban_sdk::Address, ttl: u32) {
         let old_owner = enforce_owner_auth::<Self>(env);
 
         // Cancel case: ttl == 0
@@ -142,7 +142,7 @@ pub trait Ownable: Sized + Auth {
     ///
     /// # Panics
     /// - `NoPendingTransfer` if there is no pending transfer (or it expired)
-    fn accept_ownership(env: &Env) {
+    fn accept_ownership(env: &soroban_sdk::Env) {
         let new_owner = Self::pending_owner(env).unwrap_or_panic(env, OwnableError::NoPendingTransfer);
 
         // Require authorization from the pending owner
@@ -169,7 +169,7 @@ pub trait Ownable: Sized + Auth {
     /// # Panics
     /// - `OwnerNotSet` if no owner is currently set
     /// - `TransferInProgress` if a 2-step transfer is in progress (cancel it first)
-    fn renounce_ownership(env: &Env) {
+    fn renounce_ownership(env: &soroban_sdk::Env) {
         let old_owner = enforce_owner_auth::<Self>(env);
         assert_no_pending_transfer::<Self>(env);
 

package/contracts/utils/src/testing_utils.rs

@@ -1,26 +1,76 @@
-use soroban_sdk::{testutils::Events, xdr::ToXdr, Address, Env, Event, Val, Vec};
+use soroban_sdk::{testutils::Events, xdr, Address, Env, Event, TryFromVal, Val, Vec};
 
-fn topics_eq(env: &Env, a: &Vec<Val>, b: &Vec<Val>) -> bool {
-    if a.len() != b.len() {
-        return false;
-    }
-    for i in 0..a.len() {
-        let av = a.get(i).unwrap();
-        let bv = b.get(i).unwrap();
-        // Compare XDR serialization for deep value equality
-        if av.to_xdr(env) != bv.to_xdr(env) {
-            return false;
-        }
+/// Decodes a raw emitted contract event (XDR) into `(topics, data)`.
+///
+/// Soroban testutils exposes events as [`ContractEvents`](soroban_sdk::testutils::ContractEvents),
+/// which internally stores XDR [`ContractEvent`](soroban_sdk::xdr::ContractEvent) values.
+/// This helper converts the XDR topics/data into `soroban_sdk::Val` so tests can inspect
+/// topics and data using normal Soroban conversions (`TryFromVal` / `IntoVal`).
+///
+/// Returns `None` if any topic or the data payload can't be converted into `Val` for the
+/// provided `Env`.
+///
+/// # Example
+/// ```ignore
+/// let events = env.events().all().filter_by_contract(&contract);
+/// for ev in events.events().iter() {
+///     let (topics, data) = utils::testing_utils::decode_event_topics_data(&env, ev).unwrap();
+///     // ... inspect topics/data ...
+/// }
+/// ```
+pub fn decode_event_topics_data(env: &Env, event: &xdr::ContractEvent) -> Option<(Vec<Val>, Val)> {
+    // In the current Soroban SDK version this is always `V0`.
+    // Using a single-variant match avoids "irrefutable let-else" warnings.
+    let v0 = match &event.body {
+        xdr::ContractEventBody::V0(v0) => v0,
+    };
+
+    let mut topics = Vec::<Val>::new(env);
+    for t in v0.topics.iter() {
+        topics.push_back(Val::try_from_val(env, t).ok()?);
     }
-    true
+    let data = Val::try_from_val(env, &v0.data).ok()?;
+    Some((topics, data))
 }
 
-fn data_eq(env: &Env, a: &Val, b: &Val) -> bool {
-    // Compare XDR serialization for deep value equality
-    a.to_xdr(env) == b.to_xdr(env)
+/// Asserts that the environment emitted exactly one event: `expected`.
+///
+/// This is a **strict equality** assertion over `env.events().all()`:
+/// the full event list must be exactly `[expected]` (no extra events).
+///
+/// Uses the event struct's `.topics()` and `.data()` methods (generated by `#[contractevent]`)
+/// to compare against emitted events. No more hardcoding topic names or field keys!
+///
+/// # Example
+/// ```ignore
+/// use crate::events::OwnershipTransferred;
+///
+/// let expected = OwnershipTransferred {
+///     previous_owner: owner.clone(),
+///     new_owner: new_owner.clone(),
+/// };
+/// assert_eq_event(&env, &contract, expected);
+/// ```
+pub fn assert_eq_event<E: Event>(env: &Env, contract: &Address, expected: E) {
+    // Compare against the emitted `xdr::ContractEvent` directly. This avoids the
+    // `xdr -> Val` roundtrip and ensures we match exactly what was emitted.
+    //
+    // IMPORTANT: This asserts *equality* (not "contains").
+    extern crate std;
+
+    assert_eq!(
+        env.events().all(),
+        std::vec![expected.to_xdr(env, contract)],
+        "Expected exactly one event. Expected topics: {:?}, data: {:?}",
+        expected.topics(env),
+        expected.data(env),
+    );
 }
 
-/// Asserts that an event matching the expected event was emitted from the contract.
+/// Asserts that the contract emitted an event equal to `expected`.
+///
+/// This is a **contains** assertion: after filtering events by `contract`,
+/// `expected` must appear at least once (order doesn't matter; extra events allowed).
 ///
 /// Uses the event struct's `.topics()` and `.data()` methods (generated by `#[contractevent]`)
 /// to compare against emitted events. No more hardcoding topic names or field keys!
@@ -33,68 +83,86 @@ fn data_eq(env: &Env, a: &Val, b: &Val) -> bool {
 ///     previous_owner: owner.clone(),
 ///     new_owner: new_owner.clone(),
 /// };
-/// assert_event(&env, &contract, expected);
+/// assert_eq_event(&env, &contract, expected);
 /// ```
-pub fn assert_event<E: Event>(env: &Env, contract: &Address, expected: E) {
-    let events = env.events().all();
-    let expected_topics: Vec<Val> = expected.topics(env);
-    let expected_data: Val = expected.data(env);
+pub fn assert_contains_event<E: Event>(env: &Env, contract: &Address, expected: E) {
+    // Compare against the emitted `xdr::ContractEvent` directly. This avoids the
+    // `xdr -> Val` roundtrip and ensures we match exactly what was emitted.
+    let expected_xdr = expected.to_xdr(env, contract);
 
+    let events = env.events().all().filter_by_contract(contract);
     let mut found = false;
-    for (address, topics, data) in events.iter() {
-        if &address == contract && topics_eq(env, &topics, &expected_topics) && data_eq(env, &data, &expected_data) {
+    for event in events.events().iter() {
+        if *event == expected_xdr {
             found = true;
             break;
         }
     }
 
-    assert!(found, "Expected event not found. Expected topics: {:?}, data: {:?}", expected_topics, expected_data);
+    assert!(
+        found,
+        "Expected event not found. Expected topics: {:?}, data: {:?}",
+        expected.topics(env),
+        expected.data(env)
+    );
 }
 
-/// A helper struct to hold event topics and data for batch assertion with mixed event types.
-pub struct ExpectedEvent {
-    pub topics: Vec<Val>,
-    pub data: Val,
-}
+/// Asserts that the environment emitted events that match `expected_events` exactly.
+///
+/// This is a **strict equality** assertion over `env.events().all()`:
+/// the full event list must match `expected_events` **in order** and **count**
+/// (no missing/extra events).
+///
+/// # Example
+/// ```ignore
+/// assert_eq_events(env, &contract, &[
+///     &Event1 { ... },
+///     &Event2 { ... },
+/// ]);
+/// ```
 
-pub trait IntoExpectedEvent: Event + Sized {
-    fn expected(self, env: &Env) -> ExpectedEvent {
-        ExpectedEvent { topics: self.topics(env), data: self.data(env) }
-    }
-}
+pub fn assert_eq_events(env: &Env, contract: &Address, expected_events: &[&dyn Event]) {
+    // Note: this module is only compiled for tests / testutils usage, where `std` is available.
+    extern crate std;
+    let expected_xdrs: std::vec::Vec<xdr::ContractEvent> =
+        expected_events.iter().map(|e| e.to_xdr(env, contract)).collect();
 
-// Blanket implementation for all Event types
-impl<E: Event> IntoExpectedEvent for E {}
+    assert_eq!(env.events().all(), expected_xdrs, "Expected events to match exactly");
+}
 
-/// Asserts that all expected events were emitted from the contract (in any order).
-/// Use this when asserting multiple events of different types.
+/// Asserts that all `expected_events` were emitted by the contract (in any order).
+///
+/// This is a **contains** assertion with multiset semantics: after filtering events by
+/// `contract`, every expected event must be present, and duplicates in `expected_events`
+/// require duplicate emissions. Extra emitted events are allowed.
 ///
 /// # Example
 /// ```ignore
-/// use utils::testing_utils::IntoExpectedEvent;
-///
-/// assert_events(env, &contract, &[
-///     Event1 { ... }.expected(env),
-///     Event2 { ... }.expected(env),
+/// assert_eq_events(env, &contract, &[
+///     &Event1 { ... },
+///     &Event2 { ... },
 /// ]);
 /// ```
-pub fn assert_events(env: &Env, contract: &Address, expected_events: &[ExpectedEvent]) {
-    let events = env.events().all();
-    // Track which emitted events have already been matched so that duplicate expectations
-    // require duplicate emissions (multiset semantics).
-    //
+
+pub fn assert_contains_events(env: &Env, contract: &Address, expected_events: &[&dyn Event]) {
     // Note: this module is only compiled for tests / testutils usage, where `std` is available.
     extern crate std;
-    let mut used: std::vec::Vec<bool> = std::vec![false; events.len() as usize];
+    let events = env.events().all().filter_by_contract(contract);
+    let raw_events = events.events();
+    // Track which emitted events have already been matched so that duplicate expectations
+    // require duplicate emissions (multiset semantics).
+    // We use a `std::vec::Vec<bool>` as a "used" mask to implement multiset matching.
+    let mut used: std::vec::Vec<bool> = std::vec![false; raw_events.len()];
 
     for (i, expected) in expected_events.iter().enumerate() {
+        let expected_xdr = expected.to_xdr(env, contract);
+
         let mut found = false;
-        for (idx, (address, topics, data)) in events.iter().enumerate() {
+        for (idx, event) in raw_events.iter().enumerate() {
             if used[idx] {
                 continue;
             }
-            if &address == contract && topics_eq(env, &topics, &expected.topics) && data_eq(env, &data, &expected.data)
-            {
+            if *event == expected_xdr {
                 used[idx] = true;
                 found = true;
                 break;
@@ -104,7 +172,9 @@ pub fn assert_events(env: &Env, contract: &Address, expected_events: &[ExpectedE
         assert!(
             found,
             "Expected event #{} not found. Expected topics: {:?}, data: {:?}",
-            i, expected.topics, expected.data
+            i,
+            expected.topics(env),
+            expected.data(env)
         );
     }
 }