@layerzerolabs/protocol-stellar-v2 0.2.40 → 0.2.41

package/contracts/utils/src/tests/ownable.rs

@@ -169,11 +169,11 @@ fn transfer_ownership_blocked_during_2step() {
         invoke: &MockAuthInvoke {
             contract: &contract,
             args: (&new_owner, ttl).into_val(&env),
-            fn_name: "propose_ownership_transfer",
+            fn_name: "begin_ownership_transfer",
             sub_invokes: &[],
         },
     }]);
-    client.propose_ownership_transfer(&new_owner, &ttl);
+    client.begin_ownership_transfer(&new_owner, &ttl);
 
     // Try single-step transfer - should fail
     env.mock_auths(&[MockAuth {
@@ -193,7 +193,7 @@ fn transfer_ownership_blocked_during_2step() {
 // ============================================
 
 #[test]
-fn propose_ownership_transfer_initiate_and_accept() {
+fn begin_ownership_transfer_initiate_and_accept() {
     let env = Env::default();
     let owner = Address::generate(&env);
     let new_owner = Address::generate(&env);
@@ -212,11 +212,11 @@ fn propose_ownership_transfer_initiate_and_accept() {
         invoke: &MockAuthInvoke {
             contract: &contract,
             args: (&new_owner, ttl).into_val(&env),
-            fn_name: "propose_ownership_transfer",
+            fn_name: "begin_ownership_transfer",
             sub_invokes: &[],
         },
     }]);
-    client.propose_ownership_transfer(&new_owner, &ttl);
+    client.begin_ownership_transfer(&new_owner, &ttl);
 
     assert_eq_event(
         &env,
@@ -262,11 +262,11 @@ fn pending_owner_expires_after_ttl() {
         invoke: &MockAuthInvoke {
             contract: &contract,
             args: (&new_owner, ttl).into_val(&env),
-            fn_name: "propose_ownership_transfer",
+            fn_name: "begin_ownership_transfer",
             sub_invokes: &[],
         },
     }]);
-    client.propose_ownership_transfer(&new_owner, &ttl);
+    client.begin_ownership_transfer(&new_owner, &ttl);
     assert_eq!(client.pending_owner(), Some(new_owner.clone()));
 
     // Advance ledger beyond the actual storage TTL window; temporary pending owner entry should expire.
@@ -287,7 +287,7 @@ fn pending_owner_expires_after_ttl() {
 }
 
 #[test]
-fn propose_ownership_transfer_cancel() {
+fn begin_ownership_transfer_cancel() {
     let env = Env::default();
     let owner = Address::generate(&env);
     let new_owner = Address::generate(&env);
@@ -303,11 +303,11 @@ fn propose_ownership_transfer_cancel() {
         invoke: &MockAuthInvoke {
             contract: &contract,
             args: (&new_owner, ttl).into_val(&env),
-            fn_name: "propose_ownership_transfer",
+            fn_name: "begin_ownership_transfer",
             sub_invokes: &[],
         },
     }]);
-    client.propose_ownership_transfer(&new_owner, &ttl);
+    client.begin_ownership_transfer(&new_owner, &ttl);
 
     assert_eq!(client.pending_owner(), Some(new_owner.clone()));
 
@@ -317,11 +317,11 @@ fn propose_ownership_transfer_cancel() {
         invoke: &MockAuthInvoke {
             contract: &contract,
             args: (&new_owner, 0u32).into_val(&env),
-            fn_name: "propose_ownership_transfer",
+            fn_name: "begin_ownership_transfer",
             sub_invokes: &[],
         },
     }]);
-    client.propose_ownership_transfer(&new_owner, &0u32);
+    client.begin_ownership_transfer(&new_owner, &0u32);
 
     // No event emitted on cancel (matching OpenZeppelin behavior)
     assert_eq!(client.owner(), Some(owner)); // Still old owner
@@ -329,7 +329,7 @@ fn propose_ownership_transfer_cancel() {
 }
 
 #[test]
-fn propose_ownership_transfer_with_max_ttl() {
+fn begin_ownership_transfer_with_max_ttl() {
     let env = Env::default();
     let owner = Address::generate(&env);
     let new_owner = Address::generate(&env);
@@ -345,11 +345,11 @@ fn propose_ownership_transfer_with_max_ttl() {
         invoke: &MockAuthInvoke {
             contract: &contract,
             args: (&new_owner, max_ttl).into_val(&env),
-            fn_name: "propose_ownership_transfer",
+            fn_name: "begin_ownership_transfer",
             sub_invokes: &[],
         },
     }]);
-    client.propose_ownership_transfer(&new_owner, &max_ttl);
+    client.begin_ownership_transfer(&new_owner, &max_ttl);
 
     assert_eq!(client.pending_owner(), Some(new_owner.clone()));
 
@@ -363,7 +363,7 @@ fn propose_ownership_transfer_with_max_ttl() {
 
 #[test]
 #[should_panic(expected = "Error(Contract, #1033)")] // NoPendingTransfer
-fn propose_ownership_transfer_cancel_no_pending_fails() {
+fn begin_ownership_transfer_cancel_no_pending_fails() {
     let env = Env::default();
     let owner = Address::generate(&env);
     let new_owner = Address::generate(&env);
@@ -377,16 +377,16 @@ fn propose_ownership_transfer_cancel_no_pending_fails() {
         invoke: &MockAuthInvoke {
             contract: &contract,
             args: (&new_owner, 0u32).into_val(&env),
-            fn_name: "propose_ownership_transfer",
+            fn_name: "begin_ownership_transfer",
             sub_invokes: &[],
         },
     }]);
-    client.propose_ownership_transfer(&new_owner, &0u32);
+    client.begin_ownership_transfer(&new_owner, &0u32);
 }
 
 #[test]
 #[should_panic(expected = "Error(Contract, #1031)")] // InvalidPendingOwner
-fn propose_ownership_transfer_cancel_wrong_address_fails() {
+fn begin_ownership_transfer_cancel_wrong_address_fails() {
     let env = Env::default();
     let owner = Address::generate(&env);
     let new_owner = Address::generate(&env);
@@ -403,11 +403,11 @@ fn propose_ownership_transfer_cancel_wrong_address_fails() {
         invoke: &MockAuthInvoke {
             contract: &contract,
             args: (&new_owner, ttl).into_val(&env),
-            fn_name: "propose_ownership_transfer",
+            fn_name: "begin_ownership_transfer",
             sub_invokes: &[],
         },
     }]);
-    client.propose_ownership_transfer(&new_owner, &ttl);
+    client.begin_ownership_transfer(&new_owner, &ttl);
 
     // Try to cancel with wrong address
     env.mock_auths(&[MockAuth {
@@ -415,16 +415,16 @@ fn propose_ownership_transfer_cancel_wrong_address_fails() {
         invoke: &MockAuthInvoke {
             contract: &contract,
             args: (&wrong_owner, 0u32).into_val(&env),
-            fn_name: "propose_ownership_transfer",
+            fn_name: "begin_ownership_transfer",
             sub_invokes: &[],
         },
     }]);
-    client.propose_ownership_transfer(&wrong_owner, &0u32);
+    client.begin_ownership_transfer(&wrong_owner, &0u32);
 }
 
 #[test]
 #[should_panic(expected = "Error(Contract, #1032)")] // InvalidTtl
-fn propose_ownership_transfer_invalid_ttl_exceeds_max_fails() {
+fn begin_ownership_transfer_invalid_ttl_exceeds_max_fails() {
     let env = Env::default();
     let owner = Address::generate(&env);
     let new_owner = Address::generate(&env);
@@ -440,12 +440,12 @@ fn propose_ownership_transfer_invalid_ttl_exceeds_max_fails() {
         invoke: &MockAuthInvoke {
             contract: &contract,
             args: (&new_owner, ttl).into_val(&env),
-            fn_name: "propose_ownership_transfer",
+            fn_name: "begin_ownership_transfer",
             sub_invokes: &[],
         },
     }]);
 
-    client.propose_ownership_transfer(&new_owner, &ttl);
+    client.begin_ownership_transfer(&new_owner, &ttl);
 }
 
 #[test]
@@ -490,11 +490,11 @@ fn accept_ownership_wrong_address_fails() {
         invoke: &MockAuthInvoke {
             contract: &contract,
             args: (&new_owner, ttl).into_val(&env),
-            fn_name: "propose_ownership_transfer",
+            fn_name: "begin_ownership_transfer",
             sub_invokes: &[],
         },
     }]);
-    client.propose_ownership_transfer(&new_owner, &ttl);
+    client.begin_ownership_transfer(&new_owner, &ttl);
 
     // Try to accept with wrong address
     env.mock_auths(&[MockAuth {
@@ -510,7 +510,7 @@ fn accept_ownership_wrong_address_fails() {
 }
 
 #[test]
-fn propose_ownership_transfer_override_pending() {
+fn begin_ownership_transfer_override_pending() {
     let env = Env::default();
     let owner = Address::generate(&env);
     let new_owner1 = Address::generate(&env);
@@ -527,11 +527,11 @@ fn propose_ownership_transfer_override_pending() {
         invoke: &MockAuthInvoke {
             contract: &contract,
             args: (&new_owner1, ttl).into_val(&env),
-            fn_name: "propose_ownership_transfer",
+            fn_name: "begin_ownership_transfer",
             sub_invokes: &[],
         },
     }]);
-    client.propose_ownership_transfer(&new_owner1, &ttl);
+    client.begin_ownership_transfer(&new_owner1, &ttl);
 
     assert_eq!(client.pending_owner(), Some(new_owner1.clone()));
 
@@ -541,11 +541,11 @@ fn propose_ownership_transfer_override_pending() {
         invoke: &MockAuthInvoke {
             contract: &contract,
             args: (&new_owner2, ttl).into_val(&env),
-            fn_name: "propose_ownership_transfer",
+            fn_name: "begin_ownership_transfer",
             sub_invokes: &[],
         },
     }]);
-    client.propose_ownership_transfer(&new_owner2, &ttl);
+    client.begin_ownership_transfer(&new_owner2, &ttl);
 
     assert_eq!(client.pending_owner(), Some(new_owner2.clone()));
 
@@ -636,11 +636,11 @@ fn renounce_blocked_during_2step_transfer() {
         invoke: &MockAuthInvoke {
             contract: &contract,
             args: (&new_owner, ttl).into_val(&env),
-            fn_name: "propose_ownership_transfer",
+            fn_name: "begin_ownership_transfer",
             sub_invokes: &[],
         },
     }]);
-    client.propose_ownership_transfer(&new_owner, &ttl);
+    client.begin_ownership_transfer(&new_owner, &ttl);
 
     // Try to renounce - should fail
     env.mock_auths(&[MockAuth {
@@ -703,11 +703,11 @@ fn chain_new_owner_can_transfer_2step() {
         invoke: &MockAuthInvoke {
             contract: &contract,
             args: (&new_owner, ttl).into_val(&env),
-            fn_name: "propose_ownership_transfer",
+            fn_name: "begin_ownership_transfer",
             sub_invokes: &[],
         },
     }]);
-    client.propose_ownership_transfer(&new_owner, &ttl);
+    client.begin_ownership_transfer(&new_owner, &ttl);
 
     env.mock_auths(&[MockAuth {
         address: &new_owner,
@@ -726,11 +726,11 @@ fn chain_new_owner_can_transfer_2step() {
         invoke: &MockAuthInvoke {
             contract: &contract,
             args: (&third_owner, ttl).into_val(&env),
-            fn_name: "propose_ownership_transfer",
+            fn_name: "begin_ownership_transfer",
             sub_invokes: &[],
         },
     }]);
-    client.propose_ownership_transfer(&third_owner, &ttl);
+    client.begin_ownership_transfer(&third_owner, &ttl);
 
     env.mock_auths(&[MockAuth {
         address: &third_owner,

package/contracts/utils/src/upgradeable.rs

@@ -1,8 +1,11 @@
-use crate::{self as utils, auth::Auth, errors::UpgradeableError, option_ext::OptionExt};
-use common_macros::{contract_trait, only_auth, storage};
-use soroban_sdk::{assert_with_error, xdr::FromXdr, Env};
+use crate::{self as utils, auth::Auth, errors::UpgradeableError, option_ext::OptionExt, rbac::RoleBasedAccessControl};
+use common_macros::{contract_trait, only_auth, only_role, storage};
+use soroban_sdk::{assert_with_error, xdr::FromXdr, Bytes, BytesN, Env};
 
-/// Trait for contracts with upgrade and migration support.
+/// Role for upgrading the contract and running migrations.
+pub const UPGRADER_ROLE: &str = "UPGRADER_ROLE";
+
+/// Trait for contracts with upgrade and migration support (Auth-based).
 ///
 /// Implements a two-phase upgrade pattern:
 /// 1. `upgrade` - Updates WASM bytecode and sets migration flag
@@ -12,32 +15,40 @@ use soroban_sdk::{assert_with_error, xdr::FromXdr, Env};
 #[contract_trait]
 pub trait Upgradeable: UpgradeableInternal + Auth {
     /// Upgrades the contract to new WASM bytecode.
-    /// Sets a migration flag that must be cleared by calling `migrate`.
     #[only_auth]
     fn upgrade(env: &soroban_sdk::Env, new_wasm_hash: &soroban_sdk::BytesN<32>) {
-        UpgradeableStorage::set_migrating(env, &true);
-        env.deployer().update_current_contract_wasm(new_wasm_hash.clone());
+        upgrade(env, new_wasm_hash);
     }
 
     /// Runs migration logic after an upgrade.
-    /// Parses XDR-encoded `migration_data` and calls `__migrate`. Clears the migration flag on success.
     #[only_auth]
     fn migrate(env: &soroban_sdk::Env, migration_data: &soroban_sdk::Bytes) {
-        assert_with_error!(env, UpgradeableStorage::migrating(env), UpgradeableError::MigrationNotAllowed);
+        migrate::<Self>(env, migration_data);
+    }
+}
 
-        // Parse the migration data and call the internal migration logic
-        let parsed_data = Self::MigrationData::from_xdr(env, migration_data)
-            .ok()
-            .unwrap_or_panic(env, UpgradeableError::InvalidMigrationData);
-        Self::__migrate(env, &parsed_data);
+/// Trait for contracts with upgrade and migration support (RBAC-based).
+///
+/// Same two-phase upgrade pattern as [`Upgradeable`], but access control uses
+/// `UPGRADER_ROLE` instead of Auth. Requires implementing [`UpgradeableInternal`]
+/// and [`RoleBasedAccessControl`].
+#[contract_trait]
+pub trait UpgradeableRbac: UpgradeableInternal + RoleBasedAccessControl {
+    /// Upgrades the contract to new WASM bytecode.
+    #[only_role(operator, UPGRADER_ROLE)]
+    fn upgrade(env: &soroban_sdk::Env, new_wasm_hash: &soroban_sdk::BytesN<32>, operator: &soroban_sdk::Address) {
+        upgrade(env, new_wasm_hash);
+    }
 
-        // Clear the migration flag after migration is successful
-        UpgradeableStorage::set_migrating(env, &false);
+    /// Runs migration logic after an upgrade.
+    #[only_role(operator, UPGRADER_ROLE)]
+    fn migrate(env: &soroban_sdk::Env, migration_data: &soroban_sdk::Bytes, operator: &soroban_sdk::Address) {
+        migrate::<Self>(env, migration_data);
     }
 }
 
 /// Trait for defining contract-specific migration logic.
-/// Must be implemented by contracts using [`Upgradeable`].
+/// Must be implemented by contracts using [`Upgradeable`] or [`UpgradeableRbac`].
 pub trait UpgradeableInternal {
     /// The XDR-decodable type for migration data. Use `()` if not needed.
     type MigrationData: FromXdr;
@@ -46,6 +57,38 @@ pub trait UpgradeableInternal {
     fn __migrate(env: &Env, migration_data: &Self::MigrationData);
 }
 
+// ============================================
+// Helper Functions
+// ============================================
+
+/// Core upgrade logic: set migrating flag and update WASM.
+///
+/// # Arguments
+/// - `new_wasm_hash` - The hash of the new WASM bytecode
+fn upgrade(env: &Env, new_wasm_hash: &BytesN<32>) {
+    UpgradeableStorage::set_migrating(env, &true);
+    env.deployer().update_current_contract_wasm(new_wasm_hash.clone());
+}
+
+/// Core migration logic: parse migration data, call `__migrate`, clear flag.
+///
+/// # Arguments
+/// - `migration_data` - The migration data
+///
+/// # Panics
+/// - `MigrationNotAllowed` if no migration is in progress
+/// - `InvalidMigrationData` if the migration data cannot be parsed into the contract's `MigrationData` type
+fn migrate<T: UpgradeableInternal>(env: &Env, migration_data: &Bytes) {
+    assert_with_error!(env, UpgradeableStorage::migrating(env), UpgradeableError::MigrationNotAllowed);
+
+    let parsed_data = T::MigrationData::from_xdr(env, migration_data)
+        .ok()
+        .unwrap_or_panic(env, UpgradeableError::InvalidMigrationData);
+    T::__migrate(env, &parsed_data);
+
+    UpgradeableStorage::set_migrating(env, &false);
+}
+
 // ============================================
 // Storage
 // ============================================

package/docs/oapp-guide.md

@@ -76,14 +76,14 @@ The `initialize_oapp` function:
 Before sending or receiving messages, configure peers for each destination chain:
 
 ```rust
-// Set a peer (owner only)
-oapp.set_peer(dst_eid, peer_address_bytes32);
+// Set a peer (owner only). Pass owner as operator (reserved for future RBAC).
+oapp.set_peer(env, dst_eid, &Some(peer_address_bytes32), &owner);
 
 // Remove a peer
-oapp.set_peer(dst_eid, None);
+oapp.set_peer(env, dst_eid, &None, &owner);
 
 // Query a peer
-let peer = oapp.peer(dst_eid);
+let peer = oapp.peer(env, dst_eid);
 ```
 
 Peers are stored as `BytesN<32>` to maintain cross-chain address compatibility.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@layerzerolabs/protocol-stellar-v2",
-  "version": "0.2.40",
+  "version": "0.2.41",
   "private": false,
   "devDependencies": {
     "@types/node": "^22.18.6",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
-    "@layerzerolabs/common-node-utils": "0.2.40",
-    "@layerzerolabs/vm-tooling-stellar": "0.2.40"
+    "@layerzerolabs/common-node-utils": "0.2.41",
+    "@layerzerolabs/vm-tooling-stellar": "0.2.41"
   },
   "publishConfig": {
     "access": "restricted",
@@ -25,7 +25,6 @@
     "generate:sdk": "pnpm exec lz-tool --script \"cargo run -p ts-bindings-gen\" stellar",
     "lint": "pnpm exec lz-tool --script \"cargo clippy -- -D warnings\" stellar",
     "lint:fix": "pnpm exec lz-tool --script \"cargo clippy --fix --allow-dirty --allow-staged && cargo fmt\" stellar",
-    "setup:toolchain": "pnpm exec lz-tool sync-toolchain",
     "test": "pnpm exec lz-tool --script \"cargo nextest run\" stellar"
   }
 }