Difference between revisions of "Runtime Update Tutorial"
(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. | ||
== | == 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. | ||
== | == 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) | # Compile the binary (which compiles the runtime) | ||
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] | ||
== | ==Democracy Proposal== | ||
Steps: | Steps: | ||
# In the | #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 | #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 | # 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]] | ||
# | #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. | ||
== | ==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) | # Compile the binary (which compiles the runtime) | ||
# Use subwasm to get the system.setCode hash for the new runtime in compact compressed format (see above for example) | |||
# 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 | ||
== | ==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 | #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 | #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]] | ||
#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]] | |||
#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 | ##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]] | ||
#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:
- 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
- Commit changes to git, and create a tag following the Semantic versioning rules described above
- 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:
- In the wallet go to the Democracy
- Click the “Submit proposal” button
- Fill in the preimage hash with the system.setCode hash from the previous steps
- 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:
- Checkout the branch with the new runtime
- Compile the binary (which compiles the runtime)
- 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
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:
- In the wallet go to the Democracy/Dispatch
- Click the “Image” button
- Select ”system” and “setCode” from the dropdown menus and click on the “file upload” toggle
- 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
- 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
- Click the “Submit preimage” button
- 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
- 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
- In the democracy dispatch queue, now it’s possible to see the exact proposal data instead of only the preimage