Rewrite with just one PoH Recorder

book/src/leader-validator-transition.md

@@ -1,87 +1,74 @@
 # Leader-to-Validator Transition
 
 A fullnode typically operates as a validator. If, however, a staker delegates
-its stake to a fullnode, it will occationally be selected as a *slot leader*.
-As a slot leader, the fullnode is resposible for producing blocks during an
-assigned *slot*. A slot has a duration of some number of preconfigured
-*ticks*. The duration of those ticks are estimated with a *PoH Generator*
-described later in this document.
+its stake to a fullnode, it will occasionally be selected as a *slot leader*.
+As a slot leader, the fullnode is responsible for producing blocks during an
+assigned *slot*. A slot has a duration of some number of preconfigured *ticks*.
+The duration of those ticks are estimated with a *PoH Recorder* described later
+in this document.
 
 ## BankFork
 
-BankFork tracks changes to the bank state over a specific slot.  Once the
-final tick has been registered the state is frozen. Any attempts to write
-to are rejected.
+BankFork tracks changes to the bank state over a specific slot.  Once the final
+tick has been registered the state is frozen. Any attempts to write to are
+rejected.
 
 ## Validator
 
 A validator operates on many different concurrent forks of the bank state until
-it can prove a PoH record at a height within the slot it is scheduled to be
-the slot leader.
+it can prove a PoH record at a height within the slot it is scheduled to be the
+slot leader.
 
 ## Slot Leader
 
 A slot leader builds blocks on top of only one fork, the one it last voted on.
 
-## PoH
+## PoH Recorder
 
-Slot leaders and validators use different objects for managing PoH. Each object only
-works for a specific range of ticks and will exit the loop when it is done.
+Slot leaders and validators use a PoH Recorder for both estimating slot height
+and for recording transactions.
 
-### PoH Generator
+### PoH as a Validators
 
-The PoH Generator generates a PoH stream for a Validator.  It solves the following
-problems for validators:
+The PoH Recorder acts as a simple VDF when validating. It tells the validator
+when it needs to switch to the slot leader role. Every time the validator votes
+on a fork, it should use the fork's latest block id to re-seed the VDF.
+Re-seeding solves two problems. First, it synchronizes its VDF to the leader's,
+allowing it to more accurately determine when its leader slot begins. Second,
+if the previous leader goes down, all wallclock time is accounted for in the
+next leader's PoH stream. For example, if one block is missing when the leader
+starts, the block it produces should have a PoH duration of two blocks. The
+longer duration ensures the following leader isn't attempting to snip all the
+transactions from the previous leader's slot.
 
-1. Keep track of *time* as defined by PoH height and stop the validator when it
-hits the scheduled leader slot.
+### PoH as a Slot Leader
 
-2. Reset the clock whenever a validator votes.  The last validator vote is the
-validators most recent commitment. It is therefore the closest fork to the
-scheduled slot.
+A slot leader use the PoH Recorder to record transactions, locking their
+positions in time. The PoH hash must be derived from a previous leader's last
+block.  If it isn't, its block will fail PoH verification and be rejected by
+the cluster.
 
-3. Provide the entries that connect the last vote to the scheduled slot.
+The PoH Recorder also serves to inform the slot leader when its slot is over.
+The leader needs to take care not to modify its bank if recording the
+transaction would generate a PoH height outside its designated slot.  The
+leader, therefore, should not commit account changes until after it generates
+the entry's PoH hash. When the PoH height falls outside its slot any
+transactions in its pipeline may be dropped or forwarded to the next leader.
+Forwarding is preferred, as it would minimize network congestion, allowing the
+cluster to advertise higher TPS capacity.
 
-The interface to this object implements the following methods:
-
-* new - Start the PoH thread, and compute it until end\_ticks.  This method
-would take the starting hash the starting tick height and ending tick height and
-create a PoH thread that runs until the end.
-
-* restart - Restart the PoH thread at a new hash and reset height.  It still
-runs until the configured ending tick height.
-
-* final\_entries - Get the entries that connect the set of entries from the
-restart point to the final tick as specified by new.
-
-### PoH Recorder
-
-This object handles PoH recording for a slot leader.  It solves the following
-problems:
-
-1. Keep track of *time* as defined by PoH height, and stop the leader when it
-gets to the end of its scheduled leader slot.
-
-2. Register ticks with the BankFork as they are produced by PoH.
-
-3. Record entries that are produced by the TPU into PoH.
-
-* new - Create a new recorder, with the starting entries as generated by the
-Generator.  The recorder runs until the ending tick height, and registers ticks
-with a BankFork.
-
-* record - Adds a vector of transactions to PoH, and register the tick with BankFork.
 
 ## Fullnode Loop
 
-This object manages the transition between modes.  The main idea is that once a
-ledger is replayed, the validator can run until there is proof that it can be a
-leader.  The slot leader can then execute and record its transactions.
+The PoH Recorder manages the transition between modes. Once a ledger is
+replayed, the validator can run until the recorder indicates it should be
+the slot leader. As a slot leader, the node can then execute and record
+transactions.
 
-The core idea is that the loop is synchronized to PoH and does a synchronous
-start and stop of the slot leader functionality. After stopping, the validator's
-TVU should find itself in the same state as if a different leader had sent it
-the same block. The following is pseudocode for the loop:
+The loop is synchronized to PoH and does a synchronous start and stop of the
+slot leader functionality. After stopping, the validator's TVU should find
+itself in the same state as if a different leader had sent it the same block.
+The following is pseudocode for the loop:
 
 The fullnode loop:
 
@@ -92,28 +79,26 @@ These components are passed in into the loop from the outside.
 * leader\_scheduler - The leader\_scheduler generated by replaying the ledger.
 
 * cluster\_info -  The network. The code to continuously receive and retransmit
-blocks is owned by this.
+  blocks is owned by this.
 
 * block\_tree -  The ledger.
 
 loop:
 
-1. Query the leader\_schedular for the next assigned slot.
+1. Query the leader\_scheduler for the next assigned slot.
 
 2. Run the TVU over all the forks.
 
    1. TVU will send votes to what it believes is the "best" fork.
-   2. After each vote, restart the PoH Generator to run until the next assigned slot.
-
-3. Wait for PoH generator to finish.
-
-4. Start a PoH recorder at the last hash of the PoH Generator.
+   2. After each vote, restart the PoH Recorder to run until the next assigned
+slot.
 
-5. Start the TPU. Point it to the last fork the TVU voted on.
+3. When time to be a slot leader, start the TPU. Point it to the last fork the
+   TVU voted on.
 
-6. Wait for the PoH recorder to finish.
+4. Produce entries until the end of the slot.
 
    1. TPU will freeze BankFork.  The vote will be sent in 2.
 
-7. Goto 1.
+5. Goto 1.