Access Control

This document is better viewed at https://docs.openzeppelin.com/contracts/api/access

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

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

  • Ownable is a simpler mechanism with a single owner "role" that can be assigned to a single account. This simpler mechanism can be useful for quick tests but projects with production concerns are likely to outgrow it.

Core

Ownable 

import "@openzeppelin/contracts/access/Ownable.sol";

Contract module which provides a basic access control mechanism, where there is an account (an owner) that can be granted exclusive access to specific functions.

The initial owner is set to the address provided by the deployer. This can later be changed with transferOwnership.

This module is used through inheritance. It will make available the modifier onlyOwner, which can be applied to your functions to restrict their use to the owner.

Modifiers
Functions
Events

onlyOwner() modifier

Throws if called by any account other than the owner.

constructor(address initialOwner) internal

Initializes the contract setting the address provided by the deployer as the initial owner.

owner() → address public

Returns the address of the current owner.

_checkOwner() internal

Throws if the sender is not the owner.

renounceOwnership() public

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

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

transferOwnership(address newOwner) public

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

_transferOwnership(address newOwner) internal

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

OwnershipTransferred(address indexed previousOwner, address indexed newOwner) event

Ownable2Step 

import "@openzeppelin/contracts/access/Ownable2Step.sol";

Contract module which provides access control mechanism, where there is an account (an owner) that can be granted exclusive access to specific functions.

The initial owner is specified at deployment time in the constructor for Ownable. This can later be changed with transferOwnership and acceptOwnership.

This module is used through inheritance. It will make available all functions from parent (Ownable).

Functions
Ownable
Events
Ownable

pendingOwner() → address public

Returns the address of the pending owner.

transferOwnership(address newOwner) public

Starts the ownership transfer of the contract to a new account. Replaces the pending transfer if there is one. Can only be called by the current owner.

_transferOwnership(address newOwner) internal

Transfers ownership of the contract to a new account (newOwner) and deletes any pending owner. Internal function without access restriction.

acceptOwnership() public

The new owner accepts the ownership transfer.

OwnershipTransferStarted(address indexed previousOwner, address indexed newOwner) event

IAccessControl 

import "@openzeppelin/contracts/access/IAccessControl.sol";

External interface of AccessControl declared to support ERC165 detection.

Functions
Events

hasRole(bytes32 role, address account) → bool external

Returns true if account has been granted role.

getRoleAdmin(bytes32 role) → bytes32 external

Returns the admin role that controls role. See grantRole and revokeRole.

To change a role’s admin, use AccessControl._setRoleAdmin.

grantRole(bytes32 role, address account) 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.

revokeRole(bytes32 role, address account) external

Revokes role from account.

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

Requirements:

  • the caller must have role's admin role.

renounceRole(bytes32 role, address callerConfirmation) external

Revokes role from the calling account.

Roles are often managed via grantRole and revokeRole: 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 callerConfirmation.

RoleAdminChanged(bytes32 indexed role, bytes32 indexed previousAdminRole, bytes32 indexed newAdminRole) event

Emitted when newAdminRole is set as role's admin role, replacing previousAdminRole

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

RoleGranted(bytes32 indexed role, address indexed account, address indexed sender) event

Emitted when account is granted role.

sender is the account that originated the contract call, an admin role bearer except when using {AccessControl-_setupRole}.

RoleRevoked(bytes32 indexed role, address indexed account, address indexed sender) event

Emitted when account is revoked role.

sender is the account that originated the contract call: - if using revokeRole, it is the admin role bearer - if using renounceRole, it is the role bearer (i.e. account)

AccessControl 

import "@openzeppelin/contracts/access/AccessControl.sol";

Contract module that allows children to implement role-based access control mechanisms. This is a lightweight version that doesn’t allow enumerating role members except through off-chain means by accessing the contract event logs. Some applications may benefit from on-chain enumerability, for those cases see AccessControlEnumerable.

Roles are referred to by their bytes32 identifier. These should be exposed in the external API and be unique. The best way to achieve this is by using public constant hash digests:

bytes32 public constant MY_ROLE = keccak256("MY_ROLE");

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

function foo() public {
    require(hasRole(MY_ROLE, msg.sender));
    ...
}

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

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 _setRoleAdmin.

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. We recommend using AccessControlDefaultAdminRules to enforce additional security measures for this role.
Modifiers
Functions
Events
IAccessControl

onlyRole(bytes32 role) modifier

Modifier that checks that an account has a specific role. Reverts with a standardized message including the required role.

The format of the revert reason is given by the following regular expression:

/^AccessControl: account (0x[0-9a-f]{40}) is missing role (0x[0-9a-f]{64})$/

supportsInterface(bytes4 interfaceId) → bool public

See IERC165.supportsInterface.

hasRole(bytes32 role, address account) → bool public

Returns true if account has been granted role.

_checkRole(bytes32 role) internal

Revert with a standard message if _msgSender() is missing role. Overriding this function changes the behavior of the onlyRole modifier.

Format of the revert message is described in _checkRole.

_checkRole(bytes32 role, address account) internal

Revert with a standard message if account is missing role.

The format of the revert reason is given by the following regular expression:

/^AccessControl: account (0x[0-9a-f]{40}) is missing role (0x[0-9a-f]{64})$/

getRoleAdmin(bytes32 role) → bytes32 public

Returns the admin role that controls role. See grantRole and revokeRole.

To change a role’s admin, use _setRoleAdmin.

grantRole(bytes32 role, address account) public

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.

revokeRole(bytes32 role, address account) public

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.

renounceRole(bytes32 role, address callerConfirmation) public

Revokes role from the calling account.

Roles are often managed via grantRole and revokeRole: 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 callerConfirmation.

May emit a RoleRevoked event.

_setRoleAdmin(bytes32 role, bytes32 adminRole) internal

Sets adminRole as role's admin role.

Emits a RoleAdminChanged event.

_grantRole(bytes32 role, address account) internal

Grants role to account.

Internal function without access restriction.

May emit a RoleGranted event.

_revokeRole(bytes32 role, address account) internal

Revokes role from account.

Internal function without access restriction.

May emit a RoleRevoked event.

Extensions

IAccessControlEnumerable 

import "@openzeppelin/contracts/access/extensions/IAccessControlEnumerable.sol";

External interface of AccessControlEnumerable declared to support ERC165 detection.

Functions
IAccessControl
Events
IAccessControl

getRoleMember(bytes32 role, uint256 index) → address external

Returns one of the accounts that have role. index must be a value between 0 and getRoleMemberCount, non-inclusive.

Role bearers are not sorted in any particular way, and their ordering may change at any point.

When using getRoleMember and getRoleMemberCount, make sure you perform all queries on the same block. See the following forum post for more information.

getRoleMemberCount(bytes32 role) → uint256 external

Returns the number of accounts that have role. Can be used together with getRoleMember to enumerate all bearers of a role.

AccessControlEnumerable 

import "@openzeppelin/contracts/access/extensions/AccessControlEnumerable.sol";

Extension of AccessControl that allows enumerating the members of each role.

Functions
AccessControl
Events
IAccessControl

supportsInterface(bytes4 interfaceId) → bool public

See IERC165.supportsInterface.

getRoleMember(bytes32 role, uint256 index) → address public

Returns one of the accounts that have role. index must be a value between 0 and getRoleMemberCount, non-inclusive.

Role bearers are not sorted in any particular way, and their ordering may change at any point.

When using getRoleMember and getRoleMemberCount, make sure you perform all queries on the same block. See the following forum post for more information.

getRoleMemberCount(bytes32 role) → uint256 public

Returns the number of accounts that have role. Can be used together with getRoleMember to enumerate all bearers of a role.

_grantRole(bytes32 role, address account) internal

Overload _grantRole to track enumerable memberships

_revokeRole(bytes32 role, address account) internal

Overload _revokeRole to track enumerable memberships

IAccessControlDefaultAdminRules 

import "@openzeppelin/contracts/access/extensions/IAccessControlDefaultAdminRules.sol";

External interface of AccessControlDefaultAdminRules declared to support ERC165 detection.

Functions
IAccessControl
Events
IAccessControl

defaultAdmin() → address external

Returns the address of the current DEFAULT_ADMIN_ROLE holder.

pendingDefaultAdmin() → address newAdmin, uint48 acceptSchedule external

Returns a tuple of a newAdmin and an accept schedule.

After the schedule passes, the newAdmin will be able to accept the defaultAdmin role by calling acceptDefaultAdminTransfer, completing the role transfer.

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

A zero address newAdmin means that defaultAdmin is being renounced.

defaultAdminDelay() → uint48 external

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

This delay will be added to the current timestamp when calling beginDefaultAdminTransfer 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 changeDefaultAdminDelay.

pendingDefaultAdminDelay() → uint48 newDelay, uint48 effectSchedule external

Returns a tuple of newDelay and an effect schedule.

After the schedule passes, the newDelay will get into effect immediately for every new defaultAdmin transfer started with beginDefaultAdminTransfer.

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

A zero value only for newDelay means that the next defaultAdminDelay will be zero after the effect schedule.

beginDefaultAdminTransfer(address newAdmin) external

Starts a defaultAdmin transfer by setting a pendingDefaultAdmin scheduled for acceptance after the current timestamp plus a defaultAdminDelay.

Requirements:

Emits a DefaultAdminRoleChangeStarted event.

cancelDefaultAdminTransfer() external

Cancels a defaultAdmin transfer previously started with beginDefaultAdminTransfer.

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

Requirements:

May emit a DefaultAdminTransferCanceled event.

acceptDefaultAdminTransfer() external

Completes a defaultAdmin transfer previously started with beginDefaultAdminTransfer.

After calling the function:

  • DEFAULT_ADMIN_ROLE should be granted to the caller.

  • DEFAULT_ADMIN_ROLE should be revoked from the previous holder.

  • pendingDefaultAdmin should be reset to zero values.

Requirements:

changeDefaultAdminDelay(uint48 newDelay) external

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

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

The pendingDefaultAdminDelay's effect schedule is defined in a way that waiting until the schedule and then calling beginDefaultAdminTransfer with the new delay will take at least the same as another defaultAdmin 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 + newDelay capped by defaultAdminDelayIncreaseWait.

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

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

Requirements:

Emits a DefaultAdminDelayChangeScheduled event and may emit a DefaultAdminDelayChangeCanceled event.

rollbackDefaultAdminDelay() external

Cancels a scheduled defaultAdminDelay change.

Requirements:

May emit a DefaultAdminDelayChangeCanceled event.

defaultAdminDelayIncreaseWait() → uint48 external

Maximum time in seconds for an increase to defaultAdminDelay (that is scheduled using changeDefaultAdminDelay) to take effect. Default to 5 days.

When the defaultAdminDelay 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 overrode for a custom defaultAdminDelay 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).

DefaultAdminTransferScheduled(address indexed newAdmin, uint48 acceptSchedule) event

Emitted when a defaultAdmin transfer is started, setting newAdmin as the next address to become the defaultAdmin by calling acceptDefaultAdminTransfer only after acceptSchedule passes.

DefaultAdminTransferCanceled() event

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

DefaultAdminDelayChangeScheduled(uint48 newDelay, uint48 effectSchedule) event

Emitted when a defaultAdminDelay change is started, setting newDelay as the next delay to be applied between default admin transfer after effectSchedule has passed.

DefaultAdminDelayChangeCanceled() event

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

AccessControlDefaultAdminRules 

import "@openzeppelin/contracts/access/extensions/AccessControlDefaultAdminRules.sol";

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 changeDefaultAdminDelay.

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

Example usage:

contract MyToken is AccessControlDefaultAdminRules {
  constructor() AccessControlDefaultAdminRules(
    3 days,
    msg.sender // Explicit initial `DEFAULT_ADMIN_ROLE` holder
   ) {}
}
Functions
AccessControl
Events
IAccessControlDefaultAdminRules
IAccessControl

constructor(uint48 initialDelay, address initialDefaultAdmin) internal

Sets the initial values for defaultAdminDelay and defaultAdmin address.

supportsInterface(bytes4 interfaceId) → bool public

See IERC165.supportsInterface.

owner() → address public

See IERC5313.owner.

grantRole(bytes32 role, address account) public

See AccessControl.grantRole. Reverts for DEFAULT_ADMIN_ROLE.

revokeRole(bytes32 role, address account) public

See AccessControl.revokeRole. Reverts for DEFAULT_ADMIN_ROLE.

renounceRole(bytes32 role, address account) public

See AccessControl.renounceRole.

For the DEFAULT_ADMIN_ROLE, it only allows renouncing in two steps by first calling beginDefaultAdminTransfer to the address(0), so it’s required that the pendingDefaultAdmin schedule has also passed when calling this function.

After its execution, it will not be possible to call onlyRole(DEFAULT_ADMIN_ROLE) functions.

Renouncing DEFAULT_ADMIN_ROLE will leave the contract without a defaultAdmin, thereby disabling any functionality that is only available for it, and the possibility of reassigning a non-administrated role.

_grantRole(bytes32 role, address account) internal

See AccessControl._grantRole.

For DEFAULT_ADMIN_ROLE, it only allows granting if there isn’t already a defaultAdmin 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.

_revokeRole(bytes32 role, address account) internal

See AccessControl._revokeRole.

_setRoleAdmin(bytes32 role, bytes32 adminRole) internal

See AccessControl._setRoleAdmin. Reverts for DEFAULT_ADMIN_ROLE.

defaultAdmin() → address public

Returns the address of the current DEFAULT_ADMIN_ROLE holder.

pendingDefaultAdmin() → address newAdmin, uint48 schedule public

Returns a tuple of a newAdmin and an accept schedule.

After the schedule passes, the newAdmin will be able to accept the defaultAdmin role by calling acceptDefaultAdminTransfer, completing the role transfer.

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

A zero address newAdmin means that defaultAdmin is being renounced.

defaultAdminDelay() → uint48 public

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

This delay will be added to the current timestamp when calling beginDefaultAdminTransfer 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 changeDefaultAdminDelay.

pendingDefaultAdminDelay() → uint48 newDelay, uint48 schedule public

Returns a tuple of newDelay and an effect schedule.

After the schedule passes, the newDelay will get into effect immediately for every new defaultAdmin transfer started with beginDefaultAdminTransfer.

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

A zero value only for newDelay means that the next defaultAdminDelay will be zero after the effect schedule.

defaultAdminDelayIncreaseWait() → uint48 public

Maximum time in seconds for an increase to defaultAdminDelay (that is scheduled using changeDefaultAdminDelay) to take effect. Default to 5 days.

When the defaultAdminDelay 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 overrode for a custom defaultAdminDelay 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).

beginDefaultAdminTransfer(address newAdmin) public

Starts a defaultAdmin transfer by setting a pendingDefaultAdmin scheduled for acceptance after the current timestamp plus a defaultAdminDelay.

Requirements:

Emits a DefaultAdminRoleChangeStarted event.

_beginDefaultAdminTransfer(address newAdmin) internal

See beginDefaultAdminTransfer.

Internal function without access restriction.

cancelDefaultAdminTransfer() public

Cancels a defaultAdmin transfer previously started with beginDefaultAdminTransfer.

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

Requirements:

May emit a DefaultAdminTransferCanceled event.

_cancelDefaultAdminTransfer() internal

See cancelDefaultAdminTransfer.

Internal function without access restriction.

acceptDefaultAdminTransfer() public

Completes a defaultAdmin transfer previously started with beginDefaultAdminTransfer.

After calling the function:

  • DEFAULT_ADMIN_ROLE should be granted to the caller.

  • DEFAULT_ADMIN_ROLE should be revoked from the previous holder.

  • pendingDefaultAdmin should be reset to zero values.

Requirements:

_acceptDefaultAdminTransfer() internal

See acceptDefaultAdminTransfer.

Internal function without access restriction.

changeDefaultAdminDelay(uint48 newDelay) public

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

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

The pendingDefaultAdminDelay's effect schedule is defined in a way that waiting until the schedule and then calling beginDefaultAdminTransfer with the new delay will take at least the same as another defaultAdmin 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 + newDelay capped by defaultAdminDelayIncreaseWait.

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

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

Requirements:

Emits a DefaultAdminDelayChangeScheduled event and may emit a DefaultAdminDelayChangeCanceled event.

_changeDefaultAdminDelay(uint48 newDelay) internal

See changeDefaultAdminDelay.

Internal function without access restriction.

rollbackDefaultAdminDelay() public

Cancels a scheduled defaultAdminDelay change.

Requirements:

May emit a DefaultAdminDelayChangeCanceled event.

_rollbackDefaultAdminDelay() internal

See rollbackDefaultAdminDelay.

Internal function without access restriction.

_delayChangeWait(uint48 newDelay) → uint48 internal

Returns the amount of seconds to wait after the newDelay will become the new defaultAdminDelay.

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 defaultAdminDelayIncreaseWait.

← FAQ
Common (Tokens) →