PBTS: migrating to main the new version of the specification

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 algorithm, adopted in CometBFT,
-which uses proposer-based timestamps.
+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_001_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**:
 
-[sysmodel]: ./pbts-sysmodel_001_draft.md
+    - The timestamp of a `Precommit` message voting for a block
+	cannot be earlier than the `Time` field of that block;
 
-[main]: ./pbts_001_draft.md
+- 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:
+
+- 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):
+
+    - 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]: ../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

@@ -0,0 +1,148 @@
+# PBTS: Protocol Specification
+
+## Proposal Time
+
+PBTS computes for a proposed value `v` the proposal time `v.time`, with bounded difference to the actual real-time the proposed value was generated.
+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][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.
+
+### Proposal times are definitive
+
+When a value `v` is produced by a process, it also assigns the associated proposal time `v.time`.
+If the same value `v` is then re-proposed in a subsequent round of consensus,
+it retains its original time, assigned by its original proposer.
+
+A value `v` should re-proposed when it becomes locked by the network, i.e., when it receives `2f + 1 PREVOTES` in a round `r` of consensus.
+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][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.
+
+## Time Monotonicity
+
+Values decided in successive heights of consensus must have increasing times, so:
+
+- Monotonicity: for any process `p` and any two decided heights `h` and `h'`, if `h > h'` then `decision_p[h].time > decision_p[h'].time`.
+
+For ensuring time monotonicity, it is enough to ensure that a value `v` proposed by process `p` at height `h_p` has `v.time > decision_p[h_p-1].time`.
+So, if process `p` is the proposer of a round of height `h_p` and reads from its clock a time `now_p <= decision_p[h_p-1]`,
+it should postpone the generation of its proposal until `now_p > decision_p[h_p-1]`.
+
+> 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`.
+
+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.
+
+## Timely Proposals
+
+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][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`.
+
+#### **[PBTS-RECEPTION-STEP.1]**
+
+Let `now_p` be the time, read from the clock of process `p`, at which `p` receives the proposed value `v`.
+The proposal is considered `timely` by `p` when:
+
+1. `now_p >= v.time - PRECISION`
+1. `now_p <= v.time + MSGDELAY + PRECISION`
+
+The first condition derives from the fact that the generation and sending of `v` precedes its reception.
+The minimum receiving time `now_p` for `v` be considered `timely` by `p` is derived from the extreme scenario when
+the clock of `p` is `PRECISION` *behind* of the clock of the proposer of `v`, and the proposal's transmission delay is `0` (minimum).
+
+The second condition derives from the assumption of an upper bound for the transmission delay of a proposal.
+The maximum receiving time `now_p` for `v` be considered `timely` by `p` is derived from the extreme scenario when
+the clock of `p` is `PRECISION` *ahead* of the clock of the proposer of `v`, and the proposal's transmission delay is `MSGDELAY` (maximum).
+
+## Updated Consensus Algorithm
+
+The following changes are proposed for the algorithm in the [arXiv paper][arXiv].
+
+#### New `StartRound`
+
+There are two additions to the `propose` round step when executed by the `proposer` of a round:
+
+1. to ensure time monotonicity, the proposer does not propose a value until its current local time becomes greater than the previously decided value's time
+1. when the proposer produce a new proposal it sets the proposal's time to its current local time
+   - no changes are made to the logic when a proposer has a non-nil `validValue`, which retains its original proposal time.
+
+#### **[PBTS-ALG-STARTROUND.1]**
+
+```go
+function StartRound(round) {
+ round_p ← round
+ step_p ← propose
+ if proposer(h_p, round_p) = p {
+  wait until now_p > decision_p[h_p-1].time // time monotonicity
+  if validValue_p != nil {
+   proposal ← validValue_p
+  } else {
+   proposal ← getValue()
+   proposal.time ← now_p // proposal time
+  }
+   broadcast ⟨PROPOSAL, h_p, round_p, proposal, validRound_p⟩
+ } else {
+  schedule OnTimeoutPropose(h_p,round_p) to be executed after timeoutPropose(round_p)
+ }
+}
+```
+
+#### New Rule Replacing Lines 22 - 27
+
+The rule on line 22 applies to values `v` proposed for the first time, i.e., for proposals not backed by `2f + 1 PREVOTE`s for `v` in a previous round.
+The `PROPOSAL` message, in this case, carry `-1` in its `validRound` field.
+
+The new rule for issuing a `PREVOTE` for a proposed value `v` requires the value to be `timely`.
+As the `timely` predicate is evaluated in the moment that the value is received,
+as part of a `PROPOSAL` message, we require the `PROPOSAL` message to be `timely`.
+
+#### **[PBTS-ALG-UPON-PROP.1]**
+
+```go
+upon timely(⟨PROPOSAL, h_p, round_p, v, −1⟩) from proposer(h_p, round_p) while step_p = propose do {
+  if valid(v) ∧ (lockedRound_p = −1 ∨ lockedValue_p = v) {
+    broadcast ⟨PREVOTE, h_p, round_p, id(v)⟩ 
+  }
+  else {
+    broadcast ⟨PREVOTE, h_p, round_p, nil⟩ 
+  }
+  step_p ← prevote
+}
+```
+
+#### Rules at Lines 28 - 33 remain unchanged
+
+The rule on line 28 applies to values `v` proposed again in the current round because its proposer received `2f + 1 PREVOTE`s for `v` in a previous round `vr`.
+This means that there was a round `r <= vr` in which `2f + 1` processes accepted `v` for the first time, and so sent `PREVOTE`s for `v`.
+Which, in turn, means that these processes executed the line 22 of the algorithm, and therefore judged `v` as a `timely` proposal.
+
+In other words, we don't need to verify whether `v` is a timely proposal because at least `f + 1` processes judged `v` as `timely` in a previous round,
+and because, since `v` was re-proposed as a `validValue` (line 16), `v.time` has not being updated from its original proposal.
+
+**All other rules remains unchanged.**
+
+Back to [main document][main].
+
+[main]: ./README.md
+
+[algorithm_v1]: ./v1/pbts-algorithm_001_draft.md
+
+[sysmodel]: ./pbts-sysmodel_002_draft.md
+
+[bfttime]: ../bft-time.md
+[arXiv]: https://arxiv.org/pdf/1807.04938.pdf