Upgrade Instructions (v2.2)
This guide describes the steps for upgrading Sonic mainnet and/or testnet nodes to the latest version v2.2.0, which includes the Ethereum Osaka feature set, supports Transaction Bundles, extends allowed code size, and adds several important security improvements.
The upgrade applies only to a running Sonic Network node, both the mainnet and the testnet.
If you are not sure which network your node operates on, you can query the node using console command below (use proper <datadir> path). The node should respond with network id 146 for the mainnet node, and with network id 14601 for the testnet node.
sudo sonictool --datadir /var/lib/sonic/ cli --exec "net.version"Once upgraded, your nodes will continue to operate on the current network until the full transition. The upgrade is backward compatible, meaning you can upgrade now without any interruption.
Important: If you did not recreate your p2p node key during the previous node upgrade, we recommend you to do so as part of this procedure. You can do it by removing <datadir>/p2p/nodekey file before restarting your node. A new p2p node ID will be created, which may break your static peering setups.
The guide covers the following steps:
Upgrade Steps Overview
Update your operating system.
Verify the version and upgrade the Golang version to v1.26 or newer as needed.
Obtain the latest Sonic release source code from GitHub.
Build the source code into a binary client.
Update the active Sonic binary to the new one, and verify the proper version is used.
Stop the currently running client gracefully.
Verify the client is not running.
Validators, pay attention to your node being recognized as in maintenance by the network before you proceed.
Start the node with the new Sonic client version.
Verify the new version is up and running.
1. Build Sonic Client and Tooling
Building the Sonic client binary requires the essential software compilation tools and the Go language version 1.26 or newer to be available. Please refer to your Linux distribution manuals to obtain the development tools on your system.
Make sure you use a clean copy of the Sonic client source code from the official GitHub repository. A modified client may lead to an inconsistent state, which will disconnect your node from the network.
Build the Sonic client:
Download the latest Sonic client source code from the official GitHub repository.
Switch to the most recent Sonic release.
(Optional) Verify your source code consistency.
Build the Sonic binary using the provided configuration.
Check the Sonic binary version (the most recent version is v2.2.0).
(Optional, root) Transfer the new binaries to the bin folder for system-wide access.
If you are reusing your existing Sonic client source code clone with a patch applied, this patch may prevent you from properly switching to the latest release.
We recommend either deleting the old source code repository and downloading the latest one or cleaning up your local copy using: git checkout -- .
2. Prime Sonic State DB From Genesis File (Optional)
This step applies only if you did not run the client before or you want to launch with a new, clean copy of the Sonic database. A freshly recreated database has a slightly smaller footprint, but the process may take up to a day to finish based on your system configuration.
Note that the database of the Sonic client v2.1.6 is fully compatible with the new Sonic client version v2.2.0. If your node has been running the previous version v2.1.6, and the node has been shut down gracefully, your database can be reused. If this is the case, you can safely skip this step.
To proceed, download the most recent Sonic network genesis file. You need to choose between “pruned” and “archive” versions of the genesis file based on your node designated feature set. The pruned one is used mostly by validators so that the database footprint is minimal. It can also be used to prime full node with block history reduced up to the block specified on the download page. The archive version contains all the network history and is intended for an archive node.
The downloaded genesis file will be utilized to prime your local database and will allow you to join the network and synchronize with it after priming. The file consistency can be verified in advance using the provided checksum.
Download the propper genesis file
You can obtain the selected genesis file here:
Download the genesis file.
(Optional) Download the genesis checksum file.
(Optional) Validate the genesis file consistency.
Expected output is:
latest-sonic-archive.g: OK
Prime Sonic Database From Downloaded Genesis
Use the sonictool app (created during the building process as build/sonictool) to prime a validated archive or pruned state database for the Sonic client.
Start the genesis expansion for archive mode. You can use a pruned genesis file
latest-sonic-pruned.ginstead of an archive genesis to prime full node.Start the genesis expansion for validator mode.
The last step of the genesis processing is the state validation. Please check that the output log contains a message with the correct block index and state root hash. The expected block index and state root hash for each genesis file is provided on the download page.
Expected output (your block index and root hash will differ based on the genesis file used):
3. Restart Sonic Node With New Version and Synchronize
With the Sonic node binary created and the state database available, you are ready to start the node on the new version and synchronize its state with the network.
1. Stop Current Node
Stop the running instance gracefully. If you use Systemd manager to handle the Sonic node control, execute the stop procedure:
Other management systems may require different shutdown procedures. You may also use the general OS termination signal via pkill sonicd. But in this case, you need to make sure the client was terminated, and the control system did not attempt to restart it automatically.
Your Sonic node may need up to several minutes to close gracefully based on your system, configuration, and load. Please make sure your node is not closed forcefully. Your database would become corrupted otherwise.
Wait until the node terminates gracefully. Make sure the node is not running:
This step is extremely important for validators. If you run more than one client instance with the same validator key unlocked, your nodes may unintentionally violate the network rules, and your stake may be lost.
2. Start New Node
Start the node using the new client version. Use the node database path (<datadir>) from the previous installation or the new genesis expansion created in the previous step.
Runtime Settings
Dedicate ≈90% of the system RAM as the GOMEMLIMIT environment variable value. The limit should always be set. If not done correctly, your node may experience random crashes and subsequent state database corruption.
We advise using ≈12 GiB of the RAM denominated in KiB as the --cache value. Larger cache size may help to speed up specific RPC workloads, but the gain diminishes very quickly.
Replace the <datadir> with the correct path to the database. We recommend that validators use the --mode validator flag to achieve smaller database footprint. Different starting flags may need to be added to start an archive node with active Web3 RPC and WebSocket interfaces. A local IPC communication socket is opened by default.
Please obtain and explicitly specify the external IP address of your node as a starting flag to help with the inter-node peer-to-peer connectivity.
Last updated