staking.params.max_allowancesspecifies the maximum number of allowances on account can store. It will be set to 16 (default value is 0) to enable support for beneficiary allowances which are required to transfer tokens into a ParaTime.
staking.params.gas_costs, governance.params.gas_costs and roothash.params.gas_costs specify gas costs for various types of staking, governance and roothash transactions. Gas costs for transactions that were missing gas costs will be added.
scheduler.params.max_validators is the maximum size of the consensus committee (i.e. the validator set). It will be increased to110 (it was set to 100 previously).
Instructions - Voting
Voting for the upgrade proposal will end at epoch 7876. We expect the Mainnet network to reach this epoch at around 2021-08-24 12:00 UTC.
At this time only entities which have active validator nodes scheduled in the validator set are eligible to vote for governance proposals.
At least 75% of the voting power needs to cast vote on the upgrade proposal for the result to be valid.
At least 90% of the votes need to be yes votes for a proposal to be accepted.
This upgrade will be the first upgrade that will use the new on-chain governance service introduced in the Cobalt Upgrade.
NONCE=$(oasis-node stake account nonce --stake.account.address $ADDRESS -a $ADDR)
where <PATH-TO-YOUR-ENTITY> is the path to your entity's descriptor, e.g. /serverdir/node/entity/.
To vote for the proposal, use the following command to generate a suitable transaction:
oasis-node governance gen_cast_vote \
--transaction.file tx_cast_vote.json \
where TX_FLAGS refer to previously set base and signer flags as described in the Oasis CLI Tools Setup doc.
If you use a Ledger-signer backed entity, you will need to install version 2.3.1 of the Oasis App as described in Installing Oasis App 2.3.1 to Your Ledger. This is needed because the current version of the Oasis App available through Ledger Live, version 1.8.2, doesn't support signing the governance.CastVote transaction type.
To submit the generated transaction, copy tx_cast_vote.json to the online Oasis node and submit it from there:
oasis-node consensus submit_tx \
Instructions - Before Upgrade System Preparation
This upgrade will upgrade Oasis Core to version 21.2.8 which:
Upgrades the BadgerDB database backend from v2 to v3. See BadgerDB v2 to v3 Migration section for required steps to be done before upgrade.
Has a check that makes sure the file descriptor limit is set to an appropriately high value (at least 50000). While previous versions only warned in case the limit was set too low, this version will refuse to start. Follow the File Descriptor Limit documentation page for details on how to increase the limit on your system.
Stop your node, replace the old version of Oasis Node with version 21.2.8 and restart your node.
Since Oasis Core 21.2.8 is otherwise compatible with the current consensus layer protocol, you may upgrade your Mainnet node to this version at any time.
For this upgrade, do NOT wipe state.
Once reaching the designated upgrade epoch, your node will stop and needs to be upgraded to Oasis Core 21.2.8.
If you upgraded your node to Oasis Core 21.2.8 before the upgrade epoch was reached, you only need to restart your node for the upgrade to proceed.
Otherwise, you need to upgrade your node to Oasis Core 21.2.8 first and then restart it.
If you use a process manager like systemd or Supervisor, you can configure it to restart the Oasis Node automatically.
The Mainnet's genesis file and the genesis document's hash will remain the same.
BadgerDB v2 to v3 Migration
This upgrade will upgrade Oasis Core to version 21.2.x which includes the new BadgerDB v3.
Since BadgerDB's on-disk format changed in v3, it requires on-disk state migration. The migration process is done automatically and makes the following steps:
Upon startup, Oasis Node will start migrating all <DATA-DIR>/**/*.badger.db files (Badger v2 files) and start writing Badger v3 DB to files with the .migrate suffix.
If the migration fails in the middle, Oasis Node will delete all <DATA-DIR>/**/*.badger.db.migrate files the next time it starts and start the migration (of the remaining <DATA-DIR>/**/*.badger.db
If the migration succeeds, Oasis Node will append the .backup suffix to all <DATA-DIR>/**/*.badger.db files (Badger v2 files) and remove the .migrate suffix from all <DATA-DIR>/**/*.badger.db.migrate files (Badger v3 files).
The BadgerDB v2 to v3 migration is very I/O intensive (both IOPS and throughput) and may take a couple of hours to complete.
To follow its progress, run:
shopt -s globstar
du -h <DATA-DIR>/**/*.badger.db* | sort -h -r
and observe the sizes of various *.badger.db* directories.
After you've confirmed your node is up and running, you can safely delete all the <DATA-DIR>/**/*.badger.db.backup files.
Extra memory requirements
BadgerDB v2 to v3 migration can use a number of Go routines to migrate different database files in parallel.
However, this comes with a memory cost. For larger database files, it might need up to 4 GB of RAM per database, so we recommend lowering the number of Go routines BadgerDB uses during migration (badger.migrate.num_go_routines) if your node has less than 8 GB of RAM.
If your node has less than 8 GB of RAM, set the number of Go routines BadgerDB uses during migration to 2 (default is 8) by adding the following to your node's config.yml:
# BadgerDB configuration.
# Set the number of Go routines BadgerDB uses during migration to 2 to lower
# the memory pressure during migration (at the expense of a longer migration
Installing Oasis App 2.3.1 to Your Ledger
This manual installation procedure is needed until the latest version of the Oasis App, version 2.3.1, becomes available through Ledger Live's Manager.
Unlike Nano S devices, Nano X devices are locked meaning one cannot manual install the latest version of the Oasis App on them. If you use a Nano X device, you will need to temporarily switch to a Nano S device or wait for the new version of the Oasis App to be available through Ledger Live's Manager.
Make the downloaded installer executable by running:
chmod +x installer_s.sh
Connect you Nano S and unlock it. Then execute the installer:
Your Nano S will give you the option to either:
Deny unsafe manager, or
review the Public Key and Allow unsafe manager.
First review the public key and ensure it matches the Generated random root public key displayed in the terminal.
Then double press the Allow unsafe manager option.
If there is an existing version of the Oasis App installed on your Nano S, you will be prompted with the Uninstall Oasis screen, followed by reviewing the Identifier (it will depend on the version of the Oasis App you have currently installed) and finally confirming deletion on the Confirm action screen.
After the new version of the Oasis App has finished loading, you will be prompted with the Install app Oasis screen, followed by reviewing the Version, Identifier and Code Identifier screens. Ensure the values are as follows:
Identifier (Application full hash on the terminal): E0CB424D3B1C2A0F694BCB6E99C3B37C7685399D59DD12D7CF80AF4A487882B1
Finally, confirm installation of the new app by double pressing on the Perform installation screen. Your Ledger device will ask for your PIN again.
Installing Oasis App 2.3.1 on a Nano S with the firmware version < 2.0.0 (e.g. 1.6.1) will NOT fail. It will show a different Identifier when installing the app which will NOT match the Application full hash shown on the terminal. However, opening the app will not work and it will "freeze" your Nano S device.
Open the Oasis App on your Nano S and ensure the Version screen shows version 2.3.1.
Starting the manually installed version of the Oasis App will always show the This app is not genuine screen, followed by Identifier (which should match the Identifier value above) screen. Finally, open the application by double pressing on the Open application screen.
After you've signed your governance.CastVote transaction, you can safely downgrade Oasis App to the latest official version available via Ledger Live, version 1.8.2.
To do that, just open Ledger Live's Manager and it will prompt you to install version 1.8.2.
2021-04-28 (16:00 UTC) - Cobalt Upgrade
Upgrade height: upgrade is scheduled to happen at epoch 5046.
We expect the Mainnet network to reach this epoch at around 2021-04-28 12:00 UTC.
Instructions - Before upgrade
Make sure you are running the latest Mainnet-compatible Oasis Node version: 20.12.7.
If you are running a different 20.12.x Oasis Node version, update to version 20.12.7 before the upgrade.
Version 20.12.7 is backwards compatible with other 20.12.x releases, so upgrade can be performed at any time by stopping the node and replacing the binary.
The upgrade descriptor contains a non-existing upgrade handler and will be used to coordinate the network shutdown, the rest of the upgrade is manual.
Following section is relevant only for runtime operators that are running storage nodes for active runtimes on the Mainnet.
This upgrade requires a runtime storage node migration to be performed before the upgrade genesis is published. This can be done before the upgrade epoch is reached by stopping all runtime nodes and running the migration.
Backup your node's data directory
To prevent irrecoverable runtime storage data corruption/loss in case of a failed storage migration, backup your node's data directory.
For example, to backup the /serverdir/node directory using the rsync tool, run:
rsync -a /serverdir/node/ /serverdir/node-BACKUP/
The storage database on all storage nodes needs to be migrated with the following command (using the 21.1.1 binary):
oasis-node storage migrate \
--datadir <NODE-DATADIR> \
After the migration to v5 completes, you will see an output similar to:
Take note of the displayed state-root and report it to the Foundation, as it needs to be included in the upgrade's new genesis file. Keep the runtime nodes stopped until the upgrade epoch is reached. At upgrade epoch, upgrade the nodes by following the remaining steps above.
Instructions - Upgrade day
Following steps should be performed on 2021-04-28 only after the network has reached the upgrade epoch and has halted: