ERC-5982: Role-based Access Control

An interface for role-based access control for smart contracts.

Abstract

This EIP defines an interface for role-based access control for smart contracts. Roles are defined as byte32. The interface specifies how to read, grant, create, and destroy roles. It specifies the meaning of role power in terms of the ability to call a given method identified by a bytes4 method selector. It also specifies how metadata of roles are represented.

Motivation

There are many ways to establish access control for privileged actions. One common pattern is “role-based” access control, where one or more users are assigned to one or more “roles,” which grant access to privileged actions. This pattern is more secure and flexible than ownership-based access control since it allows for many people to be granted permissions according to the principle of least privilege.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.

The reference interfaces are described as follows:

interface IERC_ACL_CORE {
    function hasRole(bytes32 role, address account) external view returns (bool);
    function grantRole(bytes32 role, address account) external;
    function revokeRole(bytes32 role, address account) external;
}

interface IERC_ACL_GENERAL {
    event RoleGranted(address indexed grantor, bytes32 indexed role, address indexed grantee, bytes _data);
    event RoleRevoked(address indexed revoker, bytes32 indexed role, address indexed revokee, bytes _data);

    event RoleCreated(address indexed roleGrantor, bytes32 role, bytes32 adminOfRole, string name, string desc, string uri, bytes32 calldata _data);
    event RoleDestroyed(address indexed roleDestroyer, bytes32 role, bytes32 calldata _data);
    event RolePowerSet(address indexed rolePowerSetter, bytes32 role, bytes4 methods, bytes calldata _data);

    function grantRole(bytes32 role, address account, bytes calldata _data) external;
    function revokeRole(bytes32 role, address account, bytes calldata _data) external;

    function createRole(bytes32 role, bytes32 adminOfRole, string name, string desc, string uri, bytes32 calldata _data) external;
    function destroyRole(bytes32 role, bytes32 calldata _data) external;
    function setRolePower(bytes32 role, bytes4 methods, bytes calldata _data) view external returns(bool);

    function hasRole(bytes32 role, address account, bytes calldata _data) external view returns (bool);
    function canGrantRole(bytes32 grantor, bytes32 grantee, bytes calldata _data) view external returns(bool);
    function canRevokeRole(bytes32 revoker, bytes32 revokee, address account, bytes calldata _data) view external returns(bool);
    function canExecute(bytes32 executor, bytes4 methods, bytes32 calldata payload, bytes calldata _data) view external returns(bool);
}

interface IERC_ACL_METADATA {
    function roleName(bytes32) external view returns(string);
    function roleDescription(bytes32) external view returns(string);
    function roleURI(bytes32) external view returns(string);
}

1. Compliant contracts MUST implement IERC_ACL_CORE
2. It is RECOMMENDED for compliant contracts to implement the optional extension IERC_ACL_GENERAL.
3. Compliant contracts MAY implement the optional extension IERC_ACL_METADATA.
4. A role in a compliant smart contract is represented in the format of bytes32. It is RECOMMENDED that the value of such a role be computed as a keccak256 hash of the role name, in this format: bytes32 role = keccak256("<role_name>"), such as bytes32 role = keccak256("MINTER").
5. Compliant contracts SHOULD implement ERC-165 identifier.

Rationale

1. The names and parameters of methods in IERC_ACL_CORE are chosen to allow backward compatibility with OpenZeppelin’s implementation.
2. The methods in IERC_ACL_GENERAL conform to ERC-5750 to allow extension.
3. The renounceRole method was not adopted, and was consolidated into revokeRole to simplify the interface.

Backwards Compatibility

Needs discussion.

Security Considerations

Needs discussion.

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Zainan Victor Zhou (@xinbenlv), "ERC-5982: Role-based Access Control [DRAFT]," Ethereum Improvement Proposals, no. 5982, November 2022. Available: https://eips.ethereum.org/EIPS/eip-5982.