mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-04-23 03:47:59 +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
@@ -20,7 +20,6 @@ use crate::types::{
|
||||
};
|
||||
use frame_metadata::{
|
||||
v14::RuntimeMetadataV14,
|
||||
PalletCallMetadata,
|
||||
PalletMetadata,
|
||||
};
|
||||
use heck::{
|
||||
@@ -35,13 +34,51 @@ use quote::{
|
||||
};
|
||||
use scale_info::form::PortableForm;
|
||||
|
||||
/// Generate calls from the provided pallet's metadata.
|
||||
///
|
||||
/// The function creates a new module named `calls` under the pallet's module.
|
||||
/// ```ignore
|
||||
/// pub mod PalletName {
|
||||
/// pub mod calls {
|
||||
/// ...
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// The function generates the calls as rust structs that implement the `subxt::Call` trait
|
||||
/// to uniquely identify the call's identity when creating the extrinsic.
|
||||
///
|
||||
/// ```ignore
|
||||
/// pub struct CallName {
|
||||
/// pub call_param: type,
|
||||
/// }
|
||||
/// impl ::subxt::Call for CallName {
|
||||
/// ...
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// Calls are extracted from the API and wrapped into the generated `TransactionApi` of
|
||||
/// each module.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// - `metadata` - Runtime metadata from which the calls are generated.
|
||||
/// - `type_gen` - The type generator containing all types defined by metadata.
|
||||
/// - `pallet` - Pallet metadata from which the calls are generated.
|
||||
/// - `types_mod_ident` - The ident of the base module that we can use to access the generated types from.
|
||||
pub fn generate_calls(
|
||||
metadata: &RuntimeMetadataV14,
|
||||
type_gen: &TypeGenerator,
|
||||
pallet: &PalletMetadata<PortableForm>,
|
||||
call: &PalletCallMetadata<PortableForm>,
|
||||
types_mod_ident: &syn::Ident,
|
||||
) -> TokenStream2 {
|
||||
// Early return if the pallet has no calls.
|
||||
let call = if let Some(ref calls) = pallet.calls {
|
||||
calls
|
||||
} else {
|
||||
return quote!()
|
||||
};
|
||||
|
||||
let mut struct_defs = super::generate_structs_from_variants(
|
||||
type_gen,
|
||||
call.ty.id(),
|
||||
|
||||
@@ -17,7 +17,6 @@
|
||||
use crate::types::TypeGenerator;
|
||||
use frame_metadata::{
|
||||
v14::RuntimeMetadataV14,
|
||||
PalletConstantMetadata,
|
||||
PalletMetadata,
|
||||
};
|
||||
use heck::ToSnakeCase as _;
|
||||
@@ -29,13 +28,41 @@ use quote::{
|
||||
};
|
||||
use scale_info::form::PortableForm;
|
||||
|
||||
/// Generate constants from the provided pallet's metadata.
|
||||
///
|
||||
/// The function creates a new module named `constants` under the pallet's module.
|
||||
/// ```ignore
|
||||
/// pub mod PalletName {
|
||||
/// pub mod constants {
|
||||
/// ...
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// The constants are exposed via the `ConstantsApi` wrapper.
|
||||
///
|
||||
/// Although the constants are defined in the provided static metadata, the API
|
||||
/// ensures that the constants are returned from the runtime metadata of the node.
|
||||
/// This ensures that if the node's constants change value, we'll always see the latest values.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// - `metadata` - Runtime metadata from which the calls are generated.
|
||||
/// - `type_gen` - The type generator containing all types defined by metadata
|
||||
/// - `pallet` - Pallet metadata from which the calls are generated.
|
||||
/// - `types_mod_ident` - The ident of the base module that we can use to access the generated types from.
|
||||
pub fn generate_constants(
|
||||
metadata: &RuntimeMetadataV14,
|
||||
type_gen: &TypeGenerator,
|
||||
pallet: &PalletMetadata<PortableForm>,
|
||||
constants: &[PalletConstantMetadata<PortableForm>],
|
||||
types_mod_ident: &syn::Ident,
|
||||
) -> TokenStream2 {
|
||||
// Early return if the pallet has no constants.
|
||||
if pallet.constants.is_empty() {
|
||||
return quote!()
|
||||
}
|
||||
let constants = &pallet.constants;
|
||||
|
||||
let constant_fns = constants.iter().map(|constant| {
|
||||
let fn_name = format_ident!("{}", constant.name.to_snake_case());
|
||||
let pallet_name = &pallet.name;
|
||||
|
||||
@@ -15,20 +15,51 @@
|
||||
// along with subxt. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
use crate::types::TypeGenerator;
|
||||
use frame_metadata::{
|
||||
PalletEventMetadata,
|
||||
PalletMetadata,
|
||||
};
|
||||
use frame_metadata::PalletMetadata;
|
||||
use proc_macro2::TokenStream as TokenStream2;
|
||||
use quote::quote;
|
||||
use scale_info::form::PortableForm;
|
||||
|
||||
/// Generate events from the provided pallet metadata.
|
||||
///
|
||||
/// The function creates a new module named `events` under the pallet's module.
|
||||
/// ```ignore
|
||||
/// pub mod PalletName {
|
||||
/// pub mod events {
|
||||
/// ...
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// The function generates the events as rust structs that implement the `subxt::Event` trait
|
||||
/// to uniquely identify the event's identity when creating the extrinsic.
|
||||
///
|
||||
/// ```ignore
|
||||
/// pub struct EventName {
|
||||
/// pub event_param: type,
|
||||
/// }
|
||||
/// impl ::subxt::Event for EventName {
|
||||
/// ...
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// - `type_gen` - The type generator containing all types defined by metadata.
|
||||
/// - `pallet` - Pallet metadata from which the events are generated.
|
||||
/// - `types_mod_ident` - The ident of the base module that we can use to access the generated types from.
|
||||
pub fn generate_events(
|
||||
type_gen: &TypeGenerator,
|
||||
pallet: &PalletMetadata<PortableForm>,
|
||||
event: &PalletEventMetadata<PortableForm>,
|
||||
types_mod_ident: &syn::Ident,
|
||||
) -> TokenStream2 {
|
||||
// Early return if the pallet has no events.
|
||||
let event = if let Some(ref event) = pallet.event {
|
||||
event
|
||||
} else {
|
||||
return quote!()
|
||||
};
|
||||
|
||||
let struct_defs = super::generate_structs_from_variants(
|
||||
type_gen,
|
||||
event.ty.id(),
|
||||
|
||||
+36
-39
@@ -55,6 +55,15 @@ use std::{
|
||||
};
|
||||
use syn::parse_quote;
|
||||
|
||||
/// Generates the API for interacting with a Substrate runtime.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `item_mod` - The module declaration for which the API is implemented.
|
||||
/// * `path` - The path to the scale encoded metadata of the runtime node.
|
||||
/// * `derives` - Provide custom derives for the generated types.
|
||||
///
|
||||
/// **Note:** This is a wrapper over [RuntimeGenerator] for static metadata use-cases.
|
||||
pub fn generate_runtime_api<P>(
|
||||
item_mod: syn::ItemMod,
|
||||
path: P,
|
||||
@@ -78,11 +87,16 @@ where
|
||||
generator.generate_runtime(item_mod, derives)
|
||||
}
|
||||
|
||||
/// Create the API for interacting with a Substrate runtime.
|
||||
pub struct RuntimeGenerator {
|
||||
metadata: RuntimeMetadataV14,
|
||||
}
|
||||
|
||||
impl RuntimeGenerator {
|
||||
/// Create a new runtime generator from the provided metadata.
|
||||
///
|
||||
/// **Note:** If you have a path to the metadata, prefer to use [generate_runtime_api]
|
||||
/// for generating the runtime API.
|
||||
pub fn new(metadata: RuntimeMetadataPrefixed) -> Self {
|
||||
match metadata.1 {
|
||||
RuntimeMetadata::V14(v14) => Self { metadata: v14 },
|
||||
@@ -90,6 +104,12 @@ impl RuntimeGenerator {
|
||||
}
|
||||
}
|
||||
|
||||
/// Generate the API for interacting with a Substrate runtime.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `item_mod` - The module declaration for which the API is implemented.
|
||||
/// * `derives` - Provide custom derives for the generated types.
|
||||
pub fn generate_runtime(
|
||||
&self,
|
||||
item_mod: syn::ItemMod,
|
||||
@@ -98,7 +118,7 @@ impl RuntimeGenerator {
|
||||
let item_mod_ir = ir::ItemMod::from(item_mod);
|
||||
let default_derives = derives.default_derives();
|
||||
|
||||
// some hardcoded default type substitutes, can be overridden by user
|
||||
// Some hardcoded default type substitutes, can be overridden by user
|
||||
let mut type_substitutes = [
|
||||
(
|
||||
"bitvec::order::Lsb0",
|
||||
@@ -175,47 +195,24 @@ impl RuntimeGenerator {
|
||||
let metadata_hash = get_metadata_per_pallet_hash(&self.metadata, &pallet_names);
|
||||
|
||||
let modules = pallets_with_mod_names.iter().map(|(pallet, mod_name)| {
|
||||
let calls = if let Some(ref calls) = pallet.calls {
|
||||
calls::generate_calls(
|
||||
&self.metadata,
|
||||
&type_gen,
|
||||
pallet,
|
||||
calls,
|
||||
types_mod_ident,
|
||||
)
|
||||
} else {
|
||||
quote!()
|
||||
};
|
||||
let calls =
|
||||
calls::generate_calls(&self.metadata, &type_gen, pallet, types_mod_ident);
|
||||
|
||||
let event = if let Some(ref event) = pallet.event {
|
||||
events::generate_events(&type_gen, pallet, event, types_mod_ident)
|
||||
} else {
|
||||
quote!()
|
||||
};
|
||||
let event = events::generate_events(&type_gen, pallet, types_mod_ident);
|
||||
|
||||
let storage_mod = if let Some(ref storage) = pallet.storage {
|
||||
storage::generate_storage(
|
||||
&self.metadata,
|
||||
&type_gen,
|
||||
pallet,
|
||||
storage,
|
||||
types_mod_ident,
|
||||
)
|
||||
} else {
|
||||
quote!()
|
||||
};
|
||||
let storage_mod = storage::generate_storage(
|
||||
&self.metadata,
|
||||
&type_gen,
|
||||
pallet,
|
||||
types_mod_ident,
|
||||
);
|
||||
|
||||
let constants_mod = if !pallet.constants.is_empty() {
|
||||
constants::generate_constants(
|
||||
&self.metadata,
|
||||
&type_gen,
|
||||
pallet,
|
||||
&pallet.constants,
|
||||
types_mod_ident,
|
||||
)
|
||||
} else {
|
||||
quote!()
|
||||
};
|
||||
let constants_mod = constants::generate_constants(
|
||||
&self.metadata,
|
||||
&type_gen,
|
||||
pallet,
|
||||
types_mod_ident,
|
||||
);
|
||||
|
||||
quote! {
|
||||
pub mod #mod_name {
|
||||
|
||||
@@ -18,7 +18,6 @@ use crate::types::TypeGenerator;
|
||||
use frame_metadata::{
|
||||
v14::RuntimeMetadataV14,
|
||||
PalletMetadata,
|
||||
PalletStorageMetadata,
|
||||
StorageEntryMetadata,
|
||||
StorageEntryModifier,
|
||||
StorageEntryType,
|
||||
@@ -36,13 +35,51 @@ use scale_info::{
|
||||
TypeDef,
|
||||
};
|
||||
|
||||
/// Generate storage from the provided pallet's metadata.
|
||||
///
|
||||
/// The function creates a new module named `storage` under the pallet's module.
|
||||
///
|
||||
/// ```ignore
|
||||
/// pub mod PalletName {
|
||||
/// pub mod storage {
|
||||
/// ...
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// The function generates the storage as rust structs that implement the `subxt::StorageEntry`
|
||||
/// trait to uniquely identify the storage's identity when creating the extrinsic.
|
||||
///
|
||||
/// ```ignore
|
||||
/// pub struct StorageName {
|
||||
/// pub storage_param: type,
|
||||
/// }
|
||||
/// impl ::subxt::StorageEntry for StorageName {
|
||||
/// ...
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// Storages are extracted from the API and wrapped into the generated `StorageApi` of
|
||||
/// each module.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// - `metadata` - Runtime metadata from which the storages are generated.
|
||||
/// - `type_gen` - The type generator containing all types defined by metadata.
|
||||
/// - `pallet` - Pallet metadata from which the storages are generated.
|
||||
/// - `types_mod_ident` - The ident of the base module that we can use to access the generated types from.
|
||||
pub fn generate_storage(
|
||||
metadata: &RuntimeMetadataV14,
|
||||
type_gen: &TypeGenerator,
|
||||
pallet: &PalletMetadata<PortableForm>,
|
||||
storage: &PalletStorageMetadata<PortableForm>,
|
||||
types_mod_ident: &syn::Ident,
|
||||
) -> TokenStream2 {
|
||||
let storage = if let Some(ref storage) = pallet.storage {
|
||||
storage
|
||||
} else {
|
||||
return quote!()
|
||||
};
|
||||
|
||||
let (storage_structs, storage_fns): (Vec<_>, Vec<_>) = storage
|
||||
.entries
|
||||
.iter()
|
||||
|
||||
Reference in New Issue
Block a user