@layerzerolabs/protocol-stellar-v2 0.2.15 → 0.2.19

package/contracts/utils/src/ownable.rs

@@ -1,13 +1,12 @@
-use crate::errors::OwnableError;
-use crate::option_ext::OptionExt;
-use common_macros::storage;
-use soroban_sdk::{assert_with_error, contractevent, contracttrait, Address, Env};
+use crate::{self as utils, auth::Auth, errors::OwnableError, option_ext::OptionExt};
+use common_macros::{contract_trait, storage};
+use soroban_sdk::{assert_with_error, contractevent, Address, Env};
 
 // ===========================================================================
 // Ownable events
 // ===========================================================================
 
-/// Event emitted when ownership is transferred.
+/// Event emitted when ownership is transferred (both single-step and two-step completion).
 #[contractevent]
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct OwnershipTransferred {
@@ -15,6 +14,15 @@ pub struct OwnershipTransferred {
     pub new_owner: Address,
 }
 
+/// Event emitted when a 2-step ownership transfer is proposed.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct OwnershipTransferring {
+    pub old_owner: Address,
+    pub new_owner: Address,
+    pub ttl: u32,
+}
+
 /// Event emitted when ownership is renounced.
 #[contractevent]
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -31,6 +39,10 @@ pub struct OwnershipRenounced {
 pub enum OwnableStorage {
     #[instance(Address)]
     Owner,
+    /// Pending owner for 2-step transfer. Stored in temporary storage with TTL -
+    /// automatically expires if not accepted in time.
+    #[temporary(Address)]
+    PendingOwner,
 }
 
 // ===========================================================================
@@ -38,23 +50,129 @@ pub enum OwnableStorage {
 // ===========================================================================
 
 /// Trait for contracts with single-owner access control.
-#[contracttrait]
-pub trait Ownable: Sized {
+///
+/// Extends `Auth` to provide owner-based authorization. The `Auth::authorizer()`
+/// implementation should return the owner address for Ownable contracts.
+///
+/// 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
+#[contract_trait]
+pub trait Ownable: Sized + Auth {
+    // ===========================================================================
+    // View functions
+    // ===========================================================================
+
     /// Returns the current owner address, or None if no owner is set.
-    fn owner(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
+    fn owner(env: &Env) -> Option<Address> {
         OwnableStorage::owner(env)
     }
 
-    /// Transfers ownership to a new address. Requires current owner authorization.
-    fn transfer_ownership(env: &soroban_sdk::Env, new_owner: &soroban_sdk::Address) {
+    /// Returns the pending owner address for 2-step transfer, or None if no transfer is pending.
+    fn pending_owner(env: &Env) -> Option<Address> {
+        OwnableStorage::pending_owner(env)
+    }
+
+    // ===========================================================================
+    // Single-step transfer (immediate)
+    // ===========================================================================
+
+    /// 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.
+    ///
+    /// # 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) {
         let old_owner = enforce_owner_auth::<Self>(env);
+        assert_no_pending_transfer::<Self>(env);
+
         OwnableStorage::set_owner(env, new_owner);
         OwnershipTransferred { old_owner, new_owner: new_owner.clone() }.publish(env);
     }
 
-    /// Permanently renounces ownership. Requires current owner authorization.
-    fn renounce_ownership(env: &soroban_sdk::Env) {
+    // ===========================================================================
+    // Two-step transfer (safer)
+    // ===========================================================================
+
+    /// Proposes 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.
+    ///
+    /// # Arguments
+    /// - `new_owner` - The proposed new owner
+    /// - `ttl` - Number of ledgers the new owner has to accept.
+    ///   Use `0` to cancel a pending transfer (new_owner must match pending).
+    ///
+    /// # Panics
+    /// - `OwnerNotSet` if no owner is currently set
+    /// - `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) {
         let old_owner = enforce_owner_auth::<Self>(env);
+
+        // Cancel case: ttl == 0
+        if ttl == 0 {
+            let pending = Self::pending_owner(env).unwrap_or_panic(env, OwnableError::NoPendingTransfer);
+
+            // Verify new_owner matches pending (prevents accidental cancellation)
+            assert_with_error!(env, pending == *new_owner, OwnableError::InvalidPendingOwner);
+
+            OwnableStorage::remove_pending_owner(env);
+            return;
+        }
+
+        // Initiate case: validate ttl
+        assert_with_error!(env, ttl <= env.storage().max_ttl(), OwnableError::InvalidTtl);
+
+        // Store pending owner with TTL
+        OwnableStorage::set_pending_owner(env, new_owner);
+        OwnableStorage::extend_pending_owner_ttl(env, ttl, ttl);
+
+        OwnershipTransferring { old_owner, new_owner: new_owner.clone(), ttl }.publish(env);
+    }
+
+    /// Accepts a pending 2-step ownership transfer.
+    ///
+    /// Must be called by the pending owner before the TTL expires.
+    ///
+    /// # Panics
+    /// - `NoPendingTransfer` if there is no pending transfer (or it expired)
+    fn accept_ownership(env: &Env) {
+        let new_owner = Self::pending_owner(env).unwrap_or_panic(env, OwnableError::NoPendingTransfer);
+
+        // Require authorization from the pending owner
+        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
+        // 2. renounce_ownership is blocked while a 2-step transfer is in progress
+        let old_owner = OwnableStorage::owner(env).unwrap();
+
+        // Transfer ownership
+        OwnableStorage::remove_pending_owner(env);
+        OwnableStorage::set_owner(env, &new_owner);
+
+        OwnershipTransferred { old_owner, new_owner }.publish(env);
+    }
+
+    // ===========================================================================
+    // Renounce
+    // ===========================================================================
+
+    /// Permanently renounces ownership.
+    ///
+    /// # 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) {
+        let old_owner = enforce_owner_auth::<Self>(env);
+        assert_no_pending_transfer::<Self>(env);
+
         OwnableStorage::remove_owner(env);
         OwnershipRenounced { old_owner }.publish(env);
     }
@@ -62,7 +180,7 @@ pub trait Ownable: Sized {
 
 /// Trait for initializing the owner of the contract.
 pub trait OwnableInitializer {
-    fn init_owner(env: &soroban_sdk::Env, owner: &soroban_sdk::Address) {
+    fn init_owner(env: &Env, owner: &Address) {
         assert_with_error!(env, !OwnableStorage::has_owner(env), OwnableError::OwnerAlreadySet);
         OwnableStorage::set_owner(env, owner);
     }
@@ -84,3 +202,9 @@ pub fn enforce_owner_auth<T: Ownable>(env: &Env) -> Address {
 pub fn require_owner_auth<T: Ownable>(env: &Env) {
     let _ = enforce_owner_auth::<T>(env);
 }
+
+/// Asserts that no 2-step ownership transfer is in progress.
+/// Panics with `TransferInProgress` if a pending transfer exists.
+fn assert_no_pending_transfer<T: Ownable>(env: &Env) {
+    assert_with_error!(env, T::pending_owner(env).is_none(), OwnableError::TransferInProgress);
+}

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

@@ -1,11 +1,11 @@
+use crate::{
+    buffer_reader::BufferReader,
+    buffer_writer::BufferWriter,
+    bytes_ext::BytesExt,
+    tests::test_helper::{assert_address_payload_matches, assert_panics_contains},
+};
 use soroban_sdk::{address_payload::AddressPayload, testutils::Address as _, Address, Bytes, BytesN, Env};
 
-use crate::buffer_reader::BufferReader;
-use crate::buffer_writer::BufferWriter;
-use crate::bytes_ext::BytesExt;
-
-use crate::tests::test_helper::{assert_address_payload_matches, assert_panics_contains};
-
 type ReaderStep = fn(&mut BufferReader);
 
 fn assert_reader_panics_contains(case: &str, raw: &[u8], step: ReaderStep, expected_substring: &str) {

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

@@ -1,11 +1,11 @@
+use crate::{
+    buffer_reader::BufferReader,
+    buffer_writer::BufferWriter,
+    bytes_ext::BytesExt,
+    tests::test_helper::assert_address_payload_matches,
+};
 use soroban_sdk::{address_payload::AddressPayload, testutils::Address as _, Address, Bytes, BytesN, Env, U256};
 
-use crate::buffer_reader::BufferReader;
-use crate::buffer_writer::BufferWriter;
-use crate::bytes_ext::BytesExt;
-
-use crate::tests::test_helper::assert_address_payload_matches;
-
 /// Helper to test U256 write/read roundtrip
 fn test_u256_roundtrip(env: &Env, value: &soroban_sdk::U256) {
     let mut writer = BufferWriter::new(env);

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

@@ -1,15 +1,13 @@
+use crate::{bytes_ext::BytesExt, tests::test_helper::assert_panics_contains};
 use soroban_sdk::{Bytes, Env};
 
-use crate::bytes_ext::BytesExt;
-use crate::tests::test_helper::assert_panics_contains;
-
 // ============================================
 // Helper functions
 // ============================================
 
 /// Helper to assert that `to_array::<N>()` panics with BytesExtError::LengthMismatch (1400)
 fn assert_to_array_panics<const N: usize>(case: &str, raw: &[u8]) {
-    const EXPECTED: &str = "Error(Contract, #1400)";
+    const EXPECTED: &str = "Error(Contract, #1040)"; // LengthMismatch
     assert_panics_contains(case, EXPECTED, || {
         let env = Env::default();
         let bytes = Bytes::from_slice(&env, raw);

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

@@ -1,6 +1,7 @@
 mod buffer_reader;
 mod buffer_writer;
 mod bytes_ext;
+mod multisig;
 mod option_ext;
 mod ownable;
 mod test_helper;