mirrors/tendermint
1
0
Fork 0
mirror of https://github.com/tendermint/tendermint.git synced 2026-05-22 23:21:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add an overview of the proposer-based timestamps algorithm

Browse Source
This commit is contained in:
William Banfield
2022-03-02 11:41:46 -05:00
parent c42c6d06d2
commit ca21cb28f4
2 changed files with 102 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

89
docs/tendermint-core/consensus/proposer-based-timestamps.md Normal file
View File

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

13
spec/abci/apps.md
View File

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