mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-06-13 05:51:02 +00:00
Fix documentation examples (#568)
* Fix documentation examples Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * CI: Add `cargo test --doc` Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Update .github/workflows/rust.yml Co-authored-by: Niklas Adolfsson <niklasadolfsson1@gmail.com> * Remove docs/subxt.md and move documentation to subxt/lib.rs Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Hide polkadot interface for `events/mod.rs` Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * docs: Use `#` for headers Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> Co-authored-by: Niklas Adolfsson <niklasadolfsson1@gmail.com>
This commit is contained in:
Alexandru Vasile
+178
-1
@@ -14,7 +14,184 @@
|
||||
// You should have received a copy of the GNU General Public License
|
||||
// along with subxt. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
#![doc = include_str!("../../docs/subxt.md")]
|
||||
//! Subxt is a library to **sub**mit e**xt**rinsics to a [substrate](https://github.com/paritytech/substrate) node via RPC.
|
||||
//!
|
||||
//! 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)
|
||||
//!
|
||||
//!
|
||||
//! # Generate the runtime API
|
||||
//!
|
||||
//! Subxt generates a runtime API from downloaded static metadata. The metadata can be downloaded using the
|
||||
//! [subxt-cli](https://crates.io/crates/subxt-cli) tool.
|
||||
//!
|
||||
//! To generate the runtime API, use the `subxt` attribute which points at downloaded static metadata.
|
||||
//!
|
||||
//! ```ignore
|
||||
//! #[subxt::subxt(runtime_metadata_path = "metadata.scale")]
|
||||
//! pub mod node_runtime { }
|
||||
//! ```
|
||||
//!
|
||||
//! The `node_runtime` has the following hierarchy:
|
||||
//!
|
||||
//! ```rust
|
||||
//! pub mod node_runtime {
|
||||
//! pub mod PalletName {
|
||||
//! pub mod calls { }
|
||||
//! pub mod storage { }
|
||||
//! pub mod constants { }
|
||||
//! pub mod events { }
|
||||
//! }
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! For more information regarding the `node_runtime` hierarchy, please visit the
|
||||
//! [subxt-codegen](https://docs.rs/subxt-codegen/latest/subxt_codegen/) documentation.
|
||||
//!
|
||||
//!
|
||||
//! # Initializing the API client
|
||||
//!
|
||||
//! ```no_run
|
||||
//! use subxt::{ClientBuilder, DefaultConfig, PolkadotExtrinsicParams};
|
||||
//!
|
||||
//! #[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata.scale")]
|
||||
//! pub mod polkadot {}
|
||||
//!
|
||||
//! # #[tokio::main]
|
||||
//! # async fn main() {
|
||||
//! let api = ClientBuilder::new()
|
||||
//! .set_url("wss://rpc.polkadot.io:443")
|
||||
//! .build()
|
||||
//! .await
|
||||
//! .unwrap()
|
||||
//! .to_runtime_api::<polkadot::RuntimeApi<DefaultConfig, PolkadotExtrinsicParams<DefaultConfig>>>();
|
||||
//! # }
|
||||
//! ```
|
||||
//!
|
||||
//! The `RuntimeApi` type is generated by the `subxt` macro from the supplied metadata. This can be parameterized with user
|
||||
//! supplied implementations for the `Config` and `Extra` types, if the default implementation differs from the target
|
||||
//! chain.
|
||||
//!
|
||||
//! To ensure that extrinsics are properly submitted, during the build phase of the Client the
|
||||
//! runtime metadata of the node is downloaded. If the URL is not specified (`set_url`), the local host is used instead.
|
||||
//!
|
||||
//!
|
||||
//! # Submit Extrinsics
|
||||
//!
|
||||
//! Extrinsics are obtained using the API's `RuntimeApi::tx()` method, followed by `pallet_name()` and then the
|
||||
//! `call_item_name()`.
|
||||
//!
|
||||
//! Submit an extrinsic, returning success once the transaction is validated and accepted into the pool:
|
||||
//!
|
||||
//! Please visit the [balance_transfer](../examples/examples/balance_transfer.rs) example for more details.
|
||||
//!
|
||||
//!
|
||||
//! # Querying Storage
|
||||
//!
|
||||
//! The runtime storage is queried via the generated `RuntimeApi::storage()` method, followed by the `pallet_name()` and
|
||||
//! then the `storage_item_name()`.
|
||||
//!
|
||||
//! Please visit the [fetch_staking_details](../examples/examples/fetch_staking_details.rs) example for more details.
|
||||
//!
|
||||
//! # Query Constants
|
||||
//!
|
||||
//! Constants are embedded into the node's metadata.
|
||||
//!
|
||||
//! The subxt offers the ability to query constants from the runtime metadata (metadata downloaded when constructing
|
||||
//! the client, *not* the one provided for API generation).
|
||||
//!
|
||||
//! To query constants use the generated `RuntimeApi::constants()` method, followed by the `pallet_name()` and then the
|
||||
//! `constant_item_name()`.
|
||||
//!
|
||||
//! Please visit the [fetch_constants](../examples/examples/fetch_constants.rs) example for more details.
|
||||
//!
|
||||
//! # Subscribe to Events
|
||||
//!
|
||||
//! To subscribe to events, use the generated `RuntimeApi::events()` method which exposes:
|
||||
//! - `subscribe()` - Subscribe to events emitted from blocks. These blocks haven't necessarily been finalised.
|
||||
//! - `subscribe_finalized()` - Subscribe to events from finalized blocks.
|
||||
//! - `at()` - Obtain events at a given block hash.
|
||||
//!
|
||||
//!
|
||||
//! *Examples*
|
||||
//! - [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
|
||||
//!
|
||||
//! There are two types of metadata that the subxt is aware of:
|
||||
//! - static metadata: Metadata used for generating the API.
|
||||
//! - runtime metadata: Metadata downloaded from the target node when a subxt client is created.
|
||||
//!
|
||||
//! There are cases when the static metadata is different from the runtime metadata of a node.
|
||||
//! Such is the case when the node performs a runtime update.
|
||||
//!
|
||||
//! To ensure that subxt can properly communicate with the target node the static metadata is validated
|
||||
//! against the runtime metadata of the node.
|
||||
//!
|
||||
//! This validation is performed at the Call, Constant, and Storage levels, as well for the entire metadata.
|
||||
//! The level of granularity ensures that the users can still submit a given call, even if another
|
||||
//! call suffered changes.
|
||||
//!
|
||||
//! Full metadata validation:
|
||||
//!
|
||||
//! ```no_run
|
||||
//! # use subxt::{ClientBuilder, DefaultConfig, PolkadotExtrinsicParams};
|
||||
//! # #[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata.scale")]
|
||||
//! # pub mod polkadot {}
|
||||
//! # #[tokio::main]
|
||||
//! # async fn main() {
|
||||
//! # let api = ClientBuilder::new()
|
||||
//! # .build()
|
||||
//! # .await
|
||||
//! # .unwrap()
|
||||
//! # .to_runtime_api::<polkadot::RuntimeApi<DefaultConfig, PolkadotExtrinsicParams<DefaultConfig>>>();
|
||||
//! // To make sure that all of our statically generated pallets are compatible with the
|
||||
//! // runtime node, we can run this check:
|
||||
//! api.validate_metadata().unwrap();
|
||||
//! # }
|
||||
//! ```
|
||||
//!
|
||||
//! Call level validation:
|
||||
//!
|
||||
//! ```ignore
|
||||
//! # use sp_keyring::AccountKeyring;
|
||||
//! # use subxt::{ClientBuilder, DefaultConfig, PolkadotExtrinsicParams};
|
||||
//! # #[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata.scale")]
|
||||
//! # pub mod polkadot {}
|
||||
//! # #[tokio::main]
|
||||
//! # async fn main() {
|
||||
//! # let api = ClientBuilder::new()
|
||||
//! # .build()
|
||||
//! # .await
|
||||
//! # .unwrap()
|
||||
//! # .to_runtime_api::<polkadot::RuntimeApi<DefaultConfig, PolkadotExtrinsicParams<DefaultConfig>>>();
|
||||
//! // Submit the `transfer` extrinsic from Alice's account to Bob's.
|
||||
//! let dest = AccountKeyring::Bob.to_account_id().into();
|
||||
//!
|
||||
//! let extrinsic = api
|
||||
//! .tx()
|
||||
//! .balances()
|
||||
//! // Constructing an extrinsic will fail if the metadata
|
||||
//! // is not in sync with the generated API.
|
||||
//! .transfer(dest, 123_456_789_012_345)
|
||||
//! .unwrap();
|
||||
//! # }
|
||||
//! ```
|
||||
//!
|
||||
//! # Runtime Updates
|
||||
//!
|
||||
//! There are cases when the node would perform a runtime update, and the runtime node's metadata would be
|
||||
//! out of sync with the subxt's metadata.
|
||||
//!
|
||||
//! The `UpdateClient` API keeps 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.
|
||||
|
||||
#![deny(
|
||||
bad_style,
|
||||
const_err,
|
||||
|
||||
Reference in New Issue
Block a user