Merge pull request paritytech#97 from subspace/refine-rustdoc-3

Add some trivial improvemnts to sp-consensus-subspace

crates/pallet-subspace/src/tests.rs

@@ -51,7 +51,7 @@ fn first_block_epoch_zero_start() {
 
     ext.execute_with(|| {
         let genesis_slot = Slot::from(100);
-        let solution = Solution::get_for_genesis();
+        let solution = Solution::genesis_solution();
         let por_randomness = sp_io::hashing::blake2_256(&solution.signature);
         let pre_digest = make_pre_digest(genesis_slot, solution);
 
@@ -94,7 +94,7 @@ fn author_por_output() {
 
     ext.execute_with(|| {
         let genesis_slot = Slot::from(10);
-        let solution = Solution::get_for_genesis();
+        let solution = Solution::genesis_solution();
         let por_randomness = sp_io::hashing::blake2_256(&solution.signature);
         let pre_digest = make_pre_digest(genesis_slot, solution);
 

crates/sc-consensus-subspace/src/lib.rs

@@ -90,7 +90,7 @@ use sp_consensus_subspace::{
         CompatibleDigestItem, NextConfigDescriptor, NextEpochDescriptor, NextSaltDescriptor,
         NextSolutionRangeDescriptor, PreDigest, SaltDescriptor, Solution, SolutionRangeDescriptor,
     },
-    inherents::SubspaceInherentData,
+    inherents::SubspaceInherentDataTrait,
     ConsensusLog, FarmerPublicKey, SubspaceApi, SubspaceEpochConfiguration,
     SubspaceGenesisConfiguration, SUBSPACE_ENGINE_ID,
 };
@@ -1014,7 +1014,7 @@ pub fn find_pre_digest<B: BlockT>(header: &B::Header) -> Result<PreDigest, Error
     if header.number().is_zero() {
         return Ok(PreDigest {
             slot: Slot::from(0),
-            solution: Solution::get_for_genesis(),
+            solution: Solution::genesis_solution(),
         });
     }
 
@@ -1528,7 +1528,7 @@ where
                     let mut inherent_data = create_inherent_data_providers
                         .create_inherent_data()
                         .map_err(Error::<Block>::CreateInherents)?;
-                    inherent_data.subspace_replace_inherent_data(slot);
+                    inherent_data.replace_subspace_inherent_data(slot);
                     let new_block = Block::new(pre_header.clone(), inner_body);
 
                     self.check_inherents(

crates/sp-consensus-subspace/src/digests.rs

@@ -16,10 +16,13 @@
 
 //! Private implementation details of Subspace consensus digests.
 
-use super::{FarmerSignature, Slot, SubspaceEpochConfiguration, SUBSPACE_ENGINE_ID};
-use crate::FarmerPublicKey;
+use crate::{
+    FarmerPublicKey, FarmerSignature, SubspaceBlockWeight, SubspaceEpochConfiguration,
+    SUBSPACE_ENGINE_ID,
+};
 use codec::{Codec, Decode, Encode, MaxEncodedLen};
 use scale_info::TypeInfo;
+use sp_consensus_slots::Slot;
 use sp_runtime::{DigestItem, RuntimeDebug};
 use sp_std::vec::Vec;
 use subspace_core_primitives::Randomness;
@@ -28,7 +31,7 @@ use subspace_core_primitives::Randomness;
 /// Solution
 #[derive(Clone, RuntimeDebug, Encode, Decode)]
 pub struct Solution {
-    /// Public key of the farmer that created solution
+    /// Public key of the farmer that created the solution
     pub public_key: FarmerPublicKey,
     /// Index of encoded piece
     pub piece_index: u64,
@@ -42,7 +45,7 @@ pub struct Solution {
 
 impl Solution {
     /// Dummy solution for the genesis block
-    pub fn get_for_genesis() -> Self {
+    pub fn genesis_solution() -> Self {
         Self {
             public_key: FarmerPublicKey::default(),
             piece_index: 0u64,
@@ -66,7 +69,7 @@ pub struct PreDigest {
 impl PreDigest {
     /// Returns the weight _added_ by this digest, not the cumulative weight
     /// of the chain.
-    pub fn added_weight(&self) -> crate::SubspaceBlockWeight {
+    pub fn added_weight(&self) -> SubspaceBlockWeight {
         1
     }
 }

crates/sp-consensus-subspace/src/inherents.rs

@@ -23,22 +23,24 @@ use sp_std::result::Result;
 /// The Subspace inherent identifier.
 pub const INHERENT_IDENTIFIER: InherentIdentifier = *b"subspace";
 
-/// The type of the Subspace inherent.
-pub type InherentType = sp_consensus_slots::Slot;
+/// The type of the Subspace inherent data.
+pub type SubspaceInherentData = sp_consensus_slots::Slot;
+
 /// Auxiliary trait to extract Subspace inherent data.
-pub trait SubspaceInherentData {
+pub trait SubspaceInherentDataTrait {
     /// Get Subspace inherent data.
-    fn subspace_inherent_data(&self) -> Result<Option<InherentType>, Error>;
+    fn subspace_inherent_data(&self) -> Result<Option<SubspaceInherentData>, Error>;
+
     /// Replace Subspace inherent data.
-    fn subspace_replace_inherent_data(&mut self, new: InherentType);
+    fn replace_subspace_inherent_data(&mut self, new: SubspaceInherentData);
 }
 
-impl SubspaceInherentData for InherentData {
-    fn subspace_inherent_data(&self) -> Result<Option<InherentType>, Error> {
+impl SubspaceInherentDataTrait for InherentData {
+    fn subspace_inherent_data(&self) -> Result<Option<SubspaceInherentData>, Error> {
         self.get_data(&INHERENT_IDENTIFIER)
     }
 
-    fn subspace_replace_inherent_data(&mut self, new: InherentType) {
+    fn replace_subspace_inherent_data(&mut self, new: SubspaceInherentData) {
         self.replace_data(INHERENT_IDENTIFIER, &new);
     }
 }
@@ -47,13 +49,13 @@ impl SubspaceInherentData for InherentData {
 // TODO: Remove in the future. https://github.com/paritytech/substrate/issues/8029
 #[cfg(feature = "std")]
 pub struct InherentDataProvider {
-    slot: InherentType,
+    slot: SubspaceInherentData,
 }
 
 #[cfg(feature = "std")]
 impl InherentDataProvider {
     /// Create new inherent data provider from the given `slot`.
-    pub fn new(slot: InherentType) -> Self {
+    pub fn new(slot: SubspaceInherentData) -> Self {
         Self { slot }
     }
 
@@ -63,21 +65,22 @@ impl InherentDataProvider {
         timestamp: sp_timestamp::Timestamp,
         duration: std::time::Duration,
     ) -> Self {
-        let slot =
-            InherentType::from((timestamp.as_duration().as_millis() / duration.as_millis()) as u64);
+        let slot = SubspaceInherentData::from(
+            (timestamp.as_duration().as_millis() / duration.as_millis()) as u64,
+        );
 
         Self { slot }
     }
 
     /// Returns the `slot` of this inherent data provider.
-    pub fn slot(&self) -> InherentType {
+    pub fn slot(&self) -> SubspaceInherentData {
         self.slot
     }
 }
 
 #[cfg(feature = "std")]
 impl sp_std::ops::Deref for InherentDataProvider {
-    type Target = InherentType;
+    type Target = SubspaceInherentData;
 
     fn deref(&self) -> &Self::Target {
         &self.slot

crates/sp-consensus-subspace/src/lib.rs

@@ -15,6 +15,7 @@
 // limitations under the License.
 
 //! Primitives for Subspace consensus.
+
 #![deny(warnings)]
 #![forbid(unsafe_code, missing_docs, unused_variables, unused_imports)]
 #![cfg_attr(not(feature = "std"), no_std)]
@@ -24,15 +25,15 @@ pub mod inherents;
 pub mod offence;
 
 use crate::digests::{
-    NextConfigDescriptor, NextEpochDescriptor, NextSaltDescriptor, NextSolutionRangeDescriptor,
-    SaltDescriptor, SolutionRangeDescriptor,
+    CompatibleDigestItem, NextConfigDescriptor, NextEpochDescriptor, NextSaltDescriptor,
+    NextSolutionRangeDescriptor, SaltDescriptor, SolutionRangeDescriptor,
 };
 use codec::{Decode, Encode, MaxEncodedLen};
 use scale_info::TypeInfo;
 #[cfg(feature = "std")]
 use serde::{Deserialize, Serialize};
 use sp_consensus_slots::Slot;
-use sp_runtime::{traits::Header, ConsensusEngineId, RuntimeDebug};
+use sp_runtime::{traits::Header, ConsensusEngineId, RuntimeAppPublic, RuntimeDebug};
 use sp_std::vec::Vec;
 use subspace_core_primitives::objects::BlockObjectMapping;
 use subspace_core_primitives::{Randomness, RootBlock, Sha256Hash};
@@ -151,9 +152,6 @@ pub fn check_equivocation_proof<H>(proof: EquivocationProof<H>) -> bool
 where
     H: Header,
 {
-    use digests::*;
-    use sp_application_crypto::RuntimeAppPublic;
-
     let find_pre_digest = |header: &H| {
         header
             .digest()

crates/sp-consensus-subspace/src/offence.rs

@@ -15,7 +15,15 @@
 // limitations under the License.
 
 //! Common traits and types that are useful for describing offences for usage in environments
-//! that use staking.
+//! that use subspace consensus.
+//!
+//! ## Comparison with [sp_staking::offence]
+//!
+//! Unlike [sp_staking::offence] handles both the offline and equivocation offences, there is only
+//! equivocation attack in subspace as it's a permissionless consensus based on PoC holding to
+//! Nakamoto's vision and does not have a known validator set for the block production.
+//!
+//! [sp_staking::offence]: https://docs.substrate.io/rustdocs/latest/sp_staking/offence/index.html
 
 use codec::{Decode, Encode};
 use scale_info::TypeInfo;