Upgrade Procedure for xxnetwork-chain v0.2.4 (Optional Upgrade)

This is a walk-through for how to perform the optional upgrade of the xxnetwork-chain binary to the latest version as of July 14, 2022, version 0.2.4, xxnetwork-chain 0.2.4-9ff6c85-x86_64-linux-gnu.

Releases are located at …

The substrate architecture allows splitting the logic that governs the blockchain state transitions (runtime) from everything else necessary for the blockchain node (networking, database, execution, mempool, collectively we refer to this as the client).

The binary contains both the client and the (native) runtime. However, the runtime is also stored on chain in a version compiled to WASM. This is the one that every validator in the network executes when processing transactions and blocks. This means that anytime a new runtime is released, we release a binary containing its native version (compiled from rust to the target architecture) but also we upgrade the runtime on chain. This means that you don’t need to update the node binary in order to keep executing the new runtimes as they are upgraded on chain.

It is recommended to use the latest binary for sync purposes, since the native Runtime can be faster than the WASM one, however it’s not strictly necessary for node operators to upgrade the binary. Mandatory upgrades are denoted as such in the release notes, and this is usually only done if there are client side changes to the binary.


  • This is not a mandatory upgrade.

  • This walk-through assumes the node and gateway computers were configured per the Node Handbook

  • The entire process shouldn’t take a novice Linux user more than 10-15 minutes.

  • If you’re not familiar with Linux, I suggest you proceed through the steps in the order they appear.

  • Sample output is provided for commands that generate output to assist but some sample output will not be exactly as shown.

  • Please review the following process at least once to get a feel of what is required.

The xxnetwork-chain v0.2.4 Binary Upgrade Procedure:

Step 1: On BOTH computers get the current version of the xxnetwork-chain binary by running the following command.

$ /opt/xxnetwork/bin/xxnetwork-chain --version
xxnetwork-chain 0.2.3-6f32766-x86_64-macos

If the previous command returns xxnetwork-chain 0.2.4-9ff6c85-x86_64-linux-gnu, then you should not continue. You are running the latest version.

Step 2: Stop all of the xx network services on BOTH computers:

2a. On the NODE computer run …

$ sudo systemctl stop xxnetwork-cmix
$ sudo systemctl stop xxnetwork-chain

2b. On the GATEWAY computer …

$ sudo systemctl stop xxnetwork-gateway
$ sudo systemctl stop xxnetwork-chain

Step 3: Run the following series of commands as they appear on BOTH the node and gateway computers:

3a. Change to the directory where the xx network binaries are located …

$ cd /opt/xxnetwork/bin

3b. Backup the existing xxnetwork-chain binary …

$ mv -v xxnetwork-chain xxnetwork-chain.bak
renamed 'xxnetwork-chain' -> 'xxnetwork-chain.bak'

3c. Download version 0.2.4 of the xxnetwork-chain binary …

$ curl -L -O https://github.com/xx-labs/xxchain/releases/download/v0.2.4/xxnetwork-chain
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
100 76.3M  100 76.3M    0     0  11.7M      0  0:00:06  0:00:06 --:--:-- 14.0M

3d. Verify the checksum of the xxnetwork-chain binary …

$ sha256sum xxnetwork-chain 
e7d72e972ecb0424f7414902a8c6bfb817dde57b58021ae6c9bd3c7f02a51fb7  xxnetwork-chain

The output above is the unique checksum for the 0.2.4 binary file and must be e7d72e972ecb0424f7414902a8c6bfb817dde57b58021ae6c9bd3c7f02a51fb7. If anything else is returned, the download may have failed and you likely just need to re-run the curl command. If it still does not match after trying to download again, please stop and ask for assistance here or on the xx Network Discord Server.

3e. Make the xxnetwork-chain binary executionable …

$ chmod -v +x xxnetwork-chain
mode of 'xxnetwork-chain' changed from 0664 (rw-rw-r--) to 0775 (rwxrwxr-x)

3f. Ensure the downloaded binary is version 0.2.4 …

$ /opt/xxnetwork/bin/xxnetwork-chain --version
xxnetwork-chain 0.2.4-9ff6c85-x86_64-linux-gnu

3g. Start the xxnetwork-chain service …

$ sudo systemctl start xxnetwork-chain

3h. Check the chain.log to ensure the process is running and is synced …

$ tail -F /opt/xxnetwork/log/chain.log

Depending on how log the previous steps took to complete, you may need to wait a few minutes before you see the desired messages. You want to ensure you see ✨ Imported and 💤 Idle messages scrolling by like so …

2022-06-17 08:17:42 💤 Idle (27 peers), best: #3024475 (0x6436…3523), finalized #3024472 (0xce9e…ab5b), ⬇ 235.9kiB/s ⬆ 487.7kiB/s 
2022-06-17 08:17:22 💤 Idle (27 peers), best: #3024472 (0xce9e…ab5b), finalized #3024470 (0x8c4e…c457), ⬇ 291.2kiB/s ⬆ 543.4kiB/s    
2022-06-17 08:17:24 ✨ Imported #3024473 (0x6b42…7d67)    
2022-06-17 08:17:27 💤 Idle (27 peers), best: #3024473 (0x6b42…7d67), finalized #3024471 (0x7669…21b0), ⬇ 296.4kiB/s ⬆ 590.6kiB/s    
2022-06-17 08:17:32 💤 Idle (27 peers), best: #3024473 (0x6b42…7d67), finalized #3024471 (0x7669…21b0), ⬇ 289.6kiB/s ⬆ 509.9kiB/s    
2022-06-17 08:17:36 ✨ Imported #3024474 (0xf3c8…8490)    
2022-06-17 08:17:37 💤 Idle (27 peers), best: #3024474 (0xf3c8…8490), finalized #3024472 (0xce9e…ab5b), ⬇ 598.2kiB/s ⬆ 622.8kiB/s    
2022-06-17 08:17:42 ✨ Imported #3024475 (0x65ae…b01c)

3i. Terminate tail
Press Ctrl+c

Step 4: Start the gateway and cmix services:

4a. On the GATEWAY computer …

$ sudo systemctl start xxnetwork-gateway

4b. On the NODE computer …

$ sudo systemctl start xxnetwork-cmix

That completes the steps required to upgrade the xxnetwork-chain binary to version 0.2.4.

To check the status of the xx network services you can run …

$ systemctl status xxnetwork-*

To check the xx network processes are running you can run …

$ ps -A | grep xxn

All logs related to xx network are located in /opt/xxnetwork/log
Feel free to ask for assistance here or on the xx Network Discord Server.

Thanks for running a node!

Will this update be added to the official mainnet bundle?

This update has been included in new tarballs which were pushed earlier today. It had been a while so we decided to generate new tarballs this time but v0.2.4 is not mandatory.

The tarballs are intended for new deployments of nodes/gateways joining the network or if one must re-install, not for upgrading. No one should be rushing to download new tarballs and re-installing as a method to upgrade their existing nodes/gateways.

Operators can upgrade to v0.2.4 using the instructions provided in the original post above at their convenience.

Keep in mind, even if the xxnetwork-chain binary from the previous tarball is being used, it is not an issue. Most of the network is actually on 0.2.0-7c5814f


1 Like

Sure, but I was after a possibly more efficient version (given the reduced size). That didn’t seem to materialize - I can’t tell if there’s any difference. But it works as well as the previous version, so all good!