PlatON Mainnet v1.5.0 - Node Upgrade Guide

[BoneyBee68]

PlatON Mainnet v1.5.0 - Node Upgrade Guide

Version Information

ChainID: 210425

Version: 1.5.0

Git Commit: 7b22c9351d5ff63a9ac8d143e75f9044914077f7

Binary Downloads:

Ubuntu18.04: https://download.platon.network/platon/platon/1.5.0/platon

Ubuntu20.04: https://download.platon.network/platon/platon/ubuntu20.04/1.5.0/platon

Ubuntu22.04: https://download.platon.network/platon/platon/ubuntu22.04/1.5.0/platon

Upgrade Procedure

1. Preparation

This upgrade requires generating a node snapshot. To avoid penalties caused by snapshot generation affecting node consensus, the upgrade must be performed via migration.

Requirements: Prepare a Ubuntu 22.04 server for migration (meeting PlatON validator node specifications).

Important Reminder for Hardware Upgrade:

The PlatON 1.5.0 version has increased the requirements for hardware computing performance. Nodes must meet the PlatON Validator Node Configuration Requirements (4 cores, 16GB RAM, and above). Additionally, you must choose a cloud service provider with high CPU stability and reliability (small or niche cloud providers pose significant reliability risks). Ensure proper monitoring of node operations and promptly address any abnormal risks.

We strongly recommend that nodes enable the “Zero-Block Production Observation List Monitoring” (see below). If a node appears on this list, it indicates that the node is in an unstable state. Please resolve the issue within 1-2 hours.

Notes:

• For multiple nodes, reuse decommissioned servers as new nodes after migration. Repeat steps 2–5 post-snapshot generation.
• The migration of platon-mtool does not affect node operations and can be performed at any time.
• Do NOT run nodes with the same nodekey or blskey simultaneously to avoid double-signing penalties!

2. Deploy a New Node Using v1.5.0

1. Deploy a new PlatON node strictly following the official documentation.

   Skip the “Become a Validator Node” step for migration-based upgrades. The new node will become the long-term operational node after migration.

   Replace the binary download link:

   ubuntu18.04: https://download.platon.network/platon/platon/1.5.0/platon

   ubuntu20.04: https://download.platon.network/platon/platon/ubuntu20.04/1.5.0/platon

   ubuntu22.04: https://download.platon.network/platon/platon/ubuntu22.04/1.5.0/platon

   Important Reminder:

   The PlatON 1.5.0 version has increased CPU usage compared to older versions. To avoid penalties due to missed block production caused by insufficient resources, it is strongly recommended to add the parameter --db.nogc to the 1.5.0 version process startup parameters to reduce CPU usage. Only consider enabling garbage collection (gc) if the host CPU is configured with 4 cores and 3.5GHz or higher!

2. Wait for the new node to synchronize (estimated time: 4–20 hours).

   Verify synchronization by comparing the new node’s block height with the block explorer.

   Commands:

   # Check sync status
   platon attach http://localhost:6789 -exec 'platon.syncing'
   
   # Check block height
   platon attach http://localhost:6789 -exec 'platon.blockNumber'
   

​ Important: New validators must wait until the v1.5.0 upgrade proposal is approved before staking.

3. Generate Snapshot on the New Node

Snapshots are automatically generated after synchronization. No additional configuration is required.

1. Monitor snapshot progress by setting the log level to 1 or higher:

   # Check if the node was started with --verbosity 1+
   ps aux |grep platon
   

2. Confirm snapshot completion (estimated time: 4–130 hours):

   After the snapshot generation is completed, the log will display the following keyword: "Journalled disk layer"+ xxxx +"complete=true" .

   # During the snapshot generation process, the “Journalled disk layer” log will appear multiple times. Only when “complete=true” appears does it indicate the generation is complete!
   # Check if the snapshot generation is complete：
   grep 'complete=true' platon.log 
   

4. Migrate the Validator Node

Important Notice: You must wait until the snapshot generation is completely finished before proceeding with this step!

Prerequisite: Check if the node is in “Consensus” status via the block explorer. If so, wait until it exits consensus before proceeding!

1. Stop the Validator Node:

   # Check process ID
   $ ps aux |grep platon
   root   13476 39.1 49.7 9174616 3925796 ?     Sl   Feb07 1140:19 /usr/bin/platon  --identity ....
   # Check nodekey
   $  platon attach http://127.0.0.1:6789 -exec 'admin.nodeInfo.enode' |awk -F[/@] '{print $3}'
   
   # Check blsPubKey
   $ platon attach http://127.0.0.1:6789 -exec 'admin.nodeInfo.blsPubKey'
   
   # Stop the Platon node, e.g., kill 13476. In the example above, the process ID（PID） is 13476, but in actual operation, use the appropriate process ID according to your situation. After executing the kill command, you can use the ps command mentioned earlier to check if the process has exited correctly. If it has exited normally, proceed with the subsequent start-up commands.
   $ kill <PID>
   
   

2. Replace Node Files:

   After stopping the validator node that is to be upgraded, copy the nodeid, nodekey, blskey, and blspub files from the old validator node to the new node server to complete the node file replacement.

   If you deployed according to the official documentation, these files are located in the ~/platon-node/data/ directory.

3. Restart the Upgraded Node:

   The following commands are provided as a reference. Please restart the platon process according to your own management practices.

   # Check process ID
   $ ps aux |grep platon
   root   13476 39.1 49.7 9174616 3925796 ?     Sl   Feb07 1140:19 /usr/bin/platon  --identity ....
   
   # Stop the Platon node, e.g., kill 13476. In the example above, the process ID（PID） is 13476, but in actual operation, use the appropriate process ID according to your situation. After executing the kill command, you can use the ps command mentioned earlier to check if the process has exited correctly. If it has exited normally, proceed with the subsequent start-up commands.
   $ kill <PID>
   
   # Start the node
   $ nohup platon --identity platon-node --datadir ./data  --nodekey ./data/nodekey --cbft.blskey ./data/blskey --http  --http.addr 127.0.0.1 --http.port 6789 --http.api "platon,net,web3,admin,personal,debug" --port 16789 --verbosity 1 --syncmode "fast" --db.nogc >> ./data/platon.log 2>&1 &
   
   # Check if the nodekey matches that of the original validator node.
   $  platon attach http://127.0.0.1:6789 -exec 'admin.nodeInfo.enode' |awk -F[/@] '{print $3}'
   
   # Check if the blsPubKey matches that of the original validator node.
   $ platon attach http://127.0.0.1:6789 -exec 'admin.nodeInfo.blsPubKey'
   
   # Execute the following commands consecutively to see if the block height is synchronized properly
   $ platon attach http://localhost:6789 -exec 'platon.blockNumber'
   

4. Restart the Upgraded Node:

   To ensure the upgraded validator node is running properly, verify that the nodekey and blspubkey have been correctly migrated, and that the node is synchronizing blocks normally.

# Check if the nodekey matches that of the original validator node.
$  platon attach http://127.0.0.1:6789 -exec 'admin.nodeInfo.enode' |awk -F[/@] '{print $3}'

# Check if the blsPubKey matches that of the original validator node.
$ platon attach http://127.0.0.1:6789 -exec 'admin.nodeInfo.blsPubKey'

# Execute the following commands consecutively to see if the block height is synchronized properly
$ platon attach http://localhost:6789 -exec 'platon.blockNumber'

5. Migrate platon_mtool

Follow the MTool Online Guide to install platon_mtool. Migrate the keystore and validator directories from the old node to the new platon_mtool directory.

6. Upgrade Proposal Handling

For nodes that have been staked, please use the blockchain explorer to verify whether the current node is in one of the following states:

• Producing
• Verifying
• Active

If the current node is in any of the three states listed above, please refer to the following commands to cast your vote. The proposal ID is <0x2e612db8a6f44331c776a459b6ca12c4bb418e2bef6dfcab6357cddd272a8e4a>:

# Example command for voting on an upgrade proposal
# If $PLATON_MTOOLDIR is not defined, you need to fill in the full absolute path based on your actual deployment.
$ platon_mtool vote_versionproposal --proposalid 0x2e612db8a6f44331c776a459b6ca12c4bb418e2bef6dfcab6357cddd272a8e4a --keystore $PLATON_MTOOLDIR/keystore/staking.json --config $PLATON_MTOOLDIR/validator/validator_config.json

For Candidate Nodes:

Declare the node version

# Example command for version declaration
# If $PLATON_MTOOLDIR is not defined, you need to fill in the full absolute path based on your actual deployment.
$ platon_mtool declare_version --keystore $PLATON_MTOOLDIR/keystore/staking.json --config $PLATON_MTOOLDIR/validator/validator_config.json

Note: Non-validator nodes (unstaked) require no action.

Support

For assistance, contact:

• Telegram
• Email： validator@platon.network

Appendix

Zero-Block Production Observation List Monitoring:

# Prerequisite: Enable the debug module (*Note: This will restart the node. Ensure the node is not in consensus before proceeding).
$ nohup platon --identity platon-node --datadir ./data  --nodekey ./data/nodekey --cbft.blskey ./data/blskey --http  --http.addr 127.0.0.1 --http.port 6789 --http.api "platon,net,web3,admin,personal,debug" --port 16789 --verbosity 1 --syncmode "fast" --db.nogc >> ./data/platon.log 2>&1 &

# Query the cumulative number of zero-block production cycles
$ platon attach http://localhost:6789 -exec 'debug.getWaitSlashingNodeList()'

# If a node appears in this list and continues for 20 consensus cycles (approximately 2.5 hours), it will be penalized.
# If the node resumes block production within this period, no penalty will be applied.
# Example Output:
[{\"NodeId\":\"f0ac4b8937d067c590aa6259a4e17015655b39f7c7cd48d66a329affdaad6a3ddbb1ea7bb70c86605ee52e636ce2b0af85c287fbfba326f43dfb56eb10cc4798\",\"Round\":264079,\"CountBit\":1},{{\"NodeId\"......}，... ,{{\"NodeId\".....}]
# If your node appears in the above list, trigger an **immediate alert** to address the issue promptly!

Key Notes:

1. Regularly monitor the zero-block production list to avoid penalties.
2. Ensure your node hardware and network stability to minimize zero-block occurrences.
3. If your node appears in the list, investigate and resolve the issue promptly to avoid slashing.

[JamesQU_LatticeX]

grep ‘complete=true’ platon.log may give you the result starting with “ERROR”, which is fine. It is indicating the task has completed.

multiple outputs are also fine, means it is awaiting you to migrate and vote