Add a governance extension that implements super quorum (#5492)

Co-authored-by: Hadrien Croubois <hadrien.croubois@gmail.com>
Co-authored-by: Arr00 <13561405+arr00@users.noreply.github.com>

.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.

.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.

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;

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:
 
 * <<Governor-votingDelay-,`votingDelay()`>>: 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}}

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._
  */

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;
+        }
+    }
+}

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));
+    }
 }

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);
+    }
+}

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);
+    }
+}

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);
+    }
+}

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'),
+            },
+          ],
+          '<proposal description>',
+        );
+      });
+
+      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);
+      });
+    });
+  }
+});

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());
+    }
+}

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'),
+            },
+          ],
+          '<proposal description>',
+        );
+      });
+
+      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]),
+              },
+            ],
+            '<proposal description>',
+          );
+
+          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);
+        });
+      });
+    });
+  }
+});