README

ics: 2 title: Client Semantics stage: draft category: IBC/TAO kind: interface requires: 24 required-by: 4 version compatibility: ibc-go v10.0.0 author: Juwoon Yun [email protected], Christopher Goes [email protected], Aditya Sripal [email protected] created: 2019-02-25 modified: 2024-08-22

Synopsis

The IBC protocol provides secure packet flow between applications on different ledgers by verifying the packet messages using clients of the counterparty state machines. While ICS-4 defines the core packet flow logic between two chains and the provable commitments they must make in order to communicate, this standard ICS-2 specifies how a chain verifies the IBC provable commitments of the counterparty which is crucial to securely receive and process a packet flow message arriving from the counterparty.

This standard focuses on how to keep track of the counterparty consensus and verify the state machine; it also 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

The IBC protocol 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.

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

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

type ValidityPredicate = (clientState: bytes, trustedConsensusState: bytes, trustedHeight: Number) => (newConsensusState: bytes, newHeight: Number, err: Error)

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 future state updates, which can then be used to generate new ConsensusStates.
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 function 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. Verification against the client after it is frozen will also fail.

type MisbehaviourPredicate = (clientState: bytes, trustedConsensusState: bytes, trustedHeight: Number, misbehaviour: bytes) => bool

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 ConsensusState for 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. Once the client is frozen, a recovery mechanism to address the situation must occur before client processing can presume. This recovery mechanism is out-of-scope of the IBC protocol as the specific recovery needed is highly case-dependent.

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.

Specific client types and their specifications are defined in the light clients section of this repository.

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). There MUST NOT be two valid ConensusStates for the same height. 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.

type ConsensusState = bytes

The ConsensusState MUST define a getTimestamp() method which returns the timestamp in seconds associated with that consensus state. This timestamp MUST be the timestamp used in the counterparty state machine and agreed to by Consensus.

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, client state and consensus state, writing to internal state as appropriate.

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

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

`CommitmentProof`

CommitmentProof is an opaque data structure defined by the client type.

type CommitmentProof = bytes

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

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 if 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 4).

type verifyMembership = (
  clientState: ClientState,
  height: Height,
  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 if 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).

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 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,
  proof: CommitmentProof,
  path: CommitmentPath)
  => Error

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 as MerkleTree Existence and NonExistence proofs. Client implementations may choose to implement these methods for the specific tree used by the counterparty chain or they can use the tree-generic 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 for any ICS-23 compliant tree given a ProofSpec that describes how the tree is constructed. In this case, the ICS-23 ProofSpec MUST be provided to the client on initialization.

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.

CreateClient

Calling createClient with the client state and initial consensus state creates a new client. The intiator of this client is responsible for setting all of the initial parameters of the ClientState and the initial root-of-trust ConsensusState. The client implementation is then responsible for executing the light client ValidityPredicate against these initial parameters. Thus, once a root-of-trust is instantiated; the light client guarantees to preserve that trust within the confines of the security model as parameterized by the ClientState. If a user verifies that a client is a valid client of the counterparty chain once, they can be guaranteed that it will remain a valid client into the future so long as the MisbehaviourPredicate is not triggered. If the MisbehaviourPredicate is triggered however, this can be submitted as misbehaviour to freeze the IBC light client operations.

CreateClient Inputs:

clientType: string: This is the client-type that references a particular light client implementation on the chain. The CreateClient message will create a new instance of the given client-type. ClientState: bytes: This is the opaque client state as defined for the given client type. It will contain any parameters needed for verifying client updates and proof verification against a ConsensusState. The ClientState parameterizes the security model as implemented by the client type. ConsensusState: bytes: This is the opaque consensus state as defined for the given client type. It is the initial consensus state provided and MUST be capable of being used by the ValidityPredicate to add new ConsensusStates to the client. The initial ConsensusState MAY also be used for proof verification but it is not necessary.

Excerpt (19994 of 30814 characters). Read the whole page on cosmos/ibc (ICS specifications) ↗

← Back to Documentation