Skip to content

Upgrading Runtime

Shannon Wells edited this page Jan 9, 2023 · 33 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 Rococo: frequency-rococo_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.
    • 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-rococo-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. (Anyone) Go to Governance → Democracy and click “submit preimage” for parachainSystem.authorizeUpgrade. Click “hash a file” button, and navigate in the Finder/Explorer window to select the new wasm. Before submitting the extrinsic, you may copy the value of “preimage hash” to submit in step 2 by clicking the copy icon next to the "preimage hash" field.
  4. If you did not already copy the preimage hash, go to Network → Explorer and get it from the “recent events” section, by looking for a democracy.notePreimage event/call. Click the copy icon to copy “proposalHash” (which is the same as the preimage hash).
  5. (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.
  6. (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.
  7. (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.
  8. The Technical Committee may now Fast Track this external proposal. View the external proposal in the Governance → Democracy pane.
  9. (TC) Click "Fast Track" next to the proposal, and 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.
    • 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
    
  10. (TC) Other Technical Committee members should vote on the Fast Track proposal.
  11. (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.
  12. (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.
    
  13. 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”.
    • 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.

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.