diff --git a/x/gov/spec/01_concepts.md b/x/gov/spec/01_concepts.md index 0acbfa3b709b..becb7cc6de2f 100644 --- a/x/gov/spec/01_concepts.md +++ b/x/gov/spec/01_concepts.md @@ -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 diff --git a/x/gov/spec/02_state.md b/x/gov/spec/02_state.md index ba3b12b3f3a7..4175367fdfb8 100644 --- a/x/gov/spec/02_state.md +++ b/x/gov/spec/02_state.md @@ -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 { diff --git a/x/gov/spec/03_messages.md b/x/gov/spec/03_messages.md index cac55b5ed945..59aa255f4cb4 100644 --- a/x/gov/spec/03_messages.md +++ b/x/gov/spec/03_messages.md @@ -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.