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.
-
AccessControlprovides a general role based access control mechanism. Multiple hierarchical roles can be created and assigned each to multiple accounts. -
Ownableis 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.
Authorization
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.
By default, the owner account will be the one that deploys the contract. 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.
renounceOwnership() public
Leaves the contract without owner. It will not be possible to call
onlyOwner 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(address newOwner) public
Transfers ownership of the contract to a new account (newOwner).
Can only be called by the current owner.
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.
By default, the owner account will be the one that deploys the contract. This
can later be changed with transferOwnership and acceptOwnership.
This module is used through inheritance. It will make available all functions from parent (Ownable).
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.
IAccessControl
import "@openzeppelin/contracts/access/IAccessControl.sol";External interface of AccessControl declared to support ERC165 detection.
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 account) 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
account.
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.
Available since v3.1.
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.
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.
|
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})$/
Available since v4.1.
_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.
Available since v4.6.
_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 account) 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
account.
May emit a RoleRevoked event.
_setupRole(bytes32 role, address account) internal
Grants role to account.
If account had not been already granted role, emits a RoleGranted
event. Note that unlike grantRole, this function doesn’t perform any
checks on the calling account.
May emit a RoleGranted event.
|
This function should only be called from the constructor when setting up the initial roles for the system. Using this function in any other way is effectively circumventing the admin
system imposed by |
This function is deprecated in favor of _grantRole.
|
_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.
AccessControlCrossChain
import "@openzeppelin/contracts/access/AccessControlCrossChain.sol";An extension to AccessControl with support for cross-chain access management.
For each role, is extension implements an equivalent "aliased" role that is used for
restricting calls originating from other chains.
For example, if a function myFunction is protected by onlyRole(SOME_ROLE), and
if an address x has role SOME_ROLE, it would be able to call myFunction directly.
A wallet or contract at the same address on another chain would however not be able
to call this function. In order to do so, it would require to have the role
_crossChainRoleAlias(SOME_ROLE).
This aliasing is required to protect against multiple contracts living at the same address on different chains but controlled by conflicting entities.
Available since v4.6.
IAccessControlEnumerable
import "@openzeppelin/contracts/access/IAccessControlEnumerable.sol";External interface of AccessControlEnumerable declared to support ERC165 detection.
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/AccessControlEnumerable.sol";Extension of AccessControl that allows enumerating the members of each role.
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