Building a Governance Interface
Quick Start Guide
Community governance has replaced the administrator of the Compound protocol in a major step towards full decentralization.
The primary goal of decentralization is to allow the protocol to evolve into resilient financial infrastructure, with no identifiable weak points and no reliance on any single team. In this way, the protocol can continue to scale with the growth of the entire crypto ecosystem, and last forever — or at least as long as Ethereum exists.
This guide will introduce you to Compound’s governance smart contracts, and walk you through the process of building custom functionality and interfaces that interact with the governance system.
What Is COMP?
The Compound protocol can only be upgraded and configured by COMP token holders and their delegates. All potential changes to the protocol, including the addition of new markets or the adjustment of system parameters like collateral factors or interest rate algorithms, must pass through a proposal and voting process as specified in the governance smart contracts.
COMP is a token that corresponds 1–1 with voting power in Compound governance. Holders of COMP tokens in their Ethereum wallets may delegate their voting rights either to themselves, or to any other Ethereum addresses, using a utility function in the COMP ERC-20 token contract.
The recipients of delegated voting rights, known as delegates, whether they be the COMP holders themselves or another address, may propose, vote on, and execute proposals to modify the protocol. You can see a current list of delegates on the Compound Governance Leaderboard.
To receive COMP, use the Compound protocol on Ethereum or any testnet. For more details, check out the documentation.
Key Concepts for Developing On Governance
Building an interface for governance or extending its functionality is straightforward once you understand the basics. For a more in-depth look at Governance, check out the full documentation. For just a quick start, continue with these key concepts.
- COMP — An ERC-20 token that designates the weight of a user’s voting rights. The more COMP a user has in their wallet, the more weight their delegation or vote on a proposal holds.
- Delegation — COMP holders cannot vote or create proposals until they delegate their voting rights to an address. Delegation can be given to one address at a time, including the COMP holder’s own address.
- Proposals — A proposal is executable code that modifies the protocol and how it works. In order to create a proposal, a user must have at least 60,000 COMP delegated to their address. Proposals are stored in the “proposals” mapping of the Governance smart contract. All proposals are subject to a 3-day voting period. If the proposer does not maintain their vote weight balance throughout the voting period, the proposal may be canceled by anyone.
- Voting — Users can vote for or against single proposals once they have voting rights delegated to their address. Votes can be cast while a proposal is in the “Active” state. Votes can be submitted immediately using “castVote” or submitted later with “castVoteBySig.” If the majority of votes (and a 4% quorum of delegated COMP, i.e. 400,000 COMP) vote for a proposal, the proposal is queued in the Timelock.
- Timelock — All governance and other administrative actions are required to sit in the Timelock for a minimum of 2 days, after which they can be implemented into the protocol.
Over time these key components of the governance system may change, if the community decides to upgrade them in a form of meta-governance. COMP holders will be the ultimate arbiters of the future direction of every aspect of the protocol.
What Can Be Built With Compound Governance?
Application developers can build their own custom workflows and interfaces to facilitate the participation of their users and communities in Compound governance. For example, applications integrated with Compound’s interest rate markets may be interested in adding governance functionality including:
- Encouraging users to delegate COMP voting power to the application team’s address, so the team can participate in governance on behalf of users.
- Surfacing specific governance proposals to users so users with COMP can vote on them directly.
- Giving users transparent insight into upcoming potential changes to Compound, including proposals for adding new markets, or other upgrades.
Such interfaces will require a combination of the following components:
- Voting interface — Users cast their vote on an active proposal.
- Delegation interface — Users delegate their voting rights to an address.
- Voting weight leaderboard — List voting addresses ordered by voting weight.
- Vote-on-my-behalf interface — Using the “castVoteBySig” function allows users to create a ballot which can be given to another user. This will allow another user to submit their vote on their behalf (and pay the gas fee), without needing to delegate to the other user (check out https://comp.vote/).
- Proposal Explorer — Browse past or present governance proposals in a streamlined user interface.
- Proposal creation interface — Choose protocol modifications and initialize the proposal if the user has enough vote weight.
Compound Governance Code Examples
A governance interface must read and write to and from the blockchain, and we’ll walk through some basic JavaScript code examples for doing both. Reading data will be done using the Compound API and Web3. However, write operations, like delegating or voting, can only be done with Web3.
We are going to demonstrate how to do each of the following, in order:
- Get All COMP Token Holders
- Get All Delegates
- Get All Proposals (All States)
- Get All Ballots for a Proposal
- Delegate Voting Rights
- Vote on an Active Proposal
- Vote on an Active Proposal with a Signature
The following code examples are all available in the Compound Governance Quick Start repository on GitHub. Check out the live interface examples running on GitHub pages (links are in the repository readme).
Get All COMP Token Holders
Let’s get all COMP token holders in descending order, based on their COMP balance. We can do this with the Compound API’s Governance Service.
This code uses the built in browser fetch method which returns a JavaScript promise. The repository has an identical example that does a direct blockchain query for COMP holders using Web3.js. We can find out the same information using the COMP smart contract.
The result of either of the code examples is an array of JSON objects that contain the account address, COMP token balance, and account delegate address.
Get All Delegates
We can see all of the addresses that have COMP delegated to them. Below is a blockchain query. It uses the COMP contract’s “DelegateVotesChanged” event to collect each of the current delegates.
The example only works on Ropsten. It no longer works on Mainnet because there are too many addresses for the Web3 provider to fetch at once. For better UX, and a more robust application, query this data periodically from a back-end server and persist it.
Alternatively, this information can be retrieved from the Compound API. Here is the Compound API example. These examples create an array of JSON objects that have the delegate address and the vote weight (percentage) of total COMP supply.
Get All Proposals (All States)
If you’re making a governance explorer, it’s useful to fetch all of the proposals. The Compound API comes in handy here. This example will get all proposals, regardless of their state. The API is capable of filtering proposals by state, based on request parameters.
We can also fetch the same proposal data directly with Web3 by using the governance contract’s “ProposalCreated” method. The code examples create an array of JSON objects with the following proposal data.
Get All Ballots for a Proposal
Once a proposal has reached the “Active” state, voters can begin casting their ballots. The ballots are publicly stored on the blockchain, so we can retrieve them at any time. The following is an example for fetching submitted votes on proposal #1 on Ropsten.
Proposal IDs are in ascending order starting at 1. After Governor Alpha was updated to Governor Bravo, the initial proposal ID changed. It can be retrieved from the contract by calling “initialProposalId”.
To see how many proposals have been made in total, you can fetch the “proposalCount” variable from the Governor Bravo contract. Ballots can also be fetched from the Compound API, like in this Governance service example. Here is the resulting array of JSON objects that have ballot data.
Delegate Voting Rights
In order to participate in governance, a COMP token holder must delegate their voting rights. Delegation can be done to any address, including the token holder’s own address. Delegation can be made to just one address at a time.
The following is a Web3 example of setting your delegate address. If you do not have COMP tokens, you can still delegate, and future COMP tokens you receive will automatically be delegated to your selected delegate address.
The code relies on the browser being Web3-enabled. Be sure to install MetaMask in your browser. Ropsten ETH can be requested from a faucet. Here’s what it looks like in action:
Vote on an Active Proposal
The most exciting part of Compound Governance is casting your vote in a proposal to change the protocol. Delegates can cast a vote of ‘for’, ‘against’, or ‘abstain’ for each active proposal.
The following code example drives functionality of a voting user interface. If there are no “Active” proposals, there will not be any proposals in the selector!
Building Your Own Governance Interface
The goal of community governance is to allow the Compound protocol to become truly open and resilient financial infrastructure for all. Reaching this milestone requires the community, developers and users and institutions alike, to create their own interfaces and functionality for participating in Compound governance.
Thanks to the composable and open-access nature of Ethereum, anyone and everyone can create their own COMP and Governance projects. Here are even more resources to help get you started.
Compound Governance Resources
- Governance Introduction (Feb 2020)
- Governance Launch Announcement (April 2020)
- Compound Protocol Governance Documentation
- Compound API Governance Service Documentation
- Community-led Governance Forums
Share what you are working on in the #development channel of the Compound Discord server; someone is always online, and ready to answer questions. For updates, we recommend that you subscribe to the Compound Newsletter.
