24 releases (breaking)

new 0.38.0 Oct 24, 2024
0.37.0 May 28, 2024
0.36.1 May 27, 2024
0.35.0 Mar 21, 2024
0.22.0 Jun 20, 2022

#515 in Magic Beans

Download history 5988/week @ 2024-07-09 7553/week @ 2024-07-16 6932/week @ 2024-07-23 7673/week @ 2024-07-30 7421/week @ 2024-08-06 6953/week @ 2024-08-13 7645/week @ 2024-08-20 6115/week @ 2024-08-27 6190/week @ 2024-09-03 12330/week @ 2024-09-10 34825/week @ 2024-09-17 35496/week @ 2024-09-24 41149/week @ 2024-10-01 43499/week @ 2024-10-08 45887/week @ 2024-10-15 46167/week @ 2024-10-22

183,605 downloads per month
Used in 72 crates (8 directly)

Apache-2.0 OR GPL-3.0

150KB
3.5K SLoC

subxt · build Latest Version Documentation

Subxt is a library for interacting with Substrate based nodes in Rust and WebAssembly. It can:

  • Submit Extrinsics (this is where the name comes from).
  • Subscribe to blocks, reading the extrinsics and associated events from them.
  • Read and iterate over storage values.
  • Read constants and custom values from the metadata.
  • Call runtime APIs, returning the results.
  • Do all of the above via a safe, statically types interface or via a dynamic one when you need the flexibility.
  • Compile to WASM and run entirely in the browser.
  • Do a bunch of things in a #[no_std] environment via the subxt-core crate.
  • Use a built-in light client (smoldot) to interact with chains.

Usage

Take a look in the examples folder or the examples folder for various smaller or larger subxt usage examples, or read the guide to learn more.

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.

Subxt Documentation

For more details regarding utilizing subxt, please visit the documentation.

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 up-to-date substrate executable on your path.

This can be installed from source via cargo:

cargo install --git https://github.com/paritytech/polkadot-sdk staging-node-cli --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.
  • tidext Tidechain client with Stronghold signer.
  • staking-miner-v2 Submit NPos election solutions and get rewards.
  • polkadot-introspector Tools for monitoring Polkadot nodes.
  • ink! Smart contract language that uses subxt for allowing developers to conduct End-to-End testing of their contracts.
  • Chainflip A decentralised exchange for native cross-chain swaps.
  • Hyperbridge A hyperscalable coprocessor for verifiable cross-chain interoperability.

Alternatives

substrate-api-client provides similar functionality.

License

The entire code within this repository is dual licensed under the GPL-3.0 or Apache-2.0 licenses. See the LICENSE file for more details.

Please contact us if you have questions about the licensing of our products.


lib.rs:

A representation of the metadata provided by a substrate based node. This representation is optimized to be used by Subxt and related crates, and is independent of the different versions of metadata that can be provided from a node.

Typically, this will be constructed by either:

  1. Calling Metadata::decode() given some metadata bytes obtained from a node (this uses codec::Decode).
  2. Obtaining frame_metadata::RuntimeMetadataPrefixed, and then using .try_into() to convert it into Metadata.

Dependencies

~7MB
~105K SLoC