subxt
Last updated
Last updated
The library enables you to submit transactions to a Substrate node through remote procedure calls. Before you use the subxt library, you can use the standalone subxt command-line interface to download the metadata for the Substrate node you want to use as the target for submitting transactions. The subxt-cli tool enables you to perform two key tasks that are critical to using the subxt library:
You can use the subxt-cli tool to download the metadata from any target Substrate node.
You can use the subxt-cli tool to generate the runtime API code from the metadata from any target Substrate node.
You can use the subxt library and subxt-cli tool for any node that uses metadata v14 and later. For examples of how to use the subxt library, see the folder.
To install subxt-cli:
Open a terminal shell, if necessary.
Verify that you have the Rust compiler and toolchain, if necessary.
Download the required packages with the following command: cargo install subxt-cli
The basic syntax for running subxt commands is:
subxt <SUBCOMMAND>
To use the commands exposed by subxt, you must either be running a node locally or specify the chain you're targeting. If the metadata is already provided, it is possible to use the codegen subcommand without running a node.
You can use the following optional flags with the subxt command.
-h, --help
Displays usage information.
-V, --version
Displays version information.
You can use the following subcommands with the subxt command-line interface.
codegen
Generates runtime API client code from metadata.
metadata
Downloads metadata from a Substrate node for use with subxt codegen.
Depending on how you specify the subcommand, the output from subxt displays some or all of the following information:
Metadata
A file with the metadata of a target chain.
API
A file with the API of the target chain.
To display version information for the subxt program, run the following command:
subxt --version
To display usage information for the subxt metadata command, run the following command:
subxt metadata --help
Use the subxt codegen command to generate an interface for some target Substrate node.
This could be useful for debugging or modifying a node's API to meet certain hardware constraints.
Basic usage
subxt codegen [OPTIONS]
Flags
You can use the following optional flags with the subxt codegen command.
-h, --help
Displays usage information.
-V, --version
Prints version information.
Options
You can use the following command-line options with the subxt codegen command.
-f, --file <file>
Specifies the path to the encoded metadata file.
--url <url>
Specifies the URL of the Substrate node to query for metadata for codegen.
Examples
To format the generated API and print it to the terminal, run the following command:
subxt codegen | rustfmt
To save the generated API in a file, run the following command:
subxt codegen | rustfmt --edition=2018 > api.rs
Use the subxt metadata command to get the metadata of the target Substrate node.
Basic usage
subxt metadata [OPTIONS]
Flags
You can use the following optional flags with the subxt metadata command.
-h, --help
Displays usage information.
-V, --version
Prints version information.
Options
You can use the following command-line options with the subxt metadata command.
-f, --format <format>
Specifies the format of the metadata to display. Valid formats are json, hex or bytes. The default format is json.
--url <url>
Specifies the URL of the Substrate node to query for metadata. The default URL is http://localhost:9933.
Examples
To save the metadata from the local node encoded in bytes to a file, run the following command:
subxt metadata -f bytes > metadata.scale
To save the metadata from the Rococo network to a JSON file, run the following command:
subxt metadata --url https://rococo-rpc.polkadot.io:443 > <contract_name>.json
To query type 125 from the array of types in the metadata and output in JSON, run the following command:
subxt metadata --format json | jq '.[1].V14.types.types | .[125]'