@layerzerolabs/protocol-stellar-v2 0.2.29 → 0.2.30

package/contracts/oapps/oft-core/src/utils.rs

@@ -1,6 +1,6 @@
-use soroban_sdk::{address_payload::AddressPayload, assert_with_error, Address, BytesN, Env};
-
 use crate::errors::OFTError;
+use soroban_sdk::{address_payload::AddressPayload, assert_with_error, Address, BytesN, Env};
+use utils::option_ext::OptionExt;
 
 // =====================================================
 // OFT Helper Functions
@@ -38,18 +38,22 @@ pub fn remove_dust(amount_ld: i128, conversion_rate: i128) -> i128 {
 ///
 /// # Returns
 /// A 32-byte payload (contract ID hash or Ed25519 public key)
-pub fn address_payload(address: &Address) -> BytesN<32> {
-    match address.to_payload().unwrap() {
+pub fn address_payload(env: &Env, address: &Address) -> BytesN<32> {
+    match address.to_payload().unwrap_or_panic(env, OFTError::InvalidAddress) {
         AddressPayload::ContractIdHash(payload) => payload,
         AddressPayload::AccountIdPublicKeyEd25519(payload) => payload,
     }
 }
 
-/// Resolves a 32-byte payload to an address.
+/// Resolves a 32-byte payload back to a Stellar address.
+///
+/// Cross-chain messages only carry 32-byte addresses, but Stellar has two address types
+/// (contract C-addresses and account G-addresses) that share the same 32-byte payload.
+/// This function disambiguates by checking contract existence first, then falling back
+/// to a G-address.
 ///
-/// This function attempts to convert the 32-byte payload to a contract address first.
-/// If the contract exists, it returns the contract address.
-/// If the contract doesn't exist, it falls back to creating a G-address (account address).
+/// Sending tokens to a non-existent contract address is unlikely in practice — the sender
+/// on the source chain is expected to deploy the destination contract beforehand.
 ///
 /// # Arguments
 /// * `env` - The Soroban environment

package/contracts/sac-manager/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "sac-manager"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+doctest = false
+
+[features]
+library = []
+testutils = []
+
+[dependencies]
+soroban-sdk = { workspace = true }
+utils = { workspace = true }
+common-macros = { workspace = true }
+cfg-if = { workspace = true }
+oft = { workspace = true, features = ["library"] }
+
+[dev-dependencies]
+soroban-sdk = { workspace = true, features = ["testutils"] }
+utils = { workspace = true, features = ["testutils"] }
+oft = { workspace = true, features = ["testutils"] }

package/contracts/sac-manager/src/errors.rs

@@ -0,0 +1,18 @@
+//! General errors for the SAC Manager contract.
+//!
+//! Note: Extension-specific errors are co-located with their modules:
+//! - Supply control errors: `extensions/supply_control.rs` (SupplyControlError)
+//! - Redistribution errors: `extensions/redistribution.rs` (RedistributionError)
+
+use common_macros::contract_error;
+
+/// General SacManagerError: 3220-3249
+#[contract_error]
+pub enum SacManagerError {
+    /// OFT address has not been set yet
+    OftAddressNotSet,
+    /// The values are the same
+    SameValue,
+    /// Caller is not authorized for this operation
+    Unauthorized,
+}

package/contracts/sac-manager/src/extensions/mod.rs

@@ -0,0 +1,6 @@
+//! Token Wrapper extensions.
+//!
+//! Each extension owns its own storage and provides a trait with default implementations.
+
+pub mod redistribution;
+pub mod supply_control;

package/contracts/sac-manager/src/extensions/redistribution.rs

@@ -0,0 +1,109 @@
+//! Redistribution extension for handling assets associated with blacklisted addresses.
+
+use crate::{interfaces::ISacManager, sac_manager::sac_client};
+use common_macros::{contract_error, contract_trait, only_auth, storage};
+use soroban_sdk::{assert_with_error, contractevent, Address, Env};
+use utils::ownable::Ownable;
+
+// =========================================================================
+// Errors
+// =========================================================================
+
+#[contract_error]
+pub enum RedistributionError {
+    /// Account is not blacklisted (required for redistribution)
+    NotBlacklisted = 100,
+    /// Redistribution is not enabled
+    RedistributionNotEnabled,
+}
+
+// =========================================================================
+// Events
+// =========================================================================
+
+/// Event emitted when funds are redistributed from a blacklisted account.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct RedistributeFunds {
+    pub user: Address,
+    pub amount: i128,
+}
+
+// =========================================================================
+// Storage
+// =========================================================================
+
+#[storage]
+pub enum RedistributionStorage {
+    /// Whether redistribution is enabled.
+    /// Note: variant name must be globally unique across all storage enums to avoid
+    /// Soroban storage key collisions (contracttype serializes by variant name hash).
+    #[instance(bool)]
+    RedistributionEnabled,
+}
+
+// =========================================================================
+// Redistribution Trait
+// =========================================================================
+
+/// Redistribution trait for handling transfers to blacklisted addresses.
+/// Uses SAC's authorization system - blacklisted accounts have authorized=false.
+///
+/// Only the contract owner can redistribute funds.
+/// The redistribution target is always the contract owner.
+#[contract_trait(client_name = "RedistributionClient")]
+pub trait Redistribution: ISacManager + RedistributionInternal {
+    // =========================================================================
+    // Redistribution Operations
+    // =========================================================================
+
+    /// Redistributes funds from a blacklisted account to the owner.
+    #[only_auth]
+    fn redistribute_blacklisted_funds(env: &Env, from: &Address, amount: i128) {
+        assert_with_error!(env, Self::__redistribution_enabled(env), RedistributionError::RedistributionNotEnabled);
+
+        let sac_client = sac_client::<Self>(env);
+
+        // Require `from` to be blacklisted (not authorized on SAC)
+        assert_with_error!(env, !sac_client.authorized(from), RedistributionError::NotBlacklisted);
+
+        // Transfer from blacklisted account to owner using clawback + mint
+        let owner = Self::owner(env).unwrap();
+        sac_client.clawback(from, &amount);
+        sac_client.mint(&owner, &amount);
+
+        RedistributeFunds { user: from.clone(), amount }.publish(env);
+    }
+
+    // =========================================================================
+    // View Functions
+    // =========================================================================
+
+    fn redistribution_enabled(env: &Env) -> bool {
+        Self::__redistribution_enabled(env)
+    }
+}
+
+/// Internal trait for redistribution operations.
+pub trait RedistributionInternal: ISacManager + Ownable {
+    /// Redistributes funds from a blacklisted account to the owner.
+    fn __redistribute_funds(env: &Env, to: &Address, amount: i128) -> Address {
+        // If redistribution is enabled and the address is not authorized, redistribute the funds to the owner.
+        if Self::__redistribution_enabled(env) && !sac_client::<Self>(env).authorized(to) {
+            RedistributeFunds { user: to.clone(), amount }.publish(env);
+            Self::owner(env).unwrap()
+        } else {
+            to.clone()
+        }
+    }
+
+    /// Returns whether redistribution is enabled.
+    fn __redistribution_enabled(env: &Env) -> bool {
+        RedistributionStorage::has_redistribution_enabled(env)
+    }
+
+    /// Enables redistribution. only call this function at construction time.
+    fn __enable_redistribution(env: &Env) {
+        RedistributionStorage::set_redistribution_enabled(env, &true);
+    }
+}

package/contracts/sac-manager/src/extensions/supply_control/mod.rs

@@ -0,0 +1,488 @@
+//! Supply control extension for rate-limited minting.
+//!
+//! Provides rate-limited minting with per-controller capacity tracking
+//! and optional mint whitelist enforcement.
+//!
+//! Config and rate limit state are nested in the same struct for atomic storage,
+//! but logically separated so config updates don't reset inflight state.
+
+pub(crate) mod rate_limit;
+
+use common_macros::{contract_error, contract_trait, only_auth, storage};
+use rate_limit::{get_remaining_amount, try_consume};
+pub use rate_limit::{LimitConfig, RateLimitState};
+use soroban_sdk::{assert_with_error, contractevent, contracttype, panic_with_error, Address, Env, Vec};
+use utils::{option_ext::OptionExt, ownable::Ownable};
+
+// =========================================================================
+// Errors
+// =========================================================================
+
+/// Supply control errors: 3250-3299
+#[contract_error]
+pub enum SupplyControlError {
+    /// Entry already exists (supply controller, manager, or whitelist address)
+    AlreadyExists = 200,
+    /// Cannot burn from this address
+    CannotBurnFromAddress,
+    /// Cannot mint to this address (not in whitelist)
+    CannotMintToAddress,
+    /// Invalid amount
+    InvalidAmount,
+    /// Invalid configuration
+    InvalidConfig,
+    /// Entry not found (supply controller, manager, or whitelist address)
+    NotFound,
+    /// Timestamp is older than the last refill time
+    OldTimestamp,
+    /// Rate limit exceeded
+    RateLimitExceeded,
+    /// Value is already set to the same state
+    SameValue,
+    /// Caller is not authorized (not a supply controller or manager)
+    Unauthorized,
+}
+
+// =========================================================================
+// Events
+// =========================================================================
+
+/// Event emitted when a supply controller is added.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SupplyControllerAdded {
+    pub supply_controller: Address,
+    pub config: SupplyControllerConfig,
+}
+
+/// Event emitted when a supply controller is removed.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SupplyControllerRemoved {
+    pub supply_controller: Address,
+}
+
+/// Event emitted when limit configuration is updated for a supply controller.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct LimitConfigUpdated {
+    pub supply_controller: Address,
+    pub new_limit_config: LimitConfig,
+    pub old_limit_config: LimitConfig,
+}
+
+/// Event emitted when `allow_any_mint_burn` is updated for a supply controller.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct AllowAnyMintBurnUpdated {
+    pub supply_controller: Address,
+    pub new_allow: bool,
+    pub old_allow: bool,
+}
+
+/// Event emitted when a mint whitelist entry is added or removed.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct MintWhitelistSet {
+    pub supply_controller: Address,
+    pub mint_address: Address,
+    pub active: bool,
+}
+
+/// Event emitted when a supply controller manager is added or removed.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SupplyCtrlManagerSet {
+    pub manager: Address,
+    pub active: bool,
+}
+
+/// Event emitted when tokens are minted.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SupplyIncreased {
+    pub controller: Address,
+    pub to: Address,
+    pub amount: i128,
+}
+
+/// Event emitted when tokens are burned.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SupplyDecreased {
+    pub controller: Address,
+    pub from: Address,
+    pub amount: i128,
+}
+
+// =========================================================================
+// Types
+// =========================================================================
+
+/// Supply controller configuration (the configurable parameters).
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SupplyControllerConfig {
+    /// Limit configuration
+    pub limit_config: LimitConfig,
+    /// If true, allows the supply controller to mint to and burn from any address.
+    /// When false, the controller can only mint to addresses in its whitelist.
+    pub allow_any_mint_burn: bool,
+    /// Addresses that this supply controller is allowed to mint to (when `allow_any_mint_burn` is false).
+    pub whitelist_addresses: Vec<Address>,
+}
+
+/// Supply controller with both config and state nested together.
+/// Stored per-controller for O(1) access on every mint/burn.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SupplyControllerEntry {
+    /// Configuration (can be updated independently)
+    pub config: SupplyControllerConfig,
+    /// Rate limit state (preserved across config updates)
+    pub state: RateLimitState,
+}
+
+// =========================================================================
+// Storage
+// =========================================================================
+
+#[storage]
+pub enum SupplyControlStorage {
+    /// Whether supply control is enabled.
+    /// Note: variant name must be globally unique across all storage enums to avoid
+    /// Soroban storage key collisions (contracttype serializes by variant name hash).
+    #[instance(bool)]
+    SupplyControlEnabled,
+
+    /// Per-controller entry: config + rate limit state.
+    /// Keyed by controller address for O(1) access on every mint/burn.
+    #[persistent(SupplyControllerEntry)]
+    SupplyControllerEntry { controller: Address },
+
+    /// All supply controller addresses.
+    /// Stored as a single Vec since the number of controllers is expected to be small.
+    #[persistent(Vec<Address>)]
+    #[default(Vec::new(env))]
+    SupplyControllers,
+
+    /// All supply controller manager addresses.
+    /// Stored as a single Vec since the number of managers is expected to be small.
+    #[persistent(Vec<Address>)]
+    #[default(Vec::new(env))]
+    SupplyControllerManagers,
+}
+
+// =========================================================================
+// Supply Control Trait
+// =========================================================================
+
+/// Supply control trait for managing rate-limited minting.
+///
+/// ## Authorization Model
+/// - **Owner**: Can add/remove supply controller managers.
+/// - **Supply Controller Manager**: Can add/remove/update supply controllers.
+/// - **Supply Controller**: Can mint and burn tokens.
+///
+/// Note: Global enable/disable is managed by the SacManager contract directly.
+#[contract_trait(client_name = "SupplyControlClient")]
+pub trait SupplyControl: Ownable + SupplyControlInternal {
+    // =========================================================================
+    // Supply Controller Manager Management (owner-only)
+    // =========================================================================
+
+    /// Sets whether an address is a supply controller manager. Owner-only.
+    #[only_auth]
+    fn set_supply_controller_manager(env: &Env, manager: &Address, active: bool) {
+        let mut managers = Self::get_supply_controller_managers(env);
+
+        let idx = managers.first_index_of(manager);
+        if active {
+            assert_with_error!(env, idx.is_none(), SupplyControlError::AlreadyExists);
+            managers.push_back(manager.clone());
+        } else {
+            assert_with_error!(env, idx.is_some(), SupplyControlError::NotFound);
+            managers.remove(idx.unwrap());
+        }
+        SupplyControlStorage::set_supply_controller_managers(env, &managers);
+
+        SupplyCtrlManagerSet { manager: manager.clone(), active }.publish(env);
+    }
+
+    // =========================================================================
+    // Supply Controller Management (supply controller manager-only)
+    // =========================================================================
+
+    /// Sets or removes a supply controller. Manager-only.
+    ///
+    /// - `Some(config)`: Adds a new supply controller with the given configuration.
+    /// - `None`: Removes the supply controller.
+    fn set_supply_controller(
+        env: &Env,
+        sender: &Address,
+        supply_controller: &Address,
+        config: &Option<SupplyControllerConfig>,
+    ) {
+        require_manager_auth::<Self>(env, sender);
+
+        if let Some(config) = config {
+            Self::__add_supply_controller(env, supply_controller, config);
+        } else {
+            Self::__remove_supply_controller(env, supply_controller);
+        }
+    }
+
+    /// Updates the rate limit configuration for a supply controller. Manager-only.
+    /// Note: This does NOT reset the rate limit state (remaining_amount, last_refill_time).
+    fn update_limit_config(env: &Env, sender: &Address, supply_controller: &Address, limit_config: &LimitConfig) {
+        require_manager_auth::<Self>(env, sender);
+
+        validate_limit_config(env, limit_config);
+
+        let mut sc = Self::__get_entry_or_panic(env, supply_controller);
+        let old_limit_config = sc.config.limit_config.clone();
+        assert_with_error!(env, old_limit_config != *limit_config, SupplyControlError::SameValue);
+        sc.config.limit_config = limit_config.clone();
+        SupplyControlStorage::set_supply_controller_entry(env, supply_controller, &sc);
+
+        LimitConfigUpdated {
+            supply_controller: supply_controller.clone(),
+            new_limit_config: limit_config.clone(),
+            old_limit_config,
+        }
+        .publish(env);
+    }
+
+    /// Updates whether the supply controller can mint to and burn from any address. Manager-only.
+    fn update_allow_any_mint_burn(env: &Env, sender: &Address, supply_controller: &Address, allow_any_mint_burn: bool) {
+        require_manager_auth::<Self>(env, sender);
+
+        let mut sc = Self::__get_entry_or_panic(env, supply_controller);
+        let old_allow = sc.config.allow_any_mint_burn;
+        assert_with_error!(env, old_allow != allow_any_mint_burn, SupplyControlError::SameValue);
+        sc.config.allow_any_mint_burn = allow_any_mint_burn;
+        SupplyControlStorage::set_supply_controller_entry(env, supply_controller, &sc);
+
+        AllowAnyMintBurnUpdated {
+            supply_controller: supply_controller.clone(),
+            new_allow: allow_any_mint_burn,
+            old_allow,
+        }
+        .publish(env);
+    }
+
+    /// Sets whether an address is in the mint whitelist of a supply controller. Manager-only.
+    fn set_mint_whitelist(
+        env: &Env,
+        sender: &Address,
+        supply_controller: &Address,
+        mint_address: &Address,
+        active: bool,
+    ) {
+        require_manager_auth::<Self>(env, sender);
+
+        let mut sc = Self::__get_entry_or_panic(env, supply_controller);
+
+        let idx = sc.config.whitelist_addresses.first_index_of(mint_address);
+        if active {
+            assert_with_error!(env, idx.is_none(), SupplyControlError::AlreadyExists);
+            sc.config.whitelist_addresses.push_back(mint_address.clone());
+        } else {
+            assert_with_error!(env, idx.is_some(), SupplyControlError::NotFound);
+            sc.config.whitelist_addresses.remove(idx.unwrap());
+        }
+
+        SupplyControlStorage::set_supply_controller_entry(env, supply_controller, &sc);
+
+        MintWhitelistSet { supply_controller: supply_controller.clone(), mint_address: mint_address.clone(), active }
+            .publish(env);
+    }
+
+    // =========================================================================
+    // View Functions
+    // =========================================================================
+
+    /// Returns whether the given address is a supply controller manager.
+    fn is_supply_controller_manager(env: &Env, address: &Address) -> bool {
+        Self::get_supply_controller_managers(env).first_index_of(address).is_some()
+    }
+
+    /// Gets all supply controller manager addresses.
+    fn get_supply_controller_managers(env: &Env) -> Vec<Address> {
+        SupplyControlStorage::supply_controller_managers(env)
+    }
+
+    /// Gets supply controller configuration.
+    fn get_supply_controller_config(env: &Env, supply_controller: &Address) -> Option<SupplyControllerConfig> {
+        SupplyControlStorage::supply_controller_entry(env, supply_controller).map(|sc| sc.config)
+    }
+
+    fn allow_any_mint_burn(env: &Env, supply_controller: &Address) -> bool {
+        SupplyControlStorage::supply_controller_entry(env, supply_controller)
+            .map(|sc| sc.config.allow_any_mint_burn)
+            .unwrap_or(false)
+    }
+
+    /// Gets all active supply controller addresses.
+    fn get_supply_controllers(env: &Env) -> Vec<Address> {
+        SupplyControlStorage::supply_controllers(env)
+    }
+
+    /// Returns whether the given address is in the whitelist of a supply controller.
+    fn is_address_whitelisted(env: &Env, supply_controller: &Address, mint_address: &Address) -> bool {
+        SupplyControlStorage::supply_controller_entry(env, supply_controller)
+            .map(|sc| sc.config.whitelist_addresses.contains(mint_address))
+            .unwrap_or(false)
+    }
+
+    /// Gets remaining amount which can be minted at current timestamp.
+    fn get_remaining_mint_amount(env: &Env, supply_controller: &Address) -> i128 {
+        let Some(sc) = SupplyControlStorage::supply_controller_entry(env, supply_controller) else {
+            return 0;
+        };
+
+        get_remaining_amount(&sc.config.limit_config, &sc.state, env.ledger().timestamp())
+            .unwrap_or_else(|e| panic_with_error!(env, e))
+    }
+
+    fn supply_control_enabled(env: &Env) -> bool {
+        Self::__supply_control_enabled(env)
+    }
+}
+
+// =========================================================================
+// Internal Trait
+// =========================================================================
+
+/// Internal methods for supply control operations.
+/// Separated from the public `SupplyControl` trait for encapsulation.
+pub trait SupplyControlInternal {
+    /// Enforces mint supply controls: authorization, whitelist, rate limit, and state update.
+    /// Panics on failure.
+    fn __enforce_mint(env: &Env, sender: &Address, mint_to: &Address, amount: i128, fallback_auth: impl Fn(&Address)) {
+        if !Self::__supply_control_enabled(env) {
+            fallback_auth(sender);
+            return;
+        }
+
+        let mut sc = Self::__get_entry_or_panic(env, sender);
+
+        assert_with_error!(
+            env,
+            sc.config.allow_any_mint_burn || sc.config.whitelist_addresses.contains(mint_to),
+            SupplyControlError::CannotMintToAddress
+        );
+
+        try_consume(&sc.config.limit_config, &mut sc.state, env.ledger().timestamp(), amount)
+            .unwrap_or_else(|e| panic_with_error!(env, e));
+        SupplyControlStorage::set_supply_controller_entry(env, sender, &sc);
+
+        SupplyIncreased { controller: sender.clone(), to: mint_to.clone(), amount }.publish(env);
+    }
+
+    /// Enforces burn supply controls: authorization and burn permissions.
+    /// Panics on failure.
+    fn __enforce_burn(
+        env: &Env,
+        sender: &Address,
+        burn_from: &Address,
+        amount: i128,
+        fallback_auth: impl Fn(&Address),
+    ) {
+        if !Self::__supply_control_enabled(env) {
+            fallback_auth(sender);
+            return;
+        }
+
+        assert_with_error!(
+            env,
+            Self::__get_entry_or_panic(env, sender).config.allow_any_mint_burn,
+            SupplyControlError::CannotBurnFromAddress
+        );
+
+        SupplyDecreased { controller: sender.clone(), from: burn_from.clone(), amount }.publish(env);
+    }
+
+    /// Enables supply control. only call this function at construction time.
+    fn __enable_supply_control(env: &Env) {
+        SupplyControlStorage::set_supply_control_enabled(env, &true);
+    }
+
+    /// Adds a new supply controller with the given configuration.
+    fn __add_supply_controller(env: &Env, supply_controller: &Address, config: &SupplyControllerConfig) {
+        assert_with_error!(
+            env,
+            !SupplyControlStorage::has_supply_controller_entry(env, supply_controller),
+            SupplyControlError::AlreadyExists
+        );
+
+        validate_limit_config(env, &config.limit_config);
+
+        // set the initial state of the supply controller
+        let init_state = RateLimitState {
+            remaining_amount: config.limit_config.limit_capacity,
+            last_refill_time: env.ledger().timestamp(),
+        };
+        let entry = SupplyControllerEntry { config: config.clone(), state: init_state };
+        SupplyControlStorage::set_supply_controller_entry(env, supply_controller, &entry);
+
+        // add the supply controller to the list of supply controllers
+        let mut addresses = SupplyControlStorage::supply_controllers(env);
+        addresses.push_back(supply_controller.clone());
+        SupplyControlStorage::set_supply_controllers(env, &addresses);
+
+        SupplyControllerAdded { supply_controller: supply_controller.clone(), config: config.clone() }.publish(env);
+    }
+
+    /// Removes an existing supply controller.
+    fn __remove_supply_controller(env: &Env, supply_controller: &Address) {
+        assert_with_error!(
+            env,
+            SupplyControlStorage::has_supply_controller_entry(env, supply_controller),
+            SupplyControlError::NotFound
+        );
+
+        // remove the supply controller from the list of supply controllers
+        SupplyControlStorage::remove_supply_controller_entry(env, supply_controller);
+
+        // remove the supply controller from the list of supply controllers
+        let mut addresses = SupplyControlStorage::supply_controllers(env);
+        let idx = addresses.first_index_of(supply_controller).unwrap();
+        addresses.remove(idx);
+        SupplyControlStorage::set_supply_controllers(env, &addresses);
+
+        SupplyControllerRemoved { supply_controller: supply_controller.clone() }.publish(env);
+    }
+
+    // =========================================================================
+    // View Functions
+    // =========================================================================
+
+    fn __supply_control_enabled(env: &Env) -> bool {
+        SupplyControlStorage::has_supply_control_enabled(env)
+    }
+
+    /// Loads a supply controller entry, panicking with `NotFound` if it doesn't exist.
+    fn __get_entry_or_panic(env: &Env, controller: &Address) -> SupplyControllerEntry {
+        SupplyControlStorage::supply_controller_entry(env, controller)
+            .unwrap_or_panic(env, SupplyControlError::NotFound)
+    }
+}
+
+// =========================================================================
+// Helper Functions
+// =========================================================================
+
+fn require_manager_auth<T: SupplyControl>(env: &Env, sender: &Address) {
+    sender.require_auth();
+    assert_with_error!(env, T::is_supply_controller_manager(env, sender), SupplyControlError::Unauthorized);
+}
+
+/// Validates that limit_capacity and refill_per_second are non-negative.
+fn validate_limit_config(env: &Env, limit_config: &LimitConfig) {
+    assert_with_error!(
+        env,
+        limit_config.limit_capacity >= 0 && limit_config.refill_per_second >= 0,
+        SupplyControlError::InvalidConfig
+    );
+}