Crate subxt

Subxt is a library to submit extrinsics to a substrate node via RPC.

The generated Subxt API exposes the ability to:

• Submit extrinsics (Calls)
• Query storage (Storage)
• Query constants (Constants)
• Subscribe to events (Events)

Initializing the API client

To interact with a node, you’ll need to construct a client.

use subxt::{OnlineClient, PolkadotConfig};

let api = OnlineClient::<PolkadotConfig>::new().await.unwrap();

This default client connects to a locally running node, but can be configured to point anywhere. Additionally, an crate::OfflineClient is available to perform operations that don’t require a network connection to a node.

The client takes a type parameter, here crate::PolkadotConfig, which bakes in assumptions about the structure of extrinsics and the underlying types used by the node for things like block numbers. If the node you’d like to interact with deviates from Polkadot or the default Substrate node in these areas, you’ll need to configure them by implementing the crate::config::Config type yourself.

Generating runtime types

Subxt can optionally generate types at compile time to help you interact with a node. These types are generated using metadata which can be downloaded from a node using the subxt-cli tool. These generated types provide a degree of type safety when interacting with a node that is compatible with the metadata that they were generated using. We also do runtime checks in case the node you’re talking to has deviated from the types you’re using to communicate with it (see below).

To generate the types, use the subxt macro and point it at the metadata you’ve downloaded, like so:

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

For more information, please visit the subxt-codegen documentation.

You can opt to skip this step and use dynamic queries to talk to nodes instead, which can be useful in some cases, but doesn’t provide any type safety.

Interacting with the API

Once instantiated, a client exposes four core functions:

• .tx() for submitting extrinsics/transactions. See crate::tx::TxClient for more details, or see the balance_transfer example.
• .storage() for fetching and iterating over storage entries. See crate::storage::StorageClient for more details, or see the fetch_staking_details example.
• .constants() for getting hold of constants. See crate::constants::ConstantsClient for more details, or see the fetch_constants example.
• .events() for subscribing/obtaining events. See crate::events::EventsClient for more details, or see:
  • subscribe_all_events: Subscribe to events emitted from blocks.
  • subscribe_one_event: Subscribe and filter by one event.
  • subscribe_some_events: Subscribe and filter event.

Static Metadata Validation

If you use types generated by the crate::subxt macro, there is a chance that they will fall out of sync with the actual state of the node you’re trying to interact with.

When you attempt to use any of these static types to interact with a node, Subxt will validate that they are still compatible and issue an error if they have deviated.

Additionally, you can validate that the entirety of the statically generated code aligns with a node like so:

use subxt::{OnlineClient, PolkadotConfig};

#[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata.scale")]
pub mod polkadot {}

let api = OnlineClient::<PolkadotConfig>::new().await.unwrap();

if let Err(_e) = polkadot::validate_codegen(&api) {
    println!("Generated code is not up to date with node we're connected to");
}

Opting out of static validation

The static types that are used to query/access information are validated by default, to make sure that they are compatible with the node being queried. You can generally call .unvalidated() on these static types to disable this validation.

Runtime Updates

The node you’re connected to may occasionally perform runtime updates while you’re connected, which would ordinarily leave the runtime state of the node out of sync with the information Subxt requires to do things like submit transactions.

If this is a concern, you can use the UpdateClient API to keep the RuntimeVersion and Metadata of the client synced with the target node.

Please visit the subscribe_runtime_updates example for more details.

Re-exports

pub use crate::config::Config;

pub use crate::config::PolkadotConfig;

pub use crate::config::SubstrateConfig;

pub use crate::error::Error;

Modules

blocks

This module exposes the necessary functionality for working with events.

client

This module provides two clients that can be used to work with transactions, storage and events. The OfflineClient works entirely offline and can be passed to any function that doesn’t require network access. The OnlineClient requires network access.

config

This module provides a Config type, which is used to define various types that are important in order to speak to a particular chain. SubstrateConfig provides a default set of these types suitable for the default Substrate node implementation, and PolkadotConfig for a Polkadot node.

constants

Types associated with accessing constants.

dynamic

This module provides the entry points to create dynamic transactions, storage and constant lookups.

error

Types representing the errors that can be returned.

events

This module exposes the types and such necessary for working with events. The two main entry points into events are crate::OnlineClient::events() and calls like crate::tx::TxProgress::wait_for_finalized_success().

ext

Re-export external crates that are made use of in the subxt API.

metadata

Types representing the metadata obtained from a node.

rpc

RPC types and client for interacting with a substrate node.

runtime_api

Types associated with executing runtime API calls.

storage

Types associated with accessing and working with storage items.

tx

Create and submit extrinsics.

utils

Miscellaneous utility helpers.

Macros

rpc_params

Create some RpcParams to pass to our RpcClient. RpcParams simply enforces that parameters handed to our RpcClient methods are the correct shape.

Structs

Metadata

A representation of the runtime metadata received from a node.

OfflineClient

A client that is capable of performing offline-only operations. Can be constructed as long as you can populate the required fields.

OnlineClient

A client that can be used to perform API calls (that is, either those requiring an OfflineClientT or those requiring an OnlineClientT).

Attribute Macros

subxt