# Understand the Gov Module
gov (opens new window) module enables governance on Cosmos SDK. It allows you to create proposals of any message type, and vote on them.
# Usage of the gov module
When the gov module is enabled on a chain (for example the Cosmos Hub), the users can submit a proposal to be voted on by the community.
A proposal can be an upgrade of the chain, a change of the parameters of the chain, a simple text proposal, or any other message type. This tutorial will focus on how you can participate in governance, by creating and voting on proposals.
Before starting, review some terminology:
Proposal: A proposal is a suggestion that is submitted to the network for voting. Once a proposal is submitted, it is identified by a unique proposal ID.
Message: A proposal includes an array of
sdk.Msgswhich are executed automatically if the proposal passes. This means you can submit a proposal about any action on which the governance module has
Deposit period: To prevent spam, proposals must be submitted with a deposit in the coins defined by the chain. At this point, for instance, the Cosmos Hub requires a
64 ATOMdeposit (opens new window). The deposit is always refunded to the depositors after voting, unless the proposal is vetoed: in that case the deposit is burned.
The proposer is not obliged to submit the totality of the deposit amount. Other users can also contribute to the deposit.
Voting period: After the minimum deposit is reached, the proposal enters the voting period. During this period, users can vote on the proposal. The voting period is a parameter of individual chains. For instance, the Cosmos Hub has a
2 weeksvoting period (opens new window).
Voting options: Voters can choose between
NoWithVetoallows the voter to cast a
Novote, but also to veto the proposal. If a proposal is vetoed, it is automatically rejected and the deposit burned.
Abstainallows the voter to abstain from voting. With a majority of
Yesthe proposal pass and its messages are executed.
Abstainis different from not voting at all, as voting contributes to reaching the quorum.
Voting weight: A.k.a. voting power. Each vote is weighted by the voter's staked tokens at the time the vote tally is computed. For the avoidance of doubt, it means that the number of staked tokens at the time the vote transaction is sent is irrelevant.
Quorum: Quorum is defined as the minimum percentage of voting power that needs to be cast on a proposal for the result to be valid. If the quorum is not reached, the proposal is rejected.
More information about the governance concepts can be found in the Cosmos SDK documentation (opens new window).
In the Cosmos SDK v0.46.0 release (opens new window), the gov module has been upgraded from
v1 (opens new window). To follow this tutorial, you must use the binary of a chain with the v1 gov module, for instance with a v0.46+ version of the SDK. For demonstration purposes, you will use
simd, the simulation app of the Cosmos SDK.
simd, first clone the Cosmos SDK GitHub repository and checkout the right version:
You are installing
v0.46.3 because this version added the command
draft-proposal. You will learn later what it does.
Go to the cloned directory:
Make sure the installation was successful:
The returned version number should be greater than or equal to
If you have used
simd before, you might already have a
.simapp directory in your home directory. You can skip to the next section or remove the chain directory (
rm -rf ~/.simapp).
simd, you have to set the chain ID and the keyring backend.
Secondly, you need to add keys for chain users. Call them Alice and Bob:
simd keys list you can verify that your two users have been added.
To avoid having to copy and paste the user addresses, now is a good time to export the user keys to variables that you can access and use for this tutorial.
Now you are ready to fund Alice and Bob's respective accounts and use the Alice account as validator:
The default voting period is 172800s (two days). It is too long to wait for the tutorial, so you will change it to 180s (three minutes). To do so, edit the
Then add the genesis accounts:
Lastly, start the chain:
simapp is now configured and running. You can play with the gov module.
# Create a proposal
Prior to submitting a proposal on the Cosmos Hub, it is good practice, and also requested to publish a draft of the proposal on the Cosmos Hub Forum (opens new window). This allows the community to discuss the proposal before it appears on chain.
Before sending anything to the blockchain, to create the files that describe a proposal in the proper format, you can use the following interactive command:
You will first create a simple text proposal. A text proposal does not contain any message, but only proposal metadata (opens new window).
Then enter the proposal title, authors, and other proposal metadata:
Then enter the proposal deposit:
draft-proposal command has now generated two files:
The content of
draft_metadata.json contains the information you have just entered:
This json should to be pinned on IPFS (opens new window).
In fact this file is already pinned on IPFS. Its CID is
QmbmhY1eNXdmcVV8QPqV5enwLZm1mjH7iv8aYTQ4RJCH49. You can verify its content on https://ipfs.io/ipfs/QmbmhY1eNXdmcVV8QPqV5enwLZm1mjH7iv8aYTQ4RJCH49 (opens new window).
Now look at the content of the generated
metadata field with
Submit the proposal on chain from alice:
The command outputs a transaction hash. You can use it to query the proposal:
# View and vote on proposals
In your case, the proposal ID is
1. You can query the proposal with the following command:
As you can see, the proposal is in the deposit period. This means that the deposit associated with it has not yet reached the minimum required, so you cannot vote on it just yet. Find out what is the minimum proposal deposit for a chain with the following command:
Therefore, since you submitted the proposal with
10stake, you need to top up the deposit with
9999990stake. You can do so with Bob and the following command:
The proposal is now in the voting period. Do not forget, you have three minutes (
180s as per the gov parameters) to vote on the proposal.
You can vote on it with the following command:
After waiting for the voting period, you can see that the proposal has passed.
This is because the governance proposal weights each vote by the amount of tokens staked. Alice owns staked tokens, while Bob had no staked tokens at the end of the voting period. So Bob's vote was not taken into consideration in the tally of the result.
After a proposal execution, the deposit is refunded (unless a weighted majority voted
No with veto). You can check the balance of Alice and Bob with the following commands:
# 🎉 Congratulations 🎉
By completing this tutorial, you have learned how to use the
To summarize, this tutorial has explained:
- How to a create proposal.
- How to submit a proposal
- How to vote on a proposal.
For more information about what else you can do with the CLI, please refer to the module help.
To learn more about the gov specs, check out the group (opens new window) module developer documentation. If you want to learn more about the Cosmos Hub governance, please refer to the Cosmos Hub governance (opens new window) documentation.