Software Upgrade

The software upgrade proposal allows the community to vote on the acceptance, or not, of an update the mantrachaind binary. This upgrade could be for whatever reason, as specified by the MANTRA 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. TheNoWithVeto 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 MANTRA 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.

$ mantrachaind 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.mantrachain.io/proposal-002
Enter proposal's vote option context: Yes, No, NoTWithVeto, Abstain
Enter proposal deposit: 1000000000uom
Enter msg's authority: mantra10d07y265gmmuvt4z0w9aw880jnsr700j3fep4f
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

{
 "messages": [
  {
   "@type": "/cosmos.upgrade.v1beta1.MsgSoftwareUpgrade",
   "authority": "mantra10d07y265gmmuvt4z0w9aw880jnsr700j3fep4f",
   "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

{
 "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:

{
 "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 commonsoftware-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.