mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-06-12 19:21:13 +00:00
Subxt Guide (#890)
* WIP Starting to write book; extrinsics first pass done * cargo fmt * Ongoing work; events, constants, wip blocks * at_latest() and wip blocks * remove need to import parity-scale-codec crate with Subxt for macro to work * More docs; expanding on setup guide and finish pass of main sections * Tidy and remove example section for now * format book lines to 100chars * Fix example code * cargo fmt * cargo fmt * fix example * Fix typos * fix broken doc links, pub mods * Update Subxt macro docs * can't link to Subxt here * move macro docs to Subxt to make linking better and fix example code * note on macro about docs * cargo fmt * document the no_default_derives macro feature * Address feedback and remove redundant text * address review comments; minor tweaks * WIP add Runtime calls to book * Improve Runtime API docs * expose thing we forgot to expose and doc link fixes
This commit is contained in:
James Wilson
+207
-105
@@ -2,112 +2,13 @@
|
||||
// This file is dual-licensed as Apache-2.0 or GPL-3.0.
|
||||
// see LICENSE for license details.
|
||||
|
||||
//! Subxt is a library to **sub**mit e**xt**rinsics to a [substrate](https://github.com/paritytech/substrate) node via RPC.
|
||||
//! Subxt is a library for interacting with Substrate based nodes. Using it looks something like this:
|
||||
//!
|
||||
//! The generated Subxt API exposes the ability to:
|
||||
//! - [Submit extrinsics](https://docs.substrate.io/v3/concepts/extrinsics/) (Calls)
|
||||
//! - [Query storage](https://docs.substrate.io/v3/runtime/storage/) (Storage)
|
||||
//! - [Query constants](https://docs.substrate.io/how-to-guides/v3/basics/configurable-constants/) (Constants)
|
||||
//! - [Subscribe to events](https://docs.substrate.io/v3/runtime/events-and-errors/) (Events)
|
||||
//!
|
||||
//! # Initializing the API client
|
||||
//!
|
||||
//! To interact with a node, you'll need to construct a client.
|
||||
//!
|
||||
//! ```no_run
|
||||
//! use subxt::{OnlineClient, PolkadotConfig};
|
||||
//!
|
||||
//! # #[tokio::main]
|
||||
//! # async fn main() {
|
||||
//! let api = OnlineClient::<PolkadotConfig>::new().await.unwrap();
|
||||
//! # }
|
||||
//! ```rust,ignore
|
||||
#![doc = include_str!("../../examples/examples/balance_transfer_basic.rs")]
|
||||
//! ```
|
||||
//!
|
||||
//! 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](https://crates.io/crates/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:
|
||||
//!
|
||||
//! ```ignore
|
||||
//! #[subxt::subxt(runtime_metadata_path = "metadata.scale")]
|
||||
//! pub mod node_runtime { }
|
||||
//! ```
|
||||
//!
|
||||
//! For more information, please visit the [subxt-codegen](https://docs.rs/subxt-codegen/latest/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](../examples/examples/balance_transfer.rs) example.
|
||||
//! - `.storage()` for fetching and iterating over storage entries. See [`crate::storage::StorageClient`] for more details, or see
|
||||
//! the [fetch_staking_details](../examples/examples/fetch_staking_details.rs) example.
|
||||
//! - `.constants()` for getting hold of constants. See [`crate::constants::ConstantsClient`] for more details, or see
|
||||
//! the [fetch_constants](../examples/examples/fetch_constants.rs) example.
|
||||
//! - `.events()` for subscribing/obtaining events. See [`crate::events::EventsClient`] for more details, or see:
|
||||
//! - [subscribe_all_events](../examples/examples/subscribe_all_events.rs): Subscribe to events emitted from blocks.
|
||||
//! - [subscribe_one_event](../examples/examples/subscribe_one_event.rs): Subscribe and filter by one event.
|
||||
//! - [subscribe_some_events](../examples/examples/subscribe_some_events.rs): 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:
|
||||
//!
|
||||
//! ```no_run
|
||||
//! use subxt::{OnlineClient, PolkadotConfig};
|
||||
//!
|
||||
//! #[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata.scale")]
|
||||
//! pub mod polkadot {}
|
||||
//!
|
||||
//! # #[tokio::main]
|
||||
//! # async fn main() {
|
||||
//! 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](../examples/examples/subscribe_runtime_updates.rs) example for more details.
|
||||
//! Take a look at [the Subxt guide](book) to learn more about how to use Subxt.
|
||||
|
||||
#![deny(
|
||||
bad_style,
|
||||
@@ -132,13 +33,14 @@
|
||||
)]
|
||||
#![allow(clippy::type_complexity)]
|
||||
|
||||
// The guide is here.
|
||||
pub mod book;
|
||||
|
||||
// Suppress an unused dependency warning because tokio is
|
||||
// only used in example code snippets at the time of writing.
|
||||
#[cfg(test)]
|
||||
use tokio as _;
|
||||
|
||||
pub use subxt_macro::subxt;
|
||||
|
||||
// Used to enable the js feature for wasm.
|
||||
#[cfg(target_arch = "wasm32")]
|
||||
pub use getrandom as _;
|
||||
@@ -184,3 +86,203 @@ pub mod ext {
|
||||
#[cfg(feature = "substrate-compat")]
|
||||
pub use sp_runtime;
|
||||
}
|
||||
|
||||
/// Generate a strongly typed API for interacting with a Substrate runtime from its metadata.
|
||||
///
|
||||
/// # Metadata
|
||||
///
|
||||
/// First, you'll need to get hold of some metadata for the node you'd like to interact with. One
|
||||
/// way to do this is by using the `subxt` CLI tool:
|
||||
///
|
||||
/// ```bash
|
||||
/// # Install the CLI tool:
|
||||
/// cargo install subxt-cli
|
||||
/// # Use it to download metadata (in this case, from a node running locally)
|
||||
/// subxt metadata > polkadot_metadata.scale
|
||||
/// ```
|
||||
///
|
||||
/// Run `subxt metadata --help` for more options.
|
||||
///
|
||||
/// # Basic usage
|
||||
///
|
||||
/// Annotate a Rust module with the `subxt` attribute referencing the aforementioned metadata file.
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// #[subxt::subxt(
|
||||
/// runtime_metadata_path = "../artifacts/polkadot_metadata.scale",
|
||||
/// )]
|
||||
/// mod polkadot {}
|
||||
/// ```
|
||||
///
|
||||
/// The `subxt` macro will populate the annotated module with all of the methods and types required
|
||||
/// for interacting with the runtime that the metadata came from via Subxt.
|
||||
///
|
||||
/// # Configuration
|
||||
///
|
||||
/// This macro supports a number of attributes to configure what is generated:
|
||||
///
|
||||
/// ## `crate = "..."`
|
||||
///
|
||||
/// Use this attribute to specify a custom path to the `subxt` crate:
|
||||
///
|
||||
/// ```rust
|
||||
/// # pub extern crate subxt;
|
||||
/// # pub mod path { pub mod to { pub use subxt; } }
|
||||
/// # fn main() {}
|
||||
/// #[subxt::subxt(
|
||||
/// runtime_metadata_path = "../artifacts/polkadot_metadata.scale",
|
||||
/// crate = "crate::path::to::subxt"
|
||||
/// )]
|
||||
/// mod polkadot {}
|
||||
/// ```
|
||||
///
|
||||
/// This is useful if you write a library which uses this macro, but don't want to force users to depend on `subxt`
|
||||
/// at the top level too. By default the path `::subxt` is used.
|
||||
///
|
||||
/// ## `substitute_type(path = "...", with = "...")`
|
||||
///
|
||||
/// This attribute replaces any reference to the generated type at the path given by `path` with a
|
||||
/// reference to the path given by `with`.
|
||||
///
|
||||
/// ```rust
|
||||
/// #[subxt::subxt(
|
||||
/// runtime_metadata_path = "../artifacts/polkadot_metadata.scale",
|
||||
/// substitute_type(path = "sp_arithmetic::per_things::Perbill", with = "crate::Foo")
|
||||
/// )]
|
||||
/// mod polkadot {}
|
||||
///
|
||||
/// # #[derive(
|
||||
/// # scale_encode::EncodeAsType,
|
||||
/// # scale_decode::DecodeAsType,
|
||||
/// # codec::Encode,
|
||||
/// # codec::Decode,
|
||||
/// # Clone,
|
||||
/// # Debug,
|
||||
/// # )]
|
||||
/// // In reality this needs some traits implementing on
|
||||
/// // it to allow it to be used in place of Perbill:
|
||||
/// pub struct Foo(u32);
|
||||
/// # impl codec::CompactAs for Foo {
|
||||
/// # type As = u32;
|
||||
/// # fn encode_as(&self) -> &Self::As {
|
||||
/// # &self.0
|
||||
/// # }
|
||||
/// # fn decode_from(x: Self::As) -> Result<Self, codec::Error> {
|
||||
/// # Ok(Foo(x))
|
||||
/// # }
|
||||
/// # }
|
||||
/// # impl From<codec::Compact<Foo>> for Foo {
|
||||
/// # fn from(v: codec::Compact<Foo>) -> Foo {
|
||||
/// # v.0
|
||||
/// # }
|
||||
/// # }
|
||||
/// # fn main() {}
|
||||
/// ```
|
||||
///
|
||||
/// If the type you're substituting contains generic parameters, you can "pattern match" on those, and
|
||||
/// make use of them in the substituted type, like so:
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// #[subxt::subxt(
|
||||
/// runtime_metadata_path = "../artifacts/polkadot_metadata.scale",
|
||||
/// substitute_type(
|
||||
/// path = "sp_runtime::multiaddress::MultiAddress<A, B>",
|
||||
/// with = "::subxt::utils::Static<::sp_runtime::MultiAddress<A, B>>"
|
||||
/// )
|
||||
/// )]
|
||||
/// mod polkadot {}
|
||||
/// ```
|
||||
///
|
||||
/// The above is also an example of using the [`crate::utils::Static`] type to wrap some type which doesn't
|
||||
/// on it's own implement [`scale_encode::EncodeAsType`] or [`scale_decode::DecodeAsType`], which are required traits
|
||||
/// for any substitute type to implement by default.
|
||||
///
|
||||
/// ## `derive_for_all_types = "..."`
|
||||
///
|
||||
/// By default, all generated types derive a small set of traits. This attribute allows you to derive additional
|
||||
/// traits on all generated types:
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// #[subxt::subxt(
|
||||
/// runtime_metadata_path = "../artifacts/polkadot_metadata.scale",
|
||||
/// derive_for_all_types = "Eq, PartialEq"
|
||||
/// )]
|
||||
/// mod polkadot {}
|
||||
/// ```
|
||||
///
|
||||
/// Any substituted types (including the default substitutes) must also implement these traits in order to avoid errors
|
||||
/// here.
|
||||
///
|
||||
/// ## `derive_for_type(path = "...", derive = "...")`
|
||||
///
|
||||
/// Unlike the above, which derives some trait on every generated type, this attribute allows you to derive traits only
|
||||
/// for specific types. Note that any types which are used inside the specified type may also need to derive the same traits.
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// #[subxt::subxt(
|
||||
/// runtime_metadata_path = "../artifacts/polkadot_metadata.scale",
|
||||
/// derive_for_all_types = "Eq, PartialEq",
|
||||
/// derive_for_type(path = "frame_support::PalletId", derive = "Ord, PartialOrd"),
|
||||
/// derive_for_type(path = "sp_runtime::ModuleError", derive = "Hash"),
|
||||
/// )]
|
||||
/// mod polkadot {}
|
||||
/// ```
|
||||
///
|
||||
/// ## `runtime_metadata_url = "..."`
|
||||
///
|
||||
/// This attribute can be used instead of `runtime_metadata_path` and will tell the macro to download metadata from a node running
|
||||
/// at the provided URL, rather than a node running locally. This can be useful in CI, but is **not recommended** in production code,
|
||||
/// since it runs at compile time and will cause compilation to fail if the node at the given address is unavailable or unresponsive.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// #[subxt::subxt(
|
||||
/// runtime_metadata_url = "wss://rpc.polkadot.io:443"
|
||||
/// )]
|
||||
/// mod polkadot {}
|
||||
/// ```
|
||||
///
|
||||
/// ## `generate_docs`
|
||||
///
|
||||
/// By default, documentation is not generated via the macro, since IDEs do not typically make use of it. This attribute
|
||||
/// forces documentation to be generated, too.
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// #[subxt::subxt(
|
||||
/// runtime_metadata_path = "../artifacts/polkadot_metadata.scale",
|
||||
/// generate_docs
|
||||
/// )]
|
||||
/// mod polkadot {}
|
||||
/// ```
|
||||
///
|
||||
/// ## `runtime_types_only`
|
||||
///
|
||||
/// By default, the macro will generate various interfaces to make using Subxt simpler in addition with any types that need
|
||||
/// generating to make this possible. This attribute makes the codegen only generate the types and not the Subxt interface.
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// #[subxt::subxt(
|
||||
/// runtime_metadata_path = "../artifacts/polkadot_metadata.scale",
|
||||
/// runtime_types_only
|
||||
/// )]
|
||||
/// mod polkadot {}
|
||||
/// ```
|
||||
/// ## `no_default_derives`
|
||||
///
|
||||
/// By default, the macro will add all derives necessary for the generated code to play nicely with Subxt. Adding this attribute
|
||||
/// removes all default derives.
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// #[subxt::subxt(
|
||||
/// runtime_metadata_path = "../artifacts/polkadot_metadata.scale",
|
||||
/// runtime_types_only,
|
||||
/// no_default_derives,
|
||||
/// derive_for_all_types="codec::Encode, codec::Decode"
|
||||
/// )]
|
||||
/// mod polkadot {}
|
||||
/// ```
|
||||
///
|
||||
/// **Note**: At the moment, you must derive at least one of `codec::Encode` or `codec::Decode` or `scale_encode::EncodeAsType` or
|
||||
/// `scale_decode::DecodeAsType` (because we add `#[codec(..)]` attributes on some fields/types during codegen), and you must use this
|
||||
/// feature in conjunction with `runtime_types_only` (or manually specify a bunch of defaults to make codegen work properly when
|
||||
/// generating the subxt interfaces).
|
||||
pub use subxt_macro::subxt;
|
||||
|
||||
Reference in New Issue
Block a user