FlexVotingClient
Git Source (opens in a new tab)
This is an abstract contract designed to make it easy to build clients for governance systems that inherit from GovernorCountingFractional, a.k.a. Flexible Voting governors.
A "client" in this sense is a contract that:
- (a) receives deposits of governance tokens from its users,
- (b) gives said depositors the ability to express their voting preferences on governance proposals, and
- (c) casts votes on said proposals to flexible voting governors according to the expressed preferences of its depositors.
This contract assumes that a child contract will implement a mechanism for receiving and storing deposit balances, part (a). With that in place, this contract supplies features (b) and (c).
A key concept here is that of a user's "raw balance". The raw balance is the
system's internal representation of a user's claim on the governance tokens
that it custodies. Since different systems might represent such claims in
different ways, this contract leaves the implementation of the _rawBalance
function to the child contract.
The simplest such representation would be to directly store the cumulative balance of the governance token that the user has deposited. In such a system, the amount that the user deposits is the amount that the user has claim to. If the user has claim to 1e18 governance tokens, the internal representation is just 1e18.
In many systems, however, the raw balance will not be equivalent to the amount of governance tokens the user has claim to. In Aave, for example, deposit amounts are scaled down by an ever-increasing index that represents the cumulative amount of interest earned over the lifetime of deposits. The "raw balance" of a user in Aave's case is this scaled down amount, since it is the value that represents the user's claim on deposits. Thus for Aave, a users's raw balance will always be less than the actual amount they have claim to.
If the raw balance can be identified and defined for a system, and
_rawBalance
can be implemented for it, then this contract will take care
of the rest.
State Variables
proposalVotersHasVoted
Map proposalId to an address to whether they have voted on this proposal.
mapping(uint256 => mapping(address => bool)) private proposalVotersHasVoted;
proposalVotes
Map proposalId to vote totals expressed on this proposal.
mapping(uint256 => ProposalVote) public proposalVotes;
GOVERNOR
The governor contract associated with this governance token. It must be one that supports fractional voting, e.g. GovernorCountingFractional.
IFractionalGovernor public immutable GOVERNOR;
balanceCheckpoints
Mapping from address to the checkpoint history of raw balances of that address.
mapping(address => Checkpoints.History) private balanceCheckpoints;
totalBalanceCheckpoints
History of the sum total of raw balances in the system. May or may
not be equivalent to this contract's balance of GOVERNOR
s token at a
given time.
Checkpoints.History internal totalBalanceCheckpoints;
Functions
constructor
constructor(address _governor);
Parameters
Name | Type | Description |
---|---|---|
_governor | address | The address of the flex-voting-compatible governance contract. |
_rawBalanceOf
Returns a representation of the current amount of GOVERNOR
s
token that _user
has claim to in this system. It may or may not be
equivalent to the withdrawable balance of GOVERNOR
s token for user
,
e.g. if the internal representation of balance has been scaled down.
function _rawBalanceOf(address _user) internal view virtual returns (uint256);
_castVoteReasonString
Used as the reason
param when submitting a vote to GOVERNOR
.
function _castVoteReasonString() internal virtual returns (string memory);
_selfDelegate
Delegates the present contract's voting rights with GOVERNOR
to itself.
function _selfDelegate() internal;
expressVote
Allow the caller to express their voting preference for a given
proposal. Their preference is recorded internally but not moved to the
Governor until castVote
is called.
function expressVote(uint256 proposalId, uint8 support) external;
Parameters
Name | Type | Description |
---|---|---|
proposalId | uint256 | The proposalId in the associated Governor |
support | uint8 | The depositor's vote preferences in accordance with the VoteType enum. |
castVote
Causes this contract to cast a vote to the Governor for all of the accumulated votes expressed by users. Uses the sum of all raw balances to proportionally split its voting weight. Can be called by anyone. Can be called multiple times during the lifecycle of a given proposal.
function castVote(uint256 proposalId) external;
Parameters
Name | Type | Description |
---|---|---|
proposalId | uint256 | The ID of the proposal which the Pool will now vote on. |
_checkpointRawBalanceOf
Checkpoints the _user's current raw balance.
function _checkpointRawBalanceOf(address _user) internal;
getPastRawBalance
Returns the _user
's raw balance at _blockNumber
.
function getPastRawBalance(address _user, uint256 _blockNumber) public view returns (uint256);
Parameters
Name | Type | Description |
---|---|---|
_user | address | The account that's historical raw balance will be looked up. |
_blockNumber | uint256 | The block at which to lookup the _user's raw balance. |
getPastTotalBalance
Returns the sum total of raw balances of all users at _blockNumber
.
function getPastTotalBalance(uint256 _blockNumber) public view returns (uint256);
Parameters
Name | Type | Description |
---|---|---|
_blockNumber | uint256 | The block at which to lookup the total balance. |
Structs
ProposalVote
Data structure to store vote preferences expressed by depositors.
struct ProposalVote {
uint128 againstVotes;
uint128 forVotes;
uint128 abstainVotes;
}
Enums
VoteType
The voting options corresponding to those used in the Governor.
enum VoteType {
Against,
For,
Abstain
}