Forkless Upgrades

Examples and Resources

• Storage Migration: https://github.com/LibertyDSNP/frequency/pull/485/files
• Generate Substrate Upgrade Docs: https://docs.substrate.io/build/upgrade-the-runtime/
• Substrate How To: https://docs.substrate.io/reference/how-to-guides/parachains/runtime-upgrade/
• Substrate Tutorial: https://docs.substrate.io/tutorials/get-started/upgrade-a-running-network/

via Sudo+Polkadot dashboard

To upgrade a parachain, the relay chain has to know about the upgrade in advance. Then, when the enactment extrinsic for the upgrade is submitted, the relay chain is also alerted and checks the WASM against the previously provided hash.

The extrinsics are part of the cumulus pallet_parachain_system. Both extrinsics call ensureRoot on the origin, so only Sudoers can call it.

Setup

1. Build the new release target
   1. Local Automated
      • If developing locally, ensure that the two relay nodes and the parachain are running
      • Run make upgrade-local from the root frequency directory. The make command will execute a script that builds the release target for local development, calls the extrinsic to authorize the upgrade, then calls the extrinsic to enact the upgrade. No further steps are required to upgrade the local runtime.
   2. Local Manually: Run make build-local from the root frequency directory.
   3. Mainnet and Rococo: Will use release artifacts
      • Mainnet: frequency-mainnet_runtime-v[SPEC VERSION].[RELEASE VERSION].compact.compressed.wasm
      • Rococo: frequency-rococo_runtime-v[SPEC VERSION].[RELEASE VERSION].compact.compressed.wasm
2. Connect to the Polkadot dashboard
3. Depending on the chain you’re using,
   1. If on a Rococo parachain, for example, you must have imported the Sudo account keys into the list of connected accounts for this to work.
   2. If developing locally you will be using whatever root key is configured usually is the Alice account (//Alice).

Authorize the upgrade

This step authorizes the upgrade by storing the expected hash of the upgrade.

1. Go to the Developer → Extrinsics panel.
2. Select the Sudo account for “using the selected account” from the dropdown. The Sudo account must already have been imported as an account into the dashboard.
3. From the same panel (Developer → Extrinsics), in “submit the following extrinsic,” select “sudo” and then “sudo”
4. From “call: Call”, select “parachainSystem” and “authorizeUpgrade”
5. Toggle “hash a file” switch
6. Click on the form entry to open a file browsing window
7. Select the new WASM.
   • Mainnet: frequency-mainnet_runtime-v[SPEC VERSION].[RELEASE VERSION].compact.compressed.wasm
   • Rococo: frequency-rococo_runtime-v[SPEC VERSION].[RELEASE VERSION].compact.compressed.wasm
   • Local Manual: /target/release/wbuild/frequency-rococo-runtime/frequency_rococo_runtime.compact.compressed.wasm **The rest of the fields in the Polkadot JS UI should be populated with the hash data and encoding details.
8. Click “Submit Transaction” and sign the transaction using the Sudo account key.

Enactment of the upgrade

This step schedules the forkless upgrade with the relay chain by submitting “enactAuthorizedUpgrade” as an RPC call by using the configured root key. The scheduler pallet is not required to schedule a runtime upgrade. We can not guarantee a block number to which a runtime upgrade will occur (See https://substrate.stackexchange.com/questions/5356/is-it-possible-to-schedule-a-sudo-upgrade).

1. From the same panel (Developer → Extrinsics), in “submit the following extrinsic,” select “sudo” and then “sudo”
2. In “call: Call”, select “parachainSystem” and “enactAuthorizedUpgrade(code)”
3. Toggle “file upload” on.
4. Select the new WASM, located in the same spot as before.
5. Click “Submit Transaction” and sign the transaction as before, using the Sudo account key.