Merge pull request #153 from varovainen/va-2024-02-08-docs-and-stop-sp

docs: updated docs to recent changes; chore: removed some sp deps

Cargo.toml

@@ -12,9 +12,9 @@ keywords = ["parser", "substrate"]
 exclude = ["/for_tests", "/.github"]
 
 [dependencies]
-base58 = {version = "0.2.0", optional = true}
+base58 = {version = "0.2.0"}
 bitvec = {version = "1.0.1", default-features = false, features = ["alloc"]}
-blake2 = {version = "0.10.6", default-features = false, optional = true}
+blake2 = {version = "0.10.6", default-features = false}
 external-memory-tools = {version = "0.1.0", default-features = false}
 frame-metadata = {version = "16.0.0", default-features = false, features = ["current", "decode"]}
 hex = {version = "0.4.3", default-features = false, features = ["alloc"]}
@@ -24,14 +24,11 @@ parity-scale-codec = {version = "3.6.9", default-features = false, features = ["
 primitive-types = {version = "0.12.2", default-features = false}
 scale-info = {version = "2.10.0", default-features = false}
 sp-arithmetic = {version = "23.0.0", default-features = false}
-sp-core = {version = "28.0.0", optional = true}
 sp-core-hashing = {version = "15.0.0", default-features = false}
-sp-runtime = {version = "31.0.1", optional = true}
 
 [features]
 default = ["std"]
-std = ["external-memory-tools/std", "frame-metadata/std", "plot_icon", "sp-core/std", "sp-runtime/std"]
-embed-display = ["base58", "blake2"]
+std = ["external-memory-tools/std", "frame-metadata/std", "plot_icon", "primitive-types/std", "sp-core-hashing/std"]
 
 [lib]
 name = "substrate_parser"

src/additional_types.rs

@@ -1,13 +1,8 @@
-//! Types and functions for `no_std` only.
-//!
-//! Exactly follow current substrate code from `no_std` incompatible crates. Last confirmed on v7.0.0
-#[cfg(feature = "embed-display")]
+//! Types and functions from [`sp_core`](https://docs.rs/sp-core/latest/sp_core/)
+//! and [`sp_runtime`](https://docs.rs/sp-runtime/latest/sp_runtime/).
 use base58::ToBase58;
 use parity_scale_codec::{Decode, Encode, Error, Input, Output};
 
-pub use crate::special_types::{SIGNATURE_LEN_ECDSA, SIGNATURE_LEN_ED25519, SIGNATURE_LEN_SR25519};
-
-#[cfg(feature = "embed-display")]
 use crate::std::{string::String, vec::Vec};
 
 /// Era period, same as in `sp_runtime::generic`.
@@ -49,7 +44,7 @@ impl Encode for Era {
         match self {
             Self::Immortal => output.push_byte(0),
             Self::Mortal(period, phase) => {
-                let quantize_factor = (*period as u64 >> 12).max(1);
+                let quantize_factor = (*period >> 12).max(1);
                 let encoded = (period.trailing_zeros() - 1).clamp(1, 15) as u16
                     | ((phase / quantize_factor) << 4) as u16;
                 encoded.encode_to(output);
@@ -88,6 +83,15 @@ pub const PUBLIC_LEN_SR25519: usize = 32;
 /// Known size for `sp_core::ecdsa::Public`.
 pub const PUBLIC_LEN_ECDSA: usize = 33;
 
+/// Known size for `sp_core::ed25519::Signature`.
+pub const SIGNATURE_LEN_ED25519: usize = 64;
+
+/// Known size for `sp_core::sr25519::Signature`.
+pub const SIGNATURE_LEN_SR25519: usize = 64;
+
+/// Known size for `sp_core::ecdsa::Signature`.
+pub const SIGNATURE_LEN_ECDSA: usize = 65;
+
 define_array! {
     /// Placeholder for `sp_core::crypto::AccountId32`.
     AccountId32(ACCOUNT_ID_32_LEN)
@@ -118,11 +122,9 @@ define_array! {
 }
 
 /// Prefix used in base58 conversion. From `sp_core`.
-#[cfg(feature = "embed-display")]
 const PREFIX: &[u8] = b"SS58PRE";
 
 /// Hash calculation used in base58 conversion. From `sp_core`.
-#[cfg(feature = "embed-display")]
 fn ss58hash(data: &[u8]) -> Vec<u8> {
     use blake2::{Blake2b512, Digest};
 
@@ -135,7 +137,6 @@ fn ss58hash(data: &[u8]) -> Vec<u8> {
 /// Same as `to_ss58check_with_version()` method for `Ss58Codec`.
 ///
 /// Comments also from `sp_core`.
-#[cfg(feature = "embed-display")]
 fn as_base58_with_known_prefix(input: &[u8], base58prefix: u16) -> String {
     // We mask out the upper two bits of the ident - SS58 Prefix currently only supports 14-bits
     let ident: u16 = base58prefix & 0b0011_1111_1111_1111;
@@ -158,7 +159,6 @@ fn as_base58_with_known_prefix(input: &[u8], base58prefix: u16) -> String {
 }
 
 /// Base58 representation for some special arrays from `sp_core`.
-#[cfg(feature = "embed-display")]
 macro_rules! add_base {
     ($($name: ident), *) => {
         $(
@@ -171,7 +171,6 @@ macro_rules! add_base {
     }
 }
 
-#[cfg(feature = "embed-display")]
 add_base!(AccountId32, PublicEd25519, PublicSr25519, PublicEcdsa);
 
 #[cfg(test)]

src/cards.rs

@@ -1,28 +1,15 @@
-//! Types for parsed data (nested) and parser cards (flat and formatted).
+//! Types for output: parsed data (nested) and parser cards (flat and formatted).
 use bitvec::prelude::{BitVec, Lsb0, Msb0};
 use frame_metadata::v14::StorageEntryMetadata;
 use num_bigint::{BigInt, BigUint};
 use primitive_types::{H160, H256, H512};
 use scale_info::{form::PortableForm, Field, Path, Type, Variant};
 use sp_arithmetic::{PerU16, Perbill, Percent, Permill, Perquintill};
 
-#[cfg(not(feature = "std"))]
 use crate::additional_types::{
-    AccountId32, PublicEcdsa, PublicEd25519, PublicSr25519, SignatureEcdsa, SignatureEd25519,
+    AccountId32, Era, PublicEcdsa, PublicEd25519, PublicSr25519, SignatureEcdsa, SignatureEd25519,
     SignatureSr25519,
 };
-#[cfg(feature = "std")]
-use sp_core::{
-    crypto::{AccountId32, Ss58AddressFormat, Ss58Codec},
-    ecdsa::{Public as PublicEcdsa, Signature as SignatureEcdsa},
-    ed25519::{Public as PublicEd25519, Signature as SignatureEd25519},
-    sr25519::{Public as PublicSr25519, Signature as SignatureSr25519},
-};
-
-#[cfg(not(feature = "std"))]
-use crate::additional_types::Era;
-#[cfg(feature = "std")]
-use sp_runtime::generic::Era;
 
 #[cfg(feature = "std")]
 use plot_icon::generate_png_scaled_default;
@@ -94,8 +81,7 @@ pub trait Documented {
     fn collect_docs(&self) -> String;
 }
 
-/// Collect documentation from documented [`scale_info`] entity ([`Type`],
-/// [`Field`], [`Variant`], [`StorageEntryMetadata<PortableForm>`]).
+/// Collect documentation from documented [`scale_info`] entity.
 macro_rules! impl_documented {
     ($($ty: ty), *) => {
         $(
@@ -913,37 +899,29 @@ impl std::fmt::Display for InfoFlat {
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct IdData {
     /// Base58 address
-    #[cfg(any(feature = "std", feature = "embed-display"))]
     pub base58: String,
 
     /// Identicon `png` data
     #[cfg(feature = "std")]
     pub identicon: Vec<u8>,
-
-    /// Hexadecimal key
-    #[cfg(all(not(feature = "std"), not(feature = "embed-display")))]
-    pub hex: String,
 }
 
+/// Transform array representable as base58 into [`IdData`].
 macro_rules! make_id_data {
     ($($func: ident, $ty: ty), *) => {
         $(
             impl IdData {
                 #[cfg(feature = "std")]
                 pub fn $func(value: &$ty, base58prefix: u16) -> Self {
-                    let base58 = value.to_ss58check_with_version(Ss58AddressFormat::custom(base58prefix));
-                    let identicon = generate_png_scaled_default(value.as_ref());
+                    let base58 = value.as_base58(base58prefix);
+                    let identicon = generate_png_scaled_default(value.0.as_ref());
                     Self { base58, identicon }
                 }
-                #[cfg(feature = "embed-display")]
+                #[cfg(not(feature = "std"))]
                 pub fn $func(value: &$ty, base58prefix: u16) -> Self {
                     let base58 = value.as_base58(base58prefix);
                     Self { base58 }
                 }
-                #[cfg(all(not(feature = "std"), not(feature = "embed-display")))]
-                pub fn $func(value: &$ty, _base58prefix: u16) -> Self {
-                    Self { hex: hex::encode(value.0) }
-                }
             }
         )*
     }
@@ -1139,10 +1117,7 @@ impl ExtendedCard {
             ParserCard::H160(a) => readable(self.indent, "H160", &hex::encode(a.0)),
             ParserCard::H256(a) => readable(self.indent, "H256", &hex::encode(a.0)),
             ParserCard::H512(a) => readable(self.indent, "H512", &hex::encode(a.0)),
-            #[cfg(any(feature = "std", feature = "embed-display"))]
             ParserCard::Id(a) => readable(self.indent, "Id", &a.base58),
-            #[cfg(all(not(feature = "std"), not(feature = "embed-display")))]
-            ParserCard::Id(a) => readable(self.indent, "Id", &a.hex),
             ParserCard::NameSpecVersion { name, version } => {
                 readable(self.indent, "Chain", &format!("{name}{version}"))
             }
@@ -1175,18 +1150,9 @@ impl ExtendedCard {
             ParserCard::PrimitiveU64(a) => readable(self.indent, "u64", &a.to_string()),
             ParserCard::PrimitiveU128(a) => readable(self.indent, "u128", &a.to_string()),
             ParserCard::PrimitiveU256(a) => readable(self.indent, "BigUint", &a.to_string()),
-            #[cfg(any(feature = "std", feature = "embed-display"))]
             ParserCard::PublicEd25519(a) => readable(self.indent, "PublicKey Ed25519", &a.base58),
-            #[cfg(all(not(feature = "std"), not(feature = "embed-display")))]
-            ParserCard::PublicEd25519(a) => readable(self.indent, "PublicKey Ed25519", &a.hex),
-            #[cfg(any(feature = "std", feature = "embed-display"))]
             ParserCard::PublicSr25519(a) => readable(self.indent, "PublicKey Sr25519", &a.base58),
-            #[cfg(all(not(feature = "std"), not(feature = "embed-display")))]
-            ParserCard::PublicSr25519(a) => readable(self.indent, "PublicKey Sr25519", &a.hex),
-            #[cfg(any(feature = "std", feature = "embed-display"))]
             ParserCard::PublicEcdsa(a) => readable(self.indent, "PublicKey Ecdsa", &a.base58),
-            #[cfg(all(not(feature = "std"), not(feature = "embed-display")))]
-            ParserCard::PublicEcdsa(a) => readable(self.indent, "PublicKey Ecdsa", &a.hex),
             ParserCard::SequenceAnnounced {
                 len,
                 element_info_flat: _,

src/compacts.rs

@@ -5,6 +5,7 @@ use parity_scale_codec::{Compact, Decode, HasCompact};
 use crate::error::ParserError;
 
 /// Compact found in data.
+#[derive(Debug)]
 pub struct FoundCompact<T: HasCompact> {
     /// Compact found and decoded.
     pub compact: T,
@@ -18,10 +19,10 @@ pub struct FoundCompact<T: HasCompact> {
 /// Would not make sense to check slices of higher length for a compact.
 pub const MAX_COMPACT_LEN: usize = 17;
 
-/// Search `&[u8]` for compact at given position by brute force.
+/// Search bytes slice for compact at given position by brute force.
 ///
-/// Tries to find shortest `[u8]` slice that could be decoded as a compact.
-/// Does not modify the input.
+/// Tries to find shortest slice that could be decoded as a compact.
+/// Does not shift current parser position.
 pub fn find_compact<T, B, E>(
     data: &B,
     ext_memory: &mut E,

src/decoding_sci.rs

@@ -1,4 +1,4 @@
-//! Decode using metadata with in-built types descriptors.
+//! Decode types and calls using metadata with in-built type descriptors.
 #[cfg(any(target_pointer_width = "32", test))]
 use bitvec::prelude::BitOrder;
 use bitvec::prelude::{BitVec, Lsb0, Msb0};
@@ -14,18 +14,10 @@ use scale_info::{
 };
 use sp_arithmetic::{PerU16, Perbill, Percent, Permill, Perquintill};
 
-#[cfg(not(feature = "std"))]
 use crate::additional_types::{
     AccountId32, PublicEcdsa, PublicEd25519, PublicSr25519, SignatureEcdsa, SignatureEd25519,
     SignatureSr25519,
 };
-#[cfg(feature = "std")]
-use sp_core::{
-    crypto::AccountId32,
-    ecdsa::{Public as PublicEcdsa, Signature as SignatureEcdsa},
-    ed25519::{Public as PublicEd25519, Signature as SignatureEd25519},
-    sr25519::{Public as PublicSr25519, Signature as SignatureSr25519},
-};
 
 use crate::std::{borrow::ToOwned, string::String, vec::Vec};
 
@@ -157,14 +149,18 @@ where
 }
 
 /// Parse call part of the signable transaction [`MarkedData`] using provided
-/// `V14` metadata.
+/// metadata.
 ///
 /// Call data is expected to have proper call structure and to be decoded
 /// completely, with no data left.
 ///
-/// The first `u8` element of the call data is a pallet index, the type within
-/// corresponding `PalletCallMetadata` is expected to be an enum with
-/// pallet-specific calls. If the pallet-call pattern is not observed, an error
+/// Entry point for call decoding is `call_ty`, describing all available pallets
+/// for the chain. Type corresponding to `call_ty` is expected to be an enum
+/// with call-associated `Path` identifier
+/// [`CALL`](crate::special_indicators::CALL), and the selected variant is
+/// expected to have a single field, also and enum by type, also having
+/// call-associated `Path` identifier and corresponding to all calls within
+/// selected pallet. If the pallet-call pattern is not observed, an error
 /// occurs.
 pub fn decode_as_call<B, E, M>(
     marked_data: &MarkedData<B, E, M>,
@@ -192,9 +188,13 @@ where
 
 /// Parse call part of the signable transaction using provided metadata.
 ///
-/// The first `u8` element of the call data is a pallet index, the type within
-/// corresponding `PalletCallMetadata` is expected to be an enum with
-/// pallet-specific calls. If the pallet-call pattern is not observed, an error
+/// Entry point for call decoding is `call_ty`, describing all available pallets
+/// for the chain. Type corresponding to `call_ty` is expected to be an enum
+/// with call-associated `Path` identifier
+/// [`CALL`](crate::special_indicators::CALL), and the selected variant is
+/// expected to have a single field, also and enum by type, also having
+/// call-associated `Path` identifier and corresponding to all calls within
+/// selected pallet. If the pallet-call pattern is not observed, an error
 /// occurs.
 pub fn decode_as_call_unmarked<B, E, M>(
     data: &B,
@@ -244,7 +244,7 @@ where
 ///
 /// - enums (variant index is passed)
 /// - vectors (compact vector length indicator is passed)
-/// - calls and events, options (also variant index is passed)
+/// - calls and events (also variant index is passed)
 ///
 /// In empty enums there are no inner types, therefore cycling is impossible.
 ///
@@ -571,8 +571,8 @@ where
     }
 }
 
-/// Parse part of data as a set of [`Field`]s. Used for structs, enums and call
-/// decoding.
+/// Parse part of data as a set of [`Field`]s. Used for structs, enums and
+/// pallet-specific items.
 ///
 /// Current parser position gets changed.
 fn decode_fields<B, E, M>(
@@ -686,7 +686,7 @@ where
 ///
 /// First data `u8` element is `index` of [`Variant`].
 ///
-/// Does not modify the input.
+/// Does not shift the current parser position.
 pub fn pick_variant<'a, B, E>(
     variants: &'a [Variant<PortableForm>],
     data: &B,
@@ -748,12 +748,13 @@ where
 }
 
 /// `BitOrder` as determined by the `bit_order_type` for [`TypeDefBitSequence`].
+#[derive(Debug)]
 pub enum FoundBitOrder {
     Lsb0,
     Msb0,
 }
 
-/// Determine BitOrder type of [`TypeDefBitSequence`].
+/// Determine `BitOrder` type of [`TypeDefBitSequence`].
 pub fn find_bit_order_ty<E, M>(
     bit_ty: &TypeDefBitSequence<PortableForm>,
     id: u32,
@@ -890,6 +891,7 @@ where
 }
 
 /// Positions and related values for decoding `BitVec`.
+#[derive(Debug)]
 pub struct BitVecPositions {
     /// Encoded `BitVec` start position, includes bit length compact.
     bitvec_start: usize,
@@ -1122,6 +1124,7 @@ impl_patched!(Msb0, reform_vec_msb0);
 /// Element [`Info`] is collected while resolving the type. No identical
 /// [`Type`] `id`s are expected to be encountered (these are collected and
 /// checked in [`Checker`]), otherwise the resolving would go indefinitely.
+#[derive(Debug)]
 pub struct HuskedType {
     pub info: Vec<Info>,
     pub checker: Checker,
@@ -1200,13 +1203,14 @@ where
 /// Type information used for parsing.
 #[derive(Debug)]
 pub enum Ty<'a> {
-    /// Type is already resolved in metadata `Registry`.
+    /// Type is already resolved in metadata types registry.
     Resolved(ResolvedTy),
 
     /// Type is not yet resolved.
     Symbol(&'a UntrackedSymbol<TypeId>),
 }
 
+///Type previously resolved in metadata types registry.
 #[derive(Debug)]
 pub struct ResolvedTy {
     pub ty: Type<PortableForm>,