Trait AccessControl 

pub trait AccessControl {
    // Provided methods
    fn has_role(e: &Env, account: Address, role: Symbol) -> Option<u32> { ... }
    fn get_existing_roles(e: &Env) -> Vec<Symbol> { ... }
    fn get_role_member_count(e: &Env, role: Symbol) -> u32 { ... }
    fn get_role_member(e: &Env, role: Symbol, index: u32) -> Address { ... }
    fn get_role_admin(e: &Env, role: Symbol) -> Option<Symbol> { ... }
    fn get_admin(e: &Env) -> Option<Address> { ... }
    fn grant_role(e: &Env, account: Address, role: Symbol, caller: Address) { ... }
    fn revoke_role(e: &Env, account: Address, role: Symbol, caller: Address) { ... }
    fn renounce_role(e: &Env, role: Symbol, caller: Address) { ... }
    fn accept_admin_transfer(e: &Env) { ... }
    fn transfer_admin_role(e: &Env, new_admin: Address, live_until_ledger: u32) { ... }
    fn set_role_admin(e: &Env, role: Symbol, admin_role: Symbol) { ... }
    fn renounce_admin(e: &Env) { ... }
}

Provided Methods

fn has_role(e: &Env, account: Address, role: Symbol) -> Option<u32>

Returns Some(index) if the account has the specified role, where index is the position of the account for that role, and can be used to query AccessControl::get_role_member(). Returns None if the account does not have the specified role.

Arguments

• e - Access to Soroban environment.
• account - The account to check.
• role - The role to check for.

fn get_existing_roles(e: &Env) -> Vec<Symbol>

Returns a vector containing all existing roles. Defaults to empty vector if no roles exist.

Arguments

• e - Access to Soroban environment.

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_role_member_count(e: &Env, role: Symbol) -> u32

Returns the total number of accounts that have the specified role. If the role does not exist, returns 0.

Arguments

• e - Access to Soroban environment.
• role - The role to get the count for.

fn get_role_member(e: &Env, role: Symbol, index: u32) -> Address

Returns the account at the specified index for a given role.

We do not provide a function to get all the members of a role, since that would be unbounded. If you need to enumerate all the members of a role, you can use AccessControl::get_role_member_count() to get the total number of members and then use AccessControl::get_role_member() to get each member one by one.

Arguments

• e - Access to Soroban environment.
• role - The role to query.
• index - The index of the account to retrieve.

Errors

• AccessControlError::IndexOutOfBounds - If the index is out of bounds for the role’s member list.

fn get_role_admin(e: &Env, role: Symbol) -> Option<Symbol>

Returns the admin role for a specific role. If no admin role is explicitly set, returns None.

Arguments

• e - Access to Soroban environment.
• role - The role to query the admin role for.

fn get_admin(e: &Env) -> Option<Address>

Returns the admin account.

Arguments

• e - Access to Soroban environment.

fn grant_role(e: &Env, account: Address, role: Symbol, caller: Address)

Grants a role to an account.

Arguments

• e - Access to Soroban environment.
• account - The account to grant the role to.
• role - The role to grant.
• caller - The address of the caller, must be the admin or have the RoleAdmin for the role.

Errors

• AccessControlError::Unauthorized - If the caller does not have enough privileges.
• AccessControlError::MaxRolesExceeded - If adding a new role would exceed the maximum allowed number of roles.

Events

• topics - ["role_granted", role: Symbol, account: Address]
• data - [caller: Address]

fn revoke_role(e: &Env, account: Address, role: Symbol, caller: Address)

Revokes a role from an account. To revoke your own role, please use AccessControl::renounce_role() instead.

Arguments

• e - Access to Soroban environment.
• account - The account to revoke the role from.
• role - The role to revoke.
• caller - The address of the caller, must be the admin or has the RoleAdmin for the role.

Errors

• AccessControlError::Unauthorized - If the caller does not have enough privileges.
• AccessControlError::RoleNotHeld - If the account doesn’t have the role.
• AccessControlError::RoleIsEmpty - If the role has no members.

Events

• topics - ["role_revoked", role: Symbol, account: Address]
• data - [caller: Address]

fn renounce_role(e: &Env, role: Symbol, caller: Address)

Allows an account to renounce a role assigned to itself. Users can only renounce roles for their own account.

Arguments

• e - Access to Soroban environment.
• role - The role to renounce.
• caller - The address of the caller, must be the account that has the role.

Errors

• AccessControlError::RoleNotHeld - If the caller doesn’t have the role.
• AccessControlError::RoleIsEmpty - If the role has no members.

Events

• topics - ["role_revoked", role: Symbol, account: Address]
• data - [caller: Address]

fn accept_admin_transfer(e: &Env)

Initiates the admin role transfer. Admin privileges for the current admin are not revoked until the recipient accepts the transfer. Overrides the previous pending transfer if there is one.

Arguments

• e - Access to Soroban environment.
• new_admin - The account to transfer the admin privileges to.
• live_until_ledger - The ledger number at which the pending transfer expires. If live_until_ledger is 0, the pending transfer is cancelled. live_until_ledger argument is implicitly bounded by the maximum allowed TTL extension for a temporary storage entry and specifying a higher value will cause the code to panic.

Errors

• crate::role_transfer::RoleTransferError::NoPendingTransfer - If trying to cancel a transfer that doesn’t exist.
• crate::role_transfer::RoleTransferError::InvalidLiveUntilLedger - If the specified ledger is in the past.
• crate::role_transfer::RoleTransferError::InvalidPendingAccount - If the specified pending account is not the same as the provided new address.
• AccessControlError::AdminNotSet - If admin account is not set.

Events

• topics - ["admin_transfer_initiated", current_admin: Address]
• data - [new_admin: Address, live_until_ledger: u32]

Notes

• Authorization for the current admin is required.

fn transfer_admin_role(e: &Env, new_admin: Address, live_until_ledger: u32)

Completes the 2-step admin transfer.

Arguments

• e - Access to Soroban environment.

Events

• topics - ["admin_transfer_completed", new_admin: Address]
• data - [previous_admin: Address]

Errors

• crate::role_transfer::RoleTransferError::NoPendingTransfer - If there is no pending transfer to accept.
• AccessControlError::AdminNotSet - If admin account is not set.

fn set_role_admin(e: &Env, role: Symbol, admin_role: Symbol)

Sets admin_role as the admin role of role.

Arguments

• e - Access to Soroban environment.
• role - The role to set the admin for.
• admin_role - The new admin role.

Events

• topics - ["role_admin_changed", role: Symbol]
• data - [previous_admin_role: Symbol, new_admin_role: Symbol]

Errors

• AccessControlError::AdminNotSet - If admin account is not set.

Notes

• Authorization for the current admin is required.

fn renounce_admin(e: &Env)

Allows the current admin to renounce their role, making the contract permanently admin-less. This is useful for decentralization purposes or when the admin role is no longer needed. Once the admin is renounced, it cannot be reinstated.

Arguments

• e - Access to Soroban environment.

Errors

• AccessControlError::AdminNotSet - If no admin account is set.

Events

• topics - ["admin_renounced", admin: Address]
• data - []

Notes

• Authorization for the current admin is required.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors