subxt ·

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

Usage

Take a look in the examples folder for various subxt usage examples.

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

2. 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

use subxt::{ClientBuilder, DefaultConfig, SubstrateExtrinsicParams};

let api = ClientBuilder::new()
    .set_url("wss://rpc.polkadot.io:443")
    .build()
    .await?
    .to_runtime_api::<node_runtime::RuntimeApi<DefaultConfig, SubstrateExtrinsicParams<DefaultConfig>>>();

The RuntimeApi type is generated by the subxt macro from the supplied metadata. This can be parameterized with user supplied implementations for the Config and Extra types, if the default implementations differ from the target chain.

Querying Storage

Call the generated RuntimeApi::storage() method, followed by the pallet_name() and then the storage_item_name().

So in order to query Balances::TotalIssuance:

let total_issuance = api
    .storage()
    .balances()
    .total_issuance(None)
    .await
    .unwrap()

Submitting Extrinsics

Submit an extrinsic, returning success once the transaction is validated and accepted into the pool:

use sp_keyring::AccountKeyring;
use subxt::PairSigner;

let signer = PairSigner::new(AccountKeyring::Alice.pair());
let dest = AccountKeyring::Bob.to_account_id().into();

let tx_hash = api
    .tx()
    .balances()
    .transfer(dest, 10_000)
    .sign_and_submit(&signer)
    .await?;

For more advanced usage, which can wait for block inclusion and return any events triggered by the extrinsic, see the balance transfer example.

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.}