> For the complete documentation index, see [llms.txt](https://docs.soniclabs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soniclabs.com/sonic/node-deployment/upgrade-instructions-v2.2.md). # Upgrade Instructions (v2.2) This guide describes the steps for upgrading Sonic **mainnet** and/or **testnet** nodes to the latest version [v2.2.0](https://github.com/0xsoniclabs/sonic/releases/tag/v2.2.0), which includes the Ethereum Osaka feature set, supports Transaction Bundles, extends allowed code size, and adds several important security improvements. {% hint style="warning" %} 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 `` path). The node should respond with network id 146 for the mainnet node, and with network id 14601 for the testnet node. ```bash sudo sonictool --datadir /var/lib/sonic/ cli --exec "net.version" ``` {% endhint %} 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. {% hint style="info" %} **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 `/p2p/nodekey` file before restarting your node. A new p2p node ID will be created, which may break your static peering setups. {% endhint %} The guide covers the following steps: 1. [Build Sonic Client and Tooling](#id-1.-build-sonic-client-and-tooling) 2. [Prime Sonic State DB From Genesis File (Optional)](#id-2.-prime-sonic-state-db-from-genesis-file-optional) 3. [Restart Sonic Node With New Version and Synchronize](#id-3.-restart-sonic-node-with-new-version-and-synchronize) ## Upgrade Steps Overview 1. Update your operating system. 2. Verify the version and upgrade the [Golang](https://go.dev/dl/) version to v1.26 or newer as needed. 3. Obtain the latest [Sonic release](https://github.com/0xsoniclabs/sonic/releases) source code from GitHub. 4. Build the source code into a binary client. 5. Update the active Sonic binary to the new one, and verify the proper version is used. 6. Stop the currently running client gracefully. 7. Verify the client is not running. 8. Validators, pay attention to your node being recognized as [*in maintenance*](https://xapi.sonic.soniclabs.com/html/validators/down) by the network before you proceed. 9. Start the node with the new Sonic client version. 10. 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](https://go.dev/dl/) language version 1.26 or newer to be available. Please refer to your Linux distribution manuals to obtain the development tools on your system. {% hint style="danger" %} **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.** {% endhint %} Build the Sonic client: 1. Download the latest Sonic client source code from the official GitHub repository. ```bash git clone https://github.com/0xsoniclabs/sonic.git ``` 2. Switch to the most recent [Sonic release](https://github.com/0xsoniclabs/sonic/releases/latest). ```bash cd sonic && git fetch --tags && git checkout -b v2.2.0 tags/v2.2.0 ``` 3. (Optional) Verify your source code consistency. ```bash git status && git log -n1 ``` 4. Build the Sonic binary using the provided configuration. ```bash make all ``` 5. Check the Sonic binary version (the most recent version is v2.2.0). ```bash build/sonicd version ``` 6. (Optional, root) Transfer the new binaries to the bin folder for system-wide access. ```bash sudo mv build/sonic* /usr/local/bin/ ``` {% hint style="info" %} 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 -- .` {% endhint %} ## 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](https://genesis.soniclabs.com/). 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](https://genesis.soniclabs.com/). 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: * * 1. Download the genesis file. ```bash curl -JLO https://genesis.soniclabs.com/latest-sonic-archive.g ``` 2. (Optional) Download the genesis checksum file. ```bash curl -JLO https://genesis.soniclabs.com/latest-sonic-archive.g.md5 ``` 3. (Optional) Validate the genesis file consistency. ```bash md5sum --check --ignore-missing latest-sonic-archive.g.md5 ``` 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.g` instead of an archive genesis to prime full node. 
GOMEMLIMIT=14GiB sonictool --datadir --cache 12000 genesis --mode rpc latest-sonic-archive.g
* Start the genesis expansion for validator mode. 
GOMEMLIMIT=14GiB sonictool --datadir --cache 12000 genesis --mode validator latest-sonic-pruned.g
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](https://genesis.soniclabs.com/). Expected output (your block index and root hash will differ based on the genesis file used): {% code overflow="wrap" %} ``` StateDB imported successfully, stateRoot matches module=gossip-store index=45456335 root="7619c4...0140ac" ``` {% endcode %} ## 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: {% code overflow="wrap" %} ```bash systemctl stop sonicd ``` {% endcode %} 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. {% hint style="info" %} 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. {% endhint %} Wait until the node terminates gracefully. Make sure the node is not running: {% code overflow="wrap" %} ```bash ps aux | grep "[s]onicd" ``` {% endcode %} {% hint style="warning" %} This step is [extremely important for validators](https://xapi.sonic.soniclabs.com/html/validators/down). 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. {% endhint %} **2. Start New Node** Start the node using the new client version. Use the node database path (``) from the previous installation or the new genesis expansion created in [the previous step](#id-2.-prime-sonic-state-db-from-genesis-file-optional). {% code overflow="wrap" %} ```bash systemctl start sonicd ``` {% endcode %} ### **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 `` 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. {% hint style="info" %} 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. {% code overflow="wrap" %} ```bash curl -4s ifconfig.me/ip ``` {% endcode %} {% endhint %} {% code overflow="wrap" %} ```bash GOMEMLIMIT=30GiB sonicd --datadir --cache 12000 --nat extip: ``` {% endcode %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.soniclabs.com/sonic/node-deployment/upgrade-instructions-v2.2.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.