Access

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

This directory contains utility contracts to restrict access control in smart contracts. These include:

  • AccessManagerLight: A simpler version of an AccessManager that uses bytes8 roles to allow function calls identified by their 4-bytes selector.

  • AccessManagerWithRoleAccounts: An AccessManager extension that exposes a deterministic account (RoleAccount) for each role, so the current members of a role can produce signatures and execute calls on its behalf.

AccessManager

AccessManagerLight 

import "@openzeppelin/community-contracts/access/manager/AccessManagerLight.sol";

Light version of an AccessManager contract that defines bytes8 roles that are stored as requirements (see getRequirements) for each function.

Each requirement is a bitmask of roles that are allowed to call a function identified by its bytes4 selector. Users have their permissioned stored as a bitmask of roles they belong to.

The admin role is a special role that has access to all functions and can manage the roles of other users.

Modifiers

  • onlyRole(requirement)

Functions

  • constructor(admin)

  • canCall(caller, target, selector)

  • getGroups(user)

  • getGroupAdmins(group)

  • getRequirements(target, selector)

  • addGroup(user, group)

  • remGroup(user, group)

  • _addGroup(user, group)

  • _remGroup(user, group)

  • setGroupAdmins(group, admins)

  • _setGroupAdmins(group, admins)

  • setRequirements(target, selectors, groups)

  • _setRequirements(target, selector, groups)

  • ADMIN_ROLE()

  • PUBLIC_ROLE()

  • ADMIN_MASK()

  • PUBLIC_MASK()

Events

  • GroupAdded(user, group)

  • GroupRemoved(user, group)

  • GroupAdmins(group, admins)

  • RequirementsSet(target, selector, groups)

Errors

  • MissingPermissions(user, permissions, requirement)

onlyRole(Masks.Mask requirement) modifier

Throws if the specified requirement is not met by the caller’s permissions (see getGroups).

constructor(address admin) public

Initializes the contract with the admin as the first member of the admin group.

canCall(address caller, address target, bytes4 selector) → bool public

Returns whether the caller has the required permissions to call the target with the selector.

getGroups(address user) → Masks.Mask public

Returns the groups that the user belongs to.

getGroupAdmins(uint8 group) → Masks.Mask public

Returns the admins of the group.

getRequirements(address target, bytes4 selector) → Masks.Mask public

Returns the requirements for the target and selector.

addGroup(address user, uint8 group) public

Adds the user to the group. Emits GroupAdded event.

remGroup(address user, uint8 group) public

Removes the user from the group. Emits GroupRemoved event.

_addGroup(address user, uint8 group) internal

Internal version of addGroup without access control.

_remGroup(address user, uint8 group) internal

Internal version of remGroup without access control.

setGroupAdmins(uint8 group, uint8[] admins) public

Sets the admins of the group. Emits GroupAdmins event.

_setGroupAdmins(uint8 group, Masks.Mask admins) internal

Internal version of _setGroupAdmins without access control.

setRequirements(address target, bytes4[] selectors, uint8[] groups) public

Sets the groups requirements for the selectors of the target.

_setRequirements(address target, bytes4 selector, Masks.Mask groups) internal

Internal version of _setRequirements without access control.

ADMIN_ROLE() → uint8 public

PUBLIC_ROLE() → uint8 public

ADMIN_MASK() → Masks.Mask public

PUBLIC_MASK() → Masks.Mask public

GroupAdded(address indexed user, uint8 indexed group) event

GroupRemoved(address indexed user, uint8 indexed group) event

GroupAdmins(uint8 indexed group, Masks.Mask admins) event

RequirementsSet(address indexed target, bytes4 indexed selector, Masks.Mask groups) event

MissingPermissions(address user, Masks.Mask permissions, Masks.Mask requirement) error

AccessManagerWithRoleAccounts 

import "@openzeppelin/community-contracts/access/manager/AccessManagerWithRoleAccounts.sol";

Extension of {AccessManager} that exposes a deterministic RoleAccount for each role.

Every role managed by this instance has an associated RoleAccount deployed at an address derived deterministically from the role id. That account acts on behalf of the current members of the role: it can produce ERC-1271 signatures and execute batched calls, and its authority follows role membership as it is granted or revoked through the access manager.

The account address can be computed off-chain (or on-chain via getRoleAccount) before deployment, so it can be used as an authorization target or funded ahead of time. deployRoleAccount materializes the clone at that address when needed.

A role account grants control to every current member of its role. For the special PUBLIC_ROLE (type(uint64).max), which every address belongs to, this means the account is controllable by anyone.
deployRoleAccount is permissionless. Because the deployment is deterministic and behaviorally fixed, this is harmless (front-running it only produces the same account).
Functions

  • constructor(initialAdmin)

  • getRoleAccount(roleId)

  • deployRoleAccount(roleId)

  • _roleToSalt(roleId)

AccessManager

  • canCall(caller, target, selector)

  • expiration()

  • minSetback()

  • isTargetClosed(target)

  • getTargetFunctionRole(target, selector)

  • getTargetAdminDelay(target)

  • getRoleAdmin(roleId)

  • getRoleGuardian(roleId)

  • getRoleGrantDelay(roleId)

  • getAccess(roleId, account)

  • hasRole(roleId, account)

  • labelRole(roleId, label)

  • grantRole(roleId, account, executionDelay)

  • revokeRole(roleId, account)

  • renounceRole(roleId, callerConfirmation)

  • setRoleAdmin(roleId, admin)

  • setRoleGuardian(roleId, guardian)

  • setGrantDelay(roleId, newDelay)

  • _grantRole(roleId, account, grantDelay, executionDelay)

  • _revokeRole(roleId, account)

  • _setRoleAdmin(roleId, admin)

  • _setRoleGuardian(roleId, guardian)

  • _setGrantDelay(roleId, newDelay)

  • setTargetFunctionRole(target, selectors, roleId)

  • _setTargetFunctionRole(target, selector, roleId)

  • setTargetAdminDelay(target, newDelay)

  • _setTargetAdminDelay(target, newDelay)

  • setTargetClosed(target, closed)

  • _setTargetClosed(target, closed)

  • getSchedule(id)

  • getNonce(id)

  • schedule(target, data, when)

  • execute(target, data)

  • cancel(caller, target, data)

  • consumeScheduledOp(caller, data)

  • _consumeScheduledOp(operationId)

  • hashOperation(caller, target, data)

  • updateAuthority(target, newAuthority)

  • ADMIN_ROLE()

  • PUBLIC_ROLE()

Multicall

  • multicall(data)

Events
IAccessManager

  • OperationScheduled(operationId, nonce, schedule, caller, target, data)

  • OperationExecuted(operationId, nonce)

  • OperationCanceled(operationId, nonce)

  • RoleLabel(roleId, label)

  • RoleGranted(roleId, account, delay, since, newMember)

  • RoleRevoked(roleId, account)

  • RoleAdminChanged(roleId, admin)

  • RoleGuardianChanged(roleId, guardian)

  • RoleGrantDelayChanged(roleId, delay, since)

  • TargetClosed(target, closed)

  • TargetFunctionRoleUpdated(target, selector, roleId)

  • TargetAdminDelayUpdated(target, delay, since)

Errors
IAccessManager

  • AccessManagerAlreadyScheduled(operationId)

  • AccessManagerNotScheduled(operationId)

  • AccessManagerNotReady(operationId)

  • AccessManagerExpired(operationId)

  • AccessManagerLockedRole(roleId)

  • AccessManagerLockedFunction(selector)

  • AccessManagerBadConfirmation()

  • AccessManagerUnauthorizedAccount(msgsender, roleId)

  • AccessManagerUnauthorizedCall(caller, target, selector)

  • AccessManagerUnauthorizedConsume(target)

  • AccessManagerUnauthorizedCancel(msgsender, caller, target, selector)

  • AccessManagerInvalidInitialAdmin(initialAdmin)

constructor(address initialAdmin) public

getRoleAccount(uint64 roleId) → address public

Returns the deterministic address of the RoleAccount for roleId, whether or not it has already been deployed.

deployRoleAccount(uint64 roleId) → address public

Deploys the RoleAccount clone for roleId at its deterministic address and returns it. Reverts if the account for roleId has already been deployed.

_roleToSalt(uint64 roleId) → bytes32 internal

Derives the CREATE2 salt used to deploy the clone for roleId. Defaults to the role id itself.

← Utilities
Account →