refactor!: decouple client routing from encoding

CHANGELOG.md

@@ -40,6 +40,8 @@ Ref: https://keepachangelog.com/en/1.0.0/
 
 ### API Breaking
 
+* (core/02-client, light-clients) [\#5806](https://github.com/cosmos/ibc-go/pull/5806) Decouple light client routing from their encoding structure.
+
 ### State Machine Breaking
 
 ### Improvements

docs/docs/01-ibc/05-upgrades/02-developer-guide.md

@@ -11,4 +11,4 @@ slug: /ibc/upgrades/developer-guide
 Learn how to implement upgrade functionality for your custom IBC client.
 :::
 
-Please see the section [Handling upgrades](../../03-light-clients/01-developer-guide/05-upgrades.md) from the light client developer guide for more information.
+Please see the section [Handling upgrades](../../03-light-clients/01-developer-guide/06-upgrades.md) from the light client developer guide for more information.

docs/docs/03-light-clients/01-developer-guide/01-overview.md

@@ -27,6 +27,7 @@ The following aims to provide a high level IBC light client module developer gui
 
 A light client module developer should be concerned with three main interfaces:
 
+- [`LightClientModule`](#lightclientmodule) a module which manages many light client instances of a certain type. 
 - [`ClientState`](#clientstate) encapsulates the light client implementation and its semantics.
 - [`ConsensusState`](#consensusstate) tracks consensus data used for verification of client updates, misbehaviour detection and proof verification of counterparty state.
 - [`ClientMessage`](#clientmessage) used for submitting block headers for client updates and submission of misbehaviour evidence using conflicting headers.
@@ -35,6 +36,21 @@ Throughout this guide the `07-tendermint` light client module may be referred to
 
 ## Concepts and vocabulary
 
+### `LightClientModule`
+
+`LightClientModule` is an interface defined by core IBC which allows for modular light client implementations. All light client implementations *must* implement the [`LightClientModule` interface](https://github.com/cosmos/ibc-go/blob/501a8462345da099144efe91d495bfcfa18d760d/modules/core/exported/client.go#L51) so that core IBC may redirect calls to the light client module. 
+
+For example a light client module may need to:
+
+- create clients
+- update clients
+- recover and upgrade clients
+- verify membership and non-membership
+
+The methods which make up this interface are detailed at a more granular level in the [`LightClientModule` section of this guide](02-light-client-module.md).
+
+Please refer to the `07-tendermint`'s [`LightClientModule` definition](https://github.com/cosmos/ibc-go/blob/501a8462345da099144efe91d495bfcfa18d760d/modules/light-clients/07-tendermint/light_client_module.go#L17) for more information. 
+
 ### `ClientState`
 
 `ClientState` is a term used to define the data structure which encapsulates opaque light client state. The `ClientState` contains all the information needed to verify a `ClientMessage` and perform membership and non-membership proof verification of counterparty state. This includes properties that refer to the remote state machine, the light client type and the specific light client instance.
@@ -47,7 +63,7 @@ For example:
 - Constraints used for client upgrades.
 
 The `ClientState` type maintained within the light client module *must* implement the [`ClientState`](https://github.com/cosmos/ibc-go/tree/02-client-refactor-beta1/modules/core/exported/client.go#L36) interface defined in `core/modules/exported/client.go`.
-The methods which make up this interface are detailed at a more granular level in the [ClientState section of this guide](02-client-state.md).
+The methods which make up this interface are detailed at a more granular level in the [`ClientState` section of this guide](03-client-state.md).
 
 Please refer to the `07-tendermint` light client module's [`ClientState` definition](https://github.com/cosmos/ibc-go/tree/02-client-refactor-beta1/proto/ibc/lightclients/tendermint/v1/tendermint.proto#L18) containing information such as chain ID, status, latest height, unbonding period and proof specifications.
 
@@ -58,7 +74,7 @@ Please refer to the `07-tendermint` light client module's [`ClientState` definit
 For example, the `ConsensusState` of the `07-tendermint` light client module defines a trusted root which is used by the `ClientState` to perform verification of membership and non-membership commitment proofs, as well as the next validator set hash used for verifying headers can be trusted in client updates.
 
 The `ConsensusState` type maintained within the light client module *must* implement the [`ConsensusState`](https://github.com/cosmos/ibc-go/tree/02-client-refactor-beta1/modules/core/exported/client.go#L134) interface defined in `modules/core/exported/client.go`.
-The methods which make up this interface are detailed at a more granular level in the [`ConsensusState` section of this guide](03-consensus-state.md).
+The methods which make up this interface are detailed at a more granular level in the [`ConsensusState` section of this guide](04-consensus-state.md).
 
 ### `Height`
 
@@ -76,4 +92,4 @@ The following are considered as valid update scenarios:
 - A batch of block headers which when verified inserts `N` `ConsensusState` instances for `N` unique heights.
 - Evidence of misbehaviour provided by two conflicting block headers.
 
-Learn more in the [Handling update and misbehaviour](04-updates-and-misbehaviour.md) section.
+Learn more in the [Handling update and misbehaviour](05-updates-and-misbehaviour.md) section.

docs/docs/03-light-clients/01-developer-guide/02-client-state.md → docs/docs/03-light-clients/01-developer-guide/02-light-client-module.md

@@ -1,28 +1,12 @@
 ---
-title: Client State interface
-sidebar_label: Client State interface
+title: Light Client Module interface
+sidebar_label: Light Client Module interface
 sidebar_position: 2
-slug: /ibc/light-clients/client-state
+slug: /ibc/light-clients/light-client-module
 ---
 
 
-# Implementing the `ClientState` interface
-
-Learn how to implement the [`ClientState`](https://github.com/cosmos/ibc-go/blob/v7.0.0/modules/core/exported/client.go#L36) interface. This list of methods described here does not include all methods of the interface. Some methods are explained in detail in the relevant sections of the guide.
-
-## `ClientType` method
-
-`ClientType` should return a unique string identifier of the light client. This will be used when generating a client identifier.
-The format is created as follows: `ClientType-{N}` where `{N}` is the unique global nonce associated with a specific client.
-
-## `GetLatestHeight` method
-
-`GetLatestHeight` should return the latest block height that the client state represents.
-
-## `Validate` method
-
-`Validate` should validate every client state field and should return an error if any value is invalid. The light client
-implementer is in charge of determining which checks are required. See the [Tendermint light client implementation](https://github.com/cosmos/ibc-go/blob/v7.0.0/modules/light-clients/07-tendermint/client_state.go#L111) as a reference.
+# Implementing the `LightClientModule` interface
 
 ## `Status` method
 
@@ -37,9 +21,9 @@ All possible `Status` types can be found [here](https://github.com/cosmos/ibc-go
 
 This field is returned in the response of the gRPC [`ibc.core.client.v1.Query/ClientStatus`](https://github.com/cosmos/ibc-go/blob/v7.0.0/modules/core/02-client/types/query.pb.go#L665) endpoint.
 
-## `GetTimestampAtHeight` method
+## `TimestampAtHeight` method
 
-`GetTimestampAtHeight` must return the timestamp for the consensus state associated with the provided height.
+`TimestampAtHeight` must return the timestamp for the consensus state associated with the provided height.
 This value is used to facilitate timeouts by checking the packet timeout timestamp against the returned value.
 
 ## `Initialize` method
@@ -52,12 +36,12 @@ Clients may also store any necessary client-specific metadata.
 ## `VerifyMembership` method
 
 `VerifyMembership` must verify the existence of a value at a given commitment path at the specified height. For more information about membership proofs
-see the [Existence and non-existence proofs section](06-proofs.md).
+see the [Existence and non-existence proofs section](07-proofs.md).
 
 ## `VerifyNonMembership` method
 
 `VerifyNonMembership` must verify the absence of a value at a given commitment path at a specified height. For more information about non-membership proofs
-see the [Existence and non-existence proofs section](06-proofs.md).
+see the [Existence and non-existence proofs section](07-proofs.md).
 
 ## `VerifyClientMessage` method
 

docs/docs/03-light-clients/01-developer-guide/03-client-state.md

@@ -0,0 +1,21 @@
+---
+title: Client State interface
+sidebar_label: Client State interface
+sidebar_position: 3
+slug: /ibc/light-clients/client-state
+---
+
+
+# Implementing the `ClientState` interface
+
+Learn how to implement the [`ClientState`](https://github.com/cosmos/ibc-go/blob/v7.0.0/modules/core/exported/client.go#L36) interface.
+
+## `ClientType` method
+
+`ClientType` should return a unique string identifier of the light client. This will be used when generating a client identifier.
+The format is created as follows: `{client-type}-{N}` where `{N}` is the unique global nonce associated with a specific client (e.g `07-tendermint-0`).
+
+## `Validate` method
+
+`Validate` should validate every client state field and should return an error if any value is invalid. The light client
+implementer is in charge of determining which checks are required. See the [Tendermint light client implementation](https://github.com/cosmos/ibc-go/blob/v7.0.0/modules/light-clients/07-tendermint/client_state.go#L111) as a reference.

docs/docs/03-light-clients/01-developer-guide/03-consensus-state.md → docs/docs/03-light-clients/01-developer-guide/04-consensus-state.md

@@ -1,7 +1,7 @@
 ---
 title: Consensus State interface
 sidebar_label: Consensus State interface
-sidebar_position: 3
+sidebar_position: 4
 slug: /ibc/light-clients/consensus-state
 ---
 
@@ -16,13 +16,11 @@ The below [`ConsensusState`](https://github.com/cosmos/ibc-go/blob/v7.0.0/module
 
 ## `ClientType` method
 
-This is the type of client consensus. It should be the same as the `ClientType` return value for the [corresponding `ClientState` implementation](02-client-state.md).
+This is the type of client consensus. It should be the same as the `ClientType` return value for the [corresponding `ClientState` implementation](03-client-state.md).
 
 ## `GetTimestamp` method
 
-*Deprecated*: soon to be removed from interface
-
-`GetTimestamp` should return the timestamp (in nanoseconds) of the consensus state snapshot.
+`GetTimestamp` should return the timestamp (in nanoseconds) of the consensus state snapshot. This function has been deprecated and will be removed in a future release.
 
 ## `ValidateBasic` method
 

docs/docs/03-light-clients/01-developer-guide/04-updates-and-misbehaviour.md → docs/docs/03-light-clients/01-developer-guide/05-updates-and-misbehaviour.md

@@ -1,14 +1,14 @@
 ---
 title: Handling Updates and Misbehaviour
 sidebar_label: Handling Updates and Misbehaviour
-sidebar_position: 4
+sidebar_position: 5
 slug: /ibc/light-clients/updates-and-misbehaviour
 ---
 
 
 # Handling `ClientMessage`s: updates and misbehaviour
 
-As mentioned before in the documentation about [implementing the `ConsensusState` interface](03-consensus-state.md), [`ClientMessage`](https://github.com/cosmos/ibc-go/blob/v7.0.0/modules/core/exported/client.go#L147) is an interface used to update an IBC client. This update may be performed by:
+As mentioned before in the documentation about [implementing the `ConsensusState` interface](04-consensus-state.md), [`ClientMessage`](https://github.com/cosmos/ibc-go/blob/v7.0.0/modules/core/exported/client.go#L147) is an interface used to update an IBC client. This update may be performed by:
 
 - a single header
 - a batch of headers
@@ -30,7 +30,7 @@ type ClientMessage interface {
 }
 ```
 
-The `ClientMessage` will be passed to the client to be used in [`UpdateClient`](https://github.com/cosmos/ibc-go/blob/v7.0.0/modules/core/02-client/keeper/client.go#L48), which retrieves the `ClientState` by client ID (available in `MsgUpdateClient`). This `ClientState` implements the [`ClientState` interface](02-client-state.md) for its specific consenus type (e.g. Tendermint).
+The `ClientMessage` will be passed to the client to be used in [`UpdateClient`](https://github.com/cosmos/ibc-go/blob/v7.0.0/modules/core/02-client/keeper/client.go#L48), which retrieves the `ClientState` by client ID (available in `MsgUpdateClient`). This `ClientState` implements the [`ClientState` interface](03-client-state.md) for its specific consenus type (e.g. Tendermint).
 
 `UpdateClient` will then handle a number of cases including misbehaviour and/or updating the consensus state, utilizing the specific methods defined in the relevant `ClientState`.
 

docs/docs/03-light-clients/01-developer-guide/05-upgrades.md → docs/docs/03-light-clients/01-developer-guide/06-upgrades.md

@@ -1,7 +1,7 @@
 ---
 title: Handling Upgrades
 sidebar_label: Handling Upgrades
-sidebar_position: 5
+sidebar_position: 6
 slug: /ibc/light-clients/upgrades
 ---
 

docs/docs/03-light-clients/01-developer-guide/06-proofs.md → docs/docs/03-light-clients/01-developer-guide/07-proofs.md

@@ -1,7 +1,7 @@
 ---
 title: Existence/Non-Existence Proofs
 sidebar_label: Existence/Non-Existence Proofs
-sidebar_position: 6
+sidebar_position: 7
 slug: /ibc/light-clients/proofs
 ---
 

docs/docs/03-light-clients/01-developer-guide/07-proposals.md → docs/docs/03-light-clients/01-developer-guide/08-proposals.md

@@ -1,7 +1,7 @@
 ---
 title: Handling Proposals
 sidebar_label: Handling Proposals
-sidebar_position: 7
+sidebar_position: 8
 slug: /ibc/light-clients/proposals
 ---
 

docs/docs/03-light-clients/01-developer-guide/08-setup.md → docs/docs/03-light-clients/01-developer-guide/09-setup.md

@@ -1,7 +1,7 @@
 ---
 title: Setup
 sidebar_label: Setup
-sidebar_position: 8
+sidebar_position: 9
 slug: /ibc/light-clients/setup
 ---
 

docs/docs/03-light-clients/04-wasm/03-integration.md

@@ -353,7 +353,7 @@ func CreateWasmUpgradeHandler(
 }
 ```
 
-Or alternatively the parameter can be updated via a governance proposal (see at the bottom of section [`Creating clients`](../01-developer-guide/08-setup.md#creating-clients) for an example of how to do this).
+Or alternatively the parameter can be updated via a governance proposal (see at the bottom of section [`Creating clients`](../01-developer-guide/09-setup.md#creating-clients) for an example of how to do this).
 
 ## Adding the module to the store
 

docs/docs/03-light-clients/04-wasm/07-contracts.md

@@ -52,10 +52,10 @@ pub enum QueryMsg {
 
 To learn what it is expected from the Wasm light client contract when processing each message, please read the corresponding section of the [Light client developer guide](../01-developer-guide/01-overview.md):
 
-- For `StatusMsg`, see the section [`Status` method](../01-developer-guide/02-client-state.md#status-method).
-- For `TimestampAtHeightMsg`, see the section [`GetTimestampAtHeight` method](../01-developer-guide/02-client-state.md#gettimestampatheight-method).
-- For `VerifyClientMessageMsg`, see the section [`VerifyClientMessage`](../01-developer-guide/04-updates-and-misbehaviour.md#verifyclientmessage).
-- For `CheckForMisbehaviourMsg`, see the section [`CheckForMisbehaviour` method](../01-developer-guide/02-client-state.md#checkformisbehaviour-method).
+- For `StatusMsg`, see the section [`Status` method](../01-developer-guide/03-client-state.md#status-method).
+- For `TimestampAtHeightMsg`, see the section [`GetTimestampAtHeight` method](../01-developer-guide/03-client-state.md#gettimestampatheight-method).
+- For `VerifyClientMessageMsg`, see the section [`VerifyClientMessage`](../01-developer-guide/05-updates-and-misbehaviour.md#verifyclientmessage).
+- For `CheckForMisbehaviourMsg`, see the section [`CheckForMisbehaviour` method](../01-developer-guide/03-client-state.md#checkformisbehaviour-method).
 
 ## `SudoMsg`
 
@@ -88,12 +88,12 @@ pub enum SudoMsg {
 
 To learn what it is expected from the Wasm light client contract when processing each message, please read the corresponding section of the [Light client developer guide](../01-developer-guide/01-overview.md):
 
-- For `UpdateStateMsg`, see the section [`UpdateState`](../01-developer-guide/04-updates-and-misbehaviour.md#updatestate).
-- For `UpdateStateOnMisbehaviourMsg`, see the section [`UpdateStateOnMisbehaviour`](../01-developer-guide/04-updates-and-misbehaviour.md#updatestateonmisbehaviour).
-- For `VerifyUpgradeAndUpdateStateMsg`, see the section [`GetTimestampAtHeight` method](../01-developer-guide/05-upgrades.md#implementing-verifyupgradeandupdatestate).
-- For `VerifyMembershipMsg`, see the section [`VerifyMembership` method](../01-developer-guide/02-client-state.md#verifymembership-method).
-- For `VerifyNonMembershipMsg`, see the section [`VerifyNonMembership` method](../01-developer-guide/02-client-state.md#verifynonmembership-method).
-- For `MigrateClientStoreMsg`, see the section [Implementing `CheckSubstituteAndUpdateState`](../01-developer-guide/07-proposals.md#implementing-checksubstituteandupdatestate).
+- For `UpdateStateMsg`, see the section [`UpdateState`](../01-developer-guide/05-updates-and-misbehaviour.md#updatestate).
+- For `UpdateStateOnMisbehaviourMsg`, see the section [`UpdateStateOnMisbehaviour`](../01-developer-guide/05-updates-and-misbehaviour.md#updatestateonmisbehaviour).
+- For `VerifyUpgradeAndUpdateStateMsg`, see the section [`GetTimestampAtHeight` method](../01-developer-guide/06-upgrades.md#implementing-verifyupgradeandupdatestate).
+- For `VerifyMembershipMsg`, see the section [`VerifyMembership` method](../01-developer-guide/03-client-state.md#verifymembership-method).
+- For `VerifyNonMembershipMsg`, see the section [`VerifyNonMembership` method](../01-developer-guide/03-client-state.md#verifynonmembership-method).
+- For `MigrateClientStoreMsg`, see the section [Implementing `CheckSubstituteAndUpdateState`](../01-developer-guide/08-proposals.md#implementing-checksubstituteandupdatestate).
 
 ### Migration
 

docs/docs/05-migrations/13-v8-to-v9.md

@@ -55,6 +55,29 @@ Please use the new functions `path.Setup`, `path.SetupClients`, `path.SetupConne
 
 The `ExportMetadata` interface function has been removed from the `ClientState` interface. Core IBC will export all key/value's within the 02-client store.  
 
+The `ZeroCustomFields` interface function has been removed from the `ClientState` interface.
+
+The following functions have also been removed from the `ClientState` interface: `Initialize`, `Status`, `GetLatestHeight`, `GetTimestampAtHeight`, `VerifyClientMessage`, `VerifyMembership`, `VerifyNonMembership`, `CheckForMisbehaviour`, `UpdateState`, `UpdateStateOnMisbehaviour`,  `CheckSubstituteAndUpdateState` and `VerifyUpgradeAndUpdateState`. ibc-go v9 decouples routing at the `02-client` layer from the light clients' encoding structure (i.e. every light client implementation of the `ClientState` interface is not used anymore to route the requests to the right light client at the `02-client` layer, instead a *light client module* is registered for every light client type and `02-client` routes the requests to the right light client module based on the client ID). Light client developers must implement the newly introduced `LightClientModule` interface and are encouraged to move the logic implemented in the functions of their light client's implementation of the `ClientState` interface to the equivalent function in the `LightClientModule` interface. The table below shows the equivalence between the `ClientState` interface functions that have been removed and the functions in the `LightClientModule` interface:
+
+|`ClientState` interface|`LightClientModule` interface|
+|-----------------------|-----------------------------|
+|`Initialize`                   |`Initialize`                 |
+|`Status`                       |`Status`                     |
+|`GetLatestHeight`              |`LatestHeight`               |
+|`GetTimestampAtHeight`         |`TimestampAtHeight`          |
+|`VerifyClientMessage`          |`VerifyClientMessage`        |
+|`VerifyMembership`             |`VerifyMembership`           |
+|`VerifyNonMembership`          |`VerifyNonMembership`        |
+|`CheckForMisbehaviour`         |`CheckForMisbehaviour`       |
+|`UpdateState`                  |`UpdateState`                |
+|`UpdateStateOnMisbehaviour`    |`UpdateStateOnMisbehaviour`  |
+|`CheckSubstituteAndUpdateState`|`RecoverClient`              |
+|`VerifyUpgradeAndUpdateState`  |`VerifyUpgradeAndUpdateState`|
+|`ExportMetadata`               |                             |
+|`ZeroCustomFields`             |                             |
+
+Please check also the [Light client developer guide](../03-light-clients/01-developer-guide/01-overview.md) for more information. The light client module implementation for `07-tendermint` may also be useful as reference.
+
 ### 07-tendermint
 
 The `IterateConsensusMetadata` function has been removed.