arr00-testing-oz-contracts 0.0.0 → 5.8.0

package/governance/extensions/GovernorVotes.sol

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v5.8.0) (governance/extensions/GovernorVotes.sol)
+
+pragma solidity ^0.8.24;
+
+import {IERC5805} from "../../interfaces/IERC5805.sol";
+import {ERC6372Utils} from "../../utils/ERC6372Utils.sol";
+import {Time} from "../../utils/types/Time.sol";
+import {Governor} from "../Governor.sol";
+import {IVotes} from "../utils/IVotes.sol";
+
+/**
+ * @dev Extension of {Governor} for voting weight extraction from an {ERC20Votes} token, or since v4.5 an {ERC721Votes}
+ * token.
+ */
+abstract contract GovernorVotes is Governor {
+    IERC5805 private immutable _token;
+
+    constructor(IVotes tokenAddress) {
+        _token = IERC5805(address(tokenAddress));
+    }
+
+    /**
+     * @dev The token that voting power is sourced from.
+     */
+    function token() public view virtual returns (IERC5805) {
+        return _token;
+    }
+
+    /**
+     * @dev Clock (as specified in ERC-6372) is set to match the token's clock. Fallback to block numbers if the token
+     * does not implement ERC-6372.
+     */
+    function clock() public view virtual override returns (uint48) {
+        try token().clock() returns (uint48 timepoint) {
+            return timepoint;
+        } catch {
+            return Time.blockNumber();
+        }
+    }
+
+    /**
+     * @dev Machine-readable description of the clock as specified in ERC-6372.
+     */
+    // solhint-disable-next-line func-name-mixedcase
+    function CLOCK_MODE() public view virtual override returns (string memory) {
+        try token().CLOCK_MODE() returns (string memory clockmode) {
+            return clockmode;
+        } catch {
+            return ERC6372Utils.blockNumberClockMode(clock);
+        }
+    }
+
+    /**
+     * Read the voting weight from the token's built in snapshot mechanism (see {Governor-_getVotes}).
+     */
+    function _getVotes(
+        address account,
+        uint256 timepoint,
+        bytes memory /*params*/
+    ) internal view virtual override returns (uint256) {
+        return token().getPastVotes(account, timepoint);
+    }
+}

package/governance/extensions/GovernorVotesQuorumFraction.sol

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v5.8.0) (governance/extensions/GovernorVotesQuorumFraction.sol)
+
+pragma solidity ^0.8.24;
+
+import {Math} from "../../utils/math/Math.sol";
+import {SafeCast} from "../../utils/math/SafeCast.sol";
+import {Checkpoints} from "../../utils/structs/Checkpoints.sol";
+import {GovernorVotes} from "./GovernorVotes.sol";
+
+/**
+ * @dev Extension of {Governor} for voting weight extraction from an {ERC20Votes} token and a quorum expressed as a
+ * fraction of the total supply.
+ */
+abstract contract GovernorVotesQuorumFraction is GovernorVotes {
+    using Checkpoints for Checkpoints.Trace208;
+
+    Checkpoints.Trace208 private _quorumNumeratorHistory;
+
+    event QuorumNumeratorUpdated(uint256 oldQuorumNumerator, uint256 newQuorumNumerator);
+
+    /**
+     * @dev The quorum set is not a valid fraction.
+     */
+    error GovernorInvalidQuorumFraction(uint256 quorumNumerator, uint256 quorumDenominator);
+
+    /**
+     * @dev Initialize quorum as a fraction of the token's total supply.
+     *
+     * The fraction is specified as `numerator / denominator`. By default the denominator is 100, so quorum is
+     * specified as a percent: a numerator of 10 corresponds to quorum being 10% of total supply. The denominator can be
+     * customized by overriding {quorumDenominator}.
+     */
+    constructor(uint256 quorumNumeratorValue) {
+        _updateQuorumNumerator(quorumNumeratorValue);
+    }
+
+    /**
+     * @dev Returns the current quorum numerator. See {quorumDenominator}.
+     */
+    function quorumNumerator() public view virtual returns (uint256) {
+        return _quorumNumeratorHistory.latest();
+    }
+
+    /**
+     * @dev Returns the quorum numerator at a specific timepoint. See {quorumDenominator}.
+     */
+    function quorumNumerator(uint256 timepoint) public view virtual returns (uint256) {
+        return _optimisticUpperLookupRecent(_quorumNumeratorHistory, timepoint);
+    }
+
+    /**
+     * @dev Returns the quorum denominator. Defaults to 100, but may be overridden.
+     */
+    function quorumDenominator() public view virtual returns (uint256) {
+        return 100;
+    }
+
+    /**
+     * @dev Returns the quorum for a timepoint, in terms of number of votes: `supply * numerator / denominator`.
+     */
+    function quorum(uint256 timepoint) public view virtual override returns (uint256) {
+        return Math.mulDiv(token().getPastTotalSupply(timepoint), quorumNumerator(timepoint), quorumDenominator());
+    }
+
+    /**
+     * @dev Changes the quorum numerator.
+     *
+     * Emits a {QuorumNumeratorUpdated} event.
+     *
+     * Requirements:
+     *
+     * - Must be called through a governance proposal.
+     * - New numerator must be smaller or equal to the denominator.
+     */
+    function updateQuorumNumerator(uint256 newQuorumNumerator) public virtual onlyGovernance {
+        _updateQuorumNumerator(newQuorumNumerator);
+    }
+
+    /**
+     * @dev Changes the quorum numerator.
+     *
+     * Emits a {QuorumNumeratorUpdated} event.
+     *
+     * Requirements:
+     *
+     * - New numerator must be smaller or equal to the denominator.
+     */
+    function _updateQuorumNumerator(uint256 newQuorumNumerator) internal virtual {
+        uint256 denominator = quorumDenominator();
+        if (newQuorumNumerator > denominator) {
+            revert GovernorInvalidQuorumFraction(newQuorumNumerator, denominator);
+        }
+
+        uint256 oldQuorumNumerator = quorumNumerator();
+        _quorumNumeratorHistory.push(clock(), SafeCast.toUint208(newQuorumNumerator));
+
+        emit QuorumNumeratorUpdated(oldQuorumNumerator, newQuorumNumerator);
+    }
+
+    /**
+     * @dev Returns the numerator at a specific timepoint.
+     */
+    function _optimisticUpperLookupRecent(
+        Checkpoints.Trace208 storage ckpts,
+        uint256 timepoint
+    ) internal view returns (uint256) {
+        // If trace is empty, key and value are both equal to 0.
+        // In that case `key <= timepoint` is true, and it is ok to return 0.
+        (, uint48 key, uint208 value) = ckpts.latestCheckpoint();
+        return key <= timepoint ? value : ckpts.upperLookupRecent(SafeCast.toUint48(timepoint));
+    }
+}

package/governance/extensions/GovernorVotesSuperQuorumFraction.sol

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v5.8.0) (governance/extensions/GovernorVotesSuperQuorumFraction.sol)
+
+pragma solidity ^0.8.24;
+
+import {Math} from "../../utils/math/Math.sol";
+import {SafeCast} from "../../utils/math/SafeCast.sol";
+import {Checkpoints} from "../../utils/structs/Checkpoints.sol";
+import {Governor} from "../Governor.sol";
+import {GovernorSuperQuorum} from "./GovernorSuperQuorum.sol";
+import {GovernorVotesQuorumFraction} from "./GovernorVotesQuorumFraction.sol";
+
+/**
+ * @dev Extension of {GovernorVotesQuorumFraction} with a super quorum expressed as a
+ * fraction of the total supply. Proposals that meet the super quorum (and have a majority of for votes) advance to
+ * the `Succeeded` state before the proposal deadline.
+ */
+abstract contract GovernorVotesSuperQuorumFraction is GovernorVotesQuorumFraction, GovernorSuperQuorum {
+    using Checkpoints for Checkpoints.Trace208;
+
+    Checkpoints.Trace208 private _superQuorumNumeratorHistory;
+
+    event SuperQuorumNumeratorUpdated(uint256 oldSuperQuorumNumerator, uint256 newSuperQuorumNumerator);
+
+    /**
+     * @dev The super quorum set is not valid as it exceeds the quorum denominator.
+     */
+    error GovernorInvalidSuperQuorumFraction(uint256 superQuorumNumerator, uint256 denominator);
+
+    /**
+     * @dev The super quorum set is not valid as it is smaller than the quorum.
+     */
+    error GovernorInvalidSuperQuorumTooSmall(uint256 superQuorumNumerator, uint256 quorumNumerator);
+
+    /**
+     * @dev The quorum set is not valid as it exceeds the super quorum.
+     */
+    error GovernorInvalidQuorumTooLarge(uint256 quorumNumerator, uint256 superQuorumNumerator);
+
+    /**
+     * @dev Initialize super quorum as a fraction of the token's total supply.
+     *
+     * The super quorum is specified as a fraction of the token's total supply and has to
+     * be greater than or equal to the quorum.
+     */
+    constructor(uint256 superQuorumNumeratorValue) {
+        _updateSuperQuorumNumerator(superQuorumNumeratorValue);
+    }
+
+    /**
+     * @dev Returns the current super quorum numerator.
+     */
+    function superQuorumNumerator() public view virtual returns (uint256) {
+        return _superQuorumNumeratorHistory.latest();
+    }
+
+    /**
+     * @dev Returns the super quorum numerator at a specific `timepoint`.
+     */
+    function superQuorumNumerator(uint256 timepoint) public view virtual returns (uint256) {
+        return _optimisticUpperLookupRecent(_superQuorumNumeratorHistory, timepoint);
+    }
+
+    /**
+     * @dev Returns the super quorum for a `timepoint`, in terms of number of votes: `supply * numerator / denominator`.
+     * See {GovernorSuperQuorum-superQuorum} for more details.
+     */
+    function superQuorum(uint256 timepoint) public view virtual override returns (uint256) {
+        return Math.mulDiv(token().getPastTotalSupply(timepoint), superQuorumNumerator(timepoint), quorumDenominator());
+    }
+
+    /**
+     * @dev Changes the super quorum numerator.
+     *
+     * Emits a {SuperQuorumNumeratorUpdated} event.
+     *
+     * Requirements:
+     *
+     * - Must be called through a governance proposal.
+     * - New super quorum numerator must be smaller or equal to the denominator.
+     * - New super quorum numerator must be greater than or equal to the quorum numerator.
+     */
+    function updateSuperQuorumNumerator(uint256 newSuperQuorumNumerator) public virtual onlyGovernance {
+        _updateSuperQuorumNumerator(newSuperQuorumNumerator);
+    }
+
+    /**
+     * @dev Changes the super quorum numerator.
+     *
+     * Emits a {SuperQuorumNumeratorUpdated} event.
+     *
+     * Requirements:
+     *
+     * - New super quorum numerator must be smaller or equal to the denominator.
+     * - New super quorum numerator must be greater than or equal to the quorum numerator.
+     */
+    function _updateSuperQuorumNumerator(uint256 newSuperQuorumNumerator) internal virtual {
+        uint256 denominator = quorumDenominator();
+        if (newSuperQuorumNumerator > denominator) {
+            revert GovernorInvalidSuperQuorumFraction(newSuperQuorumNumerator, denominator);
+        }
+
+        uint256 quorumNumerator = quorumNumerator();
+        if (newSuperQuorumNumerator < quorumNumerator) {
+            revert GovernorInvalidSuperQuorumTooSmall(newSuperQuorumNumerator, quorumNumerator);
+        }
+
+        uint256 oldSuperQuorumNumerator = _superQuorumNumeratorHistory.latest();
+        _superQuorumNumeratorHistory.push(clock(), SafeCast.toUint208(newSuperQuorumNumerator));
+
+        emit SuperQuorumNumeratorUpdated(oldSuperQuorumNumerator, newSuperQuorumNumerator);
+    }
+
+    /**
+     * @dev Overrides {GovernorVotesQuorumFraction-_updateQuorumNumerator} to ensure the super
+     * quorum numerator is greater than or equal to the quorum numerator.
+     */
+    function _updateQuorumNumerator(uint256 newQuorumNumerator) internal virtual override {
+        // Ignoring check when the superQuorum was never set (construction sets quorum before superQuorum)
+        if (_superQuorumNumeratorHistory.length() > 0) {
+            uint256 superQuorumNumerator_ = superQuorumNumerator();
+            if (newQuorumNumerator > superQuorumNumerator_) {
+                revert GovernorInvalidQuorumTooLarge(newQuorumNumerator, superQuorumNumerator_);
+            }
+        }
+        super._updateQuorumNumerator(newQuorumNumerator);
+    }
+
+    /// @inheritdoc GovernorSuperQuorum
+    function state(
+        uint256 proposalId
+    ) public view virtual override(Governor, GovernorSuperQuorum) returns (ProposalState) {
+        return super.state(proposalId);
+    }
+}

package/governance/utils/IVotes.sol

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v5.5.0) (governance/utils/IVotes.sol)
+
+pragma solidity >=0.8.4;
+
+/**
+ * @dev Common interface for {ERC20Votes}, {ERC721Votes}, and other {Votes}-enabled contracts.
+ */
+interface IVotes {
+    /**
+     * @dev The signature used has expired.
+     */
+    error VotesExpiredSignature(uint256 expiry);
+
+    /**
+     * @dev Emitted when an account changes their delegate.
+     */
+    event DelegateChanged(address indexed delegator, address indexed fromDelegate, address indexed toDelegate);
+
+    /**
+     * @dev Emitted when a token transfer or delegate change results in changes to a delegate's number of voting units.
+     */
+    event DelegateVotesChanged(address indexed delegate, uint256 previousVotes, uint256 newVotes);
+
+    /**
+     * @dev Returns the current amount of votes that `account` has.
+     */
+    function getVotes(address account) external view returns (uint256);
+
+    /**
+     * @dev Returns the amount of votes that `account` had at a specific moment in the past. If the `clock()` is
+     * configured to use block numbers, this will return the value at the end of the corresponding block.
+     */
+    function getPastVotes(address account, uint256 timepoint) external view returns (uint256);
+
+    /**
+     * @dev Returns the total supply of votes available at a specific moment in the past. If the `clock()` is
+     * configured to use block numbers, this will return the value at the end of the corresponding block.
+     *
+     * NOTE: This value is the sum of all available votes, which is not necessarily the sum of all delegated votes.
+     * Votes that have not been delegated are still part of total supply, even though they would not participate in a
+     * vote.
+     */
+    function getPastTotalSupply(uint256 timepoint) external view returns (uint256);
+
+    /**
+     * @dev Returns the delegate that `account` has chosen.
+     */
+    function delegates(address account) external view returns (address);
+
+    /**
+     * @dev Delegates votes from the sender to `delegatee`.
+     */
+    function delegate(address delegatee) external;
+
+    /**
+     * @dev Delegates votes from signer to `delegatee`.
+     */
+    function delegateBySig(address delegatee, uint256 nonce, uint256 expiry, uint8 v, bytes32 r, bytes32 s) external;
+}

package/governance/utils/Votes.sol

@@ -0,0 +1,245 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v5.8.0) (governance/utils/Votes.sol)
+
+pragma solidity ^0.8.24;
+
+import {IERC5805} from "../../interfaces/IERC5805.sol";
+import {Context} from "../../utils/Context.sol";
+import {ECDSA} from "../../utils/cryptography/ECDSA.sol";
+import {EIP712} from "../../utils/cryptography/EIP712.sol";
+import {ERC6372Utils} from "../../utils/ERC6372Utils.sol";
+import {SafeCast} from "../../utils/math/SafeCast.sol";
+import {Nonces} from "../../utils/Nonces.sol";
+import {Checkpoints} from "../../utils/structs/Checkpoints.sol";
+import {Time} from "../../utils/types/Time.sol";
+
+/**
+ * @dev This is a base abstract contract that tracks voting units, which are a measure of voting power that can be
+ * transferred, and provides a system of vote delegation, where an account can delegate its voting units to a sort of
+ * "representative" that will pool delegated voting units from different accounts and can then use it to vote in
+ * decisions. In fact, voting units _must_ be delegated in order to count as actual votes, and an account has to
+ * delegate those votes to itself if it wishes to participate in decisions and does not have a trusted representative.
+ *
+ * This contract is often combined with a token contract such that voting units correspond to token units. For an
+ * example, see {ERC721Votes}.
+ *
+ * The full history of delegate votes is tracked on-chain so that governance protocols can consider votes as distributed
+ * at a particular block number to protect against flash loans and double voting. The opt-in delegate system makes the
+ * 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-_update}).
+ */
+abstract contract Votes is Context, EIP712, Nonces, IERC5805 {
+    using Checkpoints for Checkpoints.Trace208;
+
+    bytes32 private constant DELEGATION_TYPEHASH =
+        keccak256("Delegation(address delegatee,uint256 nonce,uint256 expiry)");
+
+    mapping(address account => address) private _delegatee;
+
+    mapping(address delegatee => Checkpoints.Trace208) private _delegateCheckpoints;
+
+    Checkpoints.Trace208 private _totalCheckpoints;
+
+    /**
+     * @dev Lookup to future votes is not available.
+     */
+    error ERC5805FutureLookup(uint256 timepoint, uint48 clock);
+
+    /**
+     * @dev Clock used for flagging checkpoints. Can be overridden to implement timestamp based
+     * checkpoints (and voting), in which case {CLOCK_MODE} should be overridden as well to match.
+     */
+    function clock() public view virtual returns (uint48) {
+        return Time.blockNumber();
+    }
+
+    /**
+     * @dev Machine-readable description of the clock as specified in ERC-6372.
+     */
+    // solhint-disable-next-line func-name-mixedcase
+    function CLOCK_MODE() public view virtual returns (string memory) {
+        return ERC6372Utils.blockNumberClockMode(clock);
+    }
+
+    /**
+     * @dev Validate that a timepoint is in the past, and return it as a uint48.
+     */
+    function _validateTimepoint(uint256 timepoint) internal view returns (uint48) {
+        uint48 currentTimepoint = clock();
+        if (timepoint >= currentTimepoint) revert ERC5805FutureLookup(timepoint, currentTimepoint);
+        return SafeCast.toUint48(timepoint);
+    }
+
+    /**
+     * @dev Returns the current amount of votes that `account` has.
+     */
+    function getVotes(address account) public view virtual returns (uint256) {
+        return _delegateCheckpoints[account].latest();
+    }
+
+    /**
+     * @dev Returns the amount of votes that `account` had at a specific moment in the past. If the `clock()` is
+     * configured to use block numbers, this will return the value at the end of the corresponding block.
+     *
+     * Requirements:
+     *
+     * - `timepoint` must be in the past. If operating using block numbers, the block must be already mined.
+     */
+    function getPastVotes(address account, uint256 timepoint) public view virtual returns (uint256) {
+        return _delegateCheckpoints[account].upperLookupRecent(_validateTimepoint(timepoint));
+    }
+
+    /**
+     * @dev Returns the total supply of votes available at a specific moment in the past. If the `clock()` is
+     * configured to use block numbers, this will return the value at the end of the corresponding block.
+     *
+     * NOTE: This value is the sum of all available votes, which is not necessarily the sum of all delegated votes.
+     * Votes that have not been delegated are still part of total supply, even though they would not participate in a
+     * vote.
+     *
+     * Requirements:
+     *
+     * - `timepoint` must be in the past. If operating using block numbers, the block must be already mined.
+     */
+    function getPastTotalSupply(uint256 timepoint) public view virtual returns (uint256) {
+        return _totalCheckpoints.upperLookupRecent(_validateTimepoint(timepoint));
+    }
+
+    /**
+     * @dev Returns the current total supply of votes.
+     */
+    function _getTotalSupply() internal view virtual returns (uint256) {
+        return _totalCheckpoints.latest();
+    }
+
+    /**
+     * @dev Returns the delegate that `account` has chosen.
+     */
+    function delegates(address account) public view virtual returns (address) {
+        return _delegatee[account];
+    }
+
+    /**
+     * @dev Delegates votes from the sender to `delegatee`.
+     */
+    function delegate(address delegatee) public virtual {
+        address account = _msgSender();
+        _delegate(account, delegatee);
+    }
+
+    /**
+     * @dev Delegates votes from signer to `delegatee`.
+     */
+    function delegateBySig(
+        address delegatee,
+        uint256 nonce,
+        uint256 expiry,
+        uint8 v,
+        bytes32 r,
+        bytes32 s
+    ) public virtual {
+        if (block.timestamp > expiry) {
+            revert VotesExpiredSignature(expiry);
+        }
+        address signer = ECDSA.recover(
+            _hashTypedDataV4(keccak256(abi.encode(DELEGATION_TYPEHASH, delegatee, nonce, expiry))),
+            v,
+            r,
+            s
+        );
+        _useCheckedNonce(signer, nonce);
+        _delegate(signer, delegatee);
+    }
+
+    /**
+     * @dev Delegate all of `account`'s voting units to `delegatee`.
+     *
+     * Emits events {IVotes-DelegateChanged} and {IVotes-DelegateVotesChanged}.
+     */
+    function _delegate(address account, address delegatee) internal virtual {
+        address oldDelegate = delegates(account);
+        _delegatee[account] = delegatee;
+
+        emit DelegateChanged(account, oldDelegate, delegatee);
+        _moveDelegateVotes(oldDelegate, delegatee, _getVotingUnits(account));
+    }
+
+    /**
+     * @dev Transfers, mints, or burns voting units. To register a mint, `from` should be zero. To register a burn, `to`
+     * should be zero. Total supply of voting units will be adjusted with mints and burns.
+     */
+    function _transferVotingUnits(address from, address to, uint256 amount) internal virtual {
+        if (from == address(0)) {
+            _push(_totalCheckpoints, _add, SafeCast.toUint208(amount));
+        }
+        if (to == address(0)) {
+            _push(_totalCheckpoints, _subtract, SafeCast.toUint208(amount));
+        }
+        _moveDelegateVotes(delegates(from), delegates(to), amount);
+    }
+
+    /**
+     * @dev Moves delegated votes from one delegate to another.
+     */
+    function _moveDelegateVotes(address from, address to, uint256 amount) internal virtual {
+        if (from != to && amount > 0) {
+            if (from != address(0)) {
+                (uint256 oldValue, uint256 newValue) = _push(
+                    _delegateCheckpoints[from],
+                    _subtract,
+                    SafeCast.toUint208(amount)
+                );
+                emit DelegateVotesChanged(from, oldValue, newValue);
+            }
+            if (to != address(0)) {
+                (uint256 oldValue, uint256 newValue) = _push(
+                    _delegateCheckpoints[to],
+                    _add,
+                    SafeCast.toUint208(amount)
+                );
+                emit DelegateVotesChanged(to, oldValue, newValue);
+            }
+        }
+    }
+
+    /**
+     * @dev Get number of checkpoints for `account`.
+     */
+    function _numCheckpoints(address account) internal view virtual returns (uint32) {
+        return SafeCast.toUint32(_delegateCheckpoints[account].length());
+    }
+
+    /**
+     * @dev Get the `index`-th checkpoint for `account`.
+     */
+    function _checkpoints(
+        address account,
+        uint32 index
+    ) internal view virtual returns (Checkpoints.Checkpoint208 memory) {
+        return _delegateCheckpoints[account].pos(index);
+    }
+
+    function _push(
+        Checkpoints.Trace208 storage store,
+        function(uint208, uint208) view returns (uint208) op,
+        uint208 delta
+    ) private returns (uint208 oldValue, uint208 newValue) {
+        return store.push(clock(), op(store.latest(), delta));
+    }
+
+    function _add(uint208 a, uint208 b) private pure returns (uint208) {
+        return a + b;
+    }
+
+    function _subtract(uint208 a, uint208 b) private pure returns (uint208) {
+        return a - b;
+    }
+
+    /**
+     * @dev Must return the voting units held by an account.
+     */
+    function _getVotingUnits(address) internal view virtual returns (uint256);
+}