diff --git a/docs/architecture/adr-069-gov-improvements.md b/docs/architecture/adr-069-gov-improvements.md deleted file mode 100644 index 1ef6971c713d..000000000000 --- a/docs/architecture/adr-069-gov-improvements.md +++ /dev/null @@ -1,224 +0,0 @@ -# ADR 069: `x/gov` modularity, multiple choice and optimistic proposals - -## Changelog - -* 2023-11-17: Initial draft (@julienrbrt, @tac0turtle) - -## Status - -ACCEPTED - Implemented - -## Abstract - -Governance is an important aspect of Cosmos SDK chains. - -This ADR aimed to extend the `x/gov` module functionalities by adding two different kinds of proposals, as well as making `x/gov` more composable and extendable. - -Those two types are, namely: multiple choice proposals and optimistic proposals. - -## Context - -`x/gov` is the center of Cosmos governance, and has already been improved from its first version `v1beta1`, with a second version [`v1`][5]. -This second iteration of gov unlocked many possibilities by letting governance proposals contain any number of proposals. -The last addition of gov has been expedited proposals (proposals that have a shorter voting period and a higher quorum, approval threshold). - -The community requested ([1], [4]) two additional proposals for improving governance choices. Those proposals would be useful when having protocol decisions made on specific choices or simplifying regular proposals that do not require high community involvement. - -Additionally, the SDK should allow chains to customize the tallying method of proposals (if they want to count the votes in another way). Currently, the Cosmos SDK counts votes proportionally to the voting power/stake. However, custom tallying could allow counting votes with a quadratic function instead. - -## Decision - -`x/gov` will integrate these functions and extract helpers and interfaces for extending the `x/gov` module capabilities. - -### Proposals - -Currently, all proposals are [`v1.Proposal`][5]. Optimistic and multiple choice proposals require a different tally logic, but the rest of the proposal stays the same to not create other proposal types, `v1.Proposal` will have an extra field: - -```protobuf -// ProposalType enumerates the valid proposal types. -// All proposal types are v1.Proposal which have different voting periods or tallying logic. -enum ProposalType { - // PROPOSAL_TYPE_UNSPECIFIED defines no proposal type, which fallback to PROPOSAL_TYPE_STANDARD. - PROPOSAL_TYPE_UNSPECIFIED = 0; - // PROPOSAL_TYPE_STANDARD defines the type for a standard proposal. - PROPOSAL_TYPE_STANDARD = 1; - // PROPOSAL_TYPE_MULTIPLE_CHOICE defines the type for a multiple choice proposal. - PROPOSAL_TYPE_MULTIPLE_CHOICE = 2; - // PROPOSAL_TYPE_OPTIMISTIC defines the type for an optimistic proposal. - PROPOSAL_TYPE_OPTIMISTIC = 3; - // PROPOSAL_TYPE_EXPEDITED defines the type for an expedited proposal. - PROPOSAL_TYPE_EXPEDITED = 4; -} -``` - -Note, that expedited becomes a proposal type itself instead of a boolean on the `v1.Proposal` struct. - -> An expedited proposal is by design a standard proposal with a quicker voting period and higher threshold. When an expedited proposal fails, it gets converted to a standard proposal. - -An expedited optimistic proposal and an expedited multiple choice proposal do not make sense based on the definition above and is a proposal type instead of a proposal characteristic. - -#### Optimistic Proposal - -An optimistic proposal is a proposal that passes unless a threshold a NO votes is reached. - -Voter can only vote NO on the proposal. If the NO threshold is reached, the optimistic proposal is converted to a standard proposal. - -Two governance parameters will be in added [`v1.Params`][5] to support optimistic proposals: - -```protobuf -// optimistic_authorized_addreses is an optional governance parameter that limits the authorized accounts that can submit optimistic proposals -repeated string optimistic_authorized_addreses = 17 [(cosmos_proto.scalar) = "cosmos.AddressString"]; - -// Optimistic rejected threshold defines at which percentage of NO votes, the optimistic proposal should fail and be converted to a standard proposal. -string optimistic_rejected_threshold = 18 [(cosmos_proto.scalar) = "cosmos.Dec"]; -``` - -#### Multiple Choice Proposal - -A multiple choice proposal is a proposal where the voting options can be defined by the proposer. - -The number of voting options will be limited to a maximum of 4. -A new vote option `SPAM` will be added and distinguished from those voting options. `SPAM` will be used to mark a proposal as spam and is explained further below. - -Multiple choice proposals, contrary to any other proposal type, cannot have messages to execute. They are only text proposals. - -Submitting a new multiple choice proposal will use a different message than the [`v1.MsgSubmitProposal`][5]. This is done in order to simplify the proposal submission and allow defining the voting options directly. - - -```protobuf -message MsgSubmitMultipleChoiceProposal { - repeated cosmos.base.v1beta1.Coin initial_deposit = 1; - string proposer = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"]; - string metadata = 3; - string title = 4; - string summary = 5; - string option_one = 6; - string option_two = 7; - string option_three = 8; - string option_four = 9; -} -``` - -Voters can only vote on the defined options in the proposal. - -To maintain compatibility with the existing endpoints, the voting options will not be stored in the proposal itself and each option will be mapped to [`v1.VoteOption`][5]. A multiple choice proposal will be stored as a [`v1.Proposal`][5]. A query will be available for multiple choice proposal types to get the voting options. - -### Votes - -As mentioned above [multiple choice proposal](#multiple-choice-proposal) will introduce an additional vote option: `SPAM`. - -This vote option will be supported by all proposal types. -At the end of the voting period, if a proposal is voted as `SPAM`, it fails and its deposit is burned. - -`SPAM` differs from the `No with Veto` vote as its threshold is dynamic. -A proposal is marked as `SPAM` when the total of weighted votes for all options is lower than the amount of weighted vote on `SPAM` -(`spam` > `option_one + option_two + option_three + option_four` = proposal marked as spam). -This allows clear spam proposals to be marked as spam easily, even with low participation from validators. - -To avoid voters wrongfully voting down a proposal as `SPAM`, voters will be slashed `x`% (default 0%) of their voting stake if they voted `SPAM` on a proposal that wasn't a spam proposal. The parameter allows to incentivise voters to only vote `SPAM` on actual spam proposals and not use `SPAM` as a way to vote `No with Veto` with a different threshold. - -This leads to the addition of the following governance parameter in [`v1.Params`][5]: - -```protobuf -// burn_spam_amount defines the percentage of the voting stake that will be burned if a voter votes SPAM on a proposal that is not marked as SPAM. -string burn_spam_amount = 8 [(cosmos_proto.scalar) = "cosmos.Dec"]; -``` - -Additionally, the current vote options will be aliased to better accommodate the multiple choice proposal: - -```protobuf -// VoteOption enumerates the valid vote options for a given governance proposal. -enum VoteOption { - option allow_alias = true; - - // VOTE_OPTION_UNSPECIFIED defines a no-op vote option. - VOTE_OPTION_UNSPECIFIED = 0; - // VOTE_OPTION_ONE defines the first proposal vote option. - VOTE_OPTION_ONE = 1; - // VOTE_OPTION_YES defines the yes proposal vote option. - VOTE_OPTION_YES = 1; - // VOTE_OPTION_TWO defines the second proposal vote option. - VOTE_OPTION_TWO = 2; - // VOTE_OPTION_ABSTAIN defines the abstain proposal vote option. - VOTE_OPTION_ABSTAIN = 2; - // VOTE_OPTION_THREE defines the third proposal vote option. - VOTE_OPTION_THREE = 3; - // VOTE_OPTION_NO defines the no proposal vote option. - VOTE_OPTION_NO = 3; - // VOTE_OPTION_FOUR defines the fourth proposal vote option. - VOTE_OPTION_FOUR = 4; - // VOTE_OPTION_NO_WITH_VETO defines the no with veto proposal vote option. - VOTE_OPTION_NO_WITH_VETO = 4; - // VOTE_OPTION_SPAM defines the spam proposal vote option. - VOTE_OPTION_SPAM = 5; -} -``` - -The order does not change for a standard proposal (1 = yes, 2 = abstain, 3 = no, 4 = no with veto as it was) and the aliased enum can be used interchangeably. - -Updating vote options means updating [`v1.TallyResult`][5] as well. - -#### Tally - -Due to the vote option change, each proposal can have the same tallying method. - -However, chains may want to change the tallying function (weighted vote per voting power) of `x/gov` for a different algorithm (using a quadratic function on the voter stake, for instance). - -The custom tallying function can be passed to the `x/gov` keeper config: - -```go -type CalculateVoteResultsAndVotingPowerFn func( - ctx context.Context, - keeper Keeper, - proposalID uint64, - validators map[string]v1.ValidatorGovInfo, -) (totalVoterPower math.LegacyDec, results map[v1.VoteOption]math.LegacyDec, err error) -``` - -## Consequences - -Changing voting possibilities has a direct consequence for the clients. Clients, like Keplr or Mintscan, need to implement logic for multiple choice proposals. - -That logic consists of querying multiple choice proposals vote mapping their vote options. - -### Backwards Compatibility - -Legacy proposals (`v1beta1`) endpoints will not be supporting the new proposal types. - -Voting on a gov v1 proposal having a different type than [`standard` or `expedited`](#proposals) via the `v1beta1` will not be supported. -This is already the case for the expedited proposals. - -### Positive - -* Extended governance features -* Extended governance customization - -### Negative - -* Increase gov wiring complexity - -### Neutral - -* Increases the number of parameters available - -## Further Discussions - -This ADR starts the `x/gov` overhaul for the `cosmossdk.io/x/gov` v1.0.0 release. -Further internal improvements of `x/gov` will happen soon after, in order to simplify its state management and making gov calculation in a more "lazy"-fashion. - -Those improvements may change the tallying api. - -* https://github.com/cosmos/cosmos-sdk/issues/16270 - -## References - -* [https://github.com/cosmos/cosmos-sdk/issues/16270][1] -* [https://github.com/cosmos/cosmos-sdk/issues/17781][2] -* [https://github.com/cosmos/cosmos-sdk/issues/14403][3] -* [https://github.com/decentralists/DAO/issues/28][4] - -[1]: https://grants.osmosis.zone/blog/rfp-cosmos-sdk-governance-module-improvements -[2]: https://github.com/cosmos/cosmos-sdk/issues/17781 -[3]: https://github.com/cosmos/cosmos-sdk/issues/14403 -[4]: https://github.com/decentralists/DAO/issues/28 -[5]: https://buf.build/cosmos/cosmos-sdk/docs/main:cosmos.gov.v1 diff --git a/x/gov/README.md b/x/gov/README.md index e0d412cee156..87b2fc5fad6c 100644 --- a/x/gov/README.md +++ b/x/gov/README.md @@ -18,16 +18,13 @@ currently supports: * **Proposal submission:** Users can submit proposals with a deposit. Once the minimum deposit is reached, the proposal enters voting period. The minimum deposit can be reached by collecting deposits from different users (including proposer) within deposit period. * **Vote:** Participants can vote on proposals that reached MinDeposit and entered voting period. -* **Inheritance and penalties:** Delegators, by default, inherit their validator's vote if they don't vote themselves. +* **Inheritance and penalties:** Delegators inherit their validator's vote if +they don't vote themselves. * **Claiming deposit:** Users that deposited on proposals can recover their -<<<<<<< HEAD deposits if the proposal was accepted or rejected. If the proposal was vetoed, or never entered voting period (minimum deposit not reached within deposit period), the deposit is burned. This module is in use on the Cosmos Hub (a.k.a [gaia](https://github.com/cosmos/gaia)). Features that may be added in the future are described in [Future Improvements](#future-improvements). -======= -deposits if the proposal was accepted or rejected. If the proposal was vetoed, or never entered voting period (minimum deposit not reached within deposit period), the deposit is burned (or refunded depending on the gov parameters). ->>>>>>> deec679f2 (docs: update gov docs (#22048)) ## Contents @@ -63,6 +60,7 @@ staking token of the chain. * [Metadata](#metadata) * [Proposal](#proposal-3) * [Vote](#vote-5) +* [Future Improvements](#future-improvements) ## Concepts @@ -92,7 +90,7 @@ proposal passes. The messages are executed by the governance `ModuleAccount` its such as `x/upgrade`, that want to allow certain messages to be executed by governance only should add a whitelist within the respective msg server, granting the governance module the right to execute the message once a quorum has been reached. The governance -module uses the core `router.Service` to check that these messages are correctly constructed +module uses the `MsgServiceRouter` to check that these messages are correctly constructed and have a respective path to execute on but do not perform a full validity check. ### Deposit @@ -118,22 +116,16 @@ proposal is finalized (passed or rejected). #### Deposit refund and burn When a proposal is finalized, the coins from the deposit are either refunded or burned -according to the final tally of the proposal and the governance module parameters: +according to the final tally of the proposal: -* All refunded or burned deposits are removed from the state. Events are issued when - burning or refunding a deposit. * If the proposal is approved or rejected but *not* vetoed, each deposit will be automatically refunded to its respective depositor (transferred from the governance `ModuleAccount`). -* If the proposal is marked as Spam, the deposit will be burned. - -For other cases, they are three parameters that define if the deposit of a proposal should be burned or returned to the depositors. - -* `BurnVoteVeto` burns the proposal deposit if the proposal gets vetoed. -* `BurnVoteQuorum` burns the proposal deposit if the vote does not reach quorum. -* `BurnProposalDepositPrevote` burns the proposal deposit if it does not enter the voting phase. - -> Note: These parameters are modifiable via governance. +* When the proposal is vetoed with greater than 1/3, deposits will be burned from the + governance `ModuleAccount` and the proposal information along with its deposit + information will be removed from state. +* All refunded or burned deposits are removed from the state. Events are issued when + burning or refunding a deposit. ### Vote @@ -150,7 +142,7 @@ Note that when *participants* have bonded and unbonded Atoms, their voting power Once a proposal reaches `MinDeposit`, it immediately enters `Voting period`. We define `Voting period` as the interval between the moment the vote opens and -the moment the vote closes. The default value of `Voting period` is 2 weeks but is modifiable at genesis or governance. +the moment the vote closes. The initial value of `Voting period` is 2 weeks. #### Option set @@ -168,6 +160,8 @@ The initial option set includes the following options: allows voters to signal that they do not intend to vote in favor or against the proposal but accept the result of the vote. +*Note: from the UI, for urgent proposals we should maybe add a ‘Not Urgent’ option that casts a `NoWithVeto` vote.* + #### Weighted Votes [ADR-037](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-037-gov-split-vote.md) introduces the weighted vote feature which allows a staker to split their votes into several voting options. For example, it could use 70% of its voting power to vote Yes and 30% of its voting power to vote No. @@ -177,11 +171,11 @@ Often times the entity owning that address might not be a single individual. For To represent weighted vote on chain, we use the following Protobuf message. ```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/x/gov/proto/cosmos/gov/v1/gov.proto#L56-L63 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1beta1/gov.proto#L34-L47 ``` ```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/x/gov/proto/cosmos/gov/v1/gov.proto#L202-L219 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1beta1/gov.proto#L181-L201 ``` For a weighted vote to be valid, the `options` field must not contain duplicate vote options, and the sum of weights of all options must be equal to 1. @@ -191,59 +185,18 @@ For a weighted vote to be valid, the `options` field must not contain duplicate Quorum is defined as the minimum percentage of voting power that needs to be cast on a proposal for the result to be valid. -<<<<<<< HEAD ### Expedited Proposals A proposal can be expedited, making the proposal use shorter voting duration and a higher tally threshold by its default. If an expedited proposal fails to meet the threshold within the scope of shorter voting duration, the expedited proposal is then converted to a regular proposal and restarts voting under regular voting conditions. #### Threshold -======= -### Expedited Quorum - -Expedited Quorum is defined as the minimum percentage of voting power that needs to be -cast on an **expedited** proposal for the result to be valid. - -### Yes Quorum - -Yes quorum is a more restrictive quorum that is used to determine if a proposal passes. -It is defined as the minimum percentage of voting power that needs to have voted `Yes` for the proposal to pass. -It differs from `Threshold` as it takes the whole voting power into account, not only `Yes` and `No` votes. -By default, `YesQuorum` is set to 0, which means no minimum. - -### Proposal Types - -Proposal types have been introduced in [ADR-069](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-069-gov-improvements.md). - -#### Standard proposal - -A standard proposal is a proposal that can contain any messages. The proposal follows the standard governance flow and governance parameters. - -#### Expedited Proposal -A proposal can be expedited, making the proposal use shorter voting duration and a higher tally threshold by its default. If an expedited proposal fails to meet the threshold within the scope of shorter voting duration, the expedited proposal is then converted to a regular proposal and restarts voting under regular voting conditions. - -#### Optimistic Proposal - -An optimistic proposal is a proposal that passes unless a threshold of NO votes is reached. -Voter can only vote NO on the proposal. If the NO threshold is reached, the optimistic proposal is converted to a standard proposal. - -That threshold is defined by the `optimistic_rejected_threshold` governance parameter. -A chain can optionally set a list of authorized addresses that can submit optimistic proposals using the `optimistic_authorized_addresses` governance parameter. - -#### Multiple Choice Proposals - -A multiple choice proposal is a proposal where the voting options can be defined by the proposer. -The number of voting options is limited to a maximum of **4**. -Multiple choice proposals, contrary to any other proposal type, cannot have messages to execute. They are only text proposals. - -### Threshold ->>>>>>> deec679f2 (docs: update gov docs (#22048)) - -Threshold is defined as the minimum proportion of `Yes` votes (excluding `Abstain` votes) for the proposal to be accepted. +Threshold is defined as the minimum proportion of `Yes` votes (excluding +`Abstain` votes) for the proposal to be accepted. -Initially, the threshold is set at 50% of `Yes` votes, excluding `Abstain` votes. -A possibility to veto exists if more than 1/3rd of all votes are `NoWithVeto` votes. -Note, both of these values are derived from the `Params` +Initially, the threshold is set at 50% of `Yes` votes, excluding `Abstain` +votes. A possibility to veto exists if more than 1/3rd of all votes are +`NoWithVeto` votes. Note, both of these values are derived from the `TallyParams` on-chain parameter, which is modifiable by governance. This means that proposals are accepted iff: @@ -257,26 +210,21 @@ This means that proposals are accepted iff: For expedited proposals, by default, the threshold is higher than with a *normal proposal*, namely, 66.7%. -### Inheritance +#### Inheritance -If a delegator does not vote, by default, it will inherit its validator vote. +If a delegator does not vote, it will inherit its validator vote. -* If the delegator votes before its validator, it will not inherit from the validator's vote. -* If the delegator votes after its validator, it will override its validator vote with its own. - If the proposal is urgent, it is possible that the vote will close before delegators have a chance to react and +* If the delegator votes before its validator, it will not inherit from the + validator's vote. +* If the delegator votes after its validator, it will override its validator + vote with its own. If the proposal is urgent, it is possible + that the vote will close before delegators have a chance to react and override their validator's vote. This is not a problem, as proposals require more than 2/3rd of the total voting power to pass, when tallied at the end of the voting period. Because as little as 1/3 + 1 validation power could collude to censor transactions, non-collusion is already assumed for ranges exceeding this threshold. -This behavior can be changed by passing a custom tally calculation function to the governance module. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/x/gov/keeper/config.go#L33-L35 -``` - #### Validator’s punishment for non-voting At present, validators are not punished for failing to vote. -<<<<<<< HEAD #### Governance address Later, we may add permissioned keys that could only sign txs from certain modules. For the MVP, the `Governance address` will be the main validator address generated at account creation. This address corresponds to a different PrivKey than the CometBFT PrivKey which is responsible for signing consensus messages. Validators thus do not have to sign governance transactions with the sensitive CometBFT PrivKey. @@ -290,20 +238,9 @@ There are three parameters that define if the deposit of a proposal should be bu * `BurnProposalDepositPrevote` burns the proposal deposit if it does not enter the voting phase. > Note: These parameters are modifiable via governance. -======= -#### Execution - -Execution is the process of executing the messages contained in a proposal. The execution phase will commence after the proposal has been accepted by the network. The messages contained in the proposal will be executed in the order they were submitted. All messages must be executed successfully for the proposal to be considered successful. I - -If a proposal passes but fails to execute, the proposal will be marked as `StatusFailed`. This status is different from `StatusRejected`, which is used when a proposal fails to pass. - -Execution has an upper limit on how much gas can be consumed in a single block. This limit is defined by the `ProposalExecutionGas` parameter. ->>>>>>> deec679f2 (docs: update gov docs (#22048)) ## State -The governance module uses [collections](https://docs.cosmos.network/v0.50/build/packages/collections) for state management. - ### Constitution `Constitution` is found in the genesis state. It is a string field intended to be used to descibe the purpose of a particular blockchain, and its expected norms. A few examples of how the constitution field can be used: @@ -346,7 +283,7 @@ unique id and contains a series of timestamps: `submit_time`, `deposit_end_time` `voting_start_time`, `voting_end_time` which track the lifecycle of a proposal ```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/x/gov/proto/cosmos/gov/v1/gov.proto#L78-L134 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/gov.proto#L51-L99 ``` A proposal will generally require more than just a set of messages to explain its @@ -371,19 +308,8 @@ the following `JSON` template: This makes it far easier for clients to support multiple networks. -<<<<<<< HEAD The metadata has a maximum length that is chosen by the app developer, and passed into the gov keeper as a config. The default maximum length in the SDK is 255 characters. -======= -Fields metadata, title and summary have a maximum length that is chosen by the app developer, and -passed into the gov keeper as a config (`x/gov/keeper/config`). - -The default maximum length are: - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/x/gov/keeper/config.go#L38-L47 -``` ->>>>>>> deec679f2 (docs: update gov docs (#22048)) #### Writing a module that uses governance @@ -397,14 +323,30 @@ matches `authority`. This will prevent any user from executing that message. ### Parameters and base types -`Params` define the rules according to which votes are run. If governance wants to change a -parameter it can do so by submitting a gov `MsgUpdateParams` governance proposal. +`Parameters` define the rules according to which votes are run. There can only +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. + +#### DepositParams + +```protobuf reference +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/gov.proto#L152-L162 +``` + +#### VotingParams + +```protobuf reference +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/gov.proto#L164-L168 +``` + +#### TallyParams ```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/x/gov/proto/cosmos/gov/v1/gov.proto#L259-L348 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/gov.proto#L170-L182 ``` -Parameters are stored in the `gov` store under the key `ParamsKey`. +Parameters are stored in a global `GlobalParams` KVStore. Additionally, we introduce some basic types: @@ -427,6 +369,7 @@ const ( type ProposalStatus byte + const ( StatusNil ProposalStatus = 0x00 StatusDepositPeriod ProposalStatus = 0x01 // Proposal is submitted. Participants can deposit on it but not vote @@ -440,7 +383,7 @@ const ( ### Deposit ```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/x/gov/proto/cosmos/gov/v1/gov.proto#L65-L76 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/gov.proto#L38-L49 ``` ### ValidatorGovInfo @@ -454,7 +397,6 @@ This type is used in a temp map when tallying } ``` -<<<<<<< HEAD ## Stores :::note @@ -550,23 +492,18 @@ And the pseudocode for the `ProposalProcessingQueue`: store(Governance, , proposal) ``` -======= ->>>>>>> deec679f2 (docs: update gov docs (#22048)) ### Legacy Proposal :::warning -Legacy proposals (`gov/v1beta1`) are deprecated. Use the new proposal flow by granting the governance module the right to execute the message. +Legacy proposals are deprecated. Use the new proposal flow by granting the governance module the right to execute the message. ::: -<<<<<<< HEAD A legacy proposal is the old implementation of governance proposal. Contrary to proposal that can contain any messages, a legacy proposal allows to submit a set of pre-defined proposals. These proposals are defined by their types and handled by handlers that are registered in the gov v1beta1 router. More information on how to submit proposals in the [client section](#client). -======= ->>>>>>> deec679f2 (docs: update gov docs (#22048)) ## Messages ### Proposal Submission @@ -574,31 +511,28 @@ More information on how to submit proposals in the [client section](#client). Proposals can be submitted by any account via a `MsgSubmitProposal` transaction. ```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/x/gov/proto/cosmos/gov/v1/tx.proto#L64-L102 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/tx.proto#L42-L69 ``` -<<<<<<< HEAD -======= -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/x/gov/proto/cosmos/gov/v1/tx.proto#L229-L256 -``` - -:::tip -A multiple choice proposal is a proposal where the voting options can be defined by the proposer. -It cannot have messages to execute. It is only a text proposal. -This means submitting a multiple choice proposal using `MsgSubmitProposal` is invalid, as vote options cannot be defined. -::: - ->>>>>>> deec679f2 (docs: update gov docs (#22048)) All `sdk.Msgs` passed into the `messages` field of a `MsgSubmitProposal` message -must be registered in the app's message router. Each of these messages must +must be registered in the app's `MsgServiceRouter`. Each of these messages must have one signer, namely the gov module account. And finally, the metadata length must not be larger than the `maxMetadataLen` config passed into the gov keeper. The `initialDeposit` must be strictly positive and conform to the accepted denom of the `MinDeposit` param. +**State modifications:** + +* Generate new `proposalID` +* Create new `Proposal` +* Initialise `Proposal`'s attributes +* Decrease balance of sender by `InitialDeposit` +* If `MinDeposit` is reached: + * Push `proposalID` in `ProposalProcessingQueue` +* Transfer `InitialDeposit` from the `Proposer` to the governance `ModuleAccount` + ### Deposit -Once a proposal is submitted, if `Proposal.TotalDeposit < GovParams.MinDeposit`, Atom holders can send +Once a proposal is submitted, if `Proposal.TotalDeposit < ActiveParam.MinDeposit`, Atom holders can send `MsgDeposit` transactions to increase the proposal's deposit. A deposit is accepted iff: @@ -608,19 +542,36 @@ A deposit is accepted iff: * The deposited coins are conform to the accepted denom from the `MinDeposit` param ```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/x/gov/proto/cosmos/gov/v1/tx.proto#L167-L180 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/tx.proto#L134-L147 ``` +**State modifications:** + +* Decrease balance of sender by `deposit` +* Add `deposit` of sender in `proposal.Deposits` +* Increase `proposal.TotalDeposit` by sender's `deposit` +* If `MinDeposit` is reached: + * Push `proposalID` in `ProposalProcessingQueueEnd` +* Transfer `Deposit` from the `proposer` to the governance `ModuleAccount` + ### Vote -Once `GovParams.MinDeposit` is reached, voting period starts. From there, +Once `ActiveParam.MinDeposit` is reached, voting period starts. From there, bonded Atom holders are able to send `MsgVote` transactions to cast their vote on the proposal. ```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/x/gov/proto/cosmos/gov/v1/tx.proto#L125-L141 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/tx.proto#L92-L108 ``` +**State modifications:** + +* Record `Vote` of sender + +:::note +Gas cost for this message has to take into account the future tallying of the vote in EndBlocker. +::: + ## Events The governance module emits the following events: @@ -708,62 +659,6 @@ The governance module contains the following parameters: modules. If only a subset of parameters are desired to be changed, only they need to be included and not the entire parameter object structure. -<<<<<<< HEAD -======= -### Message Based Parameters - -In addition to the parameters above, the governance module can also be configured to have different parameters for a given proposal message. - -| Key | Type | Example | -| ------------- | ---------------- | -------------------------- | -| voting_period | string (time ns) | "172800000000000" (17280s) | -| yes_quorum | string (dec) | "0.4" | -| quorum | string (dec) | "0.334000000000000000" | -| threshold | string (dec) | "0.500000000000000000" | -| veto | string (dec) | "0.334000000000000000" | - -If configured, these params will take precedence over the global params for a specific proposal. - -:::warning -Currently, messaged based parameters limit the number of messages that can be included in a proposal. -Only messages that have the same message parameters can be included in the same proposal. -::: - -## Metadata - -The gov module has two locations for metadata where users can provide further context about the on-chain actions they are taking. By default all metadata fields have a 255 character length field where metadata can be stored in json format, either on-chain or off-chain depending on the amount of data required. Here we provide a recommendation for the json structure and where the data should be stored. There are two important factors in making these recommendations. First, that the gov and group modules are consistent with one another, note the number of proposals made by all groups may be quite large. Second, that client applications such as block explorers and governance interfaces have confidence in the consistency of metadata structure across chains. - -### Proposal - -Location: off-chain as json object stored on IPFS (mirrors [group proposal](../group/README.md#metadata)) - -```json -{ - "title": "", - "authors": [""], - "summary": "", - "details": "", - "proposal_forum_url": "", - "vote_option_context": "", -} -``` - -:::note -The `authors` field is an array of strings, this is to allow for multiple authors to be listed in the metadata. -In v0.46, the `authors` field is a comma-separated string. Frontends are encouraged to support both formats for backwards compatibility. -::: - -### Vote - -Location: on-chain as json within 255 character limit (mirrors [group vote](../group/README.md#metadata)) - -```json -{ - "justification": "", -} -``` - ->>>>>>> deec679f2 (docs: update gov docs (#22048)) ## Client ### CLI @@ -1176,7 +1071,6 @@ By default the metadata, summary and title are both limited by 255 characters, t When metadata is not specified, the title is limited to 255 characters and the summary 40x the title length. ::: -<<<<<<< HEAD ##### submit-legacy-proposal The `submit-legacy-proposal` command allows users to submit a governance legacy proposal along with an initial deposit. @@ -1213,9 +1107,6 @@ simd tx gov submit-legacy-proposal param-change proposal.json --from cosmos1.. ``` #### cancel-proposal -======= -##### cancel-proposal ->>>>>>> deec679f2 (docs: update gov docs (#22048)) Once proposal is canceled, from the deposits of proposal `deposits * proposal_cancel_ratio` will be burned or sent to `ProposalCancelDest` address , if `ProposalCancelDest` is empty then deposits will be burned. The `remaining deposits` will be sent to depositers. @@ -1265,8 +1156,10 @@ A user can query the `gov` module using gRPC endpoints. The `Proposal` endpoint allows users to query a given proposal. +Using legacy v1beta1: + ```bash -cosmos.gov.v1.Query/Proposal +cosmos.gov.v1beta1.Query/Proposal ``` Example: @@ -1275,139 +1168,312 @@ Example: grpcurl -plaintext \ -d '{"proposal_id":"1"}' \ localhost:9090 \ - cosmos.gov.v1.Query/Proposal + cosmos.gov.v1beta1.Query/Proposal ``` -#### Proposals +Example Output: -The `Proposals` endpoint allows users to query all proposals with optional filters. +```bash +{ + "proposal": { + "proposalId": "1", + "content": {"@type":"/cosmos.gov.v1beta1.TextProposal","description":"testing, testing, 1, 2, 3","title":"Test Proposal"}, + "status": "PROPOSAL_STATUS_VOTING_PERIOD", + "finalTallyResult": { + "yes": "0", + "abstain": "0", + "no": "0", + "noWithVeto": "0" + }, + "submitTime": "2021-09-16T19:40:08.712440474Z", + "depositEndTime": "2021-09-18T19:40:08.712440474Z", + "totalDeposit": [ + { + "denom": "stake", + "amount": "10000000" + } + ], + "votingStartTime": "2021-09-16T19:40:08.712440474Z", + "votingEndTime": "2021-09-18T19:40:08.712440474Z", + "title": "Test Proposal", + "summary": "testing, testing, 1, 2, 3" + } +} +``` + +Using v1: ```bash -cosmos.gov.v1.Query/Proposals +cosmos.gov.v1.Query/Proposal ``` Example: ```bash grpcurl -plaintext \ + -d '{"proposal_id":"1"}' \ localhost:9090 \ - cosmos.gov.v1.Query/Proposals + cosmos.gov.v1.Query/Proposal ``` -#### Vote +Example Output: -The `Vote` endpoint allows users to query a vote for a given proposal. +```bash +{ + "proposal": { + "id": "1", + "messages": [ + {"@type":"/cosmos.bank.v1beta1.MsgSend","amount":[{"denom":"stake","amount":"10"}],"fromAddress":"cosmos1..","toAddress":"cosmos1.."} + ], + "status": "PROPOSAL_STATUS_VOTING_PERIOD", + "finalTallyResult": { + "yesCount": "0", + "abstainCount": "0", + "noCount": "0", + "noWithVetoCount": "0" + }, + "submitTime": "2022-03-28T11:50:20.819676256Z", + "depositEndTime": "2022-03-30T11:50:20.819676256Z", + "totalDeposit": [ + { + "denom": "stake", + "amount": "10000000" + } + ], + "votingStartTime": "2022-03-28T14:25:26.644857113Z", + "votingEndTime": "2022-03-30T14:25:26.644857113Z", + "metadata": "AQ==", + "title": "Test Proposal", + "summary": "testing, testing, 1, 2, 3" + } +} +``` + +#### Proposals + +The `Proposals` endpoint allows users to query all proposals with optional filters. + +Using legacy v1beta1: ```bash -cosmos.gov.v1.Query/Vote +cosmos.gov.v1beta1.Query/Proposals ``` Example: ```bash grpcurl -plaintext \ - -d '{"proposal_id":"1","voter":"cosmos1.."}' \ localhost:9090 \ - cosmos.gov.v1.Query/Vote + cosmos.gov.v1beta1.Query/Proposals ``` -#### Votes +Example Output: -The `Votes` endpoint allows users to query all votes for a given proposal. +```bash +{ + "proposals": [ + { + "proposalId": "1", + "status": "PROPOSAL_STATUS_VOTING_PERIOD", + "finalTallyResult": { + "yes": "0", + "abstain": "0", + "no": "0", + "noWithVeto": "0" + }, + "submitTime": "2022-03-28T11:50:20.819676256Z", + "depositEndTime": "2022-03-30T11:50:20.819676256Z", + "totalDeposit": [ + { + "denom": "stake", + "amount": "10000000010" + } + ], + "votingStartTime": "2022-03-28T14:25:26.644857113Z", + "votingEndTime": "2022-03-30T14:25:26.644857113Z" + }, + { + "proposalId": "2", + "status": "PROPOSAL_STATUS_DEPOSIT_PERIOD", + "finalTallyResult": { + "yes": "0", + "abstain": "0", + "no": "0", + "noWithVeto": "0" + }, + "submitTime": "2022-03-28T14:02:41.165025015Z", + "depositEndTime": "2022-03-30T14:02:41.165025015Z", + "totalDeposit": [ + { + "denom": "stake", + "amount": "10" + } + ], + "votingStartTime": "0001-01-01T00:00:00Z", + "votingEndTime": "0001-01-01T00:00:00Z" + } + ], + "pagination": { + "total": "2" + } +} + +``` + +Using v1: ```bash -cosmos.gov.v1.Query/Votes +cosmos.gov.v1.Query/Proposals ``` Example: ```bash grpcurl -plaintext \ - -d '{"proposal_id":"1"}' \ localhost:9090 \ - cosmos.gov.v1.Query/Votes + cosmos.gov.v1.Query/Proposals ``` -#### Params +Example Output: -The `Params` endpoint allows users to query all parameters for the `gov` module. +```bash +{ + "proposals": [ + { + "id": "1", + "messages": [ + {"@type":"/cosmos.bank.v1beta1.MsgSend","amount":[{"denom":"stake","amount":"10"}],"fromAddress":"cosmos1..","toAddress":"cosmos1.."} + ], + "status": "PROPOSAL_STATUS_VOTING_PERIOD", + "finalTallyResult": { + "yesCount": "0", + "abstainCount": "0", + "noCount": "0", + "noWithVetoCount": "0" + }, + "submitTime": "2022-03-28T11:50:20.819676256Z", + "depositEndTime": "2022-03-30T11:50:20.819676256Z", + "totalDeposit": [ + { + "denom": "stake", + "amount": "10000000010" + } + ], + "votingStartTime": "2022-03-28T14:25:26.644857113Z", + "votingEndTime": "2022-03-30T14:25:26.644857113Z", + "metadata": "AQ==", + "title": "Proposal Title", + "summary": "Proposal Summary" + }, + { + "id": "2", + "messages": [ + {"@type":"/cosmos.bank.v1beta1.MsgSend","amount":[{"denom":"stake","amount":"10"}],"fromAddress":"cosmos1..","toAddress":"cosmos1.."} + ], + "status": "PROPOSAL_STATUS_DEPOSIT_PERIOD", + "finalTallyResult": { + "yesCount": "0", + "abstainCount": "0", + "noCount": "0", + "noWithVetoCount": "0" + }, + "submitTime": "2022-03-28T14:02:41.165025015Z", + "depositEndTime": "2022-03-30T14:02:41.165025015Z", + "totalDeposit": [ + { + "denom": "stake", + "amount": "10" + } + ], + "metadata": "AQ==", + "title": "Proposal Title", + "summary": "Proposal Summary" + } + ], + "pagination": { + "total": "2" + } +} +``` -<<<<<<< HEAD - +#### Vote + +The `Vote` endpoint allows users to query a vote for a given proposal. Using legacy v1beta1: ```bash -cosmos.gov.v1beta1.Query/Params +cosmos.gov.v1beta1.Query/Vote ``` Example: ```bash grpcurl -plaintext \ - -d '{"params_type":"voting"}' \ + -d '{"proposal_id":"1","voter":"cosmos1.."}' \ localhost:9090 \ - cosmos.gov.v1beta1.Query/Params + cosmos.gov.v1beta1.Query/Vote ``` Example Output: ```bash { - "votingParams": { - "votingPeriod": "172800s" - }, - "depositParams": { - "maxDepositPeriod": "0s" - }, - "tallyParams": { - "quorum": "MA==", - "threshold": "MA==", - "vetoThreshold": "MA==" + "vote": { + "proposalId": "1", + "voter": "cosmos1..", + "option": "VOTE_OPTION_YES", + "options": [ + { + "option": "VOTE_OPTION_YES", + "weight": "1000000000000000000" + } + ] } } ``` Using v1: -======= ->>>>>>> deec679f2 (docs: update gov docs (#22048)) ```bash -cosmos.gov.v1.Query/Params +cosmos.gov.v1.Query/Vote ``` Example: ```bash grpcurl -plaintext \ - -d '{"params_type":"voting"}' \ + -d '{"proposal_id":"1","voter":"cosmos1.."}' \ localhost:9090 \ - cosmos.gov.v1.Query/Params + cosmos.gov.v1.Query/Vote ``` -#### Deposit - -The `Deposit` endpoint allows users to query a deposit for a given proposal from a given depositor. +Example Output: ```bash -cosmos.gov.v1.Query/Deposit +{ + "vote": { + "proposalId": "1", + "voter": "cosmos1..", + "option": "VOTE_OPTION_YES", + "options": [ + { + "option": "VOTE_OPTION_YES", + "weight": "1.000000000000000000" + } + ] + } +} ``` -Example: - -```bash -grpcurl -plaintext \ - '{"proposal_id":"1","depositor":"cosmos1.."}' \ - localhost:9090 \ - cosmos.gov.v1.Query/Deposit -``` +#### Votes -#### deposits +The `Votes` endpoint allows users to query all votes for a given proposal. -The `Deposits` endpoint allows users to query all deposits for a given proposal. +Using legacy v1beta1: ```bash -cosmos.gov.v1.Query/Deposits +cosmos.gov.v1beta1.Query/Votes ``` Example: @@ -1416,18 +1482,35 @@ Example: grpcurl -plaintext \ -d '{"proposal_id":"1"}' \ localhost:9090 \ - cosmos.gov.v1.Query/Deposits + cosmos.gov.v1beta1.Query/Votes ``` -#### TallyResult +Example Output: -The `TallyResult` endpoint allows users to query the tally of a given proposal. +```bash +{ + "votes": [ + { + "proposalId": "1", + "voter": "cosmos1..", + "options": [ + { + "option": "VOTE_OPTION_YES", + "weight": "1000000000000000000" + } + ] + } + ], + "pagination": { + "total": "1" + } +} +``` -<<<<<<< HEAD -Using legacy v1beta1: +Using v1: ```bash -cosmos.gov.v1beta1.Query/TallyResult +cosmos.gov.v1.Query/Votes ``` Example: @@ -1436,37 +1519,299 @@ Example: grpcurl -plaintext \ -d '{"proposal_id":"1"}' \ localhost:9090 \ - cosmos.gov.v1beta1.Query/TallyResult + cosmos.gov.v1.Query/Votes ``` Example Output: ```bash { - "tally": { - "yes": "1000000", - "abstain": "0", - "no": "0", - "noWithVeto": "0" + "votes": [ + { + "proposalId": "1", + "voter": "cosmos1..", + "options": [ + { + "option": "VOTE_OPTION_YES", + "weight": "1.000000000000000000" + } + ] + } + ], + "pagination": { + "total": "1" } } ``` -Using v1: +#### Params + +The `Params` endpoint allows users to query all parameters for the `gov` module. + + + +Using legacy v1beta1: -======= ->>>>>>> deec679f2 (docs: update gov docs (#22048)) ```bash -cosmos.gov.v1.Query/TallyResult +cosmos.gov.v1beta1.Query/Params ``` Example: ```bash grpcurl -plaintext \ - -d '{"proposal_id":"1"}' \ + -d '{"params_type":"voting"}' \ localhost:9090 \ - cosmos.gov.v1.Query/TallyResult + cosmos.gov.v1beta1.Query/Params +``` + +Example Output: + +```bash +{ + "votingParams": { + "votingPeriod": "172800s" + }, + "depositParams": { + "maxDepositPeriod": "0s" + }, + "tallyParams": { + "quorum": "MA==", + "threshold": "MA==", + "vetoThreshold": "MA==" + } +} +``` + +Using v1: + +```bash +cosmos.gov.v1.Query/Params +``` + +Example: + +```bash +grpcurl -plaintext \ + -d '{"params_type":"voting"}' \ + localhost:9090 \ + cosmos.gov.v1.Query/Params +``` + +Example Output: + +```bash +{ + "votingParams": { + "votingPeriod": "172800s" + } +} +``` + +#### Deposit + +The `Deposit` endpoint allows users to query a deposit for a given proposal from a given depositor. + +Using legacy v1beta1: + +```bash +cosmos.gov.v1beta1.Query/Deposit +``` + +Example: + +```bash +grpcurl -plaintext \ + '{"proposal_id":"1","depositor":"cosmos1.."}' \ + localhost:9090 \ + cosmos.gov.v1beta1.Query/Deposit +``` + +Example Output: + +```bash +{ + "deposit": { + "proposalId": "1", + "depositor": "cosmos1..", + "amount": [ + { + "denom": "stake", + "amount": "10000000" + } + ] + } +} +``` + +Using v1: + +```bash +cosmos.gov.v1.Query/Deposit +``` + +Example: + +```bash +grpcurl -plaintext \ + '{"proposal_id":"1","depositor":"cosmos1.."}' \ + localhost:9090 \ + cosmos.gov.v1.Query/Deposit +``` + +Example Output: + +```bash +{ + "deposit": { + "proposalId": "1", + "depositor": "cosmos1..", + "amount": [ + { + "denom": "stake", + "amount": "10000000" + } + ] + } +} +``` + +#### deposits + +The `Deposits` endpoint allows users to query all deposits for a given proposal. + +Using legacy v1beta1: + +```bash +cosmos.gov.v1beta1.Query/Deposits +``` + +Example: + +```bash +grpcurl -plaintext \ + -d '{"proposal_id":"1"}' \ + localhost:9090 \ + cosmos.gov.v1beta1.Query/Deposits +``` + +Example Output: + +```bash +{ + "deposits": [ + { + "proposalId": "1", + "depositor": "cosmos1..", + "amount": [ + { + "denom": "stake", + "amount": "10000000" + } + ] + } + ], + "pagination": { + "total": "1" + } +} +``` + +Using v1: + +```bash +cosmos.gov.v1.Query/Deposits +``` + +Example: + +```bash +grpcurl -plaintext \ + -d '{"proposal_id":"1"}' \ + localhost:9090 \ + cosmos.gov.v1.Query/Deposits +``` + +Example Output: + +```bash +{ + "deposits": [ + { + "proposalId": "1", + "depositor": "cosmos1..", + "amount": [ + { + "denom": "stake", + "amount": "10000000" + } + ] + } + ], + "pagination": { + "total": "1" + } +} +``` + +#### TallyResult + +The `TallyResult` endpoint allows users to query the tally of a given proposal. + +Using legacy v1beta1: + +```bash +cosmos.gov.v1beta1.Query/TallyResult +``` + +Example: + +```bash +grpcurl -plaintext \ + -d '{"proposal_id":"1"}' \ + localhost:9090 \ + cosmos.gov.v1beta1.Query/TallyResult +``` + +Example Output: + +```bash +{ + "tally": { + "yes": "1000000", + "abstain": "0", + "no": "0", + "noWithVeto": "0" + } +} +``` + +Using v1: + +```bash +cosmos.gov.v1.Query/TallyResult +``` + +Example: + +```bash +grpcurl -plaintext \ + -d '{"proposal_id":"1"}' \ + localhost:9090 \ + cosmos.gov.v1.Query/TallyResult +``` + +Example Output: + +```bash +{ + "tally": { + "yes": "1000000", + "abstain": "0", + "no": "0", + "noWithVeto": "0" + } +} ``` ### REST @@ -1477,6 +1822,48 @@ A user can query the `gov` module using REST endpoints. The `proposals` endpoint allows users to query a given proposal. +Using legacy v1beta1: + +```bash +/cosmos/gov/v1beta1/proposals/{proposal_id} +``` + +Example: + +```bash +curl localhost:1317/cosmos/gov/v1beta1/proposals/1 +``` + +Example Output: + +```bash +{ + "proposal": { + "proposal_id": "1", + "content": null, + "status": "PROPOSAL_STATUS_VOTING_PERIOD", + "final_tally_result": { + "yes": "0", + "abstain": "0", + "no": "0", + "no_with_veto": "0" + }, + "submit_time": "2022-03-28T11:50:20.819676256Z", + "deposit_end_time": "2022-03-30T11:50:20.819676256Z", + "total_deposit": [ + { + "denom": "stake", + "amount": "10000000010" + } + ], + "voting_start_time": "2022-03-28T14:25:26.644857113Z", + "voting_end_time": "2022-03-30T14:25:26.644857113Z" + } +} +``` + +Using v1: + ```bash /cosmos/gov/v1/proposals/{proposal_id} ``` @@ -1487,10 +1874,121 @@ Example: curl localhost:1317/cosmos/gov/v1/proposals/1 ``` +Example Output: + +```bash +{ + "proposal": { + "id": "1", + "messages": [ + { + "@type": "/cosmos.bank.v1beta1.MsgSend", + "from_address": "cosmos1..", + "to_address": "cosmos1..", + "amount": [ + { + "denom": "stake", + "amount": "10" + } + ] + } + ], + "status": "PROPOSAL_STATUS_VOTING_PERIOD", + "final_tally_result": { + "yes_count": "0", + "abstain_count": "0", + "no_count": "0", + "no_with_veto_count": "0" + }, + "submit_time": "2022-03-28T11:50:20.819676256Z", + "deposit_end_time": "2022-03-30T11:50:20.819676256Z", + "total_deposit": [ + { + "denom": "stake", + "amount": "10000000" + } + ], + "voting_start_time": "2022-03-28T14:25:26.644857113Z", + "voting_end_time": "2022-03-30T14:25:26.644857113Z", + "metadata": "AQ==", + "title": "Proposal Title", + "summary": "Proposal Summary" + } +} +``` + #### proposals The `proposals` endpoint also allows users to query all proposals with optional filters. +Using legacy v1beta1: + +```bash +/cosmos/gov/v1beta1/proposals +``` + +Example: + +```bash +curl localhost:1317/cosmos/gov/v1beta1/proposals +``` + +Example Output: + +```bash +{ + "proposals": [ + { + "proposal_id": "1", + "content": null, + "status": "PROPOSAL_STATUS_VOTING_PERIOD", + "final_tally_result": { + "yes": "0", + "abstain": "0", + "no": "0", + "no_with_veto": "0" + }, + "submit_time": "2022-03-28T11:50:20.819676256Z", + "deposit_end_time": "2022-03-30T11:50:20.819676256Z", + "total_deposit": [ + { + "denom": "stake", + "amount": "10000000" + } + ], + "voting_start_time": "2022-03-28T14:25:26.644857113Z", + "voting_end_time": "2022-03-30T14:25:26.644857113Z" + }, + { + "proposal_id": "2", + "content": null, + "status": "PROPOSAL_STATUS_DEPOSIT_PERIOD", + "final_tally_result": { + "yes": "0", + "abstain": "0", + "no": "0", + "no_with_veto": "0" + }, + "submit_time": "2022-03-28T14:02:41.165025015Z", + "deposit_end_time": "2022-03-30T14:02:41.165025015Z", + "total_deposit": [ + { + "denom": "stake", + "amount": "10" + } + ], + "voting_start_time": "0001-01-01T00:00:00Z", + "voting_end_time": "0001-01-01T00:00:00Z" + } + ], + "pagination": { + "next_key": null, + "total": "2" + } +} +``` + +Using v1: ```bash /cosmos/gov/v1/proposals @@ -1502,10 +2000,126 @@ Example: curl localhost:1317/cosmos/gov/v1/proposals ``` +Example Output: + +```bash +{ + "proposals": [ + { + "id": "1", + "messages": [ + { + "@type": "/cosmos.bank.v1beta1.MsgSend", + "from_address": "cosmos1..", + "to_address": "cosmos1..", + "amount": [ + { + "denom": "stake", + "amount": "10" + } + ] + } + ], + "status": "PROPOSAL_STATUS_VOTING_PERIOD", + "final_tally_result": { + "yes_count": "0", + "abstain_count": "0", + "no_count": "0", + "no_with_veto_count": "0" + }, + "submit_time": "2022-03-28T11:50:20.819676256Z", + "deposit_end_time": "2022-03-30T11:50:20.819676256Z", + "total_deposit": [ + { + "denom": "stake", + "amount": "10000000010" + } + ], + "voting_start_time": "2022-03-28T14:25:26.644857113Z", + "voting_end_time": "2022-03-30T14:25:26.644857113Z", + "metadata": "AQ==", + "title": "Proposal Title", + "summary": "Proposal Summary" + }, + { + "id": "2", + "messages": [ + { + "@type": "/cosmos.bank.v1beta1.MsgSend", + "from_address": "cosmos1..", + "to_address": "cosmos1..", + "amount": [ + { + "denom": "stake", + "amount": "10" + } + ] + } + ], + "status": "PROPOSAL_STATUS_DEPOSIT_PERIOD", + "final_tally_result": { + "yes_count": "0", + "abstain_count": "0", + "no_count": "0", + "no_with_veto_count": "0" + }, + "submit_time": "2022-03-28T14:02:41.165025015Z", + "deposit_end_time": "2022-03-30T14:02:41.165025015Z", + "total_deposit": [ + { + "denom": "stake", + "amount": "10" + } + ], + "voting_start_time": null, + "voting_end_time": null, + "metadata": "AQ==", + "title": "Proposal Title", + "summary": "Proposal Summary" + } + ], + "pagination": { + "next_key": null, + "total": "2" + } +} +``` + #### voter vote The `votes` endpoint allows users to query a vote for a given proposal. +Using legacy v1beta1: + +```bash +/cosmos/gov/v1beta1/proposals/{proposal_id}/votes/{voter} +``` + +Example: + +```bash +curl localhost:1317/cosmos/gov/v1beta1/proposals/1/votes/cosmos1.. +``` + +Example Output: + +```bash +{ + "vote": { + "proposal_id": "1", + "voter": "cosmos1..", + "option": "VOTE_OPTION_YES", + "options": [ + { + "option": "VOTE_OPTION_YES", + "weight": "1.000000000000000000" + } + ] + } +} +``` + +Using v1: ```bash /cosmos/gov/v1/proposals/{proposal_id}/votes/{voter} @@ -1517,10 +2131,66 @@ Example: curl localhost:1317/cosmos/gov/v1/proposals/1/votes/cosmos1.. ``` +Example Output: + +```bash +{ + "vote": { + "proposal_id": "1", + "voter": "cosmos1..", + "options": [ + { + "option": "VOTE_OPTION_YES", + "weight": "1.000000000000000000" + } + ], + "metadata": "" + } +} +``` + #### votes The `votes` endpoint allows users to query all votes for a given proposal. +Using legacy v1beta1: + +```bash +/cosmos/gov/v1beta1/proposals/{proposal_id}/votes +``` + +Example: + +```bash +curl localhost:1317/cosmos/gov/v1beta1/proposals/1/votes +``` + +Example Output: + +```bash +{ + "votes": [ + { + "proposal_id": "1", + "voter": "cosmos1..", + "option": "VOTE_OPTION_YES", + "options": [ + { + "option": "VOTE_OPTION_YES", + "weight": "1.000000000000000000" + } + ] + } + ], + "pagination": { + "next_key": null, + "total": "1" + } +} +``` + +Using v1: + ```bash /cosmos/gov/v1/proposals/{proposal_id}/votes ``` @@ -1531,11 +2201,34 @@ Example: curl localhost:1317/cosmos/gov/v1/proposals/1/votes ``` +Example Output: + +```bash +{ + "votes": [ + { + "proposal_id": "1", + "voter": "cosmos1..", + "options": [ + { + "option": "VOTE_OPTION_YES", + "weight": "1.000000000000000000" + } + ], + "metadata": "" + } + ], + "pagination": { + "next_key": null, + "total": "1" + } +} +``` + #### params The `params` endpoint allows users to query all parameters for the `gov` module. -<<<<<<< HEAD Using legacy v1beta1: @@ -1572,8 +2265,6 @@ Example Output: Using v1: -======= ->>>>>>> deec679f2 (docs: update gov docs (#22048)) ```bash /cosmos/gov/v1/params/{params_type} ``` @@ -1584,7 +2275,6 @@ Example: curl localhost:1317/cosmos/gov/v1/params/voting ``` -<<<<<<< HEAD Example Output: ```bash @@ -1604,14 +2294,42 @@ Example Output: } } ``` -======= -Note: `params_type` are deprecated in v1 since all params are stored in Params. ->>>>>>> deec679f2 (docs: update gov docs (#22048)) #### deposits The `deposits` endpoint allows users to query a deposit for a given proposal from a given depositor. +Using legacy v1beta1: + +```bash +/cosmos/gov/v1beta1/proposals/{proposal_id}/deposits/{depositor} +``` + +Example: + +```bash +curl localhost:1317/cosmos/gov/v1beta1/proposals/1/deposits/cosmos1.. +``` + +Example Output: + +```bash +{ + "deposit": { + "proposal_id": "1", + "depositor": "cosmos1..", + "amount": [ + { + "denom": "stake", + "amount": "10000000" + } + ] + } +} +``` + +Using v1: + ```bash /cosmos/gov/v1/proposals/{proposal_id}/deposits/{depositor} ``` @@ -1622,10 +2340,64 @@ Example: curl localhost:1317/cosmos/gov/v1/proposals/1/deposits/cosmos1.. ``` +Example Output: + +```bash +{ + "deposit": { + "proposal_id": "1", + "depositor": "cosmos1..", + "amount": [ + { + "denom": "stake", + "amount": "10000000" + } + ] + } +} +``` + #### proposal deposits The `deposits` endpoint allows users to query all deposits for a given proposal. +Using legacy v1beta1: + +```bash +/cosmos/gov/v1beta1/proposals/{proposal_id}/deposits +``` + +Example: + +```bash +curl localhost:1317/cosmos/gov/v1beta1/proposals/1/deposits +``` + +Example Output: + +```bash +{ + "deposits": [ + { + "proposal_id": "1", + "depositor": "cosmos1..", + "amount": [ + { + "denom": "stake", + "amount": "10000000" + } + ] + } + ], + "pagination": { + "next_key": null, + "total": "1" + } +} +``` + +Using v1: + ```bash /cosmos/gov/v1/proposals/{proposal_id}/deposits ``` @@ -1636,10 +2408,60 @@ Example: curl localhost:1317/cosmos/gov/v1/proposals/1/deposits ``` +Example Output: + +```bash +{ + "deposits": [ + { + "proposal_id": "1", + "depositor": "cosmos1..", + "amount": [ + { + "denom": "stake", + "amount": "10000000" + } + ] + } + ], + "pagination": { + "next_key": null, + "total": "1" + } +} +``` + #### tally The `tally` endpoint allows users to query the tally of a given proposal. +Using legacy v1beta1: + +```bash +/cosmos/gov/v1beta1/proposals/{proposal_id}/tally +``` + +Example: + +```bash +curl localhost:1317/cosmos/gov/v1beta1/proposals/1/tally +``` + +Example Output: + +```bash +{ + "tally": { + "yes": "1000000", + "abstain": "0", + "no": "0", + "no_with_veto": "0" + } +} +``` + +Using v1: + ```bash /cosmos/gov/v1/proposals/{proposal_id}/tally ``` @@ -1649,7 +2471,6 @@ Example: ```bash curl localhost:1317/cosmos/gov/v1/proposals/1/tally ``` -<<<<<<< HEAD Example Output: @@ -1724,5 +2545,3 @@ governance module. Future improvements may include: * **Better process for proposal review:** There would be two parts to `proposal.Deposit`, one for anti-spam (same as in MVP) and an other one to reward third party auditors. -======= ->>>>>>> deec679f2 (docs: update gov docs (#22048))