docs enhancement

protocols/v2/roles-logic-sv2/src/channel_logic/channel_factory.rs

@@ -1,4 +1,6 @@
-//! Contains logic for creating channels.
+//! # Channel Factory
+//!
+//! This module contains logic for creating and managing channels.
 
 use super::extended_to_standard_job;
 use crate::{
@@ -76,7 +78,7 @@ pub enum OnNewShare {
 }
 
 impl OnNewShare {
-    /// Convert standard share into extended share
+    /// Converts standard share into extended share
     pub fn into_extended(&mut self, extranonce: Vec<u8>, up_id: u32) {
         match self {
             OnNewShare::SendErrorDownstream(_) => (),
@@ -139,7 +141,7 @@ pub struct StagedPhash {
 }
 
 impl StagedPhash {
-    /// converts a Staged PrevHash into a SetNewPrevHash message
+    /// Converts a Staged PrevHash into a SetNewPrevHash message
     pub fn into_set_p_hash(
         &self,
         channel_id: u32,
@@ -156,47 +158,47 @@ impl StagedPhash {
 }
 
 impl Share {
-    /// get share sequence number
+    /// Get share sequence number
     pub fn get_sequence_number(&self) -> u32 {
         match self {
             Share::Extended(s) => s.sequence_number,
             Share::Standard(s) => s.0.sequence_number,
         }
     }
 
-    /// get share channel id
+    /// Get share channel id
     pub fn get_channel_id(&self) -> u32 {
         match self {
             Share::Extended(s) => s.channel_id,
             Share::Standard(s) => s.0.channel_id,
         }
     }
 
-    /// get share timestamp
+    /// Get share timestamp
     pub fn get_n_time(&self) -> u32 {
         match self {
             Share::Extended(s) => s.ntime,
             Share::Standard(s) => s.0.ntime,
         }
     }
 
-    /// get share nonce
+    /// Get share nonce
     pub fn get_nonce(&self) -> u32 {
         match self {
             Share::Extended(s) => s.nonce,
             Share::Standard(s) => s.0.nonce,
         }
     }
 
-    /// get share job id
+    /// Get share job id
     pub fn get_job_id(&self) -> u32 {
         match self {
             Share::Extended(s) => s.job_id,
             Share::Standard(s) => s.0.job_id,
         }
     }
 
-    /// get share version
+    /// Get share version
     pub fn get_version(&self) -> u32 {
         match self {
             Share::Extended(s) => s.version,
@@ -976,7 +978,7 @@ impl ChannelFactory {
             },
         }
     }
-    /// updates the downstream target for the given channel_id
+    /// Updates the downstream target for the given channel_id
     fn update_target_for_channel(&mut self, channel_id: u32, new_target: Target) -> Option<bool> {
         let channel = self.extended_channels.get_mut(&channel_id)?;
         channel.target = new_target.into();
@@ -1292,12 +1294,12 @@ impl PoolChannelFactory {
         true
     }
 
-    /// get extended channel ids
+    /// Get extended channel ids
     pub fn get_extended_channels_ids(&self) -> Vec<u32> {
         self.inner.extended_channels.keys().copied().collect()
     }
 
-    /// update coinbase outputs
+    /// Update coinbase outputs
     pub fn update_pool_outputs(&mut self, outs: Vec<TxOut>) {
         self.pool_coinbase_outputs = outs;
     }
@@ -1331,7 +1333,7 @@ pub struct ProxyExtendedChannelFactory {
 }
 
 impl ProxyExtendedChannelFactory {
-    /// constructor
+    /// Constructor
     #[allow(clippy::too_many_arguments)]
     pub fn new(
         ids: Arc<Mutex<GroupId>>,
@@ -1520,7 +1522,7 @@ impl ProxyExtendedChannelFactory {
 
     /// Called when a `SubmitSharesStandard` message is received from the downstream. We check the
     /// shares against the channel's respective target and return `OnNewShare` to let us know if
-    /// and where the the shares should be relayed
+    /// and where the shares should be relayed
     pub fn on_submit_shares_extended(
         &mut self,
         m: SubmitSharesExtended<'static>,
@@ -1723,12 +1725,12 @@ impl ProxyExtendedChannelFactory {
         self.inner.on_new_extended_mining_job(m)
     }
 
-    /// set new target
+    /// Set new target
     pub fn set_target(&mut self, new_target: &mut Target) {
         self.inner.kind.set_target(new_target);
     }
 
-    /// get last valid job version
+    /// Get last valid job version
     pub fn last_valid_job_version(&self) -> Option<u32> {
         self.inner.last_valid_job.as_ref().map(|j| j.0.version)
     }
@@ -1752,44 +1754,44 @@ impl ProxyExtendedChannelFactory {
             .map(|f| f.0.prev_hash.clone())
     }
 
-    /// last min ntime
+    /// Get last min ntime
     pub fn last_min_ntime(&self) -> Option<u32> {
         self.inner.last_prev_hash.as_ref().map(|f| f.0.min_ntime)
     }
 
-    /// last nbits
+    /// Get last nbits
     pub fn last_nbits(&self) -> Option<u32> {
         self.inner.last_prev_hash.as_ref().map(|f| f.0.nbits)
     }
 
-    /// extranonce_size
+    /// Get extranonce_size
     pub fn extranonce_size(&self) -> usize {
         self.inner.extranonces.get_len()
     }
 
-    /// extranonce_2 size
+    /// Get extranonce_2 size
     pub fn channel_extranonce2_size(&self) -> usize {
         self.inner.extranonces.get_len() - self.inner.extranonces.get_range0_len()
     }
 
     // Only used when the proxy is using Job Declaration
-    /// update pool outputs
+    /// Updates pool outputs
     pub fn update_pool_outputs(&mut self, outs: Vec<TxOut>) {
         self.pool_coinbase_outputs = Some(outs);
     }
 
-    /// get this channel id
+    /// Get this channel id
     pub fn get_this_channel_id(&self) -> u32 {
         self.extended_channel_id
     }
 
-    /// returns the extranonce1 len of the upstream. For a proxy, this would
+    /// Returns the extranonce1 len of the upstream. For a proxy, this would
     /// be the extranonce_prefix len
     pub fn get_upstream_extranonce1_len(&self) -> usize {
         self.inner.extranonces.get_range0_len()
     }
 
-    /// calls [`ChannelFactory::update_target_for_channel`]
+    /// Calls [`ChannelFactory::update_target_for_channel`]
     pub fn update_target_for_channel(
         &mut self,
         channel_id: u32,
@@ -1807,7 +1809,7 @@ pub enum ExtendedChannelKind {
     Pool,
 }
 impl ExtendedChannelKind {
-    /// set target
+    /// Set target
     pub fn set_target(&mut self, new_target: &mut Target) {
         match self {
             ExtendedChannelKind::Proxy { upstream_target }

protocols/v2/roles-logic-sv2/src/channel_logic/mod.rs

@@ -1,3 +1,5 @@
+//! # Channel Logic
+//!
 //! A module for managing channels on applications.
 //!
 //! Divided in two submodules:
@@ -10,7 +12,7 @@ pub mod proxy_group_channel;
 use mining_sv2::{NewExtendedMiningJob, NewMiningJob};
 use std::convert::TryInto;
 
-/// convert extended to standard job by calculating the merkle root
+/// Convert extended to standard job by calculating the merkle root
 pub fn extended_to_standard_job<'a>(
     extended: &NewExtendedMiningJob,
     coinbase_script: &[u8],

protocols/v2/roles-logic-sv2/src/channel_logic/proxy_group_channel.rs

@@ -1,4 +1,6 @@
-//! Contains logic for managing Standard Channels via Group Channels.
+//! # Proxy Group Channel
+//!
+//! This module contains logic for managing Standard Channels via Group Channels.
 
 use crate::{common_properties::StandardChannel, parsers::Mining, Error};
 
@@ -10,13 +12,13 @@ use super::extended_to_standard_job;
 use nohash_hasher::BuildNoHashHasher;
 use std::collections::HashMap;
 
-/// wrapper around `GroupChannel` for managing multiple group channels
+/// Wrapper around `GroupChannel` for managing multiple group channels
 #[derive(Debug, Clone, Default)]
 pub struct GroupChannels {
     channels: HashMap<u32, GroupChannel>,
 }
 impl GroupChannels {
-    /// constructor
+    /// Constructor
     pub fn new() -> Self {
         Self {
             channels: HashMap::new(),
@@ -74,7 +76,7 @@ impl GroupChannels {
         }
     }
 
-    /// get group channel ids
+    /// Get group channel ids
     pub fn ids(&self) -> Vec<u32> {
         self.channels.keys().copied().collect()
     }

protocols/v2/roles-logic-sv2/src/common_properties.rs

@@ -18,32 +18,28 @@ use std::{collections::HashMap, fmt::Debug as D};
 pub struct CommonDownstreamData {
     /// Header-only mining flag.
     ///
-    /// Enables the processing of block headers only, leaving transaction management and template
-    /// construction to the upstream node. It reduces the amount of data processed and transmitted
-    /// by the downstream node, making it useful when bandwidth is limited and transmitting full
-    /// block templates is costly.
+    /// Enables the processing of standard jobs only, leaving merkle root manipulation to the
+    /// upstream node.
     ///
-    /// - `true`: The downstream node only processes block headers, relying on the upstream for
-    ///   transaction management.
-    /// - `false`: The downstream node handles full blocks.
+    /// - `true`: The downstream node only processes standard jobs, relying on the upstream for
+    ///   merkle root manipulation.
+    /// - `false`: The downstream node handles extended jobs and merkle root manipulation.
     pub header_only: bool,
 
     /// Work selection flag.
     ///
-    /// Enables the selection of which transactions or templates the node will work on. It allows
-    /// for more autonomy for downstream nodes to define specific version bits to roll, adjust the
-    /// difficulty target, apply `timestamp` range constraints, etc.
+    /// Enables the selection of which transactions or templates the node will work on.
     ///
-    /// - `true`: The downstream node can modify or customize the mining job, such as choosing
-    ///   specific transactions to include in a block template.
-    /// - `false`: The downstream node strictly follows the work provided by the upstream, such as
-    ///   pre-constructed templates from a pool.
+    /// - `true`: The downstream node works on a custom block template, using the Job Declaration
+    ///   Protocol.
+    /// - `false`: The downstream node strictly follows the work provided by the upstream, based on
+    ///   pre-constructed templates from the upstream (e.g. Pool).
     pub work_selection: bool,
 
     /// Version rolling flag.
     ///
     /// Enables rolling the block header version bits which allows for more unique hash generation
-    /// on the same block template by expanding the nonce-space. Used when other fields (e.g.
+    /// on the same mining job by expanding the nonce-space. Used when other fields (e.g.
     /// `nonce` or `extranonce`) are fully exhausted.
     ///
     /// - `true`: The downstream supports version rolling and can modify specific bits in the
@@ -60,7 +56,7 @@ pub struct CommonDownstreamData {
 /// range, and flag settings.
 #[derive(Debug, Copy, Clone)]
 pub struct PairSettings {
-    /// Role the settings apply to.
+    /// Protocol the settings apply to.
     pub protocol: Protocol,
 
     /// Minimum protocol version the node supports.
@@ -70,7 +66,7 @@ pub struct PairSettings {
     pub max_v: u16,
 
     /// Flags indicating optional protocol features the node supports (e.g. header-only mining,
-    /// Noise protocol support, job configuration parameters, etc.). Each protocol field as its own
+    /// work selection, version-rolling, etc.). Each protocol field as its own
     /// flags.
     pub flags: u32,
 }
@@ -122,8 +118,9 @@ pub enum UpstreamChannel {
 
     /// A grouped channel for aggregated mining.
     ///
-    /// Aggregates mining work for multiple devices or clients under a single channel, enabling the
-    /// upstream to manage work distribution and result aggregation for an entire group of miners.
+    /// Aggregates mining work for multiple standard channels under a single group channel,
+    /// enabling the upstream to manage work distribution and result aggregation for an entire
+    /// group of channels.
     ///
     /// Typically used by a mining proxy managing multiple downstream miners.
     Group,
@@ -138,7 +135,7 @@ pub enum UpstreamChannel {
 /// Properties of a standard mining channel.
 ///
 /// Standard channels are intended to be used by end mining devices with a nominal hashrate, where
-/// each device operates on an independent connection to its upstream.
+/// each device operates on an independent channel to its upstream.
 #[derive(Debug, Clone)]
 pub struct StandardChannel {
     /// Identifies a specific channel, unique to each mining connection.
@@ -148,7 +145,7 @@ pub struct StandardChannel {
     /// the same upstream node. The identifier remains stable for the whole lifetime of the
     /// connection.
     ///
-    /// Used for broadcasting new jobs by [`mining_sv2::NewExtendedMiningJob`].
+    /// Used for broadcasting new jobs by [`mining_sv2::NewMiningJob`].
     pub channel_id: u32,
 
     /// Identifies a specific group in which the standard channel belongs.

protocols/v2/roles-logic-sv2/src/errors.rs

@@ -1,4 +1,7 @@
-//! Errors specific to this crate
+//! # Error Handling
+//!
+//! This module defines error types and utilities for handling errors in the `roles_logic_sv2`
+//! module. It includes the [`Error`] enum for representing various errors.
 
 use crate::{
     common_properties::CommonDownstreamData, parsers::PoolMessages as AllMessages,