PBTS: spec reorganization, summary of changes on README.md (#399)

* PBTS: brief context and proposal added to README

* PBTS: summary of algorithmic solution added to README

* PBTS: Context section of README improved

* PBTS: fixing links and page titles

* PBTS: moved first drafts to v1/, links updated

* PBTS: added issues to README, link to arXiv PDF

* PBTS: brief context and proposal added to README

* PBTS: summary of algorithmic solution added to README

* PBTS: Context section of README improved

* PBTS: fixing links and page titles

* PBTS: moved first drafts to v1/, links updated

* PBTS: added issues to README, link to arXiv PDF

* Apply suggestions from code review

Co-authored-by: William Banfield <4561443+williambanfield@users.noreply.github.com>
Co-authored-by: Josef Widder <44643235+josef-widder@users.noreply.github.com>

* Fixing linting problems

Co-authored-by: Daniel Cason <cason@gandria>
Co-authored-by: William Banfield <4561443+williambanfield@users.noreply.github.com>
Co-authored-by: Josef Widder <44643235+josef-widder@users.noreply.github.com>

spec/consensus/proposer-based-timestamp/README.md

@@ -1,20 +1,157 @@
-# Proposer-Based Timestamps
+# Proposer-Based Timestamps (PBTS)
 
-This section describes a version of the Tendermint consensus protocol,
-which uses proposer-based timestamps.
+This section describes a version of the Tendermint consensus protocol
+that uses proposer-based timestamps.
 
-## Contents
+## Context
 
-- [Proposer-Based Time][main] (entry point)
-- [Part I - System Model and Properties][sysmodel]
-- [Part II - Protocol Specification][algorithm]
-- [TLA+ Specification][proposertla]
+Tendermint provides a deterministic, Byzantine fault-tolerant, source of time,
+defined by the `Time` field present in the headers of committed blocks.
 
+In the current consensus implementation, the timestamp of a block is
+computed by the [`BFTTime`][bfttime] algorithm:
 
-[algorithm]: ./pbts-algorithm_002_draft.md
+- Validators include a timestamp in the `Precommit` messages they broadcast.
+Timestamps are retrieved from the validators' local clocks,
+with the only restriction that they must be **monotonic**:
+
+    - The timestamp of a `Precommit` message voting for a block
+	cannot be earlier than the `Time` field of that block;
+
+- The timestamp of a block is deterministically computed from the timestamps of
+a set of `Precommit` messages that certify the commit of the previous block.
+This certificate, a set of `Precommit` messages from a round of the previous height,
+is selected by the block's proposer and stored in the `Commit` field of the block:
+
+    - The block timestamp is the *median* of the timestamps of the `Precommit` messages
+	included in the `Commit` field, weighted by their voting power.
+	Block timestamps are **monotonic** because
+	timestamps of valid `Precommit` messages are monotonic;
+
+Assuming that the voting power controlled by Byzantine validators is bounded by `f`,
+the cumulative voting power of any valid `Commit` set must be at least `2f+1`.
+As a result, the timestamp computed by `BFTTime` is not influenced by Byzantine validators,
+as the weighted median of `Commit` timestamps comes from the clock of a non-faulty validator.
+
+Tendermint does not make any assumptions regarding the clocks of (correct) validators,
+as block timestamps have no impact in the consensus protocol.
+However, the `Time` field of committed blocks is used by other components of Tendermint,
+such as IBC, the evidence, staking, and slashing modules.
+And it is used based on the common belief that block timestamps
+should bear some resemblance to real time, which is **not guaranteed**.
+
+A more comprehensive discussion of the limitations of `BFTTime`
+can be found in the [first draft][main_v1] of this proposal.
+Of particular interest is to possibility of having validators equipped with "faulty" clocks,
+not fairly accurate with real time, that control more than `f` voting power,
+plus the proposer's flexibility when selecting a `Commit` set,
+and thus determining the timestamp for a block.
+
+## Proposal
+
+In the proposed solution, the timestamp of a block is assigned by its
+proposer, according with its local clock.
+In other words, the proposer of a block also *proposes* a timestamp for the block.
+Validators can accept or reject a proposed block.
+A block is only accepted if its timestamp is acceptable.
+A proposed timestamp is acceptable if it is *received* within a certain time window,
+determined by synchronous parameters.
+
+PBTS therefore augments the system model considered by Tendermint with *synchronous assumptions*:
+
+- **Synchronized clocks**: simultaneous clock reads at any two correct validators
+differ by at most `PRECISION`;
+
+- **Bounded message delays**: the end-to-end delay for delivering a message to all correct validators
+is bounded by `MSGDELAY`.
+This assumption is restricted to `Proposal` messages, broadcast by proposers.
+
+`PRECISION` and `MSGDELAY` are consensus parameters, shared by all validators,
+that define whether the timestamp of a block is acceptable.
+Let `t` be the time, read from its local clock, at which a validator
+receives, for the first time, a proposal with timestamp `ts`:
+
+- **[Time-Validity]** The proposed timestamp `ts` received at local time `t`
+is accepted if it satisfies the **timely** predicate:
+	> `ts - PRECISION <= t <= ts + MSGDELAY + PRECISION`
+
+The left inequality of the *timely* predicate establishes that proposed timestamps
+should be in the past, when adjusted by the clocks `PRECISION`.
+The right inequality of the *timely* predicate establishes that proposed timestamps
+should not be too much in the past, more precisely, not more than `MSGDELAY` in the past,
+when adjusted by the clocks `PRECISION`.
+
+A more detailed and formalized description is available in the
+[System Model and Properties][sysmodel] document
+
+## Implementation
+
+The implementation of PBTS requires some changes in Tendermint consensus algorithm,
+summarized below:
 
-[sysmodel]: ./pbts-sysmodel_001_draft.md
+- A proposer timestamps a block with the current time, read from its local clock.
+The block's timestamp represents the time at which it was assembled
+(after the `getValue()` call in line 18 of the [arXiv][arXiv] algorithm):
 
-[main]: ./pbts_001_draft.md
+    - Block timestamps are definitive, meaning that the original timestamp
+	is retained when a block is re-proposed (line 16);
+
+    - To preserve monotonicity, a proposer might need to wait until its clock
+	reads a time greater than the timestamp of the previous block;
+
+- A validator only prevotes for *timely* blocks,
+that is, blocks whose timestamps are considered *timely* (compared to the original Tendermint consensus, a check is added to line 23).
+If the block proposed in a round is considered *untimely*,
+the validator prevotes `nil` (line 26):
+
+    - Validators register the time at which they received `Proposal` messages,
+	in order to evaluate the *timely* predicate;
+
+    - Blocks that are re-proposed because they received `2f+1 Prevotes`
+	in a previous round (line 28) are not subject to the *timely* predicate,
+	as they have already been evaluated as *timely* at a previous round.
+
+The more complex change proposed regards blocks that can be re-proposed in multiple rounds.
+The current solution improves the [first version of the specification][algorithm_v1] (that never had been implemented)
+by simplifying the way this situation is handled,
+from a recursive reasoning regarding valid blocks that are re-proposed.
+
+The full solution is detailed and formalized in the [Protocol Specification][algorithm] document.
+
+## Further details
+
+- [System Model and Properties][sysmodel]
+- [Protocol Specification][algorithm]
+- [TLA+ Specification][proposertla] (first draft, not updated)
+
+### Open issues
+
+- [PBTS: evidence #355][issue355]: not really clear the context, probably not going to be solved.
+- [PBTS: should synchrony parameters be adaptive? #371][issue371]
+- [PBTS: Treat proposal and block parts explicitly in the spec #372][issue372]
+- [PBTS: margins for proposal times assigned by Byzantine proposers #377][issue377]
+
+### Closed issues
+
+- [Proposer time - fix message filter condition #353][issue353]
+- [PBTS: association between timely predicate and timeout_commit #370][issue370]
+
+[main_v1]: ./v1/pbts_001_draft.md
+
+[algorithm]: ./pbts-algorithm_002_draft.md
+[algorithm_v1]: ./v1/pbts-algorithm_001_draft.md
+
+[sysmodel]: ./pbts-sysmodel_002_draft.md
+[sysmodel_v1]: ./v1/pbts-sysmodel_001_draft.md
 
 [proposertla]: ./tla/TendermintPBT_001_draft.tla
+
+[bfttime]: https://github.com/tendermint/spec/blob/master/spec/consensus/bft-time.md
+[arXiv]: https://arxiv.org/pdf/1807.04938.pdf
+
+[issue353]: https://github.com/tendermint/spec/issues/353
+[issue355]: https://github.com/tendermint/spec/issues/355
+[issue370]: https://github.com/tendermint/spec/issues/370
+[issue371]: https://github.com/tendermint/spec/issues/371
+[issue372]: https://github.com/tendermint/spec/issues/372
+[issue377]: https://github.com/tendermint/spec/issues/377

spec/consensus/proposer-based-timestamp/pbts-algorithm_002_draft.md

@@ -1,4 +1,4 @@
-# Proposer-Based Time v2 - Part II
+# PBTS: Protocol Specification
 
 ## Proposal Time
 
@@ -6,7 +6,7 @@ PBTS computes for a proposed value `v` the proposal time `v.time`, with bounded
 The proposal time is read from the clock of the process that proposes a value for the first time, its original proposer.
 
 With PBTS, therefore, we assume that processes have access to **synchronized clocks**.
-The proper definition of what it means can be found in the [system model][model],
+The proper definition of what it means can be found in the [system model][sysmodel],
 but essentially we assume that two correct processes do not simultaneous read from their clocks
 time values that differ more than `PRECISION`, which is a system parameter.
 
@@ -20,7 +20,7 @@ A value `v` should re-proposed when it becomes locked by the network, i.e., when
 This means that processes with `2f + 1`-equivalent voting power accepted, in round `r`, both `v` and its associated time `v.time`.
 Since the originally proposed value and its associated time were considered valid, there is no reason for reassigning `v.time`.
 
-In the [first version][v1] of this specification, proposals were defined as pairs `(v, time)`.
+In the [first version][algorithm_v1] of this specification, proposals were defined as pairs `(v, time)`.
 In addition, the same value `v` could be proposed, in different rounds, but would be associated to distinct times each time it was reproposed.
 Since this possibility does not exist in this second specification, the proposal time became part of the proposed value.
 With this simplification, several small changes to the [arXiv][arXiv] algorithm are no longer required.
@@ -38,8 +38,8 @@ it should postpone the generation of its proposal until `now_p > decision_p[h_p-
 > Although it should be considered, this scenario is unlikely during regular operation,
 as from `decision_p[h_p-1].time` and the start of height `h_p`, a complete consensus instance need to terminate.
 
-Notice that monotonicity is not introduced by this proposal, being already ensured by [`bfttime`][bfttime].
-In `bfttime`, the `Timestamp` field of every `Precommit` message of height `h_p` sent by a correct process is required to be larger than `decision_p[h_p-1].time`, as one of such `Timestamp` fields becomes the time assigned to a value proposed at height `h_p`.
+Notice that monotonicity is not introduced by this proposal, being already ensured by  [`BFTTime`][bfttime].
+In `BFTTime`, the `Timestamp` field of every `Precommit` message of height `h_p` sent by a correct process is required to be larger than `decision_p[h_p-1].time`, as one of such `Timestamp` fields becomes the time assigned to a value proposed at height `h_p`.
 
 The time monotonicity of values proposed in heights of consensus is verified by the `valid()` predicate, to which every proposed value is submitted.
 A value rejected by the `valid()` implementation is not accepted by any correct process.
@@ -48,7 +48,7 @@ A value rejected by the `valid()` implementation is not accepted by any correct
 
 PBTS introduces a new requirement for a process to accept a proposal: the proposal must be `timely`.
 It is a temporal requirement, associated with the following synchrony (that is, timing)
-[assumptions][model] regarding the behavior of processes and the network:
+[assumptions][sysmodel] regarding the behavior of processes and the network:
 
 - Synchronized clocks: the values simultaneously read from clocks of any two correct processes differ by at most `PRECISION`;
 - Bounded transmission delays: the real time interval between the sending of a proposal at a correct process, and the reception of the proposal at any correct process is upper bounded by `MSGDELAY`.
@@ -138,8 +138,11 @@ and because, since `v` was re-proposed as a `validValue` (line 16), `v.time` has
 
 Back to [main document][main].
 
-[arXiv]: https://arxiv.org/abs/1807.04938
-[v1]: ./pbts-algorithm_001_draft.md
-[main]: ./pbts_001_draft.md
-[bfttime]: https://github.com/tendermint/spec/blob/439a5bcacb5ef6ef1118566d7b0cd68fff3553d4/spec/consensus/bft-time.md
-[model]: ./pbts-sysmodel_002_draft.md
+[main]: ./README.md
+
+[algorithm_v1]: ./v1/pbts-algorithm_001_draft.md
+
+[sysmodel]: ./pbts-sysmodel_002_draft.md
+
+[bfttime]: https://github.com/tendermint/spec/blob/master/spec/consensus/bft-time.md
+[arXiv]: https://arxiv.org/pdf/1807.04938.pdf

spec/consensus/proposer-based-timestamp/pbts-sysmodel_002_draft.md

@@ -1,4 +1,4 @@
-# Proposer-Based Time v2 - Part I
+# PBTS: System Model and Properties
 
 ## System Model
 
@@ -37,7 +37,7 @@ from their local clocks, so that their clocks can be considered synchronized.
 
 #### Accuracy
 
-The [original specification][v1] included a second clock-related parameter, `ACCURACY`,
+The [first draft][sysmodel_v1] of this specification included a second clock-related parameter, `ACCURACY`,
 that relates the values read by processes from their synchronized clocks with real time:
 
 - If `p` is a process is equipped with a synchronized clock, then at real time
@@ -248,6 +248,11 @@ The precise behavior for this workaround is under [discussion](https://github.co
 
 Back to [main document][main].
 
-[main]: ./pbts_001_draft.md
-[v1]: ./pbts-sysmodel_001_draft.md
-[arXiv]: https://arxiv.org/abs/1807.04938
+[main]: ./README.md
+
+[algorithm]: ./pbts-algorithm_002_draft.md
+
+[sysmodel]: ./pbts-sysmodel_002_draft.md
+[sysmodel_v1]: ./v1/pbts-sysmodel_001_draft.md
+
+[arXiv]: https://arxiv.org/pdf/1807.04938.pdf