From f26eb4ee89234cd5ad85bb316566f109463556bd Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Wed, 22 Jan 2020 12:55:31 -0800 Subject: [PATCH] light client dir and readmes --- spec/consensus/light/README.md | 49 +++++++++++++++++++ .../accountability.md} | 0 .../verification-non-recursive.md} | 0 .../verification.md} | 0 spec/consensus/readme.md | 24 +++++++++ 5 files changed, 73 insertions(+) create mode 100644 spec/consensus/light/README.md rename spec/consensus/{fork-accountability.md => light/accountability.md} (100%) rename spec/consensus/{non-recursive-light-client.md => light/verification-non-recursive.md} (100%) rename spec/consensus/{light-client.md => light/verification.md} (100%) diff --git a/spec/consensus/light/README.md b/spec/consensus/light/README.md new file mode 100644 index 000000000..c45875053 --- /dev/null +++ b/spec/consensus/light/README.md @@ -0,0 +1,49 @@ +# Tendermint Light Client Protocol + +## Contents + +- [Motivation](#motivation) +- [Structure](#structure) +- [Core Verification](./verification.md) +- [Fork Detection](./detection.md) +- [Fork Accountability](./accountability.md) + +## Motivation + +The Tendermint Light Client is motivated by the need for a light weight protocol +to sync with a Tendermint blockchain, with the least processing necessary to +securely verify a recent state. The protocol consists +primarily of checking hashes and verifying Tendermint commit signatures to +update trusted validator sets and committed block headers from the chain. + +Motivating use cases include: + +- Light Node: a daemon that syncs a blockchain to the latest committed header by making RPC requests to full nodes. +- State Sync: a reactor that syncs a blockchain to a recent committed state by making P2P requests to full nodes. +- IBC Client: an ABCI application library that syncs a blockchain to a recent committed header by receiving proof-carrying +transactions from "IBC relayers", who make RPC requests to full nodes on behalf of the IBC clients. + +## Structure + +The Tendermint Light Client consists of three primary components: + +- [Core Verification](./verification.md): verifying hashes, signatures, and validator set changes +- [Fork Detection](./detection.md): talking to multiple peers to detect byzantine behaviour +- [Fork Accountability](./accountability.md): analyzing byzantine behaviour to hold validators accountable. + +While every light client must perform core verification and fork detection +to achieve their prescribed security level, fork accountability is expected to +be done by full nodes and validators, and is thus more accurately a component of +the full node consensus protocol, though it is included here since it is +primarily concerned with providing security to light clients. + +Light clients are fundamentally synchronous protocols, +where security is grounded ultimately in the interval during which a validator can be punished +for byzantine behaviour. We assume here that such intervals have fixed and known minima +referred to commonly as a blockchain's Unbonding Period. + +A secure light client must guarantee that all three components - +core verification, fork detection, and fork accountability - +each with their own synchrony assumptions and fault model, can execute +sequentially and to completion within the given Unbonding Period. + diff --git a/spec/consensus/fork-accountability.md b/spec/consensus/light/accountability.md similarity index 100% rename from spec/consensus/fork-accountability.md rename to spec/consensus/light/accountability.md diff --git a/spec/consensus/non-recursive-light-client.md b/spec/consensus/light/verification-non-recursive.md similarity index 100% rename from spec/consensus/non-recursive-light-client.md rename to spec/consensus/light/verification-non-recursive.md diff --git a/spec/consensus/light-client.md b/spec/consensus/light/verification.md similarity index 100% rename from spec/consensus/light-client.md rename to spec/consensus/light/verification.md diff --git a/spec/consensus/readme.md b/spec/consensus/readme.md index 0ffc4b0bf..32d5579be 100644 --- a/spec/consensus/readme.md +++ b/spec/consensus/readme.md @@ -3,3 +3,27 @@ cards: true --- # Consensus + +Specification of the Tendermint consensus protocol. + +## Contents + +- [Consensus Paper](./consensus-paper) - Latex paper on + [arxiv](https://arxiv.org/abs/1807.04938) describing the + core Tendermint consensus state machine with proofs of safety and termination. +- [BFT Time](./bft-time.md) - How the timestamp in a Tendermint + block header is computed in a Byzantine Fault Tolerant manner +- [Creating Proposal](./creating-proposal.md) - How a proposer + creates a block proposal for consensus +- [Light Client Protocol](./light) - A protocol for light weight consensus + verification and syncing to the latest state +- [Signing](./signing.md) - Rules for cryptographic signatures + produced by validators. +- [Write Ahead Log](./wal.md) - Write ahead log used by the + consensus state machine to recover from crashes. + +The protocol used to gossip consensus messages between peers, which is critical +for liveness, is described in the [reactors section](/spec/reactors/consensus). + +There is also a [stale markdown description](consensus.md) of the consensus state machine +(TODO update this).