Skip to content

Upgrading Runtime

Jump to bottom
Wil Wade edited this page Oct 7, 2024 · 32 revisions

Intro

This process is for performing a runtime upgrade using the PolkadotJS Dashboard. The two major components to this are authorizing the upgrade and enacting the authorized upgrade.

  • If a motion, proposal or referendum is not appearing or not showing the right buttons, try reloading the page.
  • Required account types for each extrinsic to be submitted:
    • (Council) = must be executed using a Frequency Council account.
    • (TC) = must be executed using a Frequency Technical Committee account.
    • (Anyone) = any account with enough token may execute this step.
  • Legend:
    • UI menu items/panes are in Italic
    • Extrinsic names, file names, and commands are in code format
    • UI Actions to click on are in boldface

Authorize upgrade process:

  1. Download the wasm for the chain. It will be in the Assets section of the release. The file to use is:

    • Frequency Paseo Testnet: frequency-paseo_runtime-<version>.compact.compressed.wasm
    • Frequency Mainnet: frequency_runtime-<version>.compact.compressed.wasm

  2. Type subwasm info <wasm name>.compact.compressed.wasm to check the wasm, to double check the output is what is in the Release notes. In particular:

    • Verify that "Core version" reflects the same as the subwasm you are doing the upgrade for. For example, for Testnet the Core version looks like frequency-testnet-5. For Mainnet it would be frequency-5
    • The Blake2-256 hash output. It should be the same. It should also match what you see when you click "hash a file" for submitting the preimage, later.

  3. Generate the correct preimage hash

    1. Go to Governance → Preimages and click "Add preimage" for parachainSystem.authorizeUpgrade.
    2. Click "hash a file" toggle button, and navigate in the Finder/Explorer window to select the new wasm.
    3. Verify that "codeHash: H256 (Hash)" is the same as Blake2-256 hash in your subwasm output from before.
    4. Do not submit the transaction.
    5. Copy the preimage hash and the preimage length values and store them somewhere. Screenshot 2023-03-17 at 4 18 29 PM

  4. Technical Council: Request Preimage 1. (TC) Go to Developer → Extrinsics and select technicalCommitte.execute.
    1. (TC) Within proposal: Call (proposal), select preimage.requestPreimage.
    1. (TC) Paste the preimage hash you copied into the hash field.
    1. (TC) Paste the preimage length you copied into the lengthBound field.
    1. (TC) Submit the transaction.

  5. (Anyone) Go to Governance → Preimages and you should see a row in the preimages section that has an empty middle section, which is the indicator that a preimage has been requested.
    Screenshot 2023-03-17 at 4 34 00 PM

    1. Now actually add the preimage as above, but submit the transaction.

  6. Go to Governance → Preimages and copy the preimage hash for parachainSystem.authorizeUpgrade that was uploaded.

  7. (Council) Go to Governance → Council → Motions and click "propose external" and paste the preimage hash (which is the same as the proposal hash).

    • Once it’s in a block, it will appear in this Motions pane.
    • For Mainnet, edit the description of this proposal to say that this is a motion to authorize an upgrade, include the new release version number, and a link back to the Release Notes, so it shows up on Frequency Polkassembly Referenda

  8. (Council) Council members must now vote on the motion by clicking "Vote." In the row for the external proposal/motion, the “threshold” column shows the number of members of the Council that must vote Aye for the proposal to pass.

    • NOTE: if you have an even number of Council members, you will need 1 more Aye vote than the threshold shown because it has to be a “Majority” vote, which means >50% of voters voting Aye.

  9. (Anyone) Once the threshold is reached, close the motion by clicking Close in the motion row.

    • If successful, the motion becomes an external proposal. Look at the “recent events” in Network → Explorer to check that the motion was executed successfully.

  10. The Technical Committee may now Fast Track this external proposal. View the external proposal in the Governance → Democracy pane.

  11. (TC) Click "Fast Track" next to the proposal, and turn off the option to include your “Aye” vote (this is the default). Change the delay and voting period if you need to as long as voting period is not 0. NOTE as of 2022-02-08 "including your 'Aye' vote does not work because we do not have batch calls enabled.

    • If you were successful, this proposal will appear in Governance → Technical Committee → Proposals. Double-check that the proposal is for parachainSystem.authorizeUpgrade. You can view “recent events” in Network → Explorer as before, if it failed. You should see:
    technicalCommittee.Executed
A motion was executed; result will be Ok if it returned without error. 
proposalHash: H256
result: Result<Null, SpRuntimeDispatchError>
Ok

  12. (TC) Other Technical Committee members should vote on the Fast Track proposal. If you did not include your Aye vote in the Fast Track call, you will also need to vote.

  13. (Anyone) Once the threshold shown (again, this is shown in the threshold column) is reached, close the Fast Track proposal.

    • If it was approved, it becomes a referendum and people may vote on it.

  14. (Anyone) Vote on the referendum throughout the Launch Period by going to Governance → Democracy and clicking the "Vote" button to submit a democracy.vote extrinsic, specifying how much token to vote with and conviction level before submitting. Once the launch period ends, assuming it passes, the scheduler schedules the enactment for a particular block.

    • You can view it in the “recent events”, looking for scheduler.Scheduled. You should see something like:
    scheduler.Scheduled
Scheduled some task. 
when: u32
  243  ← block number when the authorizeUpgrade will be executed.
index: u32
  0 

democracy.Passed
A proposal has been approved by referendum. 
refIndex: u32
  5  ← the index of the proposal.

  15. Make a note of the block that was scheduled and keep an eye out for that block; wait for that block to come.

    • Check recent events in Network → Explorer for democracy.executed.
    • Expand this event to make sure this executes okay before proceeding with the "Enact authorized upgrade" process, otherwise you will be wasting token by storing a new wasm on chain that can’t be used. Here is a screenshot of a successfully executed authorizeUpgrade: Screenshot 2023-01-06 at 10 17 11 AM

(Anyone) Enact authorized upgrade process:

  1. Once the authorizeUpgrade execution has completed, you will go to Developer → Extrinsics and call parachainSystem.enactAuthorizedUpgrade. There is no need to go through the referendum process.
  2. Click the "file upload" toggle and then click the field to navigate to the same wasm you uploaded as before when submitting parachainSystem.authorizeUpgrade.
  3. Click Submit Transaction button to open the transaction window
    • Before clicking "Sign and submit" in the transaction window, ensure the account you're signing with has enough token to cover the transaction. This will be larger than usual because you must pay for storing the wasm file.
    • If this call was successful, you should see events in Network → Explorer, "parachainSystem.ValidationFunctionStored", followed by "parachainSystem.ValidationFunctionApplied". This event could be separated from the first one by anywhere from a few minutes to an hour.
    • On the Relay chain you may be able to see "Upgrading" under Network → Parachains before the upgrade is completed:
    • Upgrade in progress Screenshot
    • You can further validate that the runtime upgrade has succeeded by checking chain state: Developer → ChainState → Storage, then call system.lastRuntimeUpgrade and verify that the spec version has changed to the new one you expected.
  4. Update the release notes to record the block number it was successfully upgraded on.
    • Release Notes Screenshot
  5. Post that the release has been deployed to the specific network in Discord in #tech-chat.

NOTES

  • Only Root Origin can call cancel_referendum.

Troubleshooting guide:

  • After closing, Fast Track execution fails with BadOrigin:
    • the Voting period was zero.
    • the Voting period and/or Delay were set too low (but not zero) based on democracy pallet/collective pallet configuration.
    • Not enough Aye votes when the voting period ended.
    • Technical Committee member count is an even number and exactly half voted Aye. It needs to be Threshold + 1 voting Aye.
    • did not correctly submit a fast track as a motion via the correct committee - this was because of not submitting a “fast trackable” external proposal via the Council.
  • Execution of the Fast Track fails with ProposalMissing - check if it had already moved into referendum - seen in local testing, where launch periods are a few minutes. In this case there's nothing to fix, just start voting.
  • Motion to authorize preimage fails with Bad Origin
    • check if it is executed as the collective that made the motion, rather than as Root. Any motion approved by a collective will be executed as that collective origin.

Sudo Version

  • For local and Frequency Testnets.
  1. Download the wasm for the chain. It will be in the Assets section of the release. The file to use is:
    • Frequency Paseo Testnet: frequency-paseo_runtime-<version>.compact.compressed.wasm
    • Frequency Rococo Testnet: frequency-rococo_runtime-<version>.compact.compressed.wasm
  2. Type subwasm info <wasm name>.compact.compressed.wasm to check the wasm.
    • Verify that "Core version" reflects the same as the subwasm you are doing the upgrade for. For example, for Rococo the Core version looks like frequency-testnet-5. For Mainnet it would be frequency-5
    • Make a note of the Blake2-256 hash. It should be the same as when you click "hash a file" for submitting the preimage.
  3. Go to Developer → Sudo and call parachainSystem.authorizeUpgrade. Click "hash a file" button, and navigate in the Finder/Explorer window to select the new wasm.
    • The hash should match the hash from the release notes.
    • If this call was successful, you should see events in Network → Explorer, "parachainSystem.UpgradeAuthorized", followed by "sudo.Sudid".
  4. Once the authorizeUpgrade execution has completed, you will go to Developer → Extrinsics and call parachainSystem.enactAuthorizedUpgrade. There is no need to go through the referendum process.
  5. Click the "file upload" toggle and then click the field to navigate to the same wasm you uploaded as before when submitting parachainSystem.authorizeUpgrade.
  6. Click Submit Transaction button to open the transaction window
    • Before clicking "Sign and submit" in the transaction window, ensure the account you're signing with has enough token to cover the transaction. This will be larger than usual because you must pay for storing the wasm file.
    • If this call was successful, you should see events in Network → Explorer, "parachainSystem.ValidationFunctionStored", followed by "parachainSystem.ValidationFunctionApplied".
    • On the Relay chain you may be able to see "Upgrading" under Network → Parachains before the upgrade is completed:
    • Upgrade in progress Screenshot
    • You can further validate that the runtime upgrade has succeeded by checking chain state: Developer → ChainState → Storage, then call system.lastRuntimeUpgrade and verify that the spec version has changed to the new one you expected.
  7. Update the release notes to record the block number it was successfully upgraded on.
    • Screenshot 2023-01-13
  8. Post that the release has been deployed to the specific network in Discord in #tech-chat.
Clone this wiki locally