Skip to content

java-tron Node Upgrade Guide

This guide provides detailed instructions on how to safely upgrade your java-tron node to the latest version.

For mandatory upgrades, it is crucial to strictly follow this guide to complete the deployment. For optional upgrades, you may choose whether to upgrade based on your specific needs.

Standard Node Upgrade Process

All FullNodes, including block-producing Super Representative nodes, should follow these steps to complete the upgrade.

Step 1: Prepare the New Version Package

You can either download the compiled java-tron executable directly or download the new version's source code and compile it yourself to obtain the new executable file. Please perform the following operations in a directory outside of the current java-tron running directory.

  1. Visit the java-tron GitHub Releases page and download the latest executable for your system architecture: FullNode-x64.jar for x86-64 or FullNode-aarch64.jar for ARM64. After verifying its signature, rename the downloaded file to FullNode.jar for use in the subsequent steps.
  2. Security Check: To ensure the integrity and security of the file, it is essential to perform a signature verification on the downloaded JAR file according to the java-tron Signature Verification guide.

Option 2: Compile from Source Code

  1. Clone the java-tron repository and switch to the target version's branch.

    # clone the repository
git clone https://github.com/tronprotocol/java-tron.git

# Switch to the specified version branch
cd java-tron
git checkout -b release_vx.x.x

  2. Run the build command. Upon successful compilation, the new executable file, FullNode.jar, will be generated in the build/libs/ directory.

    ./gradlew clean build -x test

Step 2: Stop the Running Node

Note: If this is your first time deploying the node, please skip directly to Step 5: Start the Node.

  1. Use the following command to find the PID of the java-tron process.

    ps -ef | grep java

  2. Stop the node process.

    kill -15 <PID>

Step 3: Back Up Critical Data

A full backup is strongly recommended before upgrading. Please perform the following backup steps in the specified order:

  1. Back up the current executable file

    mv $JAVA_TRON.jar $JAVA_TRON.jar.`date "+%Y%m%d%H%M%S"`

  2. Back up the current output-directory database

    tar cvzf output-directory.`date "+%Y%m%d%H%M%S"`.etgz output-directory

  3. Back up the current configuration file

    mv $config.conf $config.conf.`date "+%Y%m%d%H%M%S"`

This ensures that if the upgrade fails, you can quickly roll back to the previous version using the backup.

Step 4: Replace Old Files

After preparing the new version of the executable file and backing up the original node data, follow these steps to replace the old files:

  1. Copy the new FullNode.jar obtained in Step 1 to the java-tron working directory.

  2. Review and update the configuration file. Updating the configuration file is optional unless the release requires a change. You can use either approach:

    • Start from the template and merge your custom settings (recommended). Replace your configuration file with the config.conf template for the same network, then merge the supported custom settings from your backed-up configuration into it.

    • Update your existing configuration file. Copy your backed-up configuration file back to its original path, then add or adjust settings according to the configuration differences and release instructions.

      For example, if your backup is named config.conf.20261021153000, restore a copy with:

      cp config.conf.20261021153000 config.conf

      Replace the example backup filename with your actual backup filename. Edit the restored config.conf and keep the backup unchanged.

    For either approach, review the release notes and compare your configuration with the current config.conf (framework/src/main/resources/config.conf) and reference.conf (common/src/main/resources/reference.conf). reference.conf supplies fallback defaults and documents supported parameters, including optional settings shown only as commented examples. config.conf is a deployment template containing commonly used settings and operational overrides.

Note on the Database: The existing database in the working directory can be used as-is. Alternatively, you may restore from a pre-built database snapshot.

Step 5: Start the Node

Super Representative Node (Block-Producing Node)

For Block-Producing Node, please refer to Starting a Block Production Node

Regular FullNode

For Regular FullNode, please refer to Starting a FullNode on the TRON main network

Step 6: Verify and Monitor

  1. Wait for Node Synchronization: After the node starts, it will begin to synchronize block data. Please wait patiently for it to catch up to the latest block height of the network.
  2. Check the Logs: Monitor the log output to ensure the node is running normally and without any error messages.

  3. Confirm Synchronization Status: You need to verify that synchronization is complete by comparing the latest block height of your local node with that of the TRON Mainnet. The upgrade is successful when the two heights are nearly identical.

    • To query local node block height, call the /wallet/getnowblock API:

      curl http://127.0.0.1:8090/wallet/getnowblock

    • To check the real-time block height of the Mainnet, use the TRONSCAN block explorer.

Contingency Plan: If you encounter any issues during the upgrade process that prevent the node from starting or running correctly, immediately use the data backed up in Step 3 to restore the previous version. Please submit a GitHub Issue or report the problem to the TRON community for assistance.

Primary/Backup Node Upgrade Guide

To ensure high availability of the service, the upgrade of primary/backup nodes should adopt a rolling upgrade strategy.

  1. Upgrade the Backup Node
  2. Perform the Switchover
    • After confirming that the Backup Node has been successfully upgraded and has completed block synchronization, stop the process on the Master Node.
    • At this point, the Backup Node will automatically take over, becoming the new Active Node and serving traffic.
  3. Upgrade the Original Master Node
    • After confirming that the new Active Node (the former Backup Node) is running stably, perform the Standard Node Upgrade Process on the original Master Node.
    • Error Handling: If the new Active Node fails during this period, immediately stop its upgrade process and restart the original Master Node to restore service. At the same time, please save the complete logs from the failed node for troubleshooting. For further support, please submit a GitHub Issue with the relevant logs or report it to the community.
  4. Restore the Primary/Backup Architecture
    • After the original Master Node has been upgraded, started, and fully synchronized, stop the currently active node (the former Backup Node).
    • The original Master Node will automatically take over again, resuming its role as the Active Node.
  5. Restart the Backup Node
    • Finally, restart the upgraded Backup Node to restore it to its backup status. This completes the entire primary/backup upgrade process.