From 835a5bcbc0b2cafe7cff4b39d2602f829f4b2597 Mon Sep 17 00:00:00 2001 From: crodriguezvega Date: Wed, 25 Jan 2023 21:32:01 +0100 Subject: [PATCH 01/27] docs: light client developer guide updates --- .../adr-001-coin-source-tracing.md | 18 +++++----- docs/dev/go-style-guide.md | 4 +-- docs/ibc/integration.md | 15 +++++---- docs/ibc/light-clients/client-state.md | 24 +++++++------- docs/ibc/light-clients/overview.md | 20 +++++------ docs/ibc/light-clients/proofs.md | 18 +++++----- docs/ibc/light-clients/proposal.md | 4 +-- docs/ibc/light-clients/setup.md | 12 ++++--- docs/ibc/light-clients/update.md | 2 +- .../light-clients/updates-and-misbehaviour.md | 33 +++++++++---------- docs/ibc/light-clients/upgrade.md | 28 ++++++++-------- 11 files changed, 91 insertions(+), 87 deletions(-) diff --git a/docs/architecture/adr-001-coin-source-tracing.md b/docs/architecture/adr-001-coin-source-tracing.md index 4aeb59aecab..94a9c86de63 100644 --- a/docs/architecture/adr-001-coin-source-tracing.md +++ b/docs/architecture/adr-001-coin-source-tracing.md @@ -114,7 +114,7 @@ trace the token back to the originating chain, as specified on ICS20. The new proposed format will be the following: -```golang +```go ibcDenom = "ibc/" + hash(trace path + "/" + base denom) ``` @@ -133,7 +133,7 @@ message DenomTrace { The `IBCDenom` function constructs the `Coin` denomination used when creating the ICS20 fungible token packet data: -```golang +```go // Hash returns the hex bytes of the SHA256 hash of the DenomTrace fields using the following formula: // // hash = sha256(tracePath + "/" + baseDenom) @@ -157,7 +157,7 @@ In order to retrieve the trace information from an IBC denomination, a lookup ta added to the `ibc-transfer` module. These values need to also be persisted between upgrades, meaning that a new `[]DenomTrace` `GenesisState` field state needs to be added to the module: -```golang +```go // GetDenomTrace retrieves the full identifiers trace and base denomination from the store. func (k Keeper) GetDenomTrace(ctx Context, denomTraceHash []byte) (DenomTrace, bool) { store := ctx.KVStore(k.storeKey) @@ -188,14 +188,14 @@ func (k Keeper) SetDenomTrace(ctx Context, denomTrace DenomTrace) { The `MsgTransfer` will validate that the `Coin` denomination from the `Token` field contains a valid hash, if the trace info is provided, or that the base denominations matches: -```golang +```go func (msg MsgTransfer) ValidateBasic() error { // ... return ValidateIBCDenom(msg.Token.Denom) } ``` -```golang +```go // ValidateIBCDenom validates that the given denomination is either: // // - A valid base denomination (eg: 'uatom') @@ -226,7 +226,7 @@ The denomination trace info only needs to be updated when token is received: - Receiver is **source** chain: The receiver created the token and must have the trace lookup already stored (if necessary _ie_ native token case wouldn't need a lookup). - Receiver is **not source** chain: Store the received info. For example, during step 1, when chain `B` receives `transfer/channelToA/denom`. -```golang +```go // SendTransfer // ... @@ -245,7 +245,7 @@ if types.SenderChainIsSource(sourcePort, sourceChannel, fullDenomPath) { //... ``` -```golang +```go // DenomPathFromHash returns the full denomination path prefix from an ibc denom with a hash // component. func (k Keeper) DenomPathFromHash(ctx sdk.Context, denom string) (string, error) { @@ -266,7 +266,7 @@ func (k Keeper) DenomPathFromHash(ctx sdk.Context, denom string) (string, error) ``` -```golang +```go // OnRecvPacket // ... @@ -322,7 +322,7 @@ return k.bankKeeper.SendCoinsFromModuleToAccount( ) ``` -```golang +```go func NewDenomTraceFromRawDenom(denom string) DenomTrace{ denomSplit := strings.Split(denom, "/") trace := "" diff --git a/docs/dev/go-style-guide.md b/docs/dev/go-style-guide.md index f481c4bcd32..c45d677e603 100644 --- a/docs/dev/go-style-guide.md +++ b/docs/dev/go-style-guide.md @@ -71,7 +71,7 @@ Perhaps more key for code readability than good commenting is having the right s - Use [goimports](https://godoc.org/golang.org/x/tools/cmd/goimports). - Separate imports into blocks: one for the standard lib, one for external libs and one for application libs. For example: - ```golang + ```go import ( // standard library imports "fmt" @@ -105,7 +105,7 @@ Perhaps more key for code readability than good commenting is having the right s - Panic is appropriate when an internal invariant of a system is broken, while all other cases (in particular, incorrect or invalid usage) should return errors. - Error messages should be formatted as following: - ```golang + ```go sdkerrors.Wrapf( , "expected %s, got %s", diff --git a/docs/ibc/integration.md b/docs/ibc/integration.md index 61c2510588f..1e735df438c 100644 --- a/docs/ibc/integration.md +++ b/docs/ibc/integration.md @@ -16,7 +16,7 @@ Integrating the IBC module to your SDK-based application is straighforward. The - Add required modules to the `module.BasicManager` - Define additional `Keeper` fields for the new modules on the `App` type -- Add the module's `StoreKeys` and initialize their `Keepers` +- Add the module's `StoreKey`s and initialize their `Keeper`s - Set up corresponding routers and routes for the `ibc` module - Add the modules to the module `Manager` - Add modules to `Begin/EndBlockers` and `InitGenesis` @@ -28,10 +28,10 @@ The first step is to add the following modules to the `BasicManager`: `x/capabil and `x/ibc-transfer`. After that, we need to grant `Minter` and `Burner` permissions to the `ibc-transfer` `ModuleAccount` to mint and burn relayed tokens. -### Integrating Light Clients +### Integrating light clients > Note that from v7 onwards, all light clients have to be explicitly registered in a chain's app.go and follow the steps listed below. - This is in contrast to earlier versions of ibc-go when 07-tendermint and 06-solomachine were added out of the box. + This is in contrast to earlier versions of ibc-go when `07-tendermint` and `06-solomachine` were added out of the box. All light clients must be registered with `module.BasicManager` in a chain's app.go file. @@ -40,9 +40,9 @@ The following code example shows how to register the existing `ibctm.AppModuleBa ```diff import ( - ... -+ ibctm "github.com/cosmos/ibc-go/v6/modules/light-clients/07-tendermint" - ... + ... ++ ibctm "github.com/cosmos/ibc-go/v6/modules/light-clients/07-tendermint" + ... ) // app.go @@ -55,7 +55,7 @@ var ( transfer.AppModuleBasic{}, // i.e ibc-transfer module // register light clients on IBC -+ ibctm.AppModuleBasic{}, ++ ibctm.AppModuleBasic{}, ) // module account permissions @@ -63,6 +63,7 @@ var ( // other module accounts permissions // ... ibctransfertypes.ModuleName: {authtypes.Minter, authtypes.Burner}, + } ) ``` diff --git a/docs/ibc/light-clients/client-state.md b/docs/ibc/light-clients/client-state.md index 9ecfe891323..1ef5c1c75b8 100644 --- a/docs/ibc/light-clients/client-state.md +++ b/docs/ibc/light-clients/client-state.md @@ -18,26 +18,26 @@ 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 -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. +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 `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. +- A `Frozen` status indicates that misbehaviour was detected in the counterparty chain and the client is not allowed to be used. +- An `Expired` status indicates that a client is not allowed to be used because it was not updated for longer than the trusting period. - 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/modules/core/exported/client.go#L26-L36). +All possible `Status` types can be found [here](https://github.com/cosmos/ibc-go/blob/v6.0.0/modules/core/exported/client.go#L26-L36). -This field is returned by the gRPC [QueryClientStatusResponse](https://github.com/cosmos/ibc-go/blob/v6.0.0/modules/core/02-client/types/query.pb.go#L665) endpoint. +This field is returned in the response of the gRPC [`ibc.core.client.v1.Query/ClientStatus`](https://github.com/cosmos/ibc-go/blob/v6.0.0/modules/core/02-client/types/query.pb.go#L665) endpoint. ## `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/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. +In the tendermint case, this may be the chain ID or the unbonding period. For more information about client upgrades see [the developer guide](../upgrades/developer-guide.md). ## `GetTimestampAtHeight` method @@ -54,22 +54,22 @@ Clients may also store any necessary client-specific metadata. ## `VerifyMembership` method -`VerifyMembership` must verify the existence of a value at a given CommitmentPath at the specified height. For more information about membership proofs +`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 proof docs](./proofs.md). ## `VerifyNonMembership` method -`VerifyNonMembership` must verify the absence of a value at a given CommitmentPath at a specified height. For more information about non membership proofs +`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 proof docs](./proofs.md). ## `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 +`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` method -Checks for evidence of a misbehaviour in Header or Misbehaviour type. It assumes the ClientMessage +Checks for evidence of a misbehaviour in `Header` or `Misbehaviour` type. It assumes the `ClientMessage` has already been verified. diff --git a/docs/ibc/light-clients/overview.md b/docs/ibc/light-clients/overview.md index c8505603d21..afd791449b5 100644 --- a/docs/ibc/light-clients/overview.md +++ b/docs/ibc/light-clients/overview.md @@ -26,9 +26,9 @@ Throughout this guide the `07-tendermint` light client module may be referred to ## Concepts and vocabulary -### ClientState +### `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. +`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: @@ -40,25 +40,25 @@ For example: 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). -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. +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. -### ConsensusState +### `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. +`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 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 `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` -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](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`. +`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](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`](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/core/exported/client.go#L157) interface defined in `core/modules/exported/client.go`. -### ClientMessage +### `ClientMessage` -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. +`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: diff --git a/docs/ibc/light-clients/proofs.md b/docs/ibc/light-clients/proofs.md index 585511d9aee..801b99dda73 100644 --- a/docs/ibc/light-clients/proofs.md +++ b/docs/ibc/light-clients/proofs.md @@ -2,29 +2,29 @@ order: 8 --> -# Existence and Non-Existence Proofs +# Existence and non-existence proofs -IBC uses merkle proofs in order to verify the state of a remote counterparty state machine given a trusted root, and [ICS23](https://github.com/cosmos/ics23/tree/master/go) is a general approach for verifying merkle trees which is used in `ibc-go`. +IBC uses merkle proofs in order to verify the state of a remote counterparty state machine given a trusted root, and [ICS-23](https://github.com/cosmos/ics23/tree/master/go) is a general approach for verifying merkle trees which is used in ibc-go. -Currently, all Cosmos SDK modules contain their own stores, which maintain the state of the application module in an IAVL (immutable AVL) binary merkle tree format. Specifically with regard to IBC, core IBC maintains its own IAVL store, and IBC apps (e.g. transfer) maintain their own dedicated stores. The Cosmos SDK multistore therefore creates a simple merkle tree of all of these IAVL trees, and from each of these individual IAVL tree root hashes derives a root hash for the application state tree as a whole (the apphash). +Currently, all Cosmos SDK modules contain their own stores, which maintain the state of the application module in an IAVL (immutable AVL) binary merkle tree format. Specifically with regard to IBC, core IBC maintains its own IAVL store, and IBC apps (e.g. transfer) maintain their own dedicated stores. The Cosmos SDK multistore therefore creates a simple merkle tree of all of these IAVL trees, and from each of these individual IAVL tree root hashes it derives a root hash for the application state tree as a whole (the `AppHash`). -For the purposes of `ibc-go`, there are two types of proofs which are important: existence and non-existence proofs, terms which have been used interchangeably with membership and non-membership proofs. For the purposes of this guide, we will stick with 'existence' and 'non-existence'. +For the purposes of ibc-go, there are two types of proofs which are important: existence and non-existence proofs, terms which have been used interchangeably with membership and non-membership proofs. For the purposes of this guide, we will stick with "existence" and "non-existence". -## Existence Proofs +## Existence proofs Existence proofs are used in IBC transactions which involve verification of counterparty state for transactions which will result in the writing of provable state. For example, this includes verification of IBC store state for handshakes and packets. Put simply, existence proofs prove that a particular key and value exists in the tree. Under the hood, an IBC existence proof comprises of two proofs: an IAVL proof that the key exists in IBC store/IBC root hash, and a proof that the IBC root hash exists in the multistore root hash. -## Non-Existence Proofs +## Non-existence proofs Non-existence proofs verify the absence of data stored within counterparty state and are used to prove that a key does NOT exist in state. As stated above, these types of proofs can be used to timeout packets by proving that the counterparty has not written a packet receipt into the store, meaning that a token transfer has NOT successfully occurred. -Some trees (e.g. SMT) may have a sentinel empty child for nonexistent keys. In this case, the ICS23 proof spec should include this `EmptyChild` so that ICS23 handles the nonexistence proof correctly. +Some trees (e.g. SMT) may have a sentinel empty child for non-existent keys. In this case, the ICS-23 proof spec should include this `EmptyChild` so that ICS-23 handles the non-existence proof correctly. In some cases, there is a necessity to "mock" non-existence proofs if the counterparty does not have ability to prove absence. Since the verification method is designed to give complete control to client implementations, clients can support chains that do not provide absence proofs by verifying the existence of a non-empty sentinel `ABSENCE` value. In these special cases, the proof provided will be an ICS-23 `Existence` proof, and the client will verify that the `ABSENCE` value is stored under the given path for the given height. -## State Verification Methods: `VerifyMembership` and `VerifyNonMembership` +## State verification methods: `VerifyMembership` and `VerifyNonMembership` The state verification functions for all IBC data types have been consolidated into two generic methods, `VerifyMembership` and `VerifyNonMembership`. @@ -32,4 +32,4 @@ For more information about how to implement `VerifyMembership`, please see the ` For more information about how to implement `VerifyNonMembership`, please see the `ClientState` [implementation guide](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/docs/ibc/light-clients/client-state.md#verifynonmembership-method). -Both are expected to be provided with a standardised key path, `exported.Path`, as defined in [ICS-24 host requirements](https://github.com/cosmos/ibc/tree/main/spec/core/ics-024-host-requirements). Membership verification requires callers to provide the marshalled value `[]byte`. Delay period values should be zero for non-packet processing verification. A zero proof height is now allowed by core IBC and may be passed into `VerifyMembership` and `VerifyNonMembership`. Light clients are responsible for returning an error if a zero proof height is invalid behaviour. \ No newline at end of file +Both are expected to be provided with a standardised key path, `exported.Path`, as defined in [ICS-24 host requirements](https://github.com/cosmos/ibc/tree/main/spec/core/ics-024-host-requirements). Membership verification requires callers to provide the value marshalled as `[]byte`. Delay period values should be zero for non-packet processing verification. A zero proof height is now allowed by core IBC and may be passed into `VerifyMembership` and `VerifyNonMembership`. Light clients are responsible for returning an error if a zero proof height is invalid behaviour. \ No newline at end of file diff --git a/docs/ibc/light-clients/proposal.md b/docs/ibc/light-clients/proposal.md index 74abe182fbf..d4f613a798d 100644 --- a/docs/ibc/light-clients/proposal.md +++ b/docs/ibc/light-clients/proposal.md @@ -4,10 +4,10 @@ order: 9 # Implementing `CheckSubstituteAndUpdateState` -`CheckSubstituteAndUpdateState` will try to update the client with the state of the substitute client. [This type of governance proposal](https://ibc.cosmos.network/main/ibc/proposals.html) is typically used to recover an expired and frozen client, as it can recover the entire state and therefore all existing channels built on top of the client. +`CheckSubstituteAndUpdateState` will try to update the client with the state of the substitute client. [This type of governance proposal](https://ibc.cosmos.network/main/ibc/proposals.html) is typically used to recover an expired or frozen client, as it can recover the entire state and therefore all existing channels built on top of the client. Prior to updating, this function must verify that: - the substitute client is the same type as the subject client. For a reference implementation, please see the [Tendermint light client](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/proposal_handle.go#L32). - the provided substitute may be used to update the subject client. This may mean that certain parameters must remain unaltered. For example, a [valid substitute Tendermint light client](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/proposal_handle.go#L84) must NOT change the chain ID, trust level, max clock drift, unbonding period, proof specs or upgrade path. Please note that `AllowUpdateAfterMisbehaviour` and `AllowUpdateAfterExpiry` have been deprecated (see ADR 026 for more information). -After these checks are performed, the function must [set the updated client and consensus states](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/proposal_handle.go#L77) within the clientStore for the subject client. \ No newline at end of file +After these checks are performed, the function must [set the updated client and consensus states](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/proposal_handle.go#L77) within the client store for the subject client. \ No newline at end of file diff --git a/docs/ibc/light-clients/setup.md b/docs/ibc/light-clients/setup.md index 8bb85b234af..426eb680fac 100644 --- a/docs/ibc/light-clients/setup.md +++ b/docs/ibc/light-clients/setup.md @@ -8,7 +8,7 @@ Learn how to configure light client modules and create clients using core IBC an ## 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). +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 `InterfaceRegistry`. 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. @@ -95,7 +95,7 @@ Leveraging protobuf `Any` encoding allows core IBC to [unpack](https://github.co 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`. +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: -``` +```shell $ %s tx gov submit-proposal param-change --from= -Where proposal.json contains: +``` + +where `proposal.json` contains: + +```json { "title": "IBC Clients Param Change", "description": "Update allowed clients", diff --git a/docs/ibc/light-clients/update.md b/docs/ibc/light-clients/update.md index 504cfca7c5c..13852892aa1 100644 --- a/docs/ibc/light-clients/update.md +++ b/docs/ibc/light-clients/update.md @@ -6,7 +6,7 @@ order: 5 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 +```go type ClientMessage interface { proto.Message diff --git a/docs/ibc/light-clients/updates-and-misbehaviour.md b/docs/ibc/light-clients/updates-and-misbehaviour.md index 715a876ea43..154b20ab3b4 100644 --- a/docs/ibc/light-clients/updates-and-misbehaviour.md +++ b/docs/ibc/light-clients/updates-and-misbehaviour.md @@ -22,11 +22,11 @@ Checks for evidence of a misbehaviour in `Header` or `Misbehaviour` type. It ass For an example of a `CheckForMisbehaviour` implementation, please check the [Tendermint light client](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/07-tendermint/misbehaviour_handle.go#L18). -> The Tendermint light client [defines `Misbehaviour`](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/07-tendermint/misbehaviour.go) as two different types of situations: a situation where two conflicting `Headers` with the same height have been submitted to update a client's `ConsensusState` within the same trusting period, or that the two conflicting `Headers` have been submitted at different heights but the consensus states are not in the correct monotonic time ordering (BFT time violation). More explicitly, updating to a new height must have a timestamp greater than the previous consensus state, or, if inserting a consensus at a past height, then time must be less than those heights which come after and greater than heights which come before. +> The Tendermint light client [defines `Misbehaviour`](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/07-tendermint/misbehaviour.go) as two different types of situations: a situation where two conflicting `Header`s with the same height have been submitted to update a client's `ConsensusState` within the same trusting period, or that the two conflicting `Header`s have been submitted at different heights but the consensus states are not in the correct monotonic time ordering (BFT time violation). More explicitly, updating to a new height must have a timestamp greater than the previous consensus state, or, if inserting a consensus at a past height, then time must be less than those heights which come after and greater than heights which come before. ## `UpdateStateOnMisbehaviour` -`UpdateStateOnMisbehaviour` should perform appropriate state changes on a client state given that misbehaviour has been detected and verified. This method should only be called when misbehaviour is detected, as it does not perform any misbehaviour checks. Notably, it should freeze the client so that calling the `Status()` function on the associated client state no longer returns `Active`. +`UpdateStateOnMisbehaviour` should perform appropriate state changes on a client state given that misbehaviour has been detected and verified. This method should only be called when misbehaviour is detected, as it does not perform any misbehaviour checks. Notably, it should freeze the client so that calling the `Status` function on the associated client state no longer returns `Active`. For an example of a `UpdateStateOnMisbehaviour` implementation, please check the [Tendermint light client](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/07-tendermint/update.go#L197). @@ -40,22 +40,21 @@ For an example of a `UpdateState` implementation, please check the [Tendermint l ## Putting it all together -The `02-client Keeper` module in ibc-go offers a reference as to how these functions will be used to [update the client](https://github.com/cosmos/ibc-go/blob/main/modules/core/02-client/keeper/client.go#L48). +The `02-client` `Keeper` module in ibc-go offers a reference as to how these functions will be used to [update the client](https://github.com/cosmos/ibc-go/blob/main/modules/core/02-client/keeper/client.go#L48). -```golang +```go if err := clientState.VerifyClientMessage(clientMessage); err != nil { - return err - } - - foundMisbehaviour := clientState.CheckForMisbehaviour(clientMessage) - if foundMisbehaviour { - clientState.UpdateStateOnMisbehaviour(clientMessage) - // emit misbehaviour event - return - } - - clientState.UpdateState(clientMessage) // expects no-op on duplicate header - // emit update event - return + return err } +foundMisbehaviour := clientState.CheckForMisbehaviour(clientMessage) +if foundMisbehaviour { + clientState.UpdateStateOnMisbehaviour(clientMessage) + // emit misbehaviour event + return +} + +clientState.UpdateState(clientMessage) // expects no-op on duplicate header + // emit update event + return +} diff --git a/docs/ibc/light-clients/upgrade.md b/docs/ibc/light-clients/upgrade.md index 6426757dc93..49fa3afa46c 100644 --- a/docs/ibc/light-clients/upgrade.md +++ b/docs/ibc/light-clients/upgrade.md @@ -8,34 +8,34 @@ It is vital that high-value IBC clients can upgrade along with their underlying The IBC protocol allows client implementations to provide a path to upgrading clients given the upgraded client state, upgraded consensus state and proofs for each. This path is provided in the `VerifyUpgradeAndUpdateState` function: -```golang +```go // NOTE: proof heights are not included as upgrade to a new revision is expected to pass only on the last height committed by the current revision. Clients are responsible for ensuring that the planned last height of the current revision is somehow encoded in the proof verification process. // This is to ensure that no premature upgrades occur, since upgrade plans committed to by the counterparty may be cancelled or modified before the last planned height. // If the upgrade is verified, the upgraded client and consensus states must be set in the client store. VerifyUpgradeAndUpdateState( - ctx sdk.Context, - cdc codec.BinaryCodec, - store sdk.KVStore, - newClient ClientState, - newConsState ConsensusState, - proofUpgradeClient, - proofUpgradeConsState []byte, + ctx sdk.Context, + cdc codec.BinaryCodec, + store sdk.KVStore, + newClient ClientState, + newConsState ConsensusState, + proofUpgradeClient, + proofUpgradeConsState []byte, ) error ``` It is important to note that light clients **must** handle all management of client and consensus states including the setting of updated client state and consensus state in the client store. This can include verifying that the submitted upgraded `ClientState` is of a valid `ClientState` type, that the height of the upgraded client is not greater than the height of the current client (in order to preserve BFT monotonic time), or that certain parameters which should not be changed have not been altered in the upgraded client state. -Note that the clients should have prior knowledge of the merkle path that the upgraded client and upgraded consensus states will use. The height at which the upgrade has occurred should also be encoded in the proof. The Tendermint client implementation accomplishes this by including an `UpgradePath` in the ClientState itself, which is used along with the upgrade height to construct the merkle path under which the client state and consensus state are committed. +Note that the clients should have prior knowledge of the merkle path that the upgraded client and upgraded consensus states will use. The height at which the upgrade has occurred should also be encoded in the proof. The Tendermint client implementation accomplishes this by including an `UpgradePath` in the `ClientState` itself, which is used along with the upgrade height to construct the merkle path under which the client state and consensus state are committed. -Developers must ensure that the `UpgradeClientMsg` does not pass until the last height of the old chain has been committed, and after the chain upgrades, the `UpgradeClientMsg` should pass once and only once on all counterparty clients. +Developers must ensure that the `MsgUpgradeClient` does not pass until the last height of the old chain has been committed, and after the chain upgrades, the `MsgUpgradeClient` should pass once and only once on all counterparty clients. -Developers must ensure that the new client adopts all of the new Client parameters that must be uniform across every valid light client of a chain (chain-chosen parameters), while maintaining the Client parameters that are customizable by each individual client (client-chosen parameters) from the previous version of the client. +Developers must ensure that the new client adopts all of the new client parameters that must be uniform across every valid light client of a chain (chain-chosen parameters), while maintaining the client parameters that are customizable by each individual client (client-chosen parameters) from the previous version of the client. -Upgrades must adhere to the IBC Security Model. IBC does not rely on the assumption of honest relayers for correctness. Thus users should not have to rely on relayers to maintain client correctness and security (though honest relayers must exist to maintain relayer liveness). While relayers may choose any set of client parameters while creating a new `ClientState`, this still holds under the security model since users can always choose a relayer-created client that suits their security and correctness needs or create a Client with their desired parameters if no such client exists. +Upgrades must adhere to the IBC Security Model. IBC does not rely on the assumption of honest relayers for correctness. Thus users should not have to rely on relayers to maintain client correctness and security (though honest relayers must exist to maintain relayer liveness). While relayers may choose any set of client parameters while creating a new `ClientState`, this still holds under the security model since users can always choose a relayer-created client that suits their security and correctness needs or create a client with their desired parameters if no such client exists. -However, when upgrading an existing client, one must keep in mind that there are already many users who depend on this client's particular parameters. We cannot give the upgrading relayer free choice over these parameters once they have already been chosen. This would violate the security model since users who rely on the client would have to rely on the upgrading relayer to maintain the same level of security. Thus, developers must make sure that their upgrade mechanism allows clients to upgrade the chain-specified parameters whenever a chain upgrade changes these parameters (examples in the Tendermint client include `UnbondingPeriod`, `TrustingPeriod`, `ChainID`, `UpgradePath`, etc.), while ensuring that the relayer submitting the `UpgradeClientMsg` cannot alter the client-chosen parameters that the users are relying upon (examples in Tendermint client include `TrustLevel`, `MaxClockDrift`, etc). +However, when upgrading an existing client, one must keep in mind that there are already many users who depend on this client's particular parameters. We cannot give the upgrading relayer free choice over these parameters once they have already been chosen. This would violate the security model since users who rely on the client would have to rely on the upgrading relayer to maintain the same level of security. Thus, developers must make sure that their upgrade mechanism allows clients to upgrade the chain-specified parameters whenever a chain upgrade changes these parameters (examples in the Tendermint client include `UnbondingPeriod`, `TrustingPeriod`, `ChainID`, `UpgradePath`, etc.), while ensuring that the relayer submitting the `MsgUpgradeClient` cannot alter the client-chosen parameters that the users are relying upon (examples in Tendermint client include `TrustLevel`, `MaxClockDrift`, etc). -Developers should maintain the distinction between Client parameters that are uniform across every valid light client of a chain (chain-chosen parameters), and Client parameters that are customizable by each individual client (client-chosen parameters); since this distinction is necessary to implement the `ZeroCustomFields` method in the `ClientState` interface: +Developers should maintain the distinction between client parameters that are uniform across every valid light client of a chain (chain-chosen parameters), and client parameters that are customizable by each individual client (client-chosen parameters); since this distinction is necessary to implement the `ZeroCustomFields` method in the `ClientState` interface: ```go // Utility function that zeroes out any client customizable fields in client state From 72065aab6618b576c161562b0c3221378abdd1ee Mon Sep 17 00:00:00 2001 From: Thomas Dekeyser Date: Thu, 26 Jan 2023 09:52:45 +0000 Subject: [PATCH 02/27] review overview.md --- docs/ibc/light-clients/overview.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/ibc/light-clients/overview.md b/docs/ibc/light-clients/overview.md index afd791449b5..931ffaaf49e 100644 --- a/docs/ibc/light-clients/overview.md +++ b/docs/ibc/light-clients/overview.md @@ -14,7 +14,7 @@ Learn how to build IBC light client modules and fulfill the interfaces required 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. +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 `modules/core/exported` package of ibc-go. A light client module developer should be concerned with three main interfaces: @@ -48,13 +48,13 @@ 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 `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). +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](./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](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`](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/core/exported/client.go#L157) 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`](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/core/exported/client.go#L157) interface defined in `modules/core/exported/client.go`. ### `ClientMessage` From cb90bdf03ac8cb03579e70273b8da48a8343836e Mon Sep 17 00:00:00 2001 From: Thomas Dekeyser Date: Fri, 27 Jan 2023 08:56:54 +0000 Subject: [PATCH 03/27] review client-state.md --- 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 1ef5c1c75b8..32d1b293bbb 100644 --- a/docs/ibc/light-clients/client-state.md +++ b/docs/ibc/light-clients/client-state.md @@ -38,7 +38,7 @@ This field is returned in the response of the gRPC [`ibc.core.client.v1.Query/Cl `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/modules/core/02-client/keeper/proposal.go#L89). Upgrades are used to upgrade chain specific fields. In the tendermint case, this may be the chain ID or the unbonding period. -For more information about client upgrades see [the developer guide](../upgrades/developer-guide.md). +For more information about client upgrades see [the dedicated section of developer guide](./upgrade.md). ## `GetTimestampAtHeight` method From 15ea112b612634f2970f0d4bdcfdf1ee64655b74 Mon Sep 17 00:00:00 2001 From: Thomas Dekeyser Date: Fri, 27 Jan 2023 09:17:48 +0000 Subject: [PATCH 04/27] review consensus-state.md --- docs/ibc/light-clients/consensus-state.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/ibc/light-clients/consensus-state.md b/docs/ibc/light-clients/consensus-state.md index ebde1e8cbbe..51ce29eac62 100644 --- a/docs/ibc/light-clients/consensus-state.md +++ b/docs/ibc/light-clients/consensus-state.md @@ -4,7 +4,9 @@ order: 3 # 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. +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). From 2988045f1a6722dae70e451c3e9ea4787c279691 Mon Sep 17 00:00:00 2001 From: Thomas Dekeyser Date: Fri, 27 Jan 2023 09:58:01 +0000 Subject: [PATCH 05/27] fix and update ordering --- docs/.vuepress/config.js | 12 ++++++------ 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 | 2 +- docs/ibc/light-clients/update.md | 2 +- docs/ibc/light-clients/updates-and-misbehaviour.md | 2 +- docs/ibc/light-clients/upgrade.md | 2 +- 8 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index c34ab01f54f..b6b19318e2b 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -352,11 +352,6 @@ module.exports = { directory: false, path: "/ibc/light-clients/consensus-state.html", }, - { - title: "Setup", - directory: false, - path: "/ibc/light-clients/setup.html", - }, { title: "Updates Handling", directory: false, @@ -365,7 +360,7 @@ module.exports = { { title: "Misbehaviour Handling", directory: false, - path: "/ibc/light-clients/misbehaviour.html", + path: "/ibc/light-clients/updates-and-misbehaviour.html", }, { title: "Existence/Non-Existence Proofs", @@ -387,6 +382,11 @@ module.exports = { directory: false, path: "/ibc/light-clients/genesis.html", }, + { + title: "Setup", + directory: false, + path: "/ibc/light-clients/setup.html", + }, ] }, { diff --git a/docs/ibc/light-clients/genesis.md b/docs/ibc/light-clients/genesis.md index 8b5d697cc9e..37a9dff11cf 100644 --- a/docs/ibc/light-clients/genesis.md +++ b/docs/ibc/light-clients/genesis.md @@ -1,5 +1,5 @@ # Genesis Metadata diff --git a/docs/ibc/light-clients/proofs.md b/docs/ibc/light-clients/proofs.md index 801b99dda73..9eddda66de4 100644 --- a/docs/ibc/light-clients/proofs.md +++ b/docs/ibc/light-clients/proofs.md @@ -1,5 +1,5 @@ # Existence and non-existence proofs diff --git a/docs/ibc/light-clients/proposal.md b/docs/ibc/light-clients/proposal.md index d4f613a798d..13dda180984 100644 --- a/docs/ibc/light-clients/proposal.md +++ b/docs/ibc/light-clients/proposal.md @@ -1,5 +1,5 @@ # Implementing `CheckSubstituteAndUpdateState` diff --git a/docs/ibc/light-clients/setup.md b/docs/ibc/light-clients/setup.md index 426eb680fac..59059d09ab3 100644 --- a/docs/ibc/light-clients/setup.md +++ b/docs/ibc/light-clients/setup.md @@ -1,5 +1,5 @@ # Setup diff --git a/docs/ibc/light-clients/update.md b/docs/ibc/light-clients/update.md index 13852892aa1..443b255bb10 100644 --- a/docs/ibc/light-clients/update.md +++ b/docs/ibc/light-clients/update.md @@ -1,5 +1,5 @@ # Implementing the `ClientMessage` interface diff --git a/docs/ibc/light-clients/updates-and-misbehaviour.md b/docs/ibc/light-clients/updates-and-misbehaviour.md index 154b20ab3b4..92f8b1fda38 100644 --- a/docs/ibc/light-clients/updates-and-misbehaviour.md +++ b/docs/ibc/light-clients/updates-and-misbehaviour.md @@ -1,5 +1,5 @@ # Handling Updates and Misbehaviour diff --git a/docs/ibc/light-clients/upgrade.md b/docs/ibc/light-clients/upgrade.md index 49fa3afa46c..9c98dcaf2ed 100644 --- a/docs/ibc/light-clients/upgrade.md +++ b/docs/ibc/light-clients/upgrade.md @@ -1,5 +1,5 @@ # Implementing `VerifyUpgradeAndUpdateState` From e25e712df4845e02de0a9626901fd8f25d0a858c Mon Sep 17 00:00:00 2001 From: Thomas Dekeyser Date: Mon, 30 Jan 2023 09:38:21 +0100 Subject: [PATCH 06/27] review upgrade.md --- docs/ibc/light-clients/upgrade.md | 38 +++++++++++++++++++------------ 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/docs/ibc/light-clients/upgrade.md b/docs/ibc/light-clients/upgrade.md index 9c98dcaf2ed..79931916568 100644 --- a/docs/ibc/light-clients/upgrade.md +++ b/docs/ibc/light-clients/upgrade.md @@ -1,18 +1,19 @@ - -# Implementing `VerifyUpgradeAndUpdateState` +# Handling Upgrades It is vital that high-value IBC clients can upgrade along with their underlying chains to avoid disruption to the IBC ecosystem. Thus, IBC client developers will want to implement upgrade functionality to enable clients to maintain connections and channels even across chain upgrades. -The IBC protocol allows client implementations to provide a path to upgrading clients given the upgraded client state, upgraded consensus state and proofs for each. This path is provided in the `VerifyUpgradeAndUpdateState` function: +## Implementing `VerifyUpgradeAndUpdateState` + +The IBC protocol allows client implementations to provide a path to upgrading clients given the upgraded `ClientState`, upgraded `ConsensusState` and proofs for each. This path is provided in the `VerifyUpgradeAndUpdateState` method: ```go // NOTE: proof heights are not included as upgrade to a new revision is expected to pass only on the last height committed by the current revision. Clients are responsible for ensuring that the planned last height of the current revision is somehow encoded in the proof verification process. // This is to ensure that no premature upgrades occur, since upgrade plans committed to by the counterparty may be cancelled or modified before the last planned height. // If the upgrade is verified, the upgraded client and consensus states must be set in the client store. -VerifyUpgradeAndUpdateState( +func (cs ClientState) VerifyUpgradeAndUpdateState( ctx sdk.Context, cdc codec.BinaryCodec, store sdk.KVStore, @@ -23,29 +24,38 @@ VerifyUpgradeAndUpdateState( ) error ``` -It is important to note that light clients **must** handle all management of client and consensus states including the setting of updated client state and consensus state in the client store. This can include verifying that the submitted upgraded `ClientState` is of a valid `ClientState` type, that the height of the upgraded client is not greater than the height of the current client (in order to preserve BFT monotonic time), or that certain parameters which should not be changed have not been altered in the upgraded client state. +> Please refer to the [`07-tendermint` implementation](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/upgrade.go#L27) as an example for implementation. -Note that the clients should have prior knowledge of the merkle path that the upgraded client and upgraded consensus states will use. The height at which the upgrade has occurred should also be encoded in the proof. The Tendermint client implementation accomplishes this by including an `UpgradePath` in the `ClientState` itself, which is used along with the upgrade height to construct the merkle path under which the client state and consensus state are committed. +It is important to note that light clients **must** handle all management of client and consensus states including the setting of updated `ClientState` and `ConsensusState` in the client store. This can include verifying that the submitted upgraded `ClientState` is of a valid `ClientState` type, that the height of the upgraded client is not greater than the height of the current client (in order to preserve BFT monotonic time), or that certain parameters which should not be changed have not been altered in the upgraded `ClientState`. Developers must ensure that the `MsgUpgradeClient` does not pass until the last height of the old chain has been committed, and after the chain upgrades, the `MsgUpgradeClient` should pass once and only once on all counterparty clients. -Developers must ensure that the new client adopts all of the new client parameters that must be uniform across every valid light client of a chain (chain-chosen parameters), while maintaining the client parameters that are customizable by each individual client (client-chosen parameters) from the previous version of the client. +### Upgrade path -Upgrades must adhere to the IBC Security Model. IBC does not rely on the assumption of honest relayers for correctness. Thus users should not have to rely on relayers to maintain client correctness and security (though honest relayers must exist to maintain relayer liveness). While relayers may choose any set of client parameters while creating a new `ClientState`, this still holds under the security model since users can always choose a relayer-created client that suits their security and correctness needs or create a client with their desired parameters if no such client exists. +Clients should have **prior knowledge of the merkle path** that the upgraded client and upgraded consensus states will use. The height at which the upgrade has occurred should also be encoded in the proof. +> The Tendermint client implementation accomplishes this by including an `UpgradePath` in the `ClientState` itself, which is used along with the upgrade height to construct the merkle path under which the client state and consensus state are committed. -However, when upgrading an existing client, one must keep in mind that there are already many users who depend on this client's particular parameters. We cannot give the upgrading relayer free choice over these parameters once they have already been chosen. This would violate the security model since users who rely on the client would have to rely on the upgrading relayer to maintain the same level of security. Thus, developers must make sure that their upgrade mechanism allows clients to upgrade the chain-specified parameters whenever a chain upgrade changes these parameters (examples in the Tendermint client include `UnbondingPeriod`, `TrustingPeriod`, `ChainID`, `UpgradePath`, etc.), while ensuring that the relayer submitting the `MsgUpgradeClient` cannot alter the client-chosen parameters that the users are relying upon (examples in Tendermint client include `TrustLevel`, `MaxClockDrift`, etc). +## Chain specific vs client specific client parameters -Developers should maintain the distinction between client parameters that are uniform across every valid light client of a chain (chain-chosen parameters), and client parameters that are customizable by each individual client (client-chosen parameters); since this distinction is necessary to implement the `ZeroCustomFields` method in the `ClientState` interface: +Developers should maintain the distinction between client parameters that are uniform across every valid light client of a chain (chain-chosen parameters), and client parameters that are customizable by each individual client (client-chosen parameters); since this distinction is necessary to implement the `ZeroCustomFields` method in the [`ClientState` interface](./client-state.md): ```go // Utility function that zeroes out any client customizable fields in client state // Ledger enforced fields are maintained while all custom fields are zero values // Used to verify upgrades -ZeroCustomFields() ClientState +func (cs ClientState) ZeroCustomFields() ClientState ``` -Counterparty clients can upgrade securely by using all of the chain-chosen parameters from the chain-committed `UpgradedClient` and preserving all of the old client-chosen parameters. This enables chains to securely upgrade without relying on an honest relayer, however it can in some cases lead to an invalid final `ClientState` if the new chain-chosen parameters clash with the old client-chosen parameter. This can happen in the Tendermint client case if the upgrading chain lowers the `UnbondingPeriod` (chain-chosen) to a duration below that of a counterparty client's `TrustingPeriod` (client-chosen). Such cases should be clearly documented by developers, so that chains know which upgrades should be avoided to prevent this problem. The final upgraded client should also be validated in `VerifyUpgradeAndUpdateState` before returning to ensure that the client does not upgrade to an invalid `ClientState`. +Developers must ensure that the new client adopts all of the new client parameters that must be uniform across every valid light client of a chain (chain-chosen parameters), while maintaining the client parameters that are customizable by each individual client (client-chosen parameters) from the previous version of the client. `ZeroCustomFields` is a useful utility function to ensure only chain specific fields are updated during upgrades. + +## Security -## Putting it all together +Upgrades must adhere to the IBC Security Model. IBC does not rely on the assumption of honest relayers for correctness. Thus users should not have to rely on relayers to maintain client correctness and security (though honest relayers must exist to maintain relayer liveness). While relayers may choose any set of client parameters while creating a new `ClientState`, this still holds under the security model since users can always choose a relayer-created client that suits their security and correctness needs or create a client with their desired parameters if no such client exists. + +However, when upgrading an existing client, one must keep in mind that there are already many users who depend on this client's particular parameters. **We cannot give the upgrading relayer free choice over these parameters once they have already been chosen. This would violate the security model** since users who rely on the client would have to rely on the upgrading relayer to maintain the same level of security. + +Thus, developers must make sure that their upgrade mechanism allows clients to upgrade the chain-specified parameters whenever a chain upgrade changes these parameters (examples in the Tendermint client include `UnbondingPeriod`, `TrustingPeriod`, `ChainID`, `UpgradePath`, etc.), while ensuring that the relayer submitting the `MsgUpgradeClient` cannot alter the client-chosen parameters that the users are relying upon (examples in Tendermint client include `TrustLevel`, `MaxClockDrift`, etc). The previous paragraph discusses how `ZeroCustomFields` helps achieve this. -Please refer to the [`07-tendermint` implementation](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/upgrade.go#L27) as an example for implementation. \ No newline at end of file +### Document potential client parameter conflicts during upgrades + +Counterparty clients can upgrade securely by using all of the chain-chosen parameters from the chain-committed `UpgradedClient` and preserving all of the old client-chosen parameters. This enables chains to securely upgrade without relying on an honest relayer, however it can in some cases lead to an invalid final `ClientState` if the new chain-chosen parameters clash with the old client-chosen parameter. This can happen in the Tendermint client case if the upgrading chain lowers the `UnbondingPeriod` (chain-chosen) to a duration below that of a counterparty client's `TrustingPeriod` (client-chosen). Such cases should be clearly documented by developers, so that chains know which upgrades should be avoided to prevent this problem. The final upgraded client should also be validated in `VerifyUpgradeAndUpdateState` before returning to ensure that the client does not upgrade to an invalid `ClientState`. From a8b26938df1225b2baffecd6e8141f218a7bcc14 Mon Sep 17 00:00:00 2001 From: Thomas Dekeyser Date: Mon, 30 Jan 2023 10:02:59 +0100 Subject: [PATCH 07/27] review proofs.md --- docs/ibc/light-clients/proofs.md | 37 +++++++++++++++++++++++++++----- 1 file changed, 32 insertions(+), 5 deletions(-) diff --git a/docs/ibc/light-clients/proofs.md b/docs/ibc/light-clients/proofs.md index 9eddda66de4..826ae5127f5 100644 --- a/docs/ibc/light-clients/proofs.md +++ b/docs/ibc/light-clients/proofs.md @@ -28,8 +28,35 @@ In some cases, there is a necessity to "mock" non-existence proofs if the counte The state verification functions for all IBC data types have been consolidated into two generic methods, `VerifyMembership` and `VerifyNonMembership`. -For more information about how to implement `VerifyMembership`, please see the `ClientState` [implementation guide](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/docs/ibc/light-clients/client-state.md#verifymembership-method). - -For more information about how to implement `VerifyNonMembership`, please see the `ClientState` [implementation guide](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/docs/ibc/light-clients/client-state.md#verifynonmembership-method). - -Both are expected to be provided with a standardised key path, `exported.Path`, as defined in [ICS-24 host requirements](https://github.com/cosmos/ibc/tree/main/spec/core/ics-024-host-requirements). Membership verification requires callers to provide the value marshalled as `[]byte`. Delay period values should be zero for non-packet processing verification. A zero proof height is now allowed by core IBC and may be passed into `VerifyMembership` and `VerifyNonMembership`. Light clients are responsible for returning an error if a zero proof height is invalid behaviour. \ No newline at end of file +From the [`ClientState` interface definition](https://github.com/cosmos/ibc-go/blob/e650be91614ced7be687c30eb42714787a3bbc59/modules/core/exported/client.go#L68-L91), we find: + +```go +VerifyMembership( + ctx sdk.Context, + clientStore sdk.KVStore, + cdc codec.BinaryCodec, + height Height, + delayTimePeriod uint64, + delayBlockPeriod uint64, + proof []byte, + path Path, + value []byte, +) error + +// 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). +VerifyNonMembership( + ctx sdk.Context, + clientStore sdk.KVStore, + cdc codec.BinaryCodec, + height Height, + delayTimePeriod uint64, + delayBlockPeriod uint64, + proof []byte, + path Path, +) error +``` + +Both are expected to be provided with a standardised key path, `exported.Path`, as defined in [ICS-24 host requirements](https://github.com/cosmos/ibc/tree/main/spec/core/ics-024-host-requirements). Membership verification requires callers to provide the value marshalled as `[]byte`. Delay period values should be zero for non-packet processing verification. A zero proof height is now allowed by core IBC and may be passed into `VerifyMembership` and `VerifyNonMembership`. Light clients are responsible for returning an error if a zero proof height is invalid behaviour. + +Please refer to the [ICS-23 implementation](https://github.com/cosmos/ibc-go/blob/e093d85b533ab3572b32a7de60b88a0816bed4af/modules/core/23-commitment/types/merkle.go#L131-L205) for a concrete example. From 03fbfc7b786a578874ed48cb9dc057671e2ecead Mon Sep 17 00:00:00 2001 From: Thomas Dekeyser Date: Mon, 30 Jan 2023 10:22:43 +0100 Subject: [PATCH 08/27] review proposal.md --- docs/ibc/light-clients/proposal.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/docs/ibc/light-clients/proposal.md b/docs/ibc/light-clients/proposal.md index 13dda180984..442cb47655b 100644 --- a/docs/ibc/light-clients/proposal.md +++ b/docs/ibc/light-clients/proposal.md @@ -1,13 +1,31 @@ +# Handling proposals -# Implementing `CheckSubstituteAndUpdateState` + It is possible try to update the client with the state of the substitute client through a governance proposal. [This type of governance proposal](https://ibc.cosmos.network/main/ibc/proposals.html) is typically used to recover an expired or frozen client, as it can recover the entire state and therefore all existing channels built on top of the client. `CheckSubstituteAndUpdateState` should be implemented to handle the proposal. -`CheckSubstituteAndUpdateState` will try to update the client with the state of the substitute client. [This type of governance proposal](https://ibc.cosmos.network/main/ibc/proposals.html) is typically used to recover an expired or frozen client, as it can recover the entire state and therefore all existing channels built on top of the client. +## Implementing `CheckSubstituteAndUpdateState` + +In the [`ClientState`interface](https://github.com/cosmos/ibc-go/blob/e650be91614ced7be687c30eb42714787a3bbc59/modules/core/exported/client.go), we find: + +```go +// CheckSubstituteAndUpdateState must verify that the provided substitute may be used to update the subject client. +// The light client must set the updated client and consensus states within the clientStore for the subject client. +CheckSubstituteAndUpdateState( + ctx sdk.Context, + cdc codec.BinaryCodec, + subjectClientStore, + substituteClientStore sdk.KVStore, + substituteClient ClientState) + error +``` Prior to updating, this function must verify that: + - the substitute client is the same type as the subject client. For a reference implementation, please see the [Tendermint light client](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/proposal_handle.go#L32). - the provided substitute may be used to update the subject client. This may mean that certain parameters must remain unaltered. For example, a [valid substitute Tendermint light client](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/proposal_handle.go#L84) must NOT change the chain ID, trust level, max clock drift, unbonding period, proof specs or upgrade path. Please note that `AllowUpdateAfterMisbehaviour` and `AllowUpdateAfterExpiry` have been deprecated (see ADR 026 for more information). -After these checks are performed, the function must [set the updated client and consensus states](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/proposal_handle.go#L77) within the client store for the subject client. \ No newline at end of file +After these checks are performed, the function must [set the updated client and consensus states](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/proposal_handle.go#L77) within the client store for the subject client. + +Please refer to the [`07-tendermint implementation](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/proposal_handle.go#L27) for reference. From dbf28497067e30fce3ac1ea24826f1a6ba5a0851 Mon Sep 17 00:00:00 2001 From: Thomas Dekeyser Date: Mon, 30 Jan 2023 10:25:24 +0100 Subject: [PATCH 09/27] review genesis.md --- docs/ibc/light-clients/genesis.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/ibc/light-clients/genesis.md b/docs/ibc/light-clients/genesis.md index 37a9dff11cf..f9dcc28f34d 100644 --- a/docs/ibc/light-clients/genesis.md +++ b/docs/ibc/light-clients/genesis.md @@ -12,7 +12,7 @@ Learn how to implement the `ExportMetadata` interface {synopsis} `ClientState` instances are provided their own isolated and namespaced client store upon initialisation. `ClientState` implementations may choose to store any amount of arbitrary metadata in order to verify counterparty consensus state and perform light client updates correctly. -The `ExportMetadata` method of the `ClientState` interface provides light client modules with the ability to persist metadata in genesis exports. +The `ExportMetadata` method of the [`ClientState` interface](https://github.com/cosmos/ibc-go/blob/e650be91614ced7be687c30eb42714787a3bbc59/modules/core/exported/client.go) provides light client modules with the ability to persist metadata in genesis exports. ```go ExportMetadata(clientStore sdk.KVStore) []GenesisMetadata @@ -29,7 +29,8 @@ type GenesisMetadata interface { } ``` -This allows `ClientState` instances to retrieve and export any number of key-value pairs which are maintained within the store in their raw `[]byte` form. +This allows `ClientState` instances to retrieve and export any number of key-value pairs which are maintained within the store in their raw `[]byte` form. + When a chain is started with a `genesis.json` file which contains `ClientState` metadata (for example, when performing manual upgrades using an exported `genesis.json`) the `02-client` submodule of core IBC will handle setting the key-value pairs within their respective client stores. [See `02-client` `InitGenesis`](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/core/02-client/genesis.go#L18-L22). Please refer to the [`07-tendermint` implementation](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/genesis.go#L12) as an example. From 40589b6a76530fa9d68342de08c8cfc02434b56e Mon Sep 17 00:00:00 2001 From: Thomas Dekeyser Date: Mon, 30 Jan 2023 10:37:39 +0100 Subject: [PATCH 10/27] review setup.md --- docs/ibc/light-clients/setup.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/ibc/light-clients/setup.md b/docs/ibc/light-clients/setup.md index 59059d09ab3..bbee7a95d28 100644 --- a/docs/ibc/light-clients/setup.md +++ b/docs/ibc/light-clients/setup.md @@ -6,6 +6,10 @@ order: 10 Learn how to configure light client modules and create clients using core IBC and the `02-client` submodule. {synopsis} +A last step to finish the development of the light client, is to implement the `AppModuleBasic` interface to allow it to be added to the chain's `app.go` alongside other light client types the chain enables. + +Finally, a succinct rundown is given of the remaining steps to make the light client operational, getting the light client type passed through governance and creating the clients. + ## 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 `InterfaceRegistry`. 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). @@ -65,7 +69,7 @@ func (AppModuleBasic) GetQueryCmd() *cobra.Command { ## 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. +Generally, this is performed 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: From ef8fac737314b0e24ecdc26e2df92a0011efcbe0 Mon Sep 17 00:00:00 2001 From: Thomas Dekeyser Date: Mon, 30 Jan 2023 11:19:38 +0100 Subject: [PATCH 11/27] combine updates sections into handling client messages --- docs/.vuepress/config.js | 17 +++----- 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 | 2 +- docs/ibc/light-clients/update.md | 2 +- .../light-clients/updates-and-misbehaviour.md | 40 +++++++++++++++++-- docs/ibc/light-clients/upgrade.md | 2 +- 8 files changed, 49 insertions(+), 20 deletions(-) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index b6b19318e2b..944f35ac41c 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -353,14 +353,14 @@ module.exports = { path: "/ibc/light-clients/consensus-state.html", }, { - title: "Updates Handling", + title: "Handling ClientMessages", directory: false, - path: "/ibc/light-clients/update.html", + path: "/ibc/light-clients/updates-and-misbehaviour.html", }, { - title: "Misbehaviour Handling", + title: "Handling Upgrades", directory: false, - path: "/ibc/light-clients/updates-and-misbehaviour.html", + path: "/ibc/light-clients/upgrades.html", }, { title: "Existence/Non-Existence Proofs", @@ -368,17 +368,12 @@ module.exports = { path: "/ibc/light-clients/proofs.html", }, { - title: "Upgrades Handling", - directory: false, - path: "/ibc/light-clients/upgrade.html", - }, - { - title: "Proposal Handling", + title: "Handling Proposals", directory: false, path: "/ibc/light-clients/proposal.html", }, { - title: "Genesis Handling", + title: "Handling Genesis", directory: false, path: "/ibc/light-clients/genesis.html", }, diff --git a/docs/ibc/light-clients/genesis.md b/docs/ibc/light-clients/genesis.md index f9dcc28f34d..63872b537bc 100644 --- a/docs/ibc/light-clients/genesis.md +++ b/docs/ibc/light-clients/genesis.md @@ -1,5 +1,5 @@ # Genesis Metadata diff --git a/docs/ibc/light-clients/proofs.md b/docs/ibc/light-clients/proofs.md index 826ae5127f5..91ddc2c03fd 100644 --- a/docs/ibc/light-clients/proofs.md +++ b/docs/ibc/light-clients/proofs.md @@ -1,5 +1,5 @@ # Existence and non-existence proofs diff --git a/docs/ibc/light-clients/proposal.md b/docs/ibc/light-clients/proposal.md index 442cb47655b..558408c47a0 100644 --- a/docs/ibc/light-clients/proposal.md +++ b/docs/ibc/light-clients/proposal.md @@ -1,5 +1,5 @@ # Handling proposals diff --git a/docs/ibc/light-clients/setup.md b/docs/ibc/light-clients/setup.md index bbee7a95d28..a17e36cf7d8 100644 --- a/docs/ibc/light-clients/setup.md +++ b/docs/ibc/light-clients/setup.md @@ -1,5 +1,5 @@ # Setup diff --git a/docs/ibc/light-clients/update.md b/docs/ibc/light-clients/update.md index 443b255bb10..98c78441b40 100644 --- a/docs/ibc/light-clients/update.md +++ b/docs/ibc/light-clients/update.md @@ -1,5 +1,5 @@ # Implementing the `ClientMessage` interface diff --git a/docs/ibc/light-clients/updates-and-misbehaviour.md b/docs/ibc/light-clients/updates-and-misbehaviour.md index 92f8b1fda38..a77d38d42d1 100644 --- a/docs/ibc/light-clients/updates-and-misbehaviour.md +++ b/docs/ibc/light-clients/updates-and-misbehaviour.md @@ -1,12 +1,46 @@ +# Handling `ClientMessage`s: updates and misbehaviour -# Handling Updates and Misbehaviour +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 performed by: + ++ a single header ++ a batch of headers ++ evidence of 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. + +## Implementing the `ClientMessage` interface + +Find the `ClientMessage`interface in `modules/core/exported`: + +```go +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 retrieves the `ClientState` by client ID (available in `MsgUpdateClient`). This `ClientState` implements the [`ClientState` interface](./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`. + +```go +VerifyClientMessage(ctx sdk.Context, cdc codec.BinaryCodec, clientStore sdk.KVStore, clientMsg ClientMessage) error +CheckForMisbehaviour(ctx sdk.Context, cdc codec.BinaryCodec, clientStore sdk.KVStore, clientMsg ClientMessage) bool +UpdateStateOnMisbehaviour(ctx sdk.Context, cdc codec.BinaryCodec, clientStore sdk.KVStore, clientMsg ClientMessage) +UpdateState(ctx sdk.Context, cdc codec.BinaryCodec, clientStore sdk.KVStore, clientMsg ClientMessage) []Height +``` + +## Handling Updates and Misbehaviour The functions for handling updates to a light client and evidence of misbehaviour are all found in the [`ClientState`](https://github.com/cosmos/ibc-go/blob/v6.0.0/modules/core/exported/client.go#L40) interface, and will be discussed below. -It is important to note that `Misbehaviour` in this particular context is referring to misbehaviour on the chain level intended to fool the light client. This will be defined by each light client. +> It is important to note that `Misbehaviour` in this particular context is referring to misbehaviour on the chain level intended to fool the light client. This will be defined by each light client. ## `VerifyClientMessage` diff --git a/docs/ibc/light-clients/upgrade.md b/docs/ibc/light-clients/upgrade.md index 79931916568..d38d18c8950 100644 --- a/docs/ibc/light-clients/upgrade.md +++ b/docs/ibc/light-clients/upgrade.md @@ -1,5 +1,5 @@ # Handling Upgrades From 21db1f818847c72ae4edea693f08440b8066014c Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Thu, 9 Feb 2023 08:35:44 +0100 Subject: [PATCH 12/27] Update genesis.md --- docs/ibc/light-clients/genesis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ibc/light-clients/genesis.md b/docs/ibc/light-clients/genesis.md index 63872b537bc..5d889635500 100644 --- a/docs/ibc/light-clients/genesis.md +++ b/docs/ibc/light-clients/genesis.md @@ -2,11 +2,11 @@ order: 8 --> -# Genesis Metadata +# Genesis metadata Learn how to implement the `ExportMetadata` interface {synopsis} -## Pre-requisite Readings +## Pre-requisite readings - [Cosmos SDK module genesis](https://docs.cosmos.network/v0.47/building-modules/genesis) {prereq} From 72e08852192ee712e6b7fb01cd86e6c900690ad6 Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Thu, 9 Feb 2023 08:39:26 +0100 Subject: [PATCH 13/27] Update client-state.md --- docs/ibc/light-clients/client-state.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ibc/light-clients/client-state.md b/docs/ibc/light-clients/client-state.md index 32d1b293bbb..c9800d6dfe1 100644 --- a/docs/ibc/light-clients/client-state.md +++ b/docs/ibc/light-clients/client-state.md @@ -55,12 +55,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 proof docs](./proofs.md). +see the [Existence and non-existence proofs section](./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 proof docs](./proofs.md). +see the [Existence and non-existence proofs section](./proofs.md). ## `VerifyClientMessage` method From cabd04854863a2ac56c5c590d4c67256eab9a146 Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Thu, 9 Feb 2023 08:40:36 +0100 Subject: [PATCH 14/27] Update proposal.md --- docs/ibc/light-clients/proposal.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/ibc/light-clients/proposal.md b/docs/ibc/light-clients/proposal.md index 558408c47a0..3c5f209adc7 100644 --- a/docs/ibc/light-clients/proposal.md +++ b/docs/ibc/light-clients/proposal.md @@ -1,6 +1,7 @@ + # Handling proposals It is possible try to update the client with the state of the substitute client through a governance proposal. [This type of governance proposal](https://ibc.cosmos.network/main/ibc/proposals.html) is typically used to recover an expired or frozen client, as it can recover the entire state and therefore all existing channels built on top of the client. `CheckSubstituteAndUpdateState` should be implemented to handle the proposal. From 09a2ebc91514c07bfb63fecebe7128aba6b8d731 Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Thu, 9 Feb 2023 08:42:06 +0100 Subject: [PATCH 15/27] Update proposal.md --- docs/ibc/light-clients/proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ibc/light-clients/proposal.md b/docs/ibc/light-clients/proposal.md index 3c5f209adc7..c35cc58a4df 100644 --- a/docs/ibc/light-clients/proposal.md +++ b/docs/ibc/light-clients/proposal.md @@ -4,7 +4,7 @@ order: 7 # Handling proposals - It is possible try to update the client with the state of the substitute client through a governance proposal. [This type of governance proposal](https://ibc.cosmos.network/main/ibc/proposals.html) is typically used to recover an expired or frozen client, as it can recover the entire state and therefore all existing channels built on top of the client. `CheckSubstituteAndUpdateState` should be implemented to handle the proposal. +It is possible to update the client with the state of the substitute client through a governance proposal. [This type of governance proposal](https://ibc.cosmos.network/main/ibc/proposals.html) is typically used to recover an expired or frozen client, as it can recover the entire state and therefore all existing channels built on top of the client. `CheckSubstituteAndUpdateState` should be implemented to handle the proposal. ## Implementing `CheckSubstituteAndUpdateState` From 12fccd574e78c6a79d283bc7412323c081fa2106 Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Thu, 9 Feb 2023 08:53:29 +0100 Subject: [PATCH 16/27] Update genesis.md --- docs/ibc/light-clients/genesis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ibc/light-clients/genesis.md b/docs/ibc/light-clients/genesis.md index 5d889635500..9947b8094b3 100644 --- a/docs/ibc/light-clients/genesis.md +++ b/docs/ibc/light-clients/genesis.md @@ -33,4 +33,4 @@ This allows `ClientState` instances to retrieve and export any number of key-val When a chain is started with a `genesis.json` file which contains `ClientState` metadata (for example, when performing manual upgrades using an exported `genesis.json`) the `02-client` submodule of core IBC will handle setting the key-value pairs within their respective client stores. [See `02-client` `InitGenesis`](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/core/02-client/genesis.go#L18-L22). -Please refer to the [`07-tendermint` implementation](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/genesis.go#L12) as an example. +Please refer to the [Tendermint light client implementation](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/genesis.go#L12) for an example. From e09b4a864a10af95674d9fcb67d921a4338d1ccb Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Thu, 9 Feb 2023 08:54:42 +0100 Subject: [PATCH 17/27] Update proposal.md --- docs/ibc/light-clients/proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ibc/light-clients/proposal.md b/docs/ibc/light-clients/proposal.md index c35cc58a4df..0881f2085ae 100644 --- a/docs/ibc/light-clients/proposal.md +++ b/docs/ibc/light-clients/proposal.md @@ -29,4 +29,4 @@ Prior to updating, this function must verify that: After these checks are performed, the function must [set the updated client and consensus states](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/proposal_handle.go#L77) within the client store for the subject client. -Please refer to the [`07-tendermint implementation](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/proposal_handle.go#L27) for reference. +Please refer to the [Tendermint light client implementation](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/proposal_handle.go#L27) for reference. From 48317ac91d8c2534860ae72c5194e31688721f73 Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Thu, 9 Feb 2023 08:55:57 +0100 Subject: [PATCH 18/27] Update upgrade.md --- docs/ibc/light-clients/upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ibc/light-clients/upgrade.md b/docs/ibc/light-clients/upgrade.md index d38d18c8950..4408815f10d 100644 --- a/docs/ibc/light-clients/upgrade.md +++ b/docs/ibc/light-clients/upgrade.md @@ -24,7 +24,7 @@ func (cs ClientState) VerifyUpgradeAndUpdateState( ) error ``` -> Please refer to the [`07-tendermint` implementation](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/upgrade.go#L27) as an example for implementation. +> Please refer to the [Tendermint light client implementation](https://github.com/cosmos/ibc-go/blob/02-client-refactor-beta1/modules/light-clients/07-tendermint/upgrade.go#L27) as an example for implementation. It is important to note that light clients **must** handle all management of client and consensus states including the setting of updated `ClientState` and `ConsensusState` in the client store. This can include verifying that the submitted upgraded `ClientState` is of a valid `ClientState` type, that the height of the upgraded client is not greater than the height of the current client (in order to preserve BFT monotonic time), or that certain parameters which should not be changed have not been altered in the upgraded `ClientState`. From 9da22a8f2d9c31986407f0039491f0025da181bd Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Thu, 9 Feb 2023 08:57:17 +0100 Subject: [PATCH 19/27] Update updates-and-misbehaviour.md --- docs/ibc/light-clients/updates-and-misbehaviour.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/ibc/light-clients/updates-and-misbehaviour.md b/docs/ibc/light-clients/updates-and-misbehaviour.md index a77d38d42d1..b9356d10616 100644 --- a/docs/ibc/light-clients/updates-and-misbehaviour.md +++ b/docs/ibc/light-clients/updates-and-misbehaviour.md @@ -1,6 +1,7 @@ + # Handling `ClientMessage`s: updates and misbehaviour 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 performed by: From 8902af671fbbbca7cc1368033602a9b4c9862839 Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Thu, 9 Feb 2023 09:01:57 +0100 Subject: [PATCH 20/27] Update updates-and-misbehaviour.md --- docs/ibc/light-clients/updates-and-misbehaviour.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ibc/light-clients/updates-and-misbehaviour.md b/docs/ibc/light-clients/updates-and-misbehaviour.md index b9356d10616..c1e7c7911ad 100644 --- a/docs/ibc/light-clients/updates-and-misbehaviour.md +++ b/docs/ibc/light-clients/updates-and-misbehaviour.md @@ -37,7 +37,7 @@ UpdateStateOnMisbehaviour(ctx sdk.Context, cdc codec.BinaryCodec, clientStore sd UpdateState(ctx sdk.Context, cdc codec.BinaryCodec, clientStore sdk.KVStore, clientMsg ClientMessage) []Height ``` -## Handling Updates and Misbehaviour +## Handling updates and misbehaviour The functions for handling updates to a light client and evidence of misbehaviour are all found in the [`ClientState`](https://github.com/cosmos/ibc-go/blob/v6.0.0/modules/core/exported/client.go#L40) interface, and will be discussed below. From 9b4d88d7070a1d1412fe03e601aa25996c02bc2f Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Thu, 9 Feb 2023 09:09:39 +0100 Subject: [PATCH 21/27] Update upgrade.md --- docs/ibc/light-clients/upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ibc/light-clients/upgrade.md b/docs/ibc/light-clients/upgrade.md index 4408815f10d..ed747439227 100644 --- a/docs/ibc/light-clients/upgrade.md +++ b/docs/ibc/light-clients/upgrade.md @@ -54,7 +54,7 @@ Upgrades must adhere to the IBC Security Model. IBC does not rely on the assumpt However, when upgrading an existing client, one must keep in mind that there are already many users who depend on this client's particular parameters. **We cannot give the upgrading relayer free choice over these parameters once they have already been chosen. This would violate the security model** since users who rely on the client would have to rely on the upgrading relayer to maintain the same level of security. -Thus, developers must make sure that their upgrade mechanism allows clients to upgrade the chain-specified parameters whenever a chain upgrade changes these parameters (examples in the Tendermint client include `UnbondingPeriod`, `TrustingPeriod`, `ChainID`, `UpgradePath`, etc.), while ensuring that the relayer submitting the `MsgUpgradeClient` cannot alter the client-chosen parameters that the users are relying upon (examples in Tendermint client include `TrustLevel`, `MaxClockDrift`, etc). The previous paragraph discusses how `ZeroCustomFields` helps achieve this. +Thus, developers must make sure that their upgrade mechanism allows clients to upgrade the chain-specified parameters whenever a chain upgrade changes these parameters (examples in the Tendermint client include `UnbondingPeriod`, `TrustingPeriod`, `ChainID`, `UpgradePath`, etc), while ensuring that the relayer submitting the `MsgUpgradeClient` cannot alter the client-chosen parameters that the users are relying upon (examples in Tendermint client include `TrustLevel`, `MaxClockDrift`, etc). The previous paragraph discusses how `ZeroCustomFields` helps achieve this. ### Document potential client parameter conflicts during upgrades From 5a86f0fe6ebfcae4d475a7b54f26e95791771475 Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Thu, 9 Feb 2023 09:10:26 +0100 Subject: [PATCH 22/27] Update upgrade.md --- docs/ibc/light-clients/upgrade.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/ibc/light-clients/upgrade.md b/docs/ibc/light-clients/upgrade.md index ed747439227..77669f9e979 100644 --- a/docs/ibc/light-clients/upgrade.md +++ b/docs/ibc/light-clients/upgrade.md @@ -1,6 +1,7 @@ + # Handling Upgrades It is vital that high-value IBC clients can upgrade along with their underlying chains to avoid disruption to the IBC ecosystem. Thus, IBC client developers will want to implement upgrade functionality to enable clients to maintain connections and channels even across chain upgrades. From d55a8c67b0c23751968eee2c0f5a352711d7e587 Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Thu, 9 Feb 2023 09:17:53 +0100 Subject: [PATCH 23/27] Delete update.md --- docs/ibc/light-clients/update.md | 18 ------------------ 1 file changed, 18 deletions(-) delete mode 100644 docs/ibc/light-clients/update.md diff --git a/docs/ibc/light-clients/update.md b/docs/ibc/light-clients/update.md deleted file mode 100644 index 98c78441b40..00000000000 --- a/docs/ibc/light-clients/update.md +++ /dev/null @@ -1,18 +0,0 @@ - - -# 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. - -```go -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 From a2283f12ccc6c5471d03223a670abd7d76365406 Mon Sep 17 00:00:00 2001 From: crodriguezvega Date: Thu, 9 Feb 2023 09:29:30 +0100 Subject: [PATCH 24/27] updates light client guide --- docs/.vuepress/config.js | 8 ++++---- docs/ibc/light-clients/{proposal.md => proposals.md} | 0 docs/ibc/light-clients/{upgrade.md => upgrades.md} | 0 3 files changed, 4 insertions(+), 4 deletions(-) rename docs/ibc/light-clients/{proposal.md => proposals.md} (100%) rename docs/ibc/light-clients/{upgrade.md => upgrades.md} (100%) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index df899851a26..ba11c556e9e 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -352,17 +352,17 @@ module.exports = { path: "/ibc/light-clients/overview.html", }, { - title: "ClientState", + title: "Client State interface", directory: false, path: "/ibc/light-clients/client-state.html", }, { - title: "ConsensusState", + title: "Consensus State interface", directory: false, path: "/ibc/light-clients/consensus-state.html", }, { - title: "Handling ClientMessages", + title: "Handling Updates and Misbehaviour", directory: false, path: "/ibc/light-clients/updates-and-misbehaviour.html", }, @@ -379,7 +379,7 @@ module.exports = { { title: "Handling Proposals", directory: false, - path: "/ibc/light-clients/proposal.html", + path: "/ibc/light-clients/proposals.html", }, { title: "Handling Genesis", diff --git a/docs/ibc/light-clients/proposal.md b/docs/ibc/light-clients/proposals.md similarity index 100% rename from docs/ibc/light-clients/proposal.md rename to docs/ibc/light-clients/proposals.md diff --git a/docs/ibc/light-clients/upgrade.md b/docs/ibc/light-clients/upgrades.md similarity index 100% rename from docs/ibc/light-clients/upgrade.md rename to docs/ibc/light-clients/upgrades.md From d456d07ff2b0250929f5f47fd93879df21ec8e3d Mon Sep 17 00:00:00 2001 From: crodriguezvega Date: Thu, 9 Feb 2023 10:04:15 +0100 Subject: [PATCH 25/27] updates to light client guide --- docs/ibc/light-clients/client-state.md | 2 +- docs/ibc/light-clients/proposals.md | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/ibc/light-clients/client-state.md b/docs/ibc/light-clients/client-state.md index c9800d6dfe1..f108f7ce2e2 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 [`ClientState`](https://github.com/cosmos/ibc-go/blob/v6.0.0/modules/core/exported/client.go#L40) interface. +Learn how to implement the [`ClientState`](https://github.com/cosmos/ibc-go/blob/v6.0.0/modules/core/exported/client.go#L40) 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 diff --git a/docs/ibc/light-clients/proposals.md b/docs/ibc/light-clients/proposals.md index 0881f2085ae..abd27b8aad5 100644 --- a/docs/ibc/light-clients/proposals.md +++ b/docs/ibc/light-clients/proposals.md @@ -14,12 +14,12 @@ In the [`ClientState`interface](https://github.com/cosmos/ibc-go/blob/e650be9161 // CheckSubstituteAndUpdateState must verify that the provided substitute may be used to update the subject client. // The light client must set the updated client and consensus states within the clientStore for the subject client. CheckSubstituteAndUpdateState( - ctx sdk.Context, - cdc codec.BinaryCodec, - subjectClientStore, - substituteClientStore sdk.KVStore, - substituteClient ClientState) - error + ctx sdk.Context, + cdc codec.BinaryCodec, + subjectClientStore, + substituteClientStore sdk.KVStore, + substituteClient ClientState) + error ``` Prior to updating, this function must verify that: From cf04143615159f5a52773ed8a1a241224e880daa Mon Sep 17 00:00:00 2001 From: crodriguezvega Date: Thu, 9 Feb 2023 10:06:45 +0100 Subject: [PATCH 26/27] add link to light client developer guide from upgrades section --- docs/ibc/light-clients/upgrades.md | 2 +- docs/ibc/upgrades/developer-guide.md | 43 +--------------------------- 2 files changed, 2 insertions(+), 43 deletions(-) diff --git a/docs/ibc/light-clients/upgrades.md b/docs/ibc/light-clients/upgrades.md index 77669f9e979..49c1503ae59 100644 --- a/docs/ibc/light-clients/upgrades.md +++ b/docs/ibc/light-clients/upgrades.md @@ -2,7 +2,7 @@ order: 5 --> -# Handling Upgrades +# Handling upgrades It is vital that high-value IBC clients can upgrade along with their underlying chains to avoid disruption to the IBC ecosystem. Thus, IBC client developers will want to implement upgrade functionality to enable clients to maintain connections and channels even across chain upgrades. diff --git a/docs/ibc/upgrades/developer-guide.md b/docs/ibc/upgrades/developer-guide.md index 73a19b93664..671ff4a64d2 100644 --- a/docs/ibc/upgrades/developer-guide.md +++ b/docs/ibc/upgrades/developer-guide.md @@ -6,45 +6,4 @@ order: 2 Learn how to implement upgrade functionality for your custom IBC client. {synopsis} -As mentioned in the [README](./README.md), it is vital that high-value IBC clients can upgrade along with their underlying chains to avoid disruption to the IBC ecosystem. Thus, IBC client developers will want to implement upgrade functionality to enable clients to maintain connections and channels even across chain upgrades. - -The IBC protocol allows client implementations to provide a path to upgrading clients given the upgraded client state, upgraded consensus state and proofs for each. - -```go -// Upgrade functions -// NOTE: proof heights are not included as upgrade to a new revision is expected to pass only on the last -// height committed by the current revision. Clients are responsible for ensuring that the planned last -// height of the current revision is somehow encoded in the proof verification process. -// This is to ensure that no premature upgrades occur, since upgrade plans committed to by the counterparty -// may be cancelled or modified before the last planned height. -VerifyUpgradeAndUpdateState( - ctx sdk.Context, - cdc codec.BinaryCodec, - store sdk.KVStore, - newClient ClientState, - newConsState ConsensusState, - proofUpgradeClient, - proofUpgradeConsState []byte, -) (upgradedClient ClientState, upgradedConsensus ConsensusState, err error) -``` - -Note that the clients should have prior knowledge of the merkle path that the upgraded client and upgraded consensus states will use. The height at which the upgrade has occurred should also be encoded in the proof. The Tendermint client implementation accomplishes this by including an `UpgradePath` in the ClientState itself, which is used along with the upgrade height to construct the merkle path under which the client state and consensus state are committed. - -Developers must ensure that the `UpgradeClientMsg` does not pass until the last height of the old chain has been committed, and after the chain upgrades, the `UpgradeClientMsg` should pass once and only once on all counterparty clients. - -Developers must ensure that the new client adopts all of the new Client parameters that must be uniform across every valid light client of a chain (chain-chosen parameters), while maintaining the Client parameters that are customizable by each individual client (client-chosen parameters) from the previous version of the client. - -Upgrades must adhere to the IBC Security Model. IBC does not rely on the assumption of honest relayers for correctness. Thus users should not have to rely on relayers to maintain client correctness and security (though honest relayers must exist to maintain relayer liveness). While relayers may choose any set of client parameters while creating a new `ClientState`, this still holds under the security model since users can always choose a relayer-created client that suits their security and correctness needs or create a Client with their desired parameters if no such client exists. - -However, when upgrading an existing client, one must keep in mind that there are already many users who depend on this client's particular parameters. We cannot give the upgrading relayer free choice over these parameters once they have already been chosen. This would violate the security model since users who rely on the client would have to rely on the upgrading relayer to maintain the same level of security. Thus, developers must make sure that their upgrade mechanism allows clients to upgrade the chain-specified parameters whenever a chain upgrade changes these parameters (examples in the Tendermint client include `UnbondingPeriod`, `TrustingPeriod`, `ChainID`, `UpgradePath`, etc.), while ensuring that the relayer submitting the `UpgradeClientMsg` cannot alter the client-chosen parameters that the users are relying upon (examples in Tendermint client include `TrustLevel`, `MaxClockDrift`, etc). - -Developers should maintain the distinction between Client parameters that are uniform across every valid light client of a chain (chain-chosen parameters), and Client parameters that are customizable by each individual client (client-chosen parameters); since this distinction is necessary to implement the `ZeroCustomFields` method in the `ClientState` interface: - -```go -// Utility function that zeroes out any client customizable fields in client state -// Ledger enforced fields are maintained while all custom fields are zero values -// Used to verify upgrades -ZeroCustomFields() ClientState -``` - -Counterparty clients can upgrade securely by using all of the chain-chosen parameters from the chain-committed `UpgradedClient` and preserving all of the old client-chosen parameters. This enables chains to securely upgrade without relying on an honest relayer, however it can in some cases lead to an invalid final `ClientState` if the new chain-chosen parameters clash with the old client-chosen parameter. This can happen in the Tendermint client case if the upgrading chain lowers the `UnbondingPeriod` (chain-chosen) to a duration below that of a counterparty client's `TrustingPeriod` (client-chosen). Such cases should be clearly documented by developers, so that chains know which upgrades should be avoided to prevent this problem. The final upgraded client should also be validated in `VerifyUpgradeAndUpdateState` before returning to ensure that the client does not upgrade to an invalid `ClientState`. +Please see the section [Handling upgrades](../light-clients/upgrades.md) from the light client developer guide for more information. \ No newline at end of file From 300ceb33c8b72c0f5a17b81fcf9b3847d69f98f0 Mon Sep 17 00:00:00 2001 From: crodriguezvega Date: Thu, 9 Feb 2023 10:33:37 +0100 Subject: [PATCH 27/27] fix dead links --- docs/ibc/light-clients/client-state.md | 2 +- docs/ibc/light-clients/overview.md | 2 +- docs/ibc/light-clients/updates-and-misbehaviour.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/ibc/light-clients/client-state.md b/docs/ibc/light-clients/client-state.md index f108f7ce2e2..bd74762e562 100644 --- a/docs/ibc/light-clients/client-state.md +++ b/docs/ibc/light-clients/client-state.md @@ -38,7 +38,7 @@ This field is returned in the response of the gRPC [`ibc.core.client.v1.Query/Cl `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/modules/core/02-client/keeper/proposal.go#L89). Upgrades are used to upgrade chain specific fields. In the tendermint case, this may be the chain ID or the unbonding period. -For more information about client upgrades see [the dedicated section of developer guide](./upgrade.md). +For more information about client upgrades see the [Handling upgrades](./upgrades.md) section. ## `GetTimestampAtHeight` method diff --git a/docs/ibc/light-clients/overview.md b/docs/ibc/light-clients/overview.md index 931ffaaf49e..9eae03f7a43 100644 --- a/docs/ibc/light-clients/overview.md +++ b/docs/ibc/light-clients/overview.md @@ -67,4 +67,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 client updates](./update.md) and [handling misbehaviour](./updates-and-misbehaviour.md) sections. +Learn more in the [Handling update and misbehaviour](./updates-and-misbehaviour.md) section. diff --git a/docs/ibc/light-clients/updates-and-misbehaviour.md b/docs/ibc/light-clients/updates-and-misbehaviour.md index c1e7c7911ad..1a503ca7983 100644 --- a/docs/ibc/light-clients/updates-and-misbehaviour.md +++ b/docs/ibc/light-clients/updates-and-misbehaviour.md @@ -45,7 +45,7 @@ The functions for handling updates to a light client and evidence of misbehaviou ## `VerifyClientMessage` -`VerifyClientMessage` must verify a `ClientMessage`. A `ClientMessage` could be a `Header`, `Misbehaviour`, or batch update. To understand how to implement a `ClientMessage`, please refer to the [documentation](./update.md) +`VerifyClientMessage` must verify a `ClientMessage`. A `ClientMessage` could be a `Header`, `Misbehaviour`, or batch update. To understand how to implement a `ClientMessage`, please refer to the [Implementing the `ClientMessage` interface](#implementing-the-clientmessage-interface) section. 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.