13 breaking releases
0.28.0 | Apr 12, 2023 |
---|---|
0.27.1 | Feb 15, 2023 |
0.26.0 | Jan 24, 2023 |
0.25.0 | Nov 16, 2022 |
0.1.0 | Nov 8, 2021 |
14,435 downloads per month
Used in 13 crates
(via subxt)
170KB
3.5K
SLoC
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)]
Dependencies
~18–27MB
~520K SLoC