https://github.com/chevdor/subwasm

Subwasm is a cli utility to look inside a Substrate WASM Runtime. It can inspect and compare the metadata of Substrate based runtimes such as Polkadot or Kusama.
https://github.com/chevdor/subwasm

blockchain chevdor cli metadata polkadot runtime rust substrate tool wasm

Last synced: 28 days ago
JSON representation

Subwasm is a cli utility to look inside a Substrate WASM Runtime. It can inspect and compare the metadata of Substrate based runtimes such as Polkadot or Kusama.

• Host: GitHub
• URL: https://github.com/chevdor/subwasm
• Owner: chevdor
• License: mit
• Created: 2021-06-02T21:07:03.000Z (over 3 years ago)
• Default Branch: master
• Last Pushed: 2024-03-27T09:17:35.000Z (9 months ago)
• Last Synced: 2024-04-02T11:22:37.071Z (8 months ago)
• Topics: blockchain, chevdor, cli, metadata, polkadot, runtime, rust, substrate, tool, wasm
• Language: WebAssembly
• Homepage:
• Size: 23.6 MB
• Stars: 58
• Watchers: 5
• Forks: 21
• Open Issues: 11
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-dot - Subwasm - Subwasm is a cli utility inside a Substrate WASM Runtime. It can inspect and compare (Libraries / Multisig Wallets)
• awesome-substrate - `subwasm` - CLI to inspect a runtime WASM blob offline. It shows information, metadata and can compare runtimes. It can also help you fetch a runtime directly from a node. (Tools)
• awesome-substrate - `subwasm` - CLI to inspect a runtime WASM blob offline. It shows information, metadata and can compare runtimes. It can also help you fetch a runtime directly from a node. (Tools)

README

        
# subwasm





## Introduction

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. You may however want to inspect a runtime that was not deployed yet to any node.

**`subwasm`** can work **offline** on wasm files without any node or internet connectivity.

## Capabilities & features

`subwasm` can:

-   get the metadata from a a wasm file directly (no need for a node): command `get`

-   show summary information and version of a runtime: commands `info` and `version`)

-   diff between two runtime to help users spot changes and difference: command `diff`

-   show the list of pallets and their content (calls, events, errors, storage, constants): command `show`

-   analyze 2 runtimes to figure out whether they are compatible and if the `transaction_version` needs to be bumped: command `diff`

-   compress and decompress a runtime WASM: commands `compress` and `decompress`

-   get the latest metadata from a running node: command `get`

-   fetch the latest runtime (wasm) from a running node: command `get`

-   get runtime and metadata at any point of time using a Block hash as reference: command `get`

-   do all of the above with an output for human or as json

## Demos

### Get a runtime



subwasm get

### info command



subwasm info

### show command



subwasm show

### meta command



subwasm meta

### diff command



subwasm diff

## Install

### Using Cargo

    cargo install --locked --git https://github.com/chevdor/subwasm --tag v0.16.1

### Homebrew

MacOS Homebrew users can use:

    brew tap chevdor/subwasm https://github.com/chevdor/subwasm

    brew install subwasm

### Linux

    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

## Usage

### Command: --help

    `subwasm` allows fetching, parsing and calling some methods on WASM runtimes of Substrate based chains

    Usage: subwasm [OPTIONS] [COMMAND]

    Commands:

      get         Get/Download the runtime wasm from a running node through rpc

      info        Shows information about a given runtime

      version     Shows information about a given runtime

      metadata    Returns the metadata of the given runtime in several format. You may also use the "meta" alias

      show        Shows the a reduced view of the runtime

      diff        Compare 2 runtimes after converting them to `[ReducedRuntime]`s

      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 already uncompressed

      help        Print this message or the help of the given subcommand(s)

    Options:

      -v, --version   Show the version

      -j, --json      Output as json

      -n, --no-color  Do not write color information to the output. This is recommended for scripts [env: NO_COLOR=]

      -q, --quiet     Less output

      -h, --help      Print help

### Command: get

    Get/Download the runtime wasm from a running node through rpc

    Usage: subwasm get [OPTIONS] [RPC_URL]

    Arguments:

      [RPC_URL]

              The node url including (mandatory) the port number. Example: ws://localhost:9944 or http://localhost:9933

    Options:

      -c, --chain 

              Provide the name of a chain or an alias.

              If you pass a valid --chain, --rpc_url will be ignored --chain local = http://localhost:9933

      -b, --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.

      -u, --url 

              Load the wasm from a URL (no node) such as 

      -g, --github 

              Load the wasm from Github passing a string in the format `@` such as `[email protected]`

      -o, --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.

      -j, --json

              Output as json

      -n, --no-color

              Do not write color information to the output. This is recommended for scripts

              [env: NO_COLOR=]

      -q, --quiet

              Less output

      -h, --help

              Print help (see a summary with '-h')

### Command: info

    Shows information about a given runtime

    Usage: subwasm info [OPTIONS] [FILE]

    Arguments:

      [FILE]

              The wasm file to load. It can be a path on your local filesystem such /tmp/runtime.wasm

              You may also fetch the runtime remotely, see `chain` and `url` flags.

    Options:

      -c, --chain 

              Load the wasm from an RPC node url such as http://localhost:9933 or ws://localhost:9944, a node alias such as "polkadot" or "dot",

              NOTE: --chain local = http://localhost:9933

      -b, --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

      -u, --url 

              Load the wasm from a URL (no node) such as 

      -g, --github 

              Load the wasm from Github passing a string in the format `@` such as `[email protected]`

      -j, --json

              Output as json

      -n, --no-color

              Do not write color information to the output. This is recommended for scripts

              [env: NO_COLOR=]

      -q, --quiet

              Less output

      -h, --help

              Print help (see a summary with '-h')

By default, the ID for the Parachain pallet is expected to be `0x01` and the call ID for `authorize_upgrade` is expected to be `0x03`.

This default behavior can be overriden by setting the `PARACHAIN_PALLET_ID` to the ID of your parachain pallet and the

`AUTHORIZE_UPGRADE_PREFIX` to the ID of your choice.

Due to a [breaking change to the `parachainSystem::authorizeUpgrade` extrinsic](https://github.com/paritytech/cumulus/commit/3249186fe643f62ca95769e2217f858dde803ab6), a new `checkVersion` boolean flag is required on chains running on Cumulus v0.9.41 and above.

This new behavior is supported by the `AUTHORIZE_UPGRADE_CHECK_VERSION` env variable, which, if set, is evaluated to

`true` if its value is the string `"true"`, or `` false` `` otherwise. If not set, the behavior remains the same as pre-0.9.41.

The new `check_spec_version` parameter can be provided with the `AUTHORIZE_UPGRADE_CHECK_VERSION=true` or `AUTHORIZE_UPGRADE_CHECK_VERSION=false` variable, if needed.

### Command: version

    Shows information about a given runtime

    Usage: subwasm version [OPTIONS] [FILE]

    Arguments:

      [FILE]

              The wasm file to load. It can be a path on your local filesystem such /tmp/runtime.wasm

              You may also fetch the runtime remotely, see `chain` and `url` flags.

    Options:

      -c, --chain 

              Load the wasm from an RPC node url such as http://localhost:9933 or ws://localhost:9944, a node alias such as "polkadot" or "dot",

              NOTE: --chain local = http://localhost:9933

      -b, --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

      -u, --url 

              Load the wasm from a URL (no node) such as 

      -g, --github 

              Load the wasm from Github passing a string in the format `@` such as `[email protected]`

      -j, --json

              Output as json

      -n, --no-color

              Do not write color information to the output. This is recommended for scripts

              [env: NO_COLOR=]

      -q, --quiet

              Less output

      -h, --help

              Print help (see a summary with '-h')

### Command: meta

    Returns the metadata of the given runtime in several format. You may also use the "meta" alias.

    If you want to see the content of a runtime, see the `show` sub-command.

    Usage: subwasm metadata [OPTIONS] [FILE]

    Arguments:

      [FILE]

              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

    Options:

      -c, --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

      -u, --url 

              Load the wasm from a URL (no node) such as 

      -g, --github 

              Load the wasm from Github passing a string in the format `@` such as `[email protected]`

      -b, --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

      -m, --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

      -f, --format 

              You may specify the output format. One of "human", "scale", "json", "json+scale", "hex+scale". If you use the default: human, you may want to check out the "show_reduced" command instead

              [default: human]

      -o, --output 

              You may specifiy the output filename where the metadata will be saved. Alternatively, you may use `auto` and an appropriate name will be generated according to the `format` your chose

      -j, --json

              Output as json

      -n, --no-color

              Do not write color information to the output. This is recommended for scripts

              [env: NO_COLOR=]

      -q, --quiet

              Less output

      -h, --help

              Print help (see a summary with '-h')

### Command: show

    Shows the a reduced view of the runtime.

    A reduced view makes it much easier to understand the inner workings of a given runtime.

    Usage: subwasm show [OPTIONS] [FILE]

    Arguments:

      [FILE]

              The runtimwe to analyze

    Options:

          --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

      -b, --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

      -u, --url 

              Load the wasm from a URL (no node) such as 

      -g, --github 

              Load the wasm from Github passing a string in the format `@` such as `[email protected]`

      -p, --pallet 

              Show only information related to the provided pallet

      -s, --summary

              The runtime is shown as a table, listing all pallets with their IDs, the count of calls, events, errors, constants and storage items

      -j, --json

              Output as json

      -n, --no-color

              Do not write color information to the output. This is recommended for scripts

              [env: NO_COLOR=]

      -q, --quiet

              Less output

      -h, --help

              Print help (see a summary with '-h')

### Command: diff

    Compare 2 runtimes after converting them to `[ReducedRuntime]`s.

    You must pass exactly 2 runtimes.

    Usage: subwasm diff [OPTIONS]  

    Arguments:

      

              Reference runtime

      

              Second runtime

    Options:

      -j, --json

              Output as json

      -n, --no-color

              Do not write color information to the output. This is recommended for scripts

              [env: NO_COLOR=]

      -q, --quiet

              Less output

      -h, --help

              Print help (see a summary with '-h')

### Command: compress

    Compress a given runtime wasm file. You will get an error if you try compressing a runtime that is already compressed

    Usage: subwasm compress [OPTIONS]  

    Arguments:

         The path of uncompressed wasm file to load

        The path of the file where the compressed runtime will be stored

    Options:

      -j, --json      Output as json

      -n, --no-color  Do not write color information to the output. This is recommended for scripts [env: NO_COLOR=]

      -q, --quiet     Less output

      -h, --help      Print help

### Command: decompress

    Decompress a given runtime wasm file. You may pass a runtime that is already uncompressed.

    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 [OPTIONS]  

    Arguments:

      

              The path of the compressed or uncompressed wasm file to load

      

              The path of the file where the uncompressed runtime will be stored

    Options:

      -j, --json

              Output as json

      -n, --no-color

              Do not write color information to the output. This is recommended for scripts

              [env: NO_COLOR=]

      -q, --quiet

              Less output

      -h, --help

              Print help (see a summary with '-h')

### Environment variables

In addition to the command line flags, you can also pass one of the following ENV variables:

    # This is a sample .env file. It is not needed if you

    # are using defaults if you want to use the default defined

    # below.

    # POLKADOT_HTTP=http://localhost:9933

    # POLKADOT_WS=ws://localhost:9944

    # PARACHAIN_PALLET_ID=0x01

    # AUTHORIZE_UPGRADE_PREFIX=0x02

    RUST_LOG=subwasm=debug,substrate_differ=trace

## Sample runs

**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 (`