updated gov docs as specified in issue cosmos#1948 (cosmos#1949)

* updated gov docs as specified in issue cosmos#1948 * fixed links * missed a few links
chillyvee · Dec 12, 2022 · 1db5f2f · 1db5f2f
1 parent a76d309
commit 1db5f2f
Show file tree

Hide file tree

Showing 34 changed files with 662 additions and 795 deletions.
diff --git a/docs/governance/README.md b/docs/governance/README.md
@@ -7,41 +7,19 @@ parent:
 
 # Governance Overview
 
-The Cosmos Hub ("Gaia") has an on-chain governance mechanism for passing
-text proposals,
-changing [consensus parameters](./params-change),
-and spending [funds from the community pool](./community-pool-spend).
+The Cosmos Hub ("Gaia") has an on-chain governance mechanism for [signaling](./proposal-types/text-prop.md), changing [consensus parameters](./proposal-types/param-change.md), and spending [funds from the community pool](./proposal-types/community-pool-spend.md). 
 
-This repository provides background information on these different kinds of proposals
-and best-practices for drafting them and proposing them on-chain.
-It also provides a place for collaborating on draft proposals in plain text on Github.
+This repository provides background information on these different kinds of proposals and best-practices for drafting them and proposing them on-chain.
 
-If you'd like to draft a proposal, start [here](./best-practices.md).
-See the contents below for more background on the governance system,
-the different types of proposals, and how to submit one.
-
-ATOM stakers can find active on-chain proposals to vote on [here](https://www.mintscan.io/cosmos/proposals).
-
-## Contents
-
-- [On-Chain Process](./process.md)
-- [Best Practices for Drafting a Proposal](./best-practices.md)
-- Proposal Types:
-  - Text Proposal
-  - [Parameter Change Proposal](./params-change)
-  - [Community Spend Proposal](./community-pool-spend)
-- [Submitting a Proposal](./submitting.md)
-- [List of Proposals](./proposals)
 
 ## Community
 
-Cosmos governance is driven by the Cosmos community, and much of the documentation in
-this repo was funded by the community fund itself in
-[Proposal 23](https://www.mintscan.io/cosmos/proposals/23).
-Governance discussions happens in a number of places moderated by diverse
-community members, including:
+Cosmos governance is driven by the Cosmos community, and much of the documentation in this repo was funded by the community fund itself in
+[Proposal 23](https://www.mintscan.io/cosmos/proposals/23) and [Proposal 63](https://www.mintscan.io/cosmos/proposals/63).
+Governance discussions happens in a number of places moderated by diverse community members, including:
 
 - [Forum](http://forum.cosmos.network/)
+- [Discord](https://discord.gg/W8trcGV)
+- [Twitter](https://twitter.com/CosmosGov)
 - [Reddit](http://reddit.com/r/cosmosnetwork)
-- [Telegram](https://t.me/atomgov)
 - anywhere else you might interact with members of the Cosmos community!
diff --git a/docs/governance/best-practices.md b/docs/governance/best-practices.md
diff --git a/docs/governance/formatting.md b/docs/governance/formatting.md
diff --git a/docs/governance/params-change/README.md b/docs/governance/params-change/README.md
diff --git a/docs/governance/process.md b/docs/governance/process.md
@@ -4,58 +4,67 @@ order: 2
 
 # On-Chain Proposal Process
 
-## The Proposal Process: Two Periods
+## Governance Parameters
+Several of the numbers involved in governance are parameters and can thus be changed by passing a parameter change proposal. 
+- Minimum deposit: 64 ATOM
+- Maximum deposit period: 14 days
+- Voting period: 14 days
+- Quorum: 40% of participating voting power
+- Pass threshold: 50% of participating voting power
+- Veto threshold: 33.40% of participating voting power
 
-### 1. Deposit Period
 
-The deposit period lasts either 14 days or until the proposal deposit totals 64 ATOMs, whichever happens first.
+## 1. Deposit Period
 
-#### Deposits
+The deposit period lasts either 14 days or until the proposal deposit totals 64 ATOMs, whichever happens first. 
 
-Deposit amounts are at risk of being burned. Prior to a governance proposal entering the voting period (ie. for the proposal to be voted upon), there must be at least a minimum number of ATOMs deposited (64). Anyone may contribute to this deposit. Deposits of passed and failed proposals are returned to the contributors.
+### Deposits
+Prior to a governance proposal entering the voting period (i.e., for the proposal to be voted upon), there must be at least a minimum number of ATOMs deposited (64). Anyone may contribute to this deposit, though it is usually filled by the proposal maker. Deposits of passed and failed proposals are returned to the contributors.
 
-In the past, different people have considered contributions amounts differently. There is some consensus that this should be a personal choice. There is also some consensus that this can be an opportunity for supporters to signal their support by adding to the deposit amount, so a proposer may choose to leave contribution room (ie. a deposit below 64 ATOMs) so that others may participate. It is important to remember that any contributed ATOMs are at risk of being burned.
+In the past, different people have considered contributions amounts differently. There is some consensus that this should be a personal choice. There is also some consensus that this can be an opportunity for supporters to signal their support by adding to the deposit amount, so a proposer may choose to leave contribution room (i.e., a deposit below 64 ATOMs) so that others may participate. It is important to remember that any contributed ATOMs are at risk of being burned.
 
-#### Burned deposits
+### Burned deposits
 
-Deposits are burned only when proposals are vetoed i.e. 33.4% of voting power backing the 'NoWithVeto' option as documented in the [Cosmos SDK gov module spec](https://docs.cosmos.network/main/modules/gov#deposit-refund-and-burn).
+Deposits are burned only when proposals are vetoed as documented in the [Cosmos SDK gov module spec](https://docs.cosmos.network/main/modules/gov#deposit-refund-and-burn). Deposits are not burned for failing to meet quorum or for being rejected. 
 
-### 2. Voting Period
+## 2. Voting Period
 
-The voting period is currently a fixed 14-day period. During the voting period, participants may select a vote of either 'Yes', 'No', 'Abstain', or 'NoWithVeto'. Voters may change their vote at any time before the voting period ends.
+The voting period is currently a fixed 14-day period. During the voting period, participants may select a vote of either 'Yes', 'No', 'Abstain', or 'NoWithVeto'. Voters may change their vote at any time before the voting period ends. 
 
-## What do the voting options mean?
+### What do the voting options mean?
 
-1. **Abstain:** indicates that the voter is impartial to the outcome of the proposal.
-2. **Yes:** indicates approval of the proposal in its current form.
-3. **No:** indicates disapproval of the proposal in its current form.
-4. **NoWithVeto:** indicates stronger opposition to the proposal than simply voting 'No'. If the number of 'NoWithVeto' votes is greater than a third of total votes including 'Abstain' votes, the proposal is rejected and the deposits are [burned](#burned-deposits).
+1. **Abstain:** The voter wishes to contribute to quorum without voting for or against a proposal.
+2. **Yes:** Approval of the proposal in its current form.
+3. **No:** Disapproval of the proposal in its current form.
+4. **NoWithVeto:** A ‘NoWithVeto’ vote indicates a proposal either (1) is deemed to be spam, i.e., irrelevant to Cosmos Hub, (2) disproportionately infringes on minority interests, or (3) violates or encourages violation of the rules of engagement as currently set out by Cosmos Hub governance.
 
-As accepted by the community in [Proposal 6](https://ipfs.io/ipfs/QmRtR7qkeaZCpCzHDwHgJeJAZdTrbmHLxFDYXhw7RoF1pp), voters are expected to vote 'NoWithVeto' if a proposal leads to undesireable outcomes for the community. It states “if a proposal seems to be spam or is deemed to have caused a negative externality to Cosmos community, voters should vote _NoWithVeto_.”
+As accepted by the community in [Proposal 75](https://ipfs.io/ipfs/QmVHVH9WeGy9tTNN9dViqvDn7N79XJJUseKXD1rpyLVckK), voters are expected to vote 'NoWithVeto' for proposals that are spam, infringe on minority interests, or violate the rules of engagement (i.e., Social protocols which have passed governance and thus been accepted as rules on the Hub). This proposal was an extension of the ideas put forward in [Proposal 6](https://ipfs.io/ipfs/QmRtR7qkeaZCpCzHDwHgJeJAZdTrbmHLxFDYXhw7RoF1pp).
 
-Voting 'NoWithVeto' provides a mechanism for a minority group representing a _third_ of the participating voting power to reject a proposal that would otherwise pass. This makes explicit an aspect of the consensus protocol: it works as long as only up to [a third of nodes fail](https://docs.tendermint.com/v0.34/introduction/what-is-tendermint.html). In other words, greater than a third of validators are always in a position to cause a proposal to fail outside the formalized governance process and the network's norms, such as by censoring transactions. The purpose of internalizing this aspect of the consensus protocol into the governance process is to discourage validators from relying on collusion and censorship tactics to influence voting outcomes.
+Voting 'NoWithVeto' has no immediate additional financial cost to the voter - you do not directly risk your ATOM by using this option.
 
-## What determines whether or not a governance proposal passes?
+### What determines whether or not a governance proposal passes?
 
 There are four criteria:
 
-1. A minimum deposit of 64 ATOM is required for the proposal to enter the voting period
+1. Deposit is filled: A minimum deposit of 64 ATOM is required for the proposal to enter the voting period
    - anyone may contribute to this deposit
    - the deposit must be reached within 14 days (this is the deposit period)
-2. A minimum of 40% of the network's voting power (quorum) is required to participate to make the proposal valid
-3. A simple majority (greater than 50%) of the participating voting power must back the 'Yes' vote during the 14-day voting period
-4. Less than 33.4% of participating voting power votes 'NoWithVeto'
+2. Quorum is reached: A minimum of 40% of the network's total voting power (staked ATOM) is required to participate 
+3. Simple majority of 'Yes' votes: Greater than 50% of the participating voting power must back the 'Yes' vote by the end of the 14-day voting period
+4. Not vetoed: Less than 33.4% of participating voting power must have backed 'NoWithVeto' by the end of the 14-day voting period
 
 Currently, the criteria for submitting and passing/failing all proposal types is the same.
 
-### How is voting tallied?
+### How is quorum determined?
 
-Voting power is determined by stake weight at the end of the 14-day voting period and is proportional to the number of total ATOMs participating in the vote. Only bonded ATOMs count towards the voting power for a governance proposal. Liquid ATOMs will not count toward a vote or quorum.
+Voting power, whether backing a vote of 'Yes', 'Abstain', 'No', or 'NoWithVeto', counts toward quorum. Quorum is required for the outcome of a governance proposal vote to be considered valid and for deposit contributors to recover their deposit amounts. 
 
-Inactive validators can cast a vote, but their voting power (including the backing of their delegators) will not count toward the vote if they are not in the active set when the voting period ends. That means that if I delegate to a validator that is either jailed, tombstoned, or ranked lower than 125 in stake-backing at the time that the voting period ends, my stake-weight will not count in the vote.
+### How is voting tallied?
 
-Though a simple majority 'Yes' vote (ie. 50% of participating voting power) is required for a governance proposal vote to pass, a 'NoWithVeto' vote of 33.4% of participating voting power or greater can override this outcome and cause the proposal to fail. This enables a minority group representing greater than 1/3 of voting power to fail a proposal that would otherwise pass.
+- **Total voting power** refers to all staked ATOM at the end of the 14-day voting period. Liquid ATOMs are not part of the total voting power and thus cannot participate in voting. 
+- **Participating voting power** refers to only the ATOM which have been used to cast a vote on a particular proposal. Quorum is set to 40% of the **participating** voting power.
 
-### How is quorum determined?
+Validators not in the active set can cast a vote, but their voting power (including the backing of their delegators) will not count toward the vote if they are not in the active set **when the voting period ends**. That means that if ATOM is delegated to a validator that is jailed, tombstoned, or outside of the active set at the time that the voting period ends, that ATOM's stake-weight will not count in the vote.
+
+Though a simple majority 'Yes' vote (ie. 50% of participating voting power) is required for a governance proposal vote to pass, a 'NoWithVeto' vote of 33.4% of participating voting power or greater can override this outcome and cause the proposal to fail. This enables a minority group representing greater than 1/3 of participating voting power to fail a proposal that would otherwise pass.
 
-Voting power, whether backing a vote of 'Yes', 'Abstain', 'No', or 'NoWithVeto', counts toward quorum. Quorum is required for the outcome of a governance proposal vote to be considered valid and for deposit contributors to recover their deposit amounts. If the proposal vote does not reach quorum (ie. less than 40% of the network's voting power is participating) within 14 days, any deposit amounts will be burned and the proposal outcome will not be considered to be valid.