> ## Documentation Index
> Fetch the complete documentation index at: https://cosmos-docs-sync-security-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading the Chain

> This document demonstrates how a live upgrade can be performed on-chain through a governance process.

This document demonstrates how a live upgrade can be performed on-chain through a
governance process.

1. Start the network and trigger upgrade

   ```bash expandable theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
   # start a gaia application full-node
   $ gaiad start

   # set up the cli config
   $ gaiad config chain-id testing

   # create an upgrade governance proposal
   $ gaiad tx gov submit-proposal  <path-to-proposal-json> --from <name-or-key>

   Where proposal json file contains MsgSoftwareUpgrade e.g.
   `{
    	"messages": [
    	 {
    	  "@type": "/cosmos.upgrade.v1beta1.MsgSoftwareUpgrade",
    	  "authority":"cosmos10d07y265gmmuvt4z0w9aw880jnsr700j6zn9kn" ,
    	  "plan": {
    	   "name": "plan name",
    	   "height": "1000" ,
    	   "info": "proposal info" ,
    	   "upgraded_client_state": null
    	  }
    	 }
    	],
    	"metadata": "ipfs://CID",
    	"deposit": "10000000stake",
    	"title": "proposal title",
    	"summary": "proposal summary"
    }`

   # once the proposal passes you can query the pending plan
   $ gaiad query upgrade plan
   ```

2. Performing an upgrade

   Assuming the proposal passes the chain will stop at given upgrade height.

   You can stop and start the original binary all you want, but **it will refuse to
   run after the upgrade height**.

   We need a new binary with the upgrade handler installed. The logs should look
   something like:

   ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
   E[2019-11-05|12:44:18.913] UPGRADE "<plan-name>" NEEDED at height: <desired-upgrade-height>:       module=main
   E[2019-11-05|12:44:18.914] CONSENSUS FAILURE!!!
   ...
   ```

   Note that the process will hang indefinitely (doesn't exit to avoid restart loops). So, you must
   manually kill the process and replace it with a new binary. Do so now with `Ctrl+C` or `killall gaiad`.

   In `gaia/app/app.go`, after `upgrade.Keeper` is initialized and set in the app, set the
   corresponding upgrade `Handler` with the correct `<plan-name>`:

   ```go theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
   app.upgradeKeeper.SetUpgradeHandler("<plan-name>", func(ctx sdk.Context, plan upgrade.Plan) {
           // custom logic after the network upgrade has been executed
   })
   ```

   Note that we panic on any error - this would cause the upgrade to fail if the
   migration could not be run, and no node would advance - allowing a manual recovery.
   If we ignored the errors, then we would proceed with an incomplete upgrade and
   have a very difficult time every recovering the proper state.

   Now, compile the new binary and run the upgraded code to complete the upgrade:

   ```bash expandable theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
   # create a new binary of gaia with the added upgrade handler
   $ make install

   # Restart the chain using the new binary. You should see the chain resume from
   # the upgrade height:
   # `I[2019-11-05|12:48:15.184] applying upgrade <plan-name> at height: <desired-upgrade-height>      module=main`
   $ gaiad start

   # verify there is no pending plan
   $ gaiad query upgrade plan

   # verify you can query the block header of the completed upgrade
   $ gaiad query upgrade applied <plan-name>
   ```