Runtime Update Tutorial

From xx network wiki

Revision as of 20:31, 26 April 2022 by Bernie (talk | contribs) (Added tutorial to perform Runtime Update)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
This is a team contributed page

This wiki page describes how to perform a runtime update (code change) in the xx network blockchain.

1. Versioning

xxchain version follows the standard Semantic versioning of v[major].[minor].[patch]

Runtime versioning stays inline with the xxchain version, using a 6 digit string.

For example:

  • v0.2.0 -> runtime 00 02 00 = 200
  • v0.2.3 -> runtime 00 02 03 = 203
  • v1.0.0 -> runtime 01 00 00 = 10000
  • v1.1.0 -> runtime 01 01 00 = 10100

If a particular change in xxchain is client side only (no runtime changes), then the runtime version stays the same. These sort of changes should always be patches.

2. Runtime Compilation


  1. Create a branch containing the desired changes to the runtime (example: xxnetwork-runtime-203)
    • Naming should follow the standard: [spec_name]-runtime-[spec_version]
    • Make sure the spec version is correctly increased for the runtime
      • Example: current runtime spec version is 202, new version needs to be 203 at least, for the upgrade to be performed
    • Make sure Cargo.toml versions are also increased for the cli and runtime packages. Also, any packages that import the runtime should be updated to import the new version
  2. Commit changes to git, and create a tag following the Semantic versioning rules described above
  3. Compile the binary (which compiles the runtime)
    make build
  4. Use subwasm to get the system.setCode hash for the new runtime in compact compressed format. Example:
    subwasm info xxnetwork_runtime-203.compact.compressed.wasm
    🏋️ Runtime size:	    	0.795 MB (833,115 bytes)
    🗜 Compressed:		    	Yes, 74.36%
    ✨ Reserved meta:	    	OK - [6D, 65, 74, 61]
    🎁 Metadata version:	   	V14
    🔥 Core version:	    	xxnetwork-203 (xxlabs-xxnetwork-0.tx1.au0)
    🗳️ system.setCode hash:		0x092f5d2602817416b6a8cb567f2db88f7abb66f9cad3d94480afcf7d685a406c
    🗳️ authorizeUpgrade hash:   0x6ba81489caa2ec9fcd956eeb67cd673f6048ded1facb75f0cb8353e04bb98eca
    #️⃣ Blake2-256 hash:	    	0x0b46a6f95890932e163c72e3722bc707d029545eb34b6daa24500d6595919c83
    📦 IPFS:	
  5. Create a release on git from the tag, uploading the compiled compact compressed runtime, chain binary and output of subwasm in the description

Alternatively, if a release already exists, you can get the necessary binary, runtime code and subwasm information from the release notes.

Example: v0.2.3

3. Democracy Proposal


  1. In the explorer go to the Democracy
  2. Click the “Submit proposal” button
    Step 2
  3. Fill in the preimage hash with the system.setCode hash from the previous steps
    Steps 3 and 4
  4. Sign and submit the transaction

Now that the proposal is up, go to the xx network community channels (discord and telegram) and inform other members of the community about the proposed code change. It is important that information about the code change is included (references to github release), since the actual code won’t be put on chain until the referendum passes.

Once the proposal becomes a referendum, anyone can vote for it. Voting period is one week.

4. Verifying Code Changes

While the referendum is ongoing, community members might wish to verify that the proposer was truthful.


  1. Checkout the branch with the new runtime
  2. Compile the binary (which compiles the runtime)
    make build
  3. Use subwasm to get the system.setCode hash for the new runtime in compact compressed format (see above for example).
  4. Verify that the proposal preimage hash that is on-chain matches the system.setCode hash output in the previous step

5. Uploading Code

If the referendum passes, the enactment period is one week as well, meaning the change is only performed one week after the referendum ends. Before the end of this enactment period, the code changes must be uploaded on chain, otherwise the enactment will fail.

This can be done by anyone, without needing to reserve coins, since the preimage is imminent.


  1. In the explorer go to the Democracy/Dispatch
  2. Click the “Image” button
  3. Select ”system” and “setCode” from the dropdown menus and click on the “file upload” toggle
    Step 3
  4. Click on the code field (where it says “click to select …”) which opens your OS file explorer. Find the runtime file containing the new code and open it
  5. Step 4
    If the code is correct, the preimage hash matches what was approved in the referendum (this was highlighted in red before the file was selected). This makes it impossible to change the code to upload after the referendum has been approved
  6. Steps 5 and 6
    Click the “Submit preimage” button
  7. Review the information
    1. NOTE: since the code change is a large file, the transaction fees shown could be close to 100 xx. However, since this referendum is imminent, the fee is refunded at the end of the transaction processing. Still, the funds still need to be available in the account to be able to submit the transaction
      Steps 7 and 8
  8. Sign and submit the transaction
  9. When the transaction is in a block it’s possible to see the transaction fee being Withdraw and then Deposited back into the account
  10. Step 9
    Step 10
    In the democracy dispatch queue, now it’s possible to see the exact proposal data instead of only the preimage