@layerzerolabs/common-utils-stellar-contracts 0.2.122

package/src/rbac.rs

@@ -0,0 +1,438 @@
+//! Role-Based Access Control (RBAC) for Soroban contracts.
+//!
+//! Combines OpenZeppelin-style role management with the Auth pattern.
+//! The authorizer (e.g. owner from Ownable, or contract from MultiSig) replaces Admin.
+
+use crate::{self as utils, auth::Auth, errors::RbacError, option_ext::OptionExt};
+use common_macros::{contract_trait, only_auth, storage};
+use soroban_sdk::{assert_with_error, contractevent, Address, Env, Symbol, Vec};
+
+// ===========================================================================
+// Constants
+// ===========================================================================
+
+/// Maximum number of roles that can exist simultaneously.
+pub const MAX_ROLES: u32 = 256;
+
+/// Role representing the contract's authorizer.
+pub const AUTHORIZER: &str = "AUTHORIZER";
+
+// ===========================================================================
+// Events
+// ===========================================================================
+
+/// Event emitted when a role is granted.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct RoleGranted {
+    #[topic]
+    pub role: Symbol,
+    #[topic]
+    pub account: Address,
+    pub caller: Address,
+}
+
+/// Event emitted when a role is revoked.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct RoleRevoked {
+    #[topic]
+    pub role: Symbol,
+    #[topic]
+    pub account: Address,
+    pub caller: Address,
+}
+
+/// Event emitted when a role admin is changed.
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct RoleAdminChanged {
+    #[topic]
+    pub role: Symbol,
+    pub previous_admin_role: Option<Symbol>,
+    pub new_admin_role: Option<Symbol>,
+}
+
+// ===========================================================================
+// Storage
+// ===========================================================================
+
+#[storage]
+pub enum RbacStorage {
+    /// All roles that have at least one member
+    #[persistent(Vec<Symbol>)]
+    #[default(Vec::new(env))]
+    ExistingRoles,
+
+    /// (role, index) -> Address
+    #[persistent(Address)]
+    RoleIndexToAccount { role: Symbol, index: u32 },
+
+    /// (role, account) -> index
+    #[persistent(u32)]
+    RoleAccountToIndex { role: Symbol, account: Address },
+
+    /// role -> count of accounts
+    #[persistent(u32)]
+    #[default(0)]
+    RoleAccountsCount { role: Symbol },
+
+    /// role -> admin role (who can grant/revoke this role). Key removed when no admin.
+    #[persistent(Symbol)]
+    RoleAdmin { role: Symbol },
+}
+
+// ===========================================================================
+// Trait
+// ===========================================================================
+
+/// Trait for contracts with role-based access control.
+///
+/// Extends `Auth` — the authorizer replaces the traditional admin and can grant/revoke
+/// any role. Each role can also have an admin role for hierarchical control.
+#[contract_trait]
+pub trait RoleBasedAccessControl: Auth {
+    // ===========================================================================
+    // State-changing
+    // ===========================================================================
+
+    /// Grants a role to an account. Caller must be owner or have the role's admin role.
+    ///
+    /// # Arguments
+    /// * `account` - The account to grant the role to.
+    /// * `role` - The role to grant.
+    /// * `caller` - The account that is granting the role. Must be owner or have the role's admin role.
+    fn grant_role(
+        env: &soroban_sdk::Env,
+        account: &soroban_sdk::Address,
+        role: &soroban_sdk::Symbol,
+        caller: &soroban_sdk::Address,
+    ) {
+        caller.require_auth();
+        ensure_if_authorizer_or_role_admin::<Self>(env, role, caller);
+        grant_role_no_auth(env, account, role, caller);
+    }
+
+    /// Revokes a role from an account. Caller must be owner or have the role's admin role.
+    ///
+    /// # Arguments
+    /// * `account` - The account to revoke the role from.
+    /// * `role` - The role to revoke.
+    /// * `caller` - The account that is revoking the role. Must be owner or have the role's admin role.
+    fn revoke_role(
+        env: &soroban_sdk::Env,
+        account: &soroban_sdk::Address,
+        role: &soroban_sdk::Symbol,
+        caller: &soroban_sdk::Address,
+    ) {
+        caller.require_auth();
+        ensure_if_authorizer_or_role_admin::<Self>(env, role, caller);
+        revoke_role_no_auth(env, account, role, caller);
+    }
+
+    /// Allows an account to renounce a role assigned to itself.
+    /// Users can only renounce roles for their own account.
+    ///
+    /// # Arguments
+    /// * `role` - The role to renounce.
+    /// * `caller` - The account that is renouncing the role. Must be the account itself.
+    fn renounce_role(env: &soroban_sdk::Env, role: &soroban_sdk::Symbol, caller: &soroban_sdk::Address) {
+        caller.require_auth();
+        revoke_role_no_auth(env, caller, role, caller);
+    }
+
+    /// Sets `admin_role` as the admin role of `role`. Caller must be the authorizer.
+    ///
+    /// # Arguments
+    /// * `role` - The role to set the admin for.
+    /// * `admin_role` - The admin role to set for the role.
+    ///
+    /// # Notes
+    ///
+    /// The admin role can be any `Symbol`, including one with no members. If the admin
+    /// role has no members, only the authorizer can grant/revoke the role.
+    #[only_auth]
+    fn set_role_admin(env: &soroban_sdk::Env, role: &soroban_sdk::Symbol, admin_role: &soroban_sdk::Symbol) {
+        set_role_admin_no_auth(env, role, admin_role);
+    }
+
+    /// Removes the admin role for a specified role. Caller must be the authorizer.
+    ///
+    /// # Arguments
+    /// * `role` - The role to remove the admin for.
+    ///
+    /// # Errors
+    /// * `RbacError::AdminRoleNotFound` - If no admin role is set for the role.
+    #[only_auth]
+    fn remove_role_admin(env: &soroban_sdk::Env, role: &soroban_sdk::Symbol) {
+        remove_role_admin_no_auth(env, role);
+    }
+
+    // ===========================================================================
+    // View functions
+    // ===========================================================================
+
+    /// Returns `Some(index)` if the account has the specified role, where `index`
+    /// is the index of the account in the role. Returns `None` if not.
+    ///
+    /// # Arguments
+    /// * `account` - The account to check the role for.
+    /// * `role` - The role to check the account for.
+    fn has_role(env: &soroban_sdk::Env, account: &soroban_sdk::Address, role: &soroban_sdk::Symbol) -> Option<u32> {
+        RbacStorage::role_account_to_index(env, role, account)
+    }
+
+    /// Returns the admin role for a specific role, or None if not set.
+    ///
+    /// # Arguments
+    /// * `role` - The role to get the admin for.
+    fn get_role_admin(env: &soroban_sdk::Env, role: &soroban_sdk::Symbol) -> Option<soroban_sdk::Symbol> {
+        RbacStorage::role_admin(env, role)
+    }
+
+    /// Returns the number of accounts that have the specified role.
+    ///
+    /// # Arguments
+    /// * `role` - The role to get the member count for.
+    fn get_role_member_count(env: &soroban_sdk::Env, role: &soroban_sdk::Symbol) -> u32 {
+        RbacStorage::role_accounts_count(env, role)
+    }
+
+    /// Returns the account at the specified index for a given role.
+    ///
+    /// # Arguments
+    /// * `role` - The role to get the member for.
+    /// * `index` - The index of the member to get.
+    ///
+    /// # Errors
+    /// * `RbacError::IndexOutOfBounds` if the index is out of bounds.
+    fn get_role_member(env: &soroban_sdk::Env, role: &soroban_sdk::Symbol, index: u32) -> soroban_sdk::Address {
+        RbacStorage::role_index_to_account(env, role, index).unwrap_or_panic(env, RbacError::IndexOutOfBounds)
+    }
+
+    /// Returns all roles that currently have at least one member.
+    /// Defaults to empty vector if no roles exist.
+    ///
+    /// # Notes
+    ///
+    /// This function returns all roles that currently have at least one member.
+    /// The maximum number of roles is limited by [`MAX_ROLES`].
+    fn get_existing_roles(env: &soroban_sdk::Env) -> soroban_sdk::Vec<soroban_sdk::Symbol> {
+        RbacStorage::existing_roles(env)
+    }
+}
+
+// ===========================================================================
+// Public helpers
+// ===========================================================================
+
+/// Ensures the caller has the specified role.
+///
+/// When `role` matches [`AUTHORIZER`], verifies that `caller` is the contract's
+/// authorizer (via [`Auth::authorizer`]) instead of checking RBAC storage.
+///
+/// # Arguments
+/// * `role` - The role to check the caller for.
+/// * `caller` - The account that is being checked. Must have the role.
+///
+/// # Errors
+/// * `Unauthorized` - If the caller does not have the role (or is not the authorizer).
+pub fn ensure_role<T: RoleBasedAccessControl>(env: &Env, role: &Symbol, caller: &Address) {
+    if *role == Symbol::new(env, AUTHORIZER) {
+        assert_with_error!(env, T::authorizer(env).as_ref() == Some(caller), RbacError::Unauthorized);
+    } else {
+        assert_with_error!(env, T::has_role(env, caller, role).is_some(), RbacError::Unauthorized);
+    }
+}
+
+/// Grants a role to an account without auth check.
+///
+/// # Arguments
+/// * `account` - The account to grant the role to.
+/// * `role` - The role to grant.
+/// * `caller` - The account that is granting the role. Must be owner or have the role's admin role.
+///
+/// # Security Warning
+///
+/// **IMPORTANT**: This function bypasses authorization checks and should only
+/// be used:
+/// - During contract initialization/construction
+/// - In admin functions that implement their own authorization logic
+///
+/// Using this function in public-facing methods creates significant security
+/// risks as it could allow unauthorized role assignments.
+pub fn grant_role_no_auth(env: &Env, account: &Address, role: &Symbol, caller: &Address) {
+    if RbacStorage::has_role_account_to_index(env, role, account) {
+        return;
+    }
+    add_to_role_enumeration(env, account, role);
+    RoleGranted { role: role.clone(), account: account.clone(), caller: caller.clone() }.publish(env);
+}
+
+/// Revokes a role from an account without auth check.
+///
+/// # Arguments
+/// * `account` - The account to revoke the role from.
+/// * `role` - The role to revoke.
+/// * `caller` - The account that is revoking the role. Must be owner or have the role's admin role.
+///
+/// # Security Warning
+///
+/// **IMPORTANT**: This function bypasses authorization checks and should only
+/// be used:
+/// - During contract initialization/construction
+/// - In admin functions that implement their own authorization logic
+///
+/// Using this function in public-facing methods creates significant security
+/// risks as it could allow unauthorized role revocations.
+pub fn revoke_role_no_auth(env: &Env, account: &Address, role: &Symbol, caller: &Address) {
+    assert_with_error!(env, RbacStorage::has_role_account_to_index(env, role, account), RbacError::RoleNotHeld);
+    remove_from_role_enumeration(env, account, role);
+    RoleRevoked { role: role.clone(), account: account.clone(), caller: caller.clone() }.publish(env);
+}
+
+/// Sets the admin role for a role without auth check. For constructor/init or when caller enforces own auth.
+///
+/// # Arguments
+/// * `role` - The role to set the admin for.
+/// * `admin_role` - The admin role to set for the role.
+///
+/// # Security Warning
+///
+/// **IMPORTANT**: This function bypasses authorization checks and should only
+/// be used:
+/// - During contract initialization/construction
+/// - In admin functions that implement their own authorization logic
+///
+/// Using this function in public-facing methods creates significant security
+/// risks as it could allow unauthorized admin role assignments.
+///
+/// # Circular Admin Warning
+///
+/// **CAUTION**: This function allows the creation of circular admin
+/// relationships between roles. For example, it's possible to assign MINT_ADMIN
+/// as the admin of MINT_ROLE while also making MINT_ROLE the admin of
+/// MINT_ADMIN. Such circular relationships can lead to unintended consequences,
+/// including:
+///
+/// - Race conditions where each role can revoke the other
+/// - Potential security vulnerabilities in role management
+/// - Confusing governance structures that are difficult to reason about
+///
+/// When designing your role hierarchy, carefully consider the relationships
+/// between roles and avoid creating circular dependencies.
+pub fn set_role_admin_no_auth(env: &Env, role: &Symbol, admin_role: &Symbol) {
+    let previous = RbacStorage::role_admin(env, role);
+    RbacStorage::set_role_admin(env, role, admin_role);
+    RoleAdminChanged { role: role.clone(), previous_admin_role: previous, new_admin_role: Some(admin_role.clone()) }
+        .publish(env);
+}
+
+/// Removes the admin role for a specified role without auth check.
+///
+/// For use in admin functions that implement their own authorization logic,
+/// or when cleaning up unused roles.
+///
+/// # Arguments
+/// * `role` - The role to remove the admin for.
+///
+/// # Errors
+/// * `RbacError::AdminRoleNotFound` - If no admin role is set for the role.
+///
+/// # Security Warning
+///
+/// **IMPORTANT**: This function bypasses authorization checks and should only
+/// be used:
+/// - In admin functions that implement their own authorization logic
+/// - When cleaning up unused roles
+pub fn remove_role_admin_no_auth(env: &Env, role: &Symbol) {
+    let previous = RbacStorage::role_admin(env, role);
+    assert_with_error!(env, previous.is_some(), RbacError::AdminRoleNotFound);
+    RbacStorage::remove_role_admin(env, role);
+    RoleAdminChanged { role: role.clone(), previous_admin_role: previous, new_admin_role: None }.publish(env);
+}
+
+// ===========================================================================
+// Private helpers
+// ===========================================================================
+
+/// Ensures the caller is the authorizer or has the role's admin role.
+///
+/// # Arguments
+/// * `role` - The role to check the caller for.
+/// * `caller` - The account that is being checked. Must be the authorizer or have the role's admin role.
+///
+/// # Errors
+/// * `Unauthorized` - If the caller is neither the authorizer nor has the role's admin role.
+fn ensure_if_authorizer_or_role_admin<T: RoleBasedAccessControl>(env: &Env, role: &Symbol, caller: &Address) {
+    assert_with_error!(
+        env,
+        T::get_role_admin(env, role).is_some_and(|admin_role| T::has_role(env, caller, &admin_role).is_some())
+            || Some(caller) == T::authorizer(env).as_ref(),
+        RbacError::Unauthorized
+    );
+}
+
+/// Adds an account to the role enumeration.
+///
+/// # Arguments
+/// * `account` - The account to add to the role enumeration.
+/// * `role` - The role to add the account to.
+fn add_to_role_enumeration(env: &Env, account: &Address, role: &Symbol) {
+    let count = RbacStorage::role_accounts_count(env, role);
+
+    // If the role has no accounts, add it to the existing roles
+    if count == 0 {
+        let mut existing = RbacStorage::existing_roles(env);
+        assert_with_error!(env, existing.len() < MAX_ROLES, RbacError::MaxRolesExceeded);
+        existing.push_back(role.clone());
+        RbacStorage::set_existing_roles(env, &existing);
+    }
+
+    RbacStorage::set_role_index_to_account(env, role, count, account);
+    RbacStorage::set_role_account_to_index(env, role, account, &count);
+    RbacStorage::set_role_accounts_count(env, role, &(count + 1));
+}
+
+/// Removes an account from the role enumeration.
+///
+/// # Arguments
+/// * `account` - The account to remove from the role enumeration.
+/// * `role` - The role to remove the account from.
+fn remove_from_role_enumeration(env: &Env, account: &Address, role: &Symbol) {
+    let count = RbacStorage::role_accounts_count(env, role);
+    assert_with_error!(env, count > 0, RbacError::RoleIsEmpty);
+
+    // Get the index of the account to remove
+    let to_remove_idx =
+        RbacStorage::role_account_to_index(env, role, account).unwrap_or_panic(env, RbacError::RoleNotHeld);
+
+    // Get the index of the last account for the role
+    let last_idx = count - 1;
+
+    // Remove the target account's mappings
+    RbacStorage::remove_role_index_to_account(env, role, to_remove_idx);
+    RbacStorage::remove_role_account_to_index(env, role, account);
+
+    // If the removed account wasn't the last, move the last account into the vacated slot
+    if to_remove_idx != last_idx {
+        // Get the last account and remove the mapping from index to account
+        let last_account =
+            RbacStorage::role_index_to_account(env, role, last_idx).unwrap_or_panic(env, RbacError::IndexOutOfBounds);
+        RbacStorage::remove_role_index_to_account(env, role, last_idx);
+
+        // Move the last account into the vacated slot
+        RbacStorage::set_role_index_to_account(env, role, to_remove_idx, &last_account);
+        RbacStorage::set_role_account_to_index(env, role, &last_account, &to_remove_idx);
+    }
+
+    RbacStorage::set_role_accounts_count(env, role, &last_idx);
+
+    // If this was the last account with this role, remove the role from the existing roles
+    if last_idx == 0 {
+        let mut existing = RbacStorage::existing_roles(env);
+        let pos = existing.first_index_of(role).unwrap_or_panic(env, RbacError::RoleNotFound);
+        existing.remove(pos);
+        RbacStorage::set_existing_roles(env, &existing);
+    }
+}

package/src/testing_utils.rs

@@ -0,0 +1,180 @@
+use soroban_sdk::{testutils::Events, xdr, Address, Env, Event, TryFromVal, Val, Vec};
+
+/// Decodes a raw emitted contract event (XDR) into `(topics, data)`.
+///
+/// Soroban testutils exposes events as [`ContractEvents`](soroban_sdk::testutils::ContractEvents),
+/// which internally stores XDR [`ContractEvent`](soroban_sdk::xdr::ContractEvent) values.
+/// This helper converts the XDR topics/data into `soroban_sdk::Val` so tests can inspect
+/// topics and data using normal Soroban conversions (`TryFromVal` / `IntoVal`).
+///
+/// Returns `None` if any topic or the data payload can't be converted into `Val` for the
+/// provided `Env`.
+///
+/// # Example
+/// ```ignore
+/// let events = env.events().all().filter_by_contract(&contract);
+/// for ev in events.events().iter() {
+///     let (topics, data) = utils::testing_utils::decode_event_topics_data(&env, ev).unwrap();
+///     // ... inspect topics/data ...
+/// }
+/// ```
+pub fn decode_event_topics_data(env: &Env, event: &xdr::ContractEvent) -> Option<(Vec<Val>, Val)> {
+    // In the current Soroban SDK version this is always `V0`.
+    // Using a single-variant match avoids "irrefutable let-else" warnings.
+    let v0 = match &event.body {
+        xdr::ContractEventBody::V0(v0) => v0,
+    };
+
+    let mut topics = Vec::<Val>::new(env);
+    for t in v0.topics.iter() {
+        topics.push_back(Val::try_from_val(env, t).ok()?);
+    }
+    let data = Val::try_from_val(env, &v0.data).ok()?;
+    Some((topics, data))
+}
+
+/// Asserts that the environment emitted exactly one event: `expected`.
+///
+/// This is a **strict equality** assertion over `env.events().all()`:
+/// the full event list must be exactly `[expected]` (no extra events).
+///
+/// Uses the event struct's `.topics()` and `.data()` methods (generated by `#[contractevent]`)
+/// to compare against emitted events. No more hardcoding topic names or field keys!
+///
+/// # Example
+/// ```ignore
+/// use crate::events::OwnershipTransferred;
+///
+/// let expected = OwnershipTransferred {
+///     previous_owner: owner.clone(),
+///     new_owner: new_owner.clone(),
+/// };
+/// assert_eq_event(&env, &contract, expected);
+/// ```
+pub fn assert_eq_event<E: Event>(env: &Env, contract: &Address, expected: E) {
+    // Compare against the emitted `xdr::ContractEvent` directly. This avoids the
+    // `xdr -> Val` roundtrip and ensures we match exactly what was emitted.
+    //
+    // IMPORTANT: This asserts *equality* (not "contains").
+    extern crate std;
+
+    assert_eq!(
+        env.events().all(),
+        std::vec![expected.to_xdr(env, contract)],
+        "Expected exactly one event. Expected topics: {:?}, data: {:?}",
+        expected.topics(env),
+        expected.data(env),
+    );
+}
+
+/// Asserts that the contract emitted an event equal to `expected`.
+///
+/// This is a **contains** assertion: after filtering events by `contract`,
+/// `expected` must appear at least once (order doesn't matter; extra events allowed).
+///
+/// Uses the event struct's `.topics()` and `.data()` methods (generated by `#[contractevent]`)
+/// to compare against emitted events. No more hardcoding topic names or field keys!
+///
+/// # Example
+/// ```ignore
+/// use crate::events::OwnershipTransferred;
+///
+/// let expected = OwnershipTransferred {
+///     previous_owner: owner.clone(),
+///     new_owner: new_owner.clone(),
+/// };
+/// assert_eq_event(&env, &contract, expected);
+/// ```
+pub fn assert_contains_event<E: Event>(env: &Env, contract: &Address, expected: E) {
+    // Compare against the emitted `xdr::ContractEvent` directly. This avoids the
+    // `xdr -> Val` roundtrip and ensures we match exactly what was emitted.
+    let expected_xdr = expected.to_xdr(env, contract);
+
+    let events = env.events().all().filter_by_contract(contract);
+    let mut found = false;
+    for event in events.events().iter() {
+        if *event == expected_xdr {
+            found = true;
+            break;
+        }
+    }
+
+    assert!(
+        found,
+        "Expected event not found. Expected topics: {:?}, data: {:?}",
+        expected.topics(env),
+        expected.data(env)
+    );
+}
+
+/// Asserts that the environment emitted events that match `expected_events` exactly.
+///
+/// This is a **strict equality** assertion over `env.events().all()`:
+/// the full event list must match `expected_events` **in order** and **count**
+/// (no missing/extra events).
+///
+/// # Example
+/// ```ignore
+/// assert_eq_events(env, &contract, &[
+///     &Event1 { ... },
+///     &Event2 { ... },
+/// ]);
+/// ```
+
+pub fn assert_eq_events(env: &Env, contract: &Address, expected_events: &[&dyn Event]) {
+    // Note: this module is only compiled for tests / testutils usage, where `std` is available.
+    extern crate std;
+    let expected_xdrs: std::vec::Vec<xdr::ContractEvent> =
+        expected_events.iter().map(|e| e.to_xdr(env, contract)).collect();
+
+    assert_eq!(env.events().all(), expected_xdrs, "Expected events to match exactly");
+}
+
+/// Asserts that all `expected_events` were emitted by the contract (in any order).
+///
+/// This is a **contains** assertion with multiset semantics: after filtering events by
+/// `contract`, every expected event must be present, and duplicates in `expected_events`
+/// require duplicate emissions. Extra emitted events are allowed.
+///
+/// # Example
+/// ```ignore
+/// assert_eq_events(env, &contract, &[
+///     &Event1 { ... },
+///     &Event2 { ... },
+/// ]);
+/// ```
+
+pub fn assert_contains_events(env: &Env, contract: &Address, expected_events: &[&dyn Event]) {
+    // Note: this module is only compiled for tests / testutils usage, where `std` is available.
+    extern crate std;
+    let events = env.events().all().filter_by_contract(contract);
+    let raw_events = events.events();
+    // Track which emitted events have already been matched so that duplicate expectations
+    // require duplicate emissions (multiset semantics).
+    // We use a `std::vec::Vec<bool>` as a "used" mask to implement multiset matching.
+    let mut used: std::vec::Vec<bool> = std::vec![false; raw_events.len()];
+
+    for (i, expected) in expected_events.iter().enumerate() {
+        let expected_xdr = expected.to_xdr(env, contract);
+
+        let mut found = false;
+        for (idx, event) in raw_events.iter().enumerate() {
+            if used[idx] {
+                continue;
+            }
+            if *event == expected_xdr {
+                used[idx] = true;
+                found = true;
+                break;
+            }
+        }
+
+        assert!(
+            found,
+            "Expected event #{} not found. Expected topics: {:?}, data: {:?}",
+            i,
+            expected.topics(env),
+            expected.data(env)
+        );
+    }
+}