> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmos.network/llms.txt
> Use this file to discover all available pages before exploring further.
# Upgrade
> gRPC queries and transaction messages defined by the upgrade module in Cosmos SDK v0.55.
Generated from [`cosmos/cosmos-sdk@2086680ff8b0`](https://github.com/cosmos/cosmos-sdk/tree/2086680ff8b08fd269ee653e087ea577bab79534/proto) on ref `release/v0.55.x`.
## Queries
A node exposes only the services its application registers:
* gRPC on port 9090
* REST on port 1317, if the method has an HTTP binding
Run `grpcurl -plaintext localhost:9090 list` to see what a node serves.
Queries are read-only and never pass through consensus. See [Queries](/sdk/latest/learn/concepts/transactions#queries).
Replace `` placeholders with real values and omit unused filters. Payloads use protobuf JSON, and some `string` fields accept enum constants listed under Types. Field tables give the encoding each value takes.
Examples assume a local node. For TLS endpoints, use port 443 and omit `-plaintext`. See [gRPC services](/sdk/latest/api-reference/grpc/index) for reflection, address formats, and decimal encoding.
### AppliedPlan
AppliedPlan queries a previously applied upgrade plan by its name.
| | |
| ---- | ------------------------------------------------- |
| gRPC | `cosmos.upgrade.v1beta1.Query/AppliedPlan` |
| REST | `GET /cosmos/upgrade/v1beta1/applied_plan/{name}` |
Request `QueryAppliedPlanRequest`:
| Field | Type | Description |
| ------ | -------- | -------------------------------------------------- |
| `name` | `string` | name is the name of the applied plan to query for. |
Response `QueryAppliedPlanResponse`:
| Field | Type | Description |
| -------- | ------- | --------------------------------------------------------- |
| `height` | `int64` | height is the block height at which the plan was applied. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"name":""}' \
localhost:9090 cosmos.upgrade.v1beta1.Query/AppliedPlan
```
### Authority
Returns the account with authority to conduct upgrades
| | |
| ---- | ---------------------------------------- |
| gRPC | `cosmos.upgrade.v1beta1.Query/Authority` |
| REST | `GET /cosmos/upgrade/v1beta1/authority` |
Request `QueryAuthorityRequest`:
This message has no fields.
Response `QueryAuthorityResponse`:
| Field | Type | Description |
| --------- | -------- | ----------- |
| `address` | `string` | |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext localhost:9090 cosmos.upgrade.v1beta1.Query/Authority
```
### CurrentPlan
CurrentPlan queries the current upgrade plan.
| | |
| ---- | ------------------------------------------ |
| gRPC | `cosmos.upgrade.v1beta1.Query/CurrentPlan` |
| REST | `GET /cosmos/upgrade/v1beta1/current_plan` |
Request `QueryCurrentPlanRequest`:
This message has no fields.
Response `QueryCurrentPlanResponse`:
| Field | Type | Description |
| ------ | -------------------------------------- | --------------------------------- |
| `plan` | [`Plan`](#cosmos-upgrade-v1beta1-plan) | plan is the current upgrade plan. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext localhost:9090 cosmos.upgrade.v1beta1.Query/CurrentPlan
```
### ModuleVersions
ModuleVersions queries the list of module versions from state.
| | |
| ---- | --------------------------------------------- |
| gRPC | `cosmos.upgrade.v1beta1.Query/ModuleVersions` |
| REST | `GET /cosmos/upgrade/v1beta1/module_versions` |
Request `QueryModuleVersionsRequest`:
| Field | Type | Description |
| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `module_name` | `string` | module\_name is a field to query a specific module consensus version from state. Leaving this empty will fetch the full list of module versions from state |
Response `QueryModuleVersionsResponse`:
| Field | Type | Description |
| ----------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------- |
| `module_versions` | [`ModuleVersion`](#cosmos-upgrade-v1beta1-moduleversion)\[] | module\_versions is a list of module names with their consensus versions. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"module_name":""}' \
localhost:9090 cosmos.upgrade.v1beta1.Query/ModuleVersions
```
### UpgradedConsensusState
This method is deprecated.
UpgradedConsensusState queries the consensus state that will serve as a trusted kernel for the next version of this chain. It will only be stored at the last height of this chain. UpgradedConsensusState RPC not supported with legacy querier This rpc is deprecated now that IBC has its own replacement ([https://github.com/cosmos/ibc-go/blob/2c880a22e9f9cc75f62b527ca94aa75ce1106001/proto/ibc/core/client/v1/query.proto#L54](https://github.com/cosmos/ibc-go/blob/2c880a22e9f9cc75f62b527ca94aa75ce1106001/proto/ibc/core/client/v1/query.proto#L54))
| | |
| ---- | ------------------------------------------------------------------- |
| gRPC | `cosmos.upgrade.v1beta1.Query/UpgradedConsensusState` |
| REST | `GET /cosmos/upgrade/v1beta1/upgraded_consensus_state/{lastHeight}` |
Request `QueryUpgradedConsensusStateRequest`:
| Field | Type | Description |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `last_height` | `int64` | last height of the current chain must be sent in request as this is the height under which next consensus state is stored |
Response `QueryUpgradedConsensusStateResponse`:
| Field | Type | Description |
| -------------------------- | ------- | ----------- |
| `upgraded_consensus_state` | `bytes` | |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"last_height":"1"}' \
localhost:9090 cosmos.upgrade.v1beta1.Query/UpgradedConsensusState
```
## Transaction messages
These messages are included in signed transactions, not called as endpoints. See [Transactions](/sdk/latest/learn/concepts/transactions#transactions) for the execution model, and [Sending transactions](/sdk/latest/api-reference/transactions) for the envelope they go into.
Examples use CLI transaction JSON. Decimal fields use values such as `"0.05"`, even when their proto type is `bytes`. The gRPC `TxEncode` method instead requires the scaled value `"50000000000000000"`. See [scalar encodings](/sdk/latest/api-reference/grpc/index#scalar-encodings).
* Handler: Generated client method
* Signer: Account that must sign
* Amino name: Legacy identifier used by hardware wallets and other Amino signers
### CancelUpgrade
CancelUpgrade is a governance operation for cancelling a previously approved software upgrade.
| | |
| ---------- | ------------------------------------------ |
| Type URL | `/cosmos.upgrade.v1beta1.MsgCancelUpgrade` |
| Handler | `cosmos.upgrade.v1beta1.Msg/CancelUpgrade` |
| Signer | `authority` |
| Amino name | `cosmos-sdk/MsgCancelUpgrade` |
The signer is the governance module account, which no user holds a key for. This message executes only through a passed governance proposal, not as a transaction you submit directly.
| Field | Type | Description |
| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `authority` | `string` | authority is the address that controls the module (defaults to x/gov unless overwritten). Encoded as cosmos.AddressString. |
In a transaction:
```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
"@type": "/cosmos.upgrade.v1beta1.MsgCancelUpgrade",
"authority": ""
}
```
Response `MsgCancelUpgradeResponse`:
This message has no fields.
### SoftwareUpgrade
SoftwareUpgrade is a governance operation for initiating a software upgrade.
| | |
| ---------- | -------------------------------------------- |
| Type URL | `/cosmos.upgrade.v1beta1.MsgSoftwareUpgrade` |
| Handler | `cosmos.upgrade.v1beta1.Msg/SoftwareUpgrade` |
| Signer | `authority` |
| Amino name | `cosmos-sdk/MsgSoftwareUpgrade` |
The signer is the governance module account, which no user holds a key for. This message executes only through a passed governance proposal, not as a transaction you submit directly.
| Field | Type | Description |
| ----------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `authority` | `string` | authority is the address that controls the module (defaults to x/gov unless overwritten). Encoded as cosmos.AddressString. |
| `plan` | [`Plan`](#cosmos-upgrade-v1beta1-plan) | plan is the upgrade plan. |
In a transaction:
```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
"@type": "/cosmos.upgrade.v1beta1.MsgSoftwareUpgrade",
"authority": "",
"plan": {
"name": "",
"height": "1",
"info": ""
}
}
```
Response `MsgSoftwareUpgradeResponse`:
This message has no fields.
## Types
Messages referenced by the fields above. Protocol buffers version 3 has no required fields, so every field is optional on the wire, and a `[]` suffix marks a repeated field.
### cosmos.upgrade.v1beta1.ModuleVersion
ModuleVersion specifies a module and its consensus version.
| Field | Type | Description |
| --------- | -------- | ----------------------------------- |
| `name` | `string` | name of the app module |
| `version` | `uint64` | consensus version of the app module |
### cosmos.upgrade.v1beta1.Plan
Plan specifies information about a planned upgrade and when it should occur.
| Field | Type | Description |
| ----------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `string` | Sets the name for the upgrade. This name will be used by the upgraded version of the software to apply any special "on-upgrade" commands during the first BeginBlock method after the upgrade is applied. It is also used to detect whether a software version can handle a given upgrade. If no upgrade handler with this name has been set in the software, it will be assumed that the software is out-of-date when the upgrade Time or Height is reached and the software will exit. |
| `time` | `Timestamp` | Deprecated: Time based upgrades have been deprecated. Time based upgrade logic has been removed from the SDK. If this field is not empty, an error will be thrown. Deprecated. |
| `height` | `int64` | The height at which the upgrade must be performed. |
| `info` | `string` | Any application specific upgrade info to be included on-chain such as a git commit that validators could automatically upgrade to |
| `upgraded_client_state` | `Any` | Deprecated: UpgradedClientState field has been deprecated. IBC upgrade logic has been moved to the IBC module in the sub module 02-client. If this field is not empty, an error will be thrown. Deprecated. |