--- title: Neutron v11.0.0 Upgrade order: 2 --- # Neutron v11.0.0 Upgrade, Instructions - Chain upgrade point: `May 13th 2026, 15:00 UTC (approximately)`, at height `56277000`; - Go version: `v1.24.10` - Release: https://github.com/neutron-org/neutron/releases/tag/v11.0.0 This document describes the steps for validators and full node operators, to upgrade successfully to the Neutron v11.0.0 release. For more details on the release, please see the [release notes](https://github.com/neutron-org/neutron/releases/tag/v11.0.0). > Hadron Labs' engagement by the Neutron Foundation for core development / maintenance of the Neutron network will expire on 30 June 2026. To help ensure long-term stability of the network, we recommend adopting the new binary documented here. This new binary introduces changes to network governance and tokenomics and is designed to increase overall resilience. Because the on-chain token voting mechanism has failed to reach quorum since 1 April 2026, the upgrade height was submitted on-chain via the privileged multisig previously elected by the DAO rather than by a traditional upgrade proposal. At this height, you may opt to either continue running the previous binary (which is likely to start malfunctioning in the near future, and already fails to provide validator payments); or upgrade to the provided binary which should ultimately improve long-term stability. We strongly recommend upgrading to the new binary. ## Upgrade date The upgrade will take place approximately on May 13th at approximately `15:00 UTC` at height `56277000`; ## 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 requirement - 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. This can allow your machine to run the binary than it could run in RAM alone. ```shell sudo fallocate -l 64G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile ``` - Make sure you have enough disk space for upgrade, the state can grow twice durng 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](#method-ii-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 runtime The Neutron mainnet network, `neutron-1`, is currently running [Neutron v10.3.0](https://github.com/neutron-org/neutron/releases/tag/v10.3.0). We anticipate that operators who are running on v10.3.0, 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.24`. ### Target runtime The Neutron mainnet network, `neutron-1`, will run [Neutron v11.0.0](https://github.com/neutron-org/neutron/releases/tag/v11.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](https://pkg.go.dev/cosmossdk.io/tools/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 of v11.0.0 ### Go to neutron directory if present else clone the repository ```shell git clone https://github.com/neutron-org/neutron.git ``` ### Follow these steps if neutron repo already present ```shell cd $HOME/neutron git pull git fetch --tags git checkout v11.0.0 make install ``` ### Check the new neutron version, verify the latest commit hash ```shell $ neutrond version --long build_tags: netgo,ledger,pebbledb commit: ec10e853c7f5a8ea3b5002d96153d605f1ff3bdd cosmos_sdk_version: v0.53.4-neutron go: go version go1.24.10 linux/amd64 name: neutron server_name: neutrond version: 11.0.0 ... ``` ### Or check checksum of the binary if you decided to [download it](https://github.com/neutron-org/neutron/releases/tag/v11.0.0) ```shell $ shasum -a 256 neutrond-linux-amd64 0b2bad6c42c0445bd420810b7628c1795919186ee2a3ade67d1305942169a531 neutrond-linux-amd64 ``` ### Make sure you are using the proper version of libwasm You can check the version you are currently using by running the following command: ``` $ neutrond q wasm libwasmvm-version 3.0.3 ``` The proper version is `3.0.3`. **If the version on your machine is different you MUST change it immediately!** #### Ways to change libwasmvm - Use a statically built Neutrond binary from an official Neutron release: [https://github.com/neutron-org/neutron/releases/tag/v11.0.0](https://github.com/neutron-org/neutron/releases/tag/v11.0.0) - If you built Neutron binary by yourself, `libwasmvm` should be loaded dynamically in your binary and somehow, the wrong `libwasmvm` library was present on your machine. You can change it by downloading the proper one and linking it to the Neutron binary manually: 1. download a proper version of `libwasmvm`: ``` $ wget https://github.com/CosmWasm/wasmvm/releases/download/v3.0.3/libwasmvm.x86_64.so ``` 2. tell the linker where to find it: ``` $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/lib/ ``` 3. check that libwasmvm version is correct: ``` $ neutrond q wasm libwasmvm-version 3.0.3 ``` ### Method I: Manual Upgrade Make sure Neutron v11.0.0 is installed by either downloading a [compatible binary](https://github.com/neutron-org/neutron/releases/tag/v11.0.0), or building from source. Building from source requires **Golang 1.24.x**. Run Neutron v10.3.0 till upgrade height, the node will panic: ```shell ERR UPGRADE "v11.0.0" NEEDED at height: 56277000: upgrade to v11.0.0 and applying upgrade "v11.0.0" at height: 56277000 ``` Stop the node, and switch the binary to **Neutron v11.0.0** and re-start by `neutrond start`. 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 ### Manually preparing the binary ##### Preparation Install the latest version of Cosmovisor (`1.5.0`): ```shell go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@v1.5.0 ``` **Verify Cosmovisor Version** ```shell cosmovisor version cosmovisor version: v1.5.0 ``` Create a cosmovisor folder: create a Cosmovisor folder inside `$NEUTRON_HOME` and move Neutron v10.3.0 into `$NEUTRON_HOME/cosmovisor/genesis/bin` ```shell mkdir -p $NEUTRON_HOME/cosmovisor/genesis/bin cp $(which neutrond) $NEUTRON_HOME/cosmovisor/genesis/bin ``` build **Neutron v11.0.0**, and move neutrond v11.0.0 to `$NEUTRON_HOME/cosmovisor/upgrades/v11.0.0/bin` ```shell mkdir -p $NEUTRON_HOME/cosmovisor/upgrades/v11.0.0/bin cp $(which neutrond) $NEUTRON_HOME/cosmovisor/upgrades/v11.0.0/bin ``` Then you should get the following structure: ```shell . ├── current -> genesis or upgrades/ ├── genesis │ └── bin │ └── neutrond #v10.3.0 └── upgrades └── v11.0.0 └── bin └── neutrond #v11.0.0 ``` Export the environmental variables: ```shell 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: ```shell 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 upgrade result 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) v10.3.0 binary using the following command: > neutrond start --unsafe-skip-upgrade 56277000 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. ## FAQ 1. 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.