Upgrade Instructions (2.1)
Last updated
Last updated
This guide describes the steps for upgrading a Sonic mainnet node to the latest 2.1 version.
Once upgraded, your nodes will continue to operate on the current mainnet until the full transition. The upgrade is backward compatible, meaning you can upgrade now without any interruption.
The guide covers the following steps:
Update your operating system.
Verify the version and upgrade the Golang version to v1.24 or newer as needed.
Obtain the new Sonic release v2.1 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.
Building the Sonic client binary requires the essential software compilation tools and the Go language version 1.24 or newer to be available. Please refer to your Linux distribution manuals to obtain the development tools on your system.
Build the Sonic client:
Download the Sonic source code from the official GitHub repository.
https://github.com/0xsoniclabs/sonic.git
Switch to the most recent Sonic release.
git fetch --tags && git checkout -b v2.1.0 tags/v2.1.0
Build the Sonic binary using the provided configuration.
make all
Check the Sonic binary version (the most recent version is v2.1.0).
build/sonicd version
(Optional, root) Transfer the new binaries to the bin folder for system-wide access.
sudo mv build/sonic* /usr/local/bin/
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.
Note that the database of the Sonic client versions 2.0.1 to 2.0.7 is fully compatible with the new Sonic client version v2.1.0. If your node has been running one of the versions v2.0.1 to v2.0.7, and the node has been shut down gracefully, your database can be reused, and you can skip this step.
Download the most recent Sonic network genesis file. Based on your node designated feature set, you need to choose between “pruned” and “full” versions of the genesis file. The pruned one is used by validators so that the database footprint is minimal. The full version contains all the network history and is used for the archive node.
The genesis file will be used to prime your database and will allow you to join the network and synchronize with it after priming. Please double-check the downloaded genesis file using the provided checksum.
You can obtain the selected genesis file here:
Download the genesis file.
wget https://genesis.soniclabs.com/sonic-mainnet/genesis/sonic-38000-full.g
(Optional) Download the genesis checksum file.
wget https://genesis.soniclabs.com/sonic-mainnet/genesis/sonic-38000-full.g.md5
(Optional) Validate the genesis file consistency.
md5sum --check sonic-38000-full.g.md
Expected output is: sonic-38000-full.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 state database for the Sonic client.
Start the genesis expansion for archive mode.
GOMEMLIMIT=50GiB sonictool --datadir --cache 12000 genesis --mode rpc
Start the genesis expansion for validator mode.
GOMEMLIMIT=50GiB sonictool --datadir --cache 12000 genesis --mode validator
The last step of the genesis processing is the state validation. Please check that the output log contains a message with the correct root hash:
StateDB imported successfully, stateRoot matches module=gossip-store index=42999003 root="6ee505...b8e7c0"
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: systemctl stop sonicd
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.
Wait until the node terminates gracefully. Make sure the node is not running: ps aux|grep sonicd.
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
Use the node database path (<datadir>) from the previous installation or the new expansion created in the previous step.
Start the node using the new client version.
systemctl start sonicd
Use ≈90% of the RAM as the GOMEMLIMIT value. The limit should always be set. If not done correctly, your node may experience random crashes and subsequent state database corruption. Use ≈12 GiB of the RAM as the --cache value.
Replace the <datadir> with the correct path to the database. We recommend that validators use the --mode validator flag to obtain a smaller database footprint. Different starting flags may need to be added to start an archive node with Web3 RPC and WebSocket interfaces on the node.
GOMEMLIMIT=50GiB sonicd --datadir <datadir> --cache 12000 --nat extip:<public external IP address>