Background on Finalizers and Voting (#242)

* up guides to reflect Savanna
* intro to finalizers and voting, vote peering
* renamed no-hyphen intro finalizers and voting

native/07_node-operation/100_migration-guides/04_upgrade-guide-spring-1-0.md

@@ -92,6 +92,9 @@ State history log file compression has been disabled. Consumers with state histo
 - `finality-data-history` - When running SHiP to support Inter-Blockchain Communication (IBC) set `finality-data-history = true`. This will enable the new field, `get_blocks_request_v1`. The `get_blocks_request_v1` defaults to `null` before Savanna Consensus is activated.
 - `vote-threads` - Sets the number of threads to handle voting. The default is sufficient for all know production setups, and the recommendation is to leave this value unchanged.
 
+### Set Vote-Threads
+Where there is a block producing node that connects to its peers through an intermediate nodeos, the intermediate nodeos will need to have a value > 0 for `vote-threads`. The default value for `vote-threads` is 4. When `vote-threads` is 0 votes are not propagated.
+
 ### Finalizer Keys
 The Savanna Consensus algorithm utilized by Spring v1 separates the roles of publishing blocks from signing and finalizing blocks. Finalizer Keys are needed to sign and finalize blocks. In Spring v1, all block producers are expected to be finalizers. There are three steps to creating finalizer keys
 - generate your key(s) using `spring-utils`

native/07_node-operation/100_migration-guides/10_switch-to-savanna.md

@@ -12,7 +12,7 @@ There are four steps
    - First activate protocol feature `BLS_PRIMITIVES2`
    - See section below on [Generate and Registering Finalizer Keys](#generate-and-registering-finalizer-keys)
 3. Activate required protocol features
-   - Activate `INSTANT_FINALITY` protocol feature
+   - Activate `SAVANNA` protocol feature
 4. `eosio` user calls `switchtosvnn` action
 
 ### Antelope Software Requirements
@@ -24,7 +24,7 @@ Switching to Savanna will required the latest version of Spring Software and the
 
 ### Protocol Features Dependencies
 The reference for protocol features with their corresponding hashes may be found in [bios-boot-tutorial](https://github.com/AntelopeIO/spring/blob/main/tutorials/bios-boot-tutorial/bios-boot-tutorial.py).
-The protocol feature `INSTANT_FINALITY` depends on the following protocol features being active_schedule
+The protocol feature `SAVANNA` depends on the following protocol features being active_schedule
 - `WTMSIG_BLOCK_SIGNATURES`
 - `BLS_PRIMITIVES2`
 - `DISALLOW_EMPTY_PRODUCER_SCHEDULE`

native/60_advanced-topics/20_introduction-finalizers-voting.md

@@ -0,0 +1,49 @@
+---
+title: Introduction to Finalizers and Voting
+---
+
+## Takeaways
+- Do not share BLS keys between hosts
+- It is always safe to activate new, never used BLS keys
+- Voting is continuous, try to keep your producer active between rounds
+- Finality is a separate role tied to the authority of the top 21 block producers
+
+## Introduction to Finalizers and Voting
+The EOS blockchain bundles together transactions into blocks, and working across 21 producers comes to a consensus on those blocks before marking them as irreversible. EOS continues to advance its blockchain technology, and to improves liveness and safety of the EOS blockchain, has added Finalizers in Spring v1.0. Finalizers enable the blockchain to mark blocks as irreversible seconds after they are published. This improvement in time to finality does not come at the cost of safety. Marking a block as irreversible continues to require agreement from 15 out of the top 21 producers.
+
+## Finalizer
+In Spring v1.0, Finalizers are tightly coupled to the role of the block producer and publisher. Only the top 21 block producers may vote to advance finality. The top block producers are determined by the votes they receive from community members who stake their EOS. This distributed proof of stake remains unchanged and continues the distributed governance model that has worked so well for EOS. Starting with Spring v1.0, block producers have the authority to run two separate functions.
+- Block Publish: Bundles together transactions into a block, and links that block and transaction to previous blocks and transactions.
+- Finalizer: Cryptographic verification of the on-chain transactions
+
+To lower the time to irreversible blocks, also know as time to finality, producers must exchange information about the state of the chain more frequently. Starting in Spring v1.0 the top 21 producers vote and successful votes are included with every block that is produced. In Spring v1.0 blocks are produced every 500ms. These votes are later aggregated and verified. If there is agreement about the state of the block chain finality is advanced. The Finalizer is the software responsible for aggregating votes, performing cryptographically verification, and determining if finality may be advanced.
+
+### Block Publisher Rounds
+The top block producers alternate publishing blocks on a schedule determined by their accumulated votes. This publishing period is called a round. If a publisher is unavailable during its round, that publisher is skipped over and another publisher takes their place.
+
+### Voting Overview
+Unlike the Block Publishing process, voting does not have a schedule. There are no rounds. The top 21 block producers submit votes on every block. Agreement on the state of the chain from 15 of the top 21 is required before a block may be marked as irreversible. Unlike the Block Publishing, there is no schedule for voting. Currently there is no penalty if a block producer's vote is not included as part of the finality calculation. If the EOS blockchain fails to get votes, or those votes disagree on the state of the chain, finality will not advance, and the last irreversible block will remain unchanged.
+
+Votes include a cryptographically signed digest for the Merkle tree representing the current state of the blockchain. As the chain adds transactions and changes those digest will change. To quickly and efficiently vote each Finalizer has a `safety.dat` file which stores this history of votes, and the digest that have been voted on. The digest stored in the history file is used as a reference point for calculating future digests from incoming blocks and transactions.
+
+### BLS Keys and Signature
+Voting creates signed digests using BLS Keys. BLS signatures are very cheap to aggregate together into a single message, and this property makes them a good choice for aggregating together votes from many different finalizers. The property also makes it cheap to support a large set of BLS signatures, and allows block producers to leverage multiple BLS keys.
+
+### Keys and Voting History
+There is an implicit link between the BLS Key used to sign votes, and the voting history stored in `safety.dat`.
+
+The voting history stored in `safety.dat` includes signed digests using the BLS key registered during voting. As we mentioned previously, this history is used to generate new votes. If the `safety.dat` does not contain the full voting history for a BLS Key, the votes will not be correct. When a partial voting history is included in the `safety.dat` that block producer will vote for a different branch of the blockchain. This will create a vote that does not contribute to finality.
+
+Activating a new, never used, BLS Key is always safe. There is no voting history for a new, never used key.
+
+Please take care when managing the `safety.dat` file. Please do not share BLS keys across hosts, or reuse the same BLS key when moving from host to host. Sharing and reuse of BLS Keys may result in a corrupted or partial voting history.
+
+### Continuous Voting
+Unlike block publishing, for the top 21 block producers, voting is continuous. Taking a producer offline would prevent that producer from voting to advance finality. To support continuous voting and manage various support scenarios the EOS blockchain provides on chain actions to register, activate, and delete BLS Keys. Using these actions, a producer can quickly rotate to a new BLS Key.
+
+For this reason it is recommended that each producer instance uses its own unique BLS Key, and activates the BLS Key when going online. There are many strategies for [managing BLS Keys](managing-finalizer-keys).
+
+### Voting and Peering
+All the nodeos instance from the source of the votes, to the receiver of the votes, along with any intermediate nodes must be configured to send, receive, and propagate votes. This is accomplished by enabling the vote-threading pools, configuring `vote-threads` to a value greater than zero. By default `vote-threads` is greater than zero on all block production nodes. Therefore, when two finalizers are directly peered, votes are sent and received with no additional configuration changes needed.
+
+When nodeos instances are not directly connected, and an intermediate nodeos instance is present, the intermediate nodes must update their configuration to enable vote-threading. Failure to enable vote-threading on intermediate nodes will prevent the finalizer votes associated your producer from reaching peers.