Skip to main content

Synopsis

This specification document describes a client (verification algorithm) for a solo machine with a single updateable public key which implements the ICS 2 interface.

Motivation

Solo machines — which might be devices such as phones, browsers, or laptops — might like to interface with other machines & replicated ledgers which speak IBC, and they can do so through the uniform client interface. Solo machine clients are roughly analogous to “implicit accounts” and can be used in lieu of “regular transactions” on a ledger, allowing all transactions to work through the unified interface of IBC.

Definitions

Functions & terms are as defined in ICS 2. getCommitmentPrefix is as defined in ICS 24. removePrefix is as defined in ICS 23.

Desired properties

This specification must satisfy the client interface defined in ICS 2. Conceptually, we assume “big table of signatures in the universe” - that signatures produced are public - and incorporate replay protection accordingly.

Technical specification

This specification contains implementations for all of the functions defined by ICS 2.

Client state

The ClientState of a solo machine consists of the sequence number and a boolean indicating whether or not the client is frozen.

Consensus state

The ConsensusState of a solo machine consists of the current public key, current diversifier, and timestamp. The diversifier is an arbitrary string, chosen when the client is created, designed to allow the same public key to be re-used across different solo machine clients (potentially on different chains) without being considered misbehaviour.

Height

The Height of a solo machine is just a uint64, with the usual comparison operations.

Headers

Headers must only be provided by a solo machine when the machine wishes to update the public key or diversifier.
Header implements the ClientMessage interface.

Signature verification

The solomachine public key must sign over the following struct:

Misbehaviour

Misbehaviour for solo machines consists of a sequence and two signatures over different messages at that sequence.
Misbehaviour implements the ClientMessage interface.

Signatures

Signatures are provided in the Proof field of client state verification functions. They include data & a timestamp, which must also be signed over.

Client initialisation

The solo machine client initialise function starts an unfrozen client with the initial consensus state.
The solo machine client latestClientHeight function returns the latest sequence.

Validity predicate

The solo machine client verifyClientMessage function checks that the currently registered public key signed over the client message at the expected sequence with the current diversifier included in the client message. If the client message is an update, then it must be the current sequence. If the client message is misbehaviour then it must be the sequence of the misbehaviour.

Misbehaviour predicate

Since misbehaviour is checked in verifyClientMessage, if the client message is of type Misbehaviour then we return true:

Update functions

Function updateState updates the solo machine ConsensusState values using the provided client message header:
Function updateStateOnMisbehaviour updates the function after receiving valid misbehaviour:

State verification functions

All solo machine client state verification functions simply check a signature, which must be provided by the solo machine.

Properties & invariants

Instantiates the interface defined in ICS 2.

Backwards compatibility

Not applicable.

Forwards compatibility

Not applicable. Alterations to the client verification algorithm will require a new client standard.

Example implementations

History

December 9th, 2019 - Initial version December 17th, 2019 - Final first draft August 15th, 2022 - Changes to align with 02-client-refactor in #813 September 14th, 2022 - Changes to align with changes in #4429 All content herein is licensed under Apache 2.0.