From 9af561102520427603253c1a695d93622535b691 Mon Sep 17 00:00:00 2001 From: Eric Passmore Date: Tue, 4 Jun 2024 09:03:50 -0700 Subject: [PATCH 1/5] fix unresolved merge conflict --- .../100_migration-guides/10_switch-to-savanna.md | 4 ---- 1 file changed, 4 deletions(-) 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 2bc5ef9..888fec2 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 @@ -38,11 +38,7 @@ The Savanna Consensus algorithm utilized by Spring v1 separates the roles of pub - restart nodeos with the new `signature-provider` config - register a single key on chain with the `regfinkey` action -<<<<<<< HEAD -Additional information on Finalizer Keys may be found in [Guide to Managing Finalizer Keys](../../advanced-topics/managing-finalizer-keys) and [Introduction to Finalizers and Voting](introduction_finalizers_voting) -======= Additional information on Finalizer Keys may be found in [Guide to Managing Finalizer Keys](../../advanced-topics/managing-finalizer-keys) and [Introduction to Finalizers and Voting](../../advanced-topics/introduction_finalizers_voting). ->>>>>>> ehp/spring-docs-v1 ### Confirmation of Consensus Algorithm The action `switchtosvnn`, initiates the change to the Savanna Consensus Algorithm, and must be called by the owner of the system contracts. On EOS Mainnet this would be the `eosio` user. This is event is called only once per chain. From 060cac09ba6c598e504624d3653ee011d132b8d0 Mon Sep 17 00:00:00 2001 From: Eric Passmore Date: Tue, 4 Jun 2024 09:26:00 -0700 Subject: [PATCH 2/5] fix broken links --- .../100_migration-guides/10_switch-to-savanna.md | 2 +- native/60_advanced-topics/21_managing-finalizer-keys.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) 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 888fec2..1f8d513 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 @@ -38,7 +38,7 @@ The Savanna Consensus algorithm utilized by Spring v1 separates the roles of pub - restart nodeos with the new `signature-provider` config - register a single key on chain with the `regfinkey` action -Additional information on Finalizer Keys may be found in [Guide to Managing Finalizer Keys](../../advanced-topics/managing-finalizer-keys) and [Introduction to Finalizers and Voting](../../advanced-topics/introduction_finalizers_voting). +Additional information on Finalizer Keys may be found in [Guide to Managing Finalizer Keys](../../advanced-topics/managing-finalizer-keys) and [Introduction to Finalizers and Voting](../../advanced-topics/introduction-finalizers-voting). ### Confirmation of Consensus Algorithm The action `switchtosvnn`, initiates the change to the Savanna Consensus Algorithm, and must be called by the owner of the system contracts. On EOS Mainnet this would be the `eosio` user. This is event is called only once per chain. diff --git a/native/60_advanced-topics/21_managing-finalizer-keys.md b/native/60_advanced-topics/21_managing-finalizer-keys.md index 224511c..6b09e6a 100644 --- a/native/60_advanced-topics/21_managing-finalizer-keys.md +++ b/native/60_advanced-topics/21_managing-finalizer-keys.md @@ -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. @@ -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. @@ -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` From 1ebcec1fbc12c26804d9232bb2d3a30092cba3ea Mon Sep 17 00:00:00 2001 From: Eric Passmore Date: Thu, 27 Jun 2024 17:44:05 -0700 Subject: [PATCH 3/5] more specific steps to upgrade guide --- .../04_upgrade-guide-spring-1-0.md | 77 +++++++++++++++---- 1 file changed, 61 insertions(+), 16 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 7b3ffaa..9561979 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 @@ -2,10 +2,63 @@ title: Spring 1.0 Upgrade Guide --- -## Summary -This upgrade guide covers the steps for upgrading the Spring binary from a Leap v5 binary. The Node Operator's guide [Switching Over To Savanna Consensus Algorithm](switch-to-savanna) covers the steps needed to upgrade the consensus algorithm. Node Producers will be interested in [Guide to Managing Finalizer Keys](../../advanced-topics/managing-finalizer-keys) - -## HTTP Changes +## Purpose +This upgrade guide covers the steps for upgrading a node to the Spring binary from a Leap v5 binary. The Node Operator's guide [Switching Over To Savanna Consensus Algorithm](switch-to-savanna) covers the steps needed to upgrade the consensus algorithm. Node Producers will be interested in [Guide to Managing Finalizer Keys](../../advanced-topics/managing-finalizer-keys) + +### Summary of Changes +- [Exceeding number of in flight requests or Mb in flight now returns HTTP 503](#updated-error-codes) +- [`v1/chain/get_block_header_state` has been updated](#get-block-header-state-changed) +- [`producer-threads` is no longer a supported option](#producer-threads-removed) +- [New v7 snapshot log format](#snapshot-format) +- [State logs no longer compressed](#state-log-history-compression-disabled) +- [Added BLS Finalizer Keys to support new consensus algorithm](#finalizer-keys) +- [New Finalizer Configuration Options](#new-finalizer-configuration-options) +- [New Vote-Threads Configuration Option](#new-vote-threads-option) + +## Upgrade Steps + +### Upgrade Steps for Non-Producer Nodes +Spring v1 must restart from a snapshot or recovered from a full transaction sync due to structural changes to the state memory storage. Snapshots from version 3.1 and higher of nodeos may be used to start a Spring node. + +Below are example steps for restarting from snapshot on ubuntu: +- Download latest release + - Head to the [Spring Releases](https://github.com/AntelopeIO/spring/releases) to download the latest version +- Create a new snapshot + - `curl -X POST http://127.0.0.1:8888/v1/producer/create_snapshot` + Wait until curl returns with a JSON response containing the filename of the newly created snapshot file. +- Stop nodeos +- Remove old package + - `sudo apt-get remove -y leap` +- Remove the `shared_memory.bin` file located in nodeos' data directory. This is the only file that needs to be removed. The data directory will be the path passed to nodeos' `--data-dir` argument, or `$HOME/local/share/eosio/nodeos/data/state` by default. +- Install new package + - `apt-get install -y ./antelope-spring_1.0.0_amd64.deb` +- Restart nodeos with the snapshot file returned from the `create_snapshot` request above. Add the `--snapshot` argument along with any other existing arguments. + - `nodeos --snapshot snapshot-1323.....83c5.bin ...` + This `--snapshot` argument only needs to be given once on the first launch of a 5.x nodeos. + +### Upgrade Steps for Producer Nodes +For producer nodes, in addition to the [Steps Above](#upgrade-steps-for-non-producer-nodes) there are a few other steps. Additional Documentation on BLS finalizer keys may be found in [Guide to Managing Finalizer Keys](../../advanced-topics/managing-finalizer-keys) + +- Remove the unsupported `producer-threads` option from your configuration. +- Generate your key(s) using `spring-utils` + - `spring-util bls create key --to-console > producer-name.finalizer.key` +- Add `signature-provider` to configuration with the generated Public and Private keys. + - You may configure multiple `signature-provider`, and have multiple name/value pairs for `signature-provider`. Example in your configuration file + ``` + signature-provider = PUB_BLS_S7aaZZ7ZdvnZ7Z7Za7SV7ZZZ-ZZtaa7ZaiLaaSPp7aZnaa7aZZnZd77BuS7ZZa7Zra7SU7ZZZZnaZaZZreZZZ7rraaZZZs7-i7Z7ive7aZZLZTas77VZtZL7a7aaZZaZL7sauZ=ZZZ:PVT_BLS_Z7tZLZZaZZ7o7LZ7aaa7uaBe7rLdPVZBpsZLrUaZZBUt-a7Z + signature-provider = PUB_BLS_7ZLauuZ777ZvSa_Z7ZTrZaZ7_eraa7a7aUanv7aZZ7ZaaZdZaaadaZr-agi7_aoZa77aZZZZZaZU7aB7a7TZ-ZZu777777gaSaarZ7udZs7S-aZ-ZZZ_SBa-iZZPaZZZ7Za7rg=ZZZ:PVT_BLS_Znsaa7uZ7iZZ7uZ7aZZe7raTaaZaauZZa7aapUtuaZB7saLS + signature-provider = PUB_BLS_ZZa-PZZZZaZZZZZZ7oae7_Z7a_UZsaZaLaaaSrZ7-Zaa7ada-ZaZZaZvppoSapgZd7aaouaZZZaZZZP7ZaavZdPaeZ7Zio77ZZaZLZZaZa7ZguaZpZ7raaPgZ77ZZUoZZ7Zeva=ZZZ:PVT_BLS_-oZ_ZZZPaae7TaaaZ7aZ7Zt7aaLZZat_7ZaVaraZLaaaaiga + ``` +- For your producer account register at least one key on chain with the `regfinkey` action. When there are no registered BLS keys calling `regfinkey` will activate the provided key. + - Here is an example for the producer account `NewBlockProducer` + ``` + cleos push action eosio regfinkey '{"finalizer_name":"NewBlockProducer", \ + "finalizer_key":"PUB_BLS_SvLa9z9kZoT9bzZZZ-Zezlrst9Zb-Z9zZV9olZazZbZvzZzk9r9ZZZzzarUVzbZZ9Z9ZUzf9iZZ9P_kzZZzGLtezL-Z9zZ9zzZb9ZitZctzvSZ9G9SUszzcZzlZu-GsZnZ9I9Z", \ + "proof_of_possession":"SIG_BLS_ZPZZbZIZukZksBbZ9Z9Zfysz9zZsy9z9S9V99Z-9rZZe99vZUzZPZZlzZszZiiZVzT9ZZZZBi99Z9kZzZ9zZPzzbZ99ZZzZP9zZrU-ZZuiZZzZUvZ9ZPzZbZ_yZi9ZZZ-yZPcZZe9SZZPz9Tc9ZaZ999voB99L9PzZ99I9Zu9Zo9ZZZzTtVZbcZ-Zck_ZZUZZtfTZGszUzzBTZZGrnIZ9Z9Z9zPznyZLZIavGzZunreVZ9zZZt_ZlZS9ZZIz9yUZa9Z9-Z"}' \ + -p NewBlockProducer + ``` + +## HTTP Protocol Changes ### Updated Error Codes The HTTP error return code for exceeding `http-max-bytes-in-flight-mb` or `http-max-in-flight-requests` is now `503`, whereas in Leap 5.0.2, it was `429`. @@ -82,23 +135,15 @@ The configuration option `producer-threads` has been remove to enable greater ef ### Snapshot Format Spring v1 uses a new v7 snapshot format. The new v7 snapshot format is safe to use before, during, and after the switch to the Savanna Consensus Algorithm. Previous versions of Leap will not be able to use the v7 snapshot format. -### SHiP +### State Log History Compression Disabled State history log file compression has been disabled. Consumers with state history will need to put together their own compression. ## New & Modified Options -### New config options +### New Finalizer Configuration Options - `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. More information in [Guide to Managing Finalizer Keys](../../advanced-topics/managing-finalizer-keys). - `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` -- add `signature-provider` to configuration with the generated key(s) -- register a single key on chain with the `regfinkey` action - -Additional Documentation may be found in [Guide to Managing Finalizer Keys](../../advanced-topics/managing-finalizer-keys) +### New Vote-Threads Option +Where there is a block producing node that connects to its peers through an intermediate nodeos, the intermediate nodeos will need to have an integer value greater then for `vote-threads`. The default value for `vote-threads` is 4. When `vote-threads` is not an integer greater then zero votes are not propagated. From 71d2f70fefb2cb5382ec8b91807f7e6b5cb52527 Mon Sep 17 00:00:00 2001 From: Eric Passmore Date: Thu, 27 Jun 2024 18:45:21 -0700 Subject: [PATCH 4/5] update system contracts to 3.6 format changes --- .../100_migration-guides/04_upgrade-guide-spring-1-0.md | 8 ++++++-- .../100_migration-guides/10_switch-to-savanna.md | 2 +- 2 files changed, 7 insertions(+), 3 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 63dceb7..8b56b4b 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 @@ -13,6 +13,7 @@ This upgrade guide covers the steps for upgrading a node to the Spring binary fr - [State logs no longer compressed](#state-log-history-compression-disabled) - [Added BLS Finalizer Keys to support new consensus algorithm](#finalizer-keys) - [New Finalizer Configuration Options](#new-finalizer-configuration-options) +- [New State History Configuration Options](#new-state-history-configuration-options) - [New Vote-Threads Configuration Option](#new-vote-threads-option) ## Upgrade Steps @@ -128,10 +129,13 @@ Spring v1 uses a new v7 snapshot format. The new v7 snapshot format is safe to u ### State Log History Compression Disabled State history log file compression has been disabled. Consumers with state history will need to put together their own compression. +### New State History Configuration Options +Most node operators will never need to set these configuration options. If you are running State History you will need to set `finality-data-history`. +- `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. ### New Finalizer Configuration Options +Scripts that move or delete the ‘data’ directory need to protect the finalizer safety file, or utilize this option to set another location for the finalizer safety.dat file. - `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. More information in [Guide to Managing Finalizer Keys](../../advanced-topics/managing-finalizer-keys). -- `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. ### New Vote-Threads Option Where there is a block producing node that connects to its peers through an intermediate nodeos, the intermediate nodeos will need to have an integer value greater then for `vote-threads`. The default value for `vote-threads` is 4. When `vote-threads` is not an integer greater then zero votes are not propagated. +- `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. 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 1f8d513..bcf05b4 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 @@ -18,7 +18,7 @@ There are four steps ### Antelope Software Requirements Switching to Savanna will required the latest version of Spring Software and the EOS System Contracts. - [Spring v1.0.0](https://github.com/AntelopeIO/spring/releases) -- [EOS System Contracts v3.5.0](https://github.com/eosnetworkfoundation/eos-system-contracts/releases) +- [EOS System Contracts v3.6.0](https://github.com/eosnetworkfoundation/eos-system-contracts/releases) **Note:** [CDT v4.1.0](https://github.com/AntelopeIO/cdt/releases) is needed to compile the latest EOS System Contracts. This version of CDT contains both the needed host functions, and cryptography support needed to support managing finalizer keys. From 97e08140e3555a94d839592106d3a0489d008c98 Mon Sep 17 00:00:00 2001 From: Eric Passmore Date: Wed, 3 Jul 2024 19:33:31 -0700 Subject: [PATCH 5/5] fix broken links up a dir --- .../60_advanced-topics/20_introduction-finalizers-voting.md | 2 +- native/60_advanced-topics/21_managing-finalizer-keys.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/native/60_advanced-topics/20_introduction-finalizers-voting.md b/native/60_advanced-topics/20_introduction-finalizers-voting.md index 39f3bad..777e627 100644 --- a/native/60_advanced-topics/20_introduction-finalizers-voting.md +++ b/native/60_advanced-topics/20_introduction-finalizers-voting.md @@ -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. diff --git a/native/60_advanced-topics/21_managing-finalizer-keys.md b/native/60_advanced-topics/21_managing-finalizer-keys.md index 6b09e6a..bd6bc18 100644 --- a/native/60_advanced-topics/21_managing-finalizer-keys.md +++ b/native/60_advanced-topics/21_managing-finalizer-keys.md @@ -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. @@ -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. @@ -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`