docs: client docs for upgrade module (#10320)
<!-- The default pull request template is for types feat, fix, or refactor. For other templates, add one of the following parameters to the url: - template=docs.md - template=other.md --> ## Description Closes: #10294 <!-- Add a description of the changes that this PR introduces and the files that are the most critical to review. --> --- ### Author Checklist *All items are required. Please add a note to the item if the item is not applicable and please add links to any relevant follow up issues.* I have... - [x] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [ ] added `!` to the type prefix if API or client breaking change - [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting)) - [x] provided a link to the relevant issue or specification - [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules) - [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing) - [ ] added a changelog entry to `CHANGELOG.md` - [ ] included comments for [documenting Go code](https://blog.golang.org/godoc) - [ ] updated the relevant documentation or specification - [x] reviewed "Files changed" and left comments if necessary - [x] confirmed all CI checks have passed ### Reviewers Checklist *All items are required. Please add a note if the item is not applicable and please add your handle next to the items reviewed if you only reviewed selected items.* I have... - [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [ ] confirmed `!` in the type prefix if API or client breaking change - [ ] confirmed all author checklist items have been addressed - [ ] reviewed state machine logic - [ ] reviewed API design and naming - [ ] reviewed documentation is accurate - [ ] reviewed tests and test coverage - [ ] manually tested (if applicable)
This commit is contained in:
Murali Krishna Komatireddy
GitHub
parent
698382447d
commit
33f3b69d05
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,462 @@
|
|||
<!--
|
||||
order: 4
|
||||
-->
|
||||
|
||||
# Client
|
||||
|
||||
## CLI
|
||||
|
||||
A user can query and interact with the `upgrade` module using the CLI.
|
||||
|
||||
### Query
|
||||
|
||||
The `query` commands allow users to query `upgrade` state.
|
||||
|
||||
```bash
|
||||
simd query upgrade --help
|
||||
```
|
||||
|
||||
#### applied
|
||||
|
||||
The `applied` command allows users to query the block header for height at which a completed upgrade was applied.
|
||||
|
||||
```bash
|
||||
simd query upgrade applied [upgrade-name] [flags]
|
||||
```
|
||||
|
||||
If upgrade-name was previously executed on the chain, this returns the header for the block at which it was applied.
|
||||
This helps a client determine which binary was valid over a given range of blocks, as well as more context to understand past migrations.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
simd query upgrade applied "test-upgrade"
|
||||
```
|
||||
|
||||
Example Output:
|
||||
|
||||
```bash
|
||||
"block_id": {
|
||||
"hash": "A769136351786B9034A5F196DC53F7E50FCEB53B48FA0786E1BFC45A0BB646B5",
|
||||
"parts": {
|
||||
"total": 1,
|
||||
"hash": "B13CBD23011C7480E6F11BE4594EE316548648E6A666B3575409F8F16EC6939E"
|
||||
}
|
||||
},
|
||||
"block_size": "7213",
|
||||
"header": {
|
||||
"version": {
|
||||
"block": "11"
|
||||
},
|
||||
"chain_id": "testnet-2",
|
||||
"height": "455200",
|
||||
"time": "2021-04-10T04:37:57.085493838Z",
|
||||
"last_block_id": {
|
||||
"hash": "0E8AD9309C2DC411DF98217AF59E044A0E1CCEAE7C0338417A70338DF50F4783",
|
||||
"parts": {
|
||||
"total": 1,
|
||||
"hash": "8FE572A48CD10BC2CBB02653CA04CA247A0F6830FF19DC972F64D339A355E77D"
|
||||
}
|
||||
},
|
||||
"last_commit_hash": "DE890239416A19E6164C2076B837CC1D7F7822FC214F305616725F11D2533140",
|
||||
"data_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855",
|
||||
"validators_hash": "A31047ADE54AE9072EE2A12FF260A8990BA4C39F903EAF5636B50D58DBA72582",
|
||||
"next_validators_hash": "A31047ADE54AE9072EE2A12FF260A8990BA4C39F903EAF5636B50D58DBA72582",
|
||||
"consensus_hash": "048091BC7DDC283F77BFBF91D73C44DA58C3DF8A9CBC867405D8B7F3DAADA22F",
|
||||
"app_hash": "28ECC486AFC332BA6CC976706DBDE87E7D32441375E3F10FD084CD4BAF0DA021",
|
||||
"last_results_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855",
|
||||
"evidence_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855",
|
||||
"proposer_address": "2ABC4854B1A1C5AA8403C4EA853A81ACA901CC76"
|
||||
},
|
||||
"num_txs": "0"
|
||||
}
|
||||
```
|
||||
|
||||
#### module versions
|
||||
|
||||
The `module_versions` command gets a list of module names and their respective consensus versions.
|
||||
|
||||
Following the command with a specific module name will return only
|
||||
that module's information.
|
||||
|
||||
```bash
|
||||
simd query upgrade module_versions [optional module_name] [flags]
|
||||
```
|
||||
Example:
|
||||
|
||||
```bash
|
||||
simd query upgrade module_versions
|
||||
```
|
||||
|
||||
Example Output:
|
||||
```bash
|
||||
module_versions:
|
||||
- name: auth
|
||||
version: "2"
|
||||
- name: authz
|
||||
version: "1"
|
||||
- name: bank
|
||||
version: "2"
|
||||
- name: capability
|
||||
version: "1"
|
||||
- name: crisis
|
||||
version: "1"
|
||||
- name: distribution
|
||||
version: "2"
|
||||
- name: evidence
|
||||
version: "1"
|
||||
- name: feegrant
|
||||
version: "1"
|
||||
- name: genutil
|
||||
version: "1"
|
||||
- name: gov
|
||||
version: "2"
|
||||
- name: ibc
|
||||
version: "2"
|
||||
- name: mint
|
||||
version: "1"
|
||||
- name: params
|
||||
version: "1"
|
||||
- name: slashing
|
||||
version: "2"
|
||||
- name: staking
|
||||
version: "2"
|
||||
- name: transfer
|
||||
version: "1"
|
||||
- name: upgrade
|
||||
version: "1"
|
||||
- name: vesting
|
||||
version: "1"
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
regen query upgrade module_versions ibc
|
||||
```
|
||||
|
||||
Example Output:
|
||||
|
||||
```bash
|
||||
module_versions:
|
||||
- name: ibc
|
||||
version: "2"
|
||||
```
|
||||
|
||||
#### plan
|
||||
|
||||
The `plan` command gets the currently scheduled upgrade plan, if one exists.
|
||||
|
||||
```bash
|
||||
regen query upgrade plan [flags]
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
simd query upgrade plan
|
||||
```
|
||||
|
||||
Example Output:
|
||||
|
||||
```bash
|
||||
height: "130"
|
||||
info: ""
|
||||
name: test-upgrade
|
||||
time: "0001-01-01T00:00:00Z"
|
||||
upgraded_client_state: null
|
||||
```
|
||||
|
||||
|
||||
## REST
|
||||
|
||||
A user can query the `upgrade` module using REST endpoints.
|
||||
|
||||
### Applied Plan
|
||||
|
||||
`AppliedPlan` queries a previously applied upgrade plan by its name.
|
||||
|
||||
```bash
|
||||
/cosmos/upgrade/v1beta1/applied_plan/{name}
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
curl -X GET "http://localhost:1317/cosmos/upgrade/v1beta1/applied_plan/v2.0-upgrade" -H "accept: application/json"
|
||||
```
|
||||
|
||||
Example Output:
|
||||
|
||||
```bash
|
||||
{
|
||||
"height": "30"
|
||||
}
|
||||
```
|
||||
|
||||
### Current Plan
|
||||
|
||||
`CurrentPlan` queries the current upgrade plan.
|
||||
|
||||
```bash
|
||||
/cosmos/upgrade/v1beta1/current_plan
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
curl -X GET "http://localhost:1317/cosmos/upgrade/v1beta1/current_plan" -H "accept: application/json"
|
||||
```
|
||||
|
||||
Example Output:
|
||||
|
||||
```bash
|
||||
{
|
||||
"plan": "v2.1-upgrade"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### Module versions
|
||||
|
||||
`ModuleVersions` queries the list of module versions from state.
|
||||
|
||||
```bash
|
||||
/cosmos/upgrade/v1beta1/module_versions
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
curl -X GET "http://localhost:1317/cosmos/upgrade/v1beta1/module_versions" -H "accept: application/json"
|
||||
```
|
||||
|
||||
Example Output:
|
||||
|
||||
```bash
|
||||
{
|
||||
"module_versions": [
|
||||
{
|
||||
"name": "auth",
|
||||
"version": "2"
|
||||
},
|
||||
{
|
||||
"name": "authz",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "bank",
|
||||
"version": "2"
|
||||
},
|
||||
{
|
||||
"name": "capability",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "crisis",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "distribution",
|
||||
"version": "2"
|
||||
},
|
||||
{
|
||||
"name": "evidence",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "feegrant",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "genutil",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "gov",
|
||||
"version": "2"
|
||||
},
|
||||
{
|
||||
"name": "ibc",
|
||||
"version": "2"
|
||||
},
|
||||
{
|
||||
"name": "mint",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "params",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "slashing",
|
||||
"version": "2"
|
||||
},
|
||||
{
|
||||
"name": "staking",
|
||||
"version": "2"
|
||||
},
|
||||
{
|
||||
"name": "transfer",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "upgrade",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "vesting",
|
||||
"version": "1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## gRPC
|
||||
|
||||
A user can query the `upgrade` module using gRPC endpoints.
|
||||
|
||||
### Applied Plan
|
||||
|
||||
`AppliedPlan` queries a previously applied upgrade plan by its name.
|
||||
|
||||
```bash
|
||||
cosmos.upgrade.v1beta1.Query/AppliedPlan
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
grpcurl -plaintext \
|
||||
-d '{"name":"v2.0-upgrade"}' \
|
||||
localhost:9090 \
|
||||
cosmos.upgrade.v1beta1.Query/AppliedPlan
|
||||
```
|
||||
|
||||
Example Output:
|
||||
|
||||
```bash
|
||||
{
|
||||
"height": "30"
|
||||
}
|
||||
```
|
||||
|
||||
### Current Plan
|
||||
|
||||
`CurrentPlan` queries the current upgrade plan.
|
||||
|
||||
```bash
|
||||
cosmos.upgrade.v1beta1.Query/CurrentPlan
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
grpcurl -plaintext localhost:9090 cosmos.slashing.v1beta1.Query/CurrentPlan
|
||||
```
|
||||
|
||||
Example Output:
|
||||
|
||||
```bash
|
||||
{
|
||||
"plan": "v2.1-upgrade"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### Module versions
|
||||
|
||||
`ModuleVersions` queries the list of module versions from state.
|
||||
|
||||
```bash
|
||||
cosmos.upgrade.v1beta1.Query/ModuleVersions
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
grpcurl -plaintext localhost:9090 cosmos.slashing.v1beta1.Query/ModuleVersions
|
||||
```
|
||||
|
||||
Example Output:
|
||||
|
||||
```bash
|
||||
{
|
||||
"module_versions": [
|
||||
{
|
||||
"name": "auth",
|
||||
"version": "2"
|
||||
},
|
||||
{
|
||||
"name": "authz",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "bank",
|
||||
"version": "2"
|
||||
},
|
||||
{
|
||||
"name": "capability",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "crisis",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "distribution",
|
||||
"version": "2"
|
||||
},
|
||||
{
|
||||
"name": "evidence",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "feegrant",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "genutil",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "gov",
|
||||
"version": "2"
|
||||
},
|
||||
{
|
||||
"name": "ibc",
|
||||
"version": "2"
|
||||
},
|
||||
{
|
||||
"name": "mint",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "params",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "slashing",
|
||||
"version": "2"
|
||||
},
|
||||
{
|
||||
"name": "staking",
|
||||
"version": "2"
|
||||
},
|
||||
{
|
||||
"name": "transfer",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "upgrade",
|
||||
"version": "1"
|
||||
},
|
||||
{
|
||||
"name": "vesting",
|
||||
"version": "1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
|
@ -25,3 +25,7 @@ recover from.
|
|||
1. **[Concepts](01_concepts.md)**
|
||||
2. **[State](02_state.md)**
|
||||
3. **[Events](03_events.md)**
|
||||
4. **[Client](04_client.md)**
|
||||
- [CLI](04_client.md#cli)
|
||||
- [REST](04_client.md#rest)
|
||||
- [gRPC](04_client.md#grpc)
|
||||
|
|
|
|||
Loading…
Reference in New Issue