Skip to content

Upgrading Runtime

Jump to bottom
Shannon Wells edited this page Jan 6, 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 are in code format
    • UI Actions to click on are in boldface

Authorize upgrade process:

  1. (Anyone) Go to Governance → Democracy and click “submit preimage” for parachainSystem.authorizeUpgrade. Click “upload a file” button, and navigate in the Finder 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.

  2. 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”.

  3. (Council) Go to Governance → Council → Motions and click “propose external” and paste the preimage hash. Once it’s in a block, it will appear in this Motions pane.

  4. (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.

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

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

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

  8. (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.

  9. 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
  1. (TC) Other Technical Committee members should vote on the Fast Track proposal.
  2. (Anyone) Once the threshold shown (again, this is shown in the threshold column) is reached, close the Fast Track proposal.
  3. If it was approved, it becomes a referendum and people may vote on it.
  4. (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._
  1. 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 for scheduler.executed. 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.

(Anyone) Enact authorized upgrade process:

  1. Once the authorizeUpgrade execution has completed, use Developer → Extrinsics to call parachainSystem.enactAuthorizedUpgrade. There is no need to go through the referendum process.
  2. Make sure you have enough token to cover storing the wasm.
  3. If this call was successful, you should see events in Network → Explorer, “parachainSystem.ValidationFunctionStored”, followed by “parachainSystem.ValidationFunctionApplied”.
  4. 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.
Clone this wiki locally