README.md

ics	title	stage	category	kind	requires	required-by	author	created	modified
2	Client Semantics	draft	IBC/TAO	interface	23, 24	3	Juwoon Yun <joon@tendermint.com>, Christopher Goes <cwgoes@tendermint.com>, Aditya Sripal <aditya@interchain.io>	2019-02-25	2022-08-04

Synopsis

This standard specifies the properties that consensus algorithms of state machines implementing the inter-blockchain communication (IBC) protocol are required to satisfy. These properties are necessary for efficient and safe verification in the higher-level protocol abstractions. The algorithm utilised in IBC to verify the state updates of a remote state machine is referred to as a validity predicate. Pairing a validity predicate with a trusted state (i.e., a state that the verifier assumes to be correct), implements the functionality of a light client (often shortened to client) for a remote state machine on the host state machine. In addition to state update verification, every light client is able to detect consensus misbehaviours through a misbehaviour predicate.

Beyond the properties described in this specification, IBC does not impose any requirements on the internal operation of the state machines and their consensus algorithms. A state machine may consist of a single process signing operations with a private key (the so-called "solo machine"), a quorum of processes signing in unison, many processes operating a Byzantine fault-tolerant consensus algorithm (e.g., Tendermint), or other configurations yet to be invented — from the perspective of IBC, a state machine is defined entirely by its light client validation and misbehaviour detection logic.

This standard also specifies how the light client's functionality is registered and how its data is stored and updated by the IBC protocol. The stored client instances can be introspected by a third party actor, such as a user inspecting the state of the state machine and deciding whether or not to send an IBC packet.

Motivation

In the IBC protocol, an actor, which may be an end user, an off-chain process, or a module on a state machine, needs to be able to verify updates to the state of another state machine (i.e., the remote state machine). This entails accepting only the state updates that were agreed upon by the remote state machine's consensus algorithm. A light client of the remote state machine is the algorithm that enables the actor to verify state updates of that state machine. Note that light clients will generally not include validation of the entire state transition logic (as that would be equivalent to simply executing the other state machine), but may elect to validate parts of state transitions in particular cases. This standard formalises the light client model and requirements. As a result, the IBC protocol can easily be integrated with new state machines running new consensus algorithms, as long as the necessary light client algorithms fulfilling the listed requirements are provided.

The IBC protocol can be used to interact with probabilistic-finality consensus algorithms. In such cases, different validity predicates may be required by different applications. For probabilistic-finality consensus, a validity predicate is defined by a finality threshold (e.g., the threshold defines how many block needs to be on top of a block in order to consider it finalized). As a result, clients could act as thresholding views of other clients: One write-only client could be used to store state updates (without the ability to verify them), while many read-only clients with different finality thresholds (confirmation depths after which state updates are considered final) are used to verify state updates.

The client protocol should also support third-party introduction. For example, if A, B, and C are three state machines, with Alice a module on A, Bob a module on B, and Carol a module on C, such that Alice knows both Bob and Carol, but Bob knowns only Alice and not Carol, then Alice can utilise an existing channel to Bob to communicate the canonically-serialisable validity predicate for Carol. Bob can then use this validity predicate to open a connection and channel so that Bob and Carol can talk directly. If necessary, Alice may also communicate to Carol the validity predicate for Bob, prior to Bob's connection attempt, so that Carol knows to accept the incoming request.

Client interfaces should also be constructed so that custom validation logic can be provided safely to define a custom client at runtime, as long as the underlying state machine can provide an appropriate gas metering mechanism to charge for compute and storage. On a host state machine which supports WASM execution, for example, the validity predicate and misbehaviour predicate could be provided as executable WASM functions when the client instance is created.

Definitions

• get, set, Path, and Identifier are as defined in ICS 24.

• Consensus is a state update generating algorithm. It takes the previous state of a state machine together with a set of messages (i.e., state machine transactions) and generates a valid state update of the state machine. Every state machine MUST have a Consensus that generates a unique, ordered list of state updates starting from a genesis state.

  This specification expects that the state updates generated by Consensus satisfy the following properties:

  • Every state update MUST NOT have more than one direct successor in the list of state updates. In other words, the state machine MUST guarantee finality and safety.
  • Every state update MUST eventually have a successor in the list of state updates. In other words, the state machine MUST guarantee liveness.
  • Every state update MUST be valid (i.e., valid state transitions). In other words, Consensus MUST be honest, e.g., in the case Consensus is a Byzantine fault-tolerant consensus algorithm, such as Tendermint, less than a third of block producers MAY be Byzantine.

  Unless the state machine satisfies all of the above properties, the IBC protocol may not work as intended, e.g., users' assets might be stolen. Note that specific client types may require additional properties.

• Height specifies the order of the state updates of a state machine, e.g., a sequence number. This entails that each state update is mapped to a Height.

• CommitmentRoot is as defined in ICS 23. It provides an efficient way for higher-level protocol abstractions to verify whether a particular state transition has occurred on the remote state machine, i.e., it enables proofs of inclusion or non-inclusion of particular values at particular paths in the state of the remote state machine at particular Heights.

• ClientMessage is an arbitrary message defined by the client type that relayers can submit in order to update the client. The ClientMessage may be intended as a regular update which may add new consensus state for proof verification, or it may contain misbehaviour which should freeze the client.

• ValidityPredicate is a function that validates a ClientMessage sent by a relayer in order to update the client. Using the ValidityPredicate SHOULD be more computationally efficient than executing Consensus.

• ConsensusState is the trusted view of the state of a state machine at a particular Height. It MUST contain sufficient information to enable the ValidityPredicate to validate state updates, which can then be used to generate new ConsensusStates. It MUST be serialisable in a canonical fashion so that remote parties, such as remote state machines, can check whether a particular ConsensusState was stored by a particular state machine. It MUST be introspectable by the state machine whose view it represents, i.e., a state machine can look up its own ConsensusStates at past Heights.

• ClientState is the state of a client. It MUST expose an interface to higher-level protocol abstractions, e.g., functions to verify proofs of the existence of particular values at particular paths at particular Heights.

• MisbehaviourPredicate is a that checks whether the rules of Consensus were broken, in which case the client MUST be frozen, i.e., no subsequent ConsensusStates can be generated.

• Misbehaviour is the proof needed by the MisbehaviourPredicate to determine whether a violation of the consensus protocol occurred. For example, in the case the state machine is a blockchain, a Misbehaviour might consist of two signed block headers with different CommitmentRoots, but the same Height.

Desired Properties

Light clients MUST provide state verification functions that provide a secure way to verify the state of the remote state machines using the existing ConsensusStates. These state verification functions enable higher-level protocol abstractions to verify sub-components of the state of the remote state machines.

ValidityPredicates MUST reflect the behaviour of the remote state machine and its Consensus, i.e., ValidityPredicates accept only state updates that contain state updates generated by the Consensus of the remote state machine.

In case of misbehavior, the behaviour of the ValidityPredicate might differ from the behaviour of the remote state machine and its Consensus (since clients do not execute the Consensus of the remote state machine). In this case, a Misbehaviour SHOULD be submitted to the host state machine, which would result in the client being frozen and higher-level intervention being necessary.

Technical Specification

This specification outlines what each client type must define. A client type is a set of definitions of the data structures, initialisation logic, validity predicate, and misbehaviour predicate required to operate a light client. State machines implementing the IBC protocol can support any number of client types, and each client type can be instantiated with different initial consensus states in order to track different consensus instances. In order to establish a connection between two state machines (see ICS 3), the state machines must each support the client type corresponding to the other state machine's consensus algorithm.

Specific client types shall be defined in later versions of this specification and a canonical list shall exist in this repository. State machines implementing the IBC protocol are expected to respect these client types, although they may elect to support only a subset.

Data Structures

Height

Height is an opaque data structure defined by a client type. It must form a partially ordered set & provide operations for comparison.

type Height

enum Ord {
  LT
  EQ
  GT
}

type compare = (h1: Height, h2: Height) => Ord

A height is either LT (less than), EQ (equal to), or GT (greater than) another height.

>=, >, ===, <, <= are defined through the rest of this specification as aliases to compare.

There must also be a zero-element for a height type, referred to as 0, which is less than all non-zero heights.

ConsensusState

ConsensusState is an opaque data structure defined by a client type, used by the validity predicate to verify new commits & state roots. Likely the structure will contain the last commit produced by the consensus process, including signatures and validator set metadata.

ConsensusState MUST be generated from an instance of Consensus, which assigns unique heights for each ConsensusState (such that each height has exactly one associated consensus state). Two ConsensusStates on the same chain SHOULD NOT have the same height if they do not have equal commitment roots. Such an event is called an "equivocation" and MUST be classified as misbehaviour. Should one occur, a proof should be generated and submitted so that the client can be frozen and previous state roots invalidated as necessary.

The ConsensusState of a chain MUST have a canonical serialisation, so that other chains can check that a stored consensus state is equal to another (see ICS 24 for the keyspace table).

type ConsensusState = bytes

The ConsensusState MUST be stored under a particular key, defined below, so that other chains can verify that a particular consensus state has been stored.

The ConsensusState MUST define a getTimestamp() method which returns the timestamp associated with that consensus state:

type getTimestamp = ConsensusState => uint64

ClientState

ClientState is an opaque data structure defined by a client type. It may keep arbitrary internal state to track verified roots and past misbehaviours.

Light clients are representation-opaque — different consensus algorithms can define different light client update algorithms — but they must expose this common set of query functions to the IBC handler.

type ClientState = bytes

Client types MUST define a method to initialise a client state with the provided client identifier and consensus state, writing to internal state as appropriate.

type initialise = (identifier: Identifier, consensusState: ConsensusState) => ClientState

Client types MUST define a method to fetch the current height (height of the most recent validated state update).

type latestClientHeight = (
  clientState: ClientState)
  => Height

Client types MUST define a method on the client state to fetch the timestamp at a given height

type getTimestampAtHeight = (
  clientState: ClientState,
  height: Height
) => uint64

ClientMessage

A ClientMessage is an opaque data structure defined by a client type which provides information to update the client. ClientMessages can be submitted to an associated client to add new ConsensusState(s) and/or update the ClientState. They likely contain a height, a proof, a commitment root, and possibly updates to the validity predicate.

type ClientMessage = bytes

Validity predicate

A validity predicate is an opaque function defined by a client type to verify ClientMessages depending on the current ConsensusState. Using the validity predicate SHOULD be far more computationally efficient than replaying the full consensus algorithm for the given parent ClientMessage and the list of network messages.

The validity predicate is defined as:

type VerifyClientMessage = (ClientMessage) => Void

VerifyClientMessage MUST throw an exception if the provided ClientMessage was not valid.

Misbehaviour predicate

A misbehaviour predicate is an opaque function defined by a client type, used to check if a ClientMessage constitutes a violation of the consensus protocol. For example, if the state machine is a blockchain, this might be two signed headers with different state roots but the same height, a signed header containing invalid state transitions, or other proof of malfeasance as defined by the consensus algorithm.

The misbehaviour predicate is defined as

type checkForMisbehaviour = (ClientMessage) => bool

checkForMisbehaviour MUST throw an exception if the provided proof of misbehaviour was not valid.

UpdateState

UpdateState will update the client given a verified ClientMessage. Note that this function is intended for non-misbehaviour ClientMessages.

type UpdateState = (ClientMessage) => Void

verifyClientMessage must be called before this function, and checkForMisbehaviour must return false before this function is called.

The client MUST also mutate internal state to store now-finalised consensus roots and update any necessary signature authority tracking (e.g. changes to the validator set) for future calls to the validity predicate.

Clients MAY have time-sensitive validity predicates, such that if no ClientMessage is provided for a period of time (e.g. an unbonding period of three weeks) it will no longer be possible to update the client, i.e., the client is being frozen. In this case, a permissioned entity such as a chain governance system or trusted multi-signature MAY be allowed to intervene to unfreeze a frozen client & provide a new correct ClientMessage.

UpdateStateOnMisbehaviour

UpdateStateOnMisbehaviour will update the client upon receiving a verified ClientMessage that is valid misbehaviour.

type UpdateStateOnMisbehaviour = (ClientMessage) => Void

verifyClientMessage must be called before this function, and checkForMisbehaviour must return true before this function is called.

The client MUST also mutate internal state to mark appropriate heights which were previously considered valid as invalid, according to the nature of the misbehaviour.

Once misbehaviour is detected, clients SHOULD be frozen so that no future updates can be submitted. A permissioned entity such as a chain governance system or trusted multi-signature MAY be allowed to intervene to unfreeze a frozen client & provide a new correct ClientMessage which updates the client to a valid state.

CommitmentProof

CommitmentProof is an opaque data structure defined by a client type in accordance with ICS 23. It is utilised to verify presence or absence of a particular key/value pair in state at a particular finalised height (necessarily associated with a particular commitment root).

State verification

Client types must define functions to authenticate internal state of the state machine which the client tracks. Internal implementation details may differ (for example, a loopback client could simply read directly from the state and require no proofs).

• The delayPeriodTime is passed to the verification functions for packet-related proofs in order to allow packets to specify a period of time which must pass after a consensus state is added before it can be used for packet-related verification.
• The delayPeriodBlocks is passed to the verification functions for packet-related proofs in order to allow packets to specify a period of blocks which must pass after a consensus state is added before it can be used for packet-related verification.

verifyMembership is a generic proof verification method which verifies a proof of the existence of a value at a given CommitmentPath at the specified height. It MUST return an error is the verification is not successful. The caller is expected to construct the full CommitmentPath from a CommitmentPrefix and a standardized path (as defined in ICS 24). If the caller desires a particular delay period to be enforced, then it can pass in a non-zero delayPeriodTime or delayPeriodBlocks. If a delay period is not necessary, the caller must pass in 0 for delayPeriodTime and delayPeriodBlocks, and the client will not enforce any delay period for verification.

type verifyMembership = (
  clientState: ClientState,
  height: Height,
  delayPeriodTime: uint64,
  delayPeriodBlocks: uint64,
  proof: CommitmentProof,
  path: CommitmentPath,
  value: bytes)
  => Error

verifyNonMembership is a generic proof verification method which verifies a proof of absence of a given CommitmentPath at the specified height. It MUST return an error is the verification is not successful. The caller is expected to construct the full CommitmentPath from a CommitmentPrefix and a standardized path (as defined in ICS 24). If the caller desires a particular delay period to be enforced, then it can pass in a non-zero delayPeriodTime or delayPeriodBlocks. If a delay period is not necessary, the caller must pass in 0 for delayPeriodTime and delayPeriodBlocks, and the client will not enforce any delay period for verification.

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. Thus 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.

type verifyNonMembership = (
  clientState: ClientState,
  height: Height,
  delayPeriodTime: uint64,
  delayPeriodBlocks: uint64,
  proof: CommitmentProof,
  path: CommitmentPath)
  => Error

Query interface

Chain queries

These query endpoints are assumed to be exposed over HTTP or an equivalent RPC API by nodes of the chain associated with a particular client.

queryUpdate MUST be defined by the chain which is validated by a particular client, and should allow for retrieval of clientMessage for a given height. This endpoint is assumed to be untrusted.

type queryUpdate = (height: Height) => ClientMessage

queryChainConsensusState MAY be defined by the chain which is validated by a particular client, to allow for the retrieval of the current consensus state which can be used to construct a new client. When used in this fashion, the returned ConsensusState MUST be manually confirmed by the querying entity, since it is subjective. This endpoint is assumed to be untrusted. The precise nature of the ConsensusState may vary per client type.

type queryChainConsensusState = (height: Height) => ConsensusState

Note that retrieval of past consensus states by height (as opposed to just the current consensus state) is convenient but not required.

queryChainConsensusState MAY also return other data necessary to create clients, such as the "unbonding period" for certain proof-of-stake security models. This data MUST also be verified by the querying entity.

On-chain state queries

This specification defines a single function to query the state of a client by-identifier.

function queryClientState(identifier: Identifier): ClientState {
  return provableStore.get(clientStatePath(identifier))
}

The ClientState type SHOULD expose its latest verified height (from which the consensus state can then be retrieved using queryConsensusState if desired).

type latestHeight = (state: ClientState) => Height

Client types SHOULD define the following standardised query functions in order to allow relayers & other off-chain entities to interface with on-chain state in a standard API.

queryConsensusState allows stored consensus states to be retrieved by height.

type queryConsensusState = (
  identifier: Identifier,
  height: Height,
) => ConsensusState

Proof construction

Each client type SHOULD define functions to allow relayers to construct the proofs required by the client's state verification algorithms. These may take different forms depending on the client type. For example, Tendermint client proofs may be returned along with key-value data from store queries, and solo client proofs may need to be constructed interactively on the solo state machine in question (since the user will need to sign the message). These functions may constitute external queries over RPC to a full node as well as local computation or verification.

type queryAndProveClientConsensusState = (
  clientIdentifier: Identifier,
  height: Height,
  prefix: CommitmentPrefix,
  consensusStateHeight: Height) => ConsensusState, Proof

type queryAndProveConnectionState = (
  connectionIdentifier: Identifier,
  height: Height,
  prefix: CommitmentPrefix) => ConnectionEnd, Proof

type queryAndProveChannelState = (
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  height: Height,
  prefix: CommitmentPrefix) => ChannelEnd, Proof

type queryAndProvePacketData = (
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  height: Height,
  prefix: CommitmentPrefix,
  sequence: uint64) => []byte, Proof

type queryAndProvePacketAcknowledgement = (
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  height: Height,
  prefix: CommitmentPrefix,
  sequence: uint64) => []byte, Proof

type queryAndProvePacketAcknowledgementAbsence = (
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  height: Height,
  prefix: CommitmentPrefix,
  sequence: uint64) => Proof

type queryAndProveNextSequenceRecv = (
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  height: Height,
  prefix: CommitmentPrefix) => uint64, Proof

Implementation strategies

Loopback

A loopback client of a local state machine merely reads from the local state, to which it must have access.

Simple signatures

A client of a solo state machine with a known public key checks signatures on messages sent by that local state machine, which are provided as the Proof parameter. The height parameter can be used as a replay protection nonce.

Multi-signature or threshold signature schemes can also be used in such a fashion.

Proxy clients

Proxy clients verify another (proxy) state machine's verification of the target state machine, by including in the proof first a proof of the client state on the proxy state machine, and then a secondary proof of the sub-state of the target state machine with respect to the client state on the proxy state machine. This allows the proxy client to avoid storing and tracking the consensus state of the target state machine itself, at the cost of adding security assumptions of proxy state machine correctness.

Merklized state trees

For clients of state machines with Merklized state trees, these functions can be implemented by calling the ICS-23 verifyMembership or verifyNonMembership methods, using a verified Merkle root stored in the ClientState, to verify presence or absence of particular key/value pairs in state at particular heights in accordance with ICS 23.

type verifyMembership = (ClientState, Height, CommitmentProof, Path, Value) => boolean

type verifyNonMembership = (ClientState, Height, CommitmentProof, Path) => boolean

Sub-protocols

IBC handlers MUST implement the functions defined below.

Identifier validation

Clients are stored under a unique Identifier prefix. This ICS does not require that client identifiers be generated in a particular manner, only that they be unique. However, it is possible to restrict the space of Identifiers if required. The validation function validateClientIdentifier MAY be provided.

type validateClientIdentifier = (id: Identifier) => boolean

If not provided, the default validateClientIdentifier will always return true.

Utilising past roots

To avoid race conditions between client updates (which change the state root) and proof-carrying transactions in handshakes or packet receipt, many IBC handler functions allow the caller to specify a particular past root to reference, which is looked up by height. IBC handler functions which do this must ensure that they also perform any requisite checks on the height passed in by the caller to ensure logical correctness.

Create

Calling createClient with the client type and initial consensus state creates a new client.

function createClient(
  clientType: ClientType,
  consensusState: ConsensusState) {
    // implementations may define a identifier generation function
    identifier = generateClientIdentifier()
    abortTransactionUnless(provableStore.get(clientStatePath(identifier)) === null)
    abortSystemUnless(provableStore.get(clientTypePath(identifier)) === null)
    clientType.initialise(identifier, consensusState)
    provableStore.set(clientTypePath(identifier), clientType)
}

Query

Client consensus state and client internal state can be queried by identifier, but the specific paths which must be queried are defined by each client type.

Update

Updating a client is done by submitting a new ClientMessage. The Identifier is used to point to the stored ClientState that the logic will update. When a new ClientMessage is verified with the stored ClientState's validity predicate and ConsensusState, the client MUST update its internal state accordingly, possibly finalising commitment roots and updating the signature authority logic in the stored consensus state.

If a client can no longer be updated (if, for example, the trusting period has passed), it will no longer be possible to send any packets over connections & channels associated with that client, or timeout any packets in-flight (since the height & timestamp on the destination chain can no longer be verified). Manual intervention must take place to reset the client state or migrate the connections & channels to another client. This cannot safely be done completely automatically, but chains implementing IBC could elect to allow governance mechanisms to perform these actions (perhaps even per-client/connection/channel in a multi-sig or contract).

function updateClient(
  id: Identifier,
  clientMessage: ClientMessage) {
    // get clientState from store with id
    clientState = provableStore.get(clientStatePath(id))
    abortTransactionUnless(clientState !== null)

    clientState.VerifyClientMessage(clientMessage)
    
    foundMisbehaviour := clientState.CheckForMisbehaviour(clientMessage)
    if foundMisbehaviour {
        clientState.UpdateStateOnMisbehaviour(clientMessage)
        // emit misbehaviour event
    }
    else {    
        clientState.UpdateState(clientMessage) // expects no-op on duplicate clientMessage
        // emit update event
    }
}

Misbehaviour

A relayer may alert the client to the misbehaviour directly, possibly invalidating previously valid state roots & preventing future updates.

function submitMisbehaviourToClient(
  id: Identifier,
  clientMessage: ClientMessage) {
    clientState = provableStore.get(clientStatePath(id))
    abortTransactionUnless(clientState !== null)
    // authenticate client message
    clientState.verifyClientMessage(clientMessage)
    // check that client message is valid instance of misbehaviour
    abortTransactionUnless(clientState.checkForMisbehaviour(clientMessage))
    // update state based on misbehaviour
    clientState.UpdateStateOnMisbehaviour(misbehaviour)
}

Properties & Invariants

• Client identifiers are immutable & first-come-first-serve. Clients cannot be deleted (allowing deletion would potentially allow future replay of past packets if identifiers were re-used).

Backwards Compatibility

Not applicable.

Forwards Compatibility

New client types can be added by IBC implementations at-will as long as they conform to this interface.

Example Implementation

Please see the ibc-go implementations of light clients for examples of how to implement your own: https://github.com/cosmos/ibc-go/blob/main/modules/light-clients

Other Implementations

Coming soon.

History

Mar 5, 2019 - Initial draft finished and submitted as a PR

May 29, 2019 - Various revisions, notably multiple commitment-roots

Aug 15, 2019 - Major rework for clarity around client interface

Jan 13, 2020 - Revisions for client type separation & path alterations

Jan 26, 2020 - Addition of query interface

Jul 27, 2022 - Addition of verifyClientState function, and move ClientState to the provableStore

August 4, 2022 - Changes to ClientState interface and associated handler to align with changes in 02-client-refactor ADR: cosmos/ibc-go#1871

Copyright

All content herein is licensed under Apache 2.0.