x/gov docs basic cleanup (#8279)
* update docs * review changes * review changes * review changes * review changes * review changes Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
This commit is contained in:
atheeshp
GitHub
parent
b4bc63dd78
commit
eafd1bc945
|
|
@ -29,18 +29,24 @@ its unique `proposalID`.
|
|||
|
||||
### Proposal types
|
||||
|
||||
In the initial version of the governance module, there are two types of
|
||||
proposal:
|
||||
In the initial version of the governance module, there are five types of
|
||||
proposals:
|
||||
|
||||
- `PlainTextProposal` All the proposals that do not involve a modification of
|
||||
- `TextProposal` All the proposals that do not involve a modification of
|
||||
the source code go under this type. For example, an opinion poll would use a
|
||||
proposal of type `PlainTextProposal`.
|
||||
proposal of type `TextProposal`.
|
||||
- `SoftwareUpgradeProposal`. If accepted, validators are expected to update
|
||||
their software in accordance with the proposal. They must do so by following
|
||||
a 2-steps process described in the [Software Upgrade](#software-upgrade)
|
||||
section below. Software upgrade roadmap may be discussed and agreed on via
|
||||
`PlainTextProposals`, but actual software upgrades must be performed via
|
||||
`TextProposals`, but actual software upgrades must be performed via
|
||||
`SoftwareUpgradeProposals`.
|
||||
- `CommunityPoolSpendProposal` details a proposal for use of community funds,
|
||||
together with how many coins are proposed to be spent, and to which recipient account.
|
||||
- `ParameterChangeProposal` defines a proposal to change one or
|
||||
more parameters. If accepted, the requested parameter change is updated
|
||||
automatically by the proposal handler upon conclusion of the voting period.
|
||||
- `CancelSoftwareUpgradeProposal` is a gov Content type for cancelling a software upgrade.
|
||||
|
||||
Other modules may expand upon the governance module by implementing their own
|
||||
proposal types and handlers. These types are registered and processed through the
|
||||
|
|
|
|||
|
|
@ -11,26 +11,14 @@ be one active parameter set at any given time. If governance wants to change a
|
|||
parameter set, either to modify a value or add/remove a parameter field, a new
|
||||
parameter set has to be created and the previous one rendered inactive.
|
||||
|
||||
```go
|
||||
type DepositParams struct {
|
||||
MinDeposit sdk.Coins // Minimum deposit for a proposal to enter voting period.
|
||||
MaxDepositPeriod time.Time // Maximum period for Atom holders to deposit on a proposal. Initial value: 2 months
|
||||
}
|
||||
```
|
||||
### DepositParams
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L127-L145
|
||||
|
||||
```go
|
||||
type VotingParams struct {
|
||||
VotingPeriod time.Time // Length of the voting period. Initial value: 2 weeks
|
||||
}
|
||||
```
|
||||
### VotingParams
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L147-L156
|
||||
|
||||
```go
|
||||
type TallyParams struct {
|
||||
Quorum sdk.Dec // Minimum percentage of stake that needs to vote for a proposal to be considered valid
|
||||
Threshold sdk.Dec // Minimum proportion of Yes votes for proposal to pass. Initial value: 0.5
|
||||
Veto sdk.Dec // Minimum proportion of Veto votes to Total votes ratio for proposal to be vetoed. Initial value: 1/3
|
||||
}
|
||||
```
|
||||
### TallyParams
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L158-L183
|
||||
|
||||
Parameters are stored in a global `GlobalParams` KVStore.
|
||||
|
||||
|
|
@ -68,12 +56,7 @@ const (
|
|||
|
||||
## Deposit
|
||||
|
||||
```go
|
||||
type Deposit struct {
|
||||
Amount sdk.Coins // Amount of coins deposited by depositor
|
||||
Depositor crypto.address // Address of depositor
|
||||
}
|
||||
```
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L43-L53
|
||||
|
||||
## ValidatorGovInfo
|
||||
|
||||
|
|
@ -92,22 +75,7 @@ This type is used in a temp map when tallying
|
|||
what this proposal is about, and other fields, which are the mutable state of
|
||||
the governance process.
|
||||
|
||||
```go
|
||||
type Proposal struct {
|
||||
Content // Proposal content interface
|
||||
|
||||
ProposalID uint64
|
||||
Status ProposalStatus // Status of the Proposal {Pending, Active, Passed, Rejected}
|
||||
FinalTallyResult TallyResult // Result of Tallies
|
||||
|
||||
SubmitTime time.Time // Time of the block where TxGovSubmitProposal was included
|
||||
DepositEndTime time.Time // Time that the Proposal would expire if deposit amount isn't met
|
||||
TotalDeposit sdk.Coins // Current deposit on this proposal. Initial value is set at InitialDeposit
|
||||
|
||||
VotingStartTime time.Time // Time of the block where MinDeposit was reached. -1 if MinDeposit is not reached
|
||||
VotingEndTime time.Time // Time that the VotingPeriod for this proposal will end and votes will be tallied
|
||||
}
|
||||
```
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L55-L77
|
||||
|
||||
```go
|
||||
type Content interface {
|
||||
|
|
|
|||
|
|
@ -6,18 +6,12 @@ order: 3
|
|||
|
||||
## Proposal Submission
|
||||
|
||||
Proposals can be submitted by any Atom holder via a `TxGovSubmitProposal`
|
||||
Proposals can be submitted by any account via a `MsgSubmitProposal`
|
||||
transaction.
|
||||
|
||||
```go
|
||||
type TxGovSubmitProposal struct {
|
||||
Content Content
|
||||
InitialDeposit sdk.Coins
|
||||
Proposer sdk.AccAddress
|
||||
}
|
||||
```
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/tx.proto#L24-L39
|
||||
|
||||
The `Content` of a `TxGovSubmitProposal` message must have an appropriate router
|
||||
The `Content` of a `MsgSubmitProposal` message must have an appropriate router
|
||||
set in the governance module.
|
||||
|
||||
**State modifications:**
|
||||
|
|
@ -30,12 +24,12 @@ set in the governance module.
|
|||
- Push `proposalID` in `ProposalProcessingQueue`
|
||||
- Transfer `InitialDeposit` from the `Proposer` to the governance `ModuleAccount`
|
||||
|
||||
A `TxGovSubmitProposal` transaction can be handled according to the following
|
||||
A `MsgSubmitProposal` transaction can be handled according to the following
|
||||
pseudocode.
|
||||
|
||||
```go
|
||||
// PSEUDOCODE //
|
||||
// Check if TxGovSubmitProposal is valid. If it is, create proposal //
|
||||
// Check if MsgSubmitProposal is valid. If it is, create proposal //
|
||||
|
||||
upon receiving txGovSubmitProposal from sender do
|
||||
|
||||
|
|
@ -79,14 +73,9 @@ upon receiving txGovSubmitProposal from sender do
|
|||
|
||||
Once a proposal is submitted, if
|
||||
`Proposal.TotalDeposit < ActiveParam.MinDeposit`, Atom holders can send
|
||||
`TxGovDeposit` transactions to increase the proposal's deposit.
|
||||
`MsgDeposit` transactions to increase the proposal's deposit.
|
||||
|
||||
```go
|
||||
type TxGovDeposit struct {
|
||||
ProposalID int64 // ID of the proposal
|
||||
Deposit sdk.Coins // Number of Atoms to add to the proposal's deposit
|
||||
}
|
||||
```
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/tx.proto#L61-L72
|
||||
|
||||
**State modifications:**
|
||||
|
||||
|
|
@ -97,12 +86,12 @@ type TxGovDeposit struct {
|
|||
- Push `proposalID` in `ProposalProcessingQueueEnd`
|
||||
- Transfer `Deposit` from the `proposer` to the governance `ModuleAccount`
|
||||
|
||||
A `TxGovDeposit` transaction has to go through a number of checks to be valid.
|
||||
A `MsgDeposit` transaction has to go through a number of checks to be valid.
|
||||
These checks are outlined in the following pseudocode.
|
||||
|
||||
```go
|
||||
// PSEUDOCODE //
|
||||
// Check if TxGovDeposit is valid. If it is, increase deposit and check if MinDeposit is reached
|
||||
// Check if MsgDeposit is valid. If it is, increase deposit and check if MinDeposit is reached
|
||||
|
||||
upon receiving txGovDeposit from sender do
|
||||
// check if proposal is correctly formatted. Includes fee payment.
|
||||
|
|
@ -149,15 +138,10 @@ upon receiving txGovDeposit from sender do
|
|||
## Vote
|
||||
|
||||
Once `ActiveParam.MinDeposit` is reached, voting period starts. From there,
|
||||
bonded Atom holders are able to send `TxGovVote` transactions to cast their
|
||||
bonded Atom holders are able to send `MsgVote` transactions to cast their
|
||||
vote on the proposal.
|
||||
|
||||
```go
|
||||
type TxGovVote struct {
|
||||
ProposalID int64 // proposalID of the proposal
|
||||
Vote byte // option from OptionSet chosen by the voter
|
||||
}
|
||||
```
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/tx.proto#L46-L56
|
||||
|
||||
**State modifications:**
|
||||
|
||||
|
|
@ -165,12 +149,12 @@ vote on the proposal.
|
|||
|
||||
_Note: Gas cost for this message has to take into account the future tallying of the vote in EndBlocker_
|
||||
|
||||
Next is a pseudocode proposal of the way `TxGovVote` transactions are
|
||||
Next is a pseudocode outline of the way `MsgVote` transactions are
|
||||
handled:
|
||||
|
||||
```go
|
||||
// PSEUDOCODE //
|
||||
// Check if TxGovVote is valid. If it is, count vote//
|
||||
// Check if MsgVote is valid. If it is, count vote//
|
||||
|
||||
upon receiving txGovVote from sender do
|
||||
// check if proposal is correctly formatted. Includes fee payment.
|
||||
|
|
|
|||
Loading…
Reference in New Issue