From ca21cb28f4125622c899e78e178f5fbed77f685c Mon Sep 17 00:00:00 2001 From: William Banfield Date: Wed, 2 Mar 2022 11:41:46 -0500 Subject: [PATCH] docs: add an overview of the proposer-based timestamps algorithm --- .../consensus/proposer-based-timestamps.md | 89 +++++++++++++++++++ spec/abci/apps.md | 13 +++ 2 files changed, 102 insertions(+) create mode 100644 docs/tendermint-core/consensus/proposer-based-timestamps.md diff --git a/docs/tendermint-core/consensus/proposer-based-timestamps.md b/docs/tendermint-core/consensus/proposer-based-timestamps.md new file mode 100644 index 000000000..35c320ed6 --- /dev/null +++ b/docs/tendermint-core/consensus/proposer-based-timestamps.md @@ -0,0 +1,89 @@ +--- +order: 3 +--- + +# Proposer-Based Timestamps + + This document provides an overview of the Proposer-Based Timestamp algorithm + added to Tendermint in the v0.36 release. This document outlines the core functionality + as well as the parameters and constraints of the this algorithm. + +# Algorithm Overview + +The proposer-based timestamps algorithm defines a way for a Tendermint blockchain +to create block timestamps that are within a reasonable bound of the clocks of the +validators on the network. + +## Algorithm Parameters + +The functionality of the Proposer-Based Timestamps algorithm is governed by two +parameters within Tendermint. These two parameters are [consensus parameters](https://github.com/tendermint/tendermint/blob/c42c6d06d2986791ad1cb8742824818edd9b6323/spec/abci/apps.md#L291), +meaning they are configured by the ABCI application and are expected to be the +same across all nodes on the network. + +### `Precision` + +The `Precision` parameter configures the acceptable upper-bound of clock drift among +all of the nodes on a Tendermint network. Any two nodes on a Tendermint network +are expected to have clocks that differ by at most `Precision` seconds? Ms? at +any given instant. + +### `MessageDelay` + +The `MessageDelay` parameter configures the acceptable upper-bound for transmitting +a `Proposal` message from the proposer to _all_ of the validators on the network. + +Networks that want very tight bounds on their timestamps should set a smaller value +for `MessageDelay`. Highly distributed networks or networks with generally slow +rates of transmission should set a larger value for `MessageDelay`. + +## Algorithm Concepts + +### Block timestamps + +Each block produced by the Tendermint consensus engine contains a timestamp. +The timestamp produced in each block is a meaningful representation of time that is +useful for the protocols and applications built on top of Tendermint. + +The following protocols and application features require a reliable source of time: + +* Tendermint Light Clients [rely on correspondence between their known time](https://github.com/tendermint/tendermint/blob/master/spec/light-client/verification/README.md#definitions-1) and the block time for block verification. +* Tendermint Evidence validity is determined [either in terms of heights or in terms of time](https://github.com/tendermint/tendermint/blob/master/spec/consensus/evidence.md#verification). +* Unbonding of staked assets in the Cosmos Hub [occurs after a period of 21 days](https://github.com/cosmos/governance/blob/master/params-change/Staking.md#unbondingtime). +* IBC packets can use either a [timestamp or a height to timeout packet delivery](https://docs.cosmos.network/v0.44/ibc/overview.html#acknowledgements) + +### Proposer Selects a Block Timestamp + +When the proposer node creates a new block proposal, the node reads the time from +its local clock and uses this reading as the timestamp for the proposed block. + +### Timely-ness + +When each validator on a Tendermint network receives a proposed block, it performs +a series of checks to ensure that the block can be considered valid as a candidate +to be the next block in the chain. + +The Proposer-Based Timestamps algorithm performs a validity check on the timestamp of proposed blocks. +When a validator receives a proposal it ensures that the timestamp in the proposal +is within a bound of the validator's local clock. Specifically, the algorithm +checks that the timestamp is no more than `Precision` greater than the node's local clock +and no less than `Precision` + `MessageDelay` behind than the node's local clock. +This creates range of acceptable timestamps around the node's local time. If +the timestamp is within this range, the Proposer-Based Timestamps algorithm considers +the block `timely`. If a block is not `timely`, the node will issue a `nil` `prevote` +for this block, signaling to the rest of the network that the node does not consider +the block to be valid. + +### Clock Synchronization + +The Proposer-Based Timestamps algorithm requires the clocks of the validators on a +Tendermint network are within `Precision` of each other. In practice, this means +that validators should periodically synchronize to a reliable NTP server. Validators +that drift too far away from the rest of the network will no longer propose +blocks with valid timestamps. Additionally they will not view the timestamps of blocks proposed +by their peers to be valid either. + +## See Also + +* [The Proposer-Based Timestamps specification][https://github.com/tendermint/tendermint/blob/master/spec/consensus/proposer-based-timestamp/README.md] contains all of the details of +the algorithm. diff --git a/spec/abci/apps.md b/spec/abci/apps.md index 030a3d3c3..d6ec19832 100644 --- a/spec/abci/apps.md +++ b/spec/abci/apps.md @@ -346,6 +346,19 @@ a block minus it's overhead ( ~ `MaxBytes`). Must have `MaxNum > 0`. +### SynchronyParams.Precision + +`SynchronyParams.Precision` is a parameter of the Proposer-Based Timestamps algorithm. +that configures the acceptable upper-bound of clock drift among +all of the nodes on a Tendermint network. Any two nodes on a Tendermint network +are expected to have clocks that differ by at most `Precision`. + +### SynchronyParams.MessageDelay + +`SynchronyParams.MessageDelay` is a parameter of the Proposer-Based Timestamps +algorithm that configures the acceptable upper-bound for transmitting a `Proposal` +message from the proposer to all of the validators on the network. + ### Updates The application may set the ConsensusParams during InitChain, and update them during