7 releases (breaking)

0.7.0 Mar 22, 2021
0.6.0 Feb 8, 2021
0.5.0 Oct 5, 2020
0.4.0 Sep 1, 2020
0.1.0 Jun 25, 2020

#1591 in Magic Beans


Used in substrate-subxt

GPL-3.0 license

23KB
467 lines

subxt · build Latest Version Documentation

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

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

See https://github.com/paritytech/subxt/issues/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.

  1. Install:
cargo install subxt-cli
  1. 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.

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.

Dependencies

~44MB
~1M SLoC

@X`