From 29957d4a47d4c637a4a37e913a1b521f5aa1204b Mon Sep 17 00:00:00 2001 From: Francisco Giordano Date: Wed, 4 Aug 2021 19:08:44 -0300 Subject: [PATCH] Add Governor guide (#2811) --- docs/modules/ROOT/images/tally-admin.png | Bin 0 -> 22024 bytes docs/modules/ROOT/images/tally-vote.png | Bin 0 -> 33437 bytes docs/modules/ROOT/nav.adoc | 2 + docs/modules/ROOT/pages/governance.adoc | 328 +++++++++++++++++++++++ 4 files changed, 330 insertions(+) create mode 100644 docs/modules/ROOT/images/tally-admin.png create mode 100644 docs/modules/ROOT/images/tally-vote.png create mode 100644 docs/modules/ROOT/pages/governance.adoc diff --git a/docs/modules/ROOT/images/tally-admin.png b/docs/modules/ROOT/images/tally-admin.png new file mode 100644 index 0000000000000000000000000000000000000000..8265259302418995cbc0ee77128e6dde20d1dfe0 GIT binary patch literal 22024 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 H55fNfLFfw_ literal 0 HcmV?d00001 diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index f62cc2ef2..3804c7d94 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -14,4 +14,6 @@ ** xref:erc777.adoc[ERC777] ** xref:erc1155.adoc[ERC1155] +* xref:governance.adoc[Governance] + * xref:utilities.adoc[Utilities] diff --git a/docs/modules/ROOT/pages/governance.adoc b/docs/modules/ROOT/pages/governance.adoc new file mode 100644 index 000000000..1580e62df --- /dev/null +++ b/docs/modules/ROOT/pages/governance.adoc @@ -0,0 +1,328 @@ += How to set up on-chain governance + +In this guide we will learn how OpenZeppelin’s Govenor contract works, how to set it up, and how to use it to create proposals, vote for them, and execute them, using tools provided by Ethers.js and Tally. + +== Introduction + +Decentralized protocols are in constant evolution from the moment they are publicly released. Often, the initial team retains control of this evolution in the first stages, but eventually delegates it to a community of stakeholders. The process by which this community makes decisions is called on-chain governance, and it has become a central component of decentralized protocols, fueling varied decisions such as parameter tweaking, smart contract upgrades, integrations with other protocols, treasury management, grants, etc. + +This governance protocol is generally implemented in a special-purpose contract called “Governor”. The GovernorAlpha and GovernorBravo contracts designed by Compound have been very successful and popular so far, with the downside that projects with different requirements have had to fork the code to customize it for their needs, which can pose a high risk of introducing security issues. For OpenZeppelin Contracts, we set out to build a modular system of Governor contracts so that forking is not needed, and different requirements can be accommodated by writing small modules using Solidity inheritance. You will find the most common requirements out of the box in OpenZeppelin Contracts, but writing additional ones is simple, and we will be adding new features as requested by the community in future releases. Additionally, the design of OpenZeppelin Governor requires minimal use of storage and results in more gas efficient operation. + +== Compatibility + +OpenZeppelin’s Governor system was designed with a concern for compatibility with existing systems that were based on Compound’s GovernorAlpha and GovernorBravo. Because of this, you will find that many modules are presented in two variants, one of which is built for compatibility with those systems. + +=== ERC20Votes & ERC20VotesComp + +The ERC20 extension to keep track of votes and vote delegation is one such case. The shorter one is the more generic version because it can support token supplies greater than 2^96, while the “Comp” variant is limited in that regard, but exactly fits the interface of the COMP token that is used by GovernorAlpha and Bravo. Both contract variants share the same events, so they are fully compatible when looking at events only. + +=== Governor & GovernorCompatibilityBravo + +An OpenZeppelin Governor contract is by default not interface-compatible with GovernorAlpha or Bravo, since some of the functions are different or missing, although it shares all of the same events. However, it’s possible to opt in to full compatibility by inheriting from the GovernorCompatibilityBravo module. The contract will be cheaper to deploy and use without this module. + +=== GovernorTimelockControl & GovernorTimelockCompound + +When using a timelock with your Governor contract, you can use either OpenZeppelin’s TimelockController or Compound’s Timelock. Based on the choice of timelock, you should choose the corresponding Governor module: GovernorTimelockControl or GovernorTimelockCompound respectively. This allows you to migrate an existing GovernorAlpha instance to an OpenZeppelin-based Governor without changing the timelock in use. + +=== Tally + +Tally is a full-fledged application for user owned on-chain governance. It comprises a voting dashboard, proposal creation wizard, real time research and analysis, and educational content. + +For all of these options, the Governor will be compatible with Tally: users will be able to create proposals, visualize voting power and advocates, navigate proposals, and cast votes. For proposal creation in particular, projects can also use Defender Admin as an alternative interface. + +In the rest of this guide, we will focus on a fresh deploy of the vanilla OpenZeppelin Governor features without concern for compatibility with GovernorAlpha or Bravo. + +== Setup + +=== Token + +The voting power of each account in our governance setup will be determined by an ERC20 token. The token has to implement the ERC20Votes extension. This extension will keep track of historical balances so that voting power is retrieved from past snapshots rather than current balance, which is an important protection that prevents double voting. + +```solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.2; + +import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; +import "@openzeppelin/contracts/token/ERC20/extensions/draft-ERC20Permit.sol"; +import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Votes.sol"; + +contract MyToken is ERC20, ERC20Permit, ERC20Votes { + constructor() ERC20("MyToken", "MTK") ERC20Permit("MyToken") {} + + // The functions below are overrides required by Solidity. + + function _afterTokenTransfer(address from, address to, uint256 amount) + internal + override(ERC20, ERC20Votes) + { + super._afterTokenTransfer(from, to, amount); + } + + function _mint(address to, uint256 amount) + internal + override(ERC20, ERC20Votes) + { + super._mint(to, amount); + } + + function _burn(address account, uint256 amount) + internal + override(ERC20, ERC20Votes) + { + super._burn(account, amount); + } +} +``` + +If your project already has a live token that does not include ERC20Votes and is not upgradeable, you can wrap it in a governance token by using ERC20Wrapper. This will allow token holders to participate in governance by wrapping their tokens 1-to-1. + +```solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.2; + +import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; +import "@openzeppelin/contracts/token/ERC20/extensions/draft-ERC20Permit.sol"; +import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Votes.sol"; +import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Wrapper.sol"; + +contract MyToken is ERC20, ERC20Permit, ERC20Votes, ERC20Wrapper { + constructor(IERC20 wrappedToken) + ERC20("MyToken", "MTK") + ERC20Permit("MyToken") + ERC20Wrapper(wrappedToken) + {} + + // The functions below are overrides required by Solidity. + + function _afterTokenTransfer(address from, address to, uint256 amount) + internal + override(ERC20, ERC20Votes) + { + super._afterTokenTransfer(from, to, amount); + } + + function _mint(address to, uint256 amount) + internal + override(ERC20, ERC20Votes) + { + super._mint(to, amount); + } + + function _burn(address account, uint256 amount) + internal + override(ERC20, ERC20Votes) + { + super._burn(account, amount); + } +} +``` + +NOTE: Voting power could be determined in different ways: multiple ERC20 tokens, ERC721 tokens, sybil resistant identities, etc. All of these options are potentially supported by writing a custom Votes module for your Governor. + +=== Governor + +Initially, we will build a Governor without a timelock. The core logic is given by the Governor contract, but we still need to choose: 1) how voting power is determined, 2) how many votes are needed for quorum, and 3) what options people have when casting a vote and how those votes are counted. Each of these aspects is customizable by writing your own module, or more easily choosing one from OpenZeppelin Contracts. + +For 1) we will use the GovernorVotes module, which hooks to an ERC20Votes instance to determine the voting power of an account based on the token balance they hold when a proposal becomes active. This module requires as a constructor parameter the address of the token. + +For 2) we will use GovernorVotesQuorumFraction which works together with ERC20Votes to define quorum as a percentage of the total supply at the block a proposal’s voting power is retrieved. This requires a constructor parameter to set the percentage. Most Governors nowadays use 4%, so we will initialize the module with parameter 4 (this indicates the percentage, resulting in 4%). + +For 3) we will use GovernorCountingSimple, a module that offers 3 options to voters: For, Against, and Abstain, and where only For and Abstain votes are counted towards quorum. + +Besides these modules, Governor itself has some parameters we must set. + +votingDelay: How long after a proposal is created should voting power be fixed. A large voting delay gives users time to unstake tokens if necessary. +votingPeriod: How long does a proposal remain open to votes. + +These parameters are specified in number of blocks. Assuming block time of around 13.14 seconds, we will set votingDelay = 1 day = 6570 blocks, and votingPeriod = 1 week = 45992 blocks. + +We can optionally set a proposal threshold as well. This restricts proposal creation to accounts who have enough voting power. + +```solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.2; + +import "./governance/Governor.sol"; +import "./governance/compatibility/GovernorCompatibilityBravo.sol"; +import "./governance/extensions/GovernorVotes.sol"; +import "./governance/extensions/GovernorVotesQuorumFraction.sol"; +import "./governance/extensions/GovernorTimelockControl.sol"; + +contract MyGovernor is Governor, GovernorCompatibilityBravo, GovernorVotes, GovernorVotesQuorumFraction, GovernorTimelockControl { + constructor(ERC20Votes _token, TimelockController _timelock) + Governor("MyGovernor") + GovernorVotes(_token) + GovernorVotesQuorumFraction(4) + GovernorTimelockControl(_timelock) + {} + + function votingDelay() public pure override returns (uint256) { + return 6575; // 1 day + } + + function votingPeriod() public pure override returns (uint256) { + return 46027; // 1 week + } + + function proposalThreshold() public pure override returns (uint256) { + return 0; + } + + // The functions below are overrides required by Solidity. + + function quorum(uint256 blockNumber) + public + view + override(IGovernor, GovernorVotesQuorumFraction) + returns (uint256) + { + return super.quorum(blockNumber); + } + + function getVotes(address account, uint256 blockNumber) + public + view + override(IGovernor, GovernorVotes) + returns (uint256) + { + return super.getVotes(account, blockNumber); + } + + function state(uint256 proposalId) + public + view + override(Governor, IGovernor, GovernorTimelockControl) + returns (ProposalState) + { + return super.state(proposalId); + } + + function propose(address[] memory targets, uint256[] memory values, bytes[] memory calldatas, string memory description) + public + override(Governor, GovernorCompatibilityBravo, IGovernor) + returns (uint256) + { + return super.propose(targets, values, calldatas, description); + } + + function _execute(uint256 proposalId, address[] memory targets, uint256[] memory values, bytes[] memory calldatas, bytes32 descriptionHash) + internal + override(Governor, GovernorTimelockControl) + { + super._execute(proposalId, targets, values, calldatas, descriptionHash); + } + + 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 _executor() + internal + view + override(Governor, GovernorTimelockControl) + returns (address) + { + return super._executor(); + } + + function supportsInterface(bytes4 interfaceId) + public + view + override(Governor, IERC165, GovernorTimelockControl) + returns (bool) + { + return super.supportsInterface(interfaceId); + } +} + +``` + +=== Timelock + +It is good practice to add a timelock to governance decisions. This allows users to exit the system if they disagree with a decision before it is executed. We will use OpenZeppelin’s TimelockController in combination with the GovernorTimelockControl module. + +TimelockController uses an AccessControl setup that we need to understand in order to set up roles. The Proposer role is in charge of queueing operations: this is the role the Governor instance should be granted, and it should likely be the only proposer in the system. The Executor role is in charge of executing already available operations: we can assign this role to the special zero address to allow anyone to execute (if operations can be particularly time sensitive, the Governor should be made Executor instead). Lastly, there is the Admin role, which can grant and revoke the two previous roles: this is a very sensitive role that will be granted automatically to both deployer and timelock itself, but should be renounced by the deployer after setup. + +== Proposal Lifecycle + +Let’s walk through how to create and execute a proposal on our newly deployed Governor. + +A proposal is a sequence of actions that the Governor contract will perform if it passes. Each action consists of a target address, calldata encoding a function call, and an amount of ETH to include. Additionally, a proposal includes a human-readable description. + +=== Create a Proposal + +Let’s say we want to create a proposal to give a team a grant, in the form of ERC20 tokens from the governance treasury. This proposal will consist of a single action where the target is the ERC20 token, calldata is the encoded function call `transfer(, )`, and with 0 ETH attached. + +Generally a proposal will be created with the help of an interface such as Tally or Defender. Here we will show how to create the proposal using Ethers.js. + +First we get all the parameters necessary for the proposal action. + +```javascript +const tokenAddress = ...; +const token = await ethers.getContractAt(‘ERC20’, tokenAddress); + +const teamAddress = ...; +const grantAmount = ...; +const transferCalldata = token.interface.encodeFunctionData(‘transfer’, [teamAddress, grantAmount]); +``` + +Now we are ready to call the propose function of the governor. Note that we don’t pass in one array of actions, but instead three arrays corresponding to the list of targets, the list of values, and the list of calldatas. In this case it’s a single action, so it’s simple: + +```javascript +await governor.propose( + [tokenAddress], + [0], + [transferCalldata], + “Proposal #1: Give grant to team”, +); +``` + +This will create a new proposal, with a proposal id that is obtained by hashing together the proposal data, and which will also be found in an event in the logs of the transaction. + +=== Cast a Vote + +Once a proposal is active, stakeholders can cast their vote. This is done through a function in the Governor contract that users can invoke directly from a governance UI such as Tally. + +image::tally-vote.png[Voting in Tally] + +=== Execute the Proposal + +Once the voting period is over, if quorum was reached (enough voting power participated) and the majority voted in favor, the proposal is considered successful and can proceed to be executed. This can also be done in Tally in the "Administration Panel" section of a project. + +image::tally-admin.png[Administration Panel in Tally] + +We will see now how to do this manually using Ethers.js. + +If a timelock was set up, the first step to execution is queueing. You will notice that both the queue and execute functions require passing in all of the proposal parameters, as opposed to just the proposal id. This is necessary because this data is not stored on chain, as a measure to save gas. Note that these parameters can always be found in the events emitted by the contract. The only parameter that is not sent in its entirety is the description, since this is only needed in its hashed form to compute the proposal id. + +To queue, we call the queue function: + +```javascript +const descriptionHash = ethers.utils.id(“Proposal #1: Give grant to team”); + +await governor.queue( + [tokenAddress], + [0], + [transferCalldata], + descriptionHash, +); +``` + +This will cause the governor to interact with the timelock contract and queue the actions for execution after the required delay. + +After enough time has passed (according to the timelock parameters), the proposal can be executed. If there was no timelock to begin with, this step can be ran immediately after the proposal succeeds. + +```javascript +await governor.execute( + [tokenAddress], + [0], + [transferCalldata], + descriptionHash, +); +``` + +Executing the proposal will transfer the ERC20 tokens to the chosen recipient. To wrap up: we set up a system where a treasury is controlled by the collective decision of the token holders of a project, and all actions are executed via proposals enforced by on-chain votes.