@layerzerolabs/protocol-stellar-v2 0.2.40 → 0.2.43

package/contracts/oapps/oft-core/src/tests/test_msg_inspector.rs

@@ -60,17 +60,17 @@ fn test_set_msg_inspector() {
     // Deploy a passing inspector
     let inspector_address = env.register(PassingInspector, ());
 
-    // Owner sets the inspector
+    // Owner (with OAPP_ADMIN_ROLE) sets the inspector
     env.mock_auths(&[MockAuth {
         address: &setup.owner,
         invoke: &MockAuthInvoke {
             contract: &setup.oft.address,
             fn_name: "set_msg_inspector",
-            args: (&Some(inspector_address.clone()),).into_val(&env),
+            args: (&Some(inspector_address.clone()), &setup.owner).into_val(&env),
             sub_invokes: &[],
         },
     }]);
-    setup.oft.set_msg_inspector(&Some(inspector_address.clone()));
+    setup.oft.set_msg_inspector(&Some(inspector_address.clone()), &setup.owner);
 
     // Verify inspector is set
     let stored_inspector = setup.oft.msg_inspector();
@@ -90,11 +90,11 @@ fn test_remove_msg_inspector() {
         invoke: &MockAuthInvoke {
             contract: &setup.oft.address,
             fn_name: "set_msg_inspector",
-            args: (&Some(inspector_address.clone()),).into_val(&env),
+            args: (&Some(inspector_address.clone()), &setup.owner).into_val(&env),
             sub_invokes: &[],
         },
     }]);
-    setup.oft.set_msg_inspector(&Some(inspector_address));
+    setup.oft.set_msg_inspector(&Some(inspector_address), &setup.owner);
 
     // Verify it's set
     assert!(setup.oft.msg_inspector().is_some());
@@ -105,11 +105,11 @@ fn test_remove_msg_inspector() {
         invoke: &MockAuthInvoke {
             contract: &setup.oft.address,
             fn_name: "set_msg_inspector",
-            args: (&None::<Address>,).into_val(&env),
+            args: (&None::<Address>, &setup.owner).into_val(&env),
             sub_invokes: &[],
         },
     }]);
-    setup.oft.set_msg_inspector(&None);
+    setup.oft.set_msg_inspector(&None, &setup.owner);
 
     // Verify inspector is removed
     let stored_inspector = setup.oft.msg_inspector();
@@ -119,7 +119,7 @@ fn test_remove_msg_inspector() {
 // ==================== Access Control Tests ====================
 
 #[test]
-#[should_panic(expected = "HostError: Error(Auth, InvalidAction)")]
+#[should_panic(expected = "Error(Contract, #1086)")] // RbacError::Unauthorized
 fn test_set_msg_inspector_requires_owner() {
     let env = Env::default();
     let setup = OFTTestSetup::new(&env);
@@ -127,20 +127,20 @@ fn test_set_msg_inspector_requires_owner() {
     // Deploy a passing inspector
     let inspector_address = env.register(PassingInspector, ());
 
-    // Non-owner tries to set the inspector (no mock_auth for owner)
+    // Non-owner (without OAPP_ADMIN_ROLE) tries to set the inspector
     let non_owner = Address::generate(&env);
     env.mock_auths(&[MockAuth {
         address: &non_owner,
         invoke: &MockAuthInvoke {
             contract: &setup.oft.address,
             fn_name: "set_msg_inspector",
-            args: (&Some(inspector_address.clone()),).into_val(&env),
+            args: (&Some(inspector_address.clone()), &non_owner).into_val(&env),
             sub_invokes: &[],
         },
     }]);
 
-    // This should panic because non_owner is not the owner
-    setup.oft.set_msg_inspector(&Some(inspector_address));
+    // This should panic because non_owner does not have OAPP_ADMIN_ROLE
+    setup.oft.set_msg_inspector(&Some(inspector_address), &non_owner);
 }
 
 // ==================== Integration Tests with Send ====================
@@ -184,11 +184,11 @@ fn test_send_with_passing_inspector() {
         invoke: &MockAuthInvoke {
             contract: &setup.oft.address,
             fn_name: "set_msg_inspector",
-            args: (&Some(inspector_address.clone()),).into_val(&env),
+            args: (&Some(inspector_address.clone()), &setup.owner).into_val(&env),
             sub_invokes: &[],
         },
     }]);
-    setup.oft.set_msg_inspector(&Some(inspector_address));
+    setup.oft.set_msg_inspector(&Some(inspector_address), &setup.owner);
 
     let sender = Address::generate(&env);
 
@@ -224,11 +224,11 @@ fn test_send_with_failing_inspector() {
         invoke: &MockAuthInvoke {
             contract: &setup.oft.address,
             fn_name: "set_msg_inspector",
-            args: (&Some(inspector_address.clone()),).into_val(&env),
+            args: (&Some(inspector_address.clone()), &setup.owner).into_val(&env),
             sub_invokes: &[],
         },
     }]);
-    setup.oft.set_msg_inspector(&Some(inspector_address));
+    setup.oft.set_msg_inspector(&Some(inspector_address), &setup.owner);
 
     let sender = Address::generate(&env);
 
@@ -266,11 +266,11 @@ fn test_quote_send_with_passing_inspector() {
         invoke: &MockAuthInvoke {
             contract: &setup.oft.address,
             fn_name: "set_msg_inspector",
-            args: (&Some(inspector_address.clone()),).into_val(&env),
+            args: (&Some(inspector_address.clone()), &setup.owner).into_val(&env),
             sub_invokes: &[],
         },
     }]);
-    setup.oft.set_msg_inspector(&Some(inspector_address));
+    setup.oft.set_msg_inspector(&Some(inspector_address), &setup.owner);
 
     let sender = Address::generate(&env);
 
@@ -300,11 +300,11 @@ fn test_quote_send_with_failing_inspector() {
         invoke: &MockAuthInvoke {
             contract: &setup.oft.address,
             fn_name: "set_msg_inspector",
-            args: (&Some(inspector_address.clone()),).into_val(&env),
+            args: (&Some(inspector_address.clone()), &setup.owner).into_val(&env),
             sub_invokes: &[],
         },
     }]);
-    setup.oft.set_msg_inspector(&Some(inspector_address));
+    setup.oft.set_msg_inspector(&Some(inspector_address), &setup.owner);
 
     let sender = Address::generate(&env);
 

package/contracts/oapps/oft-core/src/tests/test_utils.rs

@@ -8,7 +8,7 @@ use crate::{
     types::{OFTReceipt, SendParam},
 };
 use endpoint_v2::{LayerZeroReceiverClient, MessagingFee, MessagingParams, MessagingReceipt, Origin};
-use oapp::oapp_core::OAppCoreClient;
+use oapp::oapp_core::{OAppCoreClient, OAPP_ADMIN_ROLE};
 use soroban_sdk::{
     address_payload::AddressPayload,
     bytes, contract, contractimpl, log, symbol_short,
@@ -16,6 +16,7 @@ use soroban_sdk::{
     token::{StellarAssetClient, TokenClient},
     Address, Bytes, BytesN, Env, IntoVal, String, Symbol,
 };
+use utils::rbac::grant_role_no_auth;
 
 // ==================== Constants ====================
 
@@ -99,6 +100,20 @@ pub fn create_origin(src_eid: u32, sender: &BytesN<32>, nonce: u64) -> Origin {
     Origin { src_eid, sender: sender.clone(), nonce }
 }
 
+fn grant_oapp_admin(env: &Env, contract: &Address, owner: &Address) {
+    let role = Symbol::new(env, oapp::oapp_core::OAPP_ADMIN_ROLE);
+    env.mock_auths(&[MockAuth {
+        address: owner,
+        invoke: &MockAuthInvoke {
+            contract,
+            fn_name: "grant_role",
+            args: (owner, &role, owner).into_val(env),
+            sub_invokes: &[],
+        },
+    }]);
+    utils::rbac::RoleBasedAccessControlClient::new(env, contract).grant_role(owner, &role, owner);
+}
+
 // ==================== Test OFT Contracts ====================
 
 mod test_mint_burn_oft {
@@ -118,6 +133,7 @@ mod test_mint_burn_oft {
     }
 
     #[oapp_macros::oapp]
+    #[common_macros::lz_contract]
     pub struct TestMintBurnOFT;
 
     #[contractimpl]
@@ -178,6 +194,7 @@ mod test_lock_unlock_oft {
     use soroban_sdk::{contractimpl, token::TokenClient, Address, Bytes, BytesN, Env};
 
     #[oapp_macros::oapp(custom = [receiver])]
+    #[common_macros::lz_contract]
     pub struct TestLockUnlockOFT;
 
     #[contractimpl]
@@ -596,6 +613,16 @@ impl<'a> OFTTestSetupBuilder<'a> {
         OFTTestSetup::mint_to(env, &owner, &native_token, &owner, INITIAL_MINT_AMOUNT);
         OFTTestSetup::mint_to(env, &owner, &zro_token, &owner, INITIAL_MINT_AMOUNT);
 
+        // Grant OAPP_ADMIN_ROLE to owner so they can call set_peer, set_delegate, set_msg_inspector, etc.
+        env.as_contract(&oft_address, || {
+            grant_role_no_auth(
+                env,
+                &owner,
+                &Symbol::new(env, OAPP_ADMIN_ROLE),
+                &owner,
+            );
+        });
+
         // Setup based on OFT type
         match oft_type {
             OFTType::MintBurn => {
@@ -649,16 +676,19 @@ impl<'a> OFTTestSetup<'a> {
     }
 
     pub fn set_peer(&self, eid: u32, peer: &BytesN<32>) {
+        grant_oapp_admin(self.env, &self.oft.address, &self.owner);
+
+        let peer_option = Some(peer.clone());
         self.env.mock_auths(&[MockAuth {
             address: &self.owner,
             invoke: &MockAuthInvoke {
                 contract: &self.oft.address,
                 fn_name: "set_peer",
-                args: (&eid, peer).into_val(self.env),
+                args: (&eid, &peer_option, &self.owner).into_val(self.env),
                 sub_invokes: &[],
             },
         }]);
-        OAppCoreClient::new(self.env, &self.oft.address).set_peer(&eid, &Some(peer.clone()));
+        OAppCoreClient::new(self.env, &self.oft.address).set_peer(&eid, &peer_option, &self.owner);
     }
 
     pub fn mint_to(env: &Env, owner: &Address, token: &Address, to: &Address, amount: i128) {

package/contracts/upgrader/src/lib.rs

@@ -2,30 +2,47 @@
 
 //! # Upgrader Contract
 //!
-//! A stateless utility contract for performing atomic upgrade and migrate operations
-//! on contracts implementing the [`Upgradeable`](utils::upgradeable::Upgradeable) trait.
+//! A stateless utility contract for performing atomic upgrade-and-migrate operations
+//! on contracts that implement [`Upgradeable`](utils::upgradeable::Upgradeable) (Auth-based)
+//! or [`UpgradeableRbac`](utils::upgradeable::UpgradeableRbac) (RBAC-based).
 //!
-//! ## Security Model
+//! ## Security model
 //!
-//! 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.
+//! The Upgrader is permissionless: anyone may call it. Security is enforced by the target
+//! contract’s authorization:
+//! - **Auth-based**: the target’s `#[only_auth]` ensures only its authorizer can upgrade/migrate.
+//! - **RBAC-based**: the target’s `#[only_role(operator, UPGRADER_ROLE)]` ensures only an
+//!   address with `UPGRADER_ROLE` can upgrade/migrate; that address must be passed as `operator`
+//!   and must have signed the transaction.
 //!
 //! ## Usage
 //!
+//! - For **Auth-based** targets, pass `operator: &None`. The transaction must be authorized
+//!   by the target contract’s authorizer.
+//! - For **RBAC-based** targets, pass `operator: &Some(upgrader_address)`. The transaction
+//!   must be signed by that address, which must hold `UPGRADER_ROLE` on the target.
+//!
 //! ```ignore
 //! let upgrader = UpgraderClient::new(&env, &upgrader_id);
 //! let migration_data = my_data.to_xdr(&env);
-//! upgrader.upgrade_and_migrate(&target_contract, &new_wasm_hash, &migration_data);
+//! // Auth-based target:
+//! upgrader.upgrade_and_migrate(&target_contract, &new_wasm_hash, &migration_data, &None);
+//! // RBAC-based target:
+//! upgrader.upgrade_and_migrate(&target_contract, &new_wasm_hash, &migration_data, &Some(operator));
 //! ```
 
 use soroban_sdk::{contract, contractimpl, xdr::ToXdr, Address, Bytes, BytesN, Env};
-use utils::{auth::AuthClient, errors::AuthError, option_ext::OptionExt, upgradeable::UpgradeableClient};
+use utils::{
+    auth::AuthClient,
+    errors::AuthError,
+    option_ext::OptionExt,
+    upgradeable::{UpgradeableClient, UpgradeableRbacClient},
+};
 
 /// Upgrader contract for managing upgrades of other contracts.
 ///
-/// This is a stateless utility contract that anyone can use.
-/// Security is enforced by the target contract's ownership checks.
+/// Stateless utility: anyone may call it. Authorization is enforced by the target
+/// contract (Auth or RBAC).
 #[contract]
 pub struct Upgrader;
 
@@ -33,39 +50,59 @@ pub struct Upgrader;
 impl Upgrader {
     /// Upgrades a target contract without custom migration data.
     ///
-    /// This is a convenience wrapper that calls `upgrade_and_migrate` with empty migration data.
+    /// Convenience wrapper around [`upgrade_and_migrate`](Self::upgrade_and_migrate) that
+    /// passes empty migration data (XDR encoding of `()`). Use only when the target’s
+    /// `MigrationData` is `()` or it supports empty migration.
     ///
     /// # 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));
+    /// * `contract_address` - Address of the contract to upgrade.
+    /// * `wasm_hash` - Hash of the new WASM bytecode.
+    /// * `operator` - `None` for Auth-based targets; `Some(addr)` for RBAC-based targets
+    pub fn upgrade(env: &Env, contract_address: &Address, wasm_hash: &BytesN<32>, operator: &Option<Address>) {
+        Self::upgrade_and_migrate(env, contract_address, wasm_hash, &().to_xdr(env), operator);
     }
 
     /// 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.
+    /// Chooses Auth-based or RBAC-based flow from `operator`:
+    /// - **`Some(operator)`**: RBAC flow. `operator` must sign the transaction and must have
+    ///   `UPGRADER_ROLE` on the target. The target must implement [`UpgradeableRbac`](utils::upgradeable::UpgradeableRbac).
+    /// - **`None`**: Auth flow. The target’s authorizer must sign the transaction. The target
+    ///   must implement [`Upgradeable`](utils::upgradeable::Upgradeable).
     ///
     /// # Arguments
-    /// * `contract_address` - The address of the contract to upgrade
-    /// * `wasm_hash` - The hash of the new WASM bytecode
-    /// * `migration_data` - XDR-encoded bytes to pass to the migrate function.
-    ///   Use `value.to_xdr(&env)` to encode the target contract's MigrationData type.
+    /// * `contract_address` - Address of the contract to upgrade.
+    /// * `wasm_hash` - Hash of the new WASM bytecode.
+    /// * `migration_data` - XDR-encoded migration payload. Use `value.to_xdr(&env)` for the
+    ///   target contract’s `MigrationData` type; use `().to_xdr(&env)` for no custom data.
+    /// * `operator` - `None` for Auth-based target; `Some(operator)` for RBAC-based target.
     ///
     /// # Example
     /// ```ignore
     /// let migration_data = my_data.to_xdr(&env);
-    /// upgrader.upgrade_and_migrate(&contract_addr, &wasm_hash, &migration_data);
+    /// upgrader.upgrade_and_migrate(&contract_addr, &wasm_hash, &migration_data, &None);
     /// ```
-    pub fn upgrade_and_migrate(env: &Env, contract_address: &Address, wasm_hash: &BytesN<32>, migration_data: &Bytes) {
-        AuthClient::new(env, contract_address)
-            .authorizer()
-            .unwrap_or_panic(env, AuthError::AuthorizerNotFound)
-            .require_auth();
-        let client = UpgradeableClient::new(env, contract_address);
-        client.upgrade(wasm_hash);
-        client.migrate(migration_data);
+    pub fn upgrade_and_migrate(
+        env: &Env,
+        contract_address: &Address,
+        wasm_hash: &BytesN<32>,
+        migration_data: &Bytes,
+        operator: &Option<Address>,
+    ) {
+        if let Some(operator) = operator {
+            operator.require_auth();
+            let client = UpgradeableRbacClient::new(env, contract_address);
+            client.upgrade(wasm_hash, operator);
+            client.migrate(migration_data, operator);
+        } else {
+            AuthClient::new(env, contract_address)
+                .authorizer()
+                .unwrap_or_panic(env, AuthError::AuthorizerNotFound)
+                .require_auth();
+            let client = UpgradeableClient::new(env, contract_address);
+            client.upgrade(wasm_hash);
+            client.migrate(migration_data);
+        }
     }
 }
 

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

@@ -16,6 +16,19 @@ trait TestUpgradeableContract2 {
     fn counter2(env: &Env) -> u32;
 }
 
+#[allow(dead_code)]
+#[contractclient(name = "TestRbacUpgradeableContractClient")]
+trait TestRbacUpgradeableContract {
+    fn counter(env: &Env) -> u32;
+}
+
+#[allow(dead_code)]
+#[contractclient(name = "TestRbacUpgradeableContractClient2")]
+trait TestRbacUpgradeableContract2 {
+    fn counter(env: &Env) -> u32;
+    fn counter2(env: &Env) -> u32;
+}
+
 mod contract_v1 {
     //#![no_std]
 
@@ -100,6 +113,13 @@ mod contract_v2 {
     soroban_sdk::contractimport!(file = "./src/tests/test_data/test_upgradeable_contract2.wasm");
 }
 
+mod contract_v3 {
+    soroban_sdk::contractimport!(file = "./src/tests/test_data/test_upgradeable_contract3.wasm");
+}
+mod contract_v4 {
+    soroban_sdk::contractimport!(file = "./src/tests/test_data/test_upgradeable_contract4.wasm");
+}
+
 fn install_new_wasm(e: &Env) -> BytesN<32> {
     e.deployer().upload_contract_wasm(contract_v2::WASM)
 }
@@ -107,7 +127,7 @@ fn install_new_wasm(e: &Env) -> BytesN<32> {
 #[test]
 fn test_upgrade_with_upgrader() {
     let e = Env::default();
-    e.mock_all_auths_allowing_non_root_auth();
+    e.mock_all_auths();
 
     let owner = Address::generate(&e);
     let contract_id = e.register(contract_v1::WASM, (&owner,));
@@ -121,7 +141,7 @@ fn test_upgrade_with_upgrader() {
     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);
+    upgrader_client.upgrade_and_migrate(&contract_id, &new_wasm_hash, &migration_data, &None);
 
     let client_v2 = TestUpgradeableContractClient2::new(&e, &contract_id);
 
@@ -131,7 +151,7 @@ fn test_upgrade_with_upgrader() {
 #[test]
 fn test_upgrade_without_migration_data_returns_error_for_non_unit_migration() {
     let e = Env::default();
-    e.mock_all_auths_allowing_non_root_auth();
+    e.mock_all_auths();
 
     let owner = Address::generate(&e);
     let contract_id = e.register(contract_v1::WASM, (&owner,));
@@ -142,6 +162,32 @@ fn test_upgrade_without_migration_data_returns_error_for_non_unit_migration() {
     let new_wasm_hash = install_new_wasm(&e);
     // The upgradeable WASM fixture requires non-unit migration data (u32).
     // `Upgrader::upgrade` always passes empty `()` migration bytes, so this must fail.
-    let res = upgrader_client.try_upgrade(&contract_id, &new_wasm_hash);
+    let res = upgrader_client.try_upgrade(&contract_id, &new_wasm_hash, &None);
     assert_eq!(res.err().unwrap().unwrap(), utils::errors::UpgradeableError::InvalidMigrationData.into());
 }
+
+#[test]
+fn test_upgrade_with_upgrader_rbac() {
+    let e = Env::default();
+    e.mock_all_auths();
+
+    let owner = Address::generate(&e);
+    let operator = Address::generate(&e);
+    // RBAC fixture constructor: (owner, upgrader_operator)
+    let contract_id = e.register(contract_v3::WASM, (&owner, &operator));
+    let client_v3 = TestRbacUpgradeableContractClient::new(&e, &contract_id);
+    assert_eq!(client_v3.counter(), 1);
+
+    let upgrader = e.register(Upgrader, ());
+    let upgrader_client = UpgraderClient::new(&e, &upgrader);
+
+    let new_wasm_hash = e.deployer().upload_contract_wasm(contract_v4::WASM);
+    let counter_value = 42_u32;
+    let migration_data = counter_value.to_xdr(&e);
+    // Use RBAC path: pass Some(operator) so the upgrader uses UpgradeableRbac and operator must have signed
+    upgrader_client.upgrade_and_migrate(&contract_id, &new_wasm_hash, &migration_data, &Some(operator));
+
+    let client_v4 = TestRbacUpgradeableContractClient2::new(&e, &contract_id);
+    assert_eq!(client_v4.counter(), 1);
+    assert_eq!(client_v4.counter2(), counter_value);
+}

package/contracts/utils/src/ownable.rs

@@ -64,7 +64,7 @@ pub enum OwnableStorage {
 ///
 /// Supports both single-step and two-step ownership transfer:
 /// - Single-step: `transfer_ownership` - Immediate transfer (use with caution)
-/// - Two-step: `propose_ownership_transfer` + `accept_ownership` - Safer, requires new owner to accept
+/// - Two-step: `begin_ownership_transfer` + `accept_ownership` - Safer, requires new owner to accept
 #[contract_trait]
 pub trait Ownable: Auth {
     // ===========================================================================
@@ -88,7 +88,7 @@ pub trait Ownable: Auth {
     /// Transfers ownership immediately to a new address.
     ///
     /// Use with caution - if you transfer to a wrong address, ownership is lost forever.
-    /// Consider using `propose_ownership_transfer` instead.
+    /// Consider using `begin_ownership_transfer` instead.
     ///
     /// # Panics
     /// - `OwnerNotSet` if no owner is currently set
@@ -105,7 +105,7 @@ pub trait Ownable: Auth {
     // Two-step transfer (safer)
     // ===========================================================================
 
-    /// Proposes an ownership transfer to a new address.
+    /// Begins an ownership transfer to a new address.
     ///
     /// The new owner must call `accept_ownership()` within `ttl` ledgers
     /// to complete the transfer. The pending transfer will automatically expire after.
@@ -120,7 +120,7 @@ pub trait Ownable: 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: &soroban_sdk::Env, new_owner: &soroban_sdk::Address, ttl: u32) {
+    fn begin_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
@@ -158,7 +158,7 @@ pub trait Ownable: Auth {
         new_owner.require_auth();
 
         // Safe to unwrap: owner must exist if pending_owner exists because:
-        // 1. pending_owner can only be set via propose_ownership_transfer, which requires owner auth
+        // 1. pending_owner can only be set via begin_ownership_transfer, which requires owner auth
         // 2. renounce_ownership is blocked while a 2-step transfer is in progress
         let old_owner = OwnableStorage::owner(env).unwrap();
 
@@ -189,6 +189,17 @@ pub trait Ownable: Auth {
 
 /// Trait for initializing the owner of the contract.
 pub trait OwnableInitializer {
+    /// Initializes the owner of the contract.
+    ///
+    /// # Critical: constructor-only, never expose as a public entrypoint
+    ///
+    /// `init_owner` must **ONLY** be called from the contract constructor. Do not expose it
+    /// as a public function under the assumption that it will "simply fail" after initialization.
+    ///
+    /// After `renounce_ownership`, the owner is removed and `has_owner` returns false. If
+    /// `init_owner` were exposed publicly, anyone could call it post-renounce and become the
+    /// new owner, effectively undoing the renunciation. Always keep this logic internal to
+    /// the constructor.
     fn init_owner(env: &Env, owner: &Address) {
         assert_with_error!(env, !OwnableStorage::has_owner(env), OwnableError::OwnerAlreadySet);
         OwnableStorage::set_owner(env, owner);