docs: improve torus substrate docstrings (#71)

Adds docstrings to most storage values and core functions. Closes
CHAIN-45.

---------

Co-authored-by: Luiz Carvalho <[email protected]>

node/src/chain_spec.rs

@@ -52,7 +52,6 @@ fn testnet_genesis() -> Value {
         polkadot_sdk_frame::traits::Get,
         sp_keyring::{Ed25519Keyring, Sr25519Keyring},
     };
-
     use torus_runtime::{
         interface::{Balance, MinimumBalance},
         BalancesConfig, SudoConfig,

node/src/cli/eth.rs

@@ -25,7 +25,8 @@ pub fn db_config_dir(config: &Configuration) -> PathBuf {
 /// Available frontier backend types.
 #[derive(Debug, Copy, Clone, Default, clap::ValueEnum)]
 pub enum BackendType {
-    /// Either RocksDb or ParityDb as per inherited from the global backend settings.
+    /// Either RocksDb or ParityDb as per inherited from the global backend
+    /// settings.
     #[default]
     KeyValue,
     /// Sql database with custom log indexing.
@@ -50,8 +51,8 @@ pub struct EthConfiguration {
     #[arg(long, default_value = "1")]
     pub target_gas_price: u64,
 
-    /// Maximum allowed gas limit will be `block.gas_limit * execute_gas_limit_multiplier`
-    /// when using eth_call/eth_estimateGas.
+    /// Maximum allowed gas limit will be `block.gas_limit *
+    /// execute_gas_limit_multiplier` when using eth_call/eth_estimateGas.
     #[arg(long, default_value = "2")]
     pub execute_gas_limit_multiplier: u64,
     /// Size in bytes of the LRU cache for block data.

node/src/command.rs

@@ -15,17 +15,18 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use crate::{
-    chain_spec,
-    cli::{Cli, Subcommand},
-    service,
-};
 use benchmarking::{inherent_benchmark_data, RemarkBuilder, TransferKeepAliveBuilder};
 use frame_benchmarking_cli::{BenchmarkCmd, ExtrinsicFactory, SUBSTRATE_REFERENCE_HARDWARE};
 use futures::TryFutureExt;
 use polkadot_sdk::{sc_cli::SubstrateCli, sc_service::PartialComponents, *};
 use torus_runtime::interface::Block;
 
+use crate::{
+    chain_spec,
+    cli::{Cli, Subcommand},
+    service,
+};
+
 mod benchmarking;
 
 impl SubstrateCli for Cli {

node/src/command/benchmarking.rs

@@ -2,7 +2,7 @@
 //!
 //! Should only be used for benchmarking as it may break in other contexts.
 
-use crate::service::FullClient;
+use std::{sync::Arc, time::Duration};
 
 use polkadot_sdk::{
     sc_cli::Result,
@@ -15,7 +15,7 @@ use polkadot_sdk::{
 };
 use torus_runtime::interface::{AccountId, Balance, BalancesCall, SystemCall};
 
-use std::{sync::Arc, time::Duration};
+use crate::service::FullClient;
 
 /// Generates extrinsics for the `benchmark overhead` command.
 ///

node/src/rpc.rs

@@ -22,6 +22,8 @@
 
 #![warn(missing_docs)]
 
+use std::sync::Arc;
+
 use eth::EthDeps;
 use futures::channel::mpsc;
 use jsonrpsee::RpcModule;
@@ -38,7 +40,6 @@ use polkadot_sdk::{
     sp_runtime::traits::Block as BlockT,
     substrate_frame_rpc_system::{System, SystemApiServer},
 };
-use std::sync::Arc;
 use torus_runtime::{interface::Hash, opaque::Block};
 
 use crate::service::FullClient;

node/src/rpc/eth.rs

@@ -1,5 +1,10 @@
 use std::{collections::BTreeMap, sync::Arc};
 
+// Frontier
+pub use fc_rpc::EthBlockDataCacheTask;
+pub use fc_rpc_core::types::{FeeHistoryCache, FeeHistoryCacheLimit, FilterPool};
+use fc_storage::StorageOverride;
+use fp_rpc::ConvertTransaction;
 use jsonrpsee::RpcModule;
 use polkadot_sdk::{
     sc_network::service::traits::NetworkService,
@@ -11,11 +16,6 @@ use polkadot_sdk::{
     sp_inherents::CreateInherentDataProviders,
     sp_runtime::traits::Block as BlockT,
 };
-// Frontier
-pub use fc_rpc::EthBlockDataCacheTask;
-pub use fc_rpc_core::types::{FeeHistoryCache, FeeHistoryCacheLimit, FilterPool};
-use fc_storage::StorageOverride;
-use fp_rpc::ConvertTransaction;
 use torus_runtime::opaque::Block;
 
 use crate::service::{FullBackend, FullClient};
@@ -52,8 +52,8 @@ pub struct EthDeps<P, A: ChainApi, CT, CIDP> {
     pub fee_history_cache: FeeHistoryCache,
     /// Maximum fee history cache size.
     pub fee_history_cache_limit: FeeHistoryCacheLimit,
-    /// Maximum allowed gas limit will be ` block.gas_limit * execute_gas_limit_multiplier` when
-    /// using eth_call/eth_estimateGas.
+    /// Maximum allowed gas limit will be ` block.gas_limit *
+    /// execute_gas_limit_multiplier` when using eth_call/eth_estimateGas.
     pub execute_gas_limit_multiplier: u64,
     /// Mandated parent hashes for a given block hash.
     pub forced_parent_hashes: Option<BTreeMap<H256, H256>>,
@@ -95,9 +95,8 @@ where
     use fc_rpc::{
         pending::AuraConsensusDataProvider, Debug, DebugApiServer, Eth, EthApiServer, EthDevSigner,
         EthFilter, EthFilterApiServer, EthPubSub, EthPubSubApiServer, EthSigner, Net, NetApiServer,
-        Web3, Web3ApiServer,
+        TxPool, TxPoolApiServer, Web3, Web3ApiServer,
     };
-    use fc_rpc::{TxPool, TxPoolApiServer};
 
     let EthDeps {
         client,

node/src/service.rs

@@ -15,6 +15,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+use std::{pin::Pin, sync::Arc, time::Duration};
+
 use fc_rpc::StorageOverrideHandler;
 use futures::FutureExt;
 use polkadot_sdk::{
@@ -28,7 +30,6 @@ use polkadot_sdk::{
     sp_runtime::traits::Block as BlockT,
     *,
 };
-use std::{pin::Pin, sync::Arc, time::Duration};
 use torus_runtime::{apis::RuntimeApi, configs::eth::TransactionConverter, opaque::Block};
 
 use crate::cli::{
@@ -495,9 +496,11 @@ pub async fn new_full<Network: sc_network::NetworkBackend<Block, <Block as Block
     let storage_override = Arc::new(StorageOverrideHandler::new(client.clone()));
 
     // Sinks for pubsub notifications.
-    // Everytime a new subscription is created, a new mpsc channel is added to the sink pool.
-    // The MappingSyncWorker sends through the channel on block import and the subscription emits a notification to the subscriber on receiving a message through this channel.
-    // This way we avoid race conditions when using native substrate block import notification stream.
+    // Every time a new subscription is created, a new mpsc channel is added to the
+    // sink pool. The MappingSyncWorker sends through the channel on block
+    // import and the subscription emits a notification to the subscriber on
+    // receiving a message through this channel. This way we avoid race
+    // conditions when using native substrate block import notification stream.
     let pubsub_notification_sinks: fc_mapping_sync::EthereumBlockNotificationSinks<
         fc_mapping_sync::EthereumBlockNotification<Block>,
     > = Default::default();

pallets/emission0/api/src/lib.rs

@@ -8,6 +8,7 @@ pub struct ConsensusMemberStats {
 
 pub trait Emission0Api<AccountId> {
     /// Fetches stats emitted by the consensus for an agent.
-    /// Returns `None` if the agent has not taken part in the last consensus run.
+    /// Returns `None` if the agent has not taken part in the last consensus
+    /// run.
     fn consensus_stats(member: &AccountId) -> Option<ConsensusMemberStats>;
 }

pallets/emission0/src/distribute.rs

@@ -212,7 +212,8 @@ impl<T: Config> ConsensusMemberInput<T> {
         }
     }
 
-    /// Removes self-weights, ensures the keys are registered to the consensus and normalizes it.
+    /// Removes self-weights, ensures the keys are registered to the consensus
+    /// and normalizes it.
     pub fn prepare_weights(
         member: ConsensusMember<T>,
         agent_id: &T::AccountId,
@@ -242,7 +243,8 @@ impl<T: Config> ConsensusMemberInput<T> {
         weights
     }
 
-    /// Normalizes the list of stakers to the agent, and adds the agent itself in case no stake was given.
+    /// Normalizes the list of stakers to the agent, and adds the agent itself
+    /// in case no stake was given.
     pub fn normalized_stakers(&self) -> Vec<(T::AccountId, Perquintill)> {
         self.stakes
             .iter()

pallets/emission0/src/distribute/math.rs

@@ -1,16 +1,15 @@
 #![allow(dead_code)]
 
+// This is necessary because functions like `f64::{fract, floor, ceil}`
+// are only implemented in `std`.
+#[cfg(not(feature = "std"))]
+use num_traits::float::FloatCore;
 use polkadot_sdk::sp_std::{cmp::Ordering, collections::btree_map::BTreeMap, vec, vec::Vec};
 use substrate_fixed::{
     transcendental::{exp, ln},
     types::I96F32,
 };
 
-// This is necessary because functions like `f64::{fract, floor, ceil}`
-// are only implemented in `std`.
-#[cfg(not(feature = "std"))]
-use num_traits::float::FloatCore;
-
 // Return true when vector sum is zero.
 pub fn is_zero(vector: &[I96F32]) -> bool {
     vector.iter().sum::<I96F32>() == I96F32::from_num(0)
@@ -344,9 +343,10 @@ pub fn weighted_median_col_sparse(
     median
 }
 
-// Stake-weighted median score finding algorithm, based on a mid pivot binary search.
-// Normally a random pivot is used, but to ensure full determinism the mid point is chosen instead.
-// Assumes relatively random score order for efficiency, typically less than O(nlogn) complexity.
+// Stake-weighted median score finding algorithm, based on a mid pivot binary
+// search. Normally a random pivot is used, but to ensure full determinism the
+// mid point is chosen instead. Assumes relatively random score order for
+// efficiency, typically less than O(nlogn) complexity.
 //
 // # Args:
 // 	* 'stake': ( &Vec<I96F32> ):
@@ -362,12 +362,12 @@ pub fn weighted_median_col_sparse(
 // 		- minority_ratio = 1 - majority_ratio
 //
 // 	* 'partition_lo' ( I96F32 ):
-// 		- lower edge of stake for partition, where partition is a segment [lo, hi] inside stake
-//     integral [0, 1].
+// 		- lower edge of stake for partition, where partition is a segment [lo, hi]
+//     inside stake integral [0, 1].
 //
 // 	* 'partition_hi' ( I96F32 ):
-// 		- higher edge of stake for partition, where partition is a segment [lo, hi] inside stake
-//     integral [0, 1].
+// 		- higher edge of stake for partition, where partition is a segment [lo, hi]
+//     inside stake integral [0, 1].
 //
 // # Returns:
 //     * 'median': ( I96F32 ):
@@ -466,7 +466,8 @@ pub fn row_sum_sparse(sparse_matrix: &[Vec<(u16, I96F32)>]) -> Vec<I96F32> {
     result
 }
 
-// Return sparse matrix with values above column threshold set to threshold value.
+// Return sparse matrix with values above column threshold set to threshold
+// value.
 pub fn col_clip_sparse(
     sparse_matrix: &[Vec<(u16, I96F32)>],
     col_threshold: &[I96F32],
@@ -706,8 +707,8 @@ pub fn mat_ema_sparse(
     result
 }
 
-/// Max-upscale vector and convert to u16 so max_value = u16::MAX. Assumes non-negative normalized
-/// input.
+/// Max-upscale vector and convert to u16 so max_value = u16::MAX. Assumes
+/// non-negative normalized input.
 pub fn vec_max_upscale_to_u16(vec: &[I96F32]) -> Vec<u16> {
     let u16_max = I96F32::from_num(u16::MAX);
     let threshold = I96F32::from_num(32768);
@@ -797,9 +798,10 @@ pub fn inplace_col_max_upscale_sparse(sparse_matrix: &mut [Vec<(u16, I96F32)>],
 #[cfg(test)]
 #[allow(clippy::arithmetic_side_effects, clippy::indexing_slicing)]
 mod tests {
-    use super::*;
     use substrate_fixed::types::{I96F32, U64F64};
 
+    use super::*;
+
     macro_rules! fixed_vec {
         () => {
             vec![]
@@ -809,7 +811,8 @@ mod tests {
         };
     }
 
-    /// Reshape vector to sparse matrix with specified number of input rows, cast f32 to I96F32.
+    /// Reshape vector to sparse matrix with specified number of input rows,
+    /// cast f32 to I96F32.
     fn vec_to_sparse_mat_fixed(
         vector: &[f32],
         rows: usize,

pallets/emission0/src/lib.rs

@@ -6,12 +6,13 @@ pub mod migrations;
 pub(crate) use ext::*;
 pub use pallet::*;
 use pallet_emission0_api::Emission0Api;
-use polkadot_sdk::frame_support::dispatch::DispatchResult;
-use polkadot_sdk::frame_support::{pallet_prelude::*, DefaultNoBound};
-use polkadot_sdk::frame_system;
-use polkadot_sdk::frame_system::pallet_prelude::OriginFor;
-use polkadot_sdk::polkadot_sdk_frame::{self as frame, traits::Currency};
-use polkadot_sdk::sp_runtime::Percent;
+use polkadot_sdk::{
+    frame_support::{dispatch::DispatchResult, pallet_prelude::*, DefaultNoBound},
+    frame_system,
+    frame_system::pallet_prelude::OriginFor,
+    polkadot_sdk_frame::{self as frame, traits::Currency},
+    sp_runtime::Percent,
+};
 
 #[doc(hidden)]
 pub mod distribute;
@@ -36,33 +37,48 @@ pub mod pallet {
 
     use super::*;
 
+    /// Map of consensus members indexed by their keys. A consensus member is
+    /// any agent eligible for emissions in the next epoch. This means
+    /// unregistered agents will also receive emissions.
     #[pallet::storage]
     pub type ConsensusMembers<T: Config> =
         StorageMap<_, Identity, AccountIdOf<T>, ConsensusMember<T>>;
 
+    /// Map of agents delegating weight control to other agents. Emissions
+    /// derived from weight delegation are taxed and the fees go the original
+    /// weight setter.
     #[pallet::storage]
     pub type WeightControlDelegation<T: Config> =
         StorageMap<_, Identity, T::AccountId, T::AccountId>;
 
+    // TODO: remove
     #[pallet::storage]
     pub type MinAllowedWeights<T: Config> =
         StorageValue<_, u16, ValueQuery, T::DefaultMinAllowedWeights>;
 
+    /// Maximum number of weights a validator can set.
     #[pallet::storage]
     pub type MaxAllowedWeights<T: Config> =
         StorageValue<_, u16, ValueQuery, T::DefaultMaxAllowedWeights>;
 
+    // TODO: cap weights on distribution.
+    /// Minimum stake a validator needs for each weight it sets.
     #[pallet::storage]
     pub type MinStakePerWeight<T> = StorageValue<_, BalanceOf<T>, ValueQuery>;
 
+    /// Percentage of issued tokens to be burned every epoch.
     #[pallet::storage]
     pub type EmissionRecyclingPercentage<T: Config> =
         StorageValue<_, Percent, ValueQuery, T::DefaultEmissionRecyclingPercentage>;
 
+    /// Ratio between incentives and dividends on distribution. 50% means they
+    /// are distributed equally.
     #[pallet::storage]
     pub type IncentivesRatio<T: Config> =
         StorageValue<_, Percent, ValueQuery, T::DefaultIncentivesRatio>;
 
+    /// Amount of tokens accumulated since the last epoch. This increases on
+    /// every block. See [`distribute::get_total_emission_per_block`].
     #[pallet::storage]
     pub type PendingEmission<T: Config> = StorageValue<_, BalanceOf<T>, ValueQuery>;
 
@@ -79,7 +95,8 @@ pub mod pallet {
         #[pallet::constant]
         type MaxSupply: Get<NonZeroU128>;
 
-        /// Emissions per block in NANOs. Not taking into account halving and recycling.
+        /// Emissions per block in NANOs. Not taking into account halving and
+        /// recycling.
         #[pallet::constant]
         type BlockEmission: Get<u128>;
 
@@ -156,7 +173,6 @@ pub mod pallet {
 
     #[pallet::call]
     impl<T: Config> Pallet<T> {
-        // TODO: configure price
         #[pallet::call_index(0)]
         #[pallet::weight((T::WeightInfo::set_weights(), DispatchClass::Normal, Pays::Yes))]
         pub fn set_weights(

pallets/emission0/src/migrations.rs

@@ -9,7 +9,6 @@ use crate::{Config, Pallet};
 
 pub mod v1 {
     use super::*;
-
     use crate::{EmissionRecyclingPercentage, IncentivesRatio};
 
     pub type Migration<T, W> = VersionedMigration<0, 1, MigrateToV1<T>, Pallet<T>, W>;