add docstrings in sequencer crate modules

crates/sequencer/Cargo.toml

@@ -24,12 +24,3 @@ tracing.workspace = true
 
 [dev-dependencies]
 strata-test-utils.workspace = true
-
-[lints]
-rust.missing_debug_implementations = "warn"
-# rust.missing_docs = "warn"
-rust.rust_2018_idioms = { level = "deny", priority = -1 }
-rust.unreachable_pub = "warn"
-rust.unused_crate_dependencies = "deny"
-rust.unused_must_use = "deny"
-# rustdoc.all = "warn"

crates/sequencer/src/block_template/block_assembly.rs

@@ -1,5 +1,6 @@
 use std::{thread, time};
 
+// TODO: use local error type
 use strata_consensus_logic::errors::Error;
 use strata_db::traits::{ChainstateDatabase, Database, L1Database};
 use strata_eectl::{

crates/sequencer/src/block_template/error.rs

@@ -2,22 +2,32 @@ use strata_db::DbError;
 use strata_primitives::l2::L2BlockId;
 use thiserror::Error;
 
+/// Possible errors during block assembly and block template handling.
 #[derive(Debug, Error)]
 pub enum Error {
+    /// Block generate was requested with timestamp earlier than acceptable.
     #[error("block timestamp too early: {0}")]
     TimestampTooEarly(u64),
+    /// Request with an unknown template id.
     #[error("unknown templateid: {0}")]
     UnknownTemplateId(L2BlockId),
+    /// Provided signature invalid for block template.
     #[error("invalid signature supplied for templateid: {0}")]
     InvalidSignature(L2BlockId),
+    /// Could not send request to worker on channel due to rx being closed.
     #[error("failed to send request, template worker exited")]
     RequestChannelClosed,
+    /// Could not receive response from worker on channel due to response tx being closed.
     #[error("failed to get response, template worker exited")]
     ResponseChannelClosed,
+    /// Could not send message to FCM.
     #[error("failed to send fcm message, fcm worker exited")]
     FcmChannelClosed,
+    /// Database Error.
     #[error("db: {0}")]
     DbError(#[from] DbError),
+    /// Consensus Error.
+    /// TODO: remove this and use local error variants
     #[error("consensus: {0}")]
     ConsensusError(#[from] strata_consensus_logic::errors::Error),
 }

crates/sequencer/src/block_template/handle.rs

@@ -26,6 +26,7 @@ pub enum TemplateManagerRequest {
     ),
 }
 
+/// Handle for communication with the template manager worker.
 #[allow(missing_debug_implementations)]
 pub struct TemplateManagerHandle {
     tx: mpsc::Sender<TemplateManagerRequest>,
@@ -35,6 +36,7 @@ pub struct TemplateManagerHandle {
 }
 
 impl TemplateManagerHandle {
+    /// Create new instance.
     pub fn new(
         tx: mpsc::Sender<TemplateManagerRequest>,
         shared: SharedState,
@@ -66,6 +68,8 @@ impl TemplateManagerHandle {
         }
     }
 
+    /// Generate a new block template based on provided [`BlockGenerationConfig`].
+    /// Will return cached template for request if it exists.
     pub async fn generate_block_template(
         &self,
         config: BlockGenerationConfig,
@@ -84,6 +88,7 @@ impl TemplateManagerHandle {
             .await
     }
 
+    /// Complete specified template with [`BlockCompletionData`] and submit to FCM.
     pub async fn complete_block_template(
         &self,
         template_id: L2BlockId,
@@ -112,6 +117,7 @@ impl TemplateManagerHandle {
         Ok(template_id)
     }
 
+    /// Get a pending block template from cache if it exists.
     pub async fn get_block_template(&self, template_id: L2BlockId) -> Result<BlockTemplate, Error> {
         self.shared
             .read()

crates/sequencer/src/block_template/mod.rs

@@ -1,3 +1,5 @@
+//! Block template management for block assembly.
+
 mod block_assembly;
 mod error;
 mod handle;

crates/sequencer/src/block_template/types.rs

@@ -5,7 +5,11 @@ use strata_state::{
     header::{L2BlockHeader, L2Header, SignedL2BlockHeader},
 };
 
-/// Block template with header, body, and accessory.
+/// Represents a complete block template containing header, body, and accessory data
+///
+/// A full block template is an intermediate representation of a block that hasn't been
+/// finalized/signed yet. It contains all the components needed to create a complete
+/// L2BlockBundle once signing is complete.
 #[derive(Debug, Clone)]
 pub struct FullBlockTemplate {
     header: L2BlockHeader,
@@ -14,6 +18,7 @@ pub struct FullBlockTemplate {
 }
 
 impl FullBlockTemplate {
+    /// Creates a new full block template from its components.
     pub fn new(header: L2BlockHeader, body: L2BlockBody, accessory: L2BlockAccessory) -> Self {
         Self {
             header,
@@ -22,14 +27,17 @@ impl FullBlockTemplate {
         }
     }
 
+    /// Retrieves the block identifier from the header.
     pub fn get_blockid(&self) -> L2BlockId {
         self.header.get_blockid()
     }
 
+    /// Returns a reference to the block header.
     pub fn header(&self) -> &L2BlockHeader {
         &self.header
     }
 
+    /// Accepts signature and finalizes the template into a signed L2BlockBundle.
     pub fn complete_block_template(self, completion: BlockCompletionData) -> L2BlockBundle {
         let FullBlockTemplate {
             header,
@@ -51,36 +59,44 @@ pub struct BlockTemplate {
 }
 
 impl BlockTemplate {
+    /// Returns the ID of the template (equivalent to resulting L2 block ID).
     pub fn template_id(&self) -> L2BlockId {
         self.header.get_blockid()
     }
 
+    /// Returns a reference to the L2 block header.
     pub fn header(&self) -> &L2BlockHeader {
         &self.header
     }
 
+    /// Create from full block template.
     pub fn from_full_ref(full: &FullBlockTemplate) -> Self {
         Self {
             header: full.header.clone(),
         }
     }
 }
 
+/// Sufficient data to complete a [`FullBlockTemplate`] and create a [`L2BlockBundle`].
+/// Currently consists of a valid signature for the block from sequencer.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct BlockCompletionData {
     signature: Buf64,
 }
 
 impl BlockCompletionData {
+    /// Create from signature.
     pub fn from_signature(signature: Buf64) -> Self {
         Self { signature }
     }
 
+    /// Returns a reference to signature.
     pub fn signature(&self) -> &Buf64 {
         &self.signature
     }
 }
 
+/// Configuration provided by sequencer for the new block to be assembled.
 #[derive(Debug, Clone, Default, Serialize, Deserialize, Hash, Eq, PartialEq)]
 pub struct BlockGenerationConfig {
     parent_block_id: L2BlockId,
@@ -91,22 +107,26 @@ pub struct BlockGenerationConfig {
 }
 
 impl BlockGenerationConfig {
+    /// Create new instance with provided parent block id.
     pub fn from_parent_block_id(parent_block_id: L2BlockId) -> Self {
         Self {
             parent_block_id,
             ..Default::default()
         }
     }
 
+    /// Update with provided block timestamp.
     pub fn with_ts(mut self, ts: u64) -> Self {
         self.ts = Some(ts);
         self
     }
 
+    /// Return parent block id.
     pub fn parent_block_id(&self) -> L2BlockId {
         self.parent_block_id
     }
 
+    /// Return block timestamp.
     pub fn ts(&self) -> &Option<u64> {
         &self.ts
     }

crates/sequencer/src/block_template/worker.rs

@@ -36,6 +36,7 @@ pub struct WorkerContext<D, E> {
 }
 
 impl<D, E> WorkerContext<D, E> {
+    /// Create new worker context.
     pub fn new(
         params: Arc<Params>,
         database: Arc<D>,
@@ -95,6 +96,7 @@ impl WorkerState {
     }
 }
 
+/// State of worker shared between worker task and handle.
 pub type SharedState = Arc<RwLock<WorkerState>>;
 
 /// Block template worker task.

crates/sequencer/src/checkpoint/expiry.rs

@@ -1,3 +1,5 @@
+//! Handle timeouts for checkpoints in ProofPublishMode::Timeout
+
 use std::{cmp::Reverse, collections::BinaryHeap, sync::Arc};
 
 use strata_db::types::CheckpointProvingStatus;

crates/sequencer/src/checkpoint/helper.rs

@@ -1,6 +1,9 @@
+//! reusable utils.
+
 use strata_primitives::params::Params;
 use strata_state::{batch::SignedBatchCheckpoint, block_validation::verify_sequencer_signature};
 
+/// Verify checkpoint has correct signature from sequencer.
 pub fn verify_checkpoint_sig(signed_checkpoint: &SignedBatchCheckpoint, params: &Params) -> bool {
     let msg = signed_checkpoint.checkpoint().hash();
     let sig = signed_checkpoint.signature();

crates/sequencer/src/checkpoint/mod.rs

@@ -1,3 +1,5 @@
+//! Checkpoint generation and expiry.
+
 pub mod checkpoint_handle;
 pub mod expiry;
 pub mod helper;

crates/sequencer/src/checkpoint/worker.rs

@@ -1,3 +1,5 @@
+//! worker to monitor chainstate and create checkpoint entries.
+
 use std::sync::Arc;
 
 use strata_consensus_logic::csm::message::ClientUpdateNotif;

crates/sequencer/src/duty/errors.rs

@@ -1,13 +1,16 @@
-//! common error types for sequencer duty
+//! Common error types for sequencer duty.
 
 use strata_state::id::L2BlockId;
 use thiserror::Error;
 
+/// Errors used in sequencer duty.
 #[derive(Debug, Error)]
 pub enum Error {
+    /// L2 block not found in db.
     #[error("L2 blkid {0:?} missing from database")]
     MissingL2Block(L2BlockId),
 
+    /// Other db error.
     #[error("db: {0}")]
     Db(#[from] strata_db::errors::DbError),
 }

crates/sequencer/src/duty/types.rs

@@ -97,14 +97,17 @@ pub struct BatchCheckpointDuty {
 }
 
 impl BatchCheckpointDuty {
+    /// Create new duty from [`BatchCheckpoint`]
     pub fn new(checkpoint: BatchCheckpoint) -> Self {
         Self { checkpoint }
     }
 
+    /// Gen checkpoint index.
     pub fn idx(&self) -> u64 {
         self.checkpoint.batch_info().idx()
     }
 
+    /// Get reference to checkpoint.
     pub fn checkpoint(&self) -> &BatchCheckpoint {
         &self.checkpoint
     }
@@ -202,10 +205,12 @@ impl DutyTracker {
         }));
     }
 
+    /// Sets the finalized block.
     pub fn set_finalized_block(&mut self, blkid: Option<L2BlockId>) {
         self.finalized_block = blkid;
     }
 
+    /// Get finalized block.
     pub fn get_finalized_block(&self) -> Option<L2BlockId> {
         self.finalized_block
     }
@@ -216,6 +221,7 @@ impl DutyTracker {
     }
 }
 
+/// Represents a single duty inside duty tracker.
 #[derive(Clone, Debug)]
 pub struct DutyEntry {
     /// Duty data itself.
@@ -232,10 +238,12 @@ pub struct DutyEntry {
 }
 
 impl DutyEntry {
+    /// Get reference to Duty.
     pub fn duty(&self) -> &Duty {
         &self.duty
     }
 
+    /// Get duty ID.
     pub fn id(&self) -> Buf32 {
         self.id
     }
@@ -297,6 +305,7 @@ pub enum Identity {
     Sequencer(Buf32),
 }
 
+/// Represents a group of duties created from a single sync event.
 #[derive(Clone, Debug)]
 pub struct DutyBatch {
     sync_ev_idx: u64,
@@ -323,6 +332,7 @@ impl DutyBatch {
 /// Sequencer key used for signing-related duties.
 #[derive(Clone, Debug, BorshDeserialize, BorshSerialize)]
 pub enum IdentityKey {
+    /// Sequencer pubkey
     Sequencer(Buf32),
 }
 

crates/sequencer/src/duty/worker.rs

@@ -21,6 +21,7 @@ use crate::{
     },
 };
 
+/// Watch client state updates and generate sequencer duties.
 pub fn duty_tracker_task<D: Database>(
     shutdown: ShutdownGuard,
     duty_tracker: Arc<RwLock<DutyTracker>>,

crates/sequencer/src/utils.rs

@@ -1,5 +1,8 @@
+//! reusable utilities.
+
 use std::time;
 
+/// Returns the current time in milliseconds since UNIX_EPOCH.
 pub fn now_millis() -> u64 {
     time::UNIX_EPOCH.elapsed().unwrap().as_millis() as u64
 }