diff --git a/crates/sequencer/Cargo.toml b/crates/sequencer/Cargo.toml index 63f412e34..2252792df 100644 --- a/crates/sequencer/Cargo.toml +++ b/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" diff --git a/crates/sequencer/src/block_template/block_assembly.rs b/crates/sequencer/src/block_template/block_assembly.rs index 4a9113492..9b47e0dfb 100644 --- a/crates/sequencer/src/block_template/block_assembly.rs +++ b/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::{ diff --git a/crates/sequencer/src/block_template/error.rs b/crates/sequencer/src/block_template/error.rs index 66ea31f9d..48cd55896 100644 --- a/crates/sequencer/src/block_template/error.rs +++ b/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), } diff --git a/crates/sequencer/src/block_template/handle.rs b/crates/sequencer/src/block_template/handle.rs index 8cfde761c..176a51ed7 100644 --- a/crates/sequencer/src/block_template/handle.rs +++ b/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, @@ -35,6 +36,7 @@ pub struct TemplateManagerHandle { } impl TemplateManagerHandle { + /// Create new instance. pub fn new( tx: mpsc::Sender, 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 { self.shared .read() diff --git a/crates/sequencer/src/block_template/mod.rs b/crates/sequencer/src/block_template/mod.rs index c4f358aae..57876651b 100644 --- a/crates/sequencer/src/block_template/mod.rs +++ b/crates/sequencer/src/block_template/mod.rs @@ -1,3 +1,5 @@ +//! Block template management for block assembly. + mod block_assembly; mod error; mod handle; diff --git a/crates/sequencer/src/block_template/types.rs b/crates/sequencer/src/block_template/types.rs index 7269bf473..016e4132d 100644 --- a/crates/sequencer/src/block_template/types.rs +++ b/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,14 +59,17 @@ 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(), @@ -66,21 +77,26 @@ impl BlockTemplate { } } +/// 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,6 +107,7 @@ 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, @@ -98,15 +115,18 @@ impl BlockGenerationConfig { } } + /// 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 { &self.ts } diff --git a/crates/sequencer/src/block_template/worker.rs b/crates/sequencer/src/block_template/worker.rs index 8cea86c04..a16065eb6 100644 --- a/crates/sequencer/src/block_template/worker.rs +++ b/crates/sequencer/src/block_template/worker.rs @@ -36,6 +36,7 @@ pub struct WorkerContext { } impl WorkerContext { + /// Create new worker context. pub fn new( params: Arc, database: Arc, @@ -95,6 +96,7 @@ impl WorkerState { } } +/// State of worker shared between worker task and handle. pub type SharedState = Arc>; /// Block template worker task. diff --git a/crates/sequencer/src/checkpoint/expiry.rs b/crates/sequencer/src/checkpoint/expiry.rs index b53e66a30..93b5e6c29 100644 --- a/crates/sequencer/src/checkpoint/expiry.rs +++ b/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; diff --git a/crates/sequencer/src/checkpoint/helper.rs b/crates/sequencer/src/checkpoint/helper.rs index 19d3c8dcd..c1ddc005c 100644 --- a/crates/sequencer/src/checkpoint/helper.rs +++ b/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(); diff --git a/crates/sequencer/src/checkpoint/mod.rs b/crates/sequencer/src/checkpoint/mod.rs index 3a523aecc..ef8cccefa 100644 --- a/crates/sequencer/src/checkpoint/mod.rs +++ b/crates/sequencer/src/checkpoint/mod.rs @@ -1,3 +1,5 @@ +//! Checkpoint generation and expiry. + pub mod checkpoint_handle; pub mod expiry; pub mod helper; diff --git a/crates/sequencer/src/checkpoint/worker.rs b/crates/sequencer/src/checkpoint/worker.rs index c47e92175..871aef95c 100644 --- a/crates/sequencer/src/checkpoint/worker.rs +++ b/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; diff --git a/crates/sequencer/src/duty/errors.rs b/crates/sequencer/src/duty/errors.rs index b2aa2f90d..7af4c3dc9 100644 --- a/crates/sequencer/src/duty/errors.rs +++ b/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), } diff --git a/crates/sequencer/src/duty/types.rs b/crates/sequencer/src/duty/types.rs index 28eab861a..1fa687368 100644 --- a/crates/sequencer/src/duty/types.rs +++ b/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) { self.finalized_block = blkid; } + /// Get finalized block. pub fn get_finalized_block(&self) -> Option { 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), } diff --git a/crates/sequencer/src/duty/worker.rs b/crates/sequencer/src/duty/worker.rs index 6df8d9a53..c2e8993d1 100644 --- a/crates/sequencer/src/duty/worker.rs +++ b/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( shutdown: ShutdownGuard, duty_tracker: Arc>, diff --git a/crates/sequencer/src/utils.rs b/crates/sequencer/src/utils.rs index e6f1dfabb..b29ab8740 100644 --- a/crates/sequencer/src/utils.rs +++ b/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 }