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

This is a walk-through for how to perform the update of the xxnetwork-chain binary to the latest version as of January 23, 2023, version 0.2.5-2.

Releases are located at …


  • This is a mandatory upgrade as we will be discontinuing the old bootnodes by the end of the month. Please upgrade at your convenience.

  • 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.

  • :warning: Those who initialized the chain database on the node computer with xxnetwork-chain ver. 0.2.5 or earlier should expect to see an Error when starting xxnetwork-chain for the first time after updating. Below are instructions on how to handle the Error See step 3h.

The xxnetwork-chain v0.2.5-2 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-2-81384c39acd, 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-2 of the xxnetwork-chain binary …

$ curl -L -o xxnetwork-chain https://github.com/xx-labs/xxchain/releases/download/v0.2.5-2/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 
7e970e7ff9506cb78718ca2a502576df1991f162ca71074da6c8d5ef5858622e  xxnetwork-chain

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

$ /opt/xxnetwork/bin/xxnetwork-chain --version
xxnetwork-chain 0.2.5-2-81384c39acd

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 ✨ Imported #3024475 (0x6436…3523)    
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)

:warning: Those who initialized the chain database on the node computer with xxnetwork-chain ver. 0.2.5 or earlier will see the following Error. It will print immediately after starting the xxnetwork-chain. This issue does not corrupt the database and only requires a fairly simple fix to resolve.

Error: Service(Client(StateDatabase("Incompatible pruning modes [stored: ArchiveAll; requested: Constrained(Constraints { max_blocks: Some(256) })]")))

If on the node computer you see the above Error do the following.

Stop the chain service

$ sudo systemctl stop xxnetwork-chain

Open the xxnetwork-chain.service file with …

nano /opt/xxnetwork/xxnetwork-chain.service

Move to the line that starts with ExecStart and after the flag --validator add --state-pruning archive
You can see an example below:

ExecStart=/bin/bash -c "/opt/xxnetwork/bin/xxnetwork-chain --validator --state-pruning archive --telemetry-url 'wss://telemetry.polkadot.io/submit/ 0' --base-path /opt/xxnetwork/db --port 15974 --ws-port 63007  >> /opt/xxnetwork/log/chain.log 2>&1"

You can save and close nano by pressing Ctrl+s then Crtl+x
Next run …

sudo systemctl daemon-reexec

Now start the xxnetwork-chain service again with …

sudo systemctl start xxnetwork-chain

Go back to Step 3h and check the log. If you see the desired output continue to step 3i

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-2.

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!


RE: new bootnodes which use DNS in ver. 0.2.5-2

After the update you may occasionally see the following message in the chain.log:

yyyy-mm-dd hh:mm:ss 💔 The bootnode you want to connect to at `/ip4/[IP ADDRESS]/tcp/15974/p2p/[PEER_ID]` provided a different peer ID `[PEER_ID]` than the one you expect `[PEER_ID]`.

It can be ignored. This is a message related to the changes of the bootnodes. We moved the bootnodes out of AWS into multiple cloud providers for more resilience. We have temporarily set up proxies from the old bootnodes’ IP addresses to the new ones. In time these messages will stop appearing once we stop the proxies or after everyone updates to 0.2.5-2.

1 Like