Decentralization of blockchains has advantages and disadvantages, one of the major advantages is that there is no single unit which has complete power over a system. From the other side, a disadvantage is that in the environment without centralized control, upgrading is hard due to the need for coordinating so many nodes at one time. One of the well known solutions of upgrading blockchains is the so-called "hard fork", however this has many potential vectors of attack and is hard to coordinate.
The newest solution for upgrading decentralized systems based on the Substrate framework is called
runtime-upgrade. The solution works smoothly and in this tutorial, I will show you how you can easily upgrade your Substrate based chain. We will examine how adaptability is implemented in the Substrate framework.
To successfully follow this tutorial, you should have a basic knowledge about the Rust programming language and Polkadot's Substrate framework.
During the tutorial we will progress through these steps:
- Build the simplest Substrate based blockchain
- Run the Substrate chain locally (on your own hardware)
- Add a new feature to the runtime
- Build a WebAssembly (WASM) file
- Verify the upgrade by checking the version
Upgrading the runtime state transition function consists of the following steps:
- Bump (increase) the spec_version
- Build the WASM file:
WASM_TARGET_DIRECTORY="$(pwd)" cargo build
- Use the
sudocommand to start the runtime
Checkout the master branch of https://github.com/TomaszWaszczyk/substrate-runtime-upgrade-tutorial, then execute the command make init and after around 10 minutes (depends on performance of your machine) you should see something like:
Access the front-end of the local node via: https://polkadot.js.org/apps/#/extrinsics?rpc=ws://127.0.0.1:9944
We can see that the kitties pallet has only a create() function, it is our current state transition function in the runtime. To demonstrate how adaptable Substrate based blockchains are, we can add a new feature - the breed() function.
Before making an upgrade, spec_version would be 1. Now that we are making an upgrade, we have incremented the field, so it will now be 2 as shown below:
Our upgrade will add a new function to the kitties pallet called
breed, here is the implementation:
After adding this breed function to the kitties pallet, we need to build the WASM file.
Here is a link to the whole new implementation: https://github.com/TomaszWaszczyk/substrate-runtime-upgrade-tutorial/blob/after-runtime-upgrade/pallets/kitties/src/lib.rs
After performing the upgrade, we expect that the kitties pallet will contain the new
breedfunction without needing to restart the running Substrate node. Real adaptability of the blockchain!
Run the terminal command
WASM_TARGET_DIRECTORY="$(pwd)" cargo buildin order to build the runtime WASM file.
After a successful build, we expect to have a new file in the current directory:
We have a running Substrate node with version 1 and want to upgrade the runtime into version 2. Proof of a successful upgrade will be our freshly added breed function. Let's check, using the front-end.
To perform the upgrade, go to the Developer tab, then select Sudo. Make sure that you have selected the
setCode(code), check in
file uploadand select the freshly created WASM file made in the previous step:
node_template_runtime.wasm. Next, check the with weight override and in the field unchecked weight for this call type a value like 100, for example. To confirm the upgrade, click on Submit Sudo Unchecked.
After successfully upgrade you should see updated
spec_versionand have access to our new function:
In the screenshot above, we can see the result of a successful upgrade. Notice that
spec_versionhas been incremented to 2 (where it says "node-template/2").
You may encounter an error while building, such as the one shown below. This means that you do not have the proper version of Rust installed.
Solution - configure and make default proper version of Rust language on your machine
You need to install and set as default the specified nightly build of Rust:
rustup update nightly-2020-08-23Rust language
rustup update nightly-2020-08-23
- Make default version
rustup default nightly-2020-08-23-x86_64-unknown-linux-gnu
- Checking of default version
rustup showand in the output you should see following output:
Congratulations! You have already understood the importance of how adaptability is important in decentralized blockchains and how the feature is implemented in Substrate framework.
During reading the tutorial you have learnt basics of Rust language, how to compile Substrate based chain and how to generate and then upload wasm file in order to deliver new feature for the chain.
The tutorial was created by Tomasz Waszczyk. In case any questions, you can reach out to Tomasz on Figment Forum and on Github for help or explaining doubts pertaining to Polkadot/Kusama ecosystem and this guide.
When you have completed the tutorial, you are ready to learn more about Forkless upgrading runtime tutorial by Jimmy Chu.