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

Update BLS Examples #260

Merged
merged 38 commits into from
Aug 30, 2024
Merged
Changes from 1 commit
Commits
Show all changes
38 commits
Select commit Hold shift + click to select a range
cfb4784
added Spring Upgrade Guides
ericpassmore May 22, 2024
81922b5
fixed path for switch to savanna guide
ericpassmore May 23, 2024
80e5b22
removed self ref to managing finkeys
ericpassmore May 23, 2024
4dbeb53
Spring Documentation Update (#240)
ericpassmore May 23, 2024
fa13b60
fixed typo in signature-provider
ericpassmore May 23, 2024
0a07123
Merge remote-tracking branch 'origin' into ehp/spring-docs-v1
ericpassmore May 23, 2024
767c0a7
fixed typo in signature-provider
ericpassmore May 23, 2024
09f8775
up guides to reflect Savanna
ericpassmore Jun 1, 2024
336de5f
intro to finalizers and voting, vote peering
ericpassmore Jun 4, 2024
2949184
renamed no-hyphen intro finalizers and voting
ericpassmore Jun 4, 2024
0afda31
Background on Finalizers and Voting (#242)
ericpassmore Jun 4, 2024
55aa3d6
finalizer overview wording fixes
ericpassmore Jun 4, 2024
91dab1d
merged in staging branch commits
ericpassmore Jun 4, 2024
8e504bf
Finalizer Overview Working Updates (#243)
ericpassmore Jun 4, 2024
78cb6f0
fix broken link
ericpassmore Jun 4, 2024
cc8ae92
fix broken link
ericpassmore Jun 4, 2024
e0cbbc0
fix unresolved merge conflict (#244)
ericpassmore Jun 4, 2024
8b97595
Fix Broken Links in Introduction-Finalizer-Voting (#245)
ericpassmore Jun 4, 2024
eb353b1
Updated with more step by step instructions
ericpassmore Jun 5, 2024
25a6d16
remove funding from misc
Jun 6, 2024
dfecc66
fix wharfkit guide link
Jun 11, 2024
34d103e
Updated Upgrade Guide (#246)
ericpassmore Jun 28, 2024
9def907
Update System Contracts Expected Version to 3.6 (#247)
ericpassmore Jun 28, 2024
069d8b4
Fix Broken Links in Advanced Topics (#248)
ericpassmore Jul 4, 2024
452cf3c
resolve Spring v1 merge conflicts with main
ericpassmore Aug 16, 2024
4748743
Merge branch 'staging' of https://github.com/eosnetworkfoundation/doc…
ericpassmore Aug 16, 2024
7ddbd40
spring1 upgrade guide vote-threads tweaks
spoonincode Aug 20, 2024
ae25200
Merge remote-tracking branch 'origin/log_compat_spring1' into staging
ericpassmore Aug 20, 2024
66599d8
Merge remote-tracking branch 'origin/spring1-vote-threads' into staging
ericpassmore Aug 20, 2024
0817cd1
Merge pull request #256 from eosnetworkfoundation/spring-v1.0-rc2-merge
ericpassmore Aug 20, 2024
725dbe8
add missing word for clarity
ericpassmore Aug 20, 2024
35e374e
Merge pull request #257 from eosnetworkfoundation/spring-v1.0-rc2-merge
ericpassmore Aug 20, 2024
d72d729
added link to Voting and Peering section
ericpassmore Aug 20, 2024
3ce4483
Merge pull request #258 from eosnetworkfoundation/spring-v1.0-rc2-merge
ericpassmore Aug 20, 2024
c6c8ce8
Merge remote-tracking branch 'origin/main' into staging
ericpassmore Aug 30, 2024
d27e3b8
updates BLS regkey and actkey examples with real world keys and rm ba…
ericpassmore Aug 30, 2024
0af0436
rm hyphens from file name
ericpassmore Aug 30, 2024
66a1068
removed H1 replaced with title tags
ericpassmore Aug 30, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Updated Upgrade Guide (#246)
* fix unresolved merge conflict
* fix broken links
* more specific steps to upgrade guide
  • Loading branch information
ericpassmore authored Jun 28, 2024
commit 34d103e04d1658bc813110c8281e6230c53c91ef
Original file line number Diff line number Diff line change
@@ -2,46 +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)

## How To Upgrade
- do snapshot on old version of Leap
- shutdown leap
- build binaries or get deb
- install binaries
- start spring binaries from snapshot
- wait to catchup to head
- to get head `cleos --url PEER get info`
- to get your current state `cleos --url ME get info`
- take new v7 snapshot on spring

## Node Producers
Ignore, these additions unless you are a block producer. Exchanges don't need to be concerned with with items.

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

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

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

## 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`.
@@ -108,10 +125,13 @@ An example response with the limited filled fields looks something like,
### 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 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.




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