{"id":13604003,"url":"https://github.com/chevdor/subwasm","last_synced_at":"2025-05-16T18:10:40.149Z","repository":{"id":38446105,"uuid":"373303166","full_name":"chevdor/subwasm","owner":"chevdor","description":"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.","archived":false,"fork":false,"pushed_at":"2025-03-13T16:35:09.000Z","size":26573,"stargazers_count":67,"open_issues_count":12,"forks_count":27,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-10T09:40:18.149Z","etag":null,"topics":["blockchain","chevdor","cli","metadata","polkadot","runtime","rust","substrate","tool","wasm"],"latest_commit_sha":null,"homepage":"","language":"WebAssembly","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chevdor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-02T21:07:03.000Z","updated_at":"2025-04-15T10:50:02.000Z","dependencies_parsed_at":"2023-02-18T05:45:47.270Z","dependency_job_id":"3152d9d6-1253-4968-8395-c11c9300d84d","html_url":"https://github.com/chevdor/subwasm","commit_stats":{"total_commits":387,"total_committers":16,"mean_commits":24.1875,"dds":0.4547803617571059,"last_synced_commit":"0d63bc3a2a09d11c1a69185eb13301a4010b43c4"},"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chevdor%2Fsubwasm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chevdor%2Fsubwasm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chevdor%2Fsubwasm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chevdor%2Fsubwasm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chevdor","download_url":"https://codeload.github.com/chevdor/subwasm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254582907,"owners_count":22095518,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","chevdor","cli","metadata","polkadot","runtime","rust","substrate","tool","wasm"],"created_at":"2024-08-01T19:00:37.960Z","updated_at":"2025-05-16T18:10:40.098Z","avatar_url":"https://github.com/chevdor.png","language":"WebAssembly","funding_links":[],"categories":["Libraries","Tools"],"sub_categories":["Multisig Wallets"],"readme":"# subwasm\n\n\u003cfigure\u003e\n\u003cimg src=\"https://github.com/chevdor/subwasm/actions/workflows/quick-check.yml/badge.svg?branch=master\" alt=\"badge\" /\u003e\n\u003c/figure\u003e\n\n\u003cfigure\u003e\n\u003cimg src=\"resources/logos/Logo_256.png\" alt=\"Logo 256\" /\u003e\n\u003c/figure\u003e\n\n## Introduction\n\nThe metadata of a given runtime is a critical piece of information as it describes how one can interact with the runtime,\nwhat operations are possible and what are the signatures of the calls.\nIt contains the exhaustive list of all the features publicly exposed by the runtime.\n\nThis tool only works with Substrate-based runtimes which are `\u003e=V11`. For earlier versions, you’ll need to connect to an archive node.\n\nAny node can be queried to provide its current metadata. This can be displayed in json format for instance.\nThis 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.\n\n**`subwasm`** can work **offline** on wasm files without any node or internet connectivity.\n\n## Capabilities \u0026 features\n\n`subwasm` can:\n\n-   get the metadata from a a wasm file directly (no need for a node): command `get`\n\n-   show summary information and version of a runtime: commands `info` and `version`)\n\n-   diff between two runtime to help users spot changes and difference: command `diff`\n\n-   show the list of pallets and their content (calls, events, errors, storage, constants): command `show`\n\n-   analyze 2 runtimes to figure out whether they are compatible and if the `transaction_version` needs to be bumped: command `diff`\n\n-   compress and decompress a runtime WASM: commands `compress` and `decompress`\n\n-   get the latest metadata from a running node: command `get`\n\n-   fetch the latest runtime (wasm) from a running node: command `get`\n\n-   get runtime and metadata at any point of time using a Block hash as reference: command `get`\n\n-   do all of the above with an output for human or as json\n\n## Demos\n\n### Get a runtime\n\n\u003cfigure\u003e\n\u003cimg src=\"./scripts/demos/gif/demo-get.gif\" alt=\"demo get\" /\u003e\n\u003cfigcaption\u003esubwasm get\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n### info command\n\n\u003cfigure\u003e\n\u003cimg src=\"./scripts/demos/gif/demo-info.gif\" alt=\"demo info\" /\u003e\n\u003cfigcaption\u003esubwasm info\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n### show command\n\n\u003cfigure\u003e\n\u003cimg src=\"./scripts/demos/gif/demo-meta.gif\" alt=\"demo meta\" /\u003e\n\u003cfigcaption\u003esubwasm show\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n### meta command\n\n\u003cfigure\u003e\n\u003cimg src=\"./scripts/demos/gif/demo-meta.gif\" alt=\"demo meta\" /\u003e\n\u003cfigcaption\u003esubwasm meta\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n### diff command\n\n\u003cfigure\u003e\n\u003cimg src=\"./scripts/demos/gif/demo-diff.gif\" alt=\"demo diff\" /\u003e\n\u003cfigcaption\u003esubwasm diff\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n## Install\n\n### Using Cargo\n\n    cargo install --locked --git https://github.com/chevdor/subwasm --tag v0.16.1\n\n### Homebrew\n\nMacOS Homebrew users can use:\n\n    brew tap chevdor/subwasm https://github.com/chevdor/subwasm\n    brew install subwasm\n\n### Linux\n\n    wget https://github.com/chevdor/subwasm/releases/download/v0.16.1/subwasm_linux_amd64_v0.16.1 -O subwasm.deb\n    sudo dpkg -i subwasm.deb\n    subwasm --help\n\n## Usage\n\n### Command: --help\n\n    `subwasm` allows fetching, parsing and calling some methods on WASM runtimes of Substrate based chains\n\n    Usage: subwasm [OPTIONS] [COMMAND]\n\n    Commands:\n      get         Get/Download the runtime wasm from a running node through rpc\n      info        Shows information about a given runtime\n      version     Shows information about a given runtime\n      metadata    Returns the metadata of the given runtime in several format. You may also use the \"meta\" alias\n      show        Shows the a reduced view of the runtime\n      diff        Compare 2 runtimes after converting them to `[ReducedRuntime]`s\n      compress    Compress a given runtime wasm file. You will get an error if you try compressing a runtime that is already compressed\n      decompress  Decompress a given runtime wasm file. You may pass a runtime that is already uncompressed\n      help        Print this message or the help of the given subcommand(s)\n\n    Options:\n      -v, --version   Show the version\n      -j, --json      Output as json\n      -n, --no-color  Do not write color information to the output. This is recommended for scripts [env: NO_COLOR=]\n      -q, --quiet     Less output\n      -h, --help      Print help\n\n### Command: get\n\n    Get/Download the runtime wasm from a running node through rpc\n\n    Usage: subwasm get [OPTIONS] [RPC_URL]\n\n    Arguments:\n      [RPC_URL]\n              The node url including (mandatory) the port number. Example: ws://localhost:9944 or http://localhost:9933\n\n    Options:\n      -c, --chain \u003cCHAIN\u003e\n              Provide the name of a chain or an alias.\n\n              If you pass a valid --chain, --rpc_url will be ignored --chain local = http://localhost:9933\n\n      -b, --block \u003cBLOCK\u003e\n              The optional block where to fetch the runtime.\n\n              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.\n\n      -u, --url \u003cURL\u003e\n              Load the wasm from a URL (no node) such as \u003chttps://github.com/paritytech/polkadot/releases/download/v0.9.42/polkadot_runtime-v9420.compact.compressed.wasm\u003e\n\n      -g, --github \u003cGITHUB\u003e\n              Load the wasm from Github passing a string in the format `\u003cruntime\u003e@\u003cversion\u003e` such as `kusama@0.9.42`\n\n      -o, --output \u003cOUTPUT\u003e\n              You may specifiy the output filename where the runtime will be saved.\n\n              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.\n\n      -j, --json\n              Output as json\n\n      -n, --no-color\n              Do not write color information to the output. This is recommended for scripts\n\n              [env: NO_COLOR=]\n\n      -q, --quiet\n              Less output\n\n      -h, --help\n              Print help (see a summary with '-h')\n\n### Command: info\n\n    Shows information about a given runtime\n\n    Usage: subwasm info [OPTIONS] [FILE]\n\n    Arguments:\n      [FILE]\n              The wasm file to load. It can be a path on your local filesystem such /tmp/runtime.wasm\n\n              You may also fetch the runtime remotely, see `chain` and `url` flags.\n\n    Options:\n      -c, --chain \u003cCHAIN\u003e\n              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\",\n\n              NOTE: --chain local = http://localhost:9933\n\n      -b, --block \u003cBLOCK\u003e\n              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\n\n      -u, --url \u003cURL\u003e\n              Load the wasm from a URL (no node) such as \u003chttps://github.com/paritytech/polkadot/releases/download/v0.9.42/polkadot_runtime-v9420.compact.compressed.wasm\u003e\n\n      -g, --github \u003cGITHUB\u003e\n              Load the wasm from Github passing a string in the format `\u003cruntime\u003e@\u003cversion\u003e` such as `kusama@0.9.42`\n\n      -j, --json\n              Output as json\n\n      -n, --no-color\n              Do not write color information to the output. This is recommended for scripts\n\n              [env: NO_COLOR=]\n\n      -q, --quiet\n              Less output\n\n      -h, --help\n              Print help (see a summary with '-h')\n\nBy default, the ID for the Parachain pallet is expected to be `0x01` and the call ID for `authorize_upgrade` is expected to be `0x03`.\nThis default behavior can be overriden by setting the `PARACHAIN_PALLET_ID` to the ID of your parachain pallet and the\n`AUTHORIZE_UPGRADE_PREFIX` to the ID of your choice.\n\nDue 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.\nThis new behavior is supported by the `AUTHORIZE_UPGRADE_CHECK_VERSION` env variable, which, if set, is evaluated to\n`true` if its value is the string `\"true\"`, or `` false` `` otherwise. If not set, the behavior remains the same as pre-0.9.41.\n\nThe new `check_spec_version` parameter can be provided with the `AUTHORIZE_UPGRADE_CHECK_VERSION=true` or `AUTHORIZE_UPGRADE_CHECK_VERSION=false` variable, if needed.\n\n### Command: version\n\n    Shows information about a given runtime\n\n    Usage: subwasm version [OPTIONS] [FILE]\n\n    Arguments:\n      [FILE]\n              The wasm file to load. It can be a path on your local filesystem such /tmp/runtime.wasm\n\n              You may also fetch the runtime remotely, see `chain` and `url` flags.\n\n    Options:\n      -c, --chain \u003cCHAIN\u003e\n              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\",\n\n              NOTE: --chain local = http://localhost:9933\n\n      -b, --block \u003cBLOCK\u003e\n              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\n\n      -u, --url \u003cURL\u003e\n              Load the wasm from a URL (no node) such as \u003chttps://github.com/paritytech/polkadot/releases/download/v0.9.42/polkadot_runtime-v9420.compact.compressed.wasm\u003e\n\n      -g, --github \u003cGITHUB\u003e\n              Load the wasm from Github passing a string in the format `\u003cruntime\u003e@\u003cversion\u003e` such as `kusama@0.9.42`\n\n      -j, --json\n              Output as json\n\n      -n, --no-color\n              Do not write color information to the output. This is recommended for scripts\n\n              [env: NO_COLOR=]\n\n      -q, --quiet\n              Less output\n\n      -h, --help\n              Print help (see a summary with '-h')\n\n### Command: meta\n\n    Returns the metadata of the given runtime in several format. You may also use the \"meta\" alias.\n\n    If you want to see the content of a runtime, see the `show` sub-command.\n\n    Usage: subwasm metadata [OPTIONS] [FILE]\n\n    Arguments:\n      [FILE]\n              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\n\n    Options:\n      -c, --chain \u003cCHAIN\u003e\n              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\n\n      -u, --url \u003cURL\u003e\n              Load the wasm from a URL (no node) such as \u003chttps://github.com/paritytech/polkadot/releases/download/v0.9.42/polkadot_runtime-v9420.compact.compressed.wasm\u003e\n\n      -g, --github \u003cGITHUB\u003e\n              Load the wasm from Github passing a string in the format `\u003cruntime\u003e@\u003cversion\u003e` such as `kusama@0.9.42`\n\n      -b, --block \u003cBLOCK\u003e\n              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\n\n      -m, --module \u003cMODULE\u003e\n              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\n\n      -f, --format \u003cFORMAT\u003e\n              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\n\n              [default: human]\n\n      -o, --output \u003cOUTPUT\u003e\n              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\n\n      -j, --json\n              Output as json\n\n      -n, --no-color\n              Do not write color information to the output. This is recommended for scripts\n\n              [env: NO_COLOR=]\n\n      -q, --quiet\n              Less output\n\n      -h, --help\n              Print help (see a summary with '-h')\n\n### Command: show\n\n    Shows the a reduced view of the runtime.\n\n    A reduced view makes it much easier to understand the inner workings of a given runtime.\n\n    Usage: subwasm show [OPTIONS] [FILE]\n\n    Arguments:\n      [FILE]\n              The runtimwe to analyze\n\n    Options:\n          --chain \u003cCHAIN\u003e\n              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\n\n      -b, --block \u003cBLOCK\u003e\n              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\n\n      -u, --url \u003cURL\u003e\n              Load the wasm from a URL (no node) such as \u003chttps://github.com/paritytech/polkadot/releases/download/v0.9.42/polkadot_runtime-v9420.compact.compressed.wasm\u003e\n\n      -g, --github \u003cGITHUB\u003e\n              Load the wasm from Github passing a string in the format `\u003cruntime\u003e@\u003cversion\u003e` such as `kusama@0.9.42`\n\n      -p, --pallet \u003cPALLET\u003e\n              Show only information related to the provided pallet\n\n      -s, --summary\n              The runtime is shown as a table, listing all pallets with their IDs, the count of calls, events, errors, constants and storage items\n\n      -j, --json\n              Output as json\n\n      -n, --no-color\n              Do not write color information to the output. This is recommended for scripts\n\n              [env: NO_COLOR=]\n\n      -q, --quiet\n              Less output\n\n      -h, --help\n              Print help (see a summary with '-h')\n\n### Command: diff\n\n    Compare 2 runtimes after converting them to `[ReducedRuntime]`s.\n\n    You must pass exactly 2 runtimes.\n\n    Usage: subwasm diff [OPTIONS] \u003cRUNTIME_1\u003e \u003cRUNTIME_2\u003e\n\n    Arguments:\n      \u003cRUNTIME_1\u003e\n              Reference runtime\n\n      \u003cRUNTIME_2\u003e\n              Second runtime\n\n    Options:\n      -j, --json\n              Output as json\n\n      -n, --no-color\n              Do not write color information to the output. This is recommended for scripts\n\n              [env: NO_COLOR=]\n\n      -q, --quiet\n              Less output\n\n      -h, --help\n              Print help (see a summary with '-h')\n\n### Command: compress\n\n    Compress a given runtime wasm file. You will get an error if you try compressing a runtime that is already compressed\n\n    Usage: subwasm compress [OPTIONS] \u003cINPUT\u003e \u003cOUTPUT\u003e\n\n    Arguments:\n      \u003cINPUT\u003e   The path of uncompressed wasm file to load\n      \u003cOUTPUT\u003e  The path of the file where the compressed runtime will be stored\n\n    Options:\n      -j, --json      Output as json\n      -n, --no-color  Do not write color information to the output. This is recommended for scripts [env: NO_COLOR=]\n      -q, --quiet     Less output\n      -h, --help      Print help\n\n### Command: decompress\n\n    Decompress a given runtime wasm file. You may pass a runtime that is already uncompressed.\n\n    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.\n\n    Usage: subwasm decompress [OPTIONS] \u003cINPUT\u003e \u003cOUTPUT\u003e\n\n    Arguments:\n      \u003cINPUT\u003e\n              The path of the compressed or uncompressed wasm file to load\n\n      \u003cOUTPUT\u003e\n              The path of the file where the uncompressed runtime will be stored\n\n    Options:\n      -j, --json\n              Output as json\n\n      -n, --no-color\n              Do not write color information to the output. This is recommended for scripts\n\n              [env: NO_COLOR=]\n\n      -q, --quiet\n              Less output\n\n      -h, --help\n              Print help (see a summary with '-h')\n\n### Environment variables\n\nIn addition to the command line flags, you can also pass one of the following ENV variables:\n\n    # This is a sample .env file. It is not needed if you\n    # are using defaults if you want to use the default defined\n    # below.\n\n    # POLKADOT_HTTP=http://localhost:9933\n    # POLKADOT_WS=ws://localhost:9944\n    # PARACHAIN_PALLET_ID=0x01\n    # AUTHORIZE_UPGRADE_PREFIX=0x02\n\n    RUST_LOG=subwasm=debug,substrate_differ=trace\n\n## Sample runs\n\n**Fetch a runtime from a running node**\n\nWe will start by fetching the runtime from a node.\n\nPlease note that you will likely need to connect to an **archive** node to retrieve an older runtime (`\u003cV11`). 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.\n\n**Here we get the latest version of the runtime, the 3 commands do the same since they all use the default values:**\n\n    subwasm get\n    subwasm get http://localhost:9933\n    subwasm get http://localhost:9933 --output runtime_000.wasm\n\n**Here we get an older runtime, back when Polkadot was at block 20 !**\n\n    subwasm get brew tap chevdor/subwasm --block 0x4d6a0bca208b85d41833a7f35cf73d1ae6974f4bad8ab576e2c3f751d691fe6c\n\nBy 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.\n\n**Get quick check of a runtime**\n\n    # Show the runtime version and exit with status 0\n    subwasm info kusama-2030.wasm\n\n    # Provide a few explanations and exit with a status that is not 0\n    subwasm info tictactoe.wasm\n\n### Metadata JSON and jq tricks\n\n`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…​\n\n        subwasm --json meta runtime.wasm | jq 'del( .. | .documentation?, .default?, .value? )'\n\n## Alternatives\n\nHere is a list of other projects allowing to get the raw metadata through a rpc call:\n\n-   [PolkadotJS](https://github.com/polkadot-js/apps) from Jaco / Parity\n\n-   [subsee](https://github.com/ascjones/subsee) from Andrew / Parity\n\n-   [substrate-api-client](https://github.com/scs/substrate-api-client) from SCS\n\n-   [subxt](https://github.com/paritytech/substrate-subxt) from Parity\n\nAll those alternatives require a running node and access it via jsonrpc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchevdor%2Fsubwasm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchevdor%2Fsubwasm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchevdor%2Fsubwasm/lists"}