From 5179b3779628718cf235576182c9a79d5cf6defd Mon Sep 17 00:00:00 2001 From: Xavier Lau Date: Sun, 30 Oct 2022 18:57:40 +0800 Subject: [PATCH 1/5] Doc & format --- bin/subalfred/src/main.rs | 2 +- lib/core/src/cargo/mod.rs | 2 +- lib/core/src/http/mod.rs | 2 +- lib/core/src/jsonrpc/mod.rs | 2 +- lib/core/src/key/mod.rs | 2 +- lib/core/src/lib.rs | 8 ++++---- lib/core/src/node/mod.rs | 2 +- lib/core/src/ss58/mod.rs | 2 +- lib/core/src/state/mod.rs | 2 +- lib/core/src/substrate_client/mod.rs | 2 +- lib/core/src/system/mod.rs | 2 +- 11 files changed, 14 insertions(+), 14 deletions(-) diff --git a/bin/subalfred/src/main.rs b/bin/subalfred/src/main.rs index dad6cf0c..ef277f05 100644 --- a/bin/subalfred/src/main.rs +++ b/bin/subalfred/src/main.rs @@ -3,7 +3,7 @@ //! Subalfred CLI start entry point. mod prelude { - pub use ::std::result::Result as StdResult; + pub use std::result::Result as StdResult; pub use anyhow::Result; diff --git a/lib/core/src/cargo/mod.rs b/lib/core/src/cargo/mod.rs index d259c79c..4c4eb12e 100644 --- a/lib/core/src/cargo/mod.rs +++ b/lib/core/src/cargo/mod.rs @@ -1,4 +1,4 @@ -//! Core library about how Subalfred interacts with Cargo. +//! Subalfred core Cargo library. #[cfg(test)] mod test; diff --git a/lib/core/src/http/mod.rs b/lib/core/src/http/mod.rs index 9c3f261d..dd370df1 100644 --- a/lib/core/src/http/mod.rs +++ b/lib/core/src/http/mod.rs @@ -1,4 +1,4 @@ -//! Core library about how Subalfred interacts with HTTP. +//! Subalfred core HTTP library. // std use std::sync::Arc; diff --git a/lib/core/src/jsonrpc/mod.rs b/lib/core/src/jsonrpc/mod.rs index dd10a630..6a7fe1b8 100644 --- a/lib/core/src/jsonrpc/mod.rs +++ b/lib/core/src/jsonrpc/mod.rs @@ -1,4 +1,4 @@ -//! Core library about how Subalfred interacts with JSONRPC. +//! Subalfred core JSONRPC library. pub mod http; pub mod ws; diff --git a/lib/core/src/key/mod.rs b/lib/core/src/key/mod.rs index 0e990986..a31552d8 100644 --- a/lib/core/src/key/mod.rs +++ b/lib/core/src/key/mod.rs @@ -1,4 +1,4 @@ -//! Substrate keys implementations. +//! Subalfred core key library. // std use std::{ diff --git a/lib/core/src/lib.rs b/lib/core/src/lib.rs index 822885c3..7c9fa2f0 100644 --- a/lib/core/src/lib.rs +++ b/lib/core/src/lib.rs @@ -13,12 +13,12 @@ pub mod substrate_client; pub mod system; pub mod prelude { - //! Subalfred core libraries prelude. + //! Subalfred core prelude. - pub use ::std::result::Result as StdResult; + pub use std::result::Result as StdResult; pub use super::error::{self, Error}; - /// Subalfred core lib's `Result` type. - pub type Result = ::std::result::Result; + /// Subalfred core libraries' `Result` type. + pub type Result = StdResult; } diff --git a/lib/core/src/node/mod.rs b/lib/core/src/node/mod.rs index 2a2c055a..f6c3ff40 100644 --- a/lib/core/src/node/mod.rs +++ b/lib/core/src/node/mod.rs @@ -1,4 +1,4 @@ -//! Core library about how Subalfred interacts with Substrate-based node. +//! Subalfred core node library. // std use std::{ diff --git a/lib/core/src/ss58/mod.rs b/lib/core/src/ss58/mod.rs index 9751e555..efa78f26 100644 --- a/lib/core/src/ss58/mod.rs +++ b/lib/core/src/ss58/mod.rs @@ -1,4 +1,4 @@ -//! SS58-prefix address algorithm implementation. +//! Subalfred core SS58 library. #[cfg(test)] mod test; diff --git a/lib/core/src/state/mod.rs b/lib/core/src/state/mod.rs index 6ca52863..4d0aabc5 100644 --- a/lib/core/src/state/mod.rs +++ b/lib/core/src/state/mod.rs @@ -1,4 +1,4 @@ -//! State core library. +//! Subalfred core runtime state library. pub mod diff; pub use diff::*; diff --git a/lib/core/src/substrate_client/mod.rs b/lib/core/src/substrate_client/mod.rs index afd3e65a..0844aa78 100644 --- a/lib/core/src/substrate_client/mod.rs +++ b/lib/core/src/substrate_client/mod.rs @@ -1,4 +1,4 @@ -//! Substrate-Base API client implementation. +//! //! Subalfred core Substrate client library. // TODO: maybe HTTP diff --git a/lib/core/src/system/mod.rs b/lib/core/src/system/mod.rs index fc82a8a2..487f331f 100644 --- a/lib/core/src/system/mod.rs +++ b/lib/core/src/system/mod.rs @@ -1,4 +1,4 @@ -//! Core library about how Subalfred interacts with OS/System. +//! Subalfred core system library. #[cfg(test)] mod test; From d3fadc05d8a892cf592a51c6b5ac752b7402f6d4 Mon Sep 17 00:00:00 2001 From: Xavier Lau Date: Sun, 30 Oct 2022 19:06:50 +0800 Subject: [PATCH 2/5] Doc --- lib/core/src/cargo/mod.rs | 19 +++++-------------- lib/core/src/error/mod.rs | 3 --- substrate-minimal/subcryptor/src/lib.rs | 4 ++-- 3 files changed, 7 insertions(+), 19 deletions(-) diff --git a/lib/core/src/cargo/mod.rs b/lib/core/src/cargo/mod.rs index 4c4eb12e..5cba5923 100644 --- a/lib/core/src/cargo/mod.rs +++ b/lib/core/src/cargo/mod.rs @@ -13,7 +13,7 @@ use regex::Captures; // hack-ink use crate::{prelude::*, system}; -/// Get the item from the given source by id. +/// Provide a method to get the item by id from specific source. pub trait GetById<'a> { /// Id type. type Id; @@ -57,34 +57,25 @@ pub fn metadata(manifest_path: &str) -> Result { .map_err(error::Cargo::ExecMetadataFailed)?) } -/// Get the metadata's root package. +/// Try to get the metadata's root package. pub fn root_package(metadata: &Metadata) -> Result<&Package> { Ok(metadata.root_package().ok_or(error::Cargo::GetRootPackageFailed)?) } -/// Get the metadata's resolve. +/// Try to get the metadata's resolve. pub fn resolve(metadata: &Metadata) -> Result<&Resolve> { Ok(metadata.resolve.as_ref().ok_or(error::Cargo::GetResolveFailed)?) } -/// Get all the workspace members from the workspace metadata. +/// Try to get all the workspace members from the workspace metadata. pub fn members(metadata: &Metadata) -> Option> { metadata.workspace_members.iter().map(|id| util::find_package(metadata, id)).collect() } -// TODO: might be useless -// /// Read the [`Manifest`] from the given path. -// pub fn manifest

(path: P) -> Result -// where -// P: AsRef, -// { -// Ok(Manifest::from_path(path).map_err(error::Cargo::OpenManifestFailed)?) -// } - // TODO: optimize the algorithm /// Update all the workspace members' versions with the given one. /// -/// If a workspace member depends on another one, the dependency will also be updated. +/// If a workspace member depends on other members, this will also update the dependencies. pub async fn update_member_versions(manifest_path: &str, to: &str) -> Result<()> { let metadata = metadata(manifest_path)?; let members = if let Some(members) = members(&metadata) { diff --git a/lib/core/src/error/mod.rs b/lib/core/src/error/mod.rs index a9c2082e..9bd7e46b 100644 --- a/lib/core/src/error/mod.rs +++ b/lib/core/src/error/mod.rs @@ -60,9 +60,6 @@ pub enum Cargo { GetPackageFailed, #[error("[core::cargo] failed to get the root package")] GetRootPackageFailed, - // TODO: might be useless - // #[error("[core::cargo] failed to open the manifest file")] - // OpenManifestFailed(#[source] cargo_toml::Error), } /// Generic error. diff --git a/substrate-minimal/subcryptor/src/lib.rs b/substrate-minimal/subcryptor/src/lib.rs index 1aa9a36e..abc66aab 100644 --- a/substrate-minimal/subcryptor/src/lib.rs +++ b/substrate-minimal/subcryptor/src/lib.rs @@ -41,7 +41,7 @@ impl Key for Sr25519 { const LEN: usize = 32; } -/// Get the specific network SS58 address of the public key. +/// Try to get the specific network SS58 address of the public key. /// /// Substrate reference(s): /// - https://github.com/paritytech/substrate/blob/c4d36065764ee23aeb3ccd181c4b6ecea8d2447a/primitives/core/src/crypto.rs#L315-L336 @@ -75,7 +75,7 @@ pub fn ss58_address_of(public_key: &[u8], network: &str) -> Result<(u16, String) Ok((prefix, bytes.to_base58())) } -/// Get the public key of the SS58 address. +/// Try to get the public key of the SS58 address. /// /// Substrate reference(s): /// - https://github.com/paritytech/substrate/blob/c4d36065764ee23aeb3ccd181c4b6ecea8d2447a/primitives/core/src/crypto.rs#L260-L302 From 266c25a3e5703f4307bc6ef0e444eb33902facf0 Mon Sep 17 00:00:00 2001 From: Xavier Lau Date: Sun, 30 Oct 2022 20:10:57 +0800 Subject: [PATCH 3/5] Doc --- .../src/command/get/runtime_upgrade_block.rs | 2 +- lib/core/src/cargo/mod.rs | 6 +++--- lib/core/src/system/mod.rs | 21 ++++++++++++------- substrate-minimal/subcryptor/src/lib.rs | 4 ++-- 4 files changed, 19 insertions(+), 14 deletions(-) diff --git a/bin/subalfred/src/command/get/runtime_upgrade_block.rs b/bin/subalfred/src/command/get/runtime_upgrade_block.rs index f9b67846..0fd0f010 100644 --- a/bin/subalfred/src/command/get/runtime_upgrade_block.rs +++ b/bin/subalfred/src/command/get/runtime_upgrade_block.rs @@ -4,7 +4,7 @@ use clap::Args; use crate::prelude::*; use subalfred_core::node; -/// Try to get the runtime upgrade block. +/// Get the runtime upgrade block. /// /// Using the dichotomy algorithm to find it out. /// This operation will fail if the runtime version does not existed. diff --git a/lib/core/src/cargo/mod.rs b/lib/core/src/cargo/mod.rs index 5cba5923..6801d8ad 100644 --- a/lib/core/src/cargo/mod.rs +++ b/lib/core/src/cargo/mod.rs @@ -57,17 +57,17 @@ pub fn metadata(manifest_path: &str) -> Result { .map_err(error::Cargo::ExecMetadataFailed)?) } -/// Try to get the metadata's root package. +/// Get the metadata's root package. pub fn root_package(metadata: &Metadata) -> Result<&Package> { Ok(metadata.root_package().ok_or(error::Cargo::GetRootPackageFailed)?) } -/// Try to get the metadata's resolve. +/// Get the metadata's resolve. pub fn resolve(metadata: &Metadata) -> Result<&Resolve> { Ok(metadata.resolve.as_ref().ok_or(error::Cargo::GetResolveFailed)?) } -/// Try to get all the workspace members from the workspace metadata. +/// Get all the workspace members from the workspace metadata. pub fn members(metadata: &Metadata) -> Option> { metadata.workspace_members.iter().map(|id| util::find_package(metadata, id)).collect() } diff --git a/lib/core/src/system/mod.rs b/lib/core/src/system/mod.rs index 487f331f..d41c9430 100644 --- a/lib/core/src/system/mod.rs +++ b/lib/core/src/system/mod.rs @@ -15,10 +15,12 @@ use tokio::{fs::File as FileAsync, io::AsyncReadExt}; // hack-ink use crate::prelude::*; -/// System port. +/// System port type. +/// +/// Basically, it is a [`u16`]. pub type Port = u16; -/// Read the file's content to [`String`]. +/// Read the file's content into a [`String`]. pub fn read_file_to_string

(path: P) -> Result where P: AsRef, @@ -43,7 +45,7 @@ where Ok(content) } -/// Read the file's content to [`Vec`]. +/// Read the file's content into a [`Vec`]. pub fn read_file_to_vec

(path: P) -> Result> where P: AsRef, @@ -68,7 +70,7 @@ where Ok(content) } -/// Read the file's content to a struct, which implemented [`DeserializeOwned`]. +/// Read the file's content into a struct implemented [`DeserializeOwned`]. pub fn read_file_to_struct(path: P) -> Result where P: AsRef, @@ -111,7 +113,10 @@ where Ok(result) } -/// Write the data to the given path file. +/// Write the data to file at the given path. +/// +/// If the file has already existed, then it will be overwritten. +/// Otherwise, this will create a file at the given path. pub fn write_data_to_file

(path: P, data: &[u8]) -> Result<()> where P: AsRef, @@ -123,7 +128,7 @@ where /// Swap the file's data with the given one. /// -/// This function will create a temporary file first. Then perform the file-swapping. +/// This will create a temporary file first, then perform the file-swapping. pub fn swap_file_data

(path: P, data: &[u8]) -> Result<()> where P: AsRef, @@ -147,9 +152,9 @@ where Some(path.with_file_name(format!(".{file_name}.swp"))) } -/// Search a available port. +/// Search an available port. /// -/// Skip the system ports, starting from 1001. +/// Skip the system used ports, starting from 1001. pub fn random_available_port() -> Result { for port in 1025..Port::MAX { if TcpListener::bind(("127.0.0.1", port)).is_ok() { diff --git a/substrate-minimal/subcryptor/src/lib.rs b/substrate-minimal/subcryptor/src/lib.rs index abc66aab..1aa9a36e 100644 --- a/substrate-minimal/subcryptor/src/lib.rs +++ b/substrate-minimal/subcryptor/src/lib.rs @@ -41,7 +41,7 @@ impl Key for Sr25519 { const LEN: usize = 32; } -/// Try to get the specific network SS58 address of the public key. +/// Get the specific network SS58 address of the public key. /// /// Substrate reference(s): /// - https://github.com/paritytech/substrate/blob/c4d36065764ee23aeb3ccd181c4b6ecea8d2447a/primitives/core/src/crypto.rs#L315-L336 @@ -75,7 +75,7 @@ pub fn ss58_address_of(public_key: &[u8], network: &str) -> Result<(u16, String) Ok((prefix, bytes.to_base58())) } -/// Try to get the public key of the SS58 address. +/// Get the public key of the SS58 address. /// /// Substrate reference(s): /// - https://github.com/paritytech/substrate/blob/c4d36065764ee23aeb3ccd181c4b6ecea8d2447a/primitives/core/src/crypto.rs#L260-L302 From 812ecfc11db9eaa032cddba03264d430d7d79acc Mon Sep 17 00:00:00 2001 From: Xavier Lau Date: Sun, 30 Oct 2022 20:15:28 +0800 Subject: [PATCH 4/5] Doc --- lib/core/src/error/mod.rs | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/lib/core/src/error/mod.rs b/lib/core/src/error/mod.rs index 9bd7e46b..9256595b 100644 --- a/lib/core/src/error/mod.rs +++ b/lib/core/src/error/mod.rs @@ -27,7 +27,7 @@ pub enum Error { Tokio(#[from] Tokio), } -/// Print the error directly. +/// An error helper/wrapper to debug/print the error quickly. #[derive(Debug)] pub struct Quick(String); impl std::fmt::Display for Quick { @@ -36,9 +36,7 @@ impl std::fmt::Display for Quick { } } impl std::error::Error for Quick {} -/// Quick debug helper. -/// -/// Convert the error to [`Quick`]. +/// Wrap the error with [`Quick`]. pub fn quick_err(e: E) -> Quick where E: std::fmt::Debug, @@ -81,7 +79,7 @@ pub enum Generic { #[error(transparent)] Tungstenite(#[from] tokio_tungstenite::tungstenite::Error), } -/// [`Generic::AlmostImpossible`] error helper. +/// Wrap the error with [`Generic::AlmostImpossible`]. pub fn almost_impossible(e_msg: &'static str) -> Generic { Generic::AlmostImpossible(e_msg) } From ffebf57f27883c31e9165816d1c58b19001eed14 Mon Sep 17 00:00:00 2001 From: Xavier Lau Date: Sun, 30 Oct 2022 22:09:17 +0800 Subject: [PATCH 5/5] Doc --- bin/subalfred/src/command/state/mod.rs | 2 +- lib/core/src/jsonrpc/http/mod.rs | 2 +- lib/core/src/jsonrpc/ws/mod.rs | 6 +++--- lib/core/src/key/mod.rs | 10 +++++----- lib/core/src/node/mod.rs | 8 ++++---- lib/core/src/ss58/mod.rs | 10 +++++----- lib/core/src/state/diff.rs | 9 ++++----- lib/core/src/state/export.rs | 8 ++++++-- lib/core/src/state/fork_off.rs | 2 +- lib/core/src/state/override.rs | 2 +- lib/core/src/substrate_client/api.rs | 7 ++----- lib/core/src/substrate_client/mod.rs | 9 ++++----- 12 files changed, 37 insertions(+), 38 deletions(-) diff --git a/bin/subalfred/src/command/state/mod.rs b/bin/subalfred/src/command/state/mod.rs index 532c5b13..0d062fd5 100644 --- a/bin/subalfred/src/command/state/mod.rs +++ b/bin/subalfred/src/command/state/mod.rs @@ -10,7 +10,7 @@ use fork_off::ForkOffCmd; mod r#override; use r#override::OverrideCmd; -/// A set of tools to process Substrate-like node state. +/// A set of tools to process Substrate-like chain state. #[cmd_impl::cmd] pub(crate) enum StateCmd { Diff, diff --git a/lib/core/src/jsonrpc/http/mod.rs b/lib/core/src/jsonrpc/http/mod.rs index bd2a975d..5b873dfd 100644 --- a/lib/core/src/jsonrpc/http/mod.rs +++ b/lib/core/src/jsonrpc/http/mod.rs @@ -1,4 +1,4 @@ -//! Minimal JSONRPC HTTP client implementation. +//! Minimal HTTP JSONRPC client implementation. #[cfg(test)] mod test; diff --git a/lib/core/src/jsonrpc/ws/mod.rs b/lib/core/src/jsonrpc/ws/mod.rs index 8383c4f1..4d833c60 100644 --- a/lib/core/src/jsonrpc/ws/mod.rs +++ b/lib/core/src/jsonrpc/ws/mod.rs @@ -1,4 +1,4 @@ -//! Full functionality JSONRPC websocket client implementation. +//! Full functionality WS JSONRPC client implementation. //! Follow specification. // std @@ -33,7 +33,7 @@ type BatchResponse = Vec; type BatchNotifier = oneshot::Sender; type BatchPool = FxHashMap; -/// The websocket initializer. +/// The WS initializer. #[derive(Debug)] pub struct Initializer { /// Concurrent tasks count limit. @@ -70,7 +70,7 @@ impl Initializer { self } - /// Initialize the websocket stream. + /// Initialize the WS stream. pub async fn connect(self, uri: &str) -> Result { let (mut ws_tx, mut ws_rx) = tokio_tungstenite::connect_async(uri) .await diff --git a/lib/core/src/key/mod.rs b/lib/core/src/key/mod.rs index a31552d8..ebd8b0fb 100644 --- a/lib/core/src/key/mod.rs +++ b/lib/core/src/key/mod.rs @@ -10,7 +10,7 @@ use parity_scale_codec::{Decode, Encode}; // hack-ink use crate::prelude::*; -/// Substrate/Polkadot keys like. +/// Substrate-like key trait. pub trait Key where Self: Sized, @@ -24,7 +24,7 @@ where /// Sub-seed, used to derive the key. fn sub_seed(self) -> Self::SubSeed; - /// Convert the [`KeyTypeId`] to `[u8; N]` + /// Convert the [`KeyTypeId`] into `[u8; N]`. fn to_key(self) -> Result<[u8; N]> { let mut result = [0; N]; let sub_seed = self.sub_seed(); @@ -92,13 +92,13 @@ macro_rules! impl_keys { }; } impl_keys! { - #[doc="Unique identifier of a pallet, aka `ModuleId`."] + #[doc="Identifier of a pallet, aka `ModuleId`."] #[id=*b"modl"] PalletId([u8; 8]), - #[doc="Unique identifier of a parachain."] + #[doc="Identifier of a parachain."] #[id=*b"para"] ParaId(u32), - #[doc="Unique identifier of a sibling chain."] + #[doc="Identifier of a sibling chain."] #[id=*b"sibl"] SiblId(u32), } diff --git a/lib/core/src/node/mod.rs b/lib/core/src/node/mod.rs index f6c3ff40..531e11b0 100644 --- a/lib/core/src/node/mod.rs +++ b/lib/core/src/node/mod.rs @@ -21,7 +21,7 @@ const E_CODEC_METADATA_IS_NON_HEX: &str = const E_STDERR_IS_EMPTY: &str = "[core::node] `stderr` is empty, , maybe the substrate node behavior changed"; -/// Spawn a Substrate-Base standard node. +/// Spawn a Substrate-like standard node. pub fn spawn(executable: &str, rpc_port: u16, chain: &str) -> Result { let mut node = Command::new(executable) .stdout(Stdio::null()) @@ -47,14 +47,14 @@ pub fn spawn(executable: &str, rpc_port: u16, chain: &str) -> Result { Ok(node) } -/// Get runtime version from node. +/// Get runtime version from a nodes's HTTP RPC endpoint. pub async fn runtime_version(uri: &str) -> Result { Ok(http::send::<_, RuntimeVersion>(uri, &state::get_runtime_version(0, None::<()>)) .await? .result) } -/// Fetch runtime metadata from node. +/// Fetch runtime metadata from a nodes's HTTP RPC endpoint. pub async fn runtime_metadata(uri: &str) -> Result { let response = http::send::<_, String>(uri, &state::get_metadata(0, None::<()>)).await?; @@ -81,7 +81,7 @@ pub async fn find_runtime_upgrade_block( // subalfred use crate::{ jsonrpc::ws::Initializer, - substrate_client::{BasicApi, Client}, + substrate_client::{Apis, Client}, }; let client = Client::initialize(Initializer::new(), uri).await?; diff --git a/lib/core/src/ss58/mod.rs b/lib/core/src/ss58/mod.rs index efa78f26..a9b1bbfa 100644 --- a/lib/core/src/ss58/mod.rs +++ b/lib/core/src/ss58/mod.rs @@ -18,9 +18,9 @@ pub struct Address<'a> { pub value: String, } -/// Generate the public key and the specific network address of address. +/// calculate the public key of the address and the network's corresponding address. /// -/// `address` could be public key or SS58 address. +/// `address` could be a public key or SS58 address. /// `network` is case insensitive. pub fn of<'a>(address: &str, network: &'a str) -> Result<(Vec, String, Address<'a>)> { let public_key = recover_public_key(address)?; @@ -31,9 +31,9 @@ pub fn of<'a>(address: &str, network: &'a str) -> Result<(Vec, String, Addre Ok((public_key, hex_public_key, Address { network, prefix, value: address })) } -/// Generate the public key and all the network addresses of the address. +/// calculate the public key and all the specific network addresses of the network. /// -/// `address` could be public key or SS58 address. +/// `address` could be a public key or SS58 address. pub fn all(address: &str) -> Result<(Vec, String, Vec

)> { let public_key = recover_public_key(address)?; let hex_public_key = array_bytes::bytes2hex("0x", &public_key); @@ -51,7 +51,7 @@ pub fn all(address: &str) -> Result<(Vec, String, Vec
)> { // Recover the public key from the given address. // -// `address` could be public key or SS58 address. +// `address` could be a public key or SS58 address. // NO-OP, If the `address` is already a public key. fn recover_public_key(address: &str) -> Result> { match address.len() { diff --git a/lib/core/src/state/diff.rs b/lib/core/src/state/diff.rs index 79f72f99..4a5b05a2 100644 --- a/lib/core/src/state/diff.rs +++ b/lib/core/src/state/diff.rs @@ -5,11 +5,10 @@ use std::path::Path; // hack-ink use crate::prelude::*; -/// Check the diff between two states. -/// +/// Check the differences between the two states. /// Note: -/// This is not a symmetric diff. -/// `a.diff(b)` may equals to `b.diff(a)`, but not always. +/// This is not a symmetric difference operation. +/// `a.diff(b)` might equal `b.diff(a)`, but not always. pub fn diff

(a: P, b: P) -> Result> where P: Send + AsRef, @@ -31,7 +30,7 @@ where diff.push(format!("-{a_k}:{a_v}\n+{a_k}:{b_v}")); } - // Completely same. + // Completely the same. } // Keys only appear in a. else { diff --git a/lib/core/src/state/export.rs b/lib/core/src/state/export.rs index 36de3d2d..23b7d6ca 100644 --- a/lib/core/src/state/export.rs +++ b/lib/core/src/state/export.rs @@ -13,12 +13,16 @@ use crate::{ jsonrpc::ws::Initializer, node, prelude::*, - substrate_client::{BasicApi, Client}, + substrate_client::{Apis, Client}, system, }; use substorager::StorageKey; -/// Export the chain state.. +/// Export the chain state from a node's WS RPC endpoint at a specific block height. +/// +/// If `at` is `None`, this will start from the latest block. +/// Use `skip_pallets` to skip the exporting of some pallets, we usually use this when the pallet's +/// data is too large. pub async fn export( uri: &str, at: Option, diff --git a/lib/core/src/state/fork_off.rs b/lib/core/src/state/fork_off.rs index 860be39c..a219dd8a 100644 --- a/lib/core/src/state/fork_off.rs +++ b/lib/core/src/state/fork_off.rs @@ -66,7 +66,7 @@ pub struct ForkOffConfig { pub disable_default_bootnodes: bool, } -/// Fork-off the state. +/// Fork-off the state with the specific configurations. pub fn fork_off

(target_chain_spec_path: P, config: &ForkOffConfig) -> Result<()> where P: AsRef, diff --git a/lib/core/src/state/override.rs b/lib/core/src/state/override.rs index 2824a0cd..b6919d96 100644 --- a/lib/core/src/state/override.rs +++ b/lib/core/src/state/override.rs @@ -5,7 +5,7 @@ use std::path::Path; // hack-ink use crate::prelude::*; -/// Override state a with b. +/// Override the state a with b. pub fn r#override

(a: P, b: P) -> Result<()> where P: Send + AsRef, diff --git a/lib/core/src/substrate_client/api.rs b/lib/core/src/substrate_client/api.rs index b12335d6..2ba3171a 100644 --- a/lib/core/src/substrate_client/api.rs +++ b/lib/core/src/substrate_client/api.rs @@ -3,9 +3,9 @@ // subalfred use crate::prelude::*; -/// Substrate-like basic API collections. +/// Substrate-like basic API collections. #[async_trait::async_trait] -pub trait BasicApi { +pub trait Apis { /// TODO: doc async fn get_block_hash( &self, @@ -43,7 +43,4 @@ pub trait BasicApi { prefix: substorager::StorageKey, at: Option, ) -> Result>; - - // async fn get_keys_paged(&self, prefix: substorager::StorageKey, at: Option) -> - // Result>; } diff --git a/lib/core/src/substrate_client/mod.rs b/lib/core/src/substrate_client/mod.rs index 0844aa78..f46436e2 100644 --- a/lib/core/src/substrate_client/mod.rs +++ b/lib/core/src/substrate_client/mod.rs @@ -3,7 +3,7 @@ // TODO: maybe HTTP mod api; -pub use api::BasicApi; +pub use api::Apis; // std use std::sync::Arc; @@ -22,14 +22,13 @@ use subversioner::RuntimeVersion; const PAGE_SIZE: usize = 512; -/// Substrate-Base API websocket client. +/// A WS client for Substrate-like chain. #[derive(Clone)] pub struct Client { - /// Websocket connection. ws: Arc, } impl Client { - /// Initialize the client with the given initializer. + /// Initialize the WS client with the given initializer. pub async fn initialize(initializer: Initializer, uri: &str) -> Result { Ok(Self { ws: Arc::new(initializer.connect(uri).await?) }) } @@ -92,7 +91,7 @@ impl Client { } } #[async_trait::async_trait] -impl BasicApi for Client { +impl Apis for Client { async fn get_block_hash(&self, block_number: Option) -> Result where BlockNumber: Send + Serialize,