From 336de5f303e56010189be81287a5ddd96997b806 Mon Sep 17 00:00:00 2001 From: Eric Passmore Date: Mon, 3 Jun 2024 17:49:43 -0700 Subject: [PATCH] intro to finalizers and voting, vote peering --- .../04_upgrade-guide-spring-1-0.md | 3 ++ .../10_switch-to-savanna.md | 2 +- .../20_introduction_finalizers_voting.md | 16 ++++-- .../21_managing-finalizer-keys.md | 53 ++++++++++++++++--- 4 files changed, 62 insertions(+), 12 deletions(-) diff --git a/native/07_node-operation/100_migration-guides/04_upgrade-guide-spring-1-0.md b/native/07_node-operation/100_migration-guides/04_upgrade-guide-spring-1-0.md index 0e975e0..7b3ffaa 100644 --- a/native/07_node-operation/100_migration-guides/04_upgrade-guide-spring-1-0.md +++ b/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` diff --git a/native/07_node-operation/100_migration-guides/10_switch-to-savanna.md b/native/07_node-operation/100_migration-guides/10_switch-to-savanna.md index 4aedb38..9eb91bb 100644 --- a/native/07_node-operation/100_migration-guides/10_switch-to-savanna.md +++ b/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 diff --git a/native/60_advanced-topics/20_introduction_finalizers_voting.md b/native/60_advanced-topics/20_introduction_finalizers_voting.md index 5f3a72b..4b7a4b4 100644 --- a/native/60_advanced-topics/20_introduction_finalizers_voting.md +++ b/native/60_advanced-topics/20_introduction_finalizers_voting.md @@ -2,6 +2,13 @@ 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 @@ -36,8 +43,7 @@ Unlike block publishing, for the top 21 block producers, voting is continuous. T 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). -## 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 +### 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. diff --git a/native/60_advanced-topics/21_managing-finalizer-keys.md b/native/60_advanced-topics/21_managing-finalizer-keys.md index 44b9581..6d988fc 100644 --- a/native/60_advanced-topics/21_managing-finalizer-keys.md +++ b/native/60_advanced-topics/21_managing-finalizer-keys.md @@ -2,29 +2,54 @@ title: Managing 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. +Review [Introduction to Finalizers and Voting](introduction_finalizers_voting) for additional background. 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. ## Recommended Setup -The recommendation is to generate several finalizer keys. Generate one for each primary and backup node producer instance you plan on running. It is recommended to have only one active finalizer key for each producer. When switching over to a backup production node you may switch out your registered finalizer key to match the new instance coming online. When the keys are generated ahead of time, and included in the configuration, only a system action is needed to register a new key. +The recommendation is to generate, and register several finalizer keys. It is recommended to have one finalizer key for each instance of a producer node. A producer may have only one active finalizer key. When the keys are generated ahead of time, and included in the configuration, only an on-chain action is needed to use a new finalizer key. +### Multiple Instances of Nodeos +Consider the scenario where there are two hosts running nodeos. One host contains the primary block producer, the other host has the backup block producer. The recommendation is each instance of nodeos (primary producer and backup-producer) have distinct BLS finalizer keys. This requires creating and registering two BLS finalizer key pairs. The signature provider for each nodeos will reference one and only one BLS key. It is recommended that the signature provider in the primary producer node reference a different BLS finalizer key from the signature provider on the backup producer node. + +When switching to the backup node, run the usual scripts, and in addition activate the BLS finalizer key referenced in the signature provider configuration for the backup producer node. When switching back from the backup producer node to the primary producer node, in addition to running the usual scripts, you must active the BLS finalizer key associated with the primary block producer. + +If the same BLS finalizer key is used when switching between producers the voting history will not be complete. As a result the associated producer will vote for a different branch of the blockchain, out of sync with the correct state of the blockchain. + +### Multiple Producers on a Single Instance +Consider the scenario when there are multiple producers on a single instance of nodeos. The recommendation is to create, register, and activate unique and distinct finalizer keys for each producer. + +### Intermediate Relay Nodes +Setting `vote-threads` on a nodeos instance is expensive, consuming CPU and adding to network traffic. For this reason, `vote-threads` is set to a non-zero on node producer instances, but set to zero on all other instances. + +Block Producers may have an intermediate nodeos instance sitting in between their block producing nodeos and peer finalizers. In this setup each nodeos, local finalizer, intermediate node, and peer finalizer, must be able to send and forward votes. With this setup there would be a BLS finalizer key for the block producing nodes. The intermediate node would not need a BLS finalizer key. The intermediate node must set their `vote-threads` > 0 *default in Spring v1 is 4 threads*. + +### Rotating Keys +The EOS blockchain, allows producers to activate new BLS finalizer keys at anytime with an on-chain action `actfinkey`. Before called the `actfinkey` action, the key must already exist in the `signature-provider` configuration when the instance of nodeos is started, and the key must be registered using the `regfinkey` action. Activating a new BLS finalizer key is always safe, and may be performed at anytime. + +## Recovery If the database is dirty or corrupted the fastest way to re-start is from a snapshot with the same finalizer key and the same `finalizers/safety.dat`. This fast restart method is similar to previous versions of Leap software. - remove state `state/shared_memory.bin` and perhaps `blocks/blocks.log` - restart from snapshot - wait for node to catch up -A full recovery is more involved and it included using a different finalizer key. +A full recovery is more involved and it included using a different finalizer key. Use these steps when the `finalizers/safety.dat` is corrupted or missing. - remove state `state/shared_memory.bin` and perhaps `blocks/blocks.log` - remove `finalizers/safety.dat` - restart from snapshot -- use a new finalizer key, is `actfinkey` to activate a previously registered finalizer key +- use a new finalizer key, `actfinkey` to activate a previously registered finalizer key - wait for node to catch up ## Generating and Registering Finalizer Keys ### Importance of Finalizer Safety -Savanna consensus introduces a new file that captures the history of finalizer voting. By default the file `finalizers/safety.dat` and is found under the data directory. If `finalizers/safety.dat` is corrupted or removed, the voting history for the active key will be lost. Therefore when `finalizers/safety.dat` is un-useable a different BLS finalizer key should be activated. +Savanna consensus introduces a new file that captures the history of finalizer voting. See [Introduction to Finalizers and Voting](introduction_finalizers_voting) for more background on voting history and the role of the `finalizers/safety.dat` file. By default the file `finalizers/safety.dat` is found under the data directory. `finalizers/safety.dat` must have the full voting history for the BLS finalizer key that is in use. If `finalizers/safety.dat` is corrupted, removed, or lacks the full voting history for the BLS finalizer key in use, a new BLS finalizer key must be used. + +Spring v1 introduces a new configuration option `finalizers-dir` that can change the location of the `safety.dat` file. A node operator may want to change the location of `safety.dat`, if they want to move this important file out of the nodeos default data directory. -There is a new configuration option `finalizers-dir` that can change the location of the `safety.dat` file. A node operator may want to change the location of `safety.dat`, if they want to move this important file out of the nodeos default data directory. +### Pre-Generating Finalizer Keys +It is safe to generate many BLS finalizer keys and register them ahead of their use and activation. Registration includes: +- Creating the BLS key pair +- Adding the key pair to configuration via `signature-provider`, this requires a restart of nodeos +- Calling on-chain `regfinkey` action ### Generate Finalizer Keys `spring-utils` is the utility designated for node operators. Only node operators need to generate a BLS finalizer key, and for that reason we use `spring-utils` to generate the finalizer keys. Keys may be output to console (`--to-console`) or to file (`--file`). @@ -100,3 +125,19 @@ The configuration options specific to managing finality. It is recommended to us - `finalizers-dir` - Specifies the directory path for storing voting history. Node Operators may want to specify a directory outside of their nodeos' data directory, and manage this as distinct file. - `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. + +## Avoid +Review [Introduction to Finalizers and Voting](introduction_finalizers_voting) for additional background. Each of the following is likely to lead to voting on a different branch of the blockchain, and therefore votes will not contribute to finality. For best results do **NOT** the following: +- share `safety.dat` between hosts or producers +- reuse BLS finalizer keys between hosts +- backup and restore `safety.dat` + +## FAQ +- Q: Should I backup and restore `safety.dat`? +- A: No you should switch to a new BLS finalizer key, that is a much easier and safer way to continue voting. Otherwise you run the risk of restoring a partial voting history, and voting on the incorrect branch of the chain. + +- Q: When I want to switch producer hosts, can I keep using the same BLS Finalizer Key, and copy over my `safety.dat` to the new host? +- A: Yes this would work, but it is not recommended. Voting is continuous, and using a new BLS key takes an on-chain action. Therefore, it is best to switch over to a new BLS key assuming that results in less voting downtime. + +- Q: Why use BLS keys, why not re-use the existing producer keys. +- A: 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.