Skip to content

Commit

Permalink
Completed docs
Browse files Browse the repository at this point in the history
  • Loading branch information
ernestognw committed Jan 28, 2023
1 parent 68adaf5 commit 0aff3ff
Show file tree
Hide file tree
Showing 4 changed files with 32 additions and 13 deletions.
2 changes: 1 addition & 1 deletion contracts/access/AccessControl.sol
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ import "../utils/introspection/ERC165.sol";
*
* WARNING: 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.
* accounts that have been granted it. See {AccessControlAdminRules}
*/
abstract contract AccessControl is Context, IAccessControl, ERC165 {
struct RoleData {
Expand Down
37 changes: 25 additions & 12 deletions contracts/access/AccessControlAdminRules.sol
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import "../utils/math/SafeCast.sol";

/**
* @dev Extension of {AccessControl} that allows to specify special rules to manage
* the `DEFAULT_ADMIN_ROLE`´s owner, which is a sensitive role with special permissions
* the `DEFAULT_ADMIN_ROLE` 's owner, which is a sensitive role with special permissions
* over other valid roles that may potentially have rights.
*
* If a specific role doesn't have an `adminRole` assigned, the holder of the
Expand All @@ -18,12 +18,26 @@ import "../utils/math/SafeCast.sol";
*
* This contract implements the following risk mitigations on top of the AccessControl implementation:
*
* - Only one account holds the `DEFAULT_ADMIN_ROLE` at every time after construction except when renounced.
* - Enforce a 2-step process to transfer the `DEFAULT_ADMIN_ROLE` to another account. Even when it's been renounced.
* - Enforce a configurable delay between the two steps, with the ability to cancel in between. Even after the timer has passed to avoid locking it forever.
* - The `DEFAULT_ADMIN_ROLE`'s admin can be only held by itself.
* * Only one account holds the `DEFAULT_ADMIN_ROLE` at every time after construction except when renounced.
* * Enforce a 2-step process to transfer the `DEFAULT_ADMIN_ROLE` to another account.
* - Even when it's been renounced.
* * Enforce a configurable delay between the two steps, with the ability to cancel in between.
* - Even after the timer has passed to avoid locking it forever.
* * The `DEFAULT_ADMIN_ROLE` 's admin can be only held by itself.
*
* NOTE: `delay` is only configurable in the constructor to avoid issues related with handling delay management during the transfer is pending to be completed.
* Once you understand what the {constructor} parameters, you can use this reference implementation:
*
* ```solidity
* contract MyToken is AccessControlAdminRules {
* constructor() AccessControlAdminRules(
* 60 * 60 * 24, // 3 days
* _msgSender() // Explicit initial `DEFAULT_ADMIN_ROLE` holder
* ) {}
*}
* ```
*
* NOTE: The `delay` is only configurable in the constructor to avoid issues related with handling
* delay management during the transfer is pending to be completed.
*
* _Available since v4.9._
*/
Expand All @@ -36,13 +50,12 @@ abstract contract AccessControlAdminRules is IAccessControlAdminRules, AccessCon
address private _pendingAdmin;

/**
* @dev Sets the values for {name} and {symbol}.
*
* All two of these values are immutable: they can only be set once during
* construction.
* @dev Sets the initial values the internal delay and {owner}.
*
* The `delay` value is immutable. It can only be set at the constructor.
*/
constructor(uint48 initialDelay, address initialAdmin) {
_delay = initialDelay;
constructor(uint48 delay, address initialAdmin) {
_delay = delay;
_grantRole(DEFAULT_ADMIN_ROLE, initialAdmin);
}

Expand Down
4 changes: 4 additions & 0 deletions contracts/access/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,7 @@ This directory provides ways to restrict who can access the functions of a contr
{{IAccessControlEnumerable}}

{{AccessControlEnumerable}}

{{IAccessControlAdminRules}}

{{AccessControlAdminRules}}
2 changes: 2 additions & 0 deletions docs/modules/ROOT/pages/access-control.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,8 @@ Every role has an associated admin role, which grants permission to call the `gr

This mechanism can be used to create complex permissioning structures resembling organizational charts, but it also provides an easy way to manage simpler applications. `AccessControl` includes a special role, called `DEFAULT_ADMIN_ROLE`, which acts as the **default admin role for all roles**. An account with this role will be able to manage any other role, unless `_setRoleAdmin` is used to select a new admin role.

NOTE: For risk mitigations related to `DEFAULT_ADMIN_ROLE` management. See xref:api:access.adoc#AccessControlAdminRules[`AccessControlAdminRules`] as an alternative with restrictions such as 2-step admin role change, single-holder enforcing and configurable minimum delay.

Let's take a look at the ERC20 token example, this time taking advantage of the default admin role:

[source,solidity]
Expand Down

0 comments on commit 0aff3ff

Please sign in to comment.