You are not reading the current version of this documentation. 2.0.0 is the current version.

Access Control

This crate provides ways to restrict who can access the functions of a contract or when they can do it.

  • Ownable is a simple mechanism with a single "owner" role that can be assigned to a single account. This mechanism can be useful in simple scenarios, but fine grained access needs are likely to outgrow it.

  • AccessControl provides a general role based access control mechanism. Multiple hierarchical roles can be created and assigned each to multiple accounts.

Core

OwnableComponent 

use openzeppelin_access::ownable::OwnableComponent;

Ownable provides a basic access control mechanism where an account (an owner) can be granted exclusive access to specific functions.

This module includes the internal assert_only_owner to restrict a function to be used only by the owner.

Internal Implementations
InternalImpl
Events

Embeddable functions

owner(self: @ContractState) → ContractAddress external

Returns the address of the current owner.

transfer_ownership(ref self: ContractState, new_owner: ContractAddress) external

Transfers ownership of the contract to a new account (new_owner). Can only be called by the current owner.

Emits an OwnershipTransferred event.

renounce_ownership(ref self: ContractState) external

Leaves the contract without owner. It will not be possible to call assert_only_owner functions anymore. Can only be called by the current owner.

Renouncing ownership will leave the contract without an owner, thereby removing any functionality that is only available to the owner.

Embeddable functions (two step transfer)

owner(self: @ContractState) → ContractAddress external

Returns the address of the current owner.

pending_owner(self: @ContractState) → ContractAddress external

Returns the address of the pending owner.

accept_ownership(ref self: ContractState) external

Transfers ownership of the contract to the pending owner. Can only be called by the pending owner. Resets pending owner to zero address.

Emits an OwnershipTransferred event.

transfer_ownership(ref self: ContractState, new_owner: ContractAddress) external

Starts the two step ownership transfer process, by setting the pending owner. Setting new_owner to the zero address is allowed, this can be used to cancel an initiated ownership transfer.

Can only be called by the current owner.

Emits an OwnershipTransferStarted event.

renounce_ownership(ref self: ContractState) external

Leaves the contract without owner. It will not be possible to call assert_only_owner functions anymore. Can only be called by the current owner.

Renouncing ownership will leave the contract without an owner, thereby removing any functionality that is only available to the owner.

transferOwnership(ref self: ContractState, newOwner: ContractAddress) external

See transfer_ownership.

renounceOwnership(ref self: ContractState) external

See renounce_ownership.

pendingOwner(self: @ContractState) external

See pending_owner.

acceptOwnership(self: @ContractState) external

See accept_ownership.

transferOwnership(self: @ContractState) external

See transfer_ownership.

renounceOwnership(self: @ContractState) external

See renounce_ownership.

Internal functions

initializer(ref self: ContractState, owner: ContractAddress) internal

Initializes the contract and sets owner as the initial owner.

Requirements:

  • owner cannot be the zero address.

Emits an OwnershipTransferred event.

assert_only_owner(self: @ContractState) internal

Panics if called by any account other than the owner.

_transfer_ownership(ref self: ContractState, new_owner: ContractAddress) internal

Transfers ownership of the contract to a new account (new_owner). Internal function without access restriction.

Emits an OwnershipTransferred event.

_propose_owner(ref self: ContractState, new_owner: ContractAddress) internal

Sets a new pending owner in a two step transfer.

Internal function without access restriction.

Emits an OwnershipTransferStarted event.

Events

OwnershipTransferStarted(previous_owner: ContractAddress, new_owner: ContractAddress) event

Emitted when the pending owner is updated.

OwnershipTransferred(previous_owner: ContractAddress, new_owner: ContractAddress) event

Emitted when the ownership is transferred.

IAccessControl 

use openzeppelin_access::accesscontrol::interface::IAccessControl;

External interface of AccessControl.

SRC5 ID

0x23700be02858dbe2ac4dc9c9f66d0b6b0ed81ec7f970ca6844500a56ff61751

Functions
Events

Functions

has_role(role: felt252, account: ContractAddress) → bool external

Returns whether account can act as role.

get_role_admin(role: felt252) → felt252 external

Returns the admin role that controls role. See grant_role and revoke_role.

To change a role’s admin, use set_role_admin.

grant_role(role: felt252, account: ContractAddress) external

Grants role to account.

If account had not been already granted role, emits a RoleGranted event.

Requirements:

  • the caller must have role's admin role.

revoke_role(role: felt252, account: ContractAddress) external

Revokes role from account.

If account had been granted role, emits a RoleRevoked event.

Requirements:

  • the caller must have role's admin role.

renounce_role(role: felt252, account: ContractAddress) external

Revokes role from the calling account.

Roles are often managed via grant_role and revoke_role. This function’s purpose is to provide a mechanism for accounts to lose their privileges if they are compromised (such as when a trusted device is misplaced).

If the calling account had been granted role, emits a RoleRevoked event.

Requirements:

  • the caller must be account.

Events

RoleAdminChanged(role: felt252, previous_admin_role: ContractAddress, new_admin_role: ContractAddress) event

Emitted when new_admin_role is set as role's admin role, replacing previous_admin_role

DEFAULT_ADMIN_ROLE is the starting admin for all roles, despite RoleAdminChanged not being emitted signaling this.

RoleGranted(role: felt252, account: ContractAddress, sender: ContractAddress) event

Emitted when account is granted role.

sender is the account that originated the contract call, an account with the admin role or the deployer address if _grant_role is called from the constructor.

RoleRevoked(role: felt252, account: ContractAddress, sender: ContractAddress) event

Emitted when account is revoked role.

sender is the account that originated the contract call:

  • if using revoke_role, it is the admin role bearer.

  • if using renounce_role, it is the role bearer (i.e. account).

IAccessControlWithDelay 

use openzeppelin_access::accesscontrol::interface::IAccessControlWithDelay;

External interface for the extended AccessControlWithDelay functionality.

Functions
Events

Functions

get_role_status(role: felt252, account: ContractAddress) → RoleStatus external

Returns the account’s status for the given role. The possible statuses are:

  • NotGranted: the role has not been granted to the account.

  • Delayed: The role has been granted to the account but is not yet active due to a time delay.

  • Effective: the role has been granted to the account and is currently active.

grant_role_with_delay(role: felt252, account: ContractAddress, delay: u64) external

Attempts to grant role to account with the specified activation delay.

Requirements:

  • The caller must have role's admin role.

  • delay must be greater than 0.

  • the role must not be already effective for account.

May emit a RoleGrantedWithDelay event.

Events

RoleGrantedWithDelay(role: felt252, account: ContractAddress, sender: ContractAddress, delay: u64) event

Emitted when account is granted role with a delay.

sender is the account that originated the contract call, an account with the admin role or the deployer address if _grant_role_with_delay is called from the constructor.

AccessControlComponent 

use openzeppelin_access::accesscontrol::AccessControlComponent;

Component that allows contracts to implement role-based access control mechanisms. Roles are referred to by their felt252 identifier:

const MY_ROLE: felt252 = selector!("MY_ROLE");

Roles can be used to represent a set of permissions. To restrict access to a function call, use assert_only_role:

(...)

#[external(v0)]
fn foo(ref self: ContractState) {
    self.accesscontrol.assert_only_role(MY_ROLE);

    // Do something
}

Roles can be granted and revoked dynamically via the grant_role, grant_role_with_delay and revoke_role functions. Each role has an associated admin role, and only accounts that have a role’s admin role can call grant_role, grant_role_with_delay and revoke_role.

By default, the admin role for all roles is DEFAULT_ADMIN_ROLE, which means that only accounts with this role will be able to grant or revoke other roles. More complex role relationships can be created by using set_role_admin.

The DEFAULT_ADMIN_ROLE is also its own admin: it has permission to grant and revoke this role. Extra precautions should be taken to secure accounts that have been granted it. See AccessControlDefaultAdminRulesComponent.
Internal Implementations
InternalImpl
Events
IAccessControl
IAccessControlWithDelay

Embeddable functions

has_role(self: @ContractState, role: felt252, account: ContractAddress) → bool external

Returns whether account can act as role.

get_role_admin(self: @ContractState, role: felt252) → felt252 external

Returns the admin role that controls role. See grant_role and revoke_role.

To change a role’s admin, use set_role_admin.

get_role_status(self: @ContractState, role: felt252, account: ContractAddress) → RoleStatus external

Returns the account’s status for the given role.

The possible statuses are:

  • NotGranted: the role has not been granted to the account.

  • Delayed: The role has been granted to the account but is not yet active due to a time delay.

  • Effective: the role has been granted to the account and is currently active.

grant_role(ref self: ContractState, role: felt252, account: ContractAddress) external

Grants role to account.

If account had not been already granted role, emits a RoleGranted event.

Requirements:

  • the caller must have role's admin role.

May emit a RoleGranted event.

grant_role_with_delay(ref self: ContractState, role: felt252, account: ContractAddress, delay: u64) external

Attempts to grant role to account with the specified activation delay.

Requirements:

  • The caller must have `role’s admin role.

  • delay must be greater than 0.

  • the role must not be already effective for account.

May emit a RoleGrantedWithDelay event.

revoke_role(ref self: ContractState, role: felt252, account: ContractAddress) external

Revokes role from account.

If account had been granted role, emits a RoleRevoked event.

Requirements:

  • the caller must have role's admin role.

May emit a RoleRevoked event.

renounce_role(ref self: ContractState, role: felt252, account: ContractAddress) external

Revokes role from the calling account.

Roles are often managed via grant_role and revoke_role. This function’s purpose is to provide a mechanism for accounts to lose their privileges if they are compromised (such as when a trusted device is misplaced).

If the calling account had been revoked role, emits a RoleRevoked event.

Requirements:

  • the caller must be account.

May emit a RoleRevoked event.

supports_interface(self: @ContractState, interface_id: felt252) → bool external

See ISRC5::supports_interface.

hasRole(self: @ContractState, role: felt252, account: ContractAddress) → bool external

See has_role.

getRoleAdmin(self: @ContractState, role: felt252) → felt252 external

See get_role_admin.

grantRole(ref self: ContractState, role: felt252, account: ContractAddress) external

See grant_role.

revokeRole(ref self: ContractState, role: felt252, account: ContractAddress) external

See revoke_role.

renounceRole(ref self: ContractState, role: felt252, account: ContractAddress) external

See renounce_role.

Internal functions

initializer(ref self: ContractState) internal

Initializes the contract by registering the IAccessControl interface ID.

assert_only_role(self: @ContractState, role: felt252) internal

Validates that the caller can act as the given role. Otherwise it panics.

is_role_effective(self: @ContractState, role: felt252, account: ContractAddress) → bool internal

Returns whether the account can act as the given role.

The account can act as the role if it is active and the effective_from time is before or equal to the current time.

If the effective_from timepoint is 0, the role is effective immediately. This is backwards compatible with implementations that didn’t use delays but a single boolean flag.

resolve_role_status(self: @ContractState, role: felt252, account: ContractAddress) → RoleStatus internal

Returns the account’s status for the given role.

The possible statuses are:

  • NotGranted: the role has not been granted to the account.

  • Delayed: The role has been granted to the account but is not yet active due to a time delay.

  • Effective: the role has been granted to the account and is currently active.

is_role_granted(self: @ContractState, role: felt252, account: ContractAddress) → bool internal

Returns whether the account has the given role granted.

The account may not be able to act as the role yet, if a delay was set and has not passed yet. Use is_role_effective to check if the account can act as the role.

set_role_admin(ref self: ContractState, role: felt252, admin_role: felt252) internal

Sets admin_role as role's admin role.

Internal function without access restriction.

Emits a RoleAdminChanged event.

_grant_role(ref self: ContractState, role: felt252, account: ContractAddress) internal

Attempts to grant role to account. The function does nothing if role is already effective for account. If role has been granted to account, but is not yet active due to a time delay, the delay is removed and role becomes effective immediately.

Internal function without access restriction.

May emit a RoleGranted event.

_grant_role_with_delay(ref self: ContractState, role: felt252, account: ContractAddress, delay: u64) internal

Attempts to grant role to account with the specified activation delay.

The role will become effective after the given delay has passed. If the role is already active (Effective) for the account, the function will panic. If the role has been granted but is not yet active (being in the Delayed state), the existing delay will be overwritten with the new delay.

Internal function without access restriction.

Requirements:

  • delay must be greater than 0.

  • the role must not be already effective for account.

May emit a RoleGrantedWithDelay event.

_revoke_role(ref self: ContractState, role: felt252, account: ContractAddress) internal

Revokes role from account.

Internal function without access restriction.

May emit a RoleRevoked event.

Events

RoleAdminChanged(role: felt252, previous_admin_role: ContractAddress, new_admin_role: ContractAddress) event

See IAccessControl::RoleAdminChanged.

RoleGranted(role: felt252, account: ContractAddress, sender: ContractAddress) event

See IAccessControl::RoleGranted.

RoleGrantedWithDelay(role: felt252, account: ContractAddress, sender: ContractAddress, delay: u64) event

See IAccessControlWithDelay::RoleGrantedWithDelay.

RoleRevoked(role: felt252, account: ContractAddress, sender: ContractAddress) event

See IAccessControl::RoleRevoked.

Extensions

IAccessControlDefaultAdminRules 

use openzeppelin_access::accesscontrol::extensions::interface::IAccessControlDefaultAdminRules;

External interface of AccessControlDefaultAdminRules declared to support SRC5 detection.

SRC5 ID

0x3509b3083c9586afe5dae781146b0608c3846870510f8d4d21ae38676cc33eb

Functions
Events

Functions

default_admin() → ContractAddress external

Returns the address of the current DEFAULT_ADMIN_ROLE holder.

pending_default_admin() → (ContractAddress, u64) external

Returns a tuple of a new_admin and an accept_schedule.

After the accept_schedule passes, the new_admin will be able to accept the default_admin role by calling accept_default_admin_transfer, completing the role transfer.

A zero value only in accept_schedule indicates no pending admin transfer.

A zero address new_admin means that default_admin is being renounced.

default_admin_delay() → u64 external

Returns the delay required to schedule the acceptance of a default_admin transfer started.

This delay will be added to the current timestamp when calling begin_default_admin_transfer to set the acceptance schedule.

If a delay change has been scheduled, it will take effect as soon as the schedule passes, making this function return the new delay.

See change_default_admin_delay.

pending_default_admin_delay() → (u64, u64) external

Returns a tuple of new_delay and an effect_schedule.

After the effect_schedule passes, the new_delay will get into effect immediately for every new default_admin transfer started with begin_default_admin_transfer.

A zero value only in effect_schedule indicates no pending delay change.

A zero value only for new_delay means that the next default_admin_delay will be zero after the effect schedule.

begin_default_admin_transfer(new_admin) external

Starts a default_admin transfer by setting a pending_default_admin scheduled for acceptance after the current timestamp plus a default_admin_delay.

Requirements:

  • Only can be called by the current default_admin.

Emits a DefaultAdminTransferScheduled event.

cancel_default_admin_transfer() external

Cancels a default_admin transfer previously started with begin_default_admin_transfer.

A pending_default_admin not yet accepted can also be cancelled with this function.

Requirements:

  • Only can be called by the current default_admin.

May emit a DefaultAdminTransferCanceled event.

accept_default_admin_transfer() external

Completes a default_admin transfer previously started with begin_default_admin_transfer.

After calling the function:

  • DEFAULT_ADMIN_ROLE must be granted to the caller.

  • DEFAULT_ADMIN_ROLE must be revoked from the previous holder.

  • pending_default_admin must be reset to zero value.

Requirements:

change_default_admin_delay(new_delay) external

Initiates a default_admin_delay update by setting a pending_default_admin_delay scheduled to take effect after the current timestamp plus a default_admin_delay.

This function guarantees that any call to begin_default_admin_transfer done between the timestamp this method is called and the pending_default_admin_delay effect schedule will use the current default_admin_delay set before calling.

The pending_default_admin_delay's effect schedule is defined in a way that waiting until the schedule and then calling begin_default_admin_transfer with the new delay will take at least the same as another default_admin complete transfer (including acceptance).

The schedule is designed for two scenarios:

  • When the delay is changed for a larger one the schedule is block.timestamp + new delay capped by default_admin_delay_increase_wait.

  • When the delay is changed for a shorter one, the schedule is block.timestamp + (current delay - new delay).

A pending_default_admin_delay that never got into effect will be canceled in favor of a new scheduled change.

Requirements:

  • Only can be called by the current default_admin.

Emits a DefaultAdminDelayChangeScheduled event and may emit a DefaultAdminDelayChangeCanceled event.

rollback_default_admin_delay() external

Cancels a scheduled default_admin_delay change.

Requirements:

  • Only can be called by the current default_admin.

May emit a DefaultAdminDelayChangeCanceled event.

default_admin_delay_increase_wait() → u64 external

Maximum time in seconds for an increase to default_admin_delay (that is scheduled using change_default_admin_delay) to take effect. Defaults to 5 days.

When the default_admin_delay is scheduled to be increased, it goes into effect after the new delay has passed with the purpose of giving enough time for reverting any accidental change (i.e. using milliseconds instead of seconds) that may lock the contract. However, to avoid excessive schedules, the wait is capped by this function and it can be overridden for a custom default_admin_delay increase scheduling.

Make sure to add a reasonable amount of time while overriding this value, otherwise, there’s a risk of setting a high new delay that goes into effect almost immediately without the possibility of human intervention in the case of an input error (e.g. set milliseconds instead of seconds).

Events

DefaultAdminTransferScheduled(new_admin: ContractAddress, accept_schedule: u64) event

Emitted when a default_admin transfer is started.

Sets new_admin as the next address to become the default_admin by calling accept_default_admin_transfer only after accept_schedule passes.

DefaultAdminTransferCanceled() event

Emitted when a pending_default_admin is reset if it was never accepted, regardless of its schedule.

DefaultAdminDelayChangeScheduled(new_delay: u64, effect_schedule: u64) event

Emitted when a default_admin_delay change is started.

Sets new_delay as the next delay to be applied between default admins transfers after effect_schedule has passed.

Emitted when a pending_default_admin_delay is reset if its schedule didn’t pass.

AccessControlDefaultAdminRulesComponent 

use openzeppelin_access::accesscontrol::extensions::AccessControlDefaultAdminRulesComponent;

Extension of AccessControl that allows specifying special rules to manage the DEFAULT_ADMIN_ROLE holder, which is a sensitive role with special permissions over other roles that may potentially have privileged rights in the system.

If a specific role doesn’t have an admin role assigned, the holder of the DEFAULT_ADMIN_ROLE will have the ability to grant it and revoke it.

This contract implements the following risk mitigations on top of AccessControl:

  • Only one account holds the DEFAULT_ADMIN_ROLE since deployment until it’s potentially renounced.

  • Enforces a 2-step process to transfer the DEFAULT_ADMIN_ROLE to another account.

  • Enforces a configurable delay between the two steps, with the ability to cancel before the transfer is accepted.

  • The delay can be changed by scheduling, see change_default_admin_delay.

  • It is not possible to use another role to manage the DEFAULT_ADMIN_ROLE.

Internal Implementations
InternalImpl
Events
IAccessControl
IAccessControlWithDelay
IAccessControlDefaultAdminRules

Embeddable functions

default_admin(self: @ContractState) → ContractAddress external

Returns the address of the current DEFAULT_ADMIN_ROLE holder.

pending_default_admin(self: @ContractState) → (ContractAddress, u64) external

Returns a tuple of a new_admin and an accept_schedule.

After the accept_schedule passes, the new_admin will be able to accept the default_admin role by calling accept_default_admin_transfer, completing the role transfer.

A zero value only in accept_schedule indicates no pending admin transfer.

A zero address new_admin means that default_admin is being renounced.

default_admin_delay(self: @ContractState) → u64 external

Returns the delay required to schedule the acceptance of a default_admin transfer started.

This delay will be added to the current timestamp when calling begin_default_admin_transfer to set the acceptance schedule.

If a delay change has been scheduled, it will take effect as soon as the schedule passes, making this function returns the new delay.

See change_default_admin_delay.

pending_default_admin_delay(self: @ContractState) → (u64, u64) external

Returns a tuple of new_delay and an effect_schedule.

After the effect_schedule passes, the new_delay will get into effect immediately for every new default_admin transfer started with begin_default_admin_transfer.

A zero value only in effect_schedule indicates no pending delay change.

A zero value only for new_delay means that the next default_admin_delay will be zero after the effect schedule.

begin_default_admin_transfer(ref self: ContractState, new_admin: ContractAddress) external

Starts a default_admin transfer by setting a pending_default_admin scheduled for acceptance after the current timestamp plus a default_admin_delay.

Requirements:

  • Only can be called by the current default_admin.

Emits a DefaultAdminTransferScheduled event.

cancel_default_admin_transfer(ref self: ContractState) external

Cancels a default_admin transfer previously started with begin_default_admin_transfer.

A pending_default_admin not yet accepted can also be cancelled with this function.

Requirements:

  • Only can be called by the current default_admin.

May emit a DefaultAdminTransferCanceled event.

accept_default_admin_transfer(ref self: ContractState) external

Completes a default_admin transfer previously started with begin_default_admin_transfer.

After calling the function:

  • DEFAULT_ADMIN_ROLE must be granted to the caller.

  • DEFAULT_ADMIN_ROLE must be revoked from the previous holder.

  • pending_default_admin must be reset to zero values.

Requirements:

change_default_admin_delay(ref self: ContractState, new_delay: u64) external

Initiates a default_admin_delay update by setting a pending_default_admin_delay scheduled for getting into effect after the current timestamp plus a default_admin_delay.

This function guarantees that any call to begin_default_admin_transfer done between the timestamp this method is called and the pending_default_admin_delay effect schedule will use the current default_admin_delay set before calling.

The pending_default_admin_delay's effect schedule is defined in a way that waiting until the schedule and then calling begin_default_admin_transfer with the new delay will take at least the same as another default_admin complete transfer (including acceptance).

The schedule is designed for two scenarios:

  • When the delay is changed for a larger one the schedule is block.timestamp
    new delay     capped by default_admin_delay_increase_wait.

  • When the delay is changed for a shorter one, the schedule is block.timestamp
    (current delay - new delay)    .

A pending_default_admin_delay that never got into effect will be canceled in favor of a new scheduled change.

Requirements:

  • Only can be called by the current default_admin.

Emits a DefaultAdminDelayChangeScheduled event and may emit a DefaultAdminDelayChangeCanceled event.

rollback_default_admin_delay(ref self: ContractState) external

Cancels a scheduled default_admin_delay change.

Requirements:

  • Only can be called by the current default_admin.

May emit a DefaultAdminDelayChangeCanceled event.

default_admin_delay_increase_wait(self: @ContractState) → u64 external

Maximum time in seconds for an increase to default_admin_delay (that is scheduled using change_default_admin_delay) to take effect. Defaults to 5 days.

When the default_admin_delay is scheduled to be increased, it goes into effect after the new delay has passed with the purpose of giving enough time for reverting any accidental change (i.e. using milliseconds instead of seconds) that may lock the contract. However, to avoid excessive schedules, the wait is capped by this function and it can be overridden for a custom default_admin_delay increase scheduling.

Make sure to add a reasonable amount of time while overriding this value, otherwise, there’s a risk of setting a high new delay that goes into effect almost immediately without the possibility of human intervention in the case of an input error (eg. set milliseconds instead of seconds).

has_role(self: @ContractState, role: felt252, account: ContractAddress) → bool external

Returns whether account can act as role.

get_role_admin(self: @ContractState, role: felt252) → felt252 external

Returns the admin role that controls role. See grant_role and revoke_role.

To change a role’s admin, use set_role_admin.

get_role_status(self: @ContractState, role: felt252, account: ContractAddress) → RoleStatus external

Returns the account’s status for the given role.

The possible statuses are:

  • NotGranted: the role has not been granted to the account.

  • Delayed: The role has been granted to the account but is not yet active due to a time delay.

  • Effective: the role has been granted to the account and is currently active.

grant_role(ref self: ContractState, role: felt252, account: ContractAddress) external

Grants role to account.

If account had not been already granted role, emits a RoleGranted event.

Requirements:

  • the caller must have role's admin role.

May emit a RoleGranted event.

grant_role_with_delay(ref self: ContractState, role: felt252, account: ContractAddress, delay: u64) external

Attempts to grant role to account with the specified activation delay.

Requirements:

  • The caller must have `role’s admin role.

  • delay must be greater than 0.

  • the role must not be already effective for account.

May emit a RoleGrantedWithDelay event.

revoke_role(ref self: ContractState, role: felt252, account: ContractAddress) external

Revokes role from account.

If account had been granted role, emits a RoleRevoked event.

Requirements:

  • the caller must have role's admin role.

May emit a RoleRevoked event.

renounce_role(ref self: ContractState, role: felt252, account: ContractAddress) external

Revokes role from the calling account.

Roles are often managed via grant_role and revoke_role. This function’s purpose is to provide a mechanism for accounts to lose their privileges if they are compromised (such as when a trusted device is misplaced).

If the calling account had been revoked role, emits a RoleRevoked event.

Requirements:

  • the caller must be account.

May emit a RoleRevoked event.

supports_interface(self: @ContractState, interface_id: felt252) → bool external

See ISRC5::supports_interface.

hasRole(self: @ContractState, role: felt252, account: ContractAddress) → bool external

See has_role.

getRoleAdmin(self: @ContractState, role: felt252) → felt252 external

See get_role_admin.

grantRole(ref self: ContractState, role: felt252, account: ContractAddress) external

See grant_role.

revokeRole(ref self: ContractState, role: felt252, account: ContractAddress) external

See revoke_role.

renounceRole(ref self: ContractState, role: felt252, account: ContractAddress) external

See renounce_role.

Internal functions

initializer(ref self: ContractState, initial_delay: u64, initial_default_admin: ContractAddress) external

Initializes the contract by registering the IAccessControl interface ID and setting the initial delay and default admin.

Requirements:

  • initial_default_admin must not be the zero address.

assert_only_role(self: @ContractState, role: felt252) external

Validates that the caller can act as the given role. Otherwise it panics.

is_role_effective(self: @ContractState, role: felt252, account: ContractAddress) → bool external

Returns whether the account can act as the given role.

The account can act as the role if it is active and the effective_from time is before or equal to the current time.

If the effective_from timepoint is 0, the role is effective immediately. This is backwards compatible with implementations that didn’t use delays but a single boolean flag.

resolve_role_status(self: @ContractState, role: felt252, account: ContractAddress) → RoleStatus external

Returns the account’s status for the given role.

The possible statuses are:

  • NotGranted: the role has not been granted to the account.

  • Delayed: The role has been granted to the account but is not yet active due to a time delay.

  • Effective: the role has been granted to the account and is currently active.

is_role_granted(self: @ContractState, role: felt252, account: ContractAddress) → bool external

Returns whether the account has the given role granted.

The account may not be able to act as the role yet, if a delay was set and has not passed yet. Use {is_role_effective} to check if the account can act as the role.

set_role_admin(ref self: ContractState, role: felt252, admin_role: felt252) external

Sets admin_role as `role’s admin role.

Internal function without access restriction.

Requirements:

  • role must not be DEFAULT_ADMIN_ROLE.

Emits a RoleAdminChanged event.

_grant_role(ref self: ContractState, role: felt252, account: ContractAddress) external

Attempts to grant role to account. The function does nothing if role is already effective for account. If role has been granted to account, but is not yet active due to a time delay, the delay is removed and role becomes effective immediately.

Internal function without access restriction.

For DEFAULT_ADMIN_ROLE, it only allows granting if there isn’t already a default_admin or if the role has been previously renounced.

Exposing this function through another mechanism may make the DEFAULT_ADMIN_ROLE assignable again. Make sure to guarantee this is the expected behavior in your implementation.

May emit a RoleGranted event.

_grant_role_with_delay(ref self: ContractState, role: felt252, account: ContractAddress, delay: u64) external

Attempts to grant role to account with the specified activation delay.

The role will become effective after the given delay has passed. If the role is already active (Effective) for the account, the function will panic. If the role has been granted but is not yet active (being in the Delayed state), the existing delay will be overwritten with the new delay.

Internal function without access restriction.

Requirements:

  • delay must be greater than 0.

  • the role must not be already effective for account.

  • role must not be DEFAULT_ADMIN_ROLE.

May emit a RoleGrantedWithDelay event.

_revoke_role(ref self: ContractState, role: felt252, account: ContractAddress) external

Attempts to revoke role from account. The function does nothing if role is not effective for account. If role has been revoked from account, but is still active due to a time delay, the delay is removed and role becomes inactive immediately.

Internal function without access restriction.

May emit a RoleRevoked event.

set_pending_default_admin(ref self: ContractState, new_admin: ContractAddress, new_schedule: u64) external

Setter of the tuple for pending admin and its schedule.

May emit a {DefaultAdminTransferCanceled} event.

set_pending_delay(ref self: ContractState, new_delay: u64, new_schedule: u64) external

Setter of the tuple for pending delay and its schedule.

May emit a {DefaultAdminDelayChangeCanceled} event.

delay_change_wait(self: @ContractState, new_delay: u64) → u64 external

Returns the amount of seconds to wait after the new_delay will become the new default_admin_delay.

The value returned guarantees that if the delay is reduced, it will go into effect after a wait that honors the previously set delay.

See default_admin_delay_increase_wait.

Events

RoleAdminChanged(role: felt252, previous_admin_role: felt252, new_admin_role: felt252) event

Emitted when new_admin_role is set as role’s admin role, replacing `previous_admin_role

DEFAULT_ADMIN_ROLE is the starting admin for all roles, despite RoleAdminChanged not being emitted signaling this.

RoleGranted(role: felt252, account: ContractAddress, sender: ContractAddress) event

Emitted when account is granted role.

sender is the account that originated the contract call, an account with the admin role or the deployer address if _grant_role is called from the constructor.

RoleRevoked(role: felt252, account: ContractAddress, sender: ContractAddress) event

Emitted when role is revoked for account.

sender is the account that originated the contract call:

  • If using revoke_role, it is the admin role bearer.

  • If using renounce_role, it is the role bearer (i.e. account).

RoleGrantedWithDelay(role: felt252, account: ContractAddress, sender: ContractAddress, delay: u64) event

Emitted when account is granted role with a delay.

sender is the account that originated the contract call, an account with the admin role or the deployer address if _grant_role_with_delay is called from the constructor.

DefaultAdminTransferScheduled(new_admin: ContractAddress, accept_schedule: u64) event

Emitted when a default_admin transfer is started.

Sets new_admin as the next address to become the default_admin by calling accept_default_admin_transfer only after accept_schedule passes.

DefaultAdminTransferCanceled() event

Emitted when a pending_default_admin is reset if it was never accepted, regardless of its schedule.

DefaultAdminDelayChangeScheduled(new_delay: u64, effect_schedule: u64) event

Emitted when a default_admin_delay change is started.

Sets new_delay as the next delay to be applied between default admins transfers after effect_schedule has passed.

Emitted when a pending_default_admin_delay is reset if its schedule didn’t pass.

← Access
Accounts →