Skip to content

Commit

Permalink
Spring Documentation Update (#240)
Browse files Browse the repository at this point in the history 
- Added Upgrade Guides for Spring
- Added Guide on switching to Savanna Consensus
- Added Guide on managing Finalizer Keys
  • Loading branch information
@ericpassmore
ericpassmore authored May 23, 2024
1 parent 3f4b808 commit 4dbeb53
Show file tree
Hide file tree
Showing 4 changed files with 249 additions and 0 deletions.
101 changes: 101 additions & 0 deletions native/07_node-operation/100_migration-guides/04_upgrade-guide-spring-1-0.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
---
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

### 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`.

### Get Block Header State Changed.
In the past, get_block_header_state returned the pre-Savanna (legacy) block header state. Parts of this response are incompatible with the internals of the new Savanna block state. Originally the plan was to remove the get_block_header_state endpoint, but some versions of eosjs, including the latest one, 22.1.0, require operation of this endpoint given certain values of blocksBehind otherwise eosjs will be unable to push a transaction.

Instead of deprecating the endpoint has been updated with behavioral differences. No matter whether Savanna has been activated or not, get_block_header_state in Spring 1.0 will return a response containing all fields but with only block_num, id, header, and additional_signatures filled out. Other fields will still exist but will be empty or zero. Additionally, the endpoint will consider both reversible and irreversible blocks. This latter tweak helps guard against a race condition in eosjs between calling get_info and then get_block_header_state when blocksBehind is a low number such as 2 or 3.

An example response with the limited filled fields looks something like,
```
{
"block_num": 40660,
"dpos_proposed_irreversible_blocknum": 0,
"dpos_irreversible_blocknum": 0,
"active_schedule": {
"version": 0,
"producers": []
},
"blockroot_merkle": {
"_active_nodes": [],
"_node_count": 0
},
"producer_to_last_produced": [],
"producer_to_last_implied_irb": [],
"valid_block_signing_authority": [
0,
{
"threshold": 0,
"keys": []
}
],
"confirm_count": [],
"id": "00009ed4aa662f3d7e96d88061e4741692b433fe783befc6c3cb6c6a40c5955a",
"header": {
"timestamp": "2024-03-19T02:39:40.000",
"producer": "inita",
"confirmed": 0,
"previous": "00009ed38d8d4c103ce5ced75558d6ac0f4d2ac4b63cf964feeb6d8bce600ade",
"transaction_mroot": "0000000000000000000000000000000000000000000000000000000000000000",
"action_mroot": "b179283d2264aa663cb669924bbff2f33e81a7ed71dcb465342673602605a1f1",
"schedule_version": 2,
"header_extensions": [
[
2,
"d39e0000010000"
]
],
"producer_signature": "SIG_K1_KgufADyFuHdBwT6VGBVdrnhVs6dakZdXp4qr5NgJFU7orfXbFi9eVc7NvjrjvUyL79SXfMjgyzW7cVGfQW8iy1CbjStENZ"
},
"pending_schedule": {
"schedule_lib_num": 0,
"schedule_hash": "0000000000000000000000000000000000000000000000000000000000000000",
"schedule": {
"version": 0,
"producers": []
}
},
"activated_protocol_features": null,
"additional_signatures": []
}
```

## Deprecations & Removals

### Producer Threads Removed
As of Spring v1, node operators MUST ensure the following parameters are NOT set in config.ini to allow nodeos to start:
- `producer-threads`

The configuration option `producer-threads` has been remove to enable greater efficiency and lower latencies. Some of the work has been offloaded to `chain-threads` and block producers may experiment with increasing the later threading configuration.

## Updates and Changes

### 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 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
- `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.

### 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-provided` 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)
44 changes: 44 additions & 0 deletions native/07_node-operation/100_migration-guides/10_switch-to-savanna.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
title: Switching Over To Savanna Consensus Algorithm
---

## Switching Over To Savanna Consensus Algorithm
Switching over to the Savanna Consensus Algorithm is a multi-step process.

### Overview of Upgrade Process
There are four steps
1. Upgrade Antelope Software, Spring and EOS System Contracts
2. Block Producers generate and register finality keys
- 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
4. `eosio` user calls `switchtosvnn` action

### Antelope Software Requirements
Switching to Savanna will required the latest version of Spring Software and the EOS System Contracts. The specific versions will be filled at a later date.
- [Spring v1.0.0](https://github.com/AntelopeIO/spring/releases)
- [EOS System Contracts v3.5.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.

### Protocol Features Dependencies
The reference for protocol features with their corresponding hashes may be found in [bios-boot-tutorial](https://github.com/AntelopeIO/spring/blob/main/tutorials/bios-boot-tutorial/bios-boot-tutorial.py).
The protocol feature `INSTANT_FINALITY` depends on the following protocol features being active_schedule
- `WTMSIG_BLOCK_SIGNATURES`
- `BLS_PRIMITIVES2`
- `DISALLOW_EMPTY_PRODUCER_SCHEDULE`
- `ACTION_RETURN_VALUE`


### Generate and Registering 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-provided` to configuration with the generated key(s)
- restart nodeos with the new `signature-provided` 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)

### 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.
2 changes: 2 additions & 0 deletions native/07_node-operation/100_migration-guides/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,5 @@ Learn about EOS History Alternatives:
- [General Upgrade Guide](01_general-upgrade-guide.md)
- [V1 History Alternatives](02_v1-history-alternatives.md)
- [5.0 Upgrade Guide](03_upgrade-guide-5-0.md)
- [Spring 1.0 Upgrade Guide](04_upgrade-guide-spring-1-0.md)
- [Switching To Savanna Consensus](10_switch-to-savanna.md)
102 changes: 102 additions & 0 deletions native/60_advanced-topics/05_managing-finalizer-keys.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
---
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.

## 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.

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.
- 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
- 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.

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.

### 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`).
```
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
```

### 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-provided` 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`

### 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.
- **Note** the authority used is the block producer's.
- `finalizer_name` must be a registered producer.
- `finalizer_key` must be in base64url format.
- `proof_of_possession` must be a valid of proof of possession signature `finalizer_name` to register.
- `linkauth` may be used to allow a lower authority to execute this action.

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"}' \
-p NewBlockProducer
```

### Changing Finalizer Key
To activate a different BLS finalizer key call the `actfinkey` action.
- The provided finalizer_key must be a registered finalizer key in base64url format.
- The authority is the authority of `finalizer_name`.

First register your new key with `cleos push action eosio regfinkey ...`. Then call `actfinkey` with the Public Key of the non-activated, and registered key.

Example
```
cleos push action eosio actfinkey '{"finalizer_name":"NewBlockProducer", \
"finalizer_key":"PUB_BLS_SvLa9z9kZoT9bzZZZ-Zezlrst9Zb-Z9zZV9olZazZbZvzZzk9r9ZZZzzarUVzbZZ9Z9ZUzf9iZZ9P_kzZZzGLtezL-Z9zZ9zzZb9ZitZctzvSZ9G9SUszzcZzlZu-GsZnZ9I9Z"}' \
-p NewBlockProducer
```

### Removing Finalizer Key
To remove a registered finalizer key, you no longer plan on using, call the `delfinkey` action.
- `finalizer_key` must be a registered finalizer key in base64url format.
- `finalizer_key` must not be active, unless it is the last registered finalizer key.
- The authority is the authority of `finalizer_name`.

Example
```
cleos push action eosio delfinkey '{"finalizer_name":"NewBlockProducer", \
"finalizer_key":"PUB_BLS_SvLa9z9kZoT9bzZZZ-Zezlrst9Zb-Z9zZV9olZazZbZvzZzk9r9ZZZzzarUVzbZZ9Z9ZUzf9iZZ9P_kzZZzGLtezL-Z9zZ9zzZb9ZitZctzvSZ9G9SUszzcZzlZu-GsZnZ9I9Z"}' \
-p NewBlockProducer
```

### Verifying Finalizer Keys
Active finalizer keys are stored in the `finkeys` table. This table can be accessed via cleos. The following request will show the active public BLS key for each producer.
`cleos get table eosio eosio finkeys`

To see all finalizer keys including non-active keys check the `finalizers` table.
`cleos get table eosio eosio finalizers`

## New Configuration Options
The configuration options specific to managing finality. It is recommended to use the default values and not set custom configurations.

- `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.

0 comments on commit 4dbeb53

Please sign in to comment.