Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update consensus state docs #2937

Merged
merged 10 commits into from
Dec 20, 2022
36 changes: 35 additions & 1 deletion docs/ibc/light-clients/consensus-state.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,37 @@
<!--
order: 3
-->
-->

# Implementing the `ConsensusState` and `ClientMessage` interfaces

A `ConsensusState` is the snapshot of the counterparty chain that an IBC client uses to verify proofs. 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.
charleenfei marked this conversation as resolved.
Show resolved Hide resolved

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
GetTimestamp should return the timestamp (in nanoseconds) of the consensus state snapshot.
`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.

charleenfei marked this conversation as resolved.
Show resolved Hide resolved

# Implementing the `ClientMessage` interface
charleenfei marked this conversation as resolved.
Show resolved Hide resolved

As mentioned above, [`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`. For example, a `ClientMessage` referencing the Tendermint `ClientType` will then trigger the Tendermint `VerifyClientMessage`, `CheckForMisbehaviour`, and `UpdateState` functions found in the Tendermint `ClientState` implementation.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a suggestion, but I think I would explain this line

a ClientMessage referencing the Tendermint ClientType will then trigger

a bit differently: 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.

Just an idea!