@layerzerolabs/protocol-stellar-v2 0.2.35 → 0.2.37

package/contracts/oapps/sac-manager/src/interfaces/sac_admin_wrapper.rs

@@ -0,0 +1,49 @@
+//! SAC Admin Wrapper trait definition.
+//!
+//! Defines the admin operations that can be performed on a Stellar Asset Contract (SAC).
+
+use common_macros::contract_trait;
+use soroban_sdk::{Address, Env};
+
+#[contract_trait]
+pub trait SACAdminWrapper {
+    /// Sets the administrator to the specified address `new_admin`.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The Soroban environment.
+    /// * `new_admin` - The address which will be the administrator of the token contract.
+    /// * `operator` - The address authorizing the invocation.
+    fn set_admin(env: &Env, new_admin: &Address, operator: &Address);
+
+    /// Sets whether the account is authorized to use its balance.
+    /// If `authorize` is true, `id` can use its balance; otherwise it is blacklisted.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The Soroban environment.
+    /// * `id` - The address being (de-)authorized.
+    /// * `authorize` - Whether `id` can use its balance.
+    /// * `operator` - The address authorizing the invocation.
+    fn set_authorized(env: &Env, id: &Address, authorize: bool, operator: &Address);
+
+    /// Clawback `amount` from `from` account. The amount is burned in the clawback process.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The Soroban environment.
+    /// * `from` - The address holding the balance to claw back from.
+    /// * `amount` - The amount of tokens to claw back.
+    /// * `operator` - The address authorizing the invocation.
+    fn clawback(env: &Env, from: &Address, amount: i128, operator: &Address);
+
+    /// Mints `amount` to `to`.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The Soroban environment.
+    /// * `to` - The address which will receive the minted tokens.
+    /// * `amount` - The amount of tokens to be minted.
+    /// * `operator` - The address authorizing the invocation.
+    fn mint(env: &Env, to: &Address, amount: i128, operator: &Address);
+}

package/contracts/oapps/sac-manager/src/lib.rs

@@ -1,8 +1,8 @@
 #![no_std]
 
-mod errors;
+mod interfaces;
 
-pub use errors::*;
+pub use interfaces::{SACAdminWrapper, SACAdminWrapperClient};
 
 cfg_if::cfg_if! {
     // Include implementation when NOT in library mode, OR when testutils is enabled (for tests)
@@ -11,7 +11,7 @@ cfg_if::cfg_if! {
         mod sac_manager;
 
         // Export the contract and client for testing purposes
-        pub use sac_manager::{SacManager, SacManagerClient};
+        pub use sac_manager::{SACManager, SACManagerClient};
     }
 }
 

package/contracts/oapps/sac-manager/src/sac_manager.rs

@@ -2,19 +2,30 @@
 //!
 //! This contract becomes the admin of a SAC and provides:
 //! - Mintable interface for OFT (mint on credit only; OFT burns on the token directly)
-//! - Admin operations (clawback, set_admin, set_authorized)
-//! - Upgradeable (owner-authorized)
+//! - Role-based access control operations (clawback, set_admin, set_authorized)
 //!
 //! ## Authorization Model
 //!
-//! - **Owner** (via Ownable): The admin address. Can do everything (upgrades, TTL, admin ops, set_minter).
-//! - **Minters**: Stored list of addresses. Only an address in Minters can call mint via Mintable with `operation: minter_address`.
-
-use crate::{errors::SacManagerError, storage::SacManagerStorage};
-use common_macros::{contract_impl, lz_contract, only_auth};
-use oft::Mintable;
-use soroban_sdk::{assert_with_error, token::StellarAssetClient, Address, Env, Vec};
-use utils::ownable::OwnableInitializer;
+//! - **Owner** (via Ownable): The deployer/admin address. Can manage TTL and grant/revoke roles.
+//! - **RBAC roles**: Access is enforced by role.
+//!   - `ADMIN_MANAGER_ROLE`: set_admin
+//!   - `MINTER_ROLE`: mint (e.g. for OFT credit)
+//!   - `BLACKLISTER_ROLE`: set_authorized
+//!   - `CLAWBACK_ROLE`: clawback
+
+use crate::{interfaces::SACAdminWrapper, storage::SACManagerStorage};
+use common_macros::{contract_impl, lz_contract, only_role};
+use soroban_sdk::{token::StellarAssetClient, Address, Env};
+use utils::rbac::RoleBasedAccessControl;
+
+/// Role that can set the admin
+const ADMIN_MANAGER_ROLE: &str = "ADMIN_MGR";
+/// Role that can mint tokens
+const MINTER_ROLE: &str = "MINTER";
+/// Role that can blacklist users
+const BLACKLISTER_ROLE: &str = "BLKLISTR";
+/// Role that can clawback tokens from users
+const CLAWBACK_ROLE: &str = "CLAWBACK";
 
 // =========================================================================
 // SAC Manager Contract
@@ -24,92 +35,53 @@ use utils::ownable::OwnableInitializer;
 ///
 /// Manages a SAC as its admin, forwarding token actions to
 /// the underlying SAC while enforcing access control.
-#[lz_contract(upgradeable(no_migration))]
-pub struct SacManager;
+#[lz_contract]
+pub struct SACManager;
 
 #[contract_impl]
-impl SacManager {
+impl SACManager {
     /// Constructs the SAC manager contract.
     ///
     /// # Arguments
     /// * `sac_token` - The underlying Stellar Asset Contract address
-    /// * `owner` - The initial owner address (for upgrades, owner ops)
-    ///
-    /// Minters can be set separately via `set_minter` after construction.
+    /// * `owner` - The initial owner address (for TTL management, role grants)
     pub fn __constructor(env: &Env, sac_token: &Address, owner: &Address) {
         Self::init_owner(env, owner);
-        SacManagerStorage::set_sac_token(env, sac_token);
+        SACManagerStorage::set_sac_token(env, sac_token);
     }
 
-    // =========================================================================
-    // SAC Admin Operations
-    // =========================================================================
-
-    /// Delegates to the underlying SAC to clawback `amount` from `from` account.
-    #[only_auth]
-    pub fn clawback(env: &Env, from: &Address, amount: i128) {
-        sac_client(env).clawback(from, &amount);
+    /// Returns the underlying SAC (Stellar Asset Contract) address.
+    pub fn underlying_sac(env: &Env) -> Address {
+        SACManagerStorage::sac_token(env).unwrap()
     }
+}
 
-    /// Delegates to the underlying SAC `set_admin` to release the admin role from the current contract to `to`.
-    #[only_auth]
-    pub fn release_sac_admin(env: &Env, to: &Address) {
-        sac_client(env).set_admin(to);
+#[contract_impl(contracttrait)]
+impl SACAdminWrapper for SACManager {
+    #[only_role(operator, ADMIN_MANAGER_ROLE)]
+    fn set_admin(env: &Env, new_admin: &Address, operator: &Address) {
+        sac_client(env).set_admin(new_admin);
     }
 
-    /// Delegates to the underlying SAC `set_authorized` to set whether `id` is authorized to use its balance.
-    #[only_auth]
-    pub fn set_authorized(env: &Env, id: &Address, authorize: bool) {
+    #[only_role(operator, BLACKLISTER_ROLE)]
+    fn set_authorized(env: &Env, id: &Address, authorize: bool, operator: &Address) {
         sac_client(env).set_authorized(id, &authorize);
     }
 
-    /// Adds (`active = true`) or removes (`active = false`) a minter.
-    #[only_auth]
-    pub fn set_minter(env: &Env, minter: &Address, active: bool) {
-        let mut minters = SacManagerStorage::minters(env);
-        let minter_index = minters.first_index_of(minter);
-        if active {
-            assert_with_error!(env, minter_index.is_none(), SacManagerError::AlreadyMinter);
-            minters.push_back(minter.clone());
-        } else {
-            minters.remove(minter_index.unwrap_or_panic(env, SacManagerError::MinterNotFound));
-        }
-        SacManagerStorage::set_minters(env, &minters);
-    }
-
-    // =========================================================================
-    // View Functions
-    // =========================================================================
-
-    /// Returns the underlying SAC (Stellar Asset Contract) address.
-    pub fn underlying_sac(env: &Env) -> Address {
-        SacManagerStorage::sac_token(env).unwrap()
-    }
-
-    /// Returns the list of addresses authorized to call mint.
-    pub fn minters(env: &Env) -> Vec<Address> {
-        SacManagerStorage::minters(env)
+    #[only_role(operator, CLAWBACK_ROLE)]
+    fn clawback(env: &Env, from: &Address, amount: i128, operator: &Address) {
+        sac_client(env).clawback(from, &amount);
     }
-}
-
-// =========================================================================
-// Mintable Implementation (OFT mint on credit)
-// =========================================================================
-
-#[contract_impl]
-impl Mintable for SacManager {
-    fn mint(env: &Env, to: &Address, amount: i128, operation: &Address) {
-        assert_with_error!(env, Self::minters(env).contains(operation), SacManagerError::Unauthorized);
-        operation.require_auth();
 
+    #[only_role(operator, MINTER_ROLE)]
+    fn mint(env: &Env, to: &Address, amount: i128, operator: &Address) {
         sac_client(env).mint(to, &amount);
     }
 }
 
-// =========================================================================
-// Helper Functions
-// =========================================================================
+#[contract_impl(contracttrait)]
+impl RoleBasedAccessControl for SACManager {}
 
 fn sac_client(env: &Env) -> StellarAssetClient<'_> {
-    StellarAssetClient::new(env, &SacManager::underlying_sac(env))
+    StellarAssetClient::new(env, &SACManager::underlying_sac(env))
 }

package/contracts/oapps/sac-manager/src/storage.rs

@@ -3,18 +3,11 @@
 //! This file contains the core storage.
 
 use common_macros::storage;
-use soroban_sdk::{Address, Vec};
+use soroban_sdk::Address;
 
-/// Core storage for the SacManager contract.
-/// Contains essential state.
 #[storage]
-pub enum SacManagerStorage {
+pub enum SACManagerStorage {
     /// The underlying SAC (Stellar Asset Contract) address
     #[instance(Address)]
     SacToken,
-
-    /// Addresses authorized to call mint (e.g. OFT or other minters).
-    #[persistent(Vec<Address>)]
-    #[default(Vec::new(env))]
-    Minters,
 }

package/contracts/oapps/sac-manager/src/tests/sac_manager/clawback.rs

@@ -1,15 +1,13 @@
 //! Clawback Integration Tests
 //!
-//! Tests for admin-initiated clawback functionality via `clawback`.
-//! The clawback operation uses SAC clawback, which requires AUTH_CLAWBACK_ENABLED
-//! flag on the SAC issuer.
+//! Operator must hold CLAWBACK_ROLE. SAC must have AUTH_CLAWBACK_ENABLED.
 
 use super::test_helper::mock_clawback_auth;
 use crate::tests::test_helper::{mock_oft_mint_auth, TestSetup};
 use soroban_sdk::testutils::IssuerFlags;
 
 // =========================================================================
-// clawback Tests (owner only)
+// clawback Tests
 // =========================================================================
 
 #[test]
@@ -25,7 +23,7 @@ fn test_clawback_by_owner() {
     assert_eq!(setup.sac_client.balance(&user), 1000);
 
     mock_clawback_auth(&setup, &setup.owner, &user, 500_i128);
-    setup.sac_manager_client.clawback(&user, &500);
+    setup.sac_manager_client.clawback(&user, &500, &setup.owner);
     assert_eq!(setup.sac_client.balance(&user), 500);
 }
 
@@ -41,7 +39,7 @@ fn test_clawback_full_balance() {
     setup.sac_manager_client.mint(&user, &1000, &setup.minter);
 
     mock_clawback_auth(&setup, &setup.owner, &user, 1000_i128);
-    setup.sac_manager_client.clawback(&user, &1000);
+    setup.sac_manager_client.clawback(&user, &1000, &setup.owner);
     assert_eq!(setup.sac_client.balance(&user), 0);
 }
 
@@ -57,18 +55,18 @@ fn test_clawback_fails_when_amount_exceeds_balance() {
     setup.sac_manager_client.mint(&user, &100, &setup.minter);
 
     mock_clawback_auth(&setup, &setup.owner, &user, 200_i128);
-    let result = setup.sac_manager_client.try_clawback(&user, &200);
+    let result = setup.sac_manager_client.try_clawback(&user, &200, &setup.owner);
     assert!(result.is_err());
 }
 
 #[test]
-fn test_clawback_by_non_owner_fails() {
+fn test_clawback_operator_without_role_fails() {
     let setup = TestSetup::new().with_manager_as_sac_admin().build();
     let user = setup.generate_address();
     let random = setup.generate_address();
 
     mock_clawback_auth(&setup, &random, &user, 500_i128);
-    let result = setup.sac_manager_client.try_clawback(&user, &500);
+    let result = setup.sac_manager_client.try_clawback(&user, &500, &random);
     assert!(result.is_err());
 }
 
@@ -82,5 +80,5 @@ fn test_clawback_fails_without_auth() {
     let setup = TestSetup::new().build();
     let user = setup.generate_address();
 
-    setup.sac_manager_client.clawback(&user, &300);
+    setup.sac_manager_client.clawback(&user, &300, &setup.owner);
 }

package/contracts/oapps/sac-manager/src/tests/sac_manager/mint.rs

@@ -1,13 +1,11 @@
 //! Mint (Mintable) Integration Tests
 //!
-//! Tests minter-originated mint via Mintable::mint(..., operation: minter),
-//! authorization (operation must be in minters, operation must auth), and error cases.
+//! Operator must hold MINTER_ROLE and authorize the call.
 
-use crate::errors::SacManagerError;
 use crate::tests::test_helper::{mock_auth, mock_oft_mint_auth, TestSetup};
 
 // =========================================================================
-// Mint success — minter calls mint
+// Mint success — operator with MINTER_ROLE calls mint
 // =========================================================================
 
 #[test]
@@ -21,31 +19,28 @@ fn test_mint_by_minter() {
 }
 
 // =========================================================================
-// Mint error cases — operation not in minters / non-minter
+// Mint role auth — operator without MINTER_ROLE fails
 // =========================================================================
 
 #[test]
-fn test_mint_fails_when_operation_not_in_minters() {
-    let setup = TestSetup::new().with_empty_minters().build();
-    let recipient = setup.generate_address();
-
-    let result = setup.sac_manager_client.try_mint(&recipient, &1000, &setup.minter);
-    assert_eq!(result.err().unwrap().unwrap(), SacManagerError::Unauthorized.into());
-}
-
-#[test]
-fn test_mint_by_non_minter_fails() {
+fn test_mint_operator_without_role_fails() {
     let setup = TestSetup::new().with_manager_as_sac_admin().build();
     let recipient = setup.generate_address();
     let random = setup.generate_address();
 
-    mock_auth(&setup.env, &setup.sac_manager, &random, "mint", (&recipient, 1000_i128, &random));
+    mock_auth(
+        &setup.env,
+        &setup.sac_manager,
+        &random,
+        "mint",
+        (&recipient, 1000_i128, &random),
+    );
     let result = setup.sac_manager_client.try_mint(&recipient, &1000, &random);
-    assert_eq!(result.err().unwrap().unwrap(), SacManagerError::Unauthorized.into());
+    assert!(result.is_err());
 }
 
 // =========================================================================
-// Mint auth tests — operation must authorize
+// Mint auth — operator must authorize
 // =========================================================================
 
 #[test]

package/contracts/oapps/sac-manager/src/tests/sac_manager/mod.rs

@@ -2,6 +2,5 @@ mod clawback;
 mod mint;
 mod set_admin;
 mod set_authorized;
-mod set_minter;
 mod test_helper;
 mod view_functions;

package/contracts/oapps/sac-manager/src/tests/sac_manager/set_admin.rs

@@ -1,36 +1,46 @@
-//! release_sac_admin Integration Tests
+//! set_admin Integration Tests
+//!
+//! Tests that set_admin requires ADMIN_MANAGER_ROLE on the operator.
 
-use super::test_helper::mock_release_sac_admin_auth;
+use super::test_helper::mock_set_admin_auth;
 use crate::tests::test_helper::TestSetup;
 
 // =========================================================================
-// release_sac_admin Tests
+// set_admin Tests
 // =========================================================================
 
 #[test]
-fn test_release_sac_admin() {
+fn test_set_admin_by_owner() {
     let setup = TestSetup::new().with_manager_as_sac_admin().build();
     let new_admin = setup.generate_address();
 
-    // Current SAC admin is the manager (configured by test setup).
     assert_eq!(setup.sac_client.admin(), setup.sac_manager);
 
-    // Owner can change SAC admin
-    mock_release_sac_admin_auth(&setup, &new_admin);
-    setup.sac_manager_client.release_sac_admin(&new_admin);
+    mock_set_admin_auth(&setup, &setup.owner, &new_admin);
+    setup.sac_manager_client.set_admin(&new_admin, &setup.owner);
     assert_eq!(setup.sac_client.admin(), new_admin);
 }
 
 // =========================================================================
-// release_sac_admin Auth Tests
+// set_admin Role Auth Tests
 // =========================================================================
 
+#[test]
+fn test_set_admin_operator_without_role_fails() {
+    let setup = TestSetup::new().with_manager_as_sac_admin().build();
+    let new_admin = setup.generate_address();
+    let random = setup.generate_address();
+
+    mock_set_admin_auth(&setup, &random, &new_admin);
+    let result = setup.sac_manager_client.try_set_admin(&new_admin, &random);
+    assert!(result.is_err());
+}
+
 #[test]
 #[should_panic(expected = "Error(Auth, InvalidAction)")]
-fn test_release_sac_admin_without_auth() {
+fn test_set_admin_without_auth() {
     let setup = TestSetup::new().build();
     let new_admin = setup.generate_address();
 
-    // Should panic because owner doesn't authorize the call
-    setup.sac_manager_client.release_sac_admin(&new_admin);
+    setup.sac_manager_client.set_admin(&new_admin, &setup.owner);
 }

package/contracts/oapps/sac-manager/src/tests/sac_manager/set_authorized.rs

@@ -1,6 +1,6 @@
 //! set_authorized Integration Tests
 //!
-//! Requires revocable issuer flag on the SAC before authorization can be changed.
+//! Requires revocable issuer flag on the SAC. Operator must hold BLACKLISTER_ROLE.
 
 use super::test_helper::mock_set_authorized_auth;
 use crate::tests::test_helper::TestSetup;
@@ -15,29 +15,39 @@ fn test_set_authorized_by_owner() {
     let setup = TestSetup::new().with_manager_as_sac_admin().build();
     let user = setup.generate_address();
 
-    // Enable issuer flag required by SAC for set_authorized.
     setup.sac_contract.issuer().set_flag(IssuerFlags::RevocableFlag);
     assert!(setup.sac_client.authorized(&user));
 
-    mock_set_authorized_auth(&setup, &user, false);
-    setup.sac_manager_client.set_authorized(&user, &false);
+    mock_set_authorized_auth(&setup, &setup.owner, &user, false);
+    setup.sac_manager_client.set_authorized(&user, &false, &setup.owner);
     assert!(!setup.sac_client.authorized(&user));
 
-    mock_set_authorized_auth(&setup, &user, true);
-    setup.sac_manager_client.set_authorized(&user, &true);
+    mock_set_authorized_auth(&setup, &setup.owner, &user, true);
+    setup.sac_manager_client.set_authorized(&user, &true, &setup.owner);
     assert!(setup.sac_client.authorized(&user));
 }
 
 // =========================================================================
-// set_authorized Auth Tests
+// set_authorized Role Auth Tests
 // =========================================================================
 
+#[test]
+fn test_set_authorized_operator_without_role_fails() {
+    let setup = TestSetup::new().with_manager_as_sac_admin().build();
+    let user = setup.generate_address();
+    let random = setup.generate_address();
+
+    setup.sac_contract.issuer().set_flag(IssuerFlags::RevocableFlag);
+    mock_set_authorized_auth(&setup, &random, &user, false);
+    let result = setup.sac_manager_client.try_set_authorized(&user, &false, &random);
+    assert!(result.is_err());
+}
+
 #[test]
 #[should_panic(expected = "Error(Auth, InvalidAction)")]
 fn test_set_authorized_without_auth() {
     let setup = TestSetup::new().build();
     let user = setup.generate_address();
 
-    // Should panic because owner doesn't authorize the call
-    setup.sac_manager_client.set_authorized(&user, &false);
+    setup.sac_manager_client.set_authorized(&user, &false, &setup.owner);
 }

package/contracts/oapps/sac-manager/src/tests/sac_manager/test_helper.rs

@@ -1,18 +1,35 @@
 use crate::tests::test_helper::{mock_auth, TestSetup};
 use soroban_sdk::Address;
 
-pub fn mock_clawback_auth(setup: &TestSetup, sender: &Address, from: &Address, amount: i128) {
-    mock_auth(&setup.env, &setup.sac_manager, sender, "clawback", (from, amount));
+/// Mock auth for `clawback(from, amount, operator)` — operator must hold CLAWBACK_ROLE.
+pub fn mock_clawback_auth(setup: &TestSetup, operator: &Address, from: &Address, amount: i128) {
+    mock_auth(
+        &setup.env,
+        &setup.sac_manager,
+        operator,
+        "clawback",
+        (from, amount, operator),
+    );
 }
 
-pub fn mock_set_authorized_auth(setup: &TestSetup, user: &Address, authorize: bool) {
-    mock_auth(&setup.env, &setup.sac_manager, &setup.owner, "set_authorized", (user, authorize));
+/// Mock auth for `set_authorized(id, authorize, operator)` — operator must hold BLACKLISTER_ROLE.
+pub fn mock_set_authorized_auth(setup: &TestSetup, operator: &Address, user: &Address, authorize: bool) {
+    mock_auth(
+        &setup.env,
+        &setup.sac_manager,
+        operator,
+        "set_authorized",
+        (user, authorize, operator),
+    );
 }
 
-pub fn mock_release_sac_admin_auth(setup: &TestSetup, new_admin: &Address) {
-    mock_auth(&setup.env, &setup.sac_manager, &setup.owner, "release_sac_admin", (new_admin,));
-}
-
-pub fn mock_set_minter_auth(setup: &TestSetup, minter: &Address, active: bool) {
-    mock_auth(&setup.env, &setup.sac_manager, &setup.owner, "set_minter", (minter, active));
+/// Mock auth for `set_admin(new_admin, operator)` — operator must hold ADMIN_MANAGER_ROLE.
+pub fn mock_set_admin_auth(setup: &TestSetup, operator: &Address, new_admin: &Address) {
+    mock_auth(
+        &setup.env,
+        &setup.sac_manager,
+        operator,
+        "set_admin",
+        (new_admin, operator),
+    );
 }

package/contracts/oapps/sac-manager/src/tests/sac_manager/view_functions.rs

@@ -11,18 +11,3 @@ fn test_underlying_sac() {
     let setup = TestSetup::new().build();
     assert_eq!(setup.sac_manager_client.underlying_sac(), setup.sac);
 }
-
-#[test]
-fn test_minters() {
-    let setup = TestSetup::new().build();
-    let minters = setup.sac_manager_client.minters();
-    assert_eq!(minters.len(), 1);
-    assert_eq!(minters.get(0), Some(setup.minter.clone()));
-}
-
-#[test]
-fn test_minters_empty_when_not_set() {
-    let setup = TestSetup::new().with_empty_minters().build();
-    let minters = setup.sac_manager_client.minters();
-    assert_eq!(minters.len(), 0);
-}