# Software Upgrade

## Software Upgrade

The software upgrade proposal allows the community to vote on the acceptance, or not, of an update the BET`chaind` binary. This upgrade could be for whatever reason, as specified by the BET Chain Developers / Maintainers.

Selecting `software-upgrade` for `proposal type` after executing the `draft-proposal` command will request the following parameters:

* **Proposal title:** the distinguishing name of the proposal, typically the way the that explorers list proposals.
* **Proposal author(s):** the person(s) making the proposal.
* **Proposal summary:** a high level, brief overview of the proposal.
* **Proposal details:** a detailed, expansive explanation of the proposal.
* **Proposal forum url:** the web location which contains more detail and where people can engage in discussion regarding the proposal.
* **Proposal vote option context:** The option set of a proposal refers to the set of choices a participant can choose from when casting its vote. The initial option set includes the following options: `Yes`, `No`, `NoWithVeto`, `Abstain`. The`NoWithVeto` counts as `No` but also adds a `Veto` vote. `Abstain` option allows voters to signal that they do not intend to vote in favour or against the proposal but accept the result of the vote.
* **Proposal deposit:** the amount of AUM deposited in order for the proposal to be considered. The minimum amount required my BET Chain is 100 OM. (100\_000\_000 uom).
* **Msg's authority:** This is the wallet that has the authority to submit the software update. This is typically the same wallet submitting the proposal.

Copy

```
$ BETchaind tx gov draft-proposal
✔ software-upgrade
Enter proposal's title: Example software upgrade proposal
✔ Enter proposal's authors: Martin Halford█
Enter proposal's summary: This is an example software upgrade proposal in order to demonstrate the proposal governance mechanism on MANTRA Chain.
Enter proposal's details: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eleifend non magna sit amet efficitur.
Enter proposal's proposal forum url: https://forum.BETchain.io/proposal-002
Enter proposal's vote option context: Yes, No, NoTWithVeto, Abstain
Enter proposal deposit: 1000000000uom
Enter msg's authority: BET10d07y265gmmuvt4z0w9aw880jnsr700j3fep4f
The draft proposal has successfully been generated.
Proposals should contain off-chain metadata, please upload the metadata JSON to IPFS.
Then, replace the generated metadata field with the IPFS CID.
```

The `draft-proposal` command will generate two (2) files:

Example `draft_proposal.json`

Copy

```
{
 "messages": [
  {
   "@type": "/cosmos.upgrade.v1beta1.MsgSoftwareUpgrade",
   "authority": "BET10d07y265gmmuvt4z0w9aw880jnsr700j3fep4f",
   "plan": {
    "name": "",
    "time": "0001-01-01T00:00:00Z",
    "height": "0",
    "info": "",
    "upgraded_client_state": null
   }
  }
 ],
 "metadata": "ipfs://CID",
 "deposit": "1000000000uom",
 "title": "Example software upgrade proposal",
 "summary": "This is an example software upgrade proposal in order to demonstrate the proposal governance mechanism on MANTRA Chain."
}
```

Edit the `draft_proposal.json` and update the `plan` which informs Validators regarding when they are expected to perform the update to their nodes and the location from where they can retrieve the binary.

Example `draft_metadata.json`

Copy

```
{
 "title": "Example software upgrade proposal",
 "authors": [
  "Martin Halford"
 ],
 "summary": "This is an example software upgrade proposal in order to demonstrate the proposal governance mechanism on MANTRA Chain.",
 "details": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eleifend non magna sit amet efficitur.",
 "proposal_forum_url": "https://forum.mantrachain.io/proposal-002",
 "vote_option_context": "Yes, No, NoTWithVeto, Abstain"
}
```

If proposals are of type `SoftwareUpgradeProposal`, then nodes need to upgrade their software to the new version that was voted. This process is divided in two steps.

Of the two (2) files, the `draft_proposal.json` file is submitted to the MANTRA Chain as part of the `submit-proposal` transaction.

The file `draft_metadata.json` is referenced within the `draft_proposal.json` in the attribute `"metadata": "ipfs://CID"`.

Upload the `draft_metadata.json` to an IPFS location and edit the `draft_proposal.json` attribute with the uploaded files IPFS location details.

Example `draft_proposal.json` with edited `plan` and IPFS location:

Copy

```
{
 "messages": [
  {
   "@type": "/cosmos.upgrade.v1beta1.MsgSoftwareUpgrade",
   "authority": "mantra10d07y265gmmuvt4z0w9aw880jnsr700j3fep4f",
   "plan": {
    "name": "",
    "time": "0001-01-01T00:00:00Z",
    "height": "0",
    "info": "",
    "upgraded_client_state": "ipfs://QmatNt96KnybCiuwBNyVBXiicaZJbu54ocUtznegin1zNt"
   }
  }
 ],
 "metadata": "ipfs://QmatNt96KnybCiuwBNyVBXiicaZJbu54ocUtznegin1zNt",
 "deposit": "1000000000uom",
 "title": "Example software upgrade proposal",
 "summary": "This is an example software upgrade proposal in order to demonstrate the proposal governance mechanism on MANTRA Chain."
}
```

**Note:** IPFS (InterPlanetary File System) is beyond the scope of this document. To learn more about IPS, see <https://docs.ipfs.tech>. In order to get started with IPFS and be able to upload and download files, you can try <https://docs.ipfs.tech/install/ipfs-desktop/> for Windows, Mac and Linux.

**Signal**

After a `software-upgrade` proposal is accepted, validators are expected to download and install the new version of the software while continuing to run the previous version. Once a validator has downloaded and installed the upgrade, it will start signaling to the network that it is ready to switch by including the proposal's `proposalID` in its *precommits*.

Note: There is only one signal slot per *precommit*. If several `software-upgrade` proposal are accepted in a short timeframe, a pipeline will form and they will be implemented one after the other in the order that they were accepted.

**Switch**

Once a block contains more than 2/3rd *precommits* where a common`software-upgrade` proposal is signaled, all the nodes (including validator nodes, non-validating full nodes and light-nodes) are expected to switch to the new version of the software.
