Difference between revisions of "Runtime Update Tutorial"

From xx network wiki
Jump to navigation Jump to search
(Added tutorial to perform Runtime Update)
 
(explorer -> wallet)
 
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This wiki page describes how to perform a runtime update (code change) in the xx network blockchain.
This wiki page describes how to perform a runtime update (code change) in the xx network blockchain.


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


Line 16: Line 16:
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.
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 ==
== Runtime Compilation ==
Steps:
Steps:


Line 25: Line 25:
#* 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
#* 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
# Commit changes to git, and create a tag following the Semantic versioning rules described above
# Commit changes to git, and create a tag following the Semantic versioning rules described above
# Compile the binary (which compiles the runtime)<syntaxhighlight lang="shell">
# Compile the binary (which compiles the runtime)
make build
 
</syntaxhighlight>
# Use subwasm to get the system.setCode hash for the new runtime in compact compressed format. Example:<syntaxhighlight>
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:         https://www.ipfs.io/ipfs/QmWUZeyEYhinoQqxwAUQkFfmZug6MD6aK9vH9bHTfYrwWj
</syntaxhighlight>
# Create a release on git from the tag, uploading the compiled compact compressed runtime, chain binary and output of subwasm in the description




Line 47: Line 33:
Example: [https://github.com/xx-labs/xxchain/releases/tag/v0.2.3 v0.2.3]
Example: [https://github.com/xx-labs/xxchain/releases/tag/v0.2.3 v0.2.3]


== 3. Democracy Proposal ==
==Democracy Proposal==
Steps:
Steps:


# In the explorer go to the [https://explorer.xx.network/#/democracy Democracy]
#In the wallet go to the [https://wallet.xx.network/#/democracy Democracy]
# Click the “Submit proposal” button[[File:Screen Shot 2022-04-26 at 2.06.27 PM.png|thumb|Step 2]]
#Click the “Submit proposal” button[[File:Screen Shot 2022-04-26 at 2.06.27 PM.png|Step 2|center]]
# Fill in the preimage hash with the system.setCode hash from the previous steps[[File:Screen Shot 2022-04-26 at 2.07.48 PM.png|thumb|Steps 3 and 4]]
# Fill in the preimage hash with the system.setCode hash from the previous steps[[File:Screen Shot 2022-04-26 at 2.07.48 PM.png|Steps 3 and 4|center]]
# Sign and submit the transaction
#Click "Submit proposal" and then on the next screen sign and submit the transaction
 
 




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


== 4. Verifying Code Changes ==
==Verifying Code Changes==
While the referendum is ongoing, community members might wish to verify that the proposer was truthful.
While the referendum is ongoing, community members might wish to verify that the proposer was truthful.


Line 66: Line 54:


# Checkout the branch with the new runtime
# Checkout the branch with the new runtime
# Compile the binary (which compiles the runtime)<syntaxhighlight lang="shell">
# Compile the binary (which compiles the runtime)
make build
# Use subwasm to get the system.setCode hash for the new runtime in compact compressed format (see above for example)
</syntaxhighlight>
# Use subwasm to get the system.setCode hash for the new runtime in compact compressed format (see above for example).
# Verify that the proposal preimage hash that is on-chain matches the system.setCode hash output in the previous step
# Verify that the proposal preimage hash that is on-chain matches the system.setCode hash output in the previous step


== 5. Uploading Code ==
==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.
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.


Line 79: Line 65:
Steps:
Steps:


# In the explorer go to the [https://explorer.xx.network/#/democracy/dispatch Democracy/Dispatch]
#In the wallet go to the [https://wallet.xx.network/#/democracy/dispatch Democracy/Dispatch]
# Click the “Image” button
#Click the “Image” button
# Select ”system” and “setCode” from the dropdown menus and click on the “file upload” toggle[[File:Screen Shot 2022-04-26 at 2.19.45 PM.png|thumb|Step 3]]
#Select ”system” and “setCode” from the dropdown menus and click on the “file upload” toggle[[File:Screen Shot 2022-04-26 at 2.19.45 PM.png|Step 3|center]]
# 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
#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[[File:Screen Shot 2022-04-26 at 2.20.26 PM.png|Step 4|center]]
# [[File:Screen Shot 2022-04-26 at 2.20.26 PM.png|thumb|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
#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[[File:Screen Shot 2022-04-26 at 2.20.37 PM.png|Steps 5 and 6|center]]
# [[File:Screen Shot 2022-04-26 at 2.20.37 PM.png|thumb|Steps 5 and 6]]Click the “Submit preimage” button
#Click the “Submit preimage” button
# Review the information
#Review the information  
## 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  [[File:Screen Shot 2022-04-26 at 2.20.49 PM.png|thumb|Steps 7 and 8]]
##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  [[File:Screen Shot 2022-04-26 at 2.20.49 PM.png|Steps 7 and 8|center]]
# Sign and submit the transaction
#Sign and submit the transaction
# When the transaction is in a block it’s possible to see the transaction fee being Withdraw and then Deposited back into the account
# When the transaction is in a block it’s possible to see the transaction fee being Withdraw and then Deposited back into the account[[File:Screen Shot 2022-04-26 at 2.21.51 PM.png|Step 9|center]]
# [[File:Screen Shot 2022-04-26 at 2.21.51 PM.png|thumb|Step 9]][[File:Screen Shot 2022-04-26 at 2.21.07 PM.png|thumb|Step 10]]In the democracy dispatch queue, now it’s possible to see the exact proposal data instead of only the preimage
#In the democracy dispatch queue, now it’s possible to see the exact proposal data instead of only the preimage[[File:Screen Shot 2022-04-26 at 2.21.07 PM.png|Step 10|center]]

Latest revision as of 23:29, 5 August 2022

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

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.

Runtime Compilation

Steps:

  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)


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

Democracy Proposal

Steps:

  1. In the wallet 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. Click "Submit proposal" and then on the next screen 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.

Verifying Code Changes

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

Steps:

  1. Checkout the branch with the new runtime
  2. Compile the binary (which compiles the runtime)
  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

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.

Steps:

  1. In the wallet 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
    Step 4
  5. 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
    Steps 5 and 6
  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
    Step 9
  10. In the democracy dispatch queue, now it’s possible to see the exact proposal data instead of only the preimage
    Step 10