From 116982259f6f2859adc3600b3c9559c773afcf67 Mon Sep 17 00:00:00 2001 From: Cian Hatton Date: Mon, 5 Dec 2022 15:20:04 +0000 Subject: [PATCH 1/8] docs: adding docs for client state --- docs/ibc/light-clients/client-state.md | 61 +++++++++++++++++++++++++- 1 file changed, 60 insertions(+), 1 deletion(-) diff --git a/docs/ibc/light-clients/client-state.md b/docs/ibc/light-clients/client-state.md index cfb3805268f..cb5a2c74ded 100644 --- a/docs/ibc/light-clients/client-state.md +++ b/docs/ibc/light-clients/client-state.md @@ -1,3 +1,62 @@ \ No newline at end of file +--> + +# Implementing the ClientState interface + +Learn how to implement the [Client State](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L36) interface. + +### ClientType + +`ClientType() string` should return a unique string identifier of the light client. + +### GetLatestHeight + +`GetLatestHeight() Height` should return the latest block height. + +### Validate + +`Validate() error` should return an error if the given ClientState values are invalid. + +### Status + +`Status() Status` must return the status of the client. Only Active clients are allowed to process packets. All +possible Status types can be found [here](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go). + +### ZeroCustomFields + +`ZeroCustomFields() ClientState` should zero out any client customizable fields in client state. Ledger enforced +fields are maintained while all custom fields are zero values, this is [used to verify upgrades](https://github.com/cosmos/ibc-go/blob/main/modules/core/02-client/types/proposal.go#L120). + +### GetTimestampAtHeight + +`GetTimestampAtHeight` must return the timestamp for the consensus state associated with the provided block height. + +### Initialize + +Clients must validate the initial consensus state, and may store any client-specific metadata necessary +for correct light client operations in the `Initialize` function. + +`Initialize` gets called when a [client is created](https://github.com/cosmos/ibc-go/blob/main/modules/core/02-client/keeper/client.go#L32). + +### VerifyMembership + +`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. +The caller is expected to construct the full CommitmentPath from a CommitmentPrefix and a standardized path (as defined in ICS 24). + +### VerifyNonMembership + +`VerifyNonMembership` is a generic proof verification method which verifies the absence of a given CommitmentPath at a specified height. +The caller is expected to construct the full CommitmentPath from a CommitmentPrefix and a standardized path (as defined in ICS 24). + +### VerifyClientMessage + +VerifyClientMessage must verify a ClientMessage. A ClientMessage could be a Header, Misbehaviour, or batch update. +It must handle each type of ClientMessage appropriately. 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. + +### CheckForMisbehaviour + +Checks for evidence of a misbehaviour in Header or Misbehaviour type. It assumes the ClientMessage +has already been verified. From 44c11cfe472729a66f30529d76693d1c9ac74d2f Mon Sep 17 00:00:00 2001 From: Cian Hatton Date: Mon, 5 Dec 2022 16:05:37 +0000 Subject: [PATCH 2/8] docs: updating client-state docs --- docs/ibc/light-clients/client-state.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/ibc/light-clients/client-state.md b/docs/ibc/light-clients/client-state.md index cb5a2c74ded..0348ce8fa26 100644 --- a/docs/ibc/light-clients/client-state.md +++ b/docs/ibc/light-clients/client-state.md @@ -8,29 +8,31 @@ Learn how to implement the [Client State](https://github.com/cosmos/ibc-go/blob/ ### ClientType -`ClientType() string` should return a unique string identifier of the light client. +`ClientType` should return a unique string identifier of the light client. ### GetLatestHeight -`GetLatestHeight() Height` should return the latest block height. +`GetLatestHeight` should return the latest block height. ### Validate -`Validate() error` should return an error if the given ClientState values are invalid. +`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/main/modules/light-clients/07-tendermint/client_state.go#L111) +as a reference. ### Status -`Status() Status` must return the status of the client. Only Active clients are allowed to process packets. All +`Status` must return the status of the client. Only `Active` clients are allowed to process packets. All possible Status types can be found [here](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go). ### ZeroCustomFields -`ZeroCustomFields() ClientState` should zero out any client customizable fields in client state. Ledger enforced -fields are maintained while all custom fields are zero values, this is [used to verify upgrades](https://github.com/cosmos/ibc-go/blob/main/modules/core/02-client/types/proposal.go#L120). +`ZeroCustomFields` should return a copy of the light client with all client customizable fields with their zero value. It should not mutate the fields of the light client. +This method is used to [verify upgrades](https://github.com/cosmos/ibc-go/blob/main/modules/core/02-client/types/proposal.go#L120) and when [scheduling upgrades](https://github.com/cosmos/ibc-go/blob/main/modules/core/02-client/keeper/proposal.go#L82). ### GetTimestampAtHeight -`GetTimestampAtHeight` must return the timestamp for the consensus state associated with the provided block height. +`GetTimestampAtHeight` must return the timestamp for the consensus state associated with the provided height. ### Initialize @@ -41,12 +43,13 @@ for correct light client operations in the `Initialize` function. ### VerifyMembership -`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. -The caller is expected to construct the full CommitmentPath from a CommitmentPrefix and a standardized path (as defined in ICS 24). +`VerifyMembership` must verify the existence of a value at a given CommitmentPath at the specified height. +The caller of this function is expected to construct the full CommitmentPath from a CommitmentPrefix and a standardized +path (as defined in ICS 24). ### VerifyNonMembership -`VerifyNonMembership` is a generic proof verification method which verifies the absence of a given CommitmentPath at a specified height. +`VerifyNonMembership` must verify the absence of a given CommitmentPath at a specified height. The caller is expected to construct the full CommitmentPath from a CommitmentPrefix and a standardized path (as defined in ICS 24). ### VerifyClientMessage From d2d5ee9ce377fc2851432b22a488fd91a5c30912 Mon Sep 17 00:00:00 2001 From: Cian Hatton Date: Tue, 6 Dec 2022 11:32:00 +0000 Subject: [PATCH 3/8] docs: updating based on PR feedback --- docs/ibc/light-clients/client-state.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/ibc/light-clients/client-state.md b/docs/ibc/light-clients/client-state.md index 0348ce8fa26..dd93799d4f1 100644 --- a/docs/ibc/light-clients/client-state.md +++ b/docs/ibc/light-clients/client-state.md @@ -4,26 +4,27 @@ order: 2 # Implementing the ClientState interface -Learn how to implement the [Client State](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L36) interface. +Learn how to implement the [Client State](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/exported/client.go#L40) interface. ### ClientType -`ClientType` should return a unique string identifier of the light client. +`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: `ClientTypes-{N}` where `{N}` is the unique global nonce associated with a specific client. ### GetLatestHeight -`GetLatestHeight` should return the latest block height. +`GetLatestHeight` should return the latest block height that the client state represents. . ### Validate `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/main/modules/light-clients/07-tendermint/client_state.go#L111) +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-rc1/modules/light-clients/07-tendermint/types/client_state.go#L101) as a reference. ### Status `Status` must return the status of the client. Only `Active` clients are allowed to process packets. All -possible Status types can be found [here](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go). +possible Status types can be found [here](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/exported/client.go#L26-L36). ### ZeroCustomFields From 271ad1e16850a94e70aab0d49e4dd616b767b7cc Mon Sep 17 00:00:00 2001 From: Cian Hatton Date: Tue, 6 Dec 2022 12:42:18 +0000 Subject: [PATCH 4/8] docs: addressing PR feedback --- docs/ibc/light-clients/client-state.md | 37 +++++++++++++------------- 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/ibc/light-clients/client-state.md b/docs/ibc/light-clients/client-state.md index dd93799d4f1..9ebab3e691d 100644 --- a/docs/ibc/light-clients/client-state.md +++ b/docs/ibc/light-clients/client-state.md @@ -4,63 +4,64 @@ order: 2 # Implementing the ClientState interface -Learn how to implement the [Client State](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/exported/client.go#L40) interface. +Learn how to implement the [`Client State`](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/exported/client.go#L40) interface. -### ClientType +## `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: `ClientTypes-{N}` where `{N}` is the unique global nonce associated with a specific client. -### GetLatestHeight +## `GetLatestHeight` method `GetLatestHeight` should return the latest block height that the client state represents. . -### Validate +## `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-rc1/modules/light-clients/07-tendermint/types/client_state.go#L101) as a reference. -### Status +## `Status` method `Status` must return the status of the client. Only `Active` clients are allowed to process packets. All possible Status types can be found [here](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/exported/client.go#L26-L36). -### ZeroCustomFields +## `ZeroCustomFields` method `ZeroCustomFields` should return a copy of the light client with all client customizable fields with their zero value. It should not mutate the fields of the light client. -This method is used to [verify upgrades](https://github.com/cosmos/ibc-go/blob/main/modules/core/02-client/types/proposal.go#L120) and when [scheduling upgrades](https://github.com/cosmos/ibc-go/blob/main/modules/core/02-client/keeper/proposal.go#L82). +This method is used when [scheduling upgrades](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/02-client/keeper/proposal.go#L89). Upgrades are used to upgrade chain specific fields such as chainID and the unbonding period. +For more information about client upgrades see [the developer guide](../upgrades/developer-guide.md). -### GetTimestampAtHeight +## `GetTimestampAtHeight` method `GetTimestampAtHeight` must return the timestamp for the consensus state associated with the provided height. +This value is used to facilitate timeouts by checking that a timeout on a packet has passed or not. -### Initialize +## `Initialize` method Clients must validate the initial consensus state, and may store any client-specific metadata necessary for correct light client operations in the `Initialize` function. `Initialize` gets called when a [client is created](https://github.com/cosmos/ibc-go/blob/main/modules/core/02-client/keeper/client.go#L32). -### VerifyMembership +## `VerifyMembership` method -`VerifyMembership` must verify the existence of a value at a given CommitmentPath at the specified height. -The caller of this function is expected to construct the full CommitmentPath from a CommitmentPrefix and a standardized -path (as defined in ICS 24). +`VerifyMembership` must verify the existence of a value at a given CommitmentPath at the specified height. For more information about membership proofs +see [the proof docs](./proofs.md). -### VerifyNonMembership +## `VerifyNonMembership` method -`VerifyNonMembership` must verify the absence of a given CommitmentPath at a specified height. -The caller is expected to construct the full CommitmentPath from a CommitmentPrefix and a standardized path (as defined in ICS 24). +`VerifyNonMembership` must verify the absence of a value at a given CommitmentPath at a specified height. For more information about non membership proofs +see [the proof docs](./proofs.md). -### VerifyClientMessage +## `VerifyClientMessage` method VerifyClientMessage must verify a ClientMessage. A ClientMessage could be a Header, Misbehaviour, or batch update. It must handle each type of ClientMessage appropriately. 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. -### CheckForMisbehaviour +## `CheckForMisbehaviour` method Checks for evidence of a misbehaviour in Header or Misbehaviour type. It assumes the ClientMessage has already been verified. From c5fb774c120b15f2b1191b3afda9404b94378c1e Mon Sep 17 00:00:00 2001 From: Cian Hatton Date: Wed, 7 Dec 2022 11:12:57 +0000 Subject: [PATCH 5/8] docs: adding backtick to ClientState --- docs/ibc/light-clients/client-state.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ibc/light-clients/client-state.md b/docs/ibc/light-clients/client-state.md index 9ebab3e691d..9d747dd2846 100644 --- a/docs/ibc/light-clients/client-state.md +++ b/docs/ibc/light-clients/client-state.md @@ -2,7 +2,7 @@ order: 2 --> -# Implementing the ClientState interface +# Implementing the `ClientState` interface Learn how to implement the [`Client State`](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/exported/client.go#L40) interface. From 1468c654f85e6bd825acd8f60186a50ff7a3a26c Mon Sep 17 00:00:00 2001 From: Cian Hatton Date: Thu, 8 Dec 2022 10:57:40 +0000 Subject: [PATCH 6/8] docs: addressing PR feedback --- docs/ibc/light-clients/client-state.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/ibc/light-clients/client-state.md b/docs/ibc/light-clients/client-state.md index 9d747dd2846..af6ebb2c57f 100644 --- a/docs/ibc/light-clients/client-state.md +++ b/docs/ibc/light-clients/client-state.md @@ -9,11 +9,11 @@ Learn how to implement the [`Client State`](https://github.com/cosmos/ibc-go/blo ## `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: `ClientTypes-{N}` where `{N}` is the unique global nonce associated with a specific client. +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. . +`GetLatestHeight` should return the latest block height that the client state represents. ## `Validate` method @@ -23,24 +23,32 @@ as a reference. ## `Status` method -`Status` must return the status of the client. Only `Active` clients are allowed to process packets. All -possible Status types can be found [here](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/exported/client.go#L26-L36). +`Status` must return the status of the client. + +* An `Active` status indicates that clients are allowed to process packets. +* A `Frozen` status indicates that a client is not allowed to be used. +* An `Expired` status indicates that a client is not allowed to be used. +* An `Unknown` status indicates that there was an error in determining the status of a client. + +All possible Status types can be found [here](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/exported/client.go#L26-L36). + +This field is returned in the gRPC [QueryClientStatusResponse](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/02-client/types/query.pb.go#L665). ## `ZeroCustomFields` method `ZeroCustomFields` should return a copy of the light client with all client customizable fields with their zero value. It should not mutate the fields of the light client. -This method is used when [scheduling upgrades](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/02-client/keeper/proposal.go#L89). Upgrades are used to upgrade chain specific fields such as chainID and the unbonding period. +This method is used when [scheduling upgrades](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/02-client/keeper/proposal.go#L89). Upgrades are used to upgrade chain specific fields. +In the tendermint case, this may be the chainID or the unbonding period. For more information about client upgrades see [the developer guide](../upgrades/developer-guide.md). ## `GetTimestampAtHeight` method `GetTimestampAtHeight` must return the timestamp for the consensus state associated with the provided height. -This value is used to facilitate timeouts by checking that a timeout on a packet has passed or not. +This value is used to facilitate timeouts by checking the packet timeout timestamp against the returned value. ## `Initialize` method -Clients must validate the initial consensus state, and may store any client-specific metadata necessary -for correct light client operations in the `Initialize` function. +Clients must validate the initial consensus state, and may 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). From 8ad270b09da775606c95040a6858fbe2c29b9a40 Mon Sep 17 00:00:00 2001 From: Cian Hatton Date: Thu, 8 Dec 2022 10:59:17 +0000 Subject: [PATCH 7/8] docs: fixing grammar in docs --- docs/ibc/light-clients/client-state.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ibc/light-clients/client-state.md b/docs/ibc/light-clients/client-state.md index af6ebb2c57f..e81efe99b67 100644 --- a/docs/ibc/light-clients/client-state.md +++ b/docs/ibc/light-clients/client-state.md @@ -32,7 +32,7 @@ as a reference. All possible Status types can be found [here](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/exported/client.go#L26-L36). -This field is returned in the gRPC [QueryClientStatusResponse](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/02-client/types/query.pb.go#L665). +This field is returned by the gRPC [QueryClientStatusResponse](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/02-client/types/query.pb.go#L665) endpoint. ## `ZeroCustomFields` method From ff490ede63dac14f82f25a68cca5e4c80027cbb0 Mon Sep 17 00:00:00 2001 From: Cian Hatton Date: Thu, 8 Dec 2022 12:04:51 +0000 Subject: [PATCH 8/8] docs: addressing PR feedback --- docs/ibc/light-clients/client-state.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/ibc/light-clients/client-state.md b/docs/ibc/light-clients/client-state.md index e81efe99b67..cff2fd23f21 100644 --- a/docs/ibc/light-clients/client-state.md +++ b/docs/ibc/light-clients/client-state.md @@ -4,7 +4,7 @@ order: 2 # Implementing the `ClientState` interface -Learn how to implement the [`Client State`](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/exported/client.go#L40) interface. +Learn how to implement the [`ClientState`](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/exported/client.go#L40) interface. ## `ClientType` method @@ -25,10 +25,10 @@ as a reference. `Status` must return the status of the client. -* An `Active` status indicates that clients are allowed to process packets. -* A `Frozen` status indicates that a client is not allowed to be used. -* An `Expired` status indicates that a client is not allowed to be used. -* An `Unknown` status indicates that there was an error in determining the status of a client. +- An `Active` status indicates that clients are allowed to process packets. +- A `Frozen` status indicates that a client is not allowed to be used. +- An `Expired` status indicates that a client is not allowed to be used. +- An `Unknown` status indicates that there was an error in determining the status of a client. All possible Status types can be found [here](https://github.com/cosmos/ibc-go/blob/v6.0.0-rc1/modules/core/exported/client.go#L26-L36).