Upgrade Procedure for xxnetwork-chain v0.2.5-1 (Mandatory Upgrade)

This is a walk-through for how to perform the mandatory upgrade of the xxnetwork-chain binary to the latest version as of October 15, 2022, version 0.2.5-1, xxnetwork-chain 0.2.5-1-8bcb0e65356.

!! The network is running, but in order to ensure it doesn’t stop we need 2/3rds of the network to update and run the new binary by 07:00 AM UTC 15th October. !!

Releases are located at …


  • This is 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.5-1 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.5-a26979c-x86_64-linux-gnu

If the previous command returns xxnetwork-chain 0.2.5-1-8bcb0e65356, 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.5-1 of the xxnetwork-chain binary …

$ curl -L -o xxnetwork-chain -O https://github.com/xx-labs/xxchain/releases/download/v0.2.5-1/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 81.3M  100 81.3M    0     0  8048k      0  0:00:10  0:00:10 --:--:-- 12.8M

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

$ sha256sum xxnetwork-chain 
6f96076b48e75bb43d0598a68b5482e0648b41cec0c38a6d16d9cf17742ad596  xxnetwork-chain

The output above is the unique checksum for the 0.2.5-1 binary file and must be 6f96076b48e75bb43d0598a68b5482e0648b41cec0c38a6d16d9cf17742ad596. 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 executable …

$ 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.5-1 …

$ /opt/xxnetwork/bin/xxnetwork-chain --version
xxnetwork-chain 0.2.5-1-8bcb0e65356

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.5-1.

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.

NOTICE: Validators that previously used flags such as --sync Warp --unsafe-pruning --pruning=1000 will likely see the following error and be required to deleted and resync the chain database data.

Error: Service(Client(StateDatabase("Invalid metadata: An existing StateDb does not have PRUNING_MODE stored in its meta-data")))

For instructions to delete and resync the chain database data, please see the instructions provided in the following post …

Thanks for running a node!


FOLLOW-UP: October 17, 2022

For those who were not present over the weekend, and are just now performing the mandatory upgrade to 0.2.5-1, there is a good chance your validator was slashed or chilled and the cMix dashboard is showing NOT CURRENTLY A VALIDATOR. It may be necessary that you re-validate.

After upgrading the binaries…

Check that you are validating.
You will see Stop or Validate beside the validator stash.

If you see Validate press Validate, set your commission and sign the transaction.
Then check you are waiting to be elected…

If you see Stop, do not press Stop, check if you are waiting to be elected…

If you are now waiting, all you should need to do at this point is wait to be elected.


FOLLOW-UP: October 29, 2022

Only about 5% of the network hasn’t updated.

If your node is OFFLINE on the cMix dashboard and you see …

WARN 2022/10/28 20:48:55 Poll of permissioning failed, will try again in 1s: Unable to send Poll: rpc error: code = 
Unknown desc = The gateway version "3.8.0" is incompatible with the required version "3.10.0".

… in the cmix.log …

Follow the procedure above to update the chain binary which will result in the gateway binary being updated via the wrapper script and will get your node and gateway back ONLINE.