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
2026-06-13 07:01:05 +00:00 · 2023-05-04 15:03:42 +01:00
parent 53544a54b6
commit 562f12cd9b
58 changed files with 1472 additions and 1506 deletions
@@ -0,0 +1,81 @@
+// Copyright 2019-2023 Parity Technologies (UK) Ltd.
+// This file is dual-licensed as Apache-2.0 or GPL-3.0.
+// see LICENSE for license details.
+
+//! # Runtime API interface
+//!
+//! The Runtime API interface allows Subxt to call runtime APIs exposed by certain pallets in order
+//! to obtain information. Much like [`super::storage`] and [`super::extrinsics`], Making a runtime
+//! call to a node and getting the response back takes the following steps:
+//!
+//! 1. [Constructing a runtime call](#constructing-a-runtime-call)
+//! 2. [Submitting it to get back the response](#submitting-it)
+//!
+//! **Note:** Runtime APIs are only available when using V15 metadata, which is currently unstable.
+//! You'll need to use `subxt metadata --version unstable` command to download the unstable V15 metadata,
+//! and activate the `unstable-metadata` feature in Subxt for it to also use this metadata from a node. The
+//! metadata format is unstable because it may change and break compatibility with Subxt at any moment, so
+//! use at your own risk.
+//!
+//! ## Constructing a runtime call
+//!
+//! We can use the statically generated interface to build runtime calls:
+//!
+//! ```rust,no_run
+//! use sp_keyring::AccountKeyring;
+//!
+//! #[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata.scale")]
+//! pub mod polkadot {}
+//!
+//! let runtime_call = polkadot::apis().metadata().metadata_versions();
+//! ```
+//!
+//! Alternately, we can dynamically construct a runtime call:
+//!
+//! ```rust,no_run
+//! use sp_keyring::AccountKeyring;
+//! use subxt::dynamic::Value;
+//!
+//! let account = AccountKeyring::Alice.to_account_id();
+//! let runtime_call = subxt::dynamic::runtime_api_call(
+//!     "Metadata_metadata_versions",
+//!     Vec::<Value<()>>::new()
+//! );
+//! ```
+//!
+//! All valid runtime calls implement [`crate::runtime_api::RuntimeApiPayload`], a trait which
+//! describes how to encode the runtime call arguments and what return type to decode from the
+//! response.
+//!
+//! ## Submitting it
+//!
+//! Runtime calls can be handed to [`crate::runtime_api::RuntimeApi::call()`], which will submit
+//! them and hand back the associated response.
+//!
+//! ### Making a static Runtime API call
+//!
+//! The easiest way to make a runtime API call is to use the statically generated interface.
+//!
+//! ```rust,ignore
+#![doc = include_str!("../../../../examples/examples/runtime_apis_static.rs")]
+//! ```
+//!
+//! ### Making a dynamic Runtime API call
+//!
+//! If you'd prefer to construct the call at runtime, you can do this using the
+//! [`crate::dynamic::runtime_api_call`] method.
+//!
+//! ```rust,ignore
+#![doc = include_str!("../../../../examples/examples/runtime_apis_dynamic.rs")]
+//! ```
+//!
+//! ### Making a raw call
+//!
+//! This is generally discouraged in favour of one of the above, but may be necessary (especially if
+//! the node you're talking to does not yet serve V15 metadata). Here, you must manually encode
+//! the argument bytes and manually provide a type for the response bytes to be decoded into.
+//!
+//! ```rust,ignore
+#![doc = include_str!("../../../../examples/examples/runtime_apis_raw.rs")]
+//! ```
+//!