Update BLS Examples

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

@@ -14,7 +14,7 @@ This upgrade guide covers the steps for upgrading a node to Spring v1 from prior
 - [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)
+- [New `vote-threads` Configuration Option](#new-vote-threads-option)
 
 ## Upgrade Steps
 
@@ -50,16 +50,16 @@ For producer nodes, in addition to the [Steps Above](#upgrade-steps-for-non-prod
 - 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=KEY:PVT_BLS_Z7tZLZZaZZ7o7LZ7aaa7uaBe7rLdPVZBpsZLrUaZZBUt-a7Z
-   signature-provider = PUB_BLS_7ZLauuZ777ZvSa_Z7ZTrZaZ7_eraa7a7aUanv7aZZ7ZaaZdZaaadaZr-agi7_aoZa77aZZZZZaZU7aB7a7TZ-ZZu777777gaSaarZ7udZs7S-aZ-ZZZ_SBa-iZZPaZZZ7Za7rg=KEY:PVT_BLS_Znsaa7uZ7iZZ7uZ7aZZe7raTaaZaauZZa7aapUtuaZB7saLS
-   signature-provider = PUB_BLS_ZZa-PZZZZaZZZZZZ7oae7_Z7a_UZsaZaLaaaSrZ7-Zaa7ada-ZaZZaZvppoSapgZd7aaouaZZZaZZZP7ZaavZdPaeZ7Zio77ZZaZLZZaZa7ZguaZpZ7raaPgZ77ZZUoZZ7Zeva=KEY:PVT_BLS_-oZ_ZZZPaae7TaaaZ7aZ7Zt7aaLZZat_7ZaVaraZLaaaaiga
+   signature-provider = PUB_BLS_Se0dH9PzeGQaYHJ1F44qVNcGR2XXTiF5HcAO5rXjYxDutIckoWjRPoY2gBTFfvAA7g8H0Ce7__7yQ0BUFMQUBBWX6Y4ERasyhh8QHxCVXK9JZOw0ICNWPxXIJD_UDmILQ0kouA
+   signature-provider = PUB_BLS_vualvdZgUpFYVEOYQweTfSeHoOmj3IYysMFwGlifZndwClPIH2qaOxYibrcJ88sI_aA3LyaW5GhnOmgD9cocBUP3P9sSQrVLi_rPIZQMFF3OsSQZQBCiiV_V7ikDlVMMYdf5Ew
+   signature-provider = PUB_BLS_vRf3BzXJ64F4hV_XrfC0ooIehDUFVnobOUxEgb1JUai_tVfgp4tM0DnDNqza2kYKgrSJgXr1xWgt3dzn7VrzzwGH9QJYbvTWvcpDZ-sNpXVYhFUA6o3apUD3oRGRmwAZjIhxLg
    ```
 - 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"}' \
+  cleos push action eosio regfinkey '{"finalizer_name":"NewBlockProducer",
+        "finalizer_key":"PUB_BLS_Se0dH9PzeGQaYHJ1F44qVNcGR2XXTiF5HcAO5rXjYxDutIckoWjRPoY2gBTFfvAA7g8H0Ce7__7yQ0BUFMQUBBWX6Y4ERasyhh8QHxCVXK9JZOw0ICNWPxXIJD_UDmILQ0kouA",
+        "proof_of_possession":"SIG_BLS_yenZIv6kbim2W1zntl73wxcSNWHFJS1DuMH7qAUFyCKOGBYWZXZYJb7MCr7503ULWiJTAwLUyjmSbXPw38BW9n6UE8r6MpjYKgxlSI2Ezuwzp-18sy_6StHbisSNLl0GtxmJ987ouO8gMvUDUO68cHhMbjRh9j2L790k4gCQS8gPON9OJgiIY9JgYraTB04FyAdpmc_3JCauU4nSwo3xYjS9NUVqgbuJR2lbQDjTPp5VR3z5OrOrNhaw2tewIkEJyxeZmg"}' 
         -p NewBlockProducer
   ```
 
@@ -143,6 +143,6 @@ To accommodate new Savanna consensus information, a new `finality-data-history`
 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).
 
-### 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.
+### 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 than 0 for `vote-threads`. The default value for `vote-threads` is 4. When `vote-threads` is not an integer greater than 0, votes are not propagated. See [Voting and Peering](../../advanced-topics/introduction-finalizers-voting/#voting-and-peering) for more background and recomendations on configuring `vote-threads`.
+- `vote-threads` - Sets the number of threads to handle voting. The default is sufficient for all known production setups, and the recommendation is to leave this value unchanged.

native/07_node-operation/50_tutorials/20_Rotate-BLS-Finalizer-Keys.md

@@ -0,0 +1,80 @@
+---
+title: Rotate BLS Finalizer Keys
+---
+
+This document is a step by step guide to switching out your active on-chain finalizer keys. You may register as many finalizer keys as you would like.
+
+### Create and Configure Additional Key
+Next we will create a new finalizer key, add it to nodoes' configuration, and register the key. In this example we are creating one key, you may create many keys.
+
+Keys may be output to console (`--to-console`) or to file (`--file`).
+```
+spring-util bls create key --to-console > producer-name.finalizer.key
+```
+The output will look like this
+```
+Private key: PVT_BLS_9-9ziZZzZcZZoiz-ZZzUtz9ZZ9u9Zo9aS9BZ-o9iznZfzUZU
+Public key: PUB_BLS_Se0dH9PzeGQaYHJ1F44qVNcGR2XXTiF5HcAO5rXjYxDutIckoWjRPoY2gBTFfvAA7g8H0Ce7__7yQ0BUFMQUBBWX6Y4ERasyhh8QHxCVXK9JZOw0ICNWPxXIJD_UDmILQ0kouA
+Proof of Possession: SIG_BLS_yenZIv6kbim2W1zntl73wxcSNWHFJS1DuMH7qAUFyCKOGBYWZXZYJb7MCr7503ULWiJTAwLUyjmSbXPw38BW9n6UE8r6MpjYKgxlSI2Ezuwzp-18sy_6StHbisSNLl0GtxmJ987ouO8gMvUDUO68cHhMbjRh9j2L790k4gCQS8gPON9OJgiIY9JgYraTB04FyAdpmc_3JCauU4nSwo3xYjS9NUVqgbuJR2lbQDjTPp5VR3z5OrOrNhaw2tewIkEJyxeZmg
+```
+
+### Add Finalizer Keys to Config
+Create an **additional** configuration. You should have multiple `signature-provider` configurations with different BLS keys. One entry will match your currently used BLS key.
+
+Formate
+`signature-provider = PUBLIC_KEY=KEY:PRIVATE_KEY`
+For example
+`signature-provider = PUB_BLS_Se0dH9PzeGQaYHJ1F44qVNcGR2XXTiF5HcAO5rXjYxDutIckoWjRPoY2gBTFfvAA7g8H0Ce7__7yQ0BUFMQUBBWX6Y4ERasyhh8QHxCVXK9JZOw0ICNWPxXIJD_UDmILQ0kouA`
+`signature-provider = PUB_BLS_vRf3BzXJ64F4hV_XrfC0ooIehDUFVnobOUxEgb1JUai_tVfgp4tM0DnDNqza2kYKgrSJgXr1xWgt3dzn7VrzzwGH9QJYbvTWvcpDZ-sNpXVYhFUA6o3apUD3oRGRmwAZjIhxLg`
+
+### Restart Nodeos
+Retart nodeos instance to load the key.
+
+### Register On-Chain Actions
+Check your existing finalizer keys
+```
+cleos get table --limit 100 eosio eosio finkeys | jq .rows[] | jq  'select (.finalizer_name=="producert-name")'
+```
+
+You should **not** see your newly created key. Lets register the new key.
+
+```
+cleos push action eosio regfinkey '{"finalizer_name":"producer-name",
+      "finalizer_key":"PUB_BLS_Se0dH9PzeGQaYHJ1F44qVNcGR2XXTiF5HcAO5rXjYxDutIckoWjRPoY2gBTFfvAA7g8H0Ce7__7yQ0BUFMQUBBWX6Y4ERasyhh8QHxCVXK9JZOw0ICNWPxXIJD_UDmILQ0kouA",
+      "proof_of_possession":"SIG_BLS_yenZIv6kbim2W1zntl73wxcSNWHFJS1DuMH7qAUFyCKOGBYWZXZYJb7MCr7503ULWiJTAwLUyjmSbXPw38BW9n6UE8r6MpjYKgxlSI2Ezuwzp-18sy_6StHbisSNLl0GtxmJ987ouO8gMvUDUO68cHhMbjRh9j2L790k4gCQS8gPON9OJgiIY9JgYraTB04FyAdpmc_3JCauU4nSwo3xYjS9NUVqgbuJR2lbQDjTPp5VR3z5OrOrNhaw2tewIkEJyxeZmg"}'
+      -p producer-name
+```
+
+Recheck your existing finalizer keys , now the key should be listed
+```
+cleos get table --limit 100 eosio eosio finkeys | jq .rows[] | jq  'select (.finalizer_name=="producert-name")'
+```
+
+### Activate On-Chain Action
+Use cleos to find your current finalizer key. Make a note of the key, so we can verify it changes at the end of this key rotation.
+```
+cleos get table --limit 100 eosio eosio finalizers | jq .rows[] | jq  'select (.finalizer_name=="producer_name")'.active_key_binary
+```
+
+Rotate to the new key with the `actfinkey` action.
+```
+cleos push action eosio actfinkey '{"finalizer_name":"producer-name",
+      "finalizer_key":"PUB_BLS_Se0dH9PzeGQaYHJ1F44qVNcGR2XXTiF5HcAO5rXjYxDutIckoWjRPoY2gBTFfvAA7g8H0Ce7__7yQ0BUFMQUBBWX6Y4ERasyhh8QHxCVXK9JZOw0ICNWPxXIJD_UDmILQ0kouA"}'
+      -p producer-name
+```
+
+The key has been rotated and the value should change.
+```
+cleos get table --limit 100 eosio eosio finalizers | jq .rows[] | jq  'select (.finalizer_name=="producer_name")'.active_key_binary
+```
+
+### Finalizer Policy Change
+Check your nodeos logs for a message indicating the Finalizer Policy has changed.
+```
+grep -i "finalizer policy" my.log
+```
+Should see two log lines like this
+```
+info  2024-06-04T18:17:04.133 nodeos    block_header_state.cpp:185    finish_next          ] Finalizer policy generation change: 1 -> 2
+info  2024-06-04T18:17:04.133 nodeos    block_header_state.cpp:187    finish_next          ] New finalizer policy becoming active in block 00002e8d6c84a48932f1b99930c3d3074c7891a6d3fa176959c4b40f5969ba6f: {"generation":2,"threshold":3,"finalizers":[{"description":"producer1","weight":1,"public_key":"PUB_BLS_..."},{"description":"producer2","weight":1,"public_key":"PUB_BLS_..."},{"description":"producer3","weight":1,"public_key":"PUB_BLS_..."}]}
+```

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

@@ -47,4 +47,4 @@ For this reason it is recommended that each producer instance uses its own uniqu
 ### 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.
+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 with your producer from reaching peers.

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. See How To [Rotate BLS Finalizer Keys](../../node-operation/tutorials/Rotate_BLS_Finalizer_Keys) for specific instructions on moving to new 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.
 
 ## 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.
@@ -66,15 +66,15 @@ spring-util bls create key --to-console > producer-name.finalizer.key
 The output will look like this
 ```
 Private key: PVT_BLS_9-9ziZZzZcZZoiz-ZZzUtz9ZZ9u9Zo9aS9BZ-o9iznZfzUZU
-Public key: PUB_BLS_SvLa9z9kZoT9bzZZZ-Zezlrst9Zb-Z9zZV9olZazZbZvzZzk9r9ZZZzzarUVzbZZ9Z9ZUzf9iZZ9P_kzZZzGLtezL-Z9zZ9zzZb9ZitZctzvSZ9G9SUszzcZzlZu-GsZnZ9I9Z
-Proof of Possession: SIG_BLS_ZPZZbZIZukZksBbZ9Z9Zfysz9zZsy9z9S9V99Z-9rZZe99vZUzZPZZlzZszZiiZVzT9ZZZZBi99Z9kZzZ9zZPzzbZ99ZZzZP9zZrU-ZZuiZZzZUvZ9ZPzZbZ_yZi9ZZZ-yZPcZZe9SZZPz9Tc9ZaZ999voB99L9PzZ99I9Zu9Zo9ZZZzTtVZbcZ-Zck_ZZUZZtfTZGszUzzBTZZGrnIZ9Z9Z9zPznyZLZIavGzZunreVZ9zZZt_ZlZS9ZZIz9yUZa9Z9-Z
+Public key: PUB_BLS_Se0dH9PzeGQaYHJ1F44qVNcGR2XXTiF5HcAO5rXjYxDutIckoWjRPoY2gBTFfvAA7g8H0Ce7__7yQ0BUFMQUBBWX6Y4ERasyhh8QHxCVXK9JZOw0ICNWPxXIJD_UDmILQ0kouA
+Proof of Possession: SIG_BLS_yenZIv6kbim2W1zntl73wxcSNWHFJS1DuMH7qAUFyCKOGBYWZXZYJb7MCr7503ULWiJTAwLUyjmSbXPw38BW9n6UE8r6MpjYKgxlSI2Ezuwzp-18sy_6StHbisSNLl0GtxmJ987ouO8gMvUDUO68cHhMbjRh9j2L790k4gCQS8gPON9OJgiIY9JgYraTB04FyAdpmc_3JCauU4nSwo3xYjS9NUVqgbuJR2lbQDjTPp5VR3z5OrOrNhaw2tewIkEJyxeZmg
 ```
 
 ### Add Finalizer Keys to Config
 You may add several finalizer keys to configuration. **NOTE** Instances of nodeos must be restarted to pick up the new configuration options. Keys are added to configuration with the `signature-provider` option. These keys may be added via the command line or placed into a configuration file. Placing the finalizer keys into a configuration file would look like this.
 `signature-provider = PUBLIC_KEY=KEY:PRIVATE_KEY`
 For example
-`signature-provider = PUB_BLS_SvLa9z9kZoT9bzZZZ-Zezlrst9Zb-Z9zZV9olZazZbZvzZzk9r9ZZZzzarUVzbZZ9Z9ZUzf9iZZ9P_kzZZzGLtezL-Z9zZ9zzZb9ZitZctzvSZ9G9SUszzcZzlZu-GsZnZ9I9Z=KEY:PVT_BLS_9-9ziZZzZcZZoiz-ZZzUtz9ZZ9u9Zo9aS9BZ-o9iznZfzUZU`
+`signature-provider = PUB_BLS_Se0dH9PzeGQaYHJ1F44qVNcGR2XXTiF5HcAO5rXjYxDutIckoWjRPoY2gBTFfvAA7g8H0Ce7__7yQ0BUFMQUBBWX6Y4ERasyhh8QHxCVXK9JZOw0ICNWPxXIJD_UDmILQ0kouA`
 
 ### Register Finalizer Key
 Each producer should register a finalizer key. This is done with the `regfinkey`. No other actions are needed when registering your first key.
@@ -86,9 +86,9 @@ Each producer should register a finalizer key. This is done with the `regfinkey`
 
 Here is an example
 ```
-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"}' \
+cleos push action eosio regfinkey '{"finalizer_name":"NewBlockProducer",
+      "finalizer_key":"PUB_BLS_Se0dH9PzeGQaYHJ1F44qVNcGR2XXTiF5HcAO5rXjYxDutIckoWjRPoY2gBTFfvAA7g8H0Ce7__7yQ0BUFMQUBBWX6Y4ERasyhh8QHxCVXK9JZOw0ICNWPxXIJD_UDmILQ0kouA",
+      "proof_of_possession":"SIG_BLS_yenZIv6kbim2W1zntl73wxcSNWHFJS1DuMH7qAUFyCKOGBYWZXZYJb7MCr7503ULWiJTAwLUyjmSbXPw38BW9n6UE8r6MpjYKgxlSI2Ezuwzp-18sy_6StHbisSNLl0GtxmJ987ouO8gMvUDUO68cHhMbjRh9j2L790k4gCQS8gPON9OJgiIY9JgYraTB04FyAdpmc_3JCauU4nSwo3xYjS9NUVqgbuJR2lbQDjTPp5VR3z5OrOrNhaw2tewIkEJyxeZmg"}'
       -p NewBlockProducer
 ```
 
@@ -101,8 +101,8 @@ First register your new key with `cleos push action eosio regfinkey ...`. Then c
 
 Example
 ```
-cleos push action eosio actfinkey '{"finalizer_name":"NewBlockProducer", \
-      "finalizer_key":"PUB_BLS_SvLa9z9kZoT9bzZZZ-Zezlrst9Zb-Z9zZV9olZazZbZvzZzk9r9ZZZzzarUVzbZZ9Z9ZUzf9iZZ9P_kzZZzGLtezL-Z9zZ9zzZb9ZitZctzvSZ9G9SUszzcZzlZu-GsZnZ9I9Z"}' \
+cleos push action eosio actfinkey '{"finalizer_name":"NewBlockProducer",
+      "finalizer_key":"PUB_BLS_Se0dH9PzeGQaYHJ1F44qVNcGR2XXTiF5HcAO5rXjYxDutIckoWjRPoY2gBTFfvAA7g8H0Ce7__7yQ0BUFMQUBBWX6Y4ERasyhh8QHxCVXK9JZOw0ICNWPxXIJD_UDmILQ0kouA"}'
       -p NewBlockProducer
 ```
 
@@ -114,8 +114,8 @@ To remove a registered finalizer key, you no longer plan on using, call the `del
 
 Example
 ```
-cleos push action eosio delfinkey '{"finalizer_name":"NewBlockProducer", \
-      "finalizer_key":"PUB_BLS_SvLa9z9kZoT9bzZZZ-Zezlrst9Zb-Z9zZV9olZazZbZvzZzk9r9ZZZzzarUVzbZZ9Z9ZUzf9iZZ9P_kzZZzGLtezL-Z9zZ9zzZb9ZitZctzvSZ9G9SUszzcZzlZu-GsZnZ9I9Z"}' \
+cleos push action eosio delfinkey '{"finalizer_name":"NewBlockProducer",
+      "finalizer_key":"PUB_BLS_Se0dH9PzeGQaYHJ1F44qVNcGR2XXTiF5HcAO5rXjYxDutIckoWjRPoY2gBTFfvAA7g8H0Ce7__7yQ0BUFMQUBBWX6Y4ERasyhh8QHxCVXK9JZOw0ICNWPxXIJD_UDmILQ0kouA"}'
       -p NewBlockProducer
 ```