Dymension Node Binary Upgrade Guide

Upgrading your Dymension node to a specific release version ensures compatibility with the latest protocol features and network security patches. This procedure involves fetching the latest source code, compiling the binary, and restarting the node service via systemd.

Prerequisites

Before executing the upgrade, ensure your environment is prepared:

• Active Node: A functional Dymension node running under a systemd service named dymd.
• Go Environment: Verify that your $GOPATH and $GOBIN are correctly configured in your shell profile.
• Source Access: Access to the official Dymension GitHub repository.

Upgrade Procedure

1. Fetch and Build the Target Version

Navigate to your local Dymension source directory and fetch the latest tags. It is recommended to perform a git fetch to ensure all remote tags are available before checking out the specific version.

cd $HOME/dymension
git fetch --all
git checkout v2.0.0-alpha.8
make install

2. Verify the Installation

After the build completes, confirm that the binary version and commit hash match the official release documentation. This step prevents running an incorrect build on the mainnet or testnet.

dymd version --long | grep -e commit -e version

Expected Output for v2.0.0-alpha.8:

version: v2.0.0-alpha.8 commit: 080bbb9ede90170f84a3f4f3665c179ea8742716

3. Restart and Monitor the Service

Once the binary is verified, restart the systemd service. Immediately follow the logs to ensure the node handles the database migration (if any) and resumes block synchronization.

sudo systemctl restart dymd && journalctl -u dymd -f -o cat

Post-Upgrade Verification

Monitor the following indicators to ensure a successful transition:

Check	Command	Goal
Catching Up	`dymd status 2>&1	jq .SyncInfo.catching_up`
Log Output	journalctl -u dymd -n 50	No “AppHash mismatch” or “Panic” errors
P2P Connectivity	`dymd net-info	jq ‘.n_peers

Common Failure Points

• Incorrect Go Version: If make install fails, verify your Go version with go version. Dymension typically requires Go 1.21 or higher.
• Path Issues: If dymd version still shows the old version, ensure your $HOME/go/bin takes precedence in your $PATH or that the binary was correctly moved to /usr/local/bin if customized.
• Database Incompatibility: If the node fails to start with a “state machine” error, you may be attempting to run a version that is incompatible with the current block height or requires a specific migration tool.