Updating the Client

Created by Jonathan Waldenfels
Last updated: Jul 08, 2021 by Kiran Roy

Note: As of June 4th, 2021, all EWC validator and full nodes should run OpenEthereum v3.2.5 (https://github.com/openethereum/openethereum/releases/tag/v3.2.5) or Nethermind v1.10.72 (https://github.com/NethermindEth/nethermind/releases/tag/1.10.72 ).



What

Description

Purpose

Documentation to update Validator Node client in preparation for Berlin Hard Fork:

  • For Validators running Parity client(v2.5.13), update is to OpenEthereum client(v3.2.5)

  • For Validators running Nethermind Client (v1.10.71 or earlier), update is to Nethermind client (v1.10.72)

Creator

EWF Team

The update schedule

OpenEthereum and Nethermind clients compatible with AuRa are released in a regular rhythm. The process for implementing regular updates is described below. Emergency updates (i.e. in the event of a known security vulnerability with a specific client version) will be accelerated.

All EWC client updates are tested by the EWF team to ensure compatibility with the EW Chain AuRa consensus mechanism. EWF strongly recommends validators and other node (e.g. RPC) operators refrain from updating their clients until compatibility with the current version is confirmed on this page. Once EWF has completed testing of each update, we will communicate to validators and the broader community via Slack and Telegram that it is safe to install the new version; this page will also be updated regularly. For security/stability reasons, we recommend rolling out the update in waves, first on Volta and then the production EW Chain. During an update, validators will be split into two or more groups to simplify coordination and help maintain overall network stability.

Below is an example of how this works (actual timelines may vary):

  • Group 1 (e.g., address ends in letter or 0)
    Group 2 (e.g., address ends in number > 0)
    Group 1 Update Volta on Monday or Tuesday after the 'Go' signal
    Group 1 Update EWC on Thursday or Friday after the Volta update

    Group 2 Update Volta on Thursday or Friday after the 'Go' signal
    Group 2 Update EWC on Monday or Tuesday (the week after the Volta update)

Updating the client

Good to know:

OpenEthereum Client update doesn’t change any of the following

  • Node Address

  • Node key

  • Private key

  • Secret

Before applying the upgrade, ensure the validator node instance has the following requirements -

CPU

Memory(GiB)

Network Capacity(GiB)

Storage(GB) and Type

4 (Minimum)

8 (Recommended)

8 (Minimum)

16 (Recommended)

Up to 5 (Minimum)

Up to 10 (Recommended)

Minimum 300, SSD

Manual Upgrade

Step 1

Stop the blockchain node by halting all running docker containers

  • 1 2 3 4 5 6 #Escalate user permissions: run as administrator sudo su #Halt the blockchain by stopping the docker containers cd $HOME/docker-stack docker-compose stop

Your blockchain node has now halted - you are ready to proceed with the installation

Step 2

Change the configuration files so the system knows what type of node software you want to run

  • Better be safe than sorry - backup current settings

    1 2 #Backup .env file that contains node setting cp $HOME/docker-stack/.env $HOME/docker-stack/.env_backup

     

  • download the node software (Openethereum v3.2.5)

    1 docker pull openethereum/openethereum:v3.2.5

 

  • verify the downloaded software to make sure no one has changed something during data transfer

    1 docker image inspect openethereum/openethereum:v3.2.5 | jq -r '.[0].Id'

You should see this hash as a result
sha256:5456244fb93fa6100e83b6dbebb9bc6f43d729522554da065b28967084bb7ee3

 

  • update the .env configuration file

    1 nano .env

you can also use vim or emacs to edit the file, up to you

  • locate these 2 variables and update these 2 settings

    1 2 PARITY_VERSION=openethereum/openethereum:v3.2.5 PARITY_CHKSUM=sha256:5456244fb93fa6100e83b6dbebb9bc6f43d729522554da065b28967084bb7ee3

     

don’t overwrite existing variables

new .env file

old .env file

new .env file

old .env file

1 2 3 4 5 6 7 8 9 VALIDATOR_ADDRESS=$YOUR_VALIDATOR_ADDRESS EXTERNAL_IP=$YOUR_VALIDATOR_IP_ADDRESS PARITY_VERSION=openethereum/openethereum:v3.2.5 PARITYTELEMETRY_VERSION=1.1.0 IS_SIGNING=signing PARITY_KEY_FILE=./chain-data/keys/EnergyWebChain/UTC--XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX CHAINSPEC_CHKSUM= CHAINSPEC_URL=https://example.com PARITY_CHKSUM=sha256:5456244fb93fa6100e83b6dbebb9bc6f43d729522554da065b28967084bb7ee3
1 2 3 4 5 6 7 8 9 VALIDATOR_ADDRESS=$YOUR_VALIDATOR_ADDRESS EXTERNAL_IP=$YOUR_VALIDATOR_IP_ADDRESS PARITY_VERSION=parity/parity:v2.5.13-stable PARITYTELEMETRY_VERSION=1.1.0 IS_SIGNING=signing PARITY_KEY_FILE=./chain-data/keys/EnergyWebChain/UTC--XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX CHAINSPEC_CHKSUM= CHAINSPEC_URL=https://example.com PARITY_CHKSUM=sha256:36be05aeb6426b5615e2d6b71c9590dbc4a4d03ae7bcfa53edefdaeef28d3f41

 

  • Step 3

Change the docker configuration files so the system can build the new docker containers
$HOME/docker-stack/

  • Better be safe than sorry - backup current settings

    1 cp $HOME/docker-stack/docker-compose.yml $HOME/docker-stack/docker-compose.yml_backup

  • Update openethereum path in docker-compose.yml file.

    1 2 3 4 5 6 #make sure you're in the docker-stack directory cd $HOME/docker-stack/ # edit line no. 11 from docker-compose.yml # use a text editor to ./chain-data:/home/openethereum/.local/share/io.parity.ethereum/

So you had to change

./chain-data:/home/parity/.local/share/io.parity.ethereum/ to ./chain-data:/home/openethereum/.local/share/io.parity.ethereum/

new docker-compose.yml

old docker-compose.yml

new docker-compose.yml

old docker-compose.yml

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 version: '2.0' services: parity: image: openethereum/openethereum:v3.2.5 restart: always command: --config /parity/config/parity-signing.toml --nat extip:${EXTERNAL_IP} volumes: - ./config:/parity/config:ro - ./chain-data:/home/openethereum/.local/share/io.parity.ethereum/ - ./.secret:/parity/authority.pwd:ro ports: - 30303:30303 - 30303:30303/udp - 127.0.0.1:8545:8545 parity-telemetry: image: energyweb/parity-telemetry:1.1.0 restart: always environment: - WSURL=ws://parity:8546 - HTTPURL=http://parity:8545 - PIPENAME=/var/spool/parity.sock volumes: - /var/spool/parity.sock:/var/spool/parity.sock
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 version: '2.0' services: parity: image: openethereum/openethereum:v3.2.5 restart: always command: --config /parity/config/parity-signing.toml --nat extip:${EXTERNAL_IP} volumes: - ./config:/parity/config:ro - ./chain-data:/home/parity/.local/share/io.parity.ethereum/ - ./.secret:/parity/authority.pwd:ro ports: - 30303:30303 - 30303:30303/udp - 127.0.0.1:8545:8545 parity-telemetry: image: energyweb/parity-telemetry:1.1.0 restart: always environment: - WSURL=ws://parity:8546 - HTTPURL=http://parity:8545 - PIPENAME=/var/spool/parity.sock volumes: - /var/spool/parity.sock:/var/spool/parity.sock

  • Step 4

We now change the blockchain settings so the system knows the preferences
$HOME/docker-stack/config

  • Yet again, better be safe than sorry - backup current settings (2 )files

    • 1 2 cp $HOME/docker-stack/config/parity-signing.toml $HOME/docker-stack/config/parity-signing.toml_backup cp $HOME/docker-stack/config/parity-non-signing.toml $HOME/docker-stack/config/parity-non-signing.toml_backup

A delicate operation - change settings in 2 files
Some settings need to be removed
Some settings need to be changed

so be careful: Only update common changes that are mentioned below (from below table’s left column) in those two .toml files.

Warning: In the new parity-non-signing.toml file there is no longer an account section.

[account]
password = ["/parity/authority.pwd"]
keys_iterations = 10240

1 2 3 cd $HOME/docker-stack/config #edit parity-signing.toml (you can use other text editor) nano parity-signing.toml

  • Update parity-signing.toml with the following new configuration from the table. (.toml file new Configuration)

  • For your convenience, you shall find the same configuration from the below table’s left column (.toml file old Configuration)

    • 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 # Remove these lines from [parity] section [parity] auto_update = "none" release_track = "current" no_download = true # Remove this section [ui] disable = true # Add port in [websockets] section [websockets] port = 8546 # Remove this line from [network] section [network] no_serve_light = true # Update this in [snapshots] section [snapshots] disable_periodic = true # [Remove this parameter and value from the [snapshots] section] enable = false # [Add this parameter and value in the [snapshots] section]

       

Do the same for parity-non-signing.toml
use the table to check line-by-line what you need to remove/update

1 2 3 cd $HOME/docker-stack/config #edit parity-non-signing.toml (you can use other text editor) nano parity-non-signing.toml

 

parity-signing.toml file new Configuration

parity-signing.toml file old Configuration

parity-non-signing.toml file new Configuration

parity-non-signing.toml file old Configuration

parity-signing.toml file new Configuration

parity-signing.toml file old Configuration

parity-non-signing.toml file new Configuration

parity-non-signing.toml file old Configuration

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 [parity] chain = "/parity/config/chainspec.json" no_persistent_txqueue = true [rpc] disable = false port = 8545 interface = "0.0.0.0" cors = [] apis = ["eth", "net", "parity", "web3"] [websockets] disable = false interface = "0.0.0.0" port = 8546 [ipc] disable = true [secretstore] disable = true [network] port = 30303 min_peers = 25 max_peers = 50 discovery = true warp = false allow_ips = "all" snapshot_peers = 0 max_pending_peers = 64 [footprint] db_compaction = "ssd" [snapshots] enable = false [mining] force_sealing = true usd_per_tx = "0.000000000000000001" usd_per_eth = "1" price_update_period = "hourly" min_gas_price = 1 gas_cap = "$BLOCK_GAS" gas_floor_target = "$BLOCK_GAS" tx_gas_limit = "$BLOCK_GAS" extra_data = "$COMPANY_NAME" engine_signer = "$VALIDATOR_ADDRESS" [account] password = ["/parity/authority.pwd"] keys_iterations = 10240
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 [parity] chain = "/parity/config/chainspec.json" auto_update = "none" release_track = "current" no_download = true no_persistent_txqueue = true [ui] disable = true [rpc] disable = false port = 8545 interface = "0.0.0.0" cors = [] apis = ["eth", "net", "parity", "web3"] [websockets] disable = false interface = "0.0.0.0" [ipc] disable = true [secretstore] disable = true [network] port = 30303 min_peers = 25 max_peers = 50 discovery = true warp = false allow_ips = "all" snapshot_peers = 0 max_pending_peers = 64 no_serve_light = true [footprint] db_compaction = "ssd" [snapshots] disable_periodic = true [mining] force_sealing = true usd_per_tx = "0.000000000000000001" usd_per_eth = "1" price_update_period = "hourly" min_gas_price = 1 gas_cap = "$BLOCK_GAS" gas_floor_target = "$BLOCK_GAS" tx_gas_limit = "$BLOCK_GAS" extra_data = "$COMPANY_NAME" engine_signer = "$VALIDATOR_ADDRESS" [account] password = ["/parity/authority.pwd"] keys_iterations = 10240
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 [parity] chain = "/parity/config/chainspec.json" no_persistent_txqueue = true [rpc] disable = false port = 8545 interface = "0.0.0.0" cors = [] apis = ["eth", "net", "parity", "web3"] [websockets] disable = false interface = "0.0.0.0" port = 8546 [ipc] disable = true [secretstore] disable = true [network] port = 30303 min_peers = 25 max_peers = 50 discovery = true warp = false allow_ips = "all" snapshot_peers = 0 max_pending_peers = 64 [footprint] db_compaction = "ssd" [snapshots] enable = false [mining] force_sealing = true usd_per_tx = "0.000000000000000001" usd_per_eth = "1" price_update_period = "hourly" min_gas_price = 1 gas_cap = "$BLOCK_GAS" gas_floor_target = "$BLOCK_GAS" tx_gas_limit = "$BLOCK_GAS" extra_data = "$COMPANY_NAME"

 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 [parity] chain = "/parity/config/chainspec.json" auto_update = "none" release_track = "current" no_download = true no_persistent_txqueue = true [ui] disable = true [rpc] disable = false port = 8545 interface = "0.0.0.0" cors = [] apis = ["eth", "net", "parity", "web3"] [websockets] disable = false interface = "0.0.0.0" [ipc] disable = true [secretstore] disable = true [network] port = 30303 min_peers = 25 max_peers = 50 discovery = true warp = false allow_ips = "all" snapshot_peers = 0 max_pending_peers = 64 no_serve_light = true [footprint] db_compaction = "ssd" [snapshots] disable_periodic = true [mining] force_sealing = true usd_per_tx = "0.000000000000000001" usd_per_eth = "1" price_update_period = "hourly" min_gas_price = 1 gas_cap = "$BLOCK_GAS" gas_floor_target = "$BLOCK_GAS" tx_gas_limit = "$BLOCK_GAS" extra_data = "$COMPANY_NAME"

 

 

  • Step 5

Almost there - let’s backup the chain db before we’ll rebuild and start the docker containers

change the text $CHAIN_NAME to
Volta or EnergyWebChain

  • 1 2 cd $HOME/docker-stack mv chain-data/chains/$CHAIN_NAME/ ./$CHAIN_NAME_backup

  • Step 6

The moment of thought… let’s restart the docker containers

1 2 cd $HOME/docker-stack docker-compose up -d --force-recreate

 

This process starts the db sync from scratch

That’s it! Congratulations - should work now…

Let’s check the logs to make sure all is up and running/syncing

  • 1 2 3 4 5 6 7 cd $HOME/docker-stack # Check openetherereum logs docker-compose logs -f --tail 100 parity # Check telemetry logs docker-compose logs -f --tail 100 parity-telemetry

Check Node is fully synced

  • Execute the following command on validator instance -

    • 1 curl -X POST --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' localhost:8545 -H 'Content-Type: application/json'

  • If the node is synced, the above command will return the following result

    • 1 {"jsonrpc":"2.0","result":false,"id":1}

  • If the node is yet to be synced, the above command will return the following result

    • 1 {"jsonrpc":"2.0","result":{"currentBlock":"0xXXXXXX","highestBlock":"0xXXXXXX","startingBlock":"0xXXXXXX","warpChunksAmount":null,"warpChunksProcessed":null},"id":1}

If you like to speed up the sync process, use the Chain DB backup

This process is recommended to speed up the Chain DB download. In fact, there is no need to wait for the DB download if you use Chain DB backup.

Here is the Documentation on how to use Chain DB backup

Common issues and Troubleshooting

Issue 1

Node sync process gets stuck in some blocks or the sync takes longer time in some blocks.

Resolution -

  • Stop docker containers

    • > docker-compose stop

  • Remove these 2 files -

    • > rm docker-stack/chain-data/chains/Volta/user_defaults

    • rm docker-stack/chain-data/chains/Volta/network/nodes.json

  • Recreate again the containers

    • > docker-compose up -d --force-recreate

Issue 2

Node reports transaction errors like Validator 0x.... clould not be reported (Transaction error (Gas price too low to replace, previous tx gas: None, new tx gas: Node)) on block ...

Resolution -  

  • Comment [mining] from parity-signing.toml  file

    • 1 2 3 4 5 6 7 8 9 10 11 #[mining] #force_sealing = true #usd_per_tx = "0.000000000000000001" #usd_per_eth = "1" #price_update_period = "hourly" #min_gas_price = 1 #gas_cap = "$BLOCK_GAS" #gas_floor_target = "$BLOCK_GAS" #tx_gas_limit = "$BLOCK_GAS" #extra_data = "$COMPANY_NAME" #engine_signer = "$VALIDATOR_ADDRESS"

  • Restart the containers

    • > docker-compose restart

PS:  When the node sync is completed, you need to uncomment those lines and restart again the containers.