This document describes the steps for validators and full node operators to upgrade to Neutron v8.0.0-rc0 on the Pion testnet.

​
Upgrade Information

  • Chain upgrade point: August 13th 2025, 15:00 UTC (approximately) at height 34540000
  • Go version: v1.23
  • Release: v8.0.0-rc0

​
Chain ID

The chain-id of the network will remain the same, pion-1. This is because an in-place migration of state will take place, i.e., this upgrade does not export any state.

​
System Requirements

  • RAM: 64GB RAM is recommended to ensure a smooth upgrade
  • Disk Space: Ensure you have enough disk space for the upgrade, as the state can grow twice during the upgrade process
If you have less than 64GB RAM, you might try creating a swapfile: 
sudo fallocate -l 64G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

​
Backups

Prior to the upgrade, validators are encouraged to take a full data snapshot. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the .neutrond directory. It is critically important for validator operators to back-up the .neutrond/data/priv_validator_state.json file after stopping the neutrond process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted.

​
Current Runtime

The Neutron testnet network, pion-1, is currently running Neutron v7.0.0-rc0. Operators who are running on v7.0.0-rc0 will be able to upgrade successfully.

​
Target Runtime

The Neutron testnet network, pion-1, will run Neutron v8.0.0-rc0. Operators MUST use this version post-upgrade to remain connected to the network.

​
Build v8.0.0-rc0

​
Option 1: Clone and build from source

# Go to neutron directory if present else clone the repository
git clone https://github.com/neutron-org/neutron.git
cd neutron
git fetch --tags
git checkout v8.0.0-rc0
make install

​
Option 2: Download the binary

Download the pre-built binary from the release page.

​
Verify binary

Check the version and commit hash: 
neutrond version --long
Expected output: 
build_tags: netgo,ledger
commit: fe9de3c9aac34d432e1e189a6638ad2224842176
cosmos_sdk_version: v0.50.13-neutron.0.20250512094026-b5afd837c4de
go: go version go1.23.10 darwin/arm64
name: neutron
server_name: neutrond
version: 8.0.0-rc0
Or check checksum of the downloaded binary: 
shasum -a 256 neutrond-linux-amd64
11fd75e0e6aa0eb5e16daf81263ac3356a5ec8c2c3c815696f55992f57bb2979  neutrond-linux-amd64

​
LibWasm Version

Make sure you are using the proper version of libwasm. You can check the version with: 
neutrond q wasm libwasmvm-version
2.2.4
The proper version is 2.2.4. If the version on your machine is different you MUST change it immediately!

​
Ways to change libwasmvm

  • Use a statically built neutrond binary from the official release
  • If you built the binary yourself, download the proper libwasmvm version:
wget https://github.com/CosmWasm/wasmvm/releases/download/v2.2.4/libwasmvm.x86_64.so
Then tell the linker where to find it: 
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/lib/

​
Upgrade Methods

​
Method I: Manual Upgrade

  1. Run Neutron v7.0.0-rc0 till upgrade height. The node will panic with:
ERR UPGRADE "v8.0.0-rc0" NEEDED at height: 34540000: upgrade to v8.0.0-rc0 and applying upgrade "v8.0.0-rc0" at height: 34540000
  1. Stop the node
  2. Switch the binary to Neutron v8.0.0-rc0
  3. Restart with neutrond start

​
Method II: Upgrade using Cosmovisor

​
Preparation

Install Cosmovisor v1.5.0: 
go install cosmossdk.io/tools/cosmovisor/cmd/[email protected]
Verify installation: 
cosmovisor version
cosmovisor version: v1.5.0
Create the Cosmovisor directory structure: 
mkdir -p $NEUTRON_HOME/cosmovisor/genesis/bin
cp $(which neutrond) $NEUTRON_HOME/cosmovisor/genesis/bin

mkdir -p $NEUTRON_HOME/cosmovisor/upgrades/v8.0.0-rc0/bin
cp $(which neutrond) $NEUTRON_HOME/cosmovisor/upgrades/v8.0.0-rc0/bin
You should get this structure: 
.
├── current -> genesis or upgrades/<name>
├── genesis
│   └── bin
│       └── neutrond  #v7.0.0-rc0
└── upgrades
    └── v8.0.0-rc0
        └── bin
            └── neutrond  #v8.0.0-rc0
Export environment variables: 
export DAEMON_NAME=neutrond
# please change to your own neutron home dir
# please note `DAEMON_HOME` has to be absolute path
export DAEMON_HOME=$NEUTRON_HOME
export DAEMON_RESTART_AFTER_UPGRADE=true
Start the node with Cosmovisor: 
cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME
Skipping invariant checks is strongly encouraged as it decreases the upgrade time significantly.

​
Upgrade Duration

The upgrade process is expected to take a couple of minutes.

​
Rollback Plan

In the event of unexpected challenges, the core team, after conferring with operators and attaining social consensus, may choose to declare that the upgrade will be skipped. Steps to skip this upgrade proposal: 
neutrond start --unsafe-skip-upgrade 34540000
Note: There is no particular need to restore a state snapshot prior to the upgrade height, unless specifically directed by core Neutron team. Important: A social consensus decision to skip the upgrade will be based solely on technical merits, thereby respecting and maintaining the decentralized governance process of the upgrade proposal’s successful YES vote.

​
Risks

As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing. The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it.

​
Notable Changes in v8.0.0-rc0

This release includes:
  1. Upgrade to libwasmvm v2.2.4
  2. Several core module improvements
  3. Enhanced performance for high-throughput transactions
Testnet validators should use this upgrade as a rehearsal for the upcoming mainnet upgrade.

​
FAQ

Q: My node restarted in the middle of upgrade process (OOM killed, hardware issues, etc), is it safe to just proceed with the upgrade? A: No. Most likely the upgrade will be completed successfully. But you get AppHash error after the network gets up. It’s a lot safer to restart full process from scratch (recover the node from a backup). To perform an upgrade you need to keep your ./data/priv_validator_state.json file when you are applying a snapshot from the backup. This will help you avoid the risk of slashing due to double signing.