Cosmos Parameter-Change Documentation

Parameter-change governance proposals enable the community to vote to enact changes to the Cosmos Hub. For example, these proposals could lower the inflation floor, or raise the penalty for validator downtime. Prior to Cosmos Hub 3, these kinds of changes required the chain to be halted and for validators to start a new chain by running a new version of the software.

Cosmos Parameter Change proposals

Creating this kind of proposal is a process that takes consideration–how could changing the Hub impact upon different stakeholders? Launching this kind of proposal also involves risking ATOMs, which are put at stake as a deposit. Proposers should engage stakeholders so that they are prepared to vote. Version 1.0 of the ‘Community Spend Best Practices’ documentation is intended to make it easier to make high quality community-spend proposals and to enable the voting community to better assess them.

Community Spend Best Practices Version 1.0

On March 24, 2020, I published the first version (v1.0) of the documentation for drafting, evaluating, and launching Cosmos parameter-change governance proposals.

The purpose of this documentation is 1) to guide the technical voice to better communicate proposed adjustments to the Cosmos Hub and 2) to build capacity for less experienced users to finalize and submit a parameter-change proposal on-chain. This doc can also help someone to assess a proposal, particularly when the proposal fails to adequately explain the proposed changes in simple terms.

The objective of this documentation is to make the proposal process easier by preparing participants for what to pay attention to and how to reduce the risk of losing deposits. Ideally, a proposal should only fail to pass because the voters 1) are aware and engaged and 2) are able to make an informed decision to vote down the proposal.

More About This Work

This document should satisfy the deliverable outlined in the Cosmos Hub community-spend proposal ‘Prop23’, and its contents belong to the Cosmos community and to anyone that would like to participate in the Cosmos Hub.

However, I’m looking for feedback on this documentation to improve upon it. Whether you’re educating yourself, working in the Cosmos ecosystem (beyond the Cosmos Hub), and especially if you’re preparing to launch a parameter-change proposal, please consider joining the Cosmos Governance Working Group channels (forumTelegram) to discuss your proposal and/or this doc. Working together can help improve the documentation and your proposal. You can also provide direct feedback here on Github or here on the forum.

Governable Parameters & Best Practices

If you are considering drafting a community-spend proposal governance, you should know:

  1. How the voting process and governance mechanism works
  2. Where and how to engage with the Cosmos community about your proposed change(s)
  3. What the community will likely want to know about the proposed change(s)
  4. How to prepare your final proposal draft for submission
  5. How to submit your proposal to the Cosmos Hub testnet & mainnet

There are currently 8 modules active in the Cosmos Hub with parameters that may be altered via governance proposal. Before proposing to change them, you should know their role in the Cosmos Hub and the potential implications of changing them.

  1. auth – Authentication of accounts and transactions
  2. bank – Token transfer functionalities
  3. gov – On-chain governance proposals and voting
  4. staking – Proof-of-stake layer
  5. slashing – Validator punishment mechanisms
  6. distribution – Fee distribution and staking token provision distribution
  7. crisis – Halting the blockchain under certain circumstances (ie. if an invariant is broken)
  8. mint – Creation of new units of staking token

There is an index of these parameters here.

The value or setting for each parameter may be verified in the chain’s genesis file, found here. The genesis parameter settings are the latest settings that the Cosmos Hub chain launched with. Only a governance proposal or software upgrade can change them.

The Voting Process & Governance Mechanism

A successful proposal is subject to two periods: the deposit period (can last up to 14 days) and the voting period (lasts exactly 14 days). During the deposit period, you’ll need to raise 512 ATOMs for your proposal to enter the voting period. Any number of others may contribute to the deposit amount, but they are putting their ATOMs at risk, since the bond may be burned. You can read more about the conditions of this bond here.

During the voting period, participants may choose to vote either ‘yes’, ‘no’, ‘abstain’, or ‘no-with-veto’. Voters may change their vote at any time before the voting period ends. Currently, the criteria for submitting and passing/failing a parameter-change proposal is the same as the criteria for signalling (text-based) proposals and community-spend proposals.

You can read more about the voting period, how votes are tallied, and how a proposal passes/fails here.

Engagement is Critical

Introduce your idea with known members of the community (preferably experts) before investing resources into drafting a proposal. Are your proposed changes reasonable? Is there a critical flaw? Will key contributors and large stakeholders likely support these changes? Read more about engagement here.

Elements of a Community-Spend Proposal

Ready to draft a governance proposal? Be concise so that people can assess your proposal quickly. Be detailed so that voters will have a clear, meaningful understanding of the changes and their impacts. Key elements for your proposal:

  1. Summary – the key details of the proposal: parameter(s) being changed; reasoning for the changes; potential impacts to stakeholders
    • assume that most people will not read beyond this section
    • try to describe what you are proposing here as simply and concisely as possible
  2. Problem/Value – generally the problem or value that’s motivating the parameter change(s)
  3. Solution – generally how changing the parameter(s) will address the problem or improve the network
    • the beneficiaries of the change(s) (ie. who will these changes impact and how?)
      • voters should understand the importance of the change(s) in a simple way
  4. Risks & Benefits – clearly describe how making this/these change(s) may expose stakeholders to new benefits and/or risks
  5. Supplementary materials – optional materials eg. models, graphs, tables, research, signed petition, etc

Read more about the key proposal elements here.

How can you submit the parameter-change proposal?

If you have a final draft of your proposal ready to submit, consider posting it on the testnet first. These are the three primary steps to getting your parameter-change proposal live on-chain:

  1. (OptionalHosting supplementary materials for your parameter-change proposal with IPFS (InterPlanetary File System)
  2. Formatting the JSON file for the governance proposal transaction that will be on-chain
  3. Sending the transaction that submits your governance proposal on-chain

I’ve detailed step-by-step instructions and simple & complex examples here.

Contributors

This documentation was created by Gavin Birch (Figment Networks). Its development was supported by community funding that was approved on January 29, 2020 by the Cosmos Hub via community-spend proposal Prop23. You can read the full proposal PDF here. You can also create an issue or pull request to participate in its development at any time!

Special thanks to the following for helping to provide credible information that contributed to this wiki’s development: Aleks (All in Bits; Fission Labs), Alessio (All in Bits), Vidor, Hyung (B-Harvest), Joe (Chorus One), Sunny (All in Bits; Sikka). You can read about their contributions here.

Next Steps

Here’s how I think this documentation could be improved upon:

I’d also like to see this work combined with other Cosmos governance documentation, such as the ‘community-spend proposal’ documentation. Ultimately the Cosmos community may find it valuable to have one comprehensive set of docs for every kind of governance proposal.


Hopefully you found this useful. Questions? Comments? Feedback is always welcome! I’m on Twitter.