From d27e3b8fb85e132db183642f62cb8fe416782aff Mon Sep 17 00:00:00 2001
From: Eric Passmore <eric.passmore@gmail.com>
Date: Fri, 30 Aug 2024 13:17:59 -0700
Subject: [PATCH] updates BLS regkey and actkey examples with real world keys
 and rm backslash from examples

---
 .../04_upgrade-guide-spring-1-0.md            | 12 +--
 .../20_Rotate_BLS_Finalizer_Keys.md           | 80 +++++++++++++++++++
 .../21_managing-finalizer-keys.md             | 22 ++---
 3 files changed, 97 insertions(+), 17 deletions(-)
 create mode 100644 native/07_node-operation/50_tutorials/20_Rotate_BLS_Finalizer_Keys.md

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 763015e1..04574aae 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
@@ -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
   ```
 
diff --git a/native/07_node-operation/50_tutorials/20_Rotate_BLS_Finalizer_Keys.md b/native/07_node-operation/50_tutorials/20_Rotate_BLS_Finalizer_Keys.md
new file mode 100644
index 00000000..44f94a0e
--- /dev/null
+++ b/native/07_node-operation/50_tutorials/20_Rotate_BLS_Finalizer_Keys.md
@@ -0,0 +1,80 @@
+# 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_..."}]}
+```
diff --git a/native/60_advanced-topics/21_managing-finalizer-keys.md b/native/60_advanced-topics/21_managing-finalizer-keys.md
index bd6bc18f..52de9ee3 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. 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
 ```