v4 instructions

upgrades/v4.0.0.md

@@ -0,0 +1,193 @@
+# Jackal v4.0.0 Upgrade Guide
+
+This upgrade is going to take place in multiple stages. Please pay attention to the details of each step. This applies to both storage providers and validators/node-operators.
+## Outline
+1. [Intermediary Upgrade](#v340)
+2. [Migration to Sequoia](#sequoia)
+3. [Secondary Upgrade](#acacia)
+
+## v3.4.0
+To begin the process of the v4 upgrade, we need to install a temporary upgrade that will halt some of the systems on Jackal while keeping the chain alive. The [/x/storage](/x/storage) module will enter essentially a read-only state. This means that no storage deal will be able to be made, and no storage deals will be burned while this version is active.
+
+### Installing New Binary
+
+Clone the Jackal repo
+
+```
+git clone https://github.com/JackalLabs/canine-chain.git
+cd canine-chain
+```
+Checkout the upgrade version
+
+```
+git fetch
+git checkout v3.4.0
+```
+
+Build the binary
+
+```
+make build
+```
+
+The resulting binary will be `canine-chain/build/canined`
+
+### Starting the Blockchain
+
+#### Cosmovisor Method
+
+Ensure your chain is at the following block height: BLOCKHEIGHT
+
+**If you halted your chain early, this may not be the case. I recommend following the canined upgrade below any situation where your node is not already at the halt height.**
+
+Copy the new binary in place of the existing genesis cosmovisor binary
+
+```
+cp $HOME/canine-chain/build/canined $HOME/.canine/cosmovisor/genesis/bin/canined
+```
+
+#### Traditional Method
+Set the halt height in the canined app config
+```
+sed -i.bak 's/halt-height = 0/halt-height = BLOCKHEIGHT/' $HOME/.canine/config/app.toml
+```
+
+Wait until the planned upgrade time (approx. TODO:NEEDNEWTIME May 4th 2023, 15:30 UTC)
+
+At the upgrade time, run the binary to ensure the node syncs to the halt height
+
+```
+canined start
+```
+
+Once it stops due to the halt-height, replace the old canined binary with the new one:
+
+```
+cp $HOME/canine-chain/build/canined $(which canined)
+```
+
+Remove the halt-height from the config:
+
+```
+sed -i.bak 's/halt-height = BLOCKHEIGHT/halt-height = 0/' $HOME/.canine/config/app.toml
+```
+
+Restart the node:
+
+```
+canined start
+```
+
+## Sequoia
+Once this upgrade has passed, storage providers will be required to upgrade their storage provider software to [Sequoia](https://github.com/JackalLabs/sequoia). Sequoia is an improved storage provider software that has been rebuilt to support v4 at launch. Please shut off your storage provider before starting these steps.
+
+### Migration Instructions
+If you are not running a storage provider with the version `1.2.0` or higher, please migrate your provider to 1.2.0 by following:
+```shell
+# Install version 1.2.0
+git clone https://github.com/JackalLabs/canine-provider.git
+cd canine-provider
+git checkout v1.2.0
+make install
+
+# Migrate the file system
+jprovd migrate
+```
+
+#### Installing Sequoia
+```shell
+git clone https://github.com/JackalLabs/sequoia.git
+cd sequoia
+git checkout v1.0.0
+make install
+```
+
+#### Migrating The File-System
+To migrate the file system of the storage provider to `sequoia`. Please follow these steps:
+```shell
+jprovd migrate-sequoia
+
+sequoia init
+
+cp -rv "{YOUR_CURRENT_STORAGE_PROVIDER_DIRECTORY}/ipfs-storage" "$HOME/.sequoia/data"
+cp "{YOUR_CURRENT_STORAGE_PROVIDER_DIRECTORY}/config/priv_storkey.json" "$HOME/.sequoia"
+```
+
+Once the v4.0.0 upgrade is finished, you can start your provider back up again by running:
+```shell
+sequoia start
+```
+
+## Acacia
+This is the final step in updating to v4. This will happen after v3.4.0 and after enough time has passed to let the storage providers update their machines to `sequoia`.
+
+### Installing New Binary
+
+Clone the Jackal repo
+
+```
+git clone https://github.com/JackalLabs/canine-chain.git
+cd canine-chain
+```
+Checkout the upgrade version
+
+```
+git fetch
+git checkout v4.0.0
+```
+
+Build the binary
+
+```
+make build
+```
+
+The resulting binary will be `canine-chain/build/canined`
+
+### Starting the Blockchain
+
+#### Cosmovisor Method
+
+Ensure your chain is at the following block height: BLOCKHEIGHT4
+
+**If you halted your chain early, this may not be the case. I recommend following the canined upgrade below any situation where your node is not already at the halt height.**
+
+Copy the new binary in place of the existing genesis cosmovisor binary
+
+```
+cp $HOME/canine-chain/build/canined $HOME/.canine/cosmovisor/genesis/bin/canined
+```
+
+#### Traditional Method
+Set the halt height in the canined app config
+```
+sed -i.bak 's/halt-height = 0/halt-height = BLOCKHEIGHT4/' $HOME/.canine/config/app.toml
+```
+
+Wait until the planned upgrade time (approx. TODO:NEEDNEWTIME4 May 4th 2023, 15:30 UTC)
+
+At the upgrade time, run the binary to ensure the node syncs to the halt height
+
+```
+canined start
+```
+
+Once it stops due to the halt-height, replace the old canined binary with the new one:
+
+```
+cp $HOME/canine-chain/build/canined $(which canined)
+```
+
+Remove the halt-height from the config:
+
+```
+sed -i.bak 's/halt-height = BLOCKHEIGHT4/halt-height = 0/' $HOME/.canine/config/app.toml
+```
+
+Restart the node:
+
+```
+canined start
+```
+
+The network should now be upgrade to v4 - Acacia.