docs: add v15 specific docs, changelogs and instructions (#3009)

* docs: add changelogs section; add migration doc * docs: change homepage banner * docs: add proposals and instructions * Update docs/docs/changelogs/v15.1.0.md Co-authored-by: Marius Poke <[email protected]> * Update docs/docs/changelogs/v15.1.0.md Co-authored-by: Stana Miric <[email protected]> * Update docs/docs/changelogs/v15.1.0.md Co-authored-by: Stana Miric <[email protected]> * Update docs/docs/changelogs/v15.1.0.md Co-authored-by: Dusan Maksimovic <[email protected]> * Update docs/docs/governance/proposal-types/software-upgrade.md Co-authored-by: Dusan Maksimovic <[email protected]> * Update docs/docs/changelogs/v15.1.0.md Co-authored-by: Dusan Maksimovic <[email protected]> * Update docs/docs/changelogs/v15.1.0.md Co-authored-by: Dusan Maksimovic <[email protected]> * Update docs/docs/migration/cosmoshub-4-v15-upgrade.md Co-authored-by: Dusan Maksimovic <[email protected]> * docs: add review comment changes * docs: add review comment changes --------- Co-authored-by: Marius Poke <[email protected]> Co-authored-by: Stana Miric <[email protected]> Co-authored-by: Dusan Maksimovic <[email protected]>
cosmos · Mar 19, 2024 · 0192205 · 0192205
1 parent 08acfa8
commit 0192205
Show file tree

Hide file tree

Showing 11 changed files with 494 additions and 15 deletions.
diff --git a/docs/docs/changelogs/README.md b/docs/docs/changelogs/README.md
@@ -0,0 +1,6 @@
+---
+title: Changelogs
+order: 1
+---
+
+This folder documents and clarifies important API and other changes introduced to the Cosmos Hub blockchain as a result of a software upgrade. Most changes are a result of updating cosmos-sdk, ibc-go and cometbft versions.
diff --git a/docs/docs/changelogs/_category_.json b/docs/docs/changelogs/_category_.json
@@ -0,0 +1,5 @@
+{
+    "label": "Changelogs",
+    "position": 16,
+    "link": { "type": "doc", "id": "changelogs/README" }
+}
diff --git a/docs/docs/changelogs/v15.1.0.md b/docs/docs/changelogs/v15.1.0.md
@@ -0,0 +1,133 @@
+---
+title: v15.1.0
+order: 1
+---
+
+This document outlines API breaking changes that were introduced in `gaia v15.1.0`.
+
+This release is based on cosmos-sdk `v0.47.x` and ibc-go `v7.x`.
+
+You can find the comprehensive API docs at:
+* https://docs.cosmos.network/api
+
+Module reference manuals (with CLI instructions) can be found at:
+* https://docs.cosmos.network/v0.47/build/modules
+
+Comprehensive list of changes:
+* https://github.com/cosmos/gaia/blob/release/v15.1.x/CHANGELOG.md#api-breaking
+
+## Supported modules:
+cosmos-sdk `v0.47.10-ics-lsm`
+* x/auth
+* x/authz
+* x/bank
+* x/capability
+* x/consensus
+* x/crisis
+* x/distribution
+* x/evidence
+* x/feegrant
+* x/gov
+* x/mint
+* x/params
+* x/slashing
+* x/staking (with LSM changes)
+* x/upgrade
+
+ibc-go `v7.x`
+* transfer
+* ica (host)
+
+interchain-security/provider `v3.3.x`
+
+packetforward `v7.x`
+
+gaia
+* x/globalfee `v15.x`
+* x/metaprotocols `v15.x`
+
+
+# Important changes
+Changes are outlined compared to `gaiad <= v14.x`
+
+## Behaviour changes
+
+Starting `v15.1.0` all users must have at least `1 ATOM` staked in order to cast a vote on a governance proposal.
+
+Votes from accounts whose staked amounts are `< 1 ATOM` will be rejected.
+
+##  REST/RPC Changes
+
+### DenomOwners
+
+The `DenomOwners` query is not supported on the Cosmos Hub chain.
+* querying `<RPC_ADDR>.cosmos/bank/v1beta1/denom_owners/{denom}` always returns an empty result.
+
+
+### Querying latest block
+
+`curl <RPC>/blocks/latest` no longer works and returns `{"code":12,"message":"Not Implemented","details":[]}`
+
+The endpoint was moved to: `<RPC>/cosmos/base/tendermint/v1beta1/blocks/latest`
+
+
+# CLI Changes
+
+## Genesis commands
+
+`gaiad` no longer uses a custom genesis commands and instead relies on the commands defined in the [x/genutil module](https://docs.cosmos.network/v0.47/build/modules/genutil).
+
+These queries no longer work:
+```shell
+gaiad gentx
+gaiad collect-gentx
+gaiad validate-genesis
+gaiad add-genesis-account
+```
+
+Use the `genesis` subcommands instead:
+```shell
+gaiad genesis gentx
+gaiad genesis collect-gentx
+gaiad genesis validate-genesis
+gaiad genesis add-genesis-account
+gaiad genesis migrate
+```
+
+## Governance commands
+
+Governance commands are aligned with cosmos-sdk v0.47.x [x/gov module](https://docs.cosmos.network/v0.47/build/modules/gov).
+
+### submit-legacy-proposal
+
+Some proposal types can be submitted using the `gaiad tx gov submit-legacy-proposal` command:
+```sh
+gaiad tx gov submit-legacy-proposal
+
+Available Commands:
+  cancel-software-upgrade Cancel the current software upgrade proposal
+  change-reward-denoms    Submit a change reward denoms proposal
+  consumer-addition       Submit a consumer addition proposal
+  consumer-removal        Submit a consumer chain removal proposal
+  ibc-upgrade             Submit an IBC upgrade proposal
+  param-change            Submit a parameter change proposal
+  software-upgrade        Submit a software upgrade proposal
+  update-client           Submit an update IBC client proposal
+```
+
+Most cosmos-sdk modules no longer allow their parameters to be upgraded using a `param-change` proposal. Use the corresponding `MsgUpgradeParams` message instead and create a JSON file proposal using `draft-proposal` (listed below).
+
+List of proposals available for submission via `submit-legacy-proposal` will be further decreased in subsequent releases.
+
+More information is available in cosmos-sdk [x/gov docs](https://docs.cosmos.network/v0.47/build/modules/gov#submit-legacy-proposal).
+
+### draft-proposal
+
+`gaiad tx gov draft-proposal` command is available. You can use this command to create a draft proposal in JSON format.
+* more information is available in the cosmos-sdk [x/gov docs](https://docs.cosmos.network/v0.47/build/modules/gov#draft-proposal)
+
+### submit-proposal 
+
+`gaiad tx gov submit-proposal` command is available. Use `draft-proposal` (listed above) to create a proposal JSON and submit it as a transaction.
+
+More information is available in cosmos-sdk [x/gov docs](https://docs.cosmos.network/v0.47/build/modules/gov#submit-proposal)
diff --git a/docs/docs/governance/proposal-types/README.md b/docs/docs/governance/proposal-types/README.md
@@ -9,7 +9,7 @@ parent:
 - [**Text**](../proposal-types/text-prop.md)
 - [**Community Pool Spend**](../proposal-types/community-pool-spend.md)
 - [**Parameter Change**](../proposal-types/param-change.md)
-- **Software Upgrade**
+- [**Software Upgrade**](../proposal-types/software-upgrade.md)
 - **IBC Client Update**
 
 ## Drafting a Proposal

diff --git a/docs/docs/governance/proposal-types/_category_.json b/docs/docs/governance/proposal-types/_category_.json
@@ -1,5 +1,5 @@
 {
-    "label": "Parameter Changes",
+    "label": "Common proposals",
     "position": 1,
     "link": { "type": "doc", "id": "governance/proposal-types/README" }
 }
diff --git a/docs/docs/governance/proposal-types/software-upgrade.md b/docs/docs/governance/proposal-types/software-upgrade.md
@@ -0,0 +1,70 @@
+---
+order: 2
+parent:
+  order: 2
+---
+
+# Software Upgrade
+
+Software upgrade proposals are submitted to signal that a Cosmos Hub release with new features, bugfixes and various other improvements is available and ready for production deployment.
+
+Software upgrade proposals should be submitted by the development teams tasked with stewarding the Cosmos Hub development.
+
+## Procedure
+
+Use `draft-proposal` command to create a draft proposal and populate it with required information.
+
+```sh
+✗ gaiad tx gov draft-proposal
+Use the arrow keys to navigate: ↓ ↑ → ←
+? Select proposal type:
+    text
+    community-pool-spend
+  ▸ software-upgrade # choose this
+    cancel-software-upgrade
+    other
+
+# populate all steps (displaying all for demonstration purposes)
+Enter proposal title: Upgrade v15
+Enter proposal authors: Stewards
+Enter proposal summary: Upgrade to v15
+Enter proposal details: <v15 upgrade changelog details>
+Enter proposal proposal forum url: /
+Enter proposal vote option context: Vote YES to support running this binary on the Cosmos Hub mainnet.
+Enter proposal deposit: 100001uatom
+Enter msg authority: cosmos10d07y265gmmuvt4z0w9aw880jnsr700j6zn9kn
+```
+
+In your `draft_proposal.json` populate the `height` with your desired upgrade height and populate the `info` field with additional information (must be a valid JSON string):
+```json
+{
+  "binaries": {
+    "darwin/amd64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-darwin-amd64?checksum=sha256:7157f03fbad4f53a4c73cde4e75454f4a40a9b09619d3295232341fec99ad138",
+    "darwin/arm64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-darwin-arm64?checksum=sha256:09e2420151dd22920304dafea47af4aa5ff4ab0ddbe056bb91797e33ff6df274",
+    "linux/amd64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-linux-amd64?checksum=sha256:236b5b83a7674e0e63ba286739c4670d15d7d6b3dcd810031ff83bdec2c0c2af",
+    "linux/arm64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-linux-arm64?checksum=sha256:b055fb7011e99d16a3ccae06443b0dcfd745b36480af6b3e569e88c94f3134d3",
+    "windows/armd64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-windows-amd64.exe?checksum=sha256:f0224ba914cad46dc27d6a9facd8179aec8a70727f0b1e509f0c6171c97ccf76",
+    "windows/arm64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-windows-arm64.exe?checksum=sha256:cbbce5933d501b4d54dcced9b097c052bffdef3fa8e1dfd75f29b34c3ee7de86"
+  }
+}
+```
+
+Upload your `draft_metadata.json` to a distribution platform of your choice. `draft_proposal.json` is used to submit a governance proposal using `submit-proposal`.
+
+```sh
+gaiad tx gov submit-proposal <path_to_proposal.json>
+   --from <submitter address> \
+   --chain-id cosmoshub-4 \
+   --gas <max gas allocated> \
+   --fees <fees allocated> \
+   --node <node address> \
+```
+
+## Using x/upgrading
+
+Software upgrade proposals can be submitted using the [x/upgrade module](https://docs.cosmos.network/v0.47/build/modules/upgrade#transactions). The end effect will be the same since the `x/gov` module routes the message to `x/upgrade` module.
+
+## Additional information
+
+Additional instructions with debugging information is available on the [submitting](../submitting.md) page.
+
diff --git a/docs/docs/governance/proposal-types/text-prop.md b/docs/docs/governance/proposal-types/text-prop.md
@@ -35,11 +35,53 @@ Technically, nothing happens on-chain. No code executes, and this 'unenforceable
 * The community might be more informed about a topic than they previously were.
 * The community might feel confident that we are aligned on a particular definition or social norm. 
 
-
-
-
-
-
-
-
-
+## Submitting a text proposal
+
+Follow the instructions below to create a text proposal and submit it to the blockchain.
+
+```sh
+➜ gaiad tx gov draft-proposal
+
+Use the arrow keys to navigate: ↓ ↑ → ←
+? Select proposal type:
+  ▸ text  # choose this
+    community-pool-spend
+    software-upgrade
+    cancel-software-upgrade
+    other
+```
+
+Choose `text` from the `draft-proposal` menu and populate all the available fields.
+```sh
+✔ text
+Enter proposal title: Title
+Enter proposal authors: Author
+Enter proposal summary: Proposal summary
+Enter proposal details: Details, all the details
+Enter proposal proposal forum url: /
+Enter proposal vote option context: Vote yes if <...>
+Enter proposal deposit: 100001uatom
+```
+
+Check `draft_proposal.json`, your result should be similar to this:
+```json
+{
+ "metadata": "ipfs://CID",
+ "deposit": "100001uatom",
+ "title": "Title",
+ "summary": "Proposal summary"
+}
+```
+
+Upload your `draft_metadata.json` to a distribution platform of your choice. `draft_proposal.json` is used to submit a governance proposal using `submit-proposal`.
+
+```sh
+gaiad tx gov submit-proposal <path_to_proposal.json>
+   --from <submitter address> \
+   --chain-id cosmoshub-4 \
+   --gas <max gas allocated> \
+   --fees <fees allocated> \
+   --node <node address> \
+```
+
+Additional instructions with debugging information is available on the [submitting](../submitting.md) page.
diff --git a/docs/docs/governance/proposals/_category_.json b/docs/docs/governance/proposals/_category_.json
@@ -1,4 +1,4 @@
 {
     "label": "Proposals",
-    "position": 1
+    "position": 6
 }
diff --git a/docs/docs/governance/submitting.md b/docs/docs/governance/submitting.md
@@ -256,4 +256,4 @@ You may want to submit your proposal to the testnet chain before the mainnet for
 1. To see what the proposal description will look like.
 2. To signal that your proposal is about to go live on the mainnet.
 3. To share what the proposal will look like in advance with stakeholders.
-4. To test the functionality of the governance features.
+4. To test the functionality of the governance features.
diff --git a/docs/docs/index.mdx b/docs/docs/index.mdx
@@ -7,10 +7,10 @@ import { currentParams } from '@site/docs/governance/current-parameters.js';
 import { PlainVar } from '@site/src/js/Var';
 
 :::tip
-### **v14 Upgrade**
-Cosmos Hub will be upgraded to [v14.1](https://github.com/cosmos/gaia/releases/tag/v14.1.0) at block height: **[18,262,000](https://www.mintscan.io/cosmos/blocks/18262000)**
+### **v15.1 Upgrade**
+Cosmos Hub will be upgraded to [v15.1](https://github.com/cosmos/gaia/releases/tag/v15.1.0) at block height: **[19,639,600](https://www.mintscan.io/cosmos/blocks/19639600)**
 
-To upgrade from v13 check the [**upgrade guide**](/migration/cosmoshub-4-v14-upgrade.md)
+To upgrade from v14 check the [**upgrade guide**](/migration/cosmoshub-4-v15-upgrade.md)
 :::
 
 ![Welcome to the Cosmos Hub](images/cosmos-hub-image.jpg)