mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-06-14 05:11:09 +00:00
Add subxt documentation (#546)
* Documentation for cli crate Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * codegen: Add documentation and simplify calls generation Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * codegen: Add documentation and simplify events generation Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * codegen: Add documentation and simplify constants generation Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * codegen: Add documentation and simplify storage generation Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * codegen: Add lib documentation Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * macro: Remove `-f bytes` as this is the default Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * subxt/client: Add examples Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * lib_doc: Add documentation to dedicated file Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Link documentation from file Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * subxt: Add more documentation Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * subxt: Add Storage example Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Add rpc documentation Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * metadata: Add documentation for errors Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Add documentation for the `extrinsic` module Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Add documentation for `events` module Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * subxt: Add `Static Metadata Validation` section Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * subxt: Add `Runtime Updates` section Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Fix link to documentation Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * readme: Remove hardcoded versions Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Move documentation to dedicated folder Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Spaces between examples Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * More details for `types_mod_ident` Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Add note for RuntimeGenerator Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Address feedback Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Update codegen/src/api/constants.rs Co-authored-by: James Wilson <james@jsdw.me> * Update subxt/src/lib.rs Co-authored-by: James Wilson <james@jsdw.me> * Update subxt/src/metadata/metadata_type.rs Co-authored-by: James Wilson <james@jsdw.me> * Update subxt/src/storage.rs Co-authored-by: James Wilson <james@jsdw.me> * Address feedback Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Fix cargo clippy Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Update call example Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Add example for fetching constants Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Link to examples in subxt.md Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Update codegen/src/api/calls.rs Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com> * Update codegen/src/api/calls.rs Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com> * Update codegen/src/api/calls.rs Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com> * Update codegen/src/api/constants.rs Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com> * Update codegen/src/api/constants.rs Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com> * Update codegen/src/api/storage.rs Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com> * Update codegen/src/api/storage.rs Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com> * Update codegen/src/api/storage.rs Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com> * Update docs/subxt.md Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com> * Update docs/subxt.md Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com> * Update docs/subxt.md Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com> * Update docs/subxt.md Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com> * Update docs/subxt.md Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com> * Update subxt/src/extrinsic/mod.rs Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com> * Update subxt/src/storage.rs Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com> * Update documentation Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Update examples/examples/balance_transfer.rs Co-authored-by: James Wilson <james@jsdw.me> * Update subxt/src/extrinsic/mod.rs Co-authored-by: James Wilson <james@jsdw.me> * Update subxt/src/rpc.rs Co-authored-by: James Wilson <james@jsdw.me> * Update subxt/src/updates.rs Co-authored-by: James Wilson <james@jsdw.me> * Update docs example with `PolkadotExtrinsicParams` Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * subxt: Remove extrinsic extra documentation Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * examples: Remove similar transfer example Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Apply cargo fmt Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> Co-authored-by: James Wilson <james@jsdw.me> Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>
This commit is contained in:
Alexandru Vasile
@@ -98,6 +98,17 @@ impl ClientBuilder {
|
||||
}
|
||||
|
||||
/// Creates a new Client.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use subxt::{ClientBuilder, DefaultConfig};
|
||||
///
|
||||
/// let client = ClientBuilder::new()
|
||||
/// .set_url("wss://rpc.polkadot.io:443")
|
||||
/// .build::<DefaultConfig>()
|
||||
/// .await?;
|
||||
/// ```
|
||||
pub async fn build<T: Config>(self) -> Result<Client<T>, BasicError> {
|
||||
let client = if let Some(client) = self.client {
|
||||
client
|
||||
@@ -190,6 +201,22 @@ impl<T: Config> Client<T> {
|
||||
}
|
||||
|
||||
/// Create a wrapper for performing runtime updates on this client.
|
||||
///
|
||||
/// # Note
|
||||
///
|
||||
/// The update client is intended to be used in the background for
|
||||
/// performing runtime updates, while the API is still in use.
|
||||
/// Without performing runtime updates the submitted extrinsics may fail.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// let update_client = client.updates();
|
||||
/// tokio::spawn(async move {
|
||||
/// let result = update_client.perform_runtime_updates().await;
|
||||
/// println!("Runtime update finished with result={:?}", result);
|
||||
/// });
|
||||
/// ```
|
||||
pub fn updates(&self) -> UpdateClient<T> {
|
||||
UpdateClient::new(
|
||||
self.rpc.clone(),
|
||||
|
||||
+52
-1
@@ -14,7 +14,58 @@
|
||||
// You should have received a copy of the GNU General Public License
|
||||
// along with subxt. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
//! For working with events.
|
||||
//! This module exposes the ability to work with events generated by a given block.
|
||||
//! Subxt can either attempt to statically decode events into known types, or it
|
||||
//! can hand back details of the raw event without knowing what shape its contents
|
||||
//! are (this may be useful if we don't know what exactly we're looking for).
|
||||
//!
|
||||
//! This module is wrapped by the generated API in `RuntimeAPI::EventsApi`.
|
||||
//!
|
||||
//! # Example
|
||||
//!
|
||||
//! ## Subscribe to all events
|
||||
//!
|
||||
//! Users can subscribe to all emitted events from blocks using `subscribe()`.
|
||||
//!
|
||||
//! To subscribe to all events from just the finalized blocks use `subscribe_finalized()`.
|
||||
//!
|
||||
//! To obtain the events from a given block use `at()`.
|
||||
//!
|
||||
//! ```rust
|
||||
//! let mut events = api.events().subscribe().await?;
|
||||
//!
|
||||
//! while let Some(ev) = events.next().await {
|
||||
//! // Obtain all events from this block.
|
||||
//! let ev: subxt::Events<_, _> = ev?;
|
||||
//! // Print block hash.
|
||||
//! println!("Event at block hash {:?}", ev.block_hash());
|
||||
//! // Iterate over all events.
|
||||
//! let mut iter = ev.iter();
|
||||
//! while let Some(event_details) = iter.next() {
|
||||
//! println!("Event details {:?}", event_details);
|
||||
//! }
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! ## Filter events
|
||||
//!
|
||||
//! The subxt exposes the ability to filter events via the `filter_events()` function.
|
||||
//!
|
||||
//! The function filters events from the provided tuple. If 1-tuple is provided, the events are
|
||||
//! returned directly. Otherwise, we'll be given a corresponding tuple of `Option`'s, with exactly
|
||||
//! one variant populated each time.
|
||||
//!
|
||||
//! ```rust
|
||||
//! let mut events = api
|
||||
//! .events()
|
||||
//! .subscribe()
|
||||
//! .await?
|
||||
//! .filter_events::<(polkadot::balances::events::Transfer,)>();
|
||||
//!
|
||||
//! while let Some(transfer_event) = transfer_events.next().await {
|
||||
//! println!("Balance transfer event: {transfer_event:?}");
|
||||
//! }
|
||||
//! ```
|
||||
|
||||
mod decoding;
|
||||
mod event_subscription;
|
||||
|
||||
@@ -15,6 +15,20 @@
|
||||
// along with subxt. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
//! Create signed or unsigned extrinsics.
|
||||
//!
|
||||
//! This modules exposes the extrinsic's parameters and the ability to sign an extrinsic.
|
||||
//!
|
||||
//!
|
||||
//! An extrinsic is submitted with an "signed extra" and "additional" parameters, which can be
|
||||
//! different for each chain. The trait [ExtrinsicParams] determines exactly which
|
||||
//! additional and signed extra parameters are used when constructing an extrinsic.
|
||||
//!
|
||||
//!
|
||||
//! The structure [BaseExtrinsicParams] is a base implementation of the trait which
|
||||
//! configures most of the "signed extra" and "additional" parameters as needed for
|
||||
//! Polkadot and Substrate nodes. Only the shape of the tip payments differs, leading to
|
||||
//! [SubstrateExtrinsicParams] and [PolkadotExtrinsicParams] structs which pick an
|
||||
//! appropriate shape for Substrate/Polkadot chains respectively.
|
||||
|
||||
mod params;
|
||||
mod signer;
|
||||
|
||||
+14
-5
@@ -14,9 +14,7 @@
|
||||
// You should have received a copy of the GNU General Public License
|
||||
// along with subxt. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
//! A library to **sub**mit e**xt**rinsics to a
|
||||
//! [substrate](https://github.com/paritytech/substrate) node via RPC.
|
||||
|
||||
#![doc = include_str!("../../docs/subxt.md")]
|
||||
#![deny(
|
||||
bad_style,
|
||||
const_err,
|
||||
@@ -126,7 +124,13 @@ pub use crate::{
|
||||
},
|
||||
};
|
||||
|
||||
/// Call trait.
|
||||
/// Trait to uniquely identify the call (extrinsic)'s identity from the runtime metadata.
|
||||
///
|
||||
/// Generated API structures that represent each of the different possible
|
||||
/// calls to a node each implement this trait.
|
||||
///
|
||||
/// When encoding an extrinsic, we use this information to know how to map
|
||||
/// the call to the specific pallet and call index needed by a particular node.
|
||||
pub trait Call: Encode {
|
||||
/// Pallet name.
|
||||
const PALLET: &'static str;
|
||||
@@ -139,7 +143,12 @@ pub trait Call: Encode {
|
||||
}
|
||||
}
|
||||
|
||||
/// Event trait.
|
||||
/// Trait to uniquely identify the events's identity from the runtime metadata.
|
||||
///
|
||||
/// Generated API structures that represent an event implement this trait.
|
||||
///
|
||||
/// The trait is utilized to decode emitted events from a block, via obtaining the
|
||||
/// form of the `Event` from the metadata.
|
||||
pub trait Event: Decode {
|
||||
/// Pallet name.
|
||||
const PALLET: &'static str;
|
||||
|
||||
@@ -37,7 +37,7 @@ use std::{
|
||||
sync::Arc,
|
||||
};
|
||||
|
||||
/// Metadata error.
|
||||
/// Metadata error originated from inspecting the internal representation of the runtime metadata.
|
||||
#[derive(Debug, thiserror::Error, PartialEq)]
|
||||
pub enum MetadataError {
|
||||
/// Module is not in metadata.
|
||||
@@ -97,7 +97,7 @@ struct MetadataInner {
|
||||
cached_storage_hashes: HashCache,
|
||||
}
|
||||
|
||||
/// Runtime metadata.
|
||||
/// A representation of the runtime metadata received from a node.
|
||||
#[derive(Clone, Debug)]
|
||||
pub struct Metadata {
|
||||
inner: Arc<MetadataInner>,
|
||||
@@ -307,7 +307,10 @@ impl EventMetadata {
|
||||
}
|
||||
}
|
||||
|
||||
/// Metadata for specific errors.
|
||||
/// Metadata for specific errors obtained from the pallet's `PalletErrorMetadata`.
|
||||
///
|
||||
/// This holds in memory information regarding the Pallet's name, Error's name, and the underlying
|
||||
/// metadata representation.
|
||||
#[derive(Clone, Debug)]
|
||||
pub struct ErrorMetadata {
|
||||
pallet: String,
|
||||
@@ -332,6 +335,10 @@ impl ErrorMetadata {
|
||||
}
|
||||
}
|
||||
|
||||
/// Error originated from converting a runtime metadata [RuntimeMetadataPrefixed] to
|
||||
/// the internal [Metadata] representation.
|
||||
///
|
||||
/// The runtime metadata is converted when building the [crate::client::Client].
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum InvalidMetadataError {
|
||||
#[error("Invalid prefix")]
|
||||
|
||||
@@ -15,6 +15,49 @@
|
||||
// along with subxt. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
//! RPC types and client for interacting with a substrate node.
|
||||
//!
|
||||
//! This is used behind the scenes by various `subxt` APIs, but can
|
||||
//! also be used directly.
|
||||
//!
|
||||
//! # Examples
|
||||
//!
|
||||
//! ## Fetch Storage
|
||||
//!
|
||||
//! ```rust
|
||||
//! use subxt::rpc::Rpc;
|
||||
//! use subxt::storage::StorageKeyPrefix;
|
||||
//!
|
||||
//! // Storage prefix is `twox_128("System") ++ twox_128("ExtrinsicCount")`.
|
||||
//! let key = StorageKeyPrefix::new::<node_runtime::system::storage::ExtrinsicCount>()
|
||||
//! .to_storage_key();
|
||||
//!
|
||||
//! // Obtain the RPC from a generated API
|
||||
//! let rpc: &Rpc<_> = api
|
||||
//! .client
|
||||
//! .rpc();
|
||||
//!
|
||||
//! let result = rpc.storage(&key, None)?;
|
||||
//! println!("Storage result: {:?}", result);
|
||||
//! ```
|
||||
//!
|
||||
//! ## Fetch Keys
|
||||
//!
|
||||
//! ```rust
|
||||
//! use subxt::rpc::Rpc;
|
||||
//! use subxt::storage::StorageKeyPrefix;
|
||||
//! let key = StorageKeyPrefix::new::<polkadot::xcm_pallet::storage::VersionNotifiers>();
|
||||
//!
|
||||
//! // Obtain the RPC from a generated API
|
||||
//! let rpc: &Rpc<_> = api
|
||||
//! .client
|
||||
//! .rpc();
|
||||
//! // Fetch up to 10 keys.
|
||||
//! let keys = rpc
|
||||
//! .storage_keys_paged(Some(key), 10, None, None);
|
||||
//! for key in keys.iter() {
|
||||
//! println!("Key: 0x{}", hex::encode(&key));
|
||||
//! }
|
||||
//! ```
|
||||
|
||||
// jsonrpsee subscriptions are interminable.
|
||||
// Allows `while let status = subscription.next().await {}`
|
||||
|
||||
+41
-1
@@ -14,7 +14,47 @@
|
||||
// You should have received a copy of the GNU General Public License
|
||||
// along with subxt. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
//! For querying runtime storage.
|
||||
//! Query the runtime storage using [StorageClient].
|
||||
//!
|
||||
//! This module is the core of performing runtime storage queries. While you can
|
||||
//! work with it directly, it's prefer to use the generated `storage()` interface where
|
||||
//! possible.
|
||||
//!
|
||||
//! The exposed API is performing RPC calls to `state_getStorage` and `state_getKeysPaged`.
|
||||
//!
|
||||
//! A runtime storage entry can be of type:
|
||||
//! - [StorageEntryKey::Plain] for keys constructed just from the prefix
|
||||
//! `twox_128(pallet) ++ twox_128(storage_item)`
|
||||
//! - [StorageEntryKey::Map] for mapped keys constructed from the prefix,
|
||||
//! plus other arguments `twox_128(pallet) ++ twox_128(storage_item) ++ hash(arg1) ++ arg1`
|
||||
//!
|
||||
//! # Examples
|
||||
//!
|
||||
//! ## Fetch Storage Keys
|
||||
//!
|
||||
//! ```rust
|
||||
//! // Fetch just the keys, returning up to 10 keys.
|
||||
//! let keys = storage
|
||||
//! .fetch_keys::<node_runtime::xcm_pallet::storage::VersionNotifiers>(10, None, None)
|
||||
//! .await?;
|
||||
//! // Iterate over each key
|
||||
//! for key in keys.iter() {
|
||||
//! println!("Key: 0x{}", hex::encode(&key));
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! ## Iterate over Storage
|
||||
//!
|
||||
//! ```rust
|
||||
//! // Iterate over keys and values.
|
||||
//! let mut iter = storage
|
||||
//! .iter::<polkadot::xcm_pallet::storage::VersionNotifiers>(None)
|
||||
//! .await?;
|
||||
//! while let Some((key, value)) = iter.next().await? {
|
||||
//! println!("Key: 0x{}", hex::encode(&key));
|
||||
//! println!("Value: {}", value);
|
||||
//! }
|
||||
//! ```
|
||||
|
||||
use codec::{
|
||||
Decode,
|
||||
|
||||
+21
-1
@@ -14,7 +14,27 @@
|
||||
// You should have received a copy of the GNU General Public License
|
||||
// along with subxt. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
//! For performing runtime updates.
|
||||
//! Perform runtime updates in the background using [UpdateClient].
|
||||
//!
|
||||
//! There are cases when the node would perform a runtime update. As a result, the subxt's metadata
|
||||
//! would be out of sync and the API would not be able to submit valid extrinsics.
|
||||
//! This API keeps the `RuntimeVersion` and `Metadata` of the client synced with the target node.
|
||||
//!
|
||||
//! The runtime update is recommended for long-running clients, or for cases where manually
|
||||
//! restarting subxt would not be feasible. Even with this, extrinsics submitted during a node
|
||||
//! runtime update are at risk or failing, as it will take `subxt` a moment to catch up.
|
||||
//!
|
||||
//! ## Note
|
||||
//!
|
||||
//! Here we use tokio to check for updates in the background, but any runtime can be used.
|
||||
//!
|
||||
//! ```rust
|
||||
//! let update_client = client.updates();
|
||||
//! tokio::spawn(async move {
|
||||
//! let result = update_client.perform_runtime_updates().await;
|
||||
//! println!("Runtime update finished with result={:?}", result);
|
||||
//! });
|
||||
//! ```
|
||||
|
||||
use crate::{
|
||||
rpc::{
|
||||
|
||||
Reference in New Issue
Block a user