diff --git a/.changeset/fuzzy-crews-poke.md b/.changeset/fuzzy-crews-poke.md new file mode 100644 index 000000000..06a990f87 --- /dev/null +++ b/.changeset/fuzzy-crews-poke.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': minor +--- + +`GovernorSuperQuorum`: Add a governance extension to support a super quorum. Proposals that meet the super quorum (and have a majority of for votes) advance to the `Succeeded` state before the proposal deadline. diff --git a/.changeset/ninety-rings-suffer.md b/.changeset/ninety-rings-suffer.md new file mode 100644 index 000000000..ed02087a6 --- /dev/null +++ b/.changeset/ninety-rings-suffer.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': minor +--- + +`GovernorVotesSuperQuorumFraction`: Add a variant of the `GovernorSuperQuorum` extensions where the super quorum is expressed as a fraction of the total supply. diff --git a/contracts/governance/Governor.sol b/contracts/governance/Governor.sol index 4b67b1995..e89e749ad 100644 --- a/contracts/governance/Governor.sol +++ b/contracts/governance/Governor.sol @@ -21,9 +21,9 @@ import {IGovernor, IERC6372} from "./IGovernor.sol"; * * This contract is abstract and requires several functions to be implemented in various modules: * - * - A counting module must implement {quorum}, {_quorumReached}, {_voteSucceeded} and {_countVote} + * - A counting module must implement {_quorumReached}, {_voteSucceeded} and {_countVote} * - A voting module must implement {_getVotes} - * - Additionally, {votingPeriod} must also be implemented + * - Additionally, {votingPeriod}, {votingDelay}, and {quorum} must also be implemented */ abstract contract Governor is Context, ERC165, EIP712, Nonces, IGovernor, IERC721Receiver, IERC1155Receiver { using DoubleEndedQueue for DoubleEndedQueue.Bytes32Deque; diff --git a/contracts/governance/README.adoc b/contracts/governance/README.adoc index a9d298083..0a9c2c4e3 100644 --- a/contracts/governance/README.adoc +++ b/contracts/governance/README.adoc @@ -24,6 +24,8 @@ Votes modules determine the source of voting power, and sometimes quorum number. * {GovernorVotesQuorumFraction}: Combines with `GovernorVotes` to set the quorum as a fraction of the total token supply. +* {GovernorVotesSuperQuorumFraction}: Combines `GovernorSuperQuorum` with `GovernorVotesQuorumFraction` to set the super quorum as a fraction of the total token supply. + Counting modules determine valid voting options. * {GovernorCountingSimple}: Simple voting mechanism with 3 voting options: Against, For and Abstain. @@ -50,6 +52,8 @@ Other extensions can customize the behavior or interface in multiple ways. * {GovernorProposalGuardian}: Adds a proposal guardian that can cancel proposals at any stage in their lifecycle--this permission is passed on to the proposers if the guardian is not set. +* {GovernorSuperQuorum}: Extension of {Governor} with a super quorum. Proposals that meet the super quorum (and have a majority of for votes) advance to the `Succeeded` state before the proposal deadline. + In addition to modules and extensions, the core contract requires a few virtual functions to be implemented to your particular specifications: * <>: Delay (in ERC-6372 clock) since the proposal is submitted until voting power is fixed and voting starts. This can be used to enforce a delay after a proposal is published for users to buy tokens, or delegate their votes. @@ -76,6 +80,8 @@ NOTE: Functions of the `Governor` contract do not include access control. If you {{GovernorVotesQuorumFraction}} +{{GovernorVotesSuperQuorumFraction}} + === Extensions {{GovernorTimelockAccess}} @@ -92,6 +98,8 @@ NOTE: Functions of the `Governor` contract do not include access control. If you {{GovernorProposalGuardian}} +{{GovernorSuperQuorum}} + == Utils {{Votes}} diff --git a/contracts/governance/extensions/GovernorCountingFractional.sol b/contracts/governance/extensions/GovernorCountingFractional.sol index 958de671c..743098494 100644 --- a/contracts/governance/extensions/GovernorCountingFractional.sol +++ b/contracts/governance/extensions/GovernorCountingFractional.sol @@ -27,7 +27,7 @@ import {Math} from "../../utils/math/Math.sol"; * * Voting from an L2 with tokens held by a bridge * * Voting privately from a shielded pool using zero knowledge proofs. * - * Based on ScopeLift's GovernorCountingFractional[https://github.com/ScopeLift/flexible-voting/blob/e5de2efd1368387b840931f19f3c184c85842761/src/GovernorCountingFractional.sol] + * Based on ScopeLift's https://github.com/ScopeLift/flexible-voting/blob/e5de2efd1368387b840931f19f3c184c85842761/src/GovernorCountingFractional.sol[`GovernorCountingFractional`] * * _Available since v5.1._ */ diff --git a/contracts/governance/extensions/GovernorSuperQuorum.sol b/contracts/governance/extensions/GovernorSuperQuorum.sol new file mode 100644 index 000000000..b9a7c68e7 --- /dev/null +++ b/contracts/governance/extensions/GovernorSuperQuorum.sol @@ -0,0 +1,59 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {Governor} from "../Governor.sol"; +import {SafeCast} from "../../utils/math/SafeCast.sol"; +import {Checkpoints} from "../../utils/structs/Checkpoints.sol"; + +/** + * @dev Extension of {Governor} with a super quorum. Proposals that meet the super quorum (and have a majority of for + * votes) advance to the `Succeeded` state before the proposal deadline. Counting modules that want to use this + * extension must implement {proposalVotes}. + */ +abstract contract GovernorSuperQuorum is Governor { + /** + * @dev Minimum number of cast votes required for a proposal to reach super quorum. Only FOR votes are counted + * towards the super quorum. Once the super quorum is reached, an active proposal can proceed to the next state + * without waiting for the proposal deadline. + * + * NOTE: The `timepoint` parameter corresponds to the snapshot used for counting the vote. This enables scaling of the + * quorum depending on values such as the `totalSupply` of a token at this timepoint (see {ERC20Votes}). + * + * NOTE: Make sure the value specified for the super quorum is greater than {quorum}, otherwise, it may be + * possible to pass a proposal with less votes than the default quorum. + */ + function superQuorum(uint256 timepoint) public view virtual returns (uint256); + + /** + * @dev Accessor to the internal vote counts. This must be implemented by the counting module. Counting modules + * that don't implement this function are incompatible with this module + */ + function proposalVotes( + uint256 proposalId + ) public view virtual returns (uint256 againstVotes, uint256 forVotes, uint256 abstainVotes); + + /** + * @dev Overridden version of the {Governor-state} function that checks if the proposal has reached the super + * quorum. + * + * NOTE: If the proposal reaches super quorum but {_voteSucceeded} returns false, eg, assuming the super quorum + * has been set low enough that both FOR and AGAINST votes have exceeded it and AGAINST votes exceed FOR votes, + * the proposal continues to be active until {_voteSucceeded} returns true or the proposal deadline is reached. + * This means that with a low super quorum it is also possible that a vote can succeed prematurely before enough + * AGAINST voters have a chance to vote. Hence, it is recommended to set a high enough super quorum to avoid these + * types of scenarios. + */ + function state(uint256 proposalId) public view virtual override returns (ProposalState) { + ProposalState currentState = super.state(proposalId); + if (currentState != ProposalState.Active) return currentState; + + (, uint256 forVotes, ) = proposalVotes(proposalId); + if (forVotes < superQuorum(proposalSnapshot(proposalId)) || !_voteSucceeded(proposalId)) { + return ProposalState.Active; + } else if (proposalEta(proposalId) == 0) { + return ProposalState.Succeeded; + } else { + return ProposalState.Queued; + } + } +} diff --git a/contracts/governance/extensions/GovernorVotesQuorumFraction.sol b/contracts/governance/extensions/GovernorVotesQuorumFraction.sol index 85a1f9826..ddaf64f07 100644 --- a/contracts/governance/extensions/GovernorVotesQuorumFraction.sol +++ b/contracts/governance/extensions/GovernorVotesQuorumFraction.sol @@ -4,6 +4,7 @@ pragma solidity ^0.8.20; import {GovernorVotes} from "./GovernorVotes.sol"; +import {Math} from "../../utils/math/Math.sol"; import {SafeCast} from "../../utils/math/SafeCast.sol"; import {Checkpoints} from "../../utils/structs/Checkpoints.sol"; @@ -45,18 +46,7 @@ abstract contract GovernorVotesQuorumFraction is GovernorVotes { * @dev Returns the quorum numerator at a specific timepoint. See {quorumDenominator}. */ function quorumNumerator(uint256 timepoint) public view virtual returns (uint256) { - uint256 length = _quorumNumeratorHistory._checkpoints.length; - - // Optimistic search, check the latest checkpoint - Checkpoints.Checkpoint208 storage latest = _quorumNumeratorHistory._checkpoints[length - 1]; - uint48 latestKey = latest._key; - uint208 latestValue = latest._value; - if (latestKey <= timepoint) { - return latestValue; - } - - // Otherwise, do the binary search - return _quorumNumeratorHistory.upperLookupRecent(SafeCast.toUint48(timepoint)); + return _optimisticUpperLookupRecent(_quorumNumeratorHistory, timepoint); } /** @@ -70,7 +60,7 @@ abstract contract GovernorVotesQuorumFraction is GovernorVotes { * @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 (token().getPastTotalSupply(timepoint) * quorumNumerator(timepoint)) / quorumDenominator(); + return Math.mulDiv(token().getPastTotalSupply(timepoint), quorumNumerator(timepoint), quorumDenominator()); } /** @@ -107,4 +97,17 @@ abstract contract GovernorVotesQuorumFraction is GovernorVotes { 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)); + } } diff --git a/contracts/governance/extensions/GovernorVotesSuperQuorumFraction.sol b/contracts/governance/extensions/GovernorVotesSuperQuorumFraction.sol new file mode 100644 index 000000000..426738951 --- /dev/null +++ b/contracts/governance/extensions/GovernorVotesSuperQuorumFraction.sol @@ -0,0 +1,132 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {Governor} from "../Governor.sol"; +import {GovernorSuperQuorum} from "./GovernorSuperQuorum.sol"; +import {GovernorVotesQuorumFraction} from "./GovernorVotesQuorumFraction.sol"; +import {Math} from "../../utils/math/Math.sol"; +import {SafeCast} from "../../utils/math/SafeCast.sol"; +import {Checkpoints} from "../../utils/structs/Checkpoints.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 or equal to 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 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`. + */ + 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); + } +} diff --git a/contracts/mocks/governance/GovernorSuperQuorumMock.sol b/contracts/mocks/governance/GovernorSuperQuorumMock.sol new file mode 100644 index 000000000..2a48dbb7c --- /dev/null +++ b/contracts/mocks/governance/GovernorSuperQuorumMock.sol @@ -0,0 +1,95 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Governor} from "../../governance/Governor.sol"; +import {GovernorSettings} from "../../governance/extensions/GovernorSettings.sol"; +import {GovernorVotes} from "../../governance/extensions/GovernorVotes.sol"; +import {GovernorSuperQuorum} from "../../governance/extensions/GovernorSuperQuorum.sol"; +import {GovernorCountingSimple} from "../../governance/extensions/GovernorCountingSimple.sol"; +import {GovernorTimelockControl} from "../../governance/extensions/GovernorTimelockControl.sol"; + +abstract contract GovernorSuperQuorumMock is + GovernorSettings, + GovernorVotes, + GovernorTimelockControl, + GovernorSuperQuorum, + GovernorCountingSimple +{ + uint256 private _quorum; + uint256 private _superQuorum; + + constructor(uint256 quorum_, uint256 superQuorum_) { + _quorum = quorum_; + _superQuorum = superQuorum_; + } + + function quorum(uint256) public view override returns (uint256) { + return _quorum; + } + + function superQuorum(uint256) public view override returns (uint256) { + return _superQuorum; + } + + function state( + uint256 proposalId + ) public view override(Governor, GovernorSuperQuorum, GovernorTimelockControl) returns (ProposalState) { + return super.state(proposalId); + } + + function proposalThreshold() public view override(Governor, GovernorSettings) returns (uint256) { + return super.proposalThreshold(); + } + + function proposalVotes( + uint256 proposalId + ) + public + view + virtual + override(GovernorCountingSimple, GovernorSuperQuorum) + returns (uint256 againstVotes, uint256 forVotes, uint256 abstainVotes) + { + return super.proposalVotes(proposalId); + } + + function _cancel( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockControl) returns (uint256) { + return super._cancel(targets, values, calldatas, descriptionHash); + } + + function _executeOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockControl) { + super._executeOperations(proposalId, targets, values, calldatas, descriptionHash); + } + + function _executor() internal view override(Governor, GovernorTimelockControl) returns (address) { + return super._executor(); + } + + function _queueOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockControl) returns (uint48) { + return super._queueOperations(proposalId, targets, values, calldatas, descriptionHash); + } + + function proposalNeedsQueuing( + uint256 proposalId + ) public view override(Governor, GovernorTimelockControl) returns (bool) { + return super.proposalNeedsQueuing(proposalId); + } +} diff --git a/contracts/mocks/governance/GovernorVotesSuperQuorumFractionMock.sol b/contracts/mocks/governance/GovernorVotesSuperQuorumFractionMock.sol new file mode 100644 index 000000000..4967b033b --- /dev/null +++ b/contracts/mocks/governance/GovernorVotesSuperQuorumFractionMock.sol @@ -0,0 +1,37 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Governor} from "../../governance/Governor.sol"; +import {GovernorSettings} from "../../governance/extensions/GovernorSettings.sol"; +import {GovernorSuperQuorum} from "../../governance/extensions/GovernorSuperQuorum.sol"; +import {GovernorCountingSimple} from "../../governance/extensions/GovernorCountingSimple.sol"; +import {GovernorVotesSuperQuorumFraction} from "../../governance/extensions/GovernorVotesSuperQuorumFraction.sol"; + +abstract contract GovernorVotesSuperQuorumFractionMock is + GovernorSettings, + GovernorVotesSuperQuorumFraction, + GovernorCountingSimple +{ + function proposalThreshold() public view override(Governor, GovernorSettings) returns (uint256) { + return super.proposalThreshold(); + } + + function proposalVotes( + uint256 proposalId + ) + public + view + virtual + override(GovernorCountingSimple, GovernorSuperQuorum) + returns (uint256 againstVotes, uint256 forVotes, uint256 abstainVotes) + { + return super.proposalVotes(proposalId); + } + + function state( + uint256 proposalId + ) public view override(Governor, GovernorVotesSuperQuorumFraction) returns (ProposalState) { + return super.state(proposalId); + } +} diff --git a/test/governance/extensions/GovernorSuperQuorum.test.js b/test/governance/extensions/GovernorSuperQuorum.test.js new file mode 100644 index 000000000..9a8b8455c --- /dev/null +++ b/test/governance/extensions/GovernorSuperQuorum.test.js @@ -0,0 +1,168 @@ +const { ethers } = require('hardhat'); +const { expect } = require('chai'); +const { loadFixture } = require('@nomicfoundation/hardhat-network-helpers'); + +const { GovernorHelper } = require('../../helpers/governance'); +const { ProposalState, VoteType } = require('../../helpers/enums'); +const time = require('../../helpers/time'); + +const TOKENS = [ + { Token: '$ERC20Votes', mode: 'blocknumber' }, + { Token: '$ERC20VotesTimestampMock', mode: 'timestamp' }, +]; + +const DEFAULT_ADMIN_ROLE = ethers.ZeroHash; +const PROPOSER_ROLE = ethers.id('PROPOSER_ROLE'); +const EXECUTOR_ROLE = ethers.id('EXECUTOR_ROLE'); +const CANCELLER_ROLE = ethers.id('CANCELLER_ROLE'); + +const name = 'OZ-Governor'; +const version = '1'; +const tokenName = 'MockToken'; +const tokenSymbol = 'MTKN'; +const tokenSupply = ethers.parseEther('100'); +const votingDelay = 4n; +const votingPeriod = 16n; +const quorum = 10n; +const superQuorum = 40n; +const value = ethers.parseEther('1'); +const delay = time.duration.hours(1n); + +describe('GovernorSuperQuorum', function () { + for (const { Token, mode } of TOKENS) { + const fixture = async () => { + const [proposer, voter1, voter2, voter3, voter4, voter5] = await ethers.getSigners(); + const receiver = await ethers.deployContract('CallReceiverMock'); + + const timelock = await ethers.deployContract('TimelockController', [delay, [], [], proposer]); + const token = await ethers.deployContract(Token, [tokenName, tokenSymbol, tokenName, version]); + const mock = await ethers.deployContract('$GovernorSuperQuorumMock', [ + name, + votingDelay, // initialVotingDelay + votingPeriod, // initialVotingPeriod + 0n, // initialProposalThreshold + token, + timelock, + quorum, + superQuorum, + ]); + + await proposer.sendTransaction({ to: timelock, value }); + await token.$_mint(proposer, tokenSupply); + await timelock.grantRole(PROPOSER_ROLE, mock); + await timelock.grantRole(PROPOSER_ROLE, proposer); + await timelock.grantRole(CANCELLER_ROLE, mock); + await timelock.grantRole(CANCELLER_ROLE, proposer); + await timelock.grantRole(EXECUTOR_ROLE, ethers.ZeroAddress); + await timelock.revokeRole(DEFAULT_ADMIN_ROLE, proposer); + + const helper = new GovernorHelper(mock, mode); + await helper.connect(proposer).delegate({ token, to: voter1, value: 40 }); + await helper.connect(proposer).delegate({ token, to: voter2, value: 30 }); + await helper.connect(proposer).delegate({ token, to: voter3, value: 20 }); + await helper.connect(proposer).delegate({ token, to: voter4, value: 15 }); + await helper.connect(proposer).delegate({ token, to: voter5, value: 5 }); + + return { proposer, voter1, voter2, voter3, voter4, voter5, receiver, token, mock, timelock, helper }; + }; + + describe(`using ${Token}`, function () { + beforeEach(async function () { + Object.assign(this, await loadFixture(fixture)); + + // default proposal + this.proposal = this.helper.setProposal( + [ + { + target: this.receiver.target, + value, + data: this.receiver.interface.encodeFunctionData('mockFunction'), + }, + ], + '', + ); + }); + + it('deployment check', async function () { + await expect(this.mock.name()).to.eventually.equal(name); + await expect(this.mock.token()).to.eventually.equal(this.token); + await expect(this.mock.quorum(0)).to.eventually.equal(quorum); + await expect(this.mock.superQuorum(0)).to.eventually.equal(superQuorum); + }); + + it('proposal succeeds early when super quorum is reached', async function () { + await this.helper.connect(this.proposer).propose(); + await this.helper.waitForSnapshot(); + + // Vote with voter2 (30) - above quorum (10) but below super quorum (40) + await this.helper.connect(this.voter2).vote({ support: VoteType.For }); + await expect(this.mock.state(this.proposal.id)).to.eventually.equal(ProposalState.Active); + + // Vote with voter3 (20) to reach super quorum (50 total > 40) + await this.helper.connect(this.voter3).vote({ support: VoteType.For }); + + await expect(this.mock.proposalEta(this.proposal.id)).to.eventually.equal(0); + + // Should be succeeded since we reached super quorum and no eta is set + await expect(this.mock.state(this.proposal.id)).to.eventually.equal(ProposalState.Succeeded); + }); + + it('proposal remains active if super quorum is not reached', async function () { + await this.helper.connect(this.proposer).propose(); + await this.helper.waitForSnapshot(); + + // Vote with voter4 (15) - below super quorum (40) but above quorum (10) + await this.helper.connect(this.voter4).vote({ support: VoteType.For }); + await expect(this.mock.state(this.proposal.id)).to.eventually.equal(ProposalState.Active); + + // Vote with voter5 (5) - still below super quorum (total 20 < 40) + await this.helper.connect(this.voter5).vote({ support: VoteType.For }); + await expect(this.mock.state(this.proposal.id)).to.eventually.equal(ProposalState.Active); + + // Wait for deadline + await this.helper.waitForDeadline(1n); + + // Should succeed since deadline passed and we have enough support (20 > 10 quorum) + await expect(this.mock.state(this.proposal.id)).to.eventually.equal(ProposalState.Succeeded); + }); + + it('proposal remains active if super quorum is reached but vote fails', async function () { + await this.helper.connect(this.proposer).propose(); + await this.helper.waitForSnapshot(); + + // Vote against with voter2 and voter3 (50) + await this.helper.connect(this.voter2).vote({ support: VoteType.Against }); + await this.helper.connect(this.voter3).vote({ support: VoteType.Against }); + + // Vote for with voter1 (40) (reaching super quorum) + await this.helper.connect(this.voter1).vote({ support: VoteType.For }); + + // should be active since super quorum is reached but vote fails + await expect(this.mock.state(this.proposal.id)).to.eventually.equal(ProposalState.Active); + + // wait for deadline + await this.helper.waitForDeadline(1n); + + // should be defeated since against votes are higher + await expect(this.mock.state(this.proposal.id)).to.eventually.equal(ProposalState.Defeated); + }); + + it('proposal is queued if super quorum is reached and eta is set', async function () { + await this.helper.connect(this.proposer).propose(); + + await this.helper.waitForSnapshot(); + + // Vote with voter1 (40) - reaching super quorum + await this.helper.connect(this.voter1).vote({ support: VoteType.For }); + + await this.helper.queue(); + + // Queueing should set eta + await expect(this.mock.proposalEta(this.proposal.id)).to.eventually.not.equal(0); + + // Should be queued since we reached super quorum and eta is set + await expect(this.mock.state(this.proposal.id)).to.eventually.equal(ProposalState.Queued); + }); + }); + } +}); diff --git a/test/governance/extensions/GovernorSuperQuorumGreaterThanQuorum.t.sol b/test/governance/extensions/GovernorSuperQuorumGreaterThanQuorum.t.sol new file mode 100644 index 000000000..eb0409c8e --- /dev/null +++ b/test/governance/extensions/GovernorSuperQuorumGreaterThanQuorum.t.sol @@ -0,0 +1,79 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Test} from "forge-std/Test.sol"; +import {GovernorVotesSuperQuorumFractionMock} from "../../../contracts/mocks/governance/GovernorVotesSuperQuorumFractionMock.sol"; +import {GovernorVotesQuorumFraction} from "../../../contracts/governance/extensions/GovernorVotesQuorumFraction.sol"; +import {GovernorVotesSuperQuorumFraction} from "../../../contracts/governance/extensions/GovernorVotesSuperQuorumFraction.sol"; +import {GovernorSettings} from "../../../contracts/governance/extensions/GovernorSettings.sol"; +import {GovernorVotes} from "../../../contracts/governance/extensions/GovernorVotes.sol"; +import {Governor} from "../../../contracts/governance/Governor.sol"; +import {IVotes} from "../../../contracts/governance/utils/IVotes.sol"; +import {ERC20VotesExtendedTimestampMock} from "../../../contracts/mocks/token/ERC20VotesAdditionalCheckpointsMock.sol"; +import {EIP712} from "../../../contracts/utils/cryptography/EIP712.sol"; +import {ERC20} from "../../../contracts/token/ERC20/ERC20.sol"; + +contract TokenMock is ERC20VotesExtendedTimestampMock { + constructor() ERC20("Mock Token", "MTK") EIP712("Mock Token", "1") {} +} + +/** + * Main responsibility: expose the functions that are relevant to the simulation + */ +contract GovernorHandler is GovernorVotesSuperQuorumFractionMock { + constructor( + string memory name_, + uint48 votingDelay_, + uint32 votingPeriod_, + uint256 proposalThreshold_, + IVotes token_, + uint256 quorumNumerator_, + uint256 superQuorumNumerator_ + ) + Governor(name_) + GovernorSettings(votingDelay_, votingPeriod_, proposalThreshold_) + GovernorVotes(token_) + GovernorVotesQuorumFraction(quorumNumerator_) + GovernorVotesSuperQuorumFraction(superQuorumNumerator_) + {} + + // solhint-disable-next-line func-name-mixedcase + function $_updateSuperQuorumNumerator(uint256 newSuperQuorumNumerator) public { + _updateSuperQuorumNumerator(newSuperQuorumNumerator); + } + + // solhint-disable-next-line func-name-mixedcase + function $_updateQuorumNumerator(uint256 newQuorumNumerator) public { + _updateQuorumNumerator(newQuorumNumerator); + } +} + +contract GovernorSuperQuorumGreaterThanQuorum is Test { + GovernorHandler private _governorHandler; + + function setUp() external { + _governorHandler = new GovernorHandler( + "GovernorName", + 0, // votingDelay + 1e4, // votingPeriod + 0, // proposalThreshold + new TokenMock(), // token + 10, // quorumNumerator + 50 // superQuorumNumerator + ); + + // limit the fuzzer scope + bytes4[] memory selectors = new bytes4[](2); + selectors[0] = GovernorHandler.$_updateSuperQuorumNumerator.selector; + selectors[1] = GovernorHandler.$_updateQuorumNumerator.selector; + + targetContract(address(_governorHandler)); + targetSelector(FuzzSelector(address(_governorHandler), selectors)); + } + + // solhint-disable-next-line func-name-mixedcase + function invariant_superQuorumGreaterThanQuorum() external view { + assertGe(_governorHandler.superQuorumNumerator(), _governorHandler.quorumNumerator()); + } +} diff --git a/test/governance/extensions/GovernorVotesSuperQuorumFraction.test.js b/test/governance/extensions/GovernorVotesSuperQuorumFraction.test.js new file mode 100644 index 000000000..25539cd3d --- /dev/null +++ b/test/governance/extensions/GovernorVotesSuperQuorumFraction.test.js @@ -0,0 +1,160 @@ +const { ethers } = require('hardhat'); +const { expect } = require('chai'); +const { loadFixture } = require('@nomicfoundation/hardhat-network-helpers'); + +const { GovernorHelper } = require('../../helpers/governance'); +const { ProposalState, VoteType } = require('../../helpers/enums'); +const time = require('../../helpers/time'); + +const TOKENS = [ + { Token: '$ERC20Votes', mode: 'blocknumber' }, + { Token: '$ERC20VotesTimestampMock', mode: 'timestamp' }, +]; + +const name = 'OZ-Governor'; +const version = '1'; +const tokenName = 'MockToken'; +const tokenSymbol = 'MTKN'; +const tokenSupply = ethers.parseEther('100'); +const quorumRatio = 8n; // percents +const superQuorumRatio = 50n; // percents +const newSuperQuorumRatio = 15n; // percents +const votingDelay = 4n; +const votingPeriod = 16n; +const value = ethers.parseEther('1'); + +describe('GovernorVotesSuperQuorumFraction', function () { + for (const { Token, mode } of TOKENS) { + const fixture = async () => { + const [owner, voter1, voter2, voter3, voter4] = await ethers.getSigners(); + const receiver = await ethers.deployContract('CallReceiverMock'); + + const token = await ethers.deployContract(Token, [tokenName, tokenSymbol, tokenName, version]); + const mock = await ethers.deployContract('$GovernorVotesSuperQuorumFractionMock', [ + name, + votingDelay, + votingPeriod, + 0n, + token, + quorumRatio, + superQuorumRatio, + ]); + + await owner.sendTransaction({ to: mock, value }); + await token.$_mint(owner, tokenSupply); + + const helper = new GovernorHelper(mock, mode); + await helper.connect(owner).delegate({ token, to: voter1, value: ethers.parseEther('30') }); + await helper.connect(owner).delegate({ token, to: voter2, value: ethers.parseEther('20') }); + await helper.connect(owner).delegate({ token, to: voter3, value: ethers.parseEther('15') }); + await helper.connect(owner).delegate({ token, to: voter4, value: ethers.parseEther('5') }); + + return { owner, voter1, voter2, voter3, voter4, receiver, token, mock, helper }; + }; + + describe(`using ${Token}`, function () { + beforeEach(async function () { + Object.assign(this, await loadFixture(fixture)); + + // default proposal + this.proposal = this.helper.setProposal( + [ + { + target: this.receiver.target, + value, + data: this.receiver.interface.encodeFunctionData('mockFunction'), + }, + ], + '', + ); + }); + + it('deployment check', async function () { + await expect(this.mock.name()).to.eventually.eventually.equal(name); + await expect(this.mock.token()).to.eventually.equal(this.token); + await expect(this.mock.votingDelay()).to.eventually.equal(votingDelay); + await expect(this.mock.votingPeriod()).to.eventually.equal(votingPeriod); + await expect(this.mock.quorumNumerator()).to.eventually.equal(quorumRatio); + await expect(this.mock.superQuorumNumerator()).to.eventually.equal(superQuorumRatio); + await expect(this.mock.quorumDenominator()).to.eventually.equal(100n); + await expect(time.clock[mode]().then(clock => this.mock.superQuorum(clock - 1n))).to.eventually.equal( + (tokenSupply * superQuorumRatio) / 100n, + ); + }); + + it('proposal remains active until super quorum is reached', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + + // Vote with voter1 (30%) - above quorum (8%) but below super quorum (50%) + await this.helper.connect(this.voter1).vote({ support: VoteType.For }); + + // Check proposal is still active + await expect(this.mock.state(this.proposal.id)).to.eventually.equal(ProposalState.Active); + + // Vote with voter2 (20%) - now matches super quorum + await this.helper.connect(this.voter2).vote({ support: VoteType.For }); + + // Proposal should no longer be active + await expect(this.mock.state(this.proposal.id)).to.eventually.equal(ProposalState.Succeeded); + }); + + describe('super quorum updates', function () { + it('updateSuperQuorumNumerator is protected', async function () { + await expect(this.mock.connect(this.owner).updateSuperQuorumNumerator(newSuperQuorumRatio)) + .to.be.revertedWithCustomError(this.mock, 'GovernorOnlyExecutor') + .withArgs(this.owner); + }); + + it('can update super quorum through governance', async function () { + this.helper.setProposal( + [ + { + target: this.mock.target, + data: this.mock.interface.encodeFunctionData('updateSuperQuorumNumerator', [newSuperQuorumRatio]), + }, + ], + '', + ); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.connect(this.voter1).vote({ support: VoteType.For }); + await this.helper.connect(this.voter2).vote({ support: VoteType.For }); + await this.helper.waitForDeadline(); + + await expect(this.helper.execute()) + .to.emit(this.mock, 'SuperQuorumNumeratorUpdated') + .withArgs(superQuorumRatio, newSuperQuorumRatio); + + await expect(this.mock.superQuorumNumerator()).to.eventually.equal(newSuperQuorumRatio); + }); + + it('cannot set super quorum below quorum', async function () { + const invalidSuperQuorum = quorumRatio - 1n; + + await expect(this.mock.$_updateSuperQuorumNumerator(invalidSuperQuorum)) + .to.be.revertedWithCustomError(this.mock, 'GovernorInvalidSuperQuorumTooSmall') + .withArgs(invalidSuperQuorum, quorumRatio); + }); + + it('cannot set super quorum above denominator', async function () { + const denominator = await this.mock.quorumDenominator(); + const invalidSuperQuorum = BigInt(denominator) + 1n; + + await expect(this.mock.$_updateSuperQuorumNumerator(invalidSuperQuorum)) + .to.be.revertedWithCustomError(this.mock, 'GovernorInvalidSuperQuorumFraction') + .withArgs(invalidSuperQuorum, denominator); + }); + + it('cannot set quorum above super quorum', async function () { + const invalidQuorum = superQuorumRatio + 1n; + + await expect(this.mock.$_updateQuorumNumerator(invalidQuorum)) + .to.be.revertedWithCustomError(this.mock, 'GovernorInvalidQuorumTooLarge') + .withArgs(invalidQuorum, superQuorumRatio); + }); + }); + }); + } +});