|
| 1 | +// SPDX-License-Identifier: MIT |
| 2 | + |
| 3 | +pragma solidity ^0.8.20; |
| 4 | + |
| 5 | +import {Governor} from "../Governor.sol"; |
| 6 | +import {GovernorCountingSimple} from "./GovernorCountingSimple.sol"; |
| 7 | +import {Math} from "../../utils/math/Math.sol"; |
| 8 | + |
| 9 | +/** |
| 10 | + * @dev Extension of {Governor} for fractional voting. |
| 11 | + * |
| 12 | + * Similar to {GovernorCountingSimple}, this contract is a votes counting module for {Governor} that supports 3 options: |
| 13 | + * Against, For, Abstain. Additionally, it includes a fourth option: Fractional, which allows voters to split their voting |
| 14 | + * power amongst the other 3 options. |
| 15 | + * |
| 16 | + * Votes cast with the Fractional support must be accompanied by a `params` argument that is three packed `uint128` values |
| 17 | + * representing the weight the delegate assigns to Against, For, and Abstain respectively. For those votes cast for the other |
| 18 | + * 3 options, the `params` argument must be empty. |
| 19 | + * |
| 20 | + * This is mostly useful when the delegate is a contract that implements its own rules for voting. These delegate-contracts |
| 21 | + * can cast fractional votes according to the preferences of multiple entities delegating their voting power. |
| 22 | + * |
| 23 | + * Some example use cases include: |
| 24 | + * |
| 25 | + * * Voting from tokens that are held by a DeFi pool |
| 26 | + * * Voting from an L2 with tokens held by a bridge |
| 27 | + * * Voting privately from a shielded pool using zero knowledge proofs. |
| 28 | + * |
| 29 | + * Based on ScopeLift's GovernorCountingFractional[https://github.com/ScopeLift/flexible-voting/blob/e5de2efd1368387b840931f19f3c184c85842761/src/GovernorCountingFractional.sol] |
| 30 | + */ |
| 31 | +abstract contract GovernorCountingFractional is Governor { |
| 32 | + using Math for *; |
| 33 | + |
| 34 | + uint8 internal constant VOTE_TYPE_FRACTIONAL = 255; |
| 35 | + |
| 36 | + struct ProposalVote { |
| 37 | + uint256 againstVotes; |
| 38 | + uint256 forVotes; |
| 39 | + uint256 abstainVotes; |
| 40 | + mapping(address voter => uint256) usedVotes; |
| 41 | + } |
| 42 | + |
| 43 | + /** |
| 44 | + * @dev Mapping from proposal ID to vote tallies for that proposal. |
| 45 | + */ |
| 46 | + mapping(uint256 => ProposalVote) private _proposalVotes; |
| 47 | + |
| 48 | + /** |
| 49 | + * @dev A fractional vote params uses more votes than are available for that user. |
| 50 | + */ |
| 51 | + error GovernorExceedRemainingWeight(address voter, uint256 usedVotes, uint256 remainingWeight); |
| 52 | + |
| 53 | + /** |
| 54 | + * @dev See {IGovernor-COUNTING_MODE}. |
| 55 | + */ |
| 56 | + // solhint-disable-next-line func-name-mixedcase |
| 57 | + function COUNTING_MODE() public pure virtual override returns (string memory) { |
| 58 | + return "support=bravo,fractional&quorum=for,abstain¶ms=fractional"; |
| 59 | + } |
| 60 | + |
| 61 | + /** |
| 62 | + * @dev See {IGovernor-hasVoted}. |
| 63 | + */ |
| 64 | + function hasVoted(uint256 proposalId, address account) public view virtual override returns (bool) { |
| 65 | + return usedVotes(proposalId, account) > 0; |
| 66 | + } |
| 67 | + |
| 68 | + /** |
| 69 | + * @dev Get the number of votes already cast by `account` for a proposal with `proposalId`. Useful for |
| 70 | + * integrations that allow delegates to cast rolling, partial votes. |
| 71 | + */ |
| 72 | + function usedVotes(uint256 proposalId, address account) public view virtual returns (uint256) { |
| 73 | + return _proposalVotes[proposalId].usedVotes[account]; |
| 74 | + } |
| 75 | + |
| 76 | + /** |
| 77 | + * @dev Get current distribution of votes for a given proposal. |
| 78 | + */ |
| 79 | + function proposalVotes( |
| 80 | + uint256 proposalId |
| 81 | + ) public view virtual returns (uint256 againstVotes, uint256 forVotes, uint256 abstainVotes) { |
| 82 | + ProposalVote storage proposalVote = _proposalVotes[proposalId]; |
| 83 | + return (proposalVote.againstVotes, proposalVote.forVotes, proposalVote.abstainVotes); |
| 84 | + } |
| 85 | + |
| 86 | + /** |
| 87 | + * @dev See {Governor-_quorumReached}. |
| 88 | + */ |
| 89 | + function _quorumReached(uint256 proposalId) internal view virtual override returns (bool) { |
| 90 | + ProposalVote storage proposalVote = _proposalVotes[proposalId]; |
| 91 | + return quorum(proposalSnapshot(proposalId)) <= proposalVote.forVotes + proposalVote.abstainVotes; |
| 92 | + } |
| 93 | + |
| 94 | + /** |
| 95 | + * @dev See {Governor-_voteSucceeded}. In this module, forVotes must be > againstVotes. |
| 96 | + */ |
| 97 | + function _voteSucceeded(uint256 proposalId) internal view virtual override returns (bool) { |
| 98 | + ProposalVote storage proposalVote = _proposalVotes[proposalId]; |
| 99 | + return proposalVote.forVotes > proposalVote.againstVotes; |
| 100 | + } |
| 101 | + |
| 102 | + /** |
| 103 | + * @dev See {Governor-_countVote}. Function that records the delegate's votes. |
| 104 | + * |
| 105 | + * Executing this function consumes (part of) the delegate's weight on the proposal. This weight can be |
| 106 | + * distributed amongst the 3 options (Against, For, Abstain) by specifying a fractional `support`. |
| 107 | + * |
| 108 | + * This counting module supports two vote casting modes: nominal and fractional. |
| 109 | + * |
| 110 | + * - Nominal: A nominal vote is cast by setting `support` to one of the 3 bravo options (Against, For, Abstain). |
| 111 | + * - Fractional: A fractional vote is cast by setting `support` to `type(uint8).max` (255). |
| 112 | + * |
| 113 | + * Casting a nominal vote requires `params` to be empty and consumes the delegate's full remaining weight on the |
| 114 | + * proposal for the specified `support` option. This is similar to the {GovernorCountingSimple} module and follows |
| 115 | + * the `VoteType` enum from Governor Bravo. As a consequence, no vote weight remains unspent so no further voting |
| 116 | + * is possible (for this `proposalId` and this `account`). |
| 117 | + * |
| 118 | + * Casting a fractional vote consumes a fraction of the delegate's remaining weight on the proposal according to the |
| 119 | + * weights the delegate assigns to each support option (Against, For, Abstain respectively). The sum total of the |
| 120 | + * three decoded vote weights _must_ be less than or equal to the delegate's remaining weight on the proposal (i.e. |
| 121 | + * their checkpointed total weight minus votes already cast on the proposal). This format can be produced using: |
| 122 | + * |
| 123 | + * `abi.encodePacked(uint128(againstVotes), uint128(forVotes), uint128(abstainVotes))` |
| 124 | + * |
| 125 | + * NOTE: Consider that fractional voting restricts the number of casted vote (in each category) to 128 bits. |
| 126 | + * Depending on how many decimals the underlying token has, a single voter may require to split their vote into |
| 127 | + * multiple vote operations. For precision higher than ~30 decimals, large token holders may require an |
| 128 | + * potentially large number of calls to cast all their votes. The voter has the possibility to cast all the |
| 129 | + * remaining votes in a single operation using the traditional "bravo" vote. |
| 130 | + */ |
| 131 | + // slither-disable-next-line cyclomatic-complexity |
| 132 | + function _countVote( |
| 133 | + uint256 proposalId, |
| 134 | + address account, |
| 135 | + uint8 support, |
| 136 | + uint256 totalWeight, |
| 137 | + bytes memory params |
| 138 | + ) internal virtual override returns (uint256) { |
| 139 | + // Compute number of remaining votes. Returns 0 on overflow. |
| 140 | + (, uint256 remainingWeight) = totalWeight.trySub(usedVotes(proposalId, account)); |
| 141 | + if (remainingWeight == 0) { |
| 142 | + revert GovernorAlreadyCastVote(account); |
| 143 | + } |
| 144 | + |
| 145 | + uint256 againstVotes = 0; |
| 146 | + uint256 forVotes = 0; |
| 147 | + uint256 abstainVotes = 0; |
| 148 | + uint256 usedWeight; |
| 149 | + |
| 150 | + // For clarity of event indexing, fractional voting must be clearly advertised in the "support" field. |
| 151 | + // |
| 152 | + // Supported `support` value must be: |
| 153 | + // - "Full" voting: `support = 0` (Against), `1` (For) or `2` (Abstain), with empty params. |
| 154 | + // - "Fractional" voting: `support = 255`, with 48 bytes params. |
| 155 | + if (support == uint8(GovernorCountingSimple.VoteType.Against)) { |
| 156 | + if (params.length != 0) revert GovernorInvalidVoteParams(); |
| 157 | + usedWeight = againstVotes = remainingWeight; |
| 158 | + } else if (support == uint8(GovernorCountingSimple.VoteType.For)) { |
| 159 | + if (params.length != 0) revert GovernorInvalidVoteParams(); |
| 160 | + usedWeight = forVotes = remainingWeight; |
| 161 | + } else if (support == uint8(GovernorCountingSimple.VoteType.Abstain)) { |
| 162 | + if (params.length != 0) revert GovernorInvalidVoteParams(); |
| 163 | + usedWeight = abstainVotes = remainingWeight; |
| 164 | + } else if (support == VOTE_TYPE_FRACTIONAL) { |
| 165 | + // The `params` argument is expected to be three packed `uint128`: |
| 166 | + // `abi.encodePacked(uint128(againstVotes), uint128(forVotes), uint128(abstainVotes))` |
| 167 | + if (params.length != 0x30) revert GovernorInvalidVoteParams(); |
| 168 | + |
| 169 | + assembly ("memory-safe") { |
| 170 | + againstVotes := shr(128, mload(add(params, 0x20))) |
| 171 | + forVotes := shr(128, mload(add(params, 0x30))) |
| 172 | + abstainVotes := shr(128, mload(add(params, 0x40))) |
| 173 | + usedWeight := add(add(againstVotes, forVotes), abstainVotes) // inputs are uint128: cannot overflow |
| 174 | + } |
| 175 | + |
| 176 | + // check parsed arguments are valid |
| 177 | + if (usedWeight > remainingWeight) { |
| 178 | + revert GovernorExceedRemainingWeight(account, usedWeight, remainingWeight); |
| 179 | + } |
| 180 | + } else { |
| 181 | + revert GovernorInvalidVoteType(); |
| 182 | + } |
| 183 | + |
| 184 | + // update votes tracking |
| 185 | + ProposalVote storage details = _proposalVotes[proposalId]; |
| 186 | + if (againstVotes > 0) details.againstVotes += againstVotes; |
| 187 | + if (forVotes > 0) details.forVotes += forVotes; |
| 188 | + if (abstainVotes > 0) details.abstainVotes += abstainVotes; |
| 189 | + details.usedVotes[account] += usedWeight; |
| 190 | + |
| 191 | + return usedWeight; |
| 192 | + } |
| 193 | +} |
0 commit comments