Lib.rs

Generate a strongly typed API for interacting with a Substrate runtime from its metadata.

Usage:

Download metadata from a running Substrate node using subxt-cli:

subxt metadata > polkadot_metadata.scale

Annotate a Rust module with the subxt attribute referencing the aforementioned metadata file.

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

The subxt macro will populate the annotated module with all of the methods and types required for submitting extrinsics and reading from storage for the given runtime.

Substituting types

In order to replace a generated type by a user-defined type, use substitute_type:

#[subxt::subxt(
    runtime_metadata_path = "polkadot_metadata.scale",
    substitute_type(type = "sp_arithmetic::per_things::Perbill", with = "sp_runtime::Perbill")
)]
pub mod polkadot {}

This will replace the generated type and any usages with the specified type at the use import. It is useful for using custom decoding for specific types, or to provide a type with foreign trait implementations, or other specialized functionality.

Custom Derives

By default all generated types are annotated with scale::Encode and scale::Decode derives. However when using the generated types in the client, they may require additional derives to be useful.

Adding derives for all types

Add derive_for_all_types with a comma separated list of the derives to apply to all types

#[subxt::subxt(
    runtime_metadata_path = "polkadot_metadata.scale",
    derive_for_all_types = "Eq, PartialEq"
)]
pub mod polkadot {}

Adding derives for specific types

Add derive_for_type for each specific type with a comma separated list of the derives to apply for that type only.

#[subxt::subxt(
    runtime_metadata_path = "polkadot_metadata.scale",
    derive_for_all_types = "Eq, PartialEq",
    derive_for_type(type = "frame_support::PalletId", derive = "Ord, PartialOrd"),
    derive_for_type(type = "sp_runtime::ModuleError", derive = "Hash"),
)]
pub mod polkadot {}

Custom crate path

In order to specify a custom crate path to be used for the code generation:

#[subxt::subxt(crate = "crate::path::to::subxt")]
pub mod polkadot {}

By default the path ::subxt is used.

Expose documentation

In order to expose the documentation from the runtime metadata on the generated code, users must specify the generate_docs flag:

#[subxt::subxt(generate_docs)]
pub mod polkadot {}

By default the documentation is not generated.

Runtime types generation

In some cases, you may be interested only in the runtime types, like RuntimeCall enum. You can limit code generation to just runtime_types module with runtime_types_only flag:

#[subxt::subxt(runtime_types_only)]
// or equivalently
#[subxt::subxt(runtime_types_only = true)]