Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
Consensus Protocol Upgrade Process #7237
This guide is intended to instruct node operators on the steps needed to successfully transition an EOSIO network through a consensus protocol upgrade (also known as a "hard fork") with minimal disruption to users.
Before deploying the upgrade to any non-test networks, protocol upgrades should be deployed and verified on test networks. The version of nodeos supporting the initial set of protocol upgrades will first be released as a release candidate: v1.8.0-rc2. Existing EOSIO test networks can use this version of nodeos to carry out and test the upgrade process.
This test upgrade process can give block producers of their respective EOSIO blockchain networks practice with carrying out the steps necessary to successfully coordinate the activation of the first consensus protocol upgrade feature (or just protocol feature for short), which will fork out any nodes that have not yet updated to the new version of nodeos by the time of activation. The process will also inform block producers of the requirements for nodes to upgrade nodeos to v1.8.x from v1.7.x and earlier, and it can help them decide an appropriate deadline to be given as notice to the community for when the first protocol feature will be activated.
Testing the upgrade process on test networks will also allow block explorers and other applications interacting with the blockchain to test the transition and the behavior of their applications under the new rules after activation of the individual protocol features. Some of the protocol features (
Upgrade process for all EOSIO networks (including test networks)
Because these steps require replay from genesis, after the release of the appropriate version of nodeos supporting the initial set of consensus protocol upgrades (v1.8.0-rc2 for test networks and v1.8.0 for all other networks), all node operators should take the following steps as soon as possible. These steps should be followed on an additional node that they can afford to be taken offline for an extended period of time:
A replay from genesis is required when upgrading nodeos from v1.7.x to v1.8.x. Afterward, the v1.8.x node can, as usual, start and stop quickly without requiring replays. The state directory generated by a v1.7.x node will not be compatible with v1.8.x of nodeos. Version 1 portable snapshots (generated by v1.7.x) will not be compatible with v1.8.x which require the version 2 portable snapshots.
Due to the long amount of time it will take to replay from genesis (even longer if running with plugins that track history), block producers of the network are suggested to provide sufficient time to the community to upgrade their nodes prior to activating the first protocol upgrade feature.
Nodes that wish to make the transition but are not interested in tracking the history of the chain from genesis have an option to speed things up by using a version 2 portable snapshots that can be generated by synced v1.8.x nodes. Since the portable snapshots are generated in a deterministic and portable manner, users can simply compare the hash of the snapshot files they downloaded from an arbitrary source to the hashes published by a variety of trusted sources, but only if they correspond to snapshots taken at the same block ID.
Special notes to block producers
Block producers will obviously need to run the replay of nodeos on a separate machine that is not producing blocks. This machine will have to be production ready so that they can switch block production over to it when it has finished replaying and syncing. Alternatively, they can take a portable snapshot on the replay machine and move it to yet another machine which is production ready, then activate the switch over from their currently producing v1.7.x BP node to the v1.8.x node.
Nearly all of the protocol upgrade features introduced in v1.8.x first require a special protocol feature (codename
After activation of the
The activation of the first protocol feature,
The BPs should then set this chosen time in the configuration JSON file for the
It is important that this configuration change happens prior to allowing that node to produce blocks on the network. As long as more than two-thirds of the active block producers have set the same future time in the configuration file for the
After the agreed upon time has passed, any of the active block producers can activate the
To determine the specific format of the request, the digest of the
In the returned array, find an object that references the
In this case, the digest of the
Then, the local block producing nodeos instance can be requested to activate the
The above command should only be used after the time has passed the agreed upon
Any synced v1.8.x nodes can be used to check which protocol features have been activated using the following command:
For example, if the
Notes for block explorers, exchanges, and applications
Block explorers, exchanges, and applications building on the blockchain can all follow the four-step processes described above to upgrade their nodes in time and ensure their services continue when the first protocol upgrade is activated. However, they should also be aware that certain protocol features change the behavior of existing operations on the blockchain, and in some cases also slightly change the structure of blocks and transactions.
First, v1.8.x changes the structure of transaction traces, even prior to the activation of any protocol features. Clients consuming transaction and action traces made available through
The state history plugin has also changed its API and the structure of the files it stores on disk in a backwards incompatible way in v1.8.x. These changes reflect, among other things, the transaction trace structural changes and the data structure changes made within the chain state database to support the new protocol features. Consumers of the state history plugin will need to be updated to work with the new changes in v1.8.x.
Second, all protocol features are activated by signaling their 256-bit digest through a block. The block producer is able to place the digest of a protocol feature in a special section of the block header (called the block header extensions) that, under the original rules of v1.7.x, is expected to be empty. This change may especially be relevant to block explorers which need to ensure that their tools will not break because of the extra data included in the block header and ideally will update their block explorers to reflect the new information. The first time block explorers or other consumers of the blockchain data will encounter a non-empty block header extension is during the activation of the
Third, upon activation of the
Fourth, activation of the
Disclaimer: Block.one makes its contribution on a voluntary basis as a member of the EOSIO community and is not responsible for ensuring the overall performance of the software or any related applications. We make no representation, warranty, guarantee or undertaking in respect of the releases described here, the related GitHub release, the EOSIO software or any related documentation, whether expressed or implied, including but not limited to the warranties or merchantability, fitness for a particular purpose and noninfringement. In no event shall we be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or documentation or the use or other dealings in the software or documentation. Any test results or performance figures are indicative and will not reflect performance under all conditions. Any reference to any third party or third-party product, resource or service is not an endorsement or recommendation by Block.one. We are not responsible, and disclaim any and all responsibility and liability, for your use of or reliance on any of these resources. Third-party resources may be updated, changed or terminated at any time, so the information here may be out of date or inaccurate. Any person using or offering this software in connection with providing software, goods or services to third parties shall advise such third parties of these license terms, disclaimers and exclusions of liability.
We are not aware of one at the moment.
Given the breadth of changes that forks of eosio can make, it seems unlikely that a global registry would truly capture all of the conflicting numbers/decisions and enable an agnostic client to navigate all possible permutations. That sounds like a far more aggressive and utopian standard of the eosio kingdom. A noble goal in the long term.
For the time period where we cannot provide a truly backend agnostic standard of interoperation, integrators will unfortunately need to be aware of which flavor they are talking to and take appropriate measures to account for the differences. This means, disambiguating a number of things including various extension IDs on core data structures will be a burden on those integrators for the foreseeable future. To that end, we expect each "primary" repo can serve as its own registry of that flavor's extensions for now. It's unfortunate.