You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CHANGELOG.md
+11Lines changed: 11 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -13,6 +13,17 @@
13
13
*`ERC721`: remove enumerability of tokens from the base implementation. This feature is now provided separately through the `ERC721Enumerable` extension. ([#2511](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2511))
14
14
*`AccessControl`: removed enumerability by default for a more lightweight contract. It is now opt-in through `AccessControlEnumerable`. ([#2512](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2512))
15
15
* Meta Transactions: add `ERC2771Context` and a `MinimalForwarder` for meta-transactions. ([#2508](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2508))
16
+
* Overall reorganisation of the contract folder to improve clarity and discoverability. ([#2503](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2503))
17
+
18
+
### How to upgrade from 3.x
19
+
20
+
Since this version has moved a few contracts to different directories, users upgrading from a previous version will need to adjust their import statements. To make this easier, the package includes a script that will migrate import statements automatically. After upgrading to the latest version of the package, run:
21
+
22
+
```
23
+
npx openzeppelin-contracts-migrate-imports
24
+
```
25
+
26
+
Make sure you're using git or another version control system to be able to recover from any potential error in our script.
Copy file name to clipboardExpand all lines: contracts/access/README.adoc
-86Lines changed: 0 additions & 86 deletions
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,6 @@ This directory provides ways to restrict who can access the functions of a contr
7
7
8
8
- {AccessControl} provides a general role based access control mechanism. Multiple hierarchical roles can be created and assigned each to multiple accounts.
9
9
- {Ownable} is 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.
10
-
- {TimelockController} is used in combination with one of the above two mechanisms. By assigning a role to an instance of the `TimelockController` contract, the access to the functions controlled by that role will be delayed by some amount of time.
11
10
12
11
== Authorization
13
12
@@ -16,88 +15,3 @@ This directory provides ways to restrict who can access the functions of a contr
16
15
{{AccessControl}}
17
16
18
17
{{AccessControlEnumerable}}
19
-
20
-
== Timelock
21
-
22
-
{{TimelockController}}
23
-
24
-
[[timelock-terminology]]
25
-
==== Terminology
26
-
27
-
* *Operation:* A transaction (or a set of transactions) that is the subject of the timelock. It has to be scheduled by a proposer and executed by an executor. The timelock enforces a minimum delay between the proposition and the execution (see xref:access-control.adoc#operation_lifecycle[operation lifecycle]). If the operation contains multiple transactions (batch mode), they are executed atomically. Operations are identified by the hash of their content.
28
-
* *Operation status:*
29
-
** *Unset:* An operation that is not part of the timelock mechanism.
30
-
** *Pending:* An operation that has been scheduled, before the timer expires.
31
-
** *Ready:* An operation that has been scheduled, after the timer expires.
32
-
** *Done:* An operation that has been executed.
33
-
* *Predecessor*: An (optional) dependency between operations. An operation can depend on another operation (its predecessor), forcing the execution order of these two operations.
34
-
* *Role*:
35
-
** *Proposer:* An address (smart contract or EOA) that is in charge of scheduling (and cancelling) operations.
36
-
** *Executor:* An address (smart contract or EOA) that is in charge of executing operations.
37
-
38
-
[[timelock-operation]]
39
-
==== Operation structure
40
-
41
-
Operation executed by the xref:api:access.adoc#TimelockController[`TimelockControler`] can contain one or multiple subsequent calls. Depending on whether you need to multiple calls to be executed atomically, you can either use simple or batched operations.
42
-
43
-
Both operations contain:
44
-
45
-
* *Target*, the address of the smart contract that the timelock should operate on.
46
-
* *Value*, in wei, that should be sent with the transaction. Most of the time this will be 0. Ether can be deposited before-end or passed along when executing the transaction.
47
-
* *Data*, containing the encoded function selector and parameters of the call. This can be produced using a number of tools. For example, a maintenance operation granting role `ROLE` to `ACCOUNT` can be encode using web3js as follows:
48
-
49
-
```javascript
50
-
const data = timelock.contract.methods.grantRole(ROLE, ACCOUNT).encodeABI()
51
-
```
52
-
53
-
* *Predecessor*, that specifies a dependency between operations. This dependency is optional. Use `bytes32(0)` if the operation does not have any dependency.
54
-
* *Salt*, used to disambiguate two otherwise identical operations. This can be any random value.
55
-
56
-
In the case of batched operations, `target`, `value` and `data` are specified as arrays, which must be of the same length.
57
-
58
-
[[timelock-operation-lifecycle]]
59
-
==== Operation lifecycle
60
-
61
-
Timelocked operations are identified by a unique id (their hash) and follow a specific lifecycle:
* By calling xref:api:access.adoc#TimelockController-schedule-address-uint256-bytes-bytes32-bytes32-uint256-[`schedule`] (or xref:api:access.adoc#TimelockController-scheduleBatch-address---uint256---bytes---bytes32-bytes32-uint256-[`scheduleBatch`]), a proposer moves the operation from the `Unset` to the `Pending` state. This starts a timer that must be longer than the minimum delay. The timer expires at a timestamp accessible through the xref:api:access.adoc#TimelockController-getTimestamp-bytes32-[`getTimestamp`] method.
66
-
* Once the timer expires, the operation automatically gets the `Ready` state. At this point, it can be executed.
67
-
* By calling xref:api:access.adoc#TimelockController-TimelockController-execute-address-uint256-bytes-bytes32-bytes32-[`execute`] (or xref:api:access.adoc#TimelockController-executeBatch-address---uint256---bytes---bytes32-bytes32-[`executeBatch`]), an executor triggers the operation's underlying transactions and moves it to the `Done` state. If the operation has a predecessor, it has to be in the `Done` state for this transition to succeed.
68
-
* xref:api:access.adoc#TimelockController-TimelockController-cancel-bytes32-[`cancel`] allows proposers to cancel any `Pending` operation. This resets the operation to the `Unset` state. It is thus possible for a proposer to re-schedule an operation that has been cancelled. In this case, the timer restarts when the operation is re-scheduled.
69
-
70
-
Operations status can be queried using the functions:
The admins are in charge of managing proposers and executors. For the timelock to be self-governed, this role should only be given to the timelock itself. Upon deployment, both the timelock and the deployer have this role. After further configuration and testing, the deployer can renounce this role such that all further maintenance operations have to go through the timelock process.
83
-
84
-
This role is identified by the *TIMELOCK_ADMIN_ROLE* value: `0x5f58e3a2316349923ce3780f8d587db2d72378aed66a8261c916544fa6846ca5`
85
-
86
-
[[timelock-proposer]]
87
-
===== Proposer
88
-
89
-
The proposers are in charge of scheduling (and cancelling) operations. This is a critical role, that should be given to governing entities. This could be an EOA, a multisig, or a DAO.
90
-
91
-
WARNING: *Proposer fight:* Having multiple proposers, while providing redundancy in case one becomes unavailable, can be dangerous. As proposer have their say on all operations, they could cancel operations they disagree with, including operations to remove them for the proposers.
92
-
93
-
This role is identified by the *PROPOSER_ROLE* value: `0xb09aa5aeb3702cfd50b6b62bc4532604938f21248a27a1d5ca736082b6819cc1`
94
-
95
-
[[timelock-executor]]
96
-
===== Executor
97
-
98
-
The executors are in charge of executing the operations scheduled by the proposers once the timelock expires. Logic dictates that multisig or DAO that are proposers should also be executors in order to guarantee operations that have been scheduled will eventually be executed. However, having additional executor can reduce the cost (the executing transaction does not require validation by the multisig or DAO that proposed it), while ensuring whoever is in charge of execution cannot trigger actions that have not been scheduled by the proposers.
99
-
100
-
This role is identified by the *EXECUTOR_ROLE* value: `0xd8aa0f3194971a2a116679f7c2090f6939c8d4e01a2a8d7e41d55e5351469e63`
101
-
102
-
103
-
WARNING: A live contract without at least one proposer and one executor is locked. Make sure these roles are filled by reliable entities before the deployer renounces its administrative rights in favour of the timelock contract itself. See the {AccessControl} documentation to learn more about role management.
NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/access
5
+
6
+
This directory includes primitives for on-chain governance. We currently only offer the {TimelockController} contract, that can be used as a component in a governance systems to introduce a delay between a proposal and its execution.
7
+
8
+
== Timelock
9
+
10
+
{{TimelockController}}
11
+
12
+
[[timelock-terminology]]
13
+
==== Terminology
14
+
15
+
* *Operation:* A transaction (or a set of transactions) that is the subject of the timelock. It has to be scheduled by a proposer and executed by an executor. The timelock enforces a minimum delay between the proposition and the execution (see xref:access-control.adoc#operation_lifecycle[operation lifecycle]). If the operation contains multiple transactions (batch mode), they are executed atomically. Operations are identified by the hash of their content.
16
+
* *Operation status:*
17
+
** *Unset:* An operation that is not part of the timelock mechanism.
18
+
** *Pending:* An operation that has been scheduled, before the timer expires.
19
+
** *Ready:* An operation that has been scheduled, after the timer expires.
20
+
** *Done:* An operation that has been executed.
21
+
* *Predecessor*: An (optional) dependency between operations. An operation can depend on another operation (its predecessor), forcing the execution order of these two operations.
22
+
* *Role*:
23
+
** *Proposer:* An address (smart contract or EOA) that is in charge of scheduling (and cancelling) operations.
24
+
** *Executor:* An address (smart contract or EOA) that is in charge of executing operations.
25
+
26
+
[[timelock-operation]]
27
+
==== Operation structure
28
+
29
+
Operation executed by the xref:api:access.adoc#TimelockController[`TimelockControler`] can contain one or multiple subsequent calls. Depending on whether you need to multiple calls to be executed atomically, you can either use simple or batched operations.
30
+
31
+
Both operations contain:
32
+
33
+
* *Target*, the address of the smart contract that the timelock should operate on.
34
+
* *Value*, in wei, that should be sent with the transaction. Most of the time this will be 0. Ether can be deposited before-end or passed along when executing the transaction.
35
+
* *Data*, containing the encoded function selector and parameters of the call. This can be produced using a number of tools. For example, a maintenance operation granting role `ROLE` to `ACCOUNT` can be encode using web3js as follows:
36
+
37
+
```javascript
38
+
const data = timelock.contract.methods.grantRole(ROLE, ACCOUNT).encodeABI()
39
+
```
40
+
41
+
* *Predecessor*, that specifies a dependency between operations. This dependency is optional. Use `bytes32(0)` if the operation does not have any dependency.
42
+
* *Salt*, used to disambiguate two otherwise identical operations. This can be any random value.
43
+
44
+
In the case of batched operations, `target`, `value` and `data` are specified as arrays, which must be of the same length.
45
+
46
+
[[timelock-operation-lifecycle]]
47
+
==== Operation lifecycle
48
+
49
+
Timelocked operations are identified by a unique id (their hash) and follow a specific lifecycle:
* By calling xref:api:access.adoc#TimelockController-schedule-address-uint256-bytes-bytes32-bytes32-uint256-[`schedule`] (or xref:api:access.adoc#TimelockController-scheduleBatch-address---uint256---bytes---bytes32-bytes32-uint256-[`scheduleBatch`]), a proposer moves the operation from the `Unset` to the `Pending` state. This starts a timer that must be longer than the minimum delay. The timer expires at a timestamp accessible through the xref:api:access.adoc#TimelockController-getTimestamp-bytes32-[`getTimestamp`] method.
54
+
* Once the timer expires, the operation automatically gets the `Ready` state. At this point, it can be executed.
55
+
* By calling xref:api:access.adoc#TimelockController-TimelockController-execute-address-uint256-bytes-bytes32-bytes32-[`execute`] (or xref:api:access.adoc#TimelockController-executeBatch-address---uint256---bytes---bytes32-bytes32-[`executeBatch`]), an executor triggers the operation's underlying transactions and moves it to the `Done` state. If the operation has a predecessor, it has to be in the `Done` state for this transition to succeed.
56
+
* xref:api:access.adoc#TimelockController-TimelockController-cancel-bytes32-[`cancel`] allows proposers to cancel any `Pending` operation. This resets the operation to the `Unset` state. It is thus possible for a proposer to re-schedule an operation that has been cancelled. In this case, the timer restarts when the operation is re-scheduled.
57
+
58
+
Operations status can be queried using the functions:
The admins are in charge of managing proposers and executors. For the timelock to be self-governed, this role should only be given to the timelock itself. Upon deployment, both the timelock and the deployer have this role. After further configuration and testing, the deployer can renounce this role such that all further maintenance operations have to go through the timelock process.
71
+
72
+
This role is identified by the *TIMELOCK_ADMIN_ROLE* value: `0x5f58e3a2316349923ce3780f8d587db2d72378aed66a8261c916544fa6846ca5`
73
+
74
+
[[timelock-proposer]]
75
+
===== Proposer
76
+
77
+
The proposers are in charge of scheduling (and cancelling) operations. This is a critical role, that should be given to governing entities. This could be an EOA, a multisig, or a DAO.
78
+
79
+
WARNING: *Proposer fight:* Having multiple proposers, while providing redundancy in case one becomes unavailable, can be dangerous. As proposer have their say on all operations, they could cancel operations they disagree with, including operations to remove them for the proposers.
80
+
81
+
This role is identified by the *PROPOSER_ROLE* value: `0xb09aa5aeb3702cfd50b6b62bc4532604938f21248a27a1d5ca736082b6819cc1`
82
+
83
+
[[timelock-executor]]
84
+
===== Executor
85
+
86
+
The executors are in charge of executing the operations scheduled by the proposers once the timelock expires. Logic dictates that multisig or DAO that are proposers should also be executors in order to guarantee operations that have been scheduled will eventually be executed. However, having additional executor can reduce the cost (the executing transaction does not require validation by the multisig or DAO that proposed it), while ensuring whoever is in charge of execution cannot trigger actions that have not been scheduled by the proposers.
87
+
88
+
This role is identified by the *EXECUTOR_ROLE* value: `0xd8aa0f3194971a2a116679f7c2090f6939c8d4e01a2a8d7e41d55e5351469e63`
89
+
90
+
91
+
WARNING: A live contract without at least one proposer and one executor is locked. Make sure these roles are filled by reliable entities before the deployer renounces its administrative rights in favour of the timelock contract itself. See the {AccessControl} documentation to learn more about role management.
0 commit comments