Tutorial: Governance Module - Creating and Managing Proposals

Tobias Schwarz

Jul 25, 2024 • 5 min read

In this tutorial, we will walk through the process of creating and managing proposals using the Governance module in a Cosmos SDK-based blockchain. Governance is a critical feature for decentralised networks, allowing stakeholders to make decisions collectively.

Prerequisites

Before we begin, ensure you have the following:

Ignite CLI installed: Instructions can be found here.
Basic knowledge of Go: Familiarity with Go programming will be helpful.

Step 1: Setting Up Your Project

Initialise a New Blockchain Project:

ignite scaffold chain github.com/username/mychain --address-prefix myprefix
cd mychain

Run the blockchain with

ignite chain serve

Add the Governance Module:
The Governance module is included by default in a scaffolded Ignite chain. To confirm, check app/app.go for the following import:
```
import (
    "github.com/cosmos/cosmos-sdk/x/gov"
)
```

Step 2: Configuring the Governance Module

Enable Governance Module in Your App:
In app/app_config.go, ensure the Governance module is included in the module manager and configured correctly:
```
		{
			Name:   govtypes.ModuleName,
			Config: appconfig.WrapAny(&govmodulev1.Module{}),
		},
```

Set Up Governance Parameters:
Governance parameters can be configured in config/genesis.json under the gov section. Example configuration:

{
    "gov": {
        "voting_params": {
            "voting_period": "172800s"
        },
        "deposit_params": {
            "min_deposit": [
                {
                    "denom": "stake",
                    "amount": "10000000"
                }
            ],
            "max_deposit_period": "172800s"
        },
        "tally_params": {
            "quorum": "0.334000000000000000",
            "threshold": "0.500000000000000000",
            "veto": "0.334000000000000000"
        }
    }
}

With the Ignite CLI, you can make this a permanent for your blockchain with modifying the config.yml file at the root of your scaffolded blockchain. The settings would look like this:

genesis:
  app_state:
    gov:
      voting_params:
        voting_period: "172800s"
      deposit_params:
        min_deposit:
          - denom: "stake"
            amount: "10000"
        max_deposit_period: "172800s"
      tally_params: 
        quorum: "0.334000000000000000"
        threshold: "0.500000000000000000"
        veto: "0.334000000000000000"

Step 3: Creating a Proposal

Proposal Types:
There are different types of proposals you can create, including

Text Proposals,
Parameter Change Proposals
Software Upgrade Proposals
- Cancel Software Upgrade Proposal
Community Pool Spend Proposal

Creating a Text Proposal:
To create a simple text proposal, use the following command:
```
mychaind tx gov draft-proposal
```

Please enter in the details, you can get some inspiration from the following example.

Broadcast the Proposal:
Ensure your transaction is broadcasted to the network:

mychaind tx gov submit-proposal ./draft_proposal.json --from=alice --chain-id mychain

Congratulations, you've created a text proposal on your local blockchain.

Step 4: Creating an Upgrade Proposal

Create the Upgrade Proposal:
To create an upgrade proposal, use the following command:
```
mychaind tx gov draft-proposal
```

Now insert your data into the skeleton draft_proposal.json.
In your draft_proposal.json populate the height with your desired upgrade height and populate the info field with additional information (must be a valid JSON string):

{
 "messages": [
  {
   "@type": "/cosmos.upgrade.v1beta1.MsgSoftwareUpgrade",
   "authority": "myprefix10d07y265gmmuvt4z0w9aw880jnsr700ja2wjxw",
   "plan": {
    "name": "v2.0.0",
    "time": "0001-01-01T00:00:00Z",
    "height": "15000",
    "info": "xxx",
    "upgraded_client_state": null
   }
  }
 ],
 "metadata": "ipfs://CID",
 "deposit": "10000000stake",
 "title": "Upgrade to v2",
 "summary": "Upgrades to the latest release v2",
 "expedited": false
}

You can specify the binaries used, have a look at this example from Cosmos Documentation.

{
  "binaries": {
    "darwin/amd64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-darwin-amd64?checksum=sha256:7157f03fbad4f53a4c73cde4e75454f4a40a9b09619d3295232341fec99ad138",
    "darwin/arm64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-darwin-arm64?checksum=sha256:09e2420151dd22920304dafea47af4aa5ff4ab0ddbe056bb91797e33ff6df274",
    "linux/amd64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-linux-amd64?checksum=sha256:236b5b83a7674e0e63ba286739c4670d15d7d6b3dcd810031ff83bdec2c0c2af",
    "linux/arm64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-linux-arm64?checksum=sha256:b055fb7011e99d16a3ccae06443b0dcfd745b36480af6b3e569e88c94f3134d3",
    "windows/armd64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-windows-amd64.exe?checksum=sha256:f0224ba914cad46dc27d6a9facd8179aec8a70727f0b1e509f0c6171c97ccf76",
    "windows/arm64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-windows-arm64.exe?checksum=sha256:cbbce5933d501b4d54dcced9b097c052bffdef3fa8e1dfd75f29b34c3ee7de86"
  }
}

Make sure to convert the JSON of the binaries with escaped characters, then it will be interpreted accordingly by the blockchain software. Then it can be added to the info field

{\"binaries\":{\"darwin/amd64\":\"https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-darwin-amd64?checksum=sha256:7157f03fbad4f53a4c73cde4e75454f4a40a9b09619d3295232341fec99ad138\",\"darwin/arm64\":\"https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-darwin-arm64?checksum=sha256:09e2420151dd22920304dafea47af4aa5ff4ab0ddbe056bb91797e33ff6df274\",\"linux/amd64\":\"https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-linux-amd64?checksum=sha256:236b5b83a7674e0e63ba286739c4670d15d7d6b3dcd810031ff83bdec2c0c2af\",\"linux/arm64\":\"https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-linux-arm64?checksum=sha256:b055fb7011e99d16a3ccae06443b0dcfd745b36480af6b3e569e88c94f3134d3\",\"windows/amd64\":\"https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-windows-amd64.exe?checksum=sha256:f0224ba914cad46dc27d6a9facd8179aec8a70727f0b1e509f0c6171c97ccf76\",\"windows/arm64\":\"https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-windows-arm64.exe?checksum=sha256:cbbce5933d501b4d54dcced9b097c052bffdef3fa8e1dfd75f29b34c3ee7de86\"}}

Final JSON:

{
 "messages": [
  {
   "@type": "/cosmos.upgrade.v1beta1.MsgSoftwareUpgrade",
   "authority": "myprefix10d07y265gmmuvt4z0w9aw880jnsr700ja2wjxw",
   "plan": {
    "name": "v2.0.0",
    "time": "0001-01-01T00:00:00Z",
    "height": "15000",
    "info": "{\"binaries\":{\"darwin/amd64\":\"https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-darwin-amd64?checksum=sha256:7157f03fbad4f53a4c73cde4e75454f4a40a9b09619d3295232341fec99ad138\",\"darwin/arm64\":\"https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-darwin-arm64?checksum=sha256:09e2420151dd22920304dafea47af4aa5ff4ab0ddbe056bb91797e33ff6df274\",\"linux/amd64\":\"https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-linux-amd64?checksum=sha256:236b5b83a7674e0e63ba286739c4670d15d7d6b3dcd810031ff83bdec2c0c2af\",\"linux/arm64\":\"https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-linux-arm64?checksum=sha256:b055fb7011e99d16a3ccae06443b0dcfd745b36480af6b3e569e88c94f3134d3\",\"windows/amd64\":\"https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-windows-amd64.exe?checksum=sha256:f0224ba914cad46dc27d6a9facd8179aec8a70727f0b1e509f0c6171c97ccf76\",\"windows/arm64\":\"https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-windows-arm64.exe?checksum=sha256:cbbce5933d501b4d54dcced9b097c052bffdef3fa8e1dfd75f29b34c3ee7de86\"}}",
    "upgraded_client_state": null
   }
  }
 ],
 "metadata": "ipfs://CID",
 "deposit": "10000000stake",
 "title": "Upgrade to v2",
 "summary": "Upgrades to the latest release v2",
 "expedited": false
}

Example Upgrade Proposal Command:

mychaind tx gov submit-proposal draft_proposal.json --from=alice --chain-id mychain --gas 500000

Step 5: Voting on a Proposal

Query Existing Proposals:
List all the proposals to find the one you want to vote on:
```
mychaind query gov proposals
```
Vote on a Proposal:
Use the proposal ID obtained from the previous step to cast your vote:
```
mychaind tx gov vote [proposal-id] yes --from=alice --chain-id mychain
```
Replace yes with no, no_with_veto, or abstain as per your decision.

Step 6: Managing Proposals

Depositing to a Proposal:
Other users can add deposits to a proposal to help it reach the minimum deposit requirement:
```
mychaind tx gov deposit [proposal-id] 5000000stake --from=bob
```
Tallying Votes:
Once the voting period ends, the proposal is automatically tallied. You can manually trigger tallying (not usually necessary):
```
mychaind q gov tally [proposal-id]
```
Query Proposal Status:
Check the status and details of a specific proposal:
```
mychaind query gov proposal [proposal-id]
```

Step 7: Best Practices

Clear Proposal Descriptions:
Ensure proposals have clear and detailed descriptions to help voters make informed decisions.
Community Engagement:
Engage with the community through discussions and forums to explain and promote your proposals. In the Cosmos ecosystem the community expects a forum proposal to be uploaded 2 weeks prior to the proposal on the blockchain, so the community can already discuss it and tweaks can be applied before uploading the proposal to the blockchain.
Regular Updates:
Provide regular updates on the progress and status of proposals to keep the community informed.

Conclusion

By following these steps, you can effectively create and manage proposals, including upgrade proposals, using the Governance module in a Cosmos SDK-based blockchain. Governance is a powerful tool for decentralised decision-making, enabling the community to shape the future of the blockchain network.

For more detailed information, refer to the Cosmos SDK Governance Module documentation.