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 GOVERNORs token at a given time.

Checkpoints.History internal totalBalanceCheckpoints;

Functions

constructor

constructor(address _governor);

Parameters

_rawBalanceOf

Returns a representation of the current amount of GOVERNORs token that _user has claim to in this system. It may or may not be equivalent to the withdrawable balance of GOVERNORs 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

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

_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

getPastTotalBalance

Returns the sum total of raw balances of all users at _blockNumber.

function getPastTotalBalance(uint256 _blockNumber) public view returns (uint256);

Parameters

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
}