The metadata of a given runtime is a critical piece of information as it describes how one can interact with the runtime, what operations are possible and what are the signatures of the calls. It contains the exhaustive list of all the features publicly exposed by the runtime.
This tool only works with Substrate-based runtimes which are >=V11
. For earlier versions, you’ll need to connect to an archive node.
Any node can be queried to provide its current metadata. This can be displayed in json format for instance. This is a great way to have a peek at what the runtime can do.
subwasm
allows:
-
getting the latest metadata from a running node
-
getting the latest runtime (wasm) from a running node
-
getting runtime and metadata at any point of time using a Block hash as reference
-
getting the metadata from a a wasm file without any node
-
extracting information (those not requiring storage) from a runtime as wasm file
-
(de)compress a given runtime WASM
cargo install --locked --git https://github.com/chevdor/subwasm --tag v0.16.1
MacOS Homebrew users can use:
brew tap chevdor/subwasm https://github.com/chevdor/subwasm
brew install subwasm
wget https://github.com/chevdor/subwasm/releases/download/v0.16.1/subwasm_linux_amd64_v0.16.1 -O subwasm.deb
sudo dpkg -i subwasm.deb
subwasm --help
subwasm 0.16.1
chevdor <chevdor@gmail.com>:Wilfried Kopp <wilfried@parity.io
You can find all available commands below
USAGE:
subwasm [FLAGS] <SUBCOMMAND>
FLAGS:
-h, --help Print help information
-j, --json Output as json
-q, --quiet Less output
-V, --version Print version information
SUBCOMMANDS:
compress Compress a given runtime wasm file. You will get an error if you try
compressing a runtime that is already compressed
decompress Decompress a given runtime wasm file. You may pass a runtime that is
uncompressed already. In that case, you will get the same content as output.
This is useful if you want to decompress "no matter what" and don't really
know whether the input will be compressed or not
diff Compare 2 runtimes
get Get/Download the runtime wasm from a running node through rpc
help Print this message or the help of the given subcommand(s)
info The `info` command returns summarized information about a runtime
metadata Returns the metadata as a json object. You may also use the "meta" alias
subwasm-get 0.16.1
chevdor <chevdor@gmail.com>:Wilfried Kopp <wilfried@parity.io
Get/Download the runtime wasm from a running node through rpc
USAGE:
subwasm get [FLAGS] [OPTIONS] [URL]
ARGS:
<URL> The node url including (mandatory) the port number. Example: ws://localhost:9944 or
http://localhost:9933 [default: http://localhost:9933]
FLAGS:
-h, --help Print help information
-j, --json Output as json
-V, --version Print version information
OPTIONS:
-b, --block <BLOCK> The optional block where to fetch the runtime. That allows fetching
older runtimes but you will need to connect to archive nodes.
Currently, you must pass a block hash. Passing the block numbers is not
supported
--chain <CHAIN> Provide the name of a chain and a random url amongst a list of known
nodes will be used. If you pass a valid --chain, --url will be ignored
--chain local = http://localhost:9933
-o, --output <OUTPUT> You may specifiy the output filename where the runtime will be saved.
If not provided, we will figure out an appropriate default name based
on a counter: runtime_NNN.wasm where NNN is incrementing to make sure
you do not override previous runtime. If you specify an existing file
as output, it will be overwritten
subwasm-info 0.16.1
chevdor <chevdor@gmail.com>:Wilfried Kopp <wilfried@parity.io
The `info` command returns summarized information about a runtime
USAGE:
subwasm info [FLAGS] [OPTIONS] [SOURCE]
ARGS:
<SOURCE> The wasm file to load. It can be a path on your local filesystem such as
/tmp/runtime.wasm or a node url such as http://localhost:9933 or
ws://localhost:9944 [default: runtime_000.wasm]
FLAGS:
-h, --help Print help information
-j, --json Output as json
-V, --version Print version information
OPTIONS:
-b, --block <BLOCK> The optional block where to fetch the runtime. That allows fetching older
runtimes but you will need to connect to archive nodes. Currently, you
must pass a block hash. Passing the block numbers is not supported
--chain <CHAIN> Provide the name of a chain and a random url amongst a list of known
nodes will be used. If you pass a valid --chain, --url will be ignored
--chain local = http://localhost:9933
subwasm-metadata 0.16.1
chevdor <chevdor@gmail.com>:Wilfried Kopp <wilfried@parity.io
Returns the metadata as a json object. You may also use the "meta" alias
USAGE:
subwasm metadata [FLAGS] [OPTIONS] [SOURCE]
ARGS:
<SOURCE> The wasm file to load. It can be a path on your local filesystem such as
/tmp/runtime.wasm or a node url such as http://localhost:9933 or
ws://localhost:9944 [default: runtime_000.wasm]
FLAGS:
-h, --help Print help information
-j, --json Output as json
-V, --version Print version information
OPTIONS:
-b, --block <BLOCK> The optional block where to fetch the runtime. That allows fetching
older runtimes but you will need to connect to archive nodes.
Currently, you must pass a block hash. Passing the block numbers is not
supported
--chain <CHAIN> Provide the name of a chain and a random url amongst a list of known
nodes will be used. If you pass a valid --chain, --url will be ignored
--chain local = http://localhost:9933
-m, --module <MODULE> Without this flag, the metadata command display the list of all
modules. Using this flag, you will only see the module of your choice
and a few details about it
subwasm-diff 0.16.1
chevdor <chevdor@gmail.com>:Wilfried Kopp <wilfried@parity.io
Compare 2 runtimes
USAGE:
subwasm diff [FLAGS] [OPTIONS] [ARGS]
ARGS:
<SRC_A> The first source [default: runtime_000.wasm]
<SRC_B> The second source [default: runtime_001.wasm]
FLAGS:
-h, --help Print help information
-j, --json Output as json
-V, --version Print version information
OPTIONS:
-a, --chain-a <CHAIN_A> Provide the name of a chain and a random url amongst a list of known
nodes will be used. If you pass a valid --chain, --url will be
ignored --chain local = http://localhost:9933
-b, --chain-b <CHAIN_B> Provide the name of a chain and a random url amongst a list of known
nodes will be used. If you pass a valid --chain, --url will be
ignored --chain local = http://localhost:9933
subwasm-compress 0.16.1
chevdor <chevdor@gmail.com>:Wilfried Kopp <wilfried@parity.io
Compress a given runtime wasm file. You will get an error if you try compressing a runtime that is
already compressed
USAGE:
subwasm compress [FLAGS] <INPUT> <OUTPUT>
ARGS:
<INPUT> The path of uncompressed wasm file to load
<OUTPUT> The path of the file where the compressed runtime will be stored
FLAGS:
-h, --help Print help information
-j, --json Output as json
-V, --version Print version information
subwasm-decompress 0.16.1
chevdor <chevdor@gmail.com>:Wilfried Kopp <wilfried@parity.io
Decompress a given runtime wasm file. You may pass a runtime that is uncompressed already. In that
case, you will get the same content as output. This is useful if you want to decompress "no matter
what" and don't really know whether the input will be compressed or not
USAGE:
subwasm decompress [FLAGS] <INPUT> <OUTPUT>
ARGS:
<INPUT> The path of the compressed or uncompressed wasm file to load
<OUTPUT> The path of the file where the uncompressed runtime will be stored
FLAGS:
-h, --help Print help information
-j, --json Output as json
-V, --version Print version information
Fetch a runtime from a running node
We will start by fetching the runtime from a node.
Please note that you will likely need to connect to an archive node to retrieve an older runtime (<V11
). A runtime takes around 2MB of storage on-chain and thus, older versions are pruned and will no longer be accessible if you are connecting to a non-archive node.
Here we get the latest version of the runtime, the 3 commands do the same since they all use the default values:
subwasm get
subwasm get --url http://localhost:9933
subwasm get --url http://localhost:9933 --output runtime_000.wasm
Here we get an older runtime, back when Polkadot was at block 20 !
subwasm get brew tap chevdor/subwasm --block 0x4d6a0bca208b85d41833a7f35cf73d1ae6974f4bad8ab576e2c3f751d691fe6c
By default, your runtime will be saved as runtime_000.wasm
. Running this command again will increase the counter so we you don’t lose your previous runtime. You may also use the --output
flag to provide the destination and filename of your choice. Beware, in this case, there will be no incremented counter.
Get quick check of a runtime
# Show the runtime version and exit with status 0
subwasm info --input kusama-2030.wasm
# Provide a few explanations and exit with a status that is not 0
subwasm info --input tictactoe.wasm
jq
can be used to reprocess the json output. For instance, removing all the documentation from the metadata makes it significantly smaller. The example below shows how to remove documentation
, value
and default
making it much easier on the eyes for human parsing…
subwasm --json meta runtime.wasm | jq 'del( .. | .documentation?, .default?, .value? )'
Here is a list of other projects allowing to get the raw metadata through a rpc call:
-
PolkadotJS from Jaco / Parity
-
subsee from Andrew / Parity
-
substrate-api-client from SCS
-
subxt from Parity
All those alternatives require a running node and access it via jsonrpc.