docs: add an overview of the proposer-based timestamps algorithm#8058
docs: add an overview of the proposer-based timestamps algorithm#8058mergify[bot] merged 3 commits intomasterfrom
Conversation
tychoish
left a comment
There was a problem hiding this comment.
I like this writing and think it's clear and provides the necessary background.I just have a few structural comments.
One of the facts of PBTS is "it replaces a system for choosing timestamps that was more arbitrary and required even less synchrony," which I think helps understand why it is the way it is, but I don't know that it... is worth including this in the document anywhere
| ## 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), |
There was a problem hiding this comment.
does it make sense to link to specific revision here?
| 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 |
There was a problem hiding this comment.
I think all of the section headings shuold be +1 level as the overview and the intro paragraph shouldn't be siblings
creachadair
left a comment
There was a problem hiding this comment.
A handful of minor suggestions, but no big comments. LGTM!
|
|
||
| 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. |
There was a problem hiding this comment.
Perhaps:
This replaces the original BFTTime algorithm for timestamp assignment based on the timestamps of previous blocks.
| 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`. |
There was a problem hiding this comment.
As @tychoish would say, it's nice to want things 🙂. Perhaps we should frame this so the reader can see a rubric, e.g., "Networks should choose as small a value of MessageDelay as is practical, provided it is large enough that messages can reach all participants with high probability given the size and latency of their connections."
The wording here probably needs work, but I hope that illustrates the idea: Not just why to increase it or decrease it, but what the mutual constraints are.
| 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. |
There was a problem hiding this comment.
You could probably define "PBTS" as shorthand in the introduction and use that throughout for simplicity.
|
|
||
| Networks should choose as small a value for `MessageDelay` as is practical, | ||
| provided it is large enough that messages can reach all participants with high | ||
| probability given the number of participants and latency of their connections. |
There was a problem hiding this comment.
Should we mention here the workaround in case of under-estimation of MessageDelay parameter?
| 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 |
| 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 |
|
|
||
| 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. |
There was a problem hiding this comment.
I would refer that if the same block is reproposed, its timestamps stay the same (original one).
| ### Clock Synchronization | ||
|
|
||
| The PBTS algorithm requires the clocks of the validators on a Tendermint network | ||
| are within `Precision` of each other. In practice, this means that validators |
There was a problem hiding this comment.
are within
Precisionof each other.
To be within?
|
|
||
| The PBTS 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 |
Part of #1731. Forward ported changes from PRs: - tendermint/tendermint#8058 - tendermint/tendermint#8129 - tendermint/tendermint#8454 Plus, updated metrics list on `docs/core/metrics.md`, with PBTS and also other added metrics. --- #### PR checklist - [ ] ~Tests written/updated~ - [ ] ~Changelog entry added in `.changelog` (we use [unclog](https://github.com/informalsystems/unclog) to manage our changelog)~ - [x] Updated relevant documentation (`docs/` or `spec/`) and code comments - [x] Title follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) spec --------- Co-authored-by: William Banfield <4561443+williambanfield@users.noreply.github.com>
This change adds an overview of the proposer-based timestamps algorithm. The goal of this documentation is to give a plain enough explanation of the algorithm so that application developers and validators can understand both the utility of the algorithm and understand how the new constraints may affect their network and topology.
I'm blanking on the scheme we decided on for docs linking, so if anyone could remind me what link format we decided on, I'll go clean that up ASAP.
Once this is merged, I intend to create a runbook for chains that see slower block-times or higher nil prevotes and link that runbook to this document to provide a higher-level overview.
closes: #8046