From ba09911eb69a565948c9177e887f3a3351318ec0 Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Wed, 6 Jul 2022 18:42:48 +0200 Subject: [PATCH] docs: clarify differences and usage of `submit-proposal` and `submit-legacy-proposal` for gov (#12410) --- CHANGELOG.md | 2 +- x/gov/spec/01_concepts.md | 4 ++-- x/gov/spec/02_state.md | 25 +++++++++++++++++-------- x/gov/spec/07_client.md | 6 +++--- 4 files changed, 23 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 295da4b27d63..b4374fcc03fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -229,7 +229,7 @@ empty coins slice before it is used to create `banktype.MsgSend`. * [\#9594](https://github.com/cosmos/cosmos-sdk/pull/9594) Remove legacy REST API. Please see the [REST Endpoints Migration guide](https://docs.cosmos.network/master/migrations/rest.html) to migrate to the new REST endpoints. * [\#9995](https://github.com/cosmos/cosmos-sdk/pull/9995) Increased gas cost for creating proposals. * [\#11029](https://github.com/cosmos/cosmos-sdk/pull/11029) The deprecated Vote Option field is removed in gov v1beta2 and nil in v1beta1. Use Options instead. -* [\#11013](https://github.com/cosmos/cosmos-sdk/pull/) The `tx gov submit-proposal` command has changed syntax to support the new Msg-based gov proposals. To access the old CLI command, please use `tx gov submit-legacy-proposal`. +* [\#11013](https://github.com/cosmos/cosmos-sdk/pull/11013) The `tx gov submit-proposal` command has changed syntax to support the new Msg-based gov proposals. To access the old CLI command, please use `tx gov submit-legacy-proposal`. * [\#11170](https://github.com/cosmos/cosmos-sdk/issues/11170) Fixes issue related to grpc-gateway of supply by ibc-denom. ### CLI Breaking Changes diff --git a/x/gov/spec/01_concepts.md b/x/gov/spec/01_concepts.md index e1a36f90094e..61843453d679 100644 --- a/x/gov/spec/01_concepts.md +++ b/x/gov/spec/01_concepts.md @@ -177,7 +177,7 @@ Later, we may add permissioned keys that could only sign txs from certain module If proposals are of type `SoftwareUpgradeProposal`, then nodes need to upgrade their software to the new version that was voted. This process is divided into -two steps. +two steps: ### Signal @@ -200,4 +200,4 @@ Once a block contains more than 2/3rd _precommits_ where a common nodes, non-validating full nodes and light-nodes) are expected to switch to the new version of the software. -_Note: Not clear how the flip is handled programmatically._ +Validators and full nodes can use an automation tool, such as [Cosmovisor](https://github.com/cosmos/cosmos-sdk/blob/main/cosmovisor/README.md), for automatically switching version of the chain. diff --git a/x/gov/spec/02_state.md b/x/gov/spec/02_state.md index 78af0fe5615e..66514ec2c54c 100644 --- a/x/gov/spec/02_state.md +++ b/x/gov/spec/02_state.md @@ -16,11 +16,11 @@ unique id and contains a series of timestamps: `submit_time`, `deposit_end_time` A proposal will generally require more than just a set of messages to explain its purpose but need some greater justification and allow a means for interested participants -to discuss and debate the proposal. In most cases, it is encouraged to have an off-chain -system that supports the on-chain governance process. To accommodate for this, a -proposal contains a special `metadata` field, an array of bytes, which can be used to -add context to the proposal. The `metadata` field allows custom use for networks, however, -it is expected that the field contains a URL or some form of CID using a system such as +to discuss and debate the proposal. +In most cases, **it is encouraged to have an off-chain system that supports the on-chain governance process**. +To accommodate for this, a proposal contains a special **`metadata`** field, an array of bytes, +which can be used to add context to the proposal. The `metadata` field allows custom use for networks, +however, it is expected that the field contains a URL or some form of CID using a system such as [IPFS](https://docs.ipfs.io/concepts/content-addressing/). To support the case of interoperability across networks, the SDK recommends that the `metadata` represents the following `JSON` template: @@ -37,7 +37,7 @@ the following `JSON` template: This makes it far easier for clients to support multiple networks. The metadata has a maximum length that is chosen by the app developer, and -passed into the gov keeper as a config. +passed into the gov keeper as a config. The default maximum length in the SDK is 255 characters. ### Writing a module that uses governance @@ -119,8 +119,7 @@ This type is used in a temp map when tallying ## Stores -_Stores are KVStores in the multi-store. The key to find the store is the first -parameter in the list_` +_Note: Stores are KVStores in the multi-store. The key to find the store is the first parameter in the list_ We will use one KVStore `Governance` to store two mappings: @@ -206,3 +205,13 @@ And the pseudocode for the `ProposalProcessingQueue`: store(Governance, , proposal) ``` + +## Legacy Proposal + +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 proposal are defined by their types. + +While proposals should use the new implementation of the governance proposal, we need still to use legacy proposal in order to submit a `software-upgrade` and a `cancel-software-upgrade` proposal. + +More information on how to submit proposals in the [client section](07_client.md). diff --git a/x/gov/spec/07_client.md b/x/gov/spec/07_client.md index 0532ad907c09..00aa57e57859 100644 --- a/x/gov/spec/07_client.md +++ b/x/gov/spec/07_client.md @@ -361,14 +361,14 @@ Example: simd tx gov submit-proposal /path/to/proposal.json --from cosmos1.. ``` -where proposal.json contains: +where `proposal.json` contains: -```bash +```json { "messages": [ { "@type": "/cosmos.bank.v1beta1.MsgSend", - "from_address": "cosmos1...", + "from_address": "cosmos1...", // The gov module module address "to_address": "cosmos1...", "amount":[{"denom": "stake","amount": "10"}] }