Add message and rpc handler to upgrade clients using v1 governance proposals

[crodriguezvega]

Part of #1282.

Point for discussion: in #1282 @colin-axner mentions that one benefit for us to move to governance v1 proposal is simplifying UpgradeProposal (currently wraps calls to x/upgrade), an IBC chain upgrade could simply be combined with a x/upgrade message. I couldn't figure out a way to completely remove the dependency to the upgrade keeper, but I am open to discuss this to see if there's a way to do it. For now, the proposal here still uses the upgrade keeper in the same way as it is used currently in HandleUpgradeProposal.

Overview of changes:

Protobuf

• Add a new rpc handler to 02-client MsgService. Something like this:

rpc ScheduleIBCUpgrade(MsgScheduleIBCUpgrade) returns (MsgScheduleIBCUpgradeResponse);

where MsgScheduleIBCUpgrade could look like this:

message MsgScheduleIBCUpgrade {
  option (gogoproto.equal)           = false;
  option (gogoproto.goproto_getters) = false;
  option (cosmos.msg.v1.signer)      = "authority";

  // authority is the address of the governance account.
  string authority = 1;
  cosmos.upgrade.v1beta1.Plan plan = 2 [(gogoproto.nullable) = false];

  // An UpgradedClientState must be provided to perform an IBC breaking upgrade.
  // This will make the chain commit to the correct upgraded (self) client state
  // before the upgrade occurs, so that connecting chains can verify that the
  // new upgraded client is valid by verifying a proof on the previous version
  // of the chain. This will allow IBC connections to persist smoothly across
  // planned chain upgrades
  google.protobuf.Any upgraded_client_state = 3;
}

and MsgScheduleIBCUpgradeResponse can be empty:

message MsgScheduleIBCUpgradeResponse {}

02-client

• Add function ScheduleIBCUpgrade to 02-client keeper with logic to store the upgraded client state. The signature of the function could look like this:

func (k Keeper) ScheduleIBCUpgrade(ctx sdk.Context, plan types.Plan, upgradedClientState exported.ClientState) error

• Add implemenation of ScheduleIBCUpgrade, which could be in a few things similar to HandleUpgradeProposal's implementation. For example:

// zero out any custom fields before setting
cs := upgradedClientState.ZeroCustomFields()
bz, err := types.MarshalClientState(k.cdc, cs)
if err != nil {
  return errorsmod.Wrap(err, "could not marshal UpgradedClientState")
}

if err := k.upgradeKeeper.ScheduleIBCUpgrade(ctx, plan); err != nil {
  return err
}

// sets the new upgraded client in last height committed on this chain is at plan.Height,
// since the chain will panic at plan.Height and new chain will resume at plan.Height
if err = k.upgradeKeeper.SetUpgradedClient(ctx, plan.Height, bz); err != nil {
  return err
}

// emitting an event for handling client upgrade proposal
emitUpgradeClientProposalEvent(ctx, plan.Height)

return nil

Comparing with the existing implementation of HandleUpgradeProposal, the pseudocode above still depends on the upgrade keeper to schedule and set the upgraded client. Removing completely the dependency seems difficult at the moment, even if a client upgrade governance v1 proposal could execute two messages, one being the message added in this issue and another one SDK's MsgSoftwareUpgrade. With MsgSoftwareUpgrade the SDK can take care of scheduling the upgrade (i.e. executing call to upgrade keeper ScheduleUpgrade), but it would not handle the call to SetUpgradedClient, which we would still need to take care of ourselves. And since SetUpgradedClient requires the plan height, then I am not sure if it is really worth it to require governance to execute two different messages... But I am looking forward to discussing alternatives to do things better here.

• Implement sdk.Msg interface for MsgScheduleIBCUpgrade.

Core

• Add implementation of ScheduleIBCUpgrade rpc handler in IBC core msg_server.go (modules/core/keeper/msg_server.go). The signature of the handler could look like this:

func (k Keeper) ScheduleIBCUpgrade(
  goCtx context.Context, 
  msg *clienttypes.MsgScheduleUpgradeClient
) (*clienttypes.MsgScheduleUpgradeClientResponse, error)

and the implementation could look like this:

// check message signer matches authority set
if k.authority != msg.Signer {
  return nil, errorsmod.Wrapf(
    govtypes.ErrInvalidSigner, 
    "invalid authority: expected %s, got %s", k.authority, msg.Signer
  )
}

ctx := sdk.UnwrapSDKContext(goCtx)

clientState, err := types.UnpackClientState(p.UpgradedClientState)
if err != nil {
  return errorsmod.Wrap(err, "could not unpack UpgradedClientState")
}

err := k.ClientKeeper.ScheduleIBCUpgrade(ctx, msg.Plan, clientState)
if err != nil {
  return nil, errorsmod.Wrap(err, "client upgrade schedule failed")
}

return &types.MsgScheduleUpgradeClientResponse{}, nil

• Add extra &MsgScheduleIBCUpgrade{} as input to RegisterImplementations.

CLI

• Implement a CLI command (NewCmdSubmitScheduleIBCUpgradeProposal) in 02-client with flag schedule-ibc-upgrade and parameters name, height and path/to/upgraded_client_state.json to construct a MsgScheduleIBCUpgrade and include it in a MsgSubmitProposal. Use v1beta1 legacy NewCmdSubmitUpgradeProposal command and SDK's NewCmdSubmitUpgradeProposal as examples.

Documentation

• Update documentation for client upgrades via governance proposals.

Break up the implementation in multiple PRs. One possible suggestion:

• PR for adding the new message type add protos, msgs, keeper handler to upgrade clients using v1 governance proposals #4436
• PR for adding the message server handler msg server function and tests for MsgScheduleIBCClientUpgrade #4442
• PR for updating the docs
• PR for adding e2e test?
• PR for CLI (requires SDK v0.47.5 or v0.50)

[colin-axner]

accomplished by all the linked pr's. Commit to merge will come from #4620