On Wednesday, September 21, 2022, EOS block producers will begin carving a new path toward self-determination by executing a coordinated consensus upgrade to Mandel 3.1.
Anyone running a node must upgrade their nodes before September 21 to continue syncing with the network.
The coordinated consensus upgrade to the Mandel 3.1 release includes priorities guided by network consensus. With this release, a coalition of EOSIO networks officially replaces the previously inattentive EOSIO developers with the EOS Network Foundation (ENF) core development team. This emancipation enables cross-chain collaboration and pushes the network into the future.
The Mandel upgrade represents the network assuming ownership of its own codebase.
As guardians of the network, block producers on EOS assume responsibility for stable network upgrades. However, with consensus upgrades, all nodes in the network need to be updated.
For weeks now, many people have been testing Mandel 3.1, and the ENF engineering team has pushed out release candidates regularly. This testing continues as developers put the finishing touches on Mandel 3.1 and related software ahead of their anticipated release in the coming days.
Like the previous EOSIO 1.8 release, Mandel 3.1 requires coordination between block producers and other network participants to ensure a smooth network consensus upgrade. Once the software is released, node operators must validate prerequisites, remove obsolete plugins, and change configuration settings before updating binaries.
This document provides an upgrade checklist to facilitate the node upgrade process and avoid disrupting operations. Some specific steps may vary based on existing node configuration, but these general steps work for most nodes.
Developers can fill out a survey form (survey questions) to help determine the most-used API nodes and help prioritize resources.
Once the ENF publishes the final release, node operators can upgrade to Mandel. The most recent release is on GitHub.
Planning for the Upgrade:
Make sure a test server is available to try out these steps before performing them on production nodes.Use one of the supported operating systems (Ubuntu 18.04, 20.04, 22.04). You can install Mandel 3.1 on a fresh server or upgrade an existing server. The instructions assume you are upgrading.Decide if you are using the pre-built binaries or compiling binaries yourself.Ensure nodes are NOT configured to use any plugins that are no longer available in Mandel 3.1 (as noted under deprecations in the GitHub Release).
Nodes that use these plugins must adapt their solutions prior to activation, ideally immediately:
History v1 “history_plugin” + “history_api_plugin”MongoDB “mongo_db_plugin”
Operators can migrate their solutions to services like Hyperion or Chronicle.
At this point, if you’re upgrading your 2.0 (NOT 2.1) node with a snapshot, you can move on to preparing for the upgrade.
EOSIO 2.1 used state history plugin (SHiP) files and blocks.log files that are incompatible with Mandel. SHiP files from 2.1 are always incompatible with 3.1. However, blocks.log files may be compatible if the node upgraded from an earlier version of EOSIO.Mandel 3.1 is based on EOSIO 2.0, so upgrading nodes from EOSIO 2.0 is straightforward.
If you are using EOSIO 2.1, you may have additional work:
2.1 Nodes that don’t keep a blocks.log file or state history are the easiest to upgrade. Just start the node from a snapshot. For 2.1 nodes that keep a blocks.log file but do not keep state history, the version of the blocks.log file is important. If your blocks.log was created before EOSIO 2.1, the blocks.log file is compatible with 3.1 and you can start from a snapshot without removing existing block logs.If you are using EOSIO 2.0 your block log is compatible.If you are using EOSIO 2.1, your block log may or may not be compatible. An incompatible blocks.log file needs to be removed. To determine if your blocks.log file is compatible, use the following command with your node:apt install bsdextrautilshexdump <nodeos data directory>/blocks/blocks.log | head(The <nodeos data directory> will be the “data” directory where nodeos stores blockchain data, for example, “.local/share/eosio/nodeos/data”)The second number in the output (top row, second column from the left) corresponds with the blocks.log version. 0001, 0002, or 0003 is ok. 0004 is from EOSIO 2.1, and is not compatible. 0000000 0003 8000 6a7f 017e e473 5a38 0827 d7e60000010 8804 fb34 07c1 2f9f b1ab 3c7b 5b12 6a14The output continues. Other than the bolded section, the content will be different.If your node is running EOSIO 2.0 and needs to keep blocks and state history, you can use a snapshot for your upgrade.If your node is running EOSIO 2.1 and needs to keep state history, you need to either replay your block log or resync from the network. Replay is faster, as it saves network overhead. You can replay your blocks log if you have a compatible version of blocks.log. See (2.2) above. A replay can take weeks.If your blocks log is not compatible, you need to resync from another node on the network. You can synchronize from either 2.0 or 2.1, and a resync creates a compatible blocks.log file. Resync can take weeks. When resyncing, blocks.log and state history are created together.Contact EOS Support if you’d like to request a 2.0 blocks.log file for download.
Figure 1, Table of steps the nodes running 2.1 must take depending on their configuration(cells highlighted in yellow and red represent steps that can take weeks to complete)
If you have any questions about the upgrade process, please reach out to EOS Support.
Preparing your node for the upgrade
Download pre-built binaries to install Mandel. Operators who wish to build Mandel themselves can find instructions in the readme.Before installing any binaries, make sure you have a compatible snapshot, if needed.If you are running EOSIO 2.0 (but not EOSIO 2.1), you can generate a snapshot from within a local node by using the command:curl -X POST http://127.0.0.1:8888/v1/producer/create_snapshotTo perform a snapshot, nodes must be started with the configuration option plugin = eosio::producer_api_pluginMake sure your node is not exposed to the public when enabling the producer_api_plugin as it is only for administrators.You can also download snapshots from a trusted block producer. Be aware that there is no way for a node to verify the integrity of these snapshots.https://snapshots.eosnation.io/ (zstd, unzip before using)https://snapshots-main.eossweden.org/ (unzip tar.gz, Use 2.0)https://snapshots.greymass.network/eos/ (unzip tar.gz, use latest)https://snapshots.eosamsterdam.net/public/eos/ (tsv, use latest)http://seed01.eosusa.news/snaps/eos/ (unzip tar.gz, use last modified)Replaying blockchain history from the start is an alternative to using a snapshot, but it can take weeks to complete.Several configuration options have changed. Nodeos will fail to start if invalid configuration options are present. The Reversible Block Database configuration has been removed, and operators should remove these parameters from config.ini and other scripts:reversible-blocks-db-size-mb reversible-blocks-db-guard-size-mb fix-reversible-blocks import-reversible-blocksexport-reversible-blocksThe Block log splitting feature from nodeos 2.1 has been removed and changed to log block rotation. Remove the following parameters::blocks-log-stridemax-retained-block-filesblocks-archive-dirAnd replace them with:block-log-retain-blocks Any nodes currently running EOSIO 2.1 should remove the state history.From the data directory, delete files from the /state-history directory usingrm <nodeos data directory>/state-history/* Any nodes that have block log version 0004 from 2.1 should remove Block logs: From the data directory, delete files from the /blocks directory usingrm <nodeos data directory>/blocks/*rm <nodeos data directory>/blocks/reversible/*
The following installation uses snapshots. Node operators who need to replay transactions for SHiP or block logs should know that a replay can take weeks to complete.
Notes for improving resync speed for blocks.log files (For 2.1 nodes):
By default, nodeos syncs 100 blocks at a time. You can potentially speed up resync using the –sync-fetch-span option, which changes the number of blocks synced at a time. This option is particularly effective with blocks that are mostly empty. Operators have reported setting the number as high as 5000. Once the resync is complete, you should set this number back to 100.
In addition, when resyncing, nodeos requests the same batches of blocks from all peers. This slows down the resync process, and is often unnecessary for trusted peers. You can choose to sync with a limited number of peers rather than all peers, which speeds up sync by avoiding duplicate data. If you feel confident, you can even pick the single closest peer node from which to sync. It is fastest to sync from a single peer located in the same datacenter.
If you use one of these practices to increase sync speed, make sure to revert options to their default settings afterward to avoid unexpected behavior.
Updating Binaries
Do these steps on a test machine before repeating the steps with production machines.
Start with a fresh Ubuntu node or update an existing node by stopping nodeos and removing the old binaries. To remove old binaries, you can generally use:dpkg --remove <old-pkg-name> Remove the state file. To delete the files in this directory, you can use:rm <nodeos data directory>/state/* Update binariesDownload the most recent Ubuntu binaries from the GitHub releases pageOpen a Terminal window and run dpkg -i filename.deb, replacing filename.deb with the file name of the downloaded Ubuntu package.Start nodeos with the snapshot.
After these steps, a node is ready for protocol activation on September 21.
System Contracts and Applications
After Mandel installation, node operators are ready for block producers to activate new features. At some point after activation, block producers can update the system contracts.
Mandel’s new features bring powerful UX improvements. However, users won’t be able to use these tools immediately because a time lag may occur while developers update their apps to take advantage of the new features.
The first applications to use new Mandel features are most likely to be the Trust EVM contract and the most popular wallets. Other applications will take time to incorporate new Mandel features into their workflows. While the release of a software development kit (SDK) will accelerate the availability of Mandel features, adoption will still take time.
Additional Considerations
Block producers activate all of the new features in Mandel 3.1 simultaneously. Although issues are unlikely, these changes may impact smart contracts and dApps. Developers can use public testnets like Jungle4 to ensure their dApps continue to work as expected. Developers can also use these test networks to test new Mandel features.
The Contract Development Toolkit (CDT) has been upgraded, and anyone using this tool should be aware of some minor naming changes:
CDT 3.1 changes the names of its binaries to replace “eosio” prefixes with “cdt” instead, as in cdt-cpp instead of eosio-cpp.For CMake projects, use find_package(cdt) instead of find_package(eosio.cdt).
The next release will likely include more naming changes.
Conclusion
The EOS network directly developed and financed the Mandel 3.1 upgrade, with arms wide open to suggestions from developers and operators. This release represents a new era of development for chains built on the EOSIO codebase and a step forward onto solid ground after years mired in the unpredictable bog of a negligent steward. With the focus and direction of the ENF and the approval and consensus of block producers, EOS is finally seizing the reins of its destiny.
EOS Network
The EOS Network is a 3rd generation blockchain platform powered by the EOS VM, a low-latency, highly performant, and extensible WebAssembly engine for deterministic execution of near feeless transactions; purpose-built for enabling optimal web3 user and developer experiences. EOS is the flagship blockchain and financial center of the EOSIO protocol, serving as the driving force behind multi-chain collaboration and public goods funding for tools and infrastructure through the EOS Network Foundation (ENF).
EOS Network Foundation
The EOS Network Foundation (ENF) is a not-for-profit organization that coordinates financial and non-financial support to encourage the growth and development of the EOS Network. The ENF is the hub of the EOS Network, harnessing the power of decentralization as a force for positive global change to chart a coordinated future for EOS.
The post Mandel 3.1 Upgrade Guide appeared first on EOS Network Foundation.