Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix Broken Links in Advanced Topics #248

Merged
merged 10 commits into from
Jul 4, 2024
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Please take care when managing the `safety.dat` file. Please do not share BLS ke
### 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).
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.
Expand Down
6 changes: 3 additions & 3 deletions native/60_advanced-topics/21_managing-finalizer-keys.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Managing Finalizer Keys
---

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.
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, 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.
Expand Down Expand Up @@ -48,7 +48,7 @@ A full recovery is more involved and it included using a different finalizer key
## Generating and Registering Finalizer Keys

### Importance of Finalizer Safety
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.
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.

Expand Down Expand Up @@ -134,7 +134,7 @@ The configuration options specific to managing finality. It is recommended to us
- `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:
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`
Expand Down
Loading