subxt ·

A library to submit extrinsics to a substrate node via RPC.

⚠️ Health Warning ⚠️ considered alpha after recent changes, API still subject to change

See paritytech#309 for an overview of outstanding issues.

Usage

Downloading metadata from a Substrate node

Use the subxt-cli tool to download the metadata for your target runtime from a node.

Install:

cargo install subxt-cli

Save the encoded metadata to a file:

subxt metadata -f bytes > metadata.scale

This defaults to querying the metadata of a locally running node on the default http://localhost:9933/. If querying a different node then the metadata command accepts a --url argument.

Generating the runtime API from the downloaded metadata

Declare a module and decorate it with the subxt attribute which points at the downloaded metadata for the target runtime:

#[subxt::subxt(runtime_metadata_path = "metadata.scale")]
pub mod node_runtime { }

Important: runtime_metadata_path resolves to a path relative to the directory where your crate's Cargo.toml resides (CARGO_MANIFEST_DIR), not relative to the source file.

Initializing the API client

API is still a work in progress. See examples for the current usage.

Querying Storage

API is still a work in progress. See tests for the current usage.

Submitting Extrinsics

API is still a work in progress. See examples for the current usage.

Integration Testing

Most tests require a running substrate node to communicate with. This is done by spawning an instance of the substrate node per test. It requires an executable binary substrate at polkadot-v0.9.10 on your path.

This can be installed from source via cargo:

cargo install --git https://github.com/paritytech/substrate node-cli --tag=polkadot-v0.9.10 --force

Real world usage

Please add your project to this list via a PR.

cargo-contract CLI for interacting with Wasm smart contracts.
xcm-cli CLI for submitting XCM messages.
phala-pherry The relayer between Phala blockchain and the off-chain Secure workers.
crunch CLI to claim staking rewards in batch every Era or X hours for substrate-based chains.
interbtc-clients Client implementations for the interBTC parachain; notably the Vault / Relayer and Oracle.

Alternatives

substrate-api-client provides similar functionality.

License

^{The entire code within this repository is licensed under the GPLv3.
Please contact us if you have questions about the licensing of our
products.}

boyswan/subxt