​
Neutron v8.0.0 Upgrade Instructions

  • Chain upgrade point: August 27th 2025, 15:00 UTC (approximately), at height 33397000
  • Go version: v1.23.4
  • Release: v8.0.0
This document describes the steps for validators and full node operators to upgrade successfully to the Neutron v8.0.0 release. For more details on the release, please see the release notes.

​
Upgrade Date

The upgrade will take place approximately on August 27th at 15:00 UTC at height 33397000.

​
Chain-id will remain the same

The chain-id of the network will remain the same, neutron-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 Requirements

  • 64GB RAM is recommended to ensure a smooth upgrade.
If you have less than 64GB RAM, you might try creating a swapfile to swap an idle program onto the hard disk to free up memory: 
sudo fallocate -l 64G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

​
Disk Space

  • Make sure you have enough disk space for upgrade, the state can grow twice during upgrade.

​
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. If you use Cosmovisor to upgrade, by default, Cosmovisor will backup your data upon upgrade. See below upgrade using cosmovisor section.
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 and Target Runtime

​
Current Runtime

The Neutron mainnet network, neutron-1, is currently running Neutron v6.0.3. We anticipate that operators who are running on v6.0.3, will be able to upgrade successfully. Validators are expected to ensure that their systems are up-to-date and capable of performing the upgrade. This includes running the correct binary, or if building from source, building with go 1.23.

​
Target Runtime

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

​
Upgrade Steps

There are 2 major ways to upgrade a node:
  • Manual upgrade
  • Upgrade using Cosmovisor
    • Either by manually preparing the new binary
    • Or by using the auto-download functionality (this is not yet recommended)
If you prefer to use Cosmovisor to upgrade, some preparation work is needed before upgrade.

​
Create the Updated Neutron Binary

​
Clone or Update Repository

# Go to neutron directory if present else clone the repository
git clone https://github.com/neutron-org/neutron.git

​
Build from Source

cd $HOME/neutron
git pull
git fetch --tags
git checkout v8.0.0
make install

​
Verify Installation

Check the new neutron version, verify the latest commit hash: 
$ neutrond version --long
build_tags: '''netgo,ledger,muslc'''
commit: 5593e5de177a45ccb237188f69580f7d160b5961
cosmos_sdk_version: v0.50.13-neutron.0.20250512094026-b5afd837c4de
go: go version go1.23.4 linux/amd64
name: neutron
server_name: neutrond
version: 8.0.0

​
Or Verify Downloaded Binary

Check checksum of the binary if you decided to download it: 
$ shasum -a 256 neutrond-linux-amd64
8ec1b0881fb1747f7015a50a1fffa61a05a1c4609ae1c84cb9374f9b260cbc79  neutrond-linux-amd64

​
LibWasm Version Check

Make sure you are using the proper version of libwasm: 
$ 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 statically built binary: Download from official release
  • Manual linking (if built from source):
# Download proper version
$ wget https://github.com/CosmWasm/wasmvm/releases/download/v2.2.4/libwasmvm.x86_64.so

# Set library path
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/lib/

# Verify version
$ neutrond q wasm libwasmvm-version
2.2.4

​
Method I: Manual Upgrade

Make sure Neutron v8.0.0 is installed by either downloading a compatible binary, or building from source. Building from source requires Golang 1.23.x.
1

Run Current Version

Run Neutron v6.0.3 till upgrade height, the node will panic:
ERR UPGRADE "v8.0.0" NEEDED at height: 33397000: upgrade to v8.0.0 and applying upgrade "v8.0.0" at height: 33397000
2

Stop and Switch Binary

Stop the node, and switch the binary to Neutron v8.0.0 and re-start by neutrond start.
3

Wait for Network

It may take several minutes to a few hours until validators with a total sum voting power > 2/3 to complete their node upgrades. After that, the chain can continue to produce blocks.

​
Method II: Upgrade using Cosmovisor

​
Preparation

Install the latest version of Cosmovisor (1.5.0): 
go install cosmossdk.io/tools/cosmovisor/cmd/[email protected]
Verify Cosmovisor Version: 
cosmovisor version
cosmovisor version: v1.5.0

​
Setup Directory Structure

1

Create Cosmovisor Folder

Create a cosmovisor folder inside $NEUTRON_HOME and move Neutron v6.0.3:
mkdir -p $NEUTRON_HOME/cosmovisor/genesis/bin
cp $(which neutrond) $NEUTRON_HOME/cosmovisor/genesis/bin
2

Prepare v8.0.0 Binary

Build Neutron v8.0.0, and move neutrond v8.0.0:
mkdir -p  $NEUTRON_HOME/cosmovisor/upgrades/v8.0.0/bin
cp $(which neutrond) $NEUTRON_HOME/cosmovisor/upgrades/v8.0.0/bin
3

Verify Structure

You should get the following structure:
.
├── current -> genesis or upgrades/<name>
├── genesis
│   └── bin
│       └── neutrond  #v6.0.3
└── upgrades
    └── v8.0.0
        └── bin
            └── neutrond  #v8.0.0

​
Start with Cosmovisor

Export the environmental 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: 
cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME
Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK.

​
Expected Results

​
Upgrade Process

When the upgrade block height is reached, Neutron will panic and stop. After upgrade, the chain will continue to produce blocks when validators with a total sum voting power > 2/3 complete their node upgrades.

​
Upgrade Duration

Most likely it takes a couple of minutes.

​
Rollback Plan

During the network upgrade, core Neutron team will be keeping an ever vigilant eye and communicating with operators on the status of their upgrades. During this time, the core team will listen to operator needs to determine if the upgrade is experiencing unintended challenges. 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 are simply to resume the neutron-1 network with the (downgraded) v6.0.3 binary using the following command: 
neutrond start --unsafe-skip-upgrade 33397000
There is no particular need to restore a state snapshot prior to the upgrade height, unless specifically directed by core Neutron team.
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.

​
FAQ

​
Support

For upgrade support and coordination:
Monitor official channels during the upgrade for real-time updates and coordination.