From 49bf1fed2d14a600923ed310f9556e0579a5d8bc Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Wed, 7 Dec 2022 16:35:20 +0100 Subject: [PATCH 01/14] adding client/consensus state and height docs --- docs/.vuepress/config.js | 2 +- docs/ibc/light-clients/overview.md | 44 +++++++++++++++++++++++++++++- 2 files changed, 44 insertions(+), 2 deletions(-) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index d89efb89ac6..cdc73d2166f 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -300,7 +300,7 @@ module.exports = { { title: "Overview", directory: false, - path: "/light-clients/overview.html", + path: "/ibc/light-clients/overview.html", }, { title: "ClientState", diff --git a/docs/ibc/light-clients/overview.md b/docs/ibc/light-clients/overview.md index 4e10266dfdb..9ee90feffdd 100644 --- a/docs/ibc/light-clients/overview.md +++ b/docs/ibc/light-clients/overview.md @@ -1,3 +1,45 @@ \ No newline at end of file +--> + +# Overview + +Learn how to build IBC lightclient modules and fulfill the interfaces required to integrate with core IBC. {synopsis} + +The following aims to provide a high level IBC lightclient module developer guide. The lifecycle of IBC lightclients are created and maintained by the core IBC `MsgServer` and the abstractions provided by the `02-client` submodule. A lightclient module developer is only required to implement the methods and fulfil the expectations of a defined set of interfaces. In ibc-go these interfaces reside within the `core/modules/exported` package. + +Throughout this guide the `07-tendermint` lightclient module may be referred to as a reference example. + +## Concepts and vocabulary + +This guide serves to be implementation specific with respect to ibc-go. Readers are expected to familiarize themselves with the IBC protocol specifications. +Please refer to the defintions outlined in [ICS-002 Client Semantics](https://github.com/cosmos/ibc/tree/main/spec/core/ics-002-client-semantics#Definitions). + +### ClientState + +ClientState is a term used to define the data structure which encapsulates opaque lightclient state. This refers to internal data that accommodate the semantics of a lightclient. This may be any arbitrary data such as: + +- Constraints used for client updates. +- Constraints used for misbehaviour detection. +- Constraints used for state verification. +- Constraints used for client upgrades. + +The `ClientState` type maintained within the lightclient module *must* implement the `ClientState` 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](./client-state.md). + +For reference, see the `07-tendermint` lightclient module's [`ClientState` defintion](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/proto/ibc/lightclients/tendermint/v1/tendermint.proto#L18). + +### ConsensusState + +ConsensusState is a term used to define the data structure which encapsulates consensus data at a particular point in time, i.e. a unique height or sequence number of a state machine. There must exist a single trusted `ConsensusState` for each height. `ConsensusState` generally contains a trusted root, validator set information and timestamp. + +For example, the `ConsensusState` of the `07-tendermint` lightclient module defines a trusted root 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 lightclient module *must* implement the `ConsensusState` interface defined in `core/modules/exported/client.go`. +The methods which make up this interface are detailed at a more granular level in the [ConsensusState section of this guide](./consensus-state.md). + +### Height + +Height defines a monotonically increasing sequence number which provides ordering of consensus state data persisted through updates. +IBC lightclient module developers are expected to use the concrete type provided by the `02-client` submodule. This implements the expectations required by the `Height` interface in `core/modules/exported/client.go`. + From a5acc189f8a229368d79386eb2ee6b9b3917b7f4 Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Wed, 7 Dec 2022 16:37:46 +0100 Subject: [PATCH 02/14] cleanup --- docs/ibc/light-clients/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ibc/light-clients/overview.md b/docs/ibc/light-clients/overview.md index 9ee90feffdd..8f19004028a 100644 --- a/docs/ibc/light-clients/overview.md +++ b/docs/ibc/light-clients/overview.md @@ -41,5 +41,5 @@ The methods which make up this interface are detailed at a more granular level i ### Height Height defines a monotonically increasing sequence number which provides ordering of consensus state data persisted through updates. -IBC lightclient module developers are expected to use the concrete type provided by the `02-client` submodule. This implements the expectations required by the `Height` interface in `core/modules/exported/client.go`. +IBC lightclient module developers are expected to use the concrete type provided by the `02-client` submodule. This implements the expectations required by the `Height` interface defined in `core/modules/exported/client.go`. From 77877f5e57395473a2f12c017fc5f31d9a71c624 Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Thu, 8 Dec 2022 12:25:55 +0100 Subject: [PATCH 03/14] rename lightclient -> light client --- docs/ibc/light-clients/overview.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/ibc/light-clients/overview.md b/docs/ibc/light-clients/overview.md index 8f19004028a..a2b91af1d99 100644 --- a/docs/ibc/light-clients/overview.md +++ b/docs/ibc/light-clients/overview.md @@ -4,11 +4,11 @@ order: 1 # Overview -Learn how to build IBC lightclient modules and fulfill the interfaces required to integrate with core IBC. {synopsis} +Learn how to build IBC light client modules and fulfill the interfaces required to integrate with core IBC. {synopsis} -The following aims to provide a high level IBC lightclient module developer guide. The lifecycle of IBC lightclients are created and maintained by the core IBC `MsgServer` and the abstractions provided by the `02-client` submodule. A lightclient module developer is only required to implement the methods and fulfil the expectations of a defined set of interfaces. In ibc-go these interfaces reside within the `core/modules/exported` package. +The following aims to provide a high level IBC light client module developer guide. The lifecycle of IBC light clients are created and maintained by the core IBC `MsgServer` and the abstractions provided by the `02-client` submodule. A light client module developer is only required to implement the methods and fulfil the expectations of a defined set of interfaces. In ibc-go these interfaces reside within the `core/modules/exported` package. -Throughout this guide the `07-tendermint` lightclient module may be referred to as a reference example. +Throughout this guide the `07-tendermint` light client module may be referred to as a reference example. ## Concepts and vocabulary @@ -17,29 +17,29 @@ Please refer to the defintions outlined in [ICS-002 Client Semantics](https://gi ### ClientState -ClientState is a term used to define the data structure which encapsulates opaque lightclient state. This refers to internal data that accommodate the semantics of a lightclient. This may be any arbitrary data such as: +ClientState is a term used to define the data structure which encapsulates opaque light client state. This refers to internal data that accommodate the semantics of a light client. This may be any arbitrary data such as: - Constraints used for client updates. - Constraints used for misbehaviour detection. - Constraints used for state verification. - Constraints used for client upgrades. -The `ClientState` type maintained within the lightclient module *must* implement the `ClientState` interface defined in `core/modules/exported/client.go`. +The `ClientState` type maintained within the light client module *must* implement the `ClientState` 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](./client-state.md). -For reference, see the `07-tendermint` lightclient module's [`ClientState` defintion](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/proto/ibc/lightclients/tendermint/v1/tendermint.proto#L18). +For reference, see the `07-tendermint` light client module's [`ClientState` defintion](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/proto/ibc/lightclients/tendermint/v1/tendermint.proto#L18). ### ConsensusState ConsensusState is a term used to define the data structure which encapsulates consensus data at a particular point in time, i.e. a unique height or sequence number of a state machine. There must exist a single trusted `ConsensusState` for each height. `ConsensusState` generally contains a trusted root, validator set information and timestamp. -For example, the `ConsensusState` of the `07-tendermint` lightclient module defines a trusted root 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. +For example, the `ConsensusState` of the `07-tendermint` light client module defines a trusted root 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 lightclient module *must* implement the `ConsensusState` interface defined in `core/modules/exported/client.go`. +The `ConsensusState` type maintained within the light client module *must* implement the `ConsensusState` interface defined in `core/modules/exported/client.go`. The methods which make up this interface are detailed at a more granular level in the [ConsensusState section of this guide](./consensus-state.md). ### Height Height defines a monotonically increasing sequence number which provides ordering of consensus state data persisted through updates. -IBC lightclient module developers are expected to use the concrete type provided by the `02-client` submodule. This implements the expectations required by the `Height` interface defined in `core/modules/exported/client.go`. +IBC light client module developers are expected to use the concrete type provided by the `02-client` submodule. This implements the expectations required by the `Height` interface defined in `core/modules/exported/client.go`. From c1f852f02cd5d1a46fb73c24b92b3c6f6e3b384d Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Thu, 8 Dec 2022 12:42:00 +0100 Subject: [PATCH 04/14] adding links --- docs/ibc/light-clients/overview.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/ibc/light-clients/overview.md b/docs/ibc/light-clients/overview.md index a2b91af1d99..31569ef1ca8 100644 --- a/docs/ibc/light-clients/overview.md +++ b/docs/ibc/light-clients/overview.md @@ -6,7 +6,7 @@ order: 1 Learn how to build IBC light client modules and fulfill the interfaces required to integrate with core IBC. {synopsis} -The following aims to provide a high level IBC light client module developer guide. The lifecycle of IBC light clients are created and maintained by the core IBC `MsgServer` and the abstractions provided by the `02-client` submodule. A light client module developer is only required to implement the methods and fulfil the expectations of a defined set of interfaces. In ibc-go these interfaces reside within the `core/modules/exported` package. +The following aims to provide a high level IBC light client module developer guide. Access to IBC light clients are gated by the core IBC `MsgServer` which utilizes the abstractions set by the `02-client` submodule to call into a light client module. A light client module developer is only required to implement the [`ClientState`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L36) and [`ConsensusState`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L134) interfaces as defined in the `core/modules/exported` package. Throughout this guide the `07-tendermint` light client module may be referred to as a reference example. @@ -24,7 +24,7 @@ ClientState is a term used to define the data structure which encapsulates opaqu - Constraints used for state verification. - Constraints used for client upgrades. -The `ClientState` type maintained within the light client module *must* implement the `ClientState` interface defined in `core/modules/exported/client.go`. +The `ClientState` type maintained within the light client module *must* implement the [`ClientState`]((https://github.com/cosmos/ibc-go/blob/main/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](./client-state.md). For reference, see the `07-tendermint` light client module's [`ClientState` defintion](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/proto/ibc/lightclients/tendermint/v1/tendermint.proto#L18). @@ -35,7 +35,7 @@ ConsensusState is a term used to define the data structure which encapsulates co For example, the `ConsensusState` of the `07-tendermint` light client module defines a trusted root 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` interface defined in `core/modules/exported/client.go`. +The `ConsensusState` type maintained within the light client module *must* implement the [`ConsensusState`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L134) interface defined in `core/modules/exported/client.go`. The methods which make up this interface are detailed at a more granular level in the [ConsensusState section of this guide](./consensus-state.md). ### Height From 6a932936bad2348e6489c829e2bc786b7530d656 Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Thu, 8 Dec 2022 16:02:24 +0100 Subject: [PATCH 05/14] adding client message section, updates re. feedback --- docs/ibc/light-clients/overview.md | 34 ++++++++++++++++++++++++------ 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/docs/ibc/light-clients/overview.md b/docs/ibc/light-clients/overview.md index 31569ef1ca8..d1f3a40ebc2 100644 --- a/docs/ibc/light-clients/overview.md +++ b/docs/ibc/light-clients/overview.md @@ -6,18 +6,28 @@ order: 1 Learn how to build IBC light client modules and fulfill the interfaces required to integrate with core IBC. {synopsis} -The following aims to provide a high level IBC light client module developer guide. Access to IBC light clients are gated by the core IBC `MsgServer` which utilizes the abstractions set by the `02-client` submodule to call into a light client module. A light client module developer is only required to implement the [`ClientState`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L36) and [`ConsensusState`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L134) interfaces as defined in the `core/modules/exported` package. + +## Pre-requisites Readings + +- [IBC Overview](../overview.md)) {prereq} +- [IBC Transport, Authentication, and Ordering Layer - Clients](https://tutorials.cosmos.network/academy/3-ibc/4-clients.html) {prereq} +- [ICS-002 Client Semantics](https://github.com/cosmos/ibc/tree/main/spec/core/ics-002-client-semantics) {prereq} + +The following aims to provide a high level IBC light client module developer guide. Access to IBC light clients are gated by the core IBC `MsgServer` which utilizes the abstractions set by the `02-client` submodule to call into a light client module. A light client module developer is only required to implement a set interfaces as defined in the `core/modules/exported` package of ibc-go. + +A light client module developer should be concerned with three main interfaces: + +- [`ClientState`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L36) encapsulates the light client implementation and its semantics. +- [`ConsensusState`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L134) tracks critical consensus data used for verification of client updates and proof verification of counterparty state. +- [`ClientMessage`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L148) used for submitting block headers for client updates and submission of misbehaviour evidence using conflicting headers. Throughout this guide the `07-tendermint` light client module may be referred to as a reference example. ## Concepts and vocabulary -This guide serves to be implementation specific with respect to ibc-go. Readers are expected to familiarize themselves with the IBC protocol specifications. -Please refer to the defintions outlined in [ICS-002 Client Semantics](https://github.com/cosmos/ibc/tree/main/spec/core/ics-002-client-semantics#Definitions). - ### ClientState -ClientState is a term used to define the data structure which encapsulates opaque light client state. This refers to internal data that accommodate the semantics of a light client. This may be any arbitrary data such as: +ClientState is a term used to define the data structure which encapsulates opaque light client state. This refers to internal data that form the rules concerning trust gaurantees and proof verification. This may be any arbitrary data such as: - Constraints used for client updates. - Constraints used for misbehaviour detection. @@ -40,6 +50,18 @@ The methods which make up this interface are detailed at a more granular level i ### Height -Height defines a monotonically increasing sequence number which provides ordering of consensus state data persisted through updates. +Height defines a monotonically increasing sequence number which provides ordering of consensus state data persisted through client updates. IBC light client module developers are expected to use the concrete type provided by the `02-client` submodule. This implements the expectations required by the `Height` interface defined in `core/modules/exported/client.go`. +### ClientMessage + +ClientMessage refers to the interface type [`ClientMessage`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L148) used for performing updates to a `ClientState` stored on chain. +This may be any concrete type which produces a change in state to the IBC client when verified. + +The following are considered as valid update scenarios: + +- A block header which when verified inserts a new `ConsensusState` at a particular height for a given client. +- 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 client updates](./update.md) and [handling misbehaviour](./misbehaviour.md) sections. From 7fc85949aa3642d4ba125417e4c124691c23e380 Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Thu, 8 Dec 2022 16:07:56 +0100 Subject: [PATCH 06/14] fix wording --- docs/ibc/light-clients/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ibc/light-clients/overview.md b/docs/ibc/light-clients/overview.md index d1f3a40ebc2..a50f6e2b364 100644 --- a/docs/ibc/light-clients/overview.md +++ b/docs/ibc/light-clients/overview.md @@ -60,7 +60,7 @@ This may be any concrete type which produces a change in state to the IBC client The following are considered as valid update scenarios: -- A block header which when verified inserts a new `ConsensusState` at a particular height for a given client. +- A block header which when verified inserts a new `ConsensusState` at a unique height. - 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. From b0a400964fa0cd89ead0e2e3f013b2c9b8eb5680 Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Fri, 9 Dec 2022 12:11:31 +0100 Subject: [PATCH 07/14] adding brief one liner intro, various minor changes --- docs/ibc/light-clients/overview.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/ibc/light-clients/overview.md b/docs/ibc/light-clients/overview.md index a50f6e2b364..20810407d7e 100644 --- a/docs/ibc/light-clients/overview.md +++ b/docs/ibc/light-clients/overview.md @@ -13,12 +13,14 @@ Learn how to build IBC light client modules and fulfill the interfaces required - [IBC Transport, Authentication, and Ordering Layer - Clients](https://tutorials.cosmos.network/academy/3-ibc/4-clients.html) {prereq} - [ICS-002 Client Semantics](https://github.com/cosmos/ibc/tree/main/spec/core/ics-002-client-semantics) {prereq} +IBC uses light clients in order to provide trust-minimized interoperability between sovereign blockchains. Light clients operate under a strict set of rules which provide security guarantees for state updates and facilitate the ability to verify the state of a remote blockchain using merkle proofs. + The following aims to provide a high level IBC light client module developer guide. Access to IBC light clients are gated by the core IBC `MsgServer` which utilizes the abstractions set by the `02-client` submodule to call into a light client module. A light client module developer is only required to implement a set interfaces as defined in the `core/modules/exported` package of ibc-go. A light client module developer should be concerned with three main interfaces: - [`ClientState`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L36) encapsulates the light client implementation and its semantics. -- [`ConsensusState`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L134) tracks critical consensus data used for verification of client updates and proof verification of counterparty state. +- [`ConsensusState`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L134) tracks consensus data used for verification of client updates, misbehaviour detection and proof verification of counterparty state. - [`ClientMessage`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L148) used for submitting block headers for client updates and submission of misbehaviour evidence using conflicting headers. Throughout this guide the `07-tendermint` light client module may be referred to as a reference example. @@ -27,7 +29,7 @@ Throughout this guide the `07-tendermint` light client module may be referred to ### ClientState -ClientState is a term used to define the data structure which encapsulates opaque light client state. This refers to internal data that form the rules concerning trust gaurantees and proof verification. This may be any arbitrary data such as: +ClientState is a term used to define the data structure which encapsulates opaque light client state. This refers to chain specific and light client specific information that form the rules concerning trust gaurantees and proof verification. This may be any arbitrary data such as: - Constraints used for client updates. - Constraints used for misbehaviour detection. @@ -37,7 +39,7 @@ ClientState is a term used to define the data structure which encapsulates opaqu The `ClientState` type maintained within the light client module *must* implement the [`ClientState`]((https://github.com/cosmos/ibc-go/blob/main/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](./client-state.md). -For reference, see the `07-tendermint` light client module's [`ClientState` defintion](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/proto/ibc/lightclients/tendermint/v1/tendermint.proto#L18). +For example, see the `07-tendermint` light client module's [`ClientState` defintion](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/proto/ibc/lightclients/tendermint/v1/tendermint.proto#L18) containing information such as chain ID, status, latest height, unbonding period and proof specifications. ### ConsensusState From 080229dabbc495aef97692cf5f2a721c3c2fc823 Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Fri, 9 Dec 2022 12:12:32 +0100 Subject: [PATCH 08/14] removing comment --- docs/ibc/light-clients/overview.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/ibc/light-clients/overview.md b/docs/ibc/light-clients/overview.md index 20810407d7e..588e66d7c68 100644 --- a/docs/ibc/light-clients/overview.md +++ b/docs/ibc/light-clients/overview.md @@ -6,7 +6,6 @@ order: 1 Learn how to build IBC light client modules and fulfill the interfaces required to integrate with core IBC. {synopsis} - ## Pre-requisites Readings - [IBC Overview](../overview.md)) {prereq} From e2d1ef1185d364794d8ba5dd6ff76d3e595d8e15 Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Fri, 9 Dec 2022 12:18:28 +0100 Subject: [PATCH 09/14] fixing spelling --- docs/ibc/light-clients/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ibc/light-clients/overview.md b/docs/ibc/light-clients/overview.md index 588e66d7c68..ab2d1f0c020 100644 --- a/docs/ibc/light-clients/overview.md +++ b/docs/ibc/light-clients/overview.md @@ -28,7 +28,7 @@ Throughout this guide the `07-tendermint` light client module may be referred to ### ClientState -ClientState is a term used to define the data structure which encapsulates opaque light client state. This refers to chain specific and light client specific information that form the rules concerning trust gaurantees and proof verification. This may be any arbitrary data such as: +ClientState is a term used to define the data structure which encapsulates opaque light client state. This refers to chain specific and light client specific information that form the rules concerning trust guarantees and proof verification. This may be any arbitrary data such as: - Constraints used for client updates. - Constraints used for misbehaviour detection. From a2010d924d948915f2315b8c4049adbc1ef7bcf4 Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Fri, 9 Dec 2022 12:24:37 +0100 Subject: [PATCH 10/14] correct wording --- docs/ibc/light-clients/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ibc/light-clients/overview.md b/docs/ibc/light-clients/overview.md index ab2d1f0c020..850beae1ce5 100644 --- a/docs/ibc/light-clients/overview.md +++ b/docs/ibc/light-clients/overview.md @@ -44,7 +44,7 @@ For example, see the `07-tendermint` light client module's [`ClientState` defint ConsensusState is a term used to define the data structure which encapsulates consensus data at a particular point in time, i.e. a unique height or sequence number of a state machine. There must exist a single trusted `ConsensusState` for each height. `ConsensusState` generally contains a trusted root, validator set information and timestamp. -For example, the `ConsensusState` of the `07-tendermint` light client module defines a trusted root 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. +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/blob/main/modules/core/exported/client.go#L134) interface defined in `core/modules/exported/client.go`. The methods which make up this interface are detailed at a more granular level in the [ConsensusState section of this guide](./consensus-state.md). From f0ca3a97c2f75809f9d21beddc83dd5dbb166af1 Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Thu, 15 Dec 2022 17:07:38 +0000 Subject: [PATCH 11/14] docs: lightclient dev guide setup and client creation (#2922) * adding setup page for configuring light client modules and creation of ibc clients * updating page ordering * pr review suggestions * use 02-client-refactor-beta tag in favour of commit hash links * add link to issue for self managed params * Update docs/ibc/light-clients/client-state.md Co-authored-by: Charly Co-authored-by: Charly --- docs/.vuepress/config.js | 9 +- docs/ibc/light-clients/client-state.md | 3 +- docs/ibc/light-clients/genesis.md | 2 +- docs/ibc/light-clients/proofs.md | 2 +- docs/ibc/light-clients/proposal.md | 2 +- docs/ibc/light-clients/setup.md | 121 +++++++++++++++++++++++++ docs/ibc/light-clients/upgrade.md | 2 +- 7 files changed, 133 insertions(+), 8 deletions(-) create mode 100644 docs/ibc/light-clients/setup.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 5ab94844910..f236fabc371 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -349,9 +349,9 @@ module.exports = { path: "/ibc/light-clients/consensus-state.html", }, { - title: "Existence/Non-Existence Proofs", + title: "Setup", directory: false, - path: "/ibc/light-clients/proofs.html", + path: "/ibc/light-clients/setup.html", }, { title: "Updates Handling", @@ -363,6 +363,11 @@ module.exports = { directory: false, path: "/ibc/light-clients/misbehaviour.html", }, + { + title: "Existence/Non-Existence Proofs", + directory: false, + path: "/ibc/light-clients/proofs.html", + }, { title: "Upgrades Handling", directory: false, diff --git a/docs/ibc/light-clients/client-state.md b/docs/ibc/light-clients/client-state.md index fa32e90fe8a..7035512b387 100644 --- a/docs/ibc/light-clients/client-state.md +++ b/docs/ibc/light-clients/client-state.md @@ -18,8 +18,7 @@ The format is created as follows: `ClientType-{N}` where `{N}` is the unique glo ## `Validate` method `Validate` should validate every client state field and should return an error if any value is invalid. The light client -implementor is in charge of determining which checks are required. See the [tendermint light client implementation](https://github.com/cosmos/ibc-go/blob/v6.0.0/modules/light-clients/07-tendermint/types/client_state.go#L101) -as a reference. +implementer is in charge of determining which checks are required. See the [tendermint light client implementation](https://github.com/cosmos/ibc-go/blob/v6.0.0/modules/light-clients/07-tendermint/types/client_state.go#L101) as a reference. ## `Status` method diff --git a/docs/ibc/light-clients/genesis.md b/docs/ibc/light-clients/genesis.md index 695231196ad..5c631dc6d60 100644 --- a/docs/ibc/light-clients/genesis.md +++ b/docs/ibc/light-clients/genesis.md @@ -1,3 +1,3 @@ \ No newline at end of file diff --git a/docs/ibc/light-clients/proofs.md b/docs/ibc/light-clients/proofs.md index 197c44cbc2b..cf8eae46ed7 100644 --- a/docs/ibc/light-clients/proofs.md +++ b/docs/ibc/light-clients/proofs.md @@ -1,3 +1,3 @@ \ No newline at end of file diff --git a/docs/ibc/light-clients/proposal.md b/docs/ibc/light-clients/proposal.md index 1aa80c4f77e..695231196ad 100644 --- a/docs/ibc/light-clients/proposal.md +++ b/docs/ibc/light-clients/proposal.md @@ -1,3 +1,3 @@ \ No newline at end of file diff --git a/docs/ibc/light-clients/setup.md b/docs/ibc/light-clients/setup.md new file mode 100644 index 00000000000..8bb85b234af --- /dev/null +++ b/docs/ibc/light-clients/setup.md @@ -0,0 +1,121 @@ + + +# Setup + +Learn how to configure light client modules and create clients using core IBC and the `02-client` submodule. {synopsis} + +## Configuring a light client module + +An IBC light client module must implement the [`AppModuleBasic`](https://github.com/cosmos/cosmos-sdk/blob/main/types/module/module.go#L50) interface in order to register its concrete types against the core IBC interfaces defined in `modules/core/exported`. This is accomplished via the `RegisterInterfaces` method which provides the light client module with the opportunity to register codec types using the chain's `InterfaceRegistery`. Please refer to the [`07-tendermint` codec registration](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/codec.go#L11). + +The `AppModuleBasic` interface may also be leveraged to install custom CLI handlers for light client module users. Light client modules can safely no-op for interface methods which it does not wish to implement. + +Please refer to the [core IBC documentation](../integration.md#integrating-light-clients) for how to configure additional light client modules alongside `07-tendermint` in `app.go`. + +See below for an example of the `07-tendermint` implementation of `AppModuleBasic`. + +```go +var _ module.AppModuleBasic = AppModuleBasic{} + +// AppModuleBasic defines the basic application module used by the tendermint light client. +// Only the RegisterInterfaces function needs to be implemented. All other function perform +// a no-op. +type AppModuleBasic struct{} + +// Name returns the tendermint module name. +func (AppModuleBasic) Name() string { + return ModuleName +} + +// RegisterLegacyAminoCodec performs a no-op. The Tendermint client does not support amino. +func (AppModuleBasic) RegisterLegacyAminoCodec(*codec.LegacyAmino) {} + +// RegisterInterfaces registers module concrete types into protobuf Any. This allows core IBC +// to unmarshal tendermint light client types. +func (AppModuleBasic) RegisterInterfaces(registry codectypes.InterfaceRegistry) { + RegisterInterfaces(registry) +} + +// DefaultGenesis performs a no-op. Genesis is not supported for the tendermint light client. +func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage { + return nil +} + +// ValidateGenesis performs a no-op. Genesis is not supported for the tendermint light cilent. +func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, config client.TxEncodingConfig, bz json.RawMessage) error { + return nil +} + +// RegisterGRPCGatewayRoutes performs a no-op. +func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux) {} + +// GetTxCmd performs a no-op. Please see the 02-client cli commands. +func (AppModuleBasic) GetTxCmd() *cobra.Command { + return nil +} + +// GetQueryCmd performs a no-op. Please see the 02-client cli commands. +func (AppModuleBasic) GetQueryCmd() *cobra.Command { + return nil +} +``` + +## Creating clients + +A client is created by executing a new `MsgCreateClient` transaction composed with a valid `ClientState` and initial `ConsensusState` encoded as protobuf `Any`s. +Generally, this is normally done by an off-chain process known as an [IBC relayer](https://github.com/cosmos/ibc/tree/main/spec/relayer/ics-018-relayer-algorithms) however, this is not a strict requirement. + +See below for a list of IBC relayer implementations: + +- [cosmos/relayer](https://github.com/cosmos/relayer) +- [informalsystems/hermes](https://github.com/informalsystems/hermes) +- [confio/ts-relayer](https://github.com/confio/ts-relayer) + +Stateless checks are performed within the [`ValidateBasic`](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/core/02-client/types/msgs.go#L48) method of `MsgCreateClient`. + +```protobuf +// MsgCreateClient defines a message to create an IBC client +message MsgCreateClient { + option (gogoproto.equal) = false; + option (gogoproto.goproto_getters) = false; + + // light client state + google.protobuf.Any client_state = 1 [(gogoproto.moretags) = "yaml:\"client_state\""]; + // consensus state associated with the client that corresponds to a given + // height. + google.protobuf.Any consensus_state = 2 [(gogoproto.moretags) = "yaml:\"consensus_state\""]; + // signer address + string signer = 3; +} +``` + +Leveraging protobuf `Any` encoding allows core IBC to [unpack](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/core/keeper/msg_server.go#L28-L36) both the `ClientState` and `ConsensusState` into their respective interface types registered previously using the light client module's `RegisterInterfaces` method. + +Within the `02-client` submodule, the [`ClientState` is then initialized](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/core/02-client/keeper/client.go#L30-L34) with its own isolated key-value store, namespaced using a unique client identifier. + +In order to successfully create an IBC client using a new client type it [must be supported](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/core/02-client/keeper/client.go#L18-L24). Light client support in IBC is gated by on-chain governance. The allow list may be updated by submitting a new governance proposal to update the `02-client` parameter `AllowedClients`. + + +See below for example: + +``` +$ %s tx gov submit-proposal param-change --from= +Where proposal.json contains: +{ + "title": "IBC Clients Param Change", + "description": "Update allowed clients", + "changes": [ + { + "subspace": "ibc", + "key": "AllowedClients", + "value": ["06-solomachine", "07-tendermint", "0x-new-client"] + } + ], + "deposit": "1000stake" +} +``` diff --git a/docs/ibc/light-clients/upgrade.md b/docs/ibc/light-clients/upgrade.md index cf8eae46ed7..1aa80c4f77e 100644 --- a/docs/ibc/light-clients/upgrade.md +++ b/docs/ibc/light-clients/upgrade.md @@ -1,3 +1,3 @@ \ No newline at end of file From e46cdaaf79a697564c3fb18dab24ec971e8af549 Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Thu, 15 Dec 2022 17:46:32 +0000 Subject: [PATCH 12/14] review updates --- docs/ibc/light-clients/overview.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/ibc/light-clients/overview.md b/docs/ibc/light-clients/overview.md index 850beae1ce5..5a8597a5ae4 100644 --- a/docs/ibc/light-clients/overview.md +++ b/docs/ibc/light-clients/overview.md @@ -18,9 +18,9 @@ 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: -- [`ClientState`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L36) encapsulates the light client implementation and its semantics. -- [`ConsensusState`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L134) tracks consensus data used for verification of client updates, misbehaviour detection and proof verification of counterparty state. -- [`ClientMessage`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L148) used for submitting block headers for client updates and submission of misbehaviour evidence using conflicting headers. +- [`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. Throughout this guide the `07-tendermint` light client module may be referred to as a reference example. @@ -28,17 +28,17 @@ Throughout this guide the `07-tendermint` light client module may be referred to ### ClientState -ClientState is a term used to define the data structure which encapsulates opaque light client state. This refers to chain specific and light client specific information that form the rules concerning trust guarantees and proof verification. This may be any arbitrary data such as: +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. - Constraints used for client updates. - Constraints used for misbehaviour detection. - Constraints used for state verification. - Constraints used for client upgrades. -The `ClientState` type maintained within the light client module *must* implement the [`ClientState`]((https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L36)) interface defined in `core/modules/exported/client.go`. +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](./client-state.md). -For example, see the `07-tendermint` light client module's [`ClientState` defintion](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/proto/ibc/lightclients/tendermint/v1/tendermint.proto#L18) containing information such as chain ID, status, latest height, unbonding period and proof specifications. +For example, see the `07-tendermint` light client module's [`ClientState` defintion](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. ### ConsensusState @@ -46,17 +46,17 @@ ConsensusState is a term used to define the data structure which encapsulates co 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/blob/main/modules/core/exported/client.go#L134) interface defined in `core/modules/exported/client.go`. +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 `core/modules/exported/client.go`. The methods which make up this interface are detailed at a more granular level in the [ConsensusState section of this guide](./consensus-state.md). ### Height Height defines a monotonically increasing sequence number which provides ordering of consensus state data persisted through client updates. -IBC light client module developers are expected to use the concrete type provided by the `02-client` submodule. This implements the expectations required by the `Height` interface defined in `core/modules/exported/client.go`. +IBC light client module developers are expected to use the [concrete type](https://github.com/cosmos/ibc-go/tree/02-client-refactor-beta1/proto/ibc/core/client/v1/client.proto#L89) provided by the `02-client` submodule. This implements the expectations required by the `Height` interface defined in `core/modules/exported/client.go`. ### ClientMessage -ClientMessage refers to the interface type [`ClientMessage`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L148) used for performing updates to a `ClientState` stored on chain. +ClientMessage refers to the interface type [`ClientMessage`](https://github.com/cosmos/ibc-go/tree/02-client-refactor-beta1/modules/core/exported/client.go#L148) used for performing updates to a `ClientState` stored on chain. This may be any concrete type which produces a change in state to the IBC client when verified. The following are considered as valid update scenarios: From 53b2f9528c37c9eb92559f38bcc00ab1e3bb26ce Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Thu, 15 Dec 2022 17:50:22 +0000 Subject: [PATCH 13/14] clean up --- docs/ibc/light-clients/overview.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/ibc/light-clients/overview.md b/docs/ibc/light-clients/overview.md index 5a8597a5ae4..950b8207f24 100644 --- a/docs/ibc/light-clients/overview.md +++ b/docs/ibc/light-clients/overview.md @@ -30,6 +30,8 @@ Throughout this guide the `07-tendermint` light client module may be referred to 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. +For example: + - Constraints used for client updates. - Constraints used for misbehaviour detection. - Constraints used for state verification. @@ -38,7 +40,7 @@ ClientState is a term used to define the data structure which encapsulates opaqu 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](./client-state.md). -For example, see the `07-tendermint` light client module's [`ClientState` defintion](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. +Please refer to the `07-tendermint` light client module's [`ClientState` defintion](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. ### ConsensusState From 3b0945dd00fc018875a445d405ff6ebc695adb1c Mon Sep 17 00:00:00 2001 From: Charly Date: Tue, 20 Dec 2022 15:01:53 +0100 Subject: [PATCH 14/14] docs: update consensus state docs (#2937) --- docs/ibc/light-clients/consensus-state.md | 20 +++++++++++++++++++- docs/ibc/light-clients/proofs.md | 4 ++++ docs/ibc/light-clients/update.md | 19 +++++++++++++++++-- 3 files changed, 40 insertions(+), 3 deletions(-) diff --git a/docs/ibc/light-clients/consensus-state.md b/docs/ibc/light-clients/consensus-state.md index 04de84a83d6..ebde1e8cbbe 100644 --- a/docs/ibc/light-clients/consensus-state.md +++ b/docs/ibc/light-clients/consensus-state.md @@ -1,3 +1,21 @@ \ No newline at end of file +--> + +# Implementing the `ConsensusState` interface + +A `ConsensusState` is the snapshot of the counterparty chain that an IBC client uses to verify proofs (e.g. a block). The further development of multiple types of IBC light clients and the difficulties presented by this generalization problem (see [ADR-006](https://github.com/cosmos/ibc-go/blob/main/docs/architecture/adr-006-02-client-refactor.md) for more information about this historical context) led to the design decision of each client keeping track of and set its own `ClientState` and `ConsensusState`, as well as the simplification of client `ConsensusState` updates through the generalized `ClientMessage` interface. + +The below [`ConsensusState`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L134) interface is a generalized interface for the types of information a `ConsensusState` could contain. For a reference `ConsensusState` implementation, please see the [Tendermint light client `ConsensusState`](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/07-tendermint/consensus_state.go). + +## `ClientType` method + +This is the type of client consensus. It should be the same as the `ClientType` return value for the [corresponding `ClientState` implementation](./client-state.md). + +## `GetTimestamp` method + +`GetTimestamp` should return the timestamp (in nanoseconds) of the consensus state snapshot. + +## `ValidateBasic` method + +`ValidateBasic` should validate every consensus 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. \ No newline at end of file diff --git a/docs/ibc/light-clients/proofs.md b/docs/ibc/light-clients/proofs.md index cf8eae46ed7..89253b73518 100644 --- a/docs/ibc/light-clients/proofs.md +++ b/docs/ibc/light-clients/proofs.md @@ -1,3 +1,7 @@ \ No newline at end of file diff --git a/docs/ibc/light-clients/update.md b/docs/ibc/light-clients/update.md index ff7a3c6ce6b..61bb3840533 100644 --- a/docs/ibc/light-clients/update.md +++ b/docs/ibc/light-clients/update.md @@ -1,3 +1,18 @@ \ No newline at end of file +order: 4 +--> + +# Implementing the `ClientMessage` interface + +As mentioned before in the documentation about [implementing the `ConsensusState` interface](./consensus-state.md), [`ClientMessage`](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L145) is an interface used to update an IBC client. This update may be done by a single header, a batch of headers, misbehaviour, or any type which when verified produces a change to the consensus state of the IBC client. This interface has been purposefully kept generic in order to give the maximum amount of flexibility to the light client implementer. + +```golang +type ClientMessage interface { + proto.Message + + ClientType() string + ValidateBasic() error +} +``` + +The `ClientMessage` will be passed to the client to be used in [`UpdateClient`](https://github.com/cosmos/ibc-go/blob/57da75a70145409247e85365b64a4b2fc6ddad2f/modules/core/02-client/keeper/client.go#L53), which will handle a number of cases including misbehaviour and/or updating the consensus state. However, this `UpdateClient` function will always reference the specific functions determined by the relevant `ClientState`. This is because `UpdateClient` retrieves the client state by client ID (available in `MsgUpdateClient`). This client state implements the `ClientState` interface for a specific client type (e.g. Tendermint). The functions called on the client state instance in `UpdateClient` will be the specific implementations of `VerifyClientMessage`, `CheckForMisbehaviour`, `UpdateStateOnMisbehaviour` and `UpdateState` functions of the `ClientState` interface for that particular client type. \ No newline at end of file