Upgrading Runtime - frequency-chain/frequency GitHub Wiki

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 showing the right buttons in the dashboard, try reloading the page.
• Required account types for each extrinsic to be submitted:
  • (Council) = must be executed using a Frequency Council account before moving to the next step.
  • (TC) = must be executed using a Frequency Technical Committee account before moving to the next step.
  • (Anyone) = any account with enough tokens may execute this step.
• Legend:
  • UI menu items/panes are in Italics
  • Extrinsic names, file names, and commands are in code format
  • UI Actions to click on are in boldface

• Frequency Paseo Democracy pane
• Frequency Mainnet Democracy pane

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 double check the Wasm output matches 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
   • Verify the Blake2-256 hash output is the same and also matches what you see when you click "hash a file" when submitting the preimage in step 3 below.

3. Generate the correct preimage hash

   1. Go to Governance → Preimages and click "Add preimage" for system.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.

4. Technical Council: Request Preimage

   1. (TC) Go to Developer → Extrinsics and select technicalCommitte.execute.
   2. (TC) Within proposal: RuntimeCall (proposal), select preimage.requestPreimage.
   3. (TC) Paste the preimage hash you copied in step 3 above into the hash field.
   4. (TC) Paste the preimage length you copied in step 3 above into the lengthBound field.
   5. (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. Note: The length will show as 0, until the preimage is uploaded.

   1. Now actually return to step 3 above and follow the steps for add the preimage, except this time, ACTUALLY SUBMIT THE TRANSACTION.

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

7. (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.
   • 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 leave the option toggled on to include your “Aye” vote - assuming you support the Fast Track of course (which is the default). Change the delay and voting period if you need to. Note: voting period can not be set to 0.

    • If successful, this proposal will appear in Governance → Technical Committee → Proposals. Double-check that the proposal is for system.authorizeUpgrade. You can view “recent events” in Network → Explorer as before. If the proposal has 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 previous Fast Track call, you will also need to vote now.

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

    • If the proposal 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 many tokens you wish to vote with and your 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 by:

    • Checking recent events in Network → Explorer for democracy.executed.
    • Expanding this event to make sure it executes properly before proceeding with the "Enact authorized upgrade" process, otherwise you will be wasting tokens by storing a new Wasm on chain that cannot be used. Here is a screenshot of a successfully executed authorizeUpgrade:

• Frequency Testnet on Paseo Extrinsics pane
• Frequency Mainnet Extrinsics pane

1. Once the authorizeUpgrade execution has completed, you will go to Developer → Extrinsics and call system.applyAuthorizedUpgrade. 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 system.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 tokens 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.
   • Go to the Polkadot Parachains page, to see "Upgrading" before the upgrade is completed. It may take close to an hour.
   • 
   • 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 within which it was successfully upgraded.
   • 
5. Post that the release has been deployed to the specific network in Discord in #tech-chat.

• Only Root Origin can call cancel_referendum.

• After closing, Fast Track execution fails with BadOrigin:
  • If the Voting period was zero.
  • If the Voting period and/or Delay were set too low (but not zero) based on democracy pallet/collective pallet configuration.
  • If there were insufficient Aye votes when the voting period ended.
  • If the Technical Committee member count is an even number and exactly half voted Aye. (It needs to be Threshold + 1 in this case as over 505 is required.)
  • If fast track as a motion was not submitted via the correct committee - e.g. submitting a “fast trackable” external proposal via the Council.
• If 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.
• If 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.

• 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 system.authorizeUpgrade. Click "hash a file" button, and navigate in the Finder/Explorer window to select the new Wasm. Check that:
   • The hash matches the hash from the release notes.
   • If this call was successful, you should see events in Network → Explorer, "system.UpgradeAuthorized", followed by "sudo.Sudid".
4. Once the authorizeUpgrade execution has completed, go to Developer → Extrinsics and call system.applyAuthorizedUpgrade. 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 system.authorizeUpgrade.
6. Click the 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 tokens to cover the transaction. This will be larger than usual because also pay for storing the Wasm file.
   • If this call succeeded, 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.
   • To further validate that the runtime upgrade has succeeded, check 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 within which it was successfully upgraded.
8. Post that the release has been deployed to the specific network in Discord in #tech-chat.