diff --git a/contracts/access/README.adoc b/contracts/access/README.adoc index ba9c02faf..b89865b2c 100644 --- a/contracts/access/README.adoc +++ b/contracts/access/README.adoc @@ -5,7 +5,9 @@ NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/ This directory provides ways to restrict who can access the functions of a contract or when they can do it. -- {AccessControl} provides a general role based access control mechanism. Multiple hierarchical roles can be created and assigned each to multiple accounts. +- {AccessManager} is a full-fledged access control solution for smart contract systems. Allows creating and assigning multiple hierarchical roles with execution delays for each account across various contracts. +- {AccessManaged} delegates its access control to an authority that dictates the permissions of the managed contract. It's compatible with an AccessManager as an authority. +- {AccessControl} provides a per-contract role based access control mechanism. Multiple hierarchical roles can be created and assigned each to multiple accounts within the same instance. - {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. == Core diff --git a/contracts/governance/README.adoc b/contracts/governance/README.adoc index 5b38c4d53..8c368aca6 100644 --- a/contracts/governance/README.adoc +++ b/contracts/governance/README.adoc @@ -30,6 +30,8 @@ Counting modules determine valid voting options. Timelock extensions add a delay for governance decisions to be executed. The workflow is extended to require a `queue` step before execution. With these modules, proposals are executed by the external timelock contract, thus it is the timelock that has to hold the assets that are being governed. +* {GovernorTimelockAccess}: Connects with an instance of an {AccessManager}. This allows restrictions (and delays) enforced by the manager to be considered by the Governor and integrated into the AccessManager's "schedule + execute" workflow. + * {GovernorTimelockControl}: Connects with an instance of {TimelockController}. Allows multiple proposers and executors, in addition to the Governor itself. * {GovernorTimelockCompound}: Connects with an instance of Compound's https://github.com/compound-finance/compound-protocol/blob/master/contracts/Timelock.sol[`Timelock`] contract. @@ -66,6 +68,8 @@ NOTE: Functions of the `Governor` contract do not include access control. If you === Extensions +{{GovernorTimelockAccess}} + {{GovernorTimelockControl}} {{GovernorTimelockCompound}} diff --git a/contracts/metatx/README.adoc b/contracts/metatx/README.adoc index 9f25802e4..c02fb103d 100644 --- a/contracts/metatx/README.adoc +++ b/contracts/metatx/README.adoc @@ -3,6 +3,11 @@ [.readme-notice] NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/metatx +This directory includes contracts for adding meta-transaction capabilities (i.e. abstracting the execution context from the transaction origin) following the https://eips.ethereum.org/EIPS/eip-2771[ERC-2771 specification]. + +- {ERC2771Context}: Provides a mechanism to override the sender and calldata of the execution context (`msg.sender` and `msg.data`) with a custom value specified by a trusted forwarder. +- {ERC2771Forwarder}: A production-ready forwarder that relays operation requests signed off-chain by an EOA. + == Core {{ERC2771Context}} diff --git a/contracts/utils/README.adoc b/contracts/utils/README.adoc index d88b00199..089f2ef8b 100644 --- a/contracts/utils/README.adoc +++ b/contracts/utils/README.adoc @@ -5,14 +5,30 @@ NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/ Miscellaneous contracts and libraries containing utility functions you can use to improve security, work with new data types, or safely use low-level primitives. + * {Math}, {SignedMath}: Implementation of various arithmetic functions. + * {SafeCast}: Checked downcasting functions to avoid silent truncation. + * {ECDSA}, {MessageHashUtils}: Libraries for interacting with ECDSA signatures. + * {SignatureChecker}: A library helper to support regular ECDSA from EOAs as well as ERC-1271 signatures for smart contracts. + * {MerkleProof}: Functions for verifying https://en.wikipedia.org/wiki/Merkle_tree[Merkle Tree] proofs. + * {EIP712}: Contract with functions to allow processing signed typed structure data according to https://eips.ethereum.org/EIPS/eip-712[EIP-712]. * {ReentrancyGuard}: A modifier that can prevent reentrancy during certain functions. * {Pausable}: A common emergency response mechanism that can pause functionality while a remediation is pending. - * {SafeCast}: Checked downcasting functions to avoid silent truncation. - * {Math}, {SignedMath}: Implementation of various arithmetic functions. - * {Multicall}: Simple way to batch together multiple calls in a single external call. - * {Create2}: Wrapper around the https://blog.openzeppelin.com/getting-the-most-out-of-create2/[`CREATE2` EVM opcode] for safe use without having to deal with low-level assembly. + * {Nonces}: Utility for tracking and verifying address nonces that only increment. + * {ERC165, ERC165Checker}: Utilities for inspecting interfaces supported by contracts. + * {BitMaps}: A simple library to manage boolean value mapped to a numerical index in an efficient way. * {EnumerableMap}: A type like Solidity's https://solidity.readthedocs.io/en/latest/types.html#mapping-types[`mapping`], but with key-value _enumeration_: this will let you know how many entries a mapping has, and iterate over them (which is not possible with `mapping`). * {EnumerableSet}: Like {EnumerableMap}, but for https://en.wikipedia.org/wiki/Set_(abstract_data_type)[sets]. Can be used to store privileged accounts, issued IDs, etc. + * {DoubleEndedQueue}: An implementation of a https://en.wikipedia.org/wiki/Double-ended_queue[double ended queue] whose values can be removed added or remove from both sides. Useful for FIFO and LIFO structures. + * {Checkpoints}: A data structure to store values mapped to an strictly increasing key. Can be used for storing and accessing values over time. + * {Create2}: Wrapper around the https://blog.openzeppelin.com/getting-the-most-out-of-create2/[`CREATE2` EVM opcode] for safe use without having to deal with low-level assembly. + * {Address}: Collection of functions for overloading Solidity's https://docs.soliditylang.org/en/latest/types.html#address[`address`] type. + * {Arrays}: Collection of functions that operate on https://docs.soliditylang.org/en/latest/types.html#arrays[`arrays`]. + * {Base64}: On-chain base64 and base64URL encoding according to https://datatracker.ietf.org/doc/html/rfc4648[RFC-4648]. + * {Strings}: Common operations for strings formatting. + * {ShortString}: Library to encode (and decode) short strings into (or from) a single bytes32 slot for optimizing costs. Short strings are limited to 31 characters. + * {StorageSlot}: Methods for accessing specific storage slots formatted as common primitive types. + * {Multicall}: Abstract contract with an utility to allow batching together multiple calls in a single transaction. Useful for allowing EOAs to perform multiple operations at once. + * {Context}: An utility for abstracting the sender and calldata in the current execution context. [NOTE] ==== @@ -45,6 +61,8 @@ Because Solidity does not support generic types, {EnumerableMap} and {Enumerable {{Pausable}} +{{Nonces}} + == Introspection This set of interfaces and contracts deal with https://en.wikipedia.org/wiki/Type_introspection[type introspection] of contracts, that is, examining which functions can be called on them. This is usually referred to as a contract's _interface_. @@ -86,3 +104,5 @@ Ethereum contracts have no native concept of an interface, so applications must {{StorageSlot}} {{Multicall}} + +{{Context}} diff --git a/docs/modules/api/pages/access.adoc b/docs/modules/api/pages/access.adoc index 9637c51e1..bf6c8a2b6 100644 --- a/docs/modules/api/pages/access.adoc +++ b/docs/modules/api/pages/access.adoc @@ -1,4 +1,6 @@ :github-icon: pass:[] +:AccessManager: pass:normal[xref:access.adoc#AccessManager[`AccessManager`]] +:AccessManaged: pass:normal[xref:access.adoc#AccessManaged[`AccessManaged`]] :AccessControl: pass:normal[xref:access.adoc#AccessControl[`AccessControl`]] :Ownable: pass:normal[xref:access.adoc#Ownable[`Ownable`]] :xref-Ownable-onlyOwner--: xref:access.adoc#Ownable-onlyOwner-- @@ -332,7 +334,9 @@ NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/ This directory provides ways to restrict who can access the functions of a contract or when they can do it. -- {AccessControl} provides a general role based access control mechanism. Multiple hierarchical roles can be created and assigned each to multiple accounts. +- {AccessManager} is a full-fledged access control solution for smart contract systems. Allows creating and assigning multiple hierarchical roles with execution delays for each account across various contracts. +- {AccessManaged} delegates its access control to an authority that dictates the permissions of the managed contract. It's compatible with an AccessManager as an authority. +- {AccessControl} provides a per-contract role based access control mechanism. Multiple hierarchical roles can be created and assigned each to multiple accounts within the same instance. - {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. == Core diff --git a/docs/modules/api/pages/governance.adoc b/docs/modules/api/pages/governance.adoc index a47cf48ce..c015bb2c5 100644 --- a/docs/modules/api/pages/governance.adoc +++ b/docs/modules/api/pages/governance.adoc @@ -5,6 +5,8 @@ :ERC721Votes: pass:normal[xref:token/ERC721.adoc#ERC721Votes[`ERC721Votes`]] :GovernorVotesQuorumFraction: pass:normal[xref:governance.adoc#GovernorVotesQuorumFraction[`GovernorVotesQuorumFraction`]] :GovernorCountingSimple: pass:normal[xref:governance.adoc#GovernorCountingSimple[`GovernorCountingSimple`]] +:GovernorTimelockAccess: pass:normal[xref:governance.adoc#GovernorTimelockAccess[`GovernorTimelockAccess`]] +:AccessManager: pass:normal[xref:access.adoc#AccessManager[`AccessManager`]] :GovernorTimelockControl: pass:normal[xref:governance.adoc#GovernorTimelockControl[`GovernorTimelockControl`]] :TimelockController: pass:normal[xref:governance.adoc#TimelockController[`TimelockController`]] :GovernorTimelockCompound: pass:normal[xref:governance.adoc#GovernorTimelockCompound[`GovernorTimelockCompound`]] @@ -458,6 +460,115 @@ :xref-IGovernor-GovernorInvalidSignature-address-: xref:governance.adoc#IGovernor-GovernorInvalidSignature-address- :xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- :Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:AccessManager: pass:normal[xref:access.adoc#AccessManager[`AccessManager`]] +:GovernorTimelockControl: pass:normal[xref:governance.adoc#GovernorTimelockControl[`GovernorTimelockControl`]] +:GovernorTimelockCompound: pass:normal[xref:governance.adoc#GovernorTimelockCompound[`GovernorTimelockCompound`]] +:AccessManager-execute: pass:normal[xref:access.adoc#AccessManager-execute-address-bytes-[`AccessManager.execute`]] +:xref-GovernorTimelockAccess-constructor-address-uint32-: xref:governance.adoc#GovernorTimelockAccess-constructor-address-uint32- +:xref-GovernorTimelockAccess-accessManager--: xref:governance.adoc#GovernorTimelockAccess-accessManager-- +:xref-GovernorTimelockAccess-baseDelaySeconds--: xref:governance.adoc#GovernorTimelockAccess-baseDelaySeconds-- +:xref-GovernorTimelockAccess-setBaseDelaySeconds-uint32-: xref:governance.adoc#GovernorTimelockAccess-setBaseDelaySeconds-uint32- +:xref-GovernorTimelockAccess-_setBaseDelaySeconds-uint32-: xref:governance.adoc#GovernorTimelockAccess-_setBaseDelaySeconds-uint32- +:xref-GovernorTimelockAccess-isAccessManagerIgnored-address-bytes4-: xref:governance.adoc#GovernorTimelockAccess-isAccessManagerIgnored-address-bytes4- +:xref-GovernorTimelockAccess-setAccessManagerIgnored-address-bytes4---bool-: xref:governance.adoc#GovernorTimelockAccess-setAccessManagerIgnored-address-bytes4---bool- +:xref-GovernorTimelockAccess-_setAccessManagerIgnored-address-bytes4-bool-: xref:governance.adoc#GovernorTimelockAccess-_setAccessManagerIgnored-address-bytes4-bool- +:xref-GovernorTimelockAccess-proposalExecutionPlan-uint256-: xref:governance.adoc#GovernorTimelockAccess-proposalExecutionPlan-uint256- +:xref-GovernorTimelockAccess-proposalNeedsQueuing-uint256-: xref:governance.adoc#GovernorTimelockAccess-proposalNeedsQueuing-uint256- +:xref-GovernorTimelockAccess-propose-address---uint256---bytes---string-: xref:governance.adoc#GovernorTimelockAccess-propose-address---uint256---bytes---string- +:xref-GovernorTimelockAccess-_queueOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#GovernorTimelockAccess-_queueOperations-uint256-address---uint256---bytes---bytes32- +:xref-GovernorTimelockAccess-_executeOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#GovernorTimelockAccess-_executeOperations-uint256-address---uint256---bytes---bytes32- +:xref-GovernorTimelockAccess-_cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#GovernorTimelockAccess-_cancel-address---uint256---bytes---bytes32- +:xref-Governor-receive--: xref:governance.adoc#Governor-receive-- +:xref-Governor-supportsInterface-bytes4-: xref:governance.adoc#Governor-supportsInterface-bytes4- +:xref-Governor-name--: xref:governance.adoc#Governor-name-- +:xref-Governor-version--: xref:governance.adoc#Governor-version-- +:xref-Governor-hashProposal-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-hashProposal-address---uint256---bytes---bytes32- +:xref-Governor-state-uint256-: xref:governance.adoc#Governor-state-uint256- +:xref-Governor-proposalThreshold--: xref:governance.adoc#Governor-proposalThreshold-- +:xref-Governor-proposalSnapshot-uint256-: xref:governance.adoc#Governor-proposalSnapshot-uint256- +:xref-Governor-proposalDeadline-uint256-: xref:governance.adoc#Governor-proposalDeadline-uint256- +:xref-Governor-proposalProposer-uint256-: xref:governance.adoc#Governor-proposalProposer-uint256- +:xref-Governor-proposalEta-uint256-: xref:governance.adoc#Governor-proposalEta-uint256- +:xref-Governor-_checkGovernance--: xref:governance.adoc#Governor-_checkGovernance-- +:xref-Governor-_quorumReached-uint256-: xref:governance.adoc#Governor-_quorumReached-uint256- +:xref-Governor-_voteSucceeded-uint256-: xref:governance.adoc#Governor-_voteSucceeded-uint256- +:xref-Governor-_getVotes-address-uint256-bytes-: xref:governance.adoc#Governor-_getVotes-address-uint256-bytes- +:xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-: xref:governance.adoc#Governor-_countVote-uint256-address-uint8-uint256-bytes- +:xref-Governor-_defaultParams--: xref:governance.adoc#Governor-_defaultParams-- +:xref-Governor-_propose-address---uint256---bytes---string-address-: xref:governance.adoc#Governor-_propose-address---uint256---bytes---string-address- +:xref-Governor-queue-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-queue-address---uint256---bytes---bytes32- +:xref-Governor-execute-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-execute-address---uint256---bytes---bytes32- +:xref-Governor-cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-cancel-address---uint256---bytes---bytes32- +:xref-Governor-getVotes-address-uint256-: xref:governance.adoc#Governor-getVotes-address-uint256- +:xref-Governor-getVotesWithParams-address-uint256-bytes-: xref:governance.adoc#Governor-getVotesWithParams-address-uint256-bytes- +:xref-Governor-castVote-uint256-uint8-: xref:governance.adoc#Governor-castVote-uint256-uint8- +:xref-Governor-castVoteWithReason-uint256-uint8-string-: xref:governance.adoc#Governor-castVoteWithReason-uint256-uint8-string- +:xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes- +:xref-Governor-castVoteBySig-uint256-uint8-address-bytes-: xref:governance.adoc#Governor-castVoteBySig-uint256-uint8-address-bytes- +:xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes- +:xref-Governor-_castVote-uint256-address-uint8-string-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string- +:xref-Governor-_castVote-uint256-address-uint8-string-bytes-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string-bytes- +:xref-Governor-relay-address-uint256-bytes-: xref:governance.adoc#Governor-relay-address-uint256-bytes- +:xref-Governor-_executor--: xref:governance.adoc#Governor-_executor-- +:xref-Governor-onERC721Received-address-address-uint256-bytes-: xref:governance.adoc#Governor-onERC721Received-address-address-uint256-bytes- +:xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-: xref:governance.adoc#Governor-onERC1155Received-address-address-uint256-uint256-bytes- +:xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-: xref:governance.adoc#Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes- +:xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-: xref:governance.adoc#Governor-_encodeStateBitmap-enum-IGovernor-ProposalState- +:xref-Governor-_isValidDescriptionForProposer-address-string-: xref:governance.adoc#Governor-_isValidDescriptionForProposer-address-string- +:xref-Governor-clock--: xref:governance.adoc#Governor-clock-- +:xref-Governor-CLOCK_MODE--: xref:governance.adoc#Governor-CLOCK_MODE-- +:xref-Governor-votingDelay--: xref:governance.adoc#Governor-votingDelay-- +:xref-Governor-votingPeriod--: xref:governance.adoc#Governor-votingPeriod-- +:xref-Governor-quorum-uint256-: xref:governance.adoc#Governor-quorum-uint256- +:xref-Governor-BALLOT_TYPEHASH-bytes32: xref:governance.adoc#Governor-BALLOT_TYPEHASH-bytes32 +:xref-Governor-EXTENDED_BALLOT_TYPEHASH-bytes32: xref:governance.adoc#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32 +:xref-IGovernor-COUNTING_MODE--: xref:governance.adoc#IGovernor-COUNTING_MODE-- +:xref-IGovernor-hasVoted-uint256-address-: xref:governance.adoc#IGovernor-hasVoted-uint256-address- +:xref-Nonces-nonces-address-: xref:utils.adoc#Nonces-nonces-address- +:xref-Nonces-_useNonce-address-: xref:utils.adoc#Nonces-_useNonce-address- +:xref-Nonces-_useCheckedNonce-address-uint256-: xref:utils.adoc#Nonces-_useCheckedNonce-address-uint256- +:xref-EIP712-_domainSeparatorV4--: xref:utils.adoc#EIP712-_domainSeparatorV4-- +:xref-EIP712-_hashTypedDataV4-bytes32-: xref:utils.adoc#EIP712-_hashTypedDataV4-bytes32- +:xref-EIP712-eip712Domain--: xref:utils.adoc#EIP712-eip712Domain-- +:xref-EIP712-_EIP712Name--: xref:utils.adoc#EIP712-_EIP712Name-- +:xref-EIP712-_EIP712Version--: xref:utils.adoc#EIP712-_EIP712Version-- +:xref-GovernorTimelockAccess-BaseDelaySet-uint32-uint32-: xref:governance.adoc#GovernorTimelockAccess-BaseDelaySet-uint32-uint32- +:xref-GovernorTimelockAccess-AccessManagerIgnoredSet-address-bytes4-bool-: xref:governance.adoc#GovernorTimelockAccess-AccessManagerIgnoredSet-address-bytes4-bool- +:xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-: xref:governance.adoc#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string- +:xref-IGovernor-ProposalQueued-uint256-uint256-: xref:governance.adoc#IGovernor-ProposalQueued-uint256-uint256- +:xref-IGovernor-ProposalExecuted-uint256-: xref:governance.adoc#IGovernor-ProposalExecuted-uint256- +:xref-IGovernor-ProposalCanceled-uint256-: xref:governance.adoc#IGovernor-ProposalCanceled-uint256- +:xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-: xref:governance.adoc#IGovernor-VoteCast-address-uint256-uint8-uint256-string- +:xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-: xref:governance.adoc#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:xref-GovernorTimelockAccess-GovernorUnmetDelay-uint256-uint256-: xref:governance.adoc#GovernorTimelockAccess-GovernorUnmetDelay-uint256-uint256- +:xref-GovernorTimelockAccess-GovernorMismatchedNonce-uint256-uint256-uint256-: xref:governance.adoc#GovernorTimelockAccess-GovernorMismatchedNonce-uint256-uint256-uint256- +:xref-GovernorTimelockAccess-GovernorLockedIgnore--: xref:governance.adoc#GovernorTimelockAccess-GovernorLockedIgnore-- +:xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256- +:xref-IGovernor-GovernorAlreadyCastVote-address-: xref:governance.adoc#IGovernor-GovernorAlreadyCastVote-address- +:xref-IGovernor-GovernorDisabledDeposit--: xref:governance.adoc#IGovernor-GovernorDisabledDeposit-- +:xref-IGovernor-GovernorOnlyProposer-address-: xref:governance.adoc#IGovernor-GovernorOnlyProposer-address- +:xref-IGovernor-GovernorOnlyExecutor-address-: xref:governance.adoc#IGovernor-GovernorOnlyExecutor-address- +:xref-IGovernor-GovernorNonexistentProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNonexistentProposal-uint256- +:xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-: xref:governance.adoc#IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32- +:xref-IGovernor-GovernorInvalidVotingPeriod-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidVotingPeriod-uint256- +:xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256- +:xref-IGovernor-GovernorRestrictedProposer-address-: xref:governance.adoc#IGovernor-GovernorRestrictedProposer-address- +:xref-IGovernor-GovernorInvalidVoteType--: xref:governance.adoc#IGovernor-GovernorInvalidVoteType-- +:xref-IGovernor-GovernorQueueNotImplemented--: xref:governance.adoc#IGovernor-GovernorQueueNotImplemented-- +:xref-IGovernor-GovernorNotQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNotQueuedProposal-uint256- +:xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorAlreadyQueuedProposal-uint256- +:xref-IGovernor-GovernorInvalidSignature-address-: xref:governance.adoc#IGovernor-GovernorInvalidSignature-address- +:xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- +:AccessManager: pass:normal[xref:access.adoc#AccessManager[`AccessManager`]] +:AccessManager: pass:normal[xref:access.adoc#AccessManager[`AccessManager`]] +:AccessManager: pass:normal[xref:access.adoc#AccessManager[`AccessManager`]] +:AccessManager: pass:normal[xref:access.adoc#AccessManager[`AccessManager`]] +:AccessManager: pass:normal[xref:access.adoc#AccessManager[`AccessManager`]] +:IGovernor-proposalNeedsQueuing: pass:normal[xref:governance.adoc#IGovernor-proposalNeedsQueuing-uint256-[`IGovernor.proposalNeedsQueuing`]] +:IGovernor-propose: pass:normal[xref:governance.adoc#IGovernor-propose-address---uint256---bytes---string-[`IGovernor.propose`]] +:AccessManager-execute: pass:normal[xref:access.adoc#AccessManager-execute-address-bytes-[`AccessManager.execute`]] +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] :TimelockController: pass:normal[xref:governance.adoc#TimelockController[`TimelockController`]] :TimelockController: pass:normal[xref:governance.adoc#TimelockController[`TimelockController`]] :Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] @@ -1059,6 +1170,8 @@ Counting modules determine valid voting options. Timelock extensions add a delay for governance decisions to be executed. The workflow is extended to require a `queue` step before execution. With these modules, proposals are executed by the external timelock contract, thus it is the timelock that has to hold the assets that are being governed. +* {GovernorTimelockAccess}: Connects with an instance of an {AccessManager}. This allows restrictions (and delays) enforced by the manager to be considered by the Governor and integrated into the AccessManager's "schedule + execute" workflow. + * {GovernorTimelockControl}: Connects with an instance of {TimelockController}. Allows multiple proposers and executors, in addition to the Governor itself. * {GovernorTimelockCompound}: Connects with an instance of Compound's https://github.com/compound-finance/compound-protocol/blob/master/contracts/Timelock.sol[`Timelock`] contract. @@ -3021,6 +3134,382 @@ The quorum set is not a valid fraction. === Extensions +:ExecutionPlan: pass:normal[xref:#GovernorTimelockAccess-ExecutionPlan[`++ExecutionPlan++`]] +:GovernorUnmetDelay: pass:normal[xref:#GovernorTimelockAccess-GovernorUnmetDelay-uint256-uint256-[`++GovernorUnmetDelay++`]] +:GovernorMismatchedNonce: pass:normal[xref:#GovernorTimelockAccess-GovernorMismatchedNonce-uint256-uint256-uint256-[`++GovernorMismatchedNonce++`]] +:GovernorLockedIgnore: pass:normal[xref:#GovernorTimelockAccess-GovernorLockedIgnore--[`++GovernorLockedIgnore++`]] +:BaseDelaySet: pass:normal[xref:#GovernorTimelockAccess-BaseDelaySet-uint32-uint32-[`++BaseDelaySet++`]] +:AccessManagerIgnoredSet: pass:normal[xref:#GovernorTimelockAccess-AccessManagerIgnoredSet-address-bytes4-bool-[`++AccessManagerIgnoredSet++`]] +:constructor: pass:normal[xref:#GovernorTimelockAccess-constructor-address-uint32-[`++constructor++`]] +:accessManager: pass:normal[xref:#GovernorTimelockAccess-accessManager--[`++accessManager++`]] +:baseDelaySeconds: pass:normal[xref:#GovernorTimelockAccess-baseDelaySeconds--[`++baseDelaySeconds++`]] +:setBaseDelaySeconds: pass:normal[xref:#GovernorTimelockAccess-setBaseDelaySeconds-uint32-[`++setBaseDelaySeconds++`]] +:_setBaseDelaySeconds: pass:normal[xref:#GovernorTimelockAccess-_setBaseDelaySeconds-uint32-[`++_setBaseDelaySeconds++`]] +:isAccessManagerIgnored: pass:normal[xref:#GovernorTimelockAccess-isAccessManagerIgnored-address-bytes4-[`++isAccessManagerIgnored++`]] +:setAccessManagerIgnored: pass:normal[xref:#GovernorTimelockAccess-setAccessManagerIgnored-address-bytes4---bool-[`++setAccessManagerIgnored++`]] +:_setAccessManagerIgnored: pass:normal[xref:#GovernorTimelockAccess-_setAccessManagerIgnored-address-bytes4-bool-[`++_setAccessManagerIgnored++`]] +:proposalExecutionPlan: pass:normal[xref:#GovernorTimelockAccess-proposalExecutionPlan-uint256-[`++proposalExecutionPlan++`]] +:proposalNeedsQueuing: pass:normal[xref:#GovernorTimelockAccess-proposalNeedsQueuing-uint256-[`++proposalNeedsQueuing++`]] +:propose: pass:normal[xref:#GovernorTimelockAccess-propose-address---uint256---bytes---string-[`++propose++`]] +:_queueOperations: pass:normal[xref:#GovernorTimelockAccess-_queueOperations-uint256-address---uint256---bytes---bytes32-[`++_queueOperations++`]] +:_executeOperations: pass:normal[xref:#GovernorTimelockAccess-_executeOperations-uint256-address---uint256---bytes---bytes32-[`++_executeOperations++`]] +:_cancel: pass:normal[xref:#GovernorTimelockAccess-_cancel-address---uint256---bytes---bytes32-[`++_cancel++`]] + +[.contract] +[[GovernorTimelockAccess]] +=== `++GovernorTimelockAccess++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.1/contracts/governance/extensions/GovernorTimelockAccess.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/governance/extensions/GovernorTimelockAccess.sol"; +``` + +This module connects a {Governor} instance to an {AccessManager} instance, allowing the governor to make calls +that are delay-restricted by the manager using the normal {queue} workflow. An optional base delay is applied to +operations that are not delayed externally by the manager. Execution of a proposal will be delayed as much as +necessary to meet the required delays of all of its operations. + +This extension allows the governor to hold and use its own assets and permissions, unlike {GovernorTimelockControl} +and {GovernorTimelockCompound}, where the timelock is a separate contract that must be the one to hold assets and +permissions. Operations that are delay-restricted by the manager, however, will be executed through the +{AccessManager-execute} function. + +==== Security Considerations + +Some operations may be cancelable in the `AccessManager` by the admin or a set of guardians, depending on the +restricted function being invoked. Since proposals are atomic, the cancellation by a guardian of a single operation +in a proposal will cause all of the proposal to become unable to execute. Consider proposing cancellable operations +separately. + +By default, function calls will be routed through the associated `AccessManager` whenever it claims the target +function to be restricted by it. However, admins may configure the manager to make that claim for functions that a +governor would want to call directly (e.g., token transfers) in an attempt to deny it access to those functions. To +mitigate this attack vector, the governor is able to ignore the restrictions claimed by the `AccessManager` using +{setAccessManagerIgnored}. While permanent denial of service is mitigated, temporary DoS may still be technically +possible. All of the governor's own functions (e.g., {setBaseDelaySeconds}) ignore the `AccessManager` by default. + +[.contract-index] +.Functions +-- +* {xref-GovernorTimelockAccess-constructor-address-uint32-}[`++constructor(manager, initialBaseDelay)++`] +* {xref-GovernorTimelockAccess-accessManager--}[`++accessManager()++`] +* {xref-GovernorTimelockAccess-baseDelaySeconds--}[`++baseDelaySeconds()++`] +* {xref-GovernorTimelockAccess-setBaseDelaySeconds-uint32-}[`++setBaseDelaySeconds(newBaseDelay)++`] +* {xref-GovernorTimelockAccess-_setBaseDelaySeconds-uint32-}[`++_setBaseDelaySeconds(newBaseDelay)++`] +* {xref-GovernorTimelockAccess-isAccessManagerIgnored-address-bytes4-}[`++isAccessManagerIgnored(target, selector)++`] +* {xref-GovernorTimelockAccess-setAccessManagerIgnored-address-bytes4---bool-}[`++setAccessManagerIgnored(target, selectors, ignored)++`] +* {xref-GovernorTimelockAccess-_setAccessManagerIgnored-address-bytes4-bool-}[`++_setAccessManagerIgnored(target, selector, ignored)++`] +* {xref-GovernorTimelockAccess-proposalExecutionPlan-uint256-}[`++proposalExecutionPlan(proposalId)++`] +* {xref-GovernorTimelockAccess-proposalNeedsQueuing-uint256-}[`++proposalNeedsQueuing(proposalId)++`] +* {xref-GovernorTimelockAccess-propose-address---uint256---bytes---string-}[`++propose(targets, values, calldatas, description)++`] +* {xref-GovernorTimelockAccess-_queueOperations-uint256-address---uint256---bytes---bytes32-}[`++_queueOperations(proposalId, targets, , calldatas, )++`] +* {xref-GovernorTimelockAccess-_executeOperations-uint256-address---uint256---bytes---bytes32-}[`++_executeOperations(proposalId, targets, values, calldatas, )++`] +* {xref-GovernorTimelockAccess-_cancel-address---uint256---bytes---bytes32-}[`++_cancel(targets, values, calldatas, descriptionHash)++`] + +[.contract-subindex-inherited] +.Governor +* {xref-Governor-receive--}[`++receive()++`] +* {xref-Governor-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-Governor-name--}[`++name()++`] +* {xref-Governor-version--}[`++version()++`] +* {xref-Governor-hashProposal-address---uint256---bytes---bytes32-}[`++hashProposal(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-state-uint256-}[`++state(proposalId)++`] +* {xref-Governor-proposalThreshold--}[`++proposalThreshold()++`] +* {xref-Governor-proposalSnapshot-uint256-}[`++proposalSnapshot(proposalId)++`] +* {xref-Governor-proposalDeadline-uint256-}[`++proposalDeadline(proposalId)++`] +* {xref-Governor-proposalProposer-uint256-}[`++proposalProposer(proposalId)++`] +* {xref-Governor-proposalEta-uint256-}[`++proposalEta(proposalId)++`] +* {xref-Governor-_checkGovernance--}[`++_checkGovernance()++`] +* {xref-Governor-_quorumReached-uint256-}[`++_quorumReached(proposalId)++`] +* {xref-Governor-_voteSucceeded-uint256-}[`++_voteSucceeded(proposalId)++`] +* {xref-Governor-_getVotes-address-uint256-bytes-}[`++_getVotes(account, timepoint, params)++`] +* {xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-}[`++_countVote(proposalId, account, support, weight, params)++`] +* {xref-Governor-_defaultParams--}[`++_defaultParams()++`] +* {xref-Governor-_propose-address---uint256---bytes---string-address-}[`++_propose(targets, values, calldatas, description, proposer)++`] +* {xref-Governor-queue-address---uint256---bytes---bytes32-}[`++queue(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-execute-address---uint256---bytes---bytes32-}[`++execute(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-cancel-address---uint256---bytes---bytes32-}[`++cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-getVotes-address-uint256-}[`++getVotes(account, timepoint)++`] +* {xref-Governor-getVotesWithParams-address-uint256-bytes-}[`++getVotesWithParams(account, timepoint, params)++`] +* {xref-Governor-castVote-uint256-uint8-}[`++castVote(proposalId, support)++`] +* {xref-Governor-castVoteWithReason-uint256-uint8-string-}[`++castVoteWithReason(proposalId, support, reason)++`] +* {xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-}[`++castVoteWithReasonAndParams(proposalId, support, reason, params)++`] +* {xref-Governor-castVoteBySig-uint256-uint8-address-bytes-}[`++castVoteBySig(proposalId, support, voter, signature)++`] +* {xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-}[`++castVoteWithReasonAndParamsBySig(proposalId, support, voter, reason, params, signature)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-}[`++_castVote(proposalId, account, support, reason)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-bytes-}[`++_castVote(proposalId, account, support, reason, params)++`] +* {xref-Governor-relay-address-uint256-bytes-}[`++relay(target, value, data)++`] +* {xref-Governor-_executor--}[`++_executor()++`] +* {xref-Governor-onERC721Received-address-address-uint256-bytes-}[`++onERC721Received(, , , )++`] +* {xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-}[`++onERC1155Received(, , , , )++`] +* {xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-}[`++onERC1155BatchReceived(, , , , )++`] +* {xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-}[`++_encodeStateBitmap(proposalState)++`] +* {xref-Governor-_isValidDescriptionForProposer-address-string-}[`++_isValidDescriptionForProposer(proposer, description)++`] +* {xref-Governor-clock--}[`++clock()++`] +* {xref-Governor-CLOCK_MODE--}[`++CLOCK_MODE()++`] +* {xref-Governor-votingDelay--}[`++votingDelay()++`] +* {xref-Governor-votingPeriod--}[`++votingPeriod()++`] +* {xref-Governor-quorum-uint256-}[`++quorum(timepoint)++`] +* {xref-Governor-BALLOT_TYPEHASH-bytes32}[`++BALLOT_TYPEHASH()++`] +* {xref-Governor-EXTENDED_BALLOT_TYPEHASH-bytes32}[`++EXTENDED_BALLOT_TYPEHASH()++`] + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-COUNTING_MODE--}[`++COUNTING_MODE()++`] +* {xref-IGovernor-hasVoted-uint256-address-}[`++hasVoted(proposalId, account)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-nonces-address-}[`++nonces(owner)++`] +* {xref-Nonces-_useNonce-address-}[`++_useNonce(owner)++`] +* {xref-Nonces-_useCheckedNonce-address-uint256-}[`++_useCheckedNonce(owner, nonce)++`] + +[.contract-subindex-inherited] +.EIP712 +* {xref-EIP712-_domainSeparatorV4--}[`++_domainSeparatorV4()++`] +* {xref-EIP712-_hashTypedDataV4-bytes32-}[`++_hashTypedDataV4(structHash)++`] +* {xref-EIP712-eip712Domain--}[`++eip712Domain()++`] +* {xref-EIP712-_EIP712Name--}[`++_EIP712Name()++`] +* {xref-EIP712-_EIP712Version--}[`++_EIP712Version()++`] + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- +* {xref-GovernorTimelockAccess-BaseDelaySet-uint32-uint32-}[`++BaseDelaySet(oldBaseDelaySeconds, newBaseDelaySeconds)++`] +* {xref-GovernorTimelockAccess-AccessManagerIgnoredSet-address-bytes4-bool-}[`++AccessManagerIgnoredSet(target, selector, ignored)++`] + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-}[`++ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)++`] +* {xref-IGovernor-ProposalQueued-uint256-uint256-}[`++ProposalQueued(proposalId, etaSeconds)++`] +* {xref-IGovernor-ProposalExecuted-uint256-}[`++ProposalExecuted(proposalId)++`] +* {xref-IGovernor-ProposalCanceled-uint256-}[`++ProposalCanceled(proposalId)++`] +* {xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-}[`++VoteCast(voter, proposalId, support, weight, reason)++`] +* {xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-}[`++VoteCastWithParams(voter, proposalId, support, weight, reason, params)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- +* {xref-GovernorTimelockAccess-GovernorUnmetDelay-uint256-uint256-}[`++GovernorUnmetDelay(proposalId, neededTimestamp)++`] +* {xref-GovernorTimelockAccess-GovernorMismatchedNonce-uint256-uint256-uint256-}[`++GovernorMismatchedNonce(proposalId, expectedNonce, actualNonce)++`] +* {xref-GovernorTimelockAccess-GovernorLockedIgnore--}[`++GovernorLockedIgnore()++`] + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-}[`++GovernorInvalidProposalLength(targets, calldatas, values)++`] +* {xref-IGovernor-GovernorAlreadyCastVote-address-}[`++GovernorAlreadyCastVote(voter)++`] +* {xref-IGovernor-GovernorDisabledDeposit--}[`++GovernorDisabledDeposit()++`] +* {xref-IGovernor-GovernorOnlyProposer-address-}[`++GovernorOnlyProposer(account)++`] +* {xref-IGovernor-GovernorOnlyExecutor-address-}[`++GovernorOnlyExecutor(account)++`] +* {xref-IGovernor-GovernorNonexistentProposal-uint256-}[`++GovernorNonexistentProposal(proposalId)++`] +* {xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-}[`++GovernorUnexpectedProposalState(proposalId, current, expectedStates)++`] +* {xref-IGovernor-GovernorInvalidVotingPeriod-uint256-}[`++GovernorInvalidVotingPeriod(votingPeriod)++`] +* {xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-}[`++GovernorInsufficientProposerVotes(proposer, votes, threshold)++`] +* {xref-IGovernor-GovernorRestrictedProposer-address-}[`++GovernorRestrictedProposer(proposer)++`] +* {xref-IGovernor-GovernorInvalidVoteType--}[`++GovernorInvalidVoteType()++`] +* {xref-IGovernor-GovernorQueueNotImplemented--}[`++GovernorQueueNotImplemented()++`] +* {xref-IGovernor-GovernorNotQueuedProposal-uint256-}[`++GovernorNotQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-}[`++GovernorAlreadyQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorInvalidSignature-address-}[`++GovernorInvalidSignature(voter)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-InvalidAccountNonce-address-uint256-}[`++InvalidAccountNonce(account, currentNonce)++`] + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[GovernorTimelockAccess-constructor-address-uint32-]] +==== `[.contract-item-name]#++constructor++#++(address manager, uint32 initialBaseDelay)++` [.item-kind]#internal# + +Initialize the governor with an {AccessManager} and initial base delay. + +[.contract-item] +[[GovernorTimelockAccess-accessManager--]] +==== `[.contract-item-name]#++accessManager++#++() → contract IAccessManager++` [.item-kind]#public# + +Returns the {AccessManager} instance associated to this governor. + +[.contract-item] +[[GovernorTimelockAccess-baseDelaySeconds--]] +==== `[.contract-item-name]#++baseDelaySeconds++#++() → uint32++` [.item-kind]#public# + +Base delay that will be applied to all function calls. Some may be further delayed by their associated +`AccessManager` authority; in this case the final delay will be the maximum of the base delay and the one +demanded by the authority. + +NOTE: Execution delays are processed by the `AccessManager` contracts, and according to that contract are +expressed in seconds. Therefore, the base delay is also in seconds, regardless of the governor's clock mode. + +[.contract-item] +[[GovernorTimelockAccess-setBaseDelaySeconds-uint32-]] +==== `[.contract-item-name]#++setBaseDelaySeconds++#++(uint32 newBaseDelay)++` [.item-kind]#public# + +Change the value of {baseDelaySeconds}. This operation can only be invoked through a governance proposal. + +[.contract-item] +[[GovernorTimelockAccess-_setBaseDelaySeconds-uint32-]] +==== `[.contract-item-name]#++_setBaseDelaySeconds++#++(uint32 newBaseDelay)++` [.item-kind]#internal# + +Change the value of {baseDelaySeconds}. Internal function without access control. + +[.contract-item] +[[GovernorTimelockAccess-isAccessManagerIgnored-address-bytes4-]] +==== `[.contract-item-name]#++isAccessManagerIgnored++#++(address target, bytes4 selector) → bool++` [.item-kind]#public# + +Check if restrictions from the associated {AccessManager} are ignored for a target function. Returns true +when the target function will be invoked directly regardless of `AccessManager` settings for the function. +See {setAccessManagerIgnored} and Security Considerations above. + +[.contract-item] +[[GovernorTimelockAccess-setAccessManagerIgnored-address-bytes4---bool-]] +==== `[.contract-item-name]#++setAccessManagerIgnored++#++(address target, bytes4[] selectors, bool ignored)++` [.item-kind]#public# + +Configure whether restrictions from the associated {AccessManager} are ignored for a target function. +See Security Considerations above. + +[.contract-item] +[[GovernorTimelockAccess-_setAccessManagerIgnored-address-bytes4-bool-]] +==== `[.contract-item-name]#++_setAccessManagerIgnored++#++(address target, bytes4 selector, bool ignored)++` [.item-kind]#internal# + +Internal version of {setAccessManagerIgnored} without access restriction. + +[.contract-item] +[[GovernorTimelockAccess-proposalExecutionPlan-uint256-]] +==== `[.contract-item-name]#++proposalExecutionPlan++#++(uint256 proposalId) → uint32 delay, bool[] indirect, bool[] withDelay++` [.item-kind]#public# + +Public accessor to check the execution plan, including the number of seconds that the proposal will be +delayed since queuing, an array indicating which of the proposal actions will be executed indirectly through +the associated {AccessManager}, and another indicating which will be scheduled in {queue}. Note that +those that must be scheduled are cancellable by `AccessManager` guardians. + +[.contract-item] +[[GovernorTimelockAccess-proposalNeedsQueuing-uint256-]] +==== `[.contract-item-name]#++proposalNeedsQueuing++#++(uint256 proposalId) → bool++` [.item-kind]#public# + +See {IGovernor-proposalNeedsQueuing}. + +[.contract-item] +[[GovernorTimelockAccess-propose-address---uint256---bytes---string-]] +==== `[.contract-item-name]#++propose++#++(address[] targets, uint256[] values, bytes[] calldatas, string description) → uint256++` [.item-kind]#public# + +See {IGovernor-propose} + +[.contract-item] +[[GovernorTimelockAccess-_queueOperations-uint256-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++_queueOperations++#++(uint256 proposalId, address[] targets, uint256[], bytes[] calldatas, bytes32) → uint48++` [.item-kind]#internal# + +Mechanism to queue a proposal, potentially scheduling some of its operations in the AccessManager. + +NOTE: The execution delay is chosen based on the delay information retrieved in {propose}. This value may be +off if the delay was updated since proposal creation. In this case, the proposal needs to be recreated. + +[.contract-item] +[[GovernorTimelockAccess-_executeOperations-uint256-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++_executeOperations++#++(uint256 proposalId, address[] targets, uint256[] values, bytes[] calldatas, bytes32)++` [.item-kind]#internal# + +Mechanism to execute a proposal, potentially going through {AccessManager-execute} for delayed operations. + +[.contract-item] +[[GovernorTimelockAccess-_cancel-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++_cancel++#++(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) → uint256++` [.item-kind]#internal# + +See {IGovernor-_cancel} + +[.contract-item] +[[GovernorTimelockAccess-BaseDelaySet-uint32-uint32-]] +==== `[.contract-item-name]#++BaseDelaySet++#++(uint32 oldBaseDelaySeconds, uint32 newBaseDelaySeconds)++` [.item-kind]#event# + +[.contract-item] +[[GovernorTimelockAccess-AccessManagerIgnoredSet-address-bytes4-bool-]] +==== `[.contract-item-name]#++AccessManagerIgnoredSet++#++(address target, bytes4 selector, bool ignored)++` [.item-kind]#event# + +[.contract-item] +[[GovernorTimelockAccess-GovernorUnmetDelay-uint256-uint256-]] +==== `[.contract-item-name]#++GovernorUnmetDelay++#++(uint256 proposalId, uint256 neededTimestamp)++` [.item-kind]#error# + +[.contract-item] +[[GovernorTimelockAccess-GovernorMismatchedNonce-uint256-uint256-uint256-]] +==== `[.contract-item-name]#++GovernorMismatchedNonce++#++(uint256 proposalId, uint256 expectedNonce, uint256 actualNonce)++` [.item-kind]#error# + +[.contract-item] +[[GovernorTimelockAccess-GovernorLockedIgnore--]] +==== `[.contract-item-name]#++GovernorLockedIgnore++#++()++` [.item-kind]#error# + :TimelockChange: pass:normal[xref:#GovernorTimelockControl-TimelockChange-address-address-[`++TimelockChange++`]] :constructor: pass:normal[xref:#GovernorTimelockControl-constructor-contract-TimelockController-[`++constructor++`]] :state: pass:normal[xref:#GovernorTimelockControl-state-uint256-[`++state++`]] diff --git a/docs/modules/api/pages/metatx.adoc b/docs/modules/api/pages/metatx.adoc index 95b4cf4af..f248f61c3 100644 --- a/docs/modules/api/pages/metatx.adoc +++ b/docs/modules/api/pages/metatx.adoc @@ -1,4 +1,6 @@ :github-icon: pass:[] +:ERC2771Context: pass:normal[xref:metatx.adoc#ERC2771Context[`ERC2771Context`]] +:ERC2771Forwarder: pass:normal[xref:metatx.adoc#ERC2771Forwarder[`ERC2771Forwarder`]] :xref-ERC2771Context-constructor-address-: xref:metatx.adoc#ERC2771Context-constructor-address- :xref-ERC2771Context-trustedForwarder--: xref:metatx.adoc#ERC2771Context-trustedForwarder-- :xref-ERC2771Context-isTrustedForwarder-address-: xref:metatx.adoc#ERC2771Context-isTrustedForwarder-address- @@ -35,6 +37,11 @@ [.readme-notice] NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/metatx +This directory includes contracts for adding meta-transaction capabilities (i.e. abstracting the execution context from the transaction origin) following the https://eips.ethereum.org/EIPS/eip-2771[ERC-2771 specification]. + +- {ERC2771Context}: Provides a mechanism to override the sender and calldata of the execution context (`msg.sender` and `msg.data`) with a custom value specified by a trusted forwarder. +- {ERC2771Forwarder}: A production-ready forwarder that relays operation requests signed off-chain by an EOA. + == Core :constructor: pass:normal[xref:#ERC2771Context-constructor-address-[`++constructor++`]] diff --git a/docs/modules/api/pages/utils.adoc b/docs/modules/api/pages/utils.adoc index 1406f7564..c7c124569 100644 --- a/docs/modules/api/pages/utils.adoc +++ b/docs/modules/api/pages/utils.adoc @@ -1,14 +1,30 @@ :github-icon: pass:[] -:ReentrancyGuard: pass:normal[xref:utils.adoc#ReentrancyGuard[`ReentrancyGuard`]] -:Pausable: pass:normal[xref:utils.adoc#Pausable[`Pausable`]] -:SafeCast: pass:normal[xref:utils.adoc#SafeCast[`SafeCast`]] :Math: pass:normal[xref:utils.adoc#Math[`Math`]] :SignedMath: pass:normal[xref:utils.adoc#SignedMath[`SignedMath`]] -:Multicall: pass:normal[xref:utils.adoc#Multicall[`Multicall`]] -:Create2: pass:normal[xref:utils.adoc#Create2[`Create2`]] +:SafeCast: pass:normal[xref:utils.adoc#SafeCast[`SafeCast`]] +:ECDSA: pass:normal[xref:utils.adoc#ECDSA[`ECDSA`]] +:MessageHashUtils: pass:normal[xref:utils.adoc#MessageHashUtils[`MessageHashUtils`]] +:SignatureChecker: pass:normal[xref:utils.adoc#SignatureChecker[`SignatureChecker`]] +:MerkleProof: pass:normal[xref:utils.adoc#MerkleProof[`MerkleProof`]] +:EIP712: pass:normal[xref:utils.adoc#EIP712[`EIP712`]] +:ReentrancyGuard: pass:normal[xref:utils.adoc#ReentrancyGuard[`ReentrancyGuard`]] +:Pausable: pass:normal[xref:utils.adoc#Pausable[`Pausable`]] +:Nonces: pass:normal[xref:utils.adoc#Nonces[`Nonces`]] +:BitMaps: pass:normal[xref:utils.adoc#BitMaps[`BitMaps`]] :EnumerableMap: pass:normal[xref:utils.adoc#EnumerableMap[`EnumerableMap`]] :EnumerableSet: pass:normal[xref:utils.adoc#EnumerableSet[`EnumerableSet`]] :EnumerableMap: pass:normal[xref:utils.adoc#EnumerableMap[`EnumerableMap`]] +:DoubleEndedQueue: pass:normal[xref:utils.adoc#DoubleEndedQueue[`DoubleEndedQueue`]] +:Checkpoints: pass:normal[xref:utils.adoc#Checkpoints[`Checkpoints`]] +:Create2: pass:normal[xref:utils.adoc#Create2[`Create2`]] +:Address: pass:normal[xref:utils.adoc#Address[`Address`]] +:Arrays: pass:normal[xref:utils.adoc#Arrays[`Arrays`]] +:Base64: pass:normal[xref:utils.adoc#Base64[`Base64`]] +:Strings: pass:normal[xref:utils.adoc#Strings[`Strings`]] +:ShortString: pass:normal[xref:utils.adoc#ShortString[`ShortString`]] +:StorageSlot: pass:normal[xref:utils.adoc#StorageSlot[`StorageSlot`]] +:Multicall: pass:normal[xref:utils.adoc#Multicall[`Multicall`]] +:Context: pass:normal[xref:utils.adoc#Context[`Context`]] :EnumerableMap: pass:normal[xref:utils.adoc#EnumerableMap[`EnumerableMap`]] :EnumerableSet: pass:normal[xref:utils.adoc#EnumerableSet[`EnumerableSet`]] :xref-Math-tryAdd-uint256-uint256-: xref:utils.adoc#Math-tryAdd-uint256-uint256- @@ -163,6 +179,10 @@ :xref-Pausable-Unpaused-address-: xref:utils.adoc#Pausable-Unpaused-address- :xref-Pausable-EnforcedPause--: xref:utils.adoc#Pausable-EnforcedPause-- :xref-Pausable-ExpectedPause--: xref:utils.adoc#Pausable-ExpectedPause-- +:xref-Nonces-nonces-address-: xref:utils.adoc#Nonces-nonces-address- +:xref-Nonces-_useNonce-address-: xref:utils.adoc#Nonces-_useNonce-address- +:xref-Nonces-_useCheckedNonce-address-uint256-: xref:utils.adoc#Nonces-_useCheckedNonce-address-uint256- +:xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- :ERC165Checker: pass:normal[xref:utils.adoc#ERC165Checker[`ERC165Checker`]] :ERC165: pass:normal[xref:utils.adoc#ERC165[`ERC165`]] :xref-IERC165-supportsInterface-bytes4-: xref:utils.adoc#IERC165-supportsInterface-bytes4- @@ -336,6 +356,9 @@ :xref-StorageSlot-getBytesSlot-bytes-: xref:utils.adoc#StorageSlot-getBytesSlot-bytes- :ERC2771Context: pass:normal[xref:metatx.adoc#ERC2771Context[`ERC2771Context`]] :xref-Multicall-multicall-bytes---: xref:utils.adoc#Multicall-multicall-bytes--- +:xref-Context-_msgSender--: xref:utils.adoc#Context-_msgSender-- +:xref-Context-_msgData--: xref:utils.adoc#Context-_msgData-- +:xref-Context-_contextSuffixLength--: xref:utils.adoc#Context-_contextSuffixLength-- = Utilities [.readme-notice] @@ -343,14 +366,30 @@ NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/ Miscellaneous contracts and libraries containing utility functions you can use to improve security, work with new data types, or safely use low-level primitives. + * {Math}, {SignedMath}: Implementation of various arithmetic functions. + * {SafeCast}: Checked downcasting functions to avoid silent truncation. + * {ECDSA}, {MessageHashUtils}: Libraries for interacting with ECDSA signatures. + * {SignatureChecker}: A library helper to support regular ECDSA from EOAs as well as ERC-1271 signatures for smart contracts. + * {MerkleProof}: Functions for verifying https://en.wikipedia.org/wiki/Merkle_tree[Merkle Tree] proofs. + * {EIP712}: Contract with functions to allow processing signed typed structure data according to https://eips.ethereum.org/EIPS/eip-712[EIP-712]. * {ReentrancyGuard}: A modifier that can prevent reentrancy during certain functions. * {Pausable}: A common emergency response mechanism that can pause functionality while a remediation is pending. - * {SafeCast}: Checked downcasting functions to avoid silent truncation. - * {Math}, {SignedMath}: Implementation of various arithmetic functions. - * {Multicall}: Simple way to batch together multiple calls in a single external call. - * {Create2}: Wrapper around the https://blog.openzeppelin.com/getting-the-most-out-of-create2/[`CREATE2` EVM opcode] for safe use without having to deal with low-level assembly. + * {Nonces}: Utility for tracking and verifying address nonces that only increment. + * {ERC165, ERC165Checker}: Utilities for inspecting interfaces supported by contracts. + * {BitMaps}: A simple library to manage boolean value mapped to a numerical index in an efficient way. * {EnumerableMap}: A type like Solidity's https://solidity.readthedocs.io/en/latest/types.html#mapping-types[`mapping`], but with key-value _enumeration_: this will let you know how many entries a mapping has, and iterate over them (which is not possible with `mapping`). * {EnumerableSet}: Like {EnumerableMap}, but for https://en.wikipedia.org/wiki/Set_(abstract_data_type)[sets]. Can be used to store privileged accounts, issued IDs, etc. + * {DoubleEndedQueue}: An implementation of a https://en.wikipedia.org/wiki/Double-ended_queue[double ended queue] whose values can be removed added or remove from both sides. Useful for FIFO and LIFO structures. + * {Checkpoints}: A data structure to store values mapped to an strictly increasing key. Can be used for storing and accessing values over time. + * {Create2}: Wrapper around the https://blog.openzeppelin.com/getting-the-most-out-of-create2/[`CREATE2` EVM opcode] for safe use without having to deal with low-level assembly. + * {Address}: Collection of functions for overloading Solidity's https://docs.soliditylang.org/en/latest/types.html#address[`address`] type. + * {Arrays}: Collection of functions that operate on https://docs.soliditylang.org/en/latest/types.html#arrays[`arrays`]. + * {Base64}: On-chain base64 and base64URL encoding according to https://datatracker.ietf.org/doc/html/rfc4648[RFC-4648]. + * {Strings}: Common operations for strings formatting. + * {ShortString}: Library to encode (and decode) short strings into (or from) a single bytes32 slot for optimizing costs. Short strings are limited to 31 characters. + * {StorageSlot}: Methods for accessing specific storage slots formatted as common primitive types. + * {Multicall}: Abstract contract with an utility to allow batching together multiple calls in a single transaction. Useful for allowing EOAs to perform multiple operations at once. + * {Context}: An utility for abstracting the sender and calldata in the current execution context. [NOTE] ==== @@ -2412,6 +2451,64 @@ The operation failed because the contract is paused. The operation failed because the contract is not paused. +:InvalidAccountNonce: pass:normal[xref:#Nonces-InvalidAccountNonce-address-uint256-[`++InvalidAccountNonce++`]] +:nonces: pass:normal[xref:#Nonces-nonces-address-[`++nonces++`]] +:_useNonce: pass:normal[xref:#Nonces-_useNonce-address-[`++_useNonce++`]] +:_useCheckedNonce: pass:normal[xref:#Nonces-_useCheckedNonce-address-uint256-[`++_useCheckedNonce++`]] + +[.contract] +[[Nonces]] +=== `++Nonces++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.1/contracts/utils/Nonces.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/Nonces.sol"; +``` + +Provides tracking nonces for addresses. Nonces will only increment. + +[.contract-index] +.Functions +-- +* {xref-Nonces-nonces-address-}[`++nonces(owner)++`] +* {xref-Nonces-_useNonce-address-}[`++_useNonce(owner)++`] +* {xref-Nonces-_useCheckedNonce-address-uint256-}[`++_useCheckedNonce(owner, nonce)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-Nonces-InvalidAccountNonce-address-uint256-}[`++InvalidAccountNonce(account, currentNonce)++`] + +-- + +[.contract-item] +[[Nonces-nonces-address-]] +==== `[.contract-item-name]#++nonces++#++(address owner) → uint256++` [.item-kind]#public# + +Returns the next unused nonce for an address. + +[.contract-item] +[[Nonces-_useNonce-address-]] +==== `[.contract-item-name]#++_useNonce++#++(address owner) → uint256++` [.item-kind]#internal# + +Consumes a nonce. + +Returns the current value and increments nonce. + +[.contract-item] +[[Nonces-_useCheckedNonce-address-uint256-]] +==== `[.contract-item-name]#++_useCheckedNonce++#++(address owner, uint256 nonce)++` [.item-kind]#internal# + +Same as {_useNonce} but checking that `nonce` is the next valid for `owner`. + +[.contract-item] +[[Nonces-InvalidAccountNonce-address-uint256-]] +==== `[.contract-item-name]#++InvalidAccountNonce++#++(address account, uint256 currentNonce)++` [.item-kind]#error# + +The nonce used for an `account` is not the expected current nonce. + == Introspection This set of interfaces and contracts deal with https://en.wikipedia.org/wiki/Type_introspection[type introspection] of contracts, that is, examining which functions can be called on them. This is usually referred to as a contract's _interface_. @@ -4505,3 +4602,46 @@ to the subcall. This makes it safe to use with {ERC2771Context}. Contexts that d Receives and executes a batch of function calls on this contract. +:_msgSender: pass:normal[xref:#Context-_msgSender--[`++_msgSender++`]] +:_msgData: pass:normal[xref:#Context-_msgData--[`++_msgData++`]] +:_contextSuffixLength: pass:normal[xref:#Context-_contextSuffixLength--[`++_contextSuffixLength++`]] + +[.contract] +[[Context]] +=== `++Context++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.1/contracts/utils/Context.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/Context.sol"; +``` + +Provides information about the current execution context, including the +sender of the transaction and its data. While these are generally available +via msg.sender and msg.data, they should not be accessed in such a direct +manner, since when dealing with meta-transactions the account sending and +paying for execution may not be the actual sender (as far as an application +is concerned). + +This contract is only required for intermediate, library-like contracts. + +[.contract-index] +.Functions +-- +* {xref-Context-_msgSender--}[`++_msgSender()++`] +* {xref-Context-_msgData--}[`++_msgData()++`] +* {xref-Context-_contextSuffixLength--}[`++_contextSuffixLength()++`] + +-- + +[.contract-item] +[[Context-_msgSender--]] +==== `[.contract-item-name]#++_msgSender++#++() → address++` [.item-kind]#internal# + +[.contract-item] +[[Context-_msgData--]] +==== `[.contract-item-name]#++_msgData++#++() → bytes++` [.item-kind]#internal# + +[.contract-item] +[[Context-_contextSuffixLength--]] +==== `[.contract-item-name]#++_contextSuffixLength++#++() → uint256++` [.item-kind]#internal# +