@layerzerolabs/protocol-stellar-v2 0.2.32 → 0.2.34

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

@@ -0,0 +1,115 @@
+//! SAC Manager Contract - Manages a Stellar Asset Contract (SAC) as its admin.
+//!
+//! 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)
+//!
+//! ## 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;
+
+// =========================================================================
+// SAC Manager Contract
+// =========================================================================
+
+/// SAC Manager Contract
+///
+/// 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;
+
+#[contract_impl]
+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.
+    pub fn __constructor(env: &Env, sac_token: &Address, owner: &Address) {
+        Self::init_owner(env, owner);
+        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);
+    }
+
+    /// 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);
+    }
+
+    /// 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) {
+        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)
+    }
+}
+
+// =========================================================================
+// 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();
+
+        sac_client(env).mint(to, &amount);
+    }
+}
+
+// =========================================================================
+// Helper Functions
+// =========================================================================
+
+fn sac_client(env: &Env) -> StellarAssetClient<'_> {
+    StellarAssetClient::new(env, &SacManager::underlying_sac(env))
+}

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

@@ -0,0 +1,20 @@
+//! Storage definitions for the SAC manager contract.
+//!
+//! This file contains the core storage.
+
+use common_macros::storage;
+use soroban_sdk::{Address, Vec};
+
+/// Core storage for the SacManager contract.
+/// Contains essential state.
+#[storage]
+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/{sac-manager → oapps/sac-manager}/src/tests/mod.rs

@@ -1,14 +1,10 @@
 //! Token Wrapper Tests
 //!
 //! Test modules organized by source module:
-//! - `supply_control`: Tests for supply control extension (controllers, mint, burn, rate limits)
-//! - `redistribution`: Tests for redistribution extension (feature flag settings)
 //! - `sac_manager`: Tests for the main SAC manager contract (admin, authorized, clawback, mint/burn, views)
 
 #![cfg(test)]
 
 mod test_helper;
 
-mod redistribution;
 mod sac_manager;
-mod supply_control;

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

@@ -0,0 +1,86 @@
+//! 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.
+
+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)
+// =========================================================================
+
+#[test]
+fn test_clawback_by_owner() {
+    let setup = TestSetup::new().with_manager_as_sac_admin().build();
+    let user = setup.generate_address();
+
+    setup.sac_contract.issuer().set_flag(IssuerFlags::RevocableFlag);
+    setup.sac_contract.issuer().set_flag(IssuerFlags::ClawbackEnabledFlag);
+
+    mock_oft_mint_auth(&setup, &user, 1000_i128);
+    setup.sac_manager_client.mint(&user, &1000, &setup.minter);
+    assert_eq!(setup.sac_client.balance(&user), 1000);
+
+    mock_clawback_auth(&setup, &setup.owner, &user, 500_i128);
+    setup.sac_manager_client.clawback(&user, &500);
+    assert_eq!(setup.sac_client.balance(&user), 500);
+}
+
+#[test]
+fn test_clawback_full_balance() {
+    let setup = TestSetup::new().with_manager_as_sac_admin().build();
+    let user = setup.generate_address();
+
+    setup.sac_contract.issuer().set_flag(IssuerFlags::RevocableFlag);
+    setup.sac_contract.issuer().set_flag(IssuerFlags::ClawbackEnabledFlag);
+
+    mock_oft_mint_auth(&setup, &user, 1000_i128);
+    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);
+    assert_eq!(setup.sac_client.balance(&user), 0);
+}
+
+#[test]
+fn test_clawback_fails_when_amount_exceeds_balance() {
+    let setup = TestSetup::new().with_manager_as_sac_admin().build();
+    let user = setup.generate_address();
+
+    setup.sac_contract.issuer().set_flag(IssuerFlags::RevocableFlag);
+    setup.sac_contract.issuer().set_flag(IssuerFlags::ClawbackEnabledFlag);
+
+    mock_oft_mint_auth(&setup, &user, 100_i128);
+    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);
+    assert!(result.is_err());
+}
+
+#[test]
+fn test_clawback_by_non_owner_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);
+    assert!(result.is_err());
+}
+
+// =========================================================================
+// clawback Auth Tests
+// =========================================================================
+
+#[test]
+#[should_panic(expected = "Error(Auth, InvalidAction)")]
+fn test_clawback_fails_without_auth() {
+    let setup = TestSetup::new().build();
+    let user = setup.generate_address();
+
+    setup.sac_manager_client.clawback(&user, &300);
+}

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

@@ -0,0 +1,58 @@
+//! 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.
+
+use crate::errors::SacManagerError;
+use crate::tests::test_helper::{mock_auth, mock_oft_mint_auth, TestSetup};
+
+// =========================================================================
+// Mint success — minter calls mint
+// =========================================================================
+
+#[test]
+fn test_mint_by_minter() {
+    let setup = TestSetup::new().with_manager_as_sac_admin().build();
+    let recipient = setup.generate_address();
+
+    mock_oft_mint_auth(&setup, &recipient, 1000_i128);
+    setup.sac_manager_client.mint(&recipient, &1000, &setup.minter);
+    assert_eq!(setup.sac_client.balance(&recipient), 1000);
+}
+
+// =========================================================================
+// Mint error cases — operation not in minters / non-minter
+// =========================================================================
+
+#[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() {
+    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));
+    let result = setup.sac_manager_client.try_mint(&recipient, &1000, &random);
+    assert_eq!(result.err().unwrap().unwrap(), SacManagerError::Unauthorized.into());
+}
+
+// =========================================================================
+// Mint auth tests — operation must authorize
+// =========================================================================
+
+#[test]
+#[should_panic(expected = "Error(Auth, InvalidAction)")]
+fn test_mint_fails_without_minter_auth() {
+    let setup = TestSetup::new().with_manager_as_sac_admin().build();
+    let recipient = setup.generate_address();
+
+    setup.sac_manager_client.mint(&recipient, &1000, &setup.minter);
+}

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

@@ -1,9 +1,7 @@
 mod clawback;
-mod admin_mint;
-mod burn;
 mod mint;
 mod set_admin;
 mod set_authorized;
-mod set_oft_address;
+mod set_minter;
 mod test_helper;
 mod view_functions;

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

@@ -0,0 +1,69 @@
+//! set_minter Integration Tests
+
+use super::test_helper::mock_set_minter_auth;
+use crate::errors::SacManagerError;
+use crate::tests::test_helper::TestSetup;
+
+// =========================================================================
+// set_minter Tests
+// =========================================================================
+
+#[test]
+fn test_set_minter_add_when_empty() {
+    let setup = TestSetup::new().with_empty_minters().build();
+    let new_minter = setup.generate_address();
+
+    mock_set_minter_auth(&setup, &new_minter, true);
+    setup.sac_manager_client.set_minter(&new_minter, &true);
+    let stored = setup.sac_manager_client.minters();
+    assert_eq!(stored.len(), 1);
+    assert_eq!(stored.get(0), Some(new_minter));
+}
+
+#[test]
+fn test_set_minter_add_then_remove() {
+    let setup = TestSetup::new().build();
+    let new_minter = setup.generate_address();
+
+    mock_set_minter_auth(&setup, &new_minter, true);
+    setup.sac_manager_client.set_minter(&new_minter, &true);
+    assert_eq!(setup.sac_manager_client.minters().len(), 2);
+
+    mock_set_minter_auth(&setup, &new_minter, false);
+    setup.sac_manager_client.set_minter(&new_minter, &false);
+    let stored = setup.sac_manager_client.minters();
+    assert_eq!(stored.len(), 1);
+    assert_eq!(stored.get(0), Some(setup.minter.clone()));
+}
+
+#[test]
+fn test_set_minter_add_fails_if_already_active() {
+    let setup = TestSetup::new().build();
+
+    mock_set_minter_auth(&setup, &setup.minter, true);
+    let result = setup.sac_manager_client.try_set_minter(&setup.minter, &true);
+    assert_eq!(result.err().unwrap().unwrap(), SacManagerError::AlreadyMinter.into());
+}
+
+#[test]
+fn test_set_minter_remove_fails_if_not_minter() {
+    let setup = TestSetup::new().build();
+    let random = setup.generate_address();
+
+    mock_set_minter_auth(&setup, &random, false);
+    let result = setup.sac_manager_client.try_set_minter(&random, &false);
+    assert_eq!(result.err().unwrap().unwrap(), SacManagerError::MinterNotFound.into());
+}
+
+// =========================================================================
+// set_minter Auth Tests
+// =========================================================================
+
+#[test]
+#[should_panic(expected = "Error(Auth, InvalidAction)")]
+fn test_set_minter_without_auth() {
+    let setup = TestSetup::new().with_empty_minters().build();
+    let new_minter = setup.generate_address();
+
+    setup.sac_manager_client.set_minter(&new_minter, &true);
+}

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

@@ -0,0 +1,18 @@
+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));
+}
+
+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));
+}
+
+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));
+}

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

@@ -0,0 +1,28 @@
+//! View Functions Integration Tests
+
+use crate::tests::test_helper::TestSetup;
+
+// =========================================================================
+// Core View Functions
+// =========================================================================
+
+#[test]
+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);
+}

package/contracts/{sac-manager → oapps/sac-manager}/src/tests/test_helper.rs

@@ -25,19 +25,12 @@ use soroban_sdk::{
 /// ```
 pub struct TestSetupBuilder {
     manager_as_sac_admin: bool,
-    redistribution_enabled: bool,
-    supply_control_enabled: bool,
-    skip_oft_setup: bool,
+    skip_minters_setup: bool,
 }
 
 impl TestSetupBuilder {
     fn new() -> Self {
-        Self {
-            manager_as_sac_admin: false,
-            redistribution_enabled: false,
-            supply_control_enabled: false,
-            skip_oft_setup: false,
-        }
+        Self { manager_as_sac_admin: false, skip_minters_setup: false }
     }
 
     /// Set the SacManager as SAC admin during setup.
@@ -46,22 +39,10 @@ impl TestSetupBuilder {
         self
     }
 
-    /// Enable redistribution at construction time.
-    pub fn with_redistribution_enabled(mut self) -> Self {
-        self.redistribution_enabled = true;
-        self
-    }
-
-    /// Enable supply control at construction time.
-    pub fn with_supply_control_enabled(mut self) -> Self {
-        self.supply_control_enabled = true;
-        self
-    }
-
-    /// Skip setting the OFT address during setup.
-    /// Use this to test `set_oft_address` auth or the once-only guard.
-    pub fn without_oft(mut self) -> Self {
-        self.skip_oft_setup = true;
+    /// Skip setting minters during setup.
+    /// Use this to test `set_minter` auth or mint when no minter is set.
+    pub fn with_empty_minters(mut self) -> Self {
+        self.skip_minters_setup = true;
         self
     }
 
@@ -71,26 +52,24 @@ impl TestSetupBuilder {
 
         let owner = Address::generate(&env);
         let oft = Address::generate(&env);
-        let sc_manager = Address::generate(&env);
         let sac_contract = env.register_stellar_asset_contract_v2(owner.clone());
         let sac = sac_contract.address();
 
-        let sac_manager =
-            env.register(SacManager, (&sac, &owner, self.redistribution_enabled, self.supply_control_enabled));
+        let sac_manager = env.register(SacManager, (&sac, &owner));
         let sac_manager_client = SacManagerClient::new(&env, &sac_manager);
         let sac_client = StellarAssetClient::new(&env, &sac);
 
-        if !self.skip_oft_setup {
+        if !self.skip_minters_setup {
             env.mock_auths(&[MockAuth {
                 address: &owner,
                 invoke: &MockAuthInvoke {
                     contract: &sac_manager,
-                    fn_name: "set_oft_address",
-                    args: (&oft,).into_val(&env),
+                    fn_name: "set_minter",
+                    args: (oft.clone(), true).into_val(&env),
                     sub_invokes: &[],
                 },
             }]);
-            sac_manager_client.set_oft_address(&oft);
+            sac_manager_client.set_minter(&oft, &true);
         }
 
         if self.manager_as_sac_admin {
@@ -106,22 +85,10 @@ impl TestSetupBuilder {
             sac_client.set_admin(&sac_manager);
         }
 
-        // Set up supply controller manager (owner grants the role)
-        env.mock_auths(&[MockAuth {
-            address: &owner,
-            invoke: &MockAuthInvoke {
-                contract: &sac_manager,
-                fn_name: "set_supply_controller_manager",
-                args: (&sc_manager, true).into_val(&env),
-                sub_invokes: &[],
-            },
-        }]);
-        sac_manager_client.set_supply_controller_manager(&sc_manager, &true);
-
         // Clear mock auths so test starts with clean auth state
         env.mock_auths(&[]);
 
-        TestSetup { env, owner, oft, sc_manager, sac, sac_contract, sac_manager, sac_manager_client, sac_client }
+        TestSetup { env, owner, minter: oft, sac, sac_contract, sac_manager, sac_manager_client, sac_client }
     }
 }
 
@@ -133,8 +100,8 @@ impl TestSetupBuilder {
 pub struct TestSetup<'a> {
     pub env: Env,
     pub owner: Address,
-    pub oft: Address,
-    pub sc_manager: Address,
+    /// Address used as a minter in default setup (in minters list).
+    pub minter: Address,
     pub sac: Address,
     pub sac_contract: StellarAssetContract,
     pub sac_manager: Address,
@@ -174,17 +141,7 @@ pub fn mock_auth<A: IntoVal<Env, soroban_sdk::Vec<Val>>>(
     }]);
 }
 
-/// Mock auth for `set_supply_controller`.
-pub fn mock_set_supply_controller_auth(
-    setup: &TestSetup,
-    sender: &Address,
-    controller: &Address,
-    config: &Option<crate::extensions::supply_control::SupplyControllerConfig>,
-) {
-    mock_auth(&setup.env, &setup.sac_manager, sender, "set_supply_controller", (sender, controller, config.clone()));
-}
-
-/// Mock auth for OFT-originated `mint`.
+/// Mock auth for minter-originated `mint(to, amount, operation)`.
 pub fn mock_oft_mint_auth(setup: &TestSetup, recipient: &Address, amount: i128) {
-    mock_auth(&setup.env, &setup.sac_manager, &setup.oft, "mint", (recipient, amount));
+    mock_auth(&setup.env, &setup.sac_manager, &setup.minter, "mint", (recipient, amount, &setup.minter));
 }

package/package.json

@@ -1,18 +1,23 @@
 {
   "name": "@layerzerolabs/protocol-stellar-v2",
-  "version": "0.2.32",
+  "version": "0.2.34",
   "private": false,
   "devDependencies": {
     "@types/node": "^22.18.6",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
-    "@layerzerolabs/common-node-utils": "0.2.32",
-    "@layerzerolabs/vm-tooling-stellar": "0.2.32"
+    "@layerzerolabs/common-node-utils": "0.2.34",
+    "@layerzerolabs/vm-tooling-stellar": "0.2.34"
   },
   "publishConfig": {
     "access": "restricted",
     "registry": "https://registry.npmjs.org/"
   },
+  "externalRepoConfig": {
+    "targets": [
+      "audit-external"
+    ]
+  },
   "scripts": {
     "build": "pnpm build:contracts && pnpm generate:sdk",
     "build:contracts": "pnpm exec lz-tool stellar contract build",