SRTOOL now showing Substrate proposal hashes

Jan 14, 2020 6 min read

I introduced srtool in a previous article. While the first implementation filled a gap and allowed for the first time users to verify substrate runtime wasm blobs, there was still work to do to improve the user’s experience.

1. Current verification process

Up to now, the verification process looked like:

a runtime dev works on some changes
he builds the new runtime locally, preferably using srtool in order to get the SHA256 of the new wasm blob right away
he deploys the proposal on chain
the wasm blob is now publicly visible
the dev shares his commit ref / tag / branch
anyone wanting to verify goes to this commit ref and uses srtool to build the runtime and get the SHA256
the resulting SHA256 can be compared with the one shared by the new runtime author

Most people did the checks mentioned above, but one important part was missing: taking the wasm blob on-chain, calculating the SHA256 and comparing with the previous. Some verifiers may have done it but no such information was ever really shared.

This last step is not complicated but requires quite some extra work from the users so no one is to blame for not going through the troubles!

This pain is now gone with the new version of srtool!

2. Getting the latest srtool version

Getting the latest version of srtool is rather simple and can be brought down to the following command:

docker rmi chevdor/srtool:nightly-2019-12-07

This command deletes the srtool docker image from your machine. The next srtool call will fetch the fresher version.

You may want to trigger this update while on a good network because there are a few MB to download. You can easily trigger this initial download with the following command:

srtool help

After a bit of network activity, you will have the shiniest version of srtool on your machine.

Congratulations! You have now everything you need to verify yourself candidate versions of a substrate runtime. You can now help growing the confidence that a new runtime is legit. You can also help catching malicious attempts to corrupt the network though malicious runtime upgrade attempts.

3. Usage

Now what?

Using the new version is 100% the same than using the former one. The only difference will be the output that srtool produces.

4. New verification process

The new verification process is simpler.

4.1. Runtime developer

Fist of all, nothing changes for the runtime developer. He makes a new version and submit the proposal on chain. New runtime proposal may/should come with an Upgrade Bulletin such as this one.

While the format may vary, the content is rather similar and split into 2 categories:

critical information:

a commit ref allowing anyone to check the right piece of code
some reference to the on-chain proposal showing the proposal hash
the srtool output. Whether showing the --json output or the more human readable version, srtool shows a few critical information such as the ructc compiler version that was used.

nice to have:

the new runtime version: good to know but not critical to the verification process
some human readable explanation of the change: this is definitely not mandatory but really helpful to understand the intent of the change(s)
the proposal hash makes things easier when provided but users should anyway check-out the data that is on-chain

4.2. Verifier

Anyone wanting to verify a new runtime proposal can proceed with the following steps:

check out the proposal on chain and take note of the proposal hash. Such a hash looks like 0x5931690e71e9d3d9f04a43d8c15e45e0968e563858dd87ad6485b2368a286a8f
go into their local polkadot repository folder
jump to the right version of the code (git checkout -b <runtime_version> <commit_ref>)
run srtool as shown below
compared the Proposal Hash from srtool with the proposal hash shown onchain

Here is a sample srtool call and its output:

$ export PACKAGE=kusama-runtime; srtool build
🧰 Substrate Runtime Toolbox 🧰
        - by Chevdor -
🏗  Building kusama-runtime as release using rustc 1.41.0-nightly (ae1b871cc 2019-12-06)
⏳ That can take a little while, be patient... subsequent builds will be faster.
   Since you have to wait a little, you may want to learn more about Substrate runtimes:
   https://substrate.dev/docs/en/runtime/architecture-of-a-runtime
    Finished release [optimized] target(s) in 51.60s
  (... more below ...)

Note	Notice that we explicitly defined the PACKAGE to `kusama-runtime` before calling `srtool`. This is not mandatory if the variable is already set but you may want to do it anyway to ensure no surprises…

It produces the following output:

We can spot a few new things:

the runtime PACKAGE is displayed to avoid mistakenly verifying the wrong runtime :) Each known runtime will also show up with a different (Oh! So Beautiful!) color
the PROPOSAL hash is now available, it is highlighted in yellow. This hash should match the proposal hash that you see on-chain for a successful validation.

Here is how one would verify the Polkadot runtime instead of the Kusama runtime as shown above:

$ export PACKAGE=polkadot-runtime; srtool build
🧰 Substrate Runtime Toolbox 🧰
        - by Chevdor -
🏗  Building polkadot-runtime as release using rustc 1.41.0-nightly (ae1b871cc 2019-12-06)
⏳ That can take a little while, be patient... subsequent builds will be faster.
   Since you have to wait a little, you may want to learn more about Substrate runtimes:
   https://substrate.dev/docs/en/runtime/architecture-of-a-runtime
    Finished release [optimized] target(s) in 51.60s

5. Automatic verification

If you are devops or want to have srtool included in your toolchain, you probably want to use the --json flag as shown below:

export PACKAGE=kusama-runtime; srtool build --json

This will produce a json object:

{
  "gen": "srtool",
  "rustc": "rustc 1.41.0-nightly (ae1b871cc 2019-12-06)",
  "wasm": "./target/srtool/release/wbuild/kusama-runtime/kusama_runtime.compact.wasm",
  "size": "1205052",
  "pkg": "kusama-runtime",
  "prop": "0x5931690e71e9d3d9f04a43d8c15e45e0968e563858dd87ad6485b2368a286a8f",
  "sha256": "d93126c814f8366b651e425e34390212a98f8e77a8b73f9e1d2b07fc229a25f1",
  "tmsp": "2020-01-14T10:23:18Z"
}

6. What if the proposal hash does not match ?

There are several reasons the proposal hash you get from srtool would not match the proposal hash that shows up on-chain. Here is a little check-list you can go though to ensure you did not make a mistake.

Did you build the right runtime? Check with echo $PACKAGE
Did you build the right version? Check with git rev-parse HEAD
Did you use the right srtool tag? Check with docker images | grep srtool
Did you build the release version of the runtime? srtool does it right by default, ensure you did not change to debug by passing extra parameters
Is your srtool definition the one you expect? Check with type srtool

If all of the above is correct but you still get a different proposal hash, you may have spotted a malicious attempt and show expose your findings on Riot and you will get some guidance from this Riot Room.

Wilfried Kopp aka. Chevdor

Building Blockchains & Decentralized Solutions

I build decentralized solutions and tooling to support them. I am developing Smart Contracts and dApps on Ethereum and developing tooling for Substrate (Polkadot & Kusama). I love Rust! I am using Docker extensively and above all I like efficiency. GPG Fingerprint 15AF C574 D3F9 F1C3 CCDD E31E 2DCE C4DC 506E 6475.

SRTOOL now showing Substrate proposal hashes

Building Blockchains & Decentralized Solutions

Related