add v3.1.0 upgrade guide

upgrade/v3.1.0.md

@@ -0,0 +1,158 @@
+# IRIS Hub Upgrade v3.1.0
+
+## This is a coordinated upgrade. IT IS CONSENSUS BREAKING, so please apply the fix only on height TODO
+
+### Release Details
+
+* <https://github.com/irisnet/irishub/releases/tag/v3.1.0>
+* Chain upgrade height : `TODO`. Exact upgrade time can be checked [here](https://www.mintscan.io/iris/block/TODO).
+* Go version has been frozen at `1.21`. If you are going to build `iris` binary from source, make sure you are using the right GO version!
+
+## Performing the co-ordinated upgrade
+
+This co-ordinated upgrades requires validators to stop their validators at `halt-height`, switch their binary to `v3.1.0` and restart their nodes with the new version.
+
+The exact sequence of steps depends on your configuration. Please take care to modify your configuration appropriately if your setup is not included in the instructions.
+
+## Manual steps
+
+## Step 1: Configure `halt-height` using v3.1.0 and restart the node
+
+This upgrade requires `iris` halting execution at a pre-selected `halt-height`. Failing to stop at `halt-height` may cause a consensus failure during chain execution at a later time.
+
+There are two mutually exclusive options for this stage:
+
+### Option 1: Set the halt height by modifying `app.toml`
+
+* Stop the iris process.
+
+* Edit the application configuration file at `~/.iris/config/app.toml` so that `halt-height` reflects the upgrade plan:
+
+```toml
+# Note: Commitment of state will be attempted on the corresponding block.
+halt-height = TODO
+```
+
+* restart iris process
+
+* Wait for the upgrade height and confirm that the node has halted
+
+### Option 2: Restart the `iris` binary with command line flags
+
+* Stop the iris process.
+
+* Do not modify `app.toml`. Restart the `iris` process with the flag `--halt-height`:
+
+```shell
+iris start --halt-height TODO
+```
+
+* Wait for the upgrade height and confirm that the node has halted
+
+Upon reaching the `halt-height` you need to replace the `v3.0.0` iris binary with the new `iris v3.1.0` binary and remove the `halt-height` constraint.
+Depending on your setup, you may need to set `halt-height = 0` in your `app.toml` before resuming operations.
+
+```shell
+   git clone https://github.com/irisnet/irishub.git
+```
+
+## Step 2: Build and start the v3.1.0 binary
+
+### Remember to revert `iris` configurations
+
+* Reset `halt-height = 0` option in the `app.toml` or
+* Remove it from start parameters of the iris binary before restarting the node
+
+We recommend you perform a backup of your data directory before switching to `v3.1.0`.
+
+```shell
+cd $HOME/irishub
+git pull
+git fetch --tags
+git checkout v3.1.0
+make install
+
+# verify install
+iris version
+# v3.1.0
+```
+
+```shell
+iris start # starts the v3.1.0 node
+```
+
+## Cosmovisor steps
+
+## Prerequisite: Alter systemd service configuration
+
+Disable automatic restart of the node service. To do so please alter your `iris.service` file configuration and set appropriate lines to following values.
+
+```bash
+Restart=no 
+
+Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
+Environment="DAEMON_RESTART_AFTER_UPGRADE=false"
+```
+
+After that you will need to run `sudo systemctl daemon-reload` to apply changes in the service configuration.
+
+There is no need to restart the node yet; these changes will get applied during the node restart in the next step.
+
+## Setup Cosmovisor
+
+### Create the updated iris binary of v3.1.0
+
+### Remember to revert `iris` configurations
+
+* Reset `halt-height = 0` option in the `app.toml` or
+* Remove it from start parameters of the iris binary before starting the node
+
+#### Go to iris directory if present else clone the repository
+
+```shell
+   git clone https://github.com/irisnet/irishub.git
+```
+
+#### Follow these steps if iris repo already present
+
+```shell
+   cd $HOME/irishub
+   git pull
+   git fetch --tags
+   git checkout v3.1.0
+   make install
+```
+
+#### Check the new iris version, verify the latest commit hash
+
+```shell
+   $ iris version --long
+   name: iris
+   server_name: iris
+   version: 3.1.0
+   commit: <commit-hash>
+   ...
+```
+
+### Copy the new iris (v3.1.0) binary to cosmovisor current directory
+
+```shell
+   cp $GOPATH/bin/iris ~/.iris/cosmovisor/current/bin
+```
+
+### Restore service file settings
+
+If you are using a service file, restore the previous `Restart` settings in your service file:
+
+```bash
+Restart=On-failure 
+```
+
+Reload the service control `sudo systemctl daemon-reload`.
+
+## Revert `iris` configurations
+
+Depending on which path you chose for Step 1, either:
+
+* Reset `halt-height = 0` option in the `app.toml` or
+* Remove it from start parameters of the iris binary and start node again