NoBey/openzeppelin-contracts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
github-actions
2023-10-05 01:42:23 +00:00
parent 645e2a6c4a
commit 9efe429a18
25 changed files with 4256 additions and 1204 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/modules/api/examples/ERC20WithAutoMinerReward.sol Normal file
View File

@ -0,0 +1,22 @@
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
contract ERC20WithAutoMinerReward is ERC20 {
constructor() ERC20("Reward", "RWD") {
_mintMinerReward();
}
function _mintMinerReward() internal {
_mint(block.coinbase, 1000);
}
function _update(address from, address to, uint256 value) internal virtual override {
if (!(from == address(0) && to == block.coinbase)) {
_mintMinerReward();
}
super._update(from, to, value);
}
}

17
docs/modules/api/examples/MyContractOwnable.sol Normal file
View File

@ -0,0 +1,17 @@
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
contract MyContract is Ownable {
constructor(address initialOwner) Ownable(initialOwner) {}
function normalThing() public {
// anyone can call this normalThing()
}
function specialThing() public onlyOwner {
// only the owner can call specialThing()!
}
}

107
docs/modules/api/pages/access.adoc
View File

@ -170,6 +170,8 @@
:AccessControl-_setRoleAdmin: pass:normal[xref:access.adoc#AccessControl-_setRoleAdmin-bytes32-bytes32-[`AccessControl._setRoleAdmin`]]
:xref-IAuthority-canCall-address-address-bytes4-: xref:access.adoc#IAuthority-canCall-address-address-bytes4-
:AccessManaged: pass:normal[xref:access.adoc#AccessManaged[`AccessManaged`]]
:AccessManaged-restricted: pass:normal[xref:access.adoc#AccessManaged-restricted--[`AccessManaged.restricted`]]
:AccessManaged-authority: pass:normal[xref:access.adoc#AccessManaged-authority--[`AccessManaged.authority`]]
:IAuthority: pass:normal[xref:access.adoc#IAuthority[`IAuthority`]]
:Ownable: pass:normal[xref:access.adoc#Ownable[`Ownable`]]
:AccessManager: pass:normal[xref:access.adoc#AccessManager[`AccessManager`]]
@ -1922,23 +1924,32 @@ import "@openzeppelin/contracts/access/manager/AccessManager.sol";
AccessManager is a central contract to store the permissions of a system.
The smart contracts under the control of an AccessManager instance will have a set of "restricted" functions, and the
exact details of how access is restricted for each of those functions is configurable by the admins of the instance.
These restrictions are expressed in terms of "roles".
A smart contract under the control of an AccessManager instance is known as a target, and will inherit from the
{AccessManaged} contract, be connected to this contract as its manager and implement the {AccessManaged-restricted}
modifier on a set of functions selected to be permissioned. Note that any function without this setup won't be
effectively restricted.
An AccessManager instance will define a set of roles. Accounts can be added into any number of these roles. Each of
them defines a role, and may confer access to some of the restricted functions in the system, as configured by admins
through the use of {setFunctionAllowedRoles}.
The restriction rules for such functions are defined in terms of "roles" identified by an `uint64` and scoped
by target (`address`) and function selectors (`bytes4`). These roles are stored in this contract and can be
configured by admins (`ADMIN_ROLE` members) after a delay (see {getTargetAdminDelay}).
Note that a function in a target contract may become permissioned in this way only when: 1) said contract is
{AccessManaged} and is connected to this contract as its manager, and 2) said function is decorated with the
`restricted` modifier.
For each target contract, admins can configure the following without any delay:
There is a special role defined by default named "public" which all accounts automatically have.
* The target's {AccessManaged-authority} via {updateAuthority}.
* Close or open a target via {setTargetClosed} keeping the permissions intact.
* The roles that are allowed (or disallowed) to call a given function (identified by its selector) through {setTargetFunctionRole}.
In addition to the access rules defined by each target's functions being assigned to roles, then entire target can
be "closed". This "closed" mode is set/unset by the admin using {setTargetClosed} and can be used to lock a contract
while permissions are being (re-)configured.
By default every address is member of the `PUBLIC_ROLE` and every target function is restricted to the `ADMIN_ROLE` until configured otherwise.
Additionally, each role has the following configuration options restricted to this manager's admins:
* A role's admin role via {setRoleAdmin} who can grant or revoke roles.
* A role's guardian role via {setRoleGuardian} who's allowed to cancel operations.
* A delay in which a role takes effect after being granted through {setGrantDelay}.
* A delay of any target's admin action via {setTargetAdminDelay}.
* A role label for discoverability purposes with {labelRole}.
Any account can be added and removed into any number of these roles by using the {grantRole} and {revokeRole} functions
restricted to each role's admin (see {getRoleAdmin}).
Since all the permissions of the managed system can be modified by the admins of this instance, it is expected that
they will be highly secured (e.g., a multisig or a well-configured DAO).
@ -2085,27 +2096,34 @@ no restriction). Additionally, it returns the delay needed to perform the call i
& {execute} workflow.
This function is usually called by the targeted contract to control immediate execution of restricted functions.
Therefore we only return true is the call can be performed without any delay. If the call is subject to a delay,
then the function should return false, and the caller should schedule the operation for future execution.
Therefore we only return true if the call can be performed without any delay. If the call is subject to a
previously set delay (not zero), then the function should return false and the caller should schedule the operation
for future execution.
We may be able to hash the operation, and check if the call was scheduled, but we would not be able to cleanup
the schedule, leaving the possibility of multiple executions. Maybe this function should not be view?
If `immediate` is true, the delay can be disregarded and the operation can be immediately executed, otherwise
the operation can be executed if and only if delay is greater than 0.
NOTE: The IAuthority interface does not include the `uint32` delay. This is an extension of that interface that
is backward compatible. Some contracts may thus ignore the second return argument. In that case they will fail
to identify the indirect workflow, and will consider calls that require a delay to be forbidden.
NOTE: This function does not report the permissions of this manager itself. These are defined by the
{_canCallSelf} function instead.
[.contract-item]
[[AccessManager-expiration--]]
==== `[.contract-item-name]#++expiration++#++() → uint32++` [.item-kind]#public#
Expiration delay for scheduled proposals. Defaults to 1 week.
IMPORTANT: Avoid overriding the expiration with 0. Otherwise every contract proposal will be expired immediately,
disabling any scheduling usage.
[.contract-item]
[[AccessManager-minSetback--]]
==== `[.contract-item-name]#++minSetback++#++() → uint32++` [.item-kind]#public#
Minimum setback for all delay updates, with the exception of execution delays, which
Minimum setback for all delay updates, with the exception of execution delays. It
can be increased without setback (and in the event of an accidental increase can be reset
via {revokeRole}). Defaults to 5 days.
@ -2113,7 +2131,7 @@ via {revokeRole}). Defaults to 5 days.
[[AccessManager-isTargetClosed-address-]]
==== `[.contract-item-name]#++isTargetClosed++#++(address target) → bool++` [.item-kind]#public#
Get the mode under which a contract is operating.
Get whether the contract is closed disabling any access. Otherwise role permissions are applied.
[.contract-item]
[[AccessManager-getTargetFunctionRole-address-bytes4-]]
@ -2131,7 +2149,7 @@ Get the admin delay for a target contract. Changes to contract configuration are
[[AccessManager-getRoleAdmin-uint64-]]
==== `[.contract-item-name]#++getRoleAdmin++#++(uint64 roleId) → uint64++` [.item-kind]#public#
Get the id of the role that acts as an admin for given role.
Get the id of the role that acts as an admin for the given role.
The admin permission is required to grant the role, revoke the role and update the execution delay to execute
an operation that is restricted to this role.
@ -2148,9 +2166,10 @@ The guardian permission allows canceling operations that have been scheduled und
[[AccessManager-getRoleGrantDelay-uint64-]]
==== `[.contract-item-name]#++getRoleGrantDelay++#++(uint64 roleId) → uint32++` [.item-kind]#public#
Get the role current grant delay, that value may change at any point, without an event emitted, following
a call to {setGrantDelay}. Changes to this value, including effect timepoint are notified by the
{RoleGrantDelayChanged} event.
Get the role current grant delay.
Its value may change at any point without an event emitted following a call to {setGrantDelay}.
Changes to this value, including effect timepoint are notified in advance by the {RoleGrantDelayChanged} event.
[.contract-item]
[[AccessManager-getAccess-uint64-address-]]
@ -2170,8 +2189,8 @@ Returns:
[[AccessManager-hasRole-uint64-address-]]
==== `[.contract-item-name]#++hasRole++#++(uint64 roleId, address account) → bool isMember, uint32 executionDelay++` [.item-kind]#public#
Check if a given account currently had the permission level corresponding to a given role. Note that this
permission might be associated with a delay. {getAccess} can provide more details.
Check if a given account currently has the permission level corresponding to a given role. Note that this
permission might be associated with an execution delay. {getAccess} can provide more details.
[.contract-item]
[[AccessManager-labelRole-uint64-string-]]
@ -2179,6 +2198,10 @@ permission might be associated with a delay. {getAccess} can provide more detail
Give a label to a role, for improved role discoverabily by UIs.
Requirements:
- the caller must be a global admin
Emits a {RoleLabel} event.
[.contract-item]
@ -2189,19 +2212,20 @@ Add `account` to `roleId`, or change its execution delay.
This gives the account the authorization to call any function that is restricted to this role. An optional
execution delay (in seconds) can be set. If that delay is non 0, the user is required to schedule any operation
that is restricted to members this role. The user will only be able to execute the operation after the delay has
that is restricted to members of this role. The user will only be able to execute the operation after the delay has
passed, before it has expired. During this period, admin and guardians can cancel the operation (see {cancel}).
If the account has already been granted this role, the execution delay will be updated. This update is not
immediate and follows the delay rules. For example, If a user currently has a delay of 3 hours, and this is
immediate and follows the delay rules. For example, if a user currently has a delay of 3 hours, and this is
called to reduce that delay to 1 hour, the new delay will take some time to take effect, enforcing that any
operation executed in the 3 hours that follows this update was indeed scheduled before this update.
Requirements:
- the caller must be an admin for the role (see {getRoleAdmin})
- granted role must not be the `PUBLIC_ROLE`
Emits a {RoleGranted} event
Emits a {RoleGranted} event.
[.contract-item]
[[AccessManager-revokeRole-uint64-address-]]
@ -2213,6 +2237,7 @@ no effect.
Requirements:
- the caller must be an admin for the role (see {getRoleAdmin})
- revoked role must not be the `PUBLIC_ROLE`
Emits a {RoleRevoked} event if the account had the role.
@ -2220,8 +2245,8 @@ Emits a {RoleRevoked} event if the account had the role.
[[AccessManager-renounceRole-uint64-address-]]
==== `[.contract-item-name]#++renounceRole++#++(uint64 roleId, address callerConfirmation)++` [.item-kind]#public#
Renounce role permissions for the calling account, with immediate effect. If the sender is not in
the role, this call has no effect.
Renounce role permissions for the calling account with immediate effect. If the sender is not in
the role this call has no effect.
Requirements:
@ -2288,7 +2313,10 @@ Emits a {RoleRevoked} event if the account had the role.
Internal version of {setRoleAdmin} without access control.
Emits a {RoleAdminChanged} event
Emits a {RoleAdminChanged} event.
NOTE: Setting the admin role as the `PUBLIC_ROLE` is allowed, but it will effectively allow
anyone to set grant or revoke such role.
[.contract-item]
[[AccessManager-_setRoleGuardian-uint64-uint64-]]
@ -2296,7 +2324,10 @@ Emits a {RoleAdminChanged} event
Internal version of {setRoleGuardian} without access control.
Emits a {RoleGuardianChanged} event
Emits a {RoleGuardianChanged} event.
NOTE: Setting the guardian role as the `PUBLIC_ROLE` is allowed, but it will effectively allow
anyone to cancel any scheduled operation for such role.
[.contract-item]
[[AccessManager-_setGrantDelay-uint64-uint32-]]
@ -2304,7 +2335,7 @@ Emits a {RoleGuardianChanged} event
Internal version of {setGrantDelay} without access control.
Emits a {RoleGrantDelayChanged} event
Emits a {RoleGrantDelayChanged} event.
[.contract-item]
[[AccessManager-setTargetFunctionRole-address-bytes4---uint64-]]
@ -2322,9 +2353,9 @@ Emits a {TargetFunctionRoleUpdated} event per selector.
[[AccessManager-_setTargetFunctionRole-address-bytes4-uint64-]]
==== `[.contract-item-name]#++_setTargetFunctionRole++#++(address target, bytes4 selector, uint64 roleId)++` [.item-kind]#internal#
Internal version of {setFunctionAllowedRole} without access control.
Internal version of {setTargetFunctionRole} without access control.
Emits a {TargetFunctionRoleUpdated} event
Emits a {TargetFunctionRoleUpdated} event.
[.contract-item]
[[AccessManager-setTargetAdminDelay-address-uint32-]]
@ -2336,7 +2367,7 @@ Requirements:
- the caller must be a global admin
Emits a {TargetAdminDelayUpdated} event per selector
Emits a {TargetAdminDelayUpdated} event.
[.contract-item]
[[AccessManager-_setTargetAdminDelay-address-uint32-]]
@ -2344,7 +2375,7 @@ Emits a {TargetAdminDelayUpdated} event per selector
Internal version of {setTargetAdminDelay} without access control.
Emits a {TargetAdminDelayUpdated} event
Emits a {TargetAdminDelayUpdated} event.
[.contract-item]
[[AccessManager-setTargetClosed-address-bool-]]
@ -2420,7 +2451,7 @@ Consume a scheduled operation targeting the caller. If such an operation exists,
This is useful for contract that want to enforce that calls targeting them were scheduled on the manager,
with all the verifications that it implies.
Emit a {OperationExecuted} event
Emit a {OperationExecuted} event.
[.contract-item]
[[AccessManager-_consumeScheduledOp-bytes32-]]

3
docs/modules/api/pages/governance.adoc
View File

@ -937,6 +937,7 @@
:IGovernor-cancel: pass:normal[xref:governance.adoc#IGovernor-cancel-address---uint256---bytes---bytes32-[`IGovernor.cancel`]]
:ERC721Votes: pass:normal[xref:token/ERC721.adoc#ERC721Votes[`ERC721Votes`]]
:ERC721-balanceOf: pass:normal[xref:token/ERC721.adoc#ERC721-balanceOf-address-[`ERC721.balanceOf`]]
:ERC721-_update: pass:normal[xref:token/ERC721.adoc#ERC721-_update-address-uint256-address-[`ERC721._update`]]
:xref-Votes-clock--: xref:governance.adoc#Votes-clock--
:xref-Votes-CLOCK_MODE--: xref:governance.adoc#Votes-CLOCK_MODE--
:xref-Votes-getVotes-address-: xref:governance.adoc#Votes-getVotes-address-
@ -4517,7 +4518,7 @@ cost of this history tracking optional.
When using this module the derived contract must implement {_getVotingUnits} (for example, make it return
{ERC721-balanceOf}), and can use {_transferVotingUnits} to track a change in the distribution of those units (in the
previous example, it would be included in {ERC721-_beforeTokenTransfer}).
previous example, it would be included in {ERC721-_update}).
[.contract-index]
.Functions