This document offers the information and instructions required for node operators complete an upgrade with a fresh installation.
We decided to remove the debian package as an installtion artifact and use our own installation tool. The main reason for this is to help our current and future node operators join the cheqd network or complete an upgrade in a more intuitive, simpler and less time intensive way.
For this upgrade from 0.5.0
to 0.6.0
there are 2 possible scenario:
upgrade by installing Cosmovisor
upgrade only cheqd-noded
binary.
Cosmovisor is a tool from the cosmos-sdk
team which is able to make an upgrade in a full-auto mode. It can download and exchange binary without any actions from a node operator. Beginning with version 0.6.0
, and with all subsequent versions, we will leverage Cosmosvisor as a tool to handling our upgrade process.
For more information about interactive installer please see this documentation. You will find answers to common questions within this document, however of course feel free to reach out to the team on Slack or Discord.
As the installation and setting up the Cosmovisor can be difficult, and requires some additional steps for setting up the systemd
service, we injected all this steps into our interactive installer.
The flow for installtion is:
systemd
serviceMake sure that it was definitely stopped by using:
The output should be:
the main focus here: Active: inactive (dead)
cheqd-noded
binary with the Cosmovisor installationIMPORTANT For running an Upgrade scenario
you'll be required to setup a current home directory for a cheqd
user as an answer on question Set path for cheqd user's home directory [default: /home/cheqd]:
. This is because the upgrade scenario will only be used if this directory exists.
WARNING Please make sure that you answered yes
for questions about overwriting existing configuration. It's very important when making a new installation with Cosmovisor.
systemd
serviceIf you are updating a current installation the next steps can be used:
systemd
serviceand make sure that it was really stopped by:
Output should be like:
the main focus here: Active: inactive (dead)
IMPORTANT For running an Upgrade scenario
you'll be required to setup a current home directory for a cheqd
user as an answer on question Set path for cheqd user's home directory [default: /home/cheqd]:
. This is because the upgrade scenario will only be used if this directory exists.
WARNING. IF you are keeping just standalone a cheqd-noded
, without Cosmovisor, it's crucial you keep your systemd
service files without overwriting them. Please make sure that your answers were no
.
Updates to the ledger code running on cheqd mainnet/testnet is voted in via governance proposals on-chain for "breaking" software changes.
We use semantic versioning to define our software release versions. The latest software version running on chain is in the v1.x.x family. Any new release versions that bump only the minor/fix version digits (the second and the third part of release version numbers) is intended to be compatible within the family and does not require an on-chain upgrade proposal to be made.
Network-wide software upgrades are typically initiated by the core development team behind the cheqd project. The process followed for the network upgrade is defined in our guide on creating a Software Upgrade proposal via network governance.
This section lists previous software upgrade proposals which are no longer valid for the active mainnet/testnet.
Upgrade process includes 2 main parts:
Sending a SoftwareUpgradeProposal
to the network
Moving to the new binary manually
SoftwareUpgradeProposal
In general, this proposal is the document which includes some additional information for operators about improvements in new version of application or another additional remarks. There are not any requirements for proposal text, just recommendations and information for operators. And also, please make sure that this proposal will be stored in the ledger in case of success voting process in the future.
The next steps are describing the general flow for making a proposal:
Send proposal command to the pool;
After getting it, ledger will be in the PROPOSAL_STATUS_DEPOSIT_PERIOD
;
After sending the first deposit from one of other operators, proposal status will be moved to PROPOSAL_STATUS_VOTING_PERIOD
and voting period (2 weeks for now) will be started;
Due to the voting period operators should send their votes to the pool, get new binary downloaded and got to be installed;
After voting period passing (for now it's 2 weeks) in case of success voting process proposal should be passed to PROPOSAL_STATUS_PASSED
;
The next step is waiting for height
which was suggested for upgrade.
On the proposed height
current node will be blocked until new binary will be installed and set up.
The main parameters here are:
upgrade_to_0.3
- name of proposal which will be used in UpgradeHandler
in the new application,
--upgrade-height
- height when upgrade process will be occurred,
--from
- alias of a key which will be used for signing proposal,
<chain_id>
- identifier of chain which will be used while creating the blockchain.
In case of successful submitting the next command can be used for getting proposal_id
:
This command will return list of all proposals. It's needed to find the last one with corresponding name
and title
. Please, remember this proposal_id
because it will be used in next steps.
Also, the next command is very useful for getting information about proposal status:
Expected result for this state is PROPOSAL_STATUS_DEPOSIT_PERIOD
, It means, that pool is in waiting for the first deposit state.
Since getting proposal, the DEPOSIT
should be set to the pool.It will be return after finishing voting_preiod. For setting deposit the next command is used:
Parameters:
<proposal_id>
- proposal identifier from [step](#Command for sending proposal) In this example, amount of deposit is equal to current min-deposit
value.
After getting deposit from the previous step, the VOTING_PERIOD
will be started. For now, we have 2 weeks for making some discussions and collecting needed vote count. For setting vote, the next command can be used:
The main parameters here:
<proposal_id>
- proposal identifier from [step](#Command for sending proposal)
Votes can be queried by sending request:
At the end of voting period, after voting_end_time
, the state of proposal with <proposal_id>
should be changed to PROPOSAL_STATUS_PASSED
, if there was enough votes Also, deposits should be refunded back to the operators.
After getting proposal status as passed, upgrade plan will be active. It can be requested by:
It means, that at height 1000 BeginBlocker
will be set and node will be out of consensus and wait for moving to the new version of application.
It will be stopped and the next messages in log are expected:
After setting up new version of application node will continue ordering process.
Instructions on setting up a new node/version can be found in our installation guide.