refactor: require light clients to set initial client and consensus state

docs/ibc/light-clients/client-state.md

@@ -48,9 +48,10 @@ This value is used to facilitate timeouts by checking the packet timeout timesta
 
 ## `Initialize` method
 
-Clients must validate the initial consensus state, and may store any client-specific metadata necessary.
+Clients must validate the initial consensus state, and set the initial client state and consensus state in the provided client store.
+Clients may also store any client-specific metadata necessary.
 
-`Initialize` gets called when a [client is created](https://github.com/cosmos/ibc-go/blob/main/modules/core/02-client/keeper/client.go#L32).
+`Initialize` is called when a [client is created](https://github.com/cosmos/ibc-go/blob/main/modules/core/02-client/keeper/client.go#L32).
 
 ## `VerifyMembership` method
 

docs/migrations/v6-to-v7.md

@@ -106,7 +106,9 @@ The `VerifyUpgradeAndUpdateState` function has been modified. The client state a
 
 Light clients **must** handle all management of client and consensus states including the setting of updated client state and consensus state in the client store.
 
-The `CheckHeaderAndUpdateState` function has been split into 4 new functions:
+The `Initialize` method is now expected to set the initial client state, consensus state and any client-specific metadata in the provided store upon client creation. 
+
+The `CheckHeaderAndUpdateState` method has been split into 4 new methods:
 
 - `VerifyClientMessage` verifies a `ClientMessage`. A `ClientMessage` could be a `Header`, `Misbehaviour`, or batch update. Calls to `CheckForMisbehaviour`, `UpdateState`, and `UpdateStateOnMisbehaviour` will assume that the content of the `ClientMessage` has been verified and can be trusted. An error should be returned if the `ClientMessage` fails to verify.
 

modules/core/02-client/keeper/client.go

@@ -10,8 +10,9 @@ import (
 	"github.com/cosmos/ibc-go/v6/modules/core/exported"
 )
 
-// CreateClient creates a new client state and populates it with a given consensus
-// state as defined in https://github.com/cosmos/ibc/tree/master/spec/core/ics-002-client-semantics#create
+// CreateClient generates a new client identifier and isolated prefix store for the provided client state.
+// The client state is responsible for setting any client-specific data in the store via the Initialize method.
+// This includes the client state, initial consensus state and any associated metadata.
 func (k Keeper) CreateClient(
 	ctx sdk.Context, clientState exported.ClientState, consensusState exported.ConsensusState,
 ) (string, error) {
@@ -24,18 +25,12 @@ func (k Keeper) CreateClient(
 	}
 
 	clientID := k.GenerateClientIdentifier(ctx, clientState.ClientType())
+	clientStore := k.ClientStore(ctx, clientID)
 
-	k.Logger(ctx).Info("client created at height", "client-id", clientID, "height", clientState.GetLatestHeight().String())
-
-	// verifies initial consensus state against client state and initializes client store with any client-specific metadata
-	// e.g. set ProcessedTime in Tendermint clients
-	if err := clientState.Initialize(ctx, k.cdc, k.ClientStore(ctx, clientID), consensusState); err != nil {
+	if err := clientState.Initialize(ctx, k.cdc, clientStore, consensusState); err != nil {
 		return "", err
 	}
 
-	k.SetClientState(ctx, clientID, clientState)
-	k.SetClientConsensusState(ctx, clientID, clientState.GetLatestHeight(), consensusState)
-
 	k.Logger(ctx).Info("client created at height", "client-id", clientID, "height", clientState.GetLatestHeight().String())
 
 	defer telemetry.IncrCounterWithLabels(

modules/core/exported/client.go

@@ -59,9 +59,8 @@ type ClientState interface {
 		height Height,
 	) (uint64, error)
 
-	// Initialization function
-	// Clients must validate the initial consensus state, and may store any client-specific metadata
-	// necessary for correct light client operation
+	// Initialize is called upon client creation, it allows the client to perform validation on the initial consensus state and set the
+	// client state, consensus state and any client-specific metadata necessary for correct light client operation in the provided client store.
 	Initialize(ctx sdk.Context, cdc codec.BinaryCodec, clientStore sdk.KVStore, consensusState ConsensusState) error
 
 	// VerifyMembership is a generic proof verification method which verifies a proof of the existence of a value at a given CommitmentPath at the specified height.

modules/light-clients/06-solomachine/client_state.go

@@ -77,12 +77,16 @@ func (cs ClientState) ZeroCustomFields() exported.ClientState {
 	panic("ZeroCustomFields is not implemented as the solo machine implementation does not support upgrades.")
 }
 
-// Initialize will check that initial consensus state is equal to the latest consensus state of the initial client.
-func (cs ClientState) Initialize(_ sdk.Context, _ codec.BinaryCodec, _ sdk.KVStore, consState exported.ConsensusState) error {
+// Initialize checks that the initial consensus state is equal to the latest consensus state of the initial client and
+// sets the client state in the provided client store.
+func (cs ClientState) Initialize(_ sdk.Context, cdc codec.BinaryCodec, clientStore sdk.KVStore, consState exported.ConsensusState) error {
 	if !reflect.DeepEqual(cs.ConsensusState, consState) {
 		return sdkerrors.Wrapf(clienttypes.ErrInvalidConsensus, "consensus state in initial client does not equal initial consensus state. expected: %s, got: %s",
 			cs.ConsensusState, consState)
 	}
+
+	setClientState(clientStore, cdc, &cs)
+
 	return nil
 }
 

modules/light-clients/07-tendermint/client_state.go

@@ -188,15 +188,19 @@ func (cs ClientState) ZeroCustomFields() exported.ClientState {
 	}
 }
 
-// Initialize will check that initial consensus state is a Tendermint consensus state
-// and will store ProcessedTime for initial consensus state as ctx.BlockTime()
-func (cs ClientState) Initialize(ctx sdk.Context, _ codec.BinaryCodec, clientStore sdk.KVStore, consState exported.ConsensusState) error {
-	if _, ok := consState.(*ConsensusState); !ok {
+// Initialize checks that the initial consensus state is an 07-tendermint consensus state and
+// sets the client state, consensus state and associated metadata in the provided client store.
+func (cs ClientState) Initialize(ctx sdk.Context, cdc codec.BinaryCodec, clientStore sdk.KVStore, consState exported.ConsensusState) error {
+	consensusState, ok := consState.(*ConsensusState)
+	if !ok {
 		return sdkerrors.Wrapf(clienttypes.ErrInvalidConsensus, "invalid initial consensus state. expected type: %T, got: %T",
 			&ConsensusState{}, consState)
 	}
-	// set metadata for initial consensus state.
+
+	setClientState(clientStore, cdc, &cs)
+	setConsensusState(clientStore, cdc, consensusState, cs.GetLatestHeight())
 	setConsensusMetadata(ctx, clientStore, cs.GetLatestHeight())
+
 	return nil
 }