Skip to content

docs: fix TimelockController admin, add CANCELLER_ROLE, and DoS warning #143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vridhib wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: fix TimelockController admin, add CANCELLER_ROLE, and DoS warning #143

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions content/contracts/5.x/access-control.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,17 +102,20 @@ This is the issue the [`TimelockController`](/contracts/5.x/api/governance#Timel
The [`TimelockController`](/contracts/5.x/api/governance#TimelockController) is a proxy that is governed by proposers and executors. When set as the owner/admin/controller of a smart contract, it ensures that whichever maintenance operation is ordered by the proposers is subject to a delay. This delay protects the users of the smart contract by giving them time to review the maintenance operation and exit the system if they consider it is in their best interest to do so.

### Using `TimelockController`

By default, the address that deployed the [`TimelockController`](/contracts/5.x/api/governance#TimelockController) gets administration privileges over the timelock. This role grants the right to assign proposers, executors, and other administrators.
The address that deploys the [`TimelockController`](/contracts/5.x/api/governance#TimelockController) does not automatically receive administration privileges over the timelock. In order for the deployer address to acquire administrative privileges, you must pass the deployer address as the `admin` argument in the constructor. This role grants the right to assign proposers, executors, and other administrators.

The first step in configuring the [`TimelockController`](/contracts/5.x/api/governance#TimelockController) is to assign at least one proposer and one executor. These can be assigned during construction or later by anyone with the administrator role. These roles are not exclusive, meaning an account can have both roles.

Roles are managed using the [`AccessControl`](/contracts/5.x/api/access#AccessControl) interface and the `bytes32` values for each role are accessible through the `ADMIN_ROLE`, `PROPOSER_ROLE` and `EXECUTOR_ROLE` constants.
Roles are managed using the [`AccessControl`](/contracts/5.x/api/access#AccessControl) interface and the `bytes32` values for each role are accessible through the `ADMIN_ROLE`, `PROPOSER_ROLE`,`EXECUTOR_ROLE`, and `CANCELLER_ROLE` constants.

There is an additional feature built on top of `AccessControl`: giving the executor role to `address(0)` opens access to anyone to execute a proposal once the timelock has expired. This feature, while useful, should be used with caution.

At this point, with both a proposer and an executor assigned, the timelock can perform operations.

<Callout type='warn'>
The `CANCELLER_ROLE` is automatically granted to all addresses in the `proposers` array. This role can cancel any and all pending operations, and thus nullify the actions of the proposer and the executor. Note that a malicious or compromised canceller could effectively freeze the timelock by cancelling all pending operations, including operations that would revoke the canceller's own role. Teams and individuals using the `TimelockController` contract should always secure the canceller(s) with a multisig or DAO.
</Callout>

An optional next step is for the deployer to renounce its administrative privileges and leave the timelock self-administered. If the deployer decides to do so, all further maintenance, including assigning new proposers/schedulers or changing the timelock duration will have to follow the timelock workflow. This links the governance of the timelock to the governance of contracts attached to the timelock, and enforce a delay on timelock maintenance operations.

<Callout type='warn'>
Expand Down