From ac713a18814a63f197e83cea462c89a61b7ba889 Mon Sep 17 00:00:00 2001 From: Ben DiFrancesco Date: Mon, 16 Oct 2023 13:14:34 -0400 Subject: [PATCH] README Updates Updates to the README which reflect the project's status, including its adoption, and link to the documentation now published at flexiblevoting.com --- README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 87 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index a9d0e31..9827041 100644 --- a/README.md +++ b/README.md @@ -4,29 +4,107 @@ Flexible Voting is an extension to the widely used OpenZeppelin DAO Governor tha For a DAO that adopts it, the Flexible Governance extension allows delegates to split their voting weight across For/Against/Abstain options for a given proposal. This new building block allows arbitrary delegate contracts to be developed which can unlock all kinds of new use cases, such as: - - Voting with tokens while earning yield in DeFi - - Voting with tokens bridged to L2 - - Shielded voting (i.e. secret/private voting) - - Cheaper subsidized signature based voting - - Better voting options with tokens held by custodians + - Voting with tokens while earning yield in DeFi + - Voting with tokens bridged to L2 + - Shielded voting (i.e. secret/private voting) + - Liquid delegation and sub-delegation + - Cheaper subsidized signature based voting + - Voting with tokens held by a 3rd party custodian + - Voting with tokens held in vesting contracts + - And much more...
Flexible Voting Diagram
-To learn more about Flexible Voting, and the use cases it enables, read the introduction on the [ScopeLift blog](https://www.scopelift.co/blog/introducing-flexible-voting). +To learn more about Flexible Voting, and the use cases it enables: + + * Visit [flexiblevoting.com](https://flexiblevoting.com) to read the documentation. + * Read about Flexible Voting on the [ScopeLift blog](https://scopelift.co/blog/tag/flexible-voting). + +## Usage + +To add Flexible Voting to your own Foundry project, use [forge install](https://book.getfoundry.sh/reference/forge/forge-install): + +```bash +$ forge install scopelift/flexible-voting +``` + +If you're using a developer framework other than Foundry, we recommend vendoring the code by adding `src/GovernorCountingFractional.sol` and/or `src/FlexVotingClient.sol` to your repo directly. In the future, we may offer an npm package for use with other frameworks. + +### Constructing a Governor + +If you're constructing a new Governor with Flexible Voting—either to upgrade an existing DAO or to launch a new one—you'll want to extend `GovernorCountingFractional`. + +```solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {GovernorVotes} from "@openzeppelin/contracts/governance/extensions/GovernorVotes.sol"; +import {GovernorSettings} from "@openzeppelin/contracts/governance/extensions/GovernorSettings.sol"; +import {GovernorTimelockControl} from + "@openzeppelin/contracts/governance/extensions/GovernorTimelockControl.sol"; +import { + Governor, GovernorCountingFractional +} from "flexible-voting/src/GovernorCountingFractional.sol"; + +contract FlexibleVotingGovernor is + GovernorCountingFractional, + GovernorVotes, + GovernorTimelockControl, + GovernorSettings +{ + // The rest of the Governor implementation... +} +``` + +For more information on building a new Governor that includes Flexible Voting, see the documentation for [upgrading an existing DAO](https://flexiblevoting.com/docs/tutorials/existing-dao) or [launching a new DAO](https://flexiblevoting.com/docs/tutorials/new-dao). + +### Creating a Voting Client Contract + +If you're building a new Flexible Voting client—a contract that can be delegated votes and is able to cast them to a compatible Governor—you'll want to extend `FlexVotingClient`. Afterwards, you'll implement the `_rawBalanceOf(address)` method for your use case. + +```solidity +import {FlexVotingClient} from "flexible-voting/src/FlexVotingClient.sol"; + +contract PoolClient is FlexVotingClient { + constructor(address _governor) FlexVotingClient(_governor) {} + + function _rawBalanceOf(address _user) internal view virtual override returns (uint256) { + // your implementation + } +} +``` + +To learn more about how to create a novel Flexible Voting client contract, checkout the [tutorial](https://flexiblevoting.com/docs/tutorials/voting-client) in the documentation. + +## Adoption + +Flexible Voting has been adopted by a number of DAOs, including: + +- [Gitcoin](https://github.com/gitcoinco/Alpha-Governor-Upgrade) +- [PoolTogether](https://github.com/ScopeLift/pooltogether-governor-upgrade) +- [Frax Finance](https://github.com/FraxFinance/frax-governance) + +A number of Flexible Voting clients have been developed, including: + +- [Aave Flexible Voting aToken](https://www.scopelift.co/blog/how-scopelift-built-a-flex-voting-atoken-on-aave) +- [Compound V3 Money Market](https://www.scopelift.co/blog/flexible-voting-on-compound) +- [Layer 2 Flexible Voting](https://github.com/ScopeLift/l2-flexible-voting) + +To read more about Flexible Voting adoption, read the documentation pages on [compatible DAOs](https://flexiblevoting.com/docs/compatible-daos) and [existing clients](https://flexiblevoting.com/docs/existing-clients). ## Repo Contents * [`src/GovernorCountingFractional.sol`](https://github.com/ScopeLift/flexible-voting/blob/master/src/GovernorCountingFractional.sol) - The Governor extension which enables Flexible Voting. A DAO adopting Flexible Voting would deploy a new Governor which used this extension. -* [`src/FractionalPool.sol`](https://github.com/ScopeLift/flexible-voting/blob/master/src/FractionalPool.sol) - A proof-of-concept contract demonstrating how Flexible Voting can be used. It implements a Compound-Finance-like governance token pool that allows holders to express their votes on proposals even when their tokens are deposited in the pool. +* [`src/FlexVotingClient.sol`](https://github.com/ScopeLift/flexible-voting/blob/master/src/FlexVotingClient.sol) - An abstract contract designed to make it easy to build clients for Flexible Voting governors. Inherit from this contract if you're building an integration or voting scheme for DAO(s) that use Flexible Voting. +* [`src/FractionalPool.sol`](https://github.com/ScopeLift/flexible-voting/blob/master/src/FractionalPool.sol) - A proof-of-concept contract demonstrating how Flexible Voting can be used. It implements a simple token pool that allows holders to express their votes on proposals even when their tokens are deposited in the pool. * [`test/`](https://github.com/ScopeLift/flexible-voting/tree/master/test) - A full suite of unit and fuzz tests exercising the contracts. ## Development - This repo is built using [Foundry](https://github.com/foundry-rs/foundry) 1. [Install Foundry](https://github.com/foundry-rs/foundry#installation) @@ -52,4 +130,4 @@ Code contributions to this repo are also welcome! Fork the project, create a new Fractional Voting is available under the [MIT](LICENSE.txt) license. -Copyright (c) 2022 ScopeLift \ No newline at end of file +Copyright (c) 2023 ScopeLift \ No newline at end of file