Skip to main content
The upgrade module is responsible for handling and coordinating software upgrades. It accomplishes this by providing a BeginBlocker hook that prevents the blockchain state machine from proceeding once a pre-defined upgrade block height has been reached. For more information, visit https://docs.cosmos.network/main/modules/upgrade/

​
Message Types

Msg defines the upgrade Msg service.
tx.proto
service Msg {
  // SoftwareUpgrade is a governance operation for initiating a software upgrade.
  //
  // Since: cosmos-sdk 0.46
  rpc SoftwareUpgrade(MsgSoftwareUpgrade) returns (MsgSoftwareUpgradeResponse);
  // CancelUpgrade is a governance operation for cancelling a previously
  // approvid software upgrade.
  //
  // Since: cosmos-sdk 0.46
  rpc CancelUpgrade(MsgCancelUpgrade) returns (MsgCancelUpgradeResponse);
}

​
MsgSoftwareUpgrade

MsgSoftwareUpgrade is the Msg/SoftwareUpgrade request type. Since: cosmos-sdk 0.46
tx.proto
message MsgSoftwareUpgrade {
  option (cosmos.msg.v1.signer) = "authority";

  // authority is the address of the governance account.
  string authority = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

  // plan is the upgrade plan.
  Plan plan = 2 [(gogoproto.nullable) = false];
}

​
MsgSoftwareUpgradeResponse

MsgSoftwareUpgradeResponse is the Msg/SoftwareUpgrade response type. Since: cosmos-sdk 0.46
tx.proto
message MsgSoftwareUpgradeResponse {}

​
MsgCancelUpgrade

MsgCancelUpgrade is the Msg/CancelUpgrade request type. Since: cosmos-sdk 0.46
tx.proto
message MsgCancelUpgrade {
  option (cosmos.msg.v1.signer) = "authority";

  // authority is the address of the governance account.
  string authority = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}

​
MsgCancelUpgradeResponse

MsgCancelUpgradeResponse is the Msg/CancelUpgrade response type. Since: cosmos-sdk 0.46
tx.proto
message MsgCancelUpgradeResponse {}

​
Queries

Query defines the gRPC upgrade querier service.
query.proto
service Query {
  // CurrentPlan queries the current upgrade plan.
  rpc CurrentPlan(QueryCurrentPlanRequest) returns (QueryCurrentPlanResponse) {
    option (google.api.http).get = "/cosmos/upgrade/v1beta1/current_plan";
  }

  // AppliedPlan queries a previously applied upgrade plan by its name.
  rpc AppliedPlan(QueryAppliedPlanRequest) returns (QueryAppliedPlanResponse) {
    option (google.api.http).get = "/cosmos/upgrade/v1beta1/applied_plan/{name}";
  }

  // 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)
  rpc UpgradedConsensusState(QueryUpgradedConsensusStateRequest) returns (QueryUpgradedConsensusStateResponse) {
    option deprecated            = true;
    option (google.api.http).get = "/cosmos/upgrade/v1beta1/upgraded_consensus_state/{last_height}";
  }

  // ModuleVersions queries the list of module versions from state.
  //
  // Since: cosmos-sdk 0.43
  rpc ModuleVersions(QueryModuleVersionsRequest) returns (QueryModuleVersionsResponse) {
    option (google.api.http).get = "/cosmos/upgrade/v1beta1/module_versions";
  }

  // Returns the account with authority to conduct upgrades
  rpc Authority(QueryAuthorityRequest) returns (QueryAuthorityResponse) {
    option (google.api.http).get = "/cosmos/upgrade/v1beta1/authority";
  }
}

​
QueryCurrentPlanRequest

QueryCurrentPlanRequest is the request type for the Query/CurrentPlan RPC method.
query.proto
message QueryCurrentPlanRequest {}

​
QueryCurrentPlanResponse

QueryCurrentPlanResponse is the response type for the Query/CurrentPlan RPC method.
query.proto
message QueryCurrentPlanResponse {
  // plan is the current upgrade plan.
  Plan plan = 1;
}

​
QueryAppliedPlanRequest

QueryAppliedPlanRequest is the request type for the Query/AppliedPlan RPC method.
query.proto
message QueryAppliedPlanRequest {
  // name is the name of the applied plan to query for.
  string name = 1;
}

​
QueryAppliedPlanResponse

QueryAppliedPlanResponse is the response type for the Query/AppliedPlan RPC method.
query.proto
message QueryAppliedPlanResponse {
  // height is the block height at which the plan was applied.
  int64 height = 1;
}

​
QueryUpgradedConsensusStateRequest

QueryUpgradedConsensusStateRequest is the request type for the Query/UpgradedConsensusState RPC method.
query.proto
message QueryUpgradedConsensusStateRequest {
  option deprecated = true;

  // last height of the current chain must be sent in request
  // as this is the height under which next consensus state is stored
  int64 last_height = 1;
}

​
QueryUpgradedConsensusStateResponse

QueryUpgradedConsensusStateResponse is the response type for the Query/UpgradedConsensusState RPC method.
query.proto
message QueryUpgradedConsensusStateResponse {
  option deprecated = true;
  reserved 1;

  // Since: cosmos-sdk 0.43
  bytes upgraded_consensus_state = 2;
}

​
QueryModuleVersionsRequest

QueryModuleVersionsRequest is the request type for the Query/ModuleVersions RPC method. Since: cosmos-sdk 0.43
query.proto
message QueryModuleVersionsRequest {
  // 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
  string module_name = 1;
}

​
QueryModuleVersionsResponse

QueryModuleVersionsResponse is the response type for the Query/ModuleVersions RPC method. Since: cosmos-sdk 0.43
query.proto
message QueryModuleVersionsResponse {
  // module_versions is a list of module names with their consensus versions.
  repeated ModuleVersion module_versions = 1;
}

​
QueryAuthorityRequest

QueryAuthorityRequest is the request type for Query/Authority. Since: cosmos-sdk 0.46
query.proto
message QueryAuthorityRequest {}

​
QueryAuthorityResponse

QueryAuthorityResponse is the response type for Query/Authority. Since: cosmos-sdk 0.46
query.proto
message QueryAuthorityResponse {
  string address = 1;
}