chore(derive): Error Exports (#758)

* feat: clean exports

* fix: lints

* feat: error re-exports

* touchups

bin/client/src/l1/driver.rs

@@ -13,15 +13,15 @@ use core::fmt::Debug;
 use kona_derive::{
     attributes::StatefulAttributesBuilder,
     errors::{PipelineErrorKind, ResetError},
-    pipeline::{DerivationPipeline, Pipeline, PipelineBuilder, StepResult},
+    pipeline::{DerivationPipeline, PipelineBuilder},
     sources::EthereumDataSource,
     stages::{
         AttributesQueue, BatchProvider, BatchStream, ChannelProvider, ChannelReader, FrameQueue,
         L1Retrieval, L1Traversal,
     },
     traits::{
-        ActivationSignal, BlobProvider, ChainProvider, L2ChainProvider, OriginProvider,
-        ResetSignal, Signal, SignalReceiver,
+        ActivationSignal, BlobProvider, ChainProvider, L2ChainProvider, OriginProvider, Pipeline,
+        ResetSignal, Signal, SignalReceiver, StepResult,
     },
 };
 use kona_executor::{KonaHandleRegister, StatelessL2BlockExecutor};

crates/derive/src/errors/attributes.rs

@@ -0,0 +1,34 @@
+//! Error types for kona's attributes builder.
+
+use alloc::string::String;
+use alloy_eips::BlockNumHash;
+use alloy_primitives::B256;
+
+/// An [AttributesBuilder] Error.
+///
+/// [AttributesBuilder]: crate::traits::AttributesBuilder
+#[derive(derive_more::Display, Clone, Debug, PartialEq, Eq)]
+pub enum BuilderError {
+    /// Mismatched blocks.
+    #[display("Block mismatch. Expected {_0:?}, got {_1:?}")]
+    BlockMismatch(BlockNumHash, BlockNumHash),
+    /// Mismatched blocks for the start of an Epoch.
+    #[display("Block mismatch on epoch reset. Expected {_0:?}, got {_1:?}")]
+    BlockMismatchEpochReset(BlockNumHash, BlockNumHash, B256),
+    /// [SystemConfig] update failed.
+    ///
+    /// [SystemConfig]: op_alloy_genesis::SystemConfig
+    #[display("System config update failed")]
+    SystemConfigUpdate,
+    /// Broken time invariant between L2 and L1.
+    #[display("Time invariant broken. L1 origin: {_0:?} | Next L2 time: {_1} | L1 block: {_2:?} | L1 timestamp {_3:?}")]
+    BrokenTimeInvariant(BlockNumHash, u64, BlockNumHash, u64),
+    /// Attributes unavailable.
+    #[display("Attributes unavailable")]
+    AttributesUnavailable,
+    /// A custom error.
+    #[display("Error in attributes builder: {_0}")]
+    Custom(String),
+}
+
+impl core::error::Error for BuilderError {}

crates/derive/src/errors/mod.rs

@@ -0,0 +1,15 @@
+//! Error types for the kona derivation pipeline.
+
+mod attributes;
+pub use attributes::BuilderError;
+
+mod stages;
+pub use stages::BatchDecompressionError;
+
+mod pipeline;
+pub use pipeline::{
+    PipelineEncodingError, PipelineError, PipelineErrorKind, PipelineResult, ResetError,
+};
+
+mod sources;
+pub use sources::{BlobDecodingError, BlobProviderError};

crates/derive/src/errors.rs → crates/derive/src/errors/pipeline.rs

@@ -1,29 +1,10 @@
 //! This module contains derivation errors thrown within the pipeline.
 
+use crate::errors::BuilderError;
 use alloc::string::String;
-use alloy_eips::BlockNumHash;
 use alloy_primitives::B256;
 use op_alloy_genesis::system::SystemConfigUpdateError;
-use op_alloy_protocol::{DepositError, SpanBatchError, MAX_SPAN_BATCH_ELEMENTS};
-
-/// Blob Decuding Error
-#[derive(derive_more::Display, Debug, PartialEq, Eq)]
-pub enum BlobDecodingError {
-    /// Invalid field element
-    #[display("Invalid field element")]
-    InvalidFieldElement,
-    /// Invalid encoding version
-    #[display("Invalid encoding version")]
-    InvalidEncodingVersion,
-    /// Invalid length
-    #[display("Invalid length")]
-    InvalidLength,
-    /// Missing Data
-    #[display("Missing data")]
-    MissingData,
-}
-
-impl core::error::Error for BlobDecodingError {}
+use op_alloy_protocol::{DepositError, SpanBatchError};
 
 /// A result type for the derivation pipeline stages.
 pub type PipelineResult<T> = Result<T, PipelineErrorKind>;
@@ -157,12 +138,12 @@ impl core::error::Error for PipelineError {
 }
 
 impl PipelineError {
-    /// Wrap [self] as a [PipelineErrorKind::Critical].
+    /// Wrap [PipelineError] as a [PipelineErrorKind::Critical].
     pub const fn crit(self) -> PipelineErrorKind {
         PipelineErrorKind::Critical(self)
     }
 
-    /// Wrap [self] as a [PipelineErrorKind::Temporary].
+    /// Wrap [PipelineError] as a [PipelineErrorKind::Temporary].
     pub const fn temp(self) -> PipelineErrorKind {
         PipelineErrorKind::Temporary(self)
     }
@@ -206,7 +187,7 @@ impl From<BuilderError> for ResetError {
 impl core::error::Error for ResetError {}
 
 impl ResetError {
-    /// Wrap [self] as a [PipelineErrorKind::Reset].
+    /// Wrap [ResetError] as a [PipelineErrorKind::Reset].
     pub const fn reset(self) -> PipelineErrorKind {
         PipelineErrorKind::Reset(self)
     }
@@ -251,70 +232,6 @@ impl From<DepositError> for PipelineEncodingError {
     }
 }
 
-/// A frame decompression error.
-#[derive(derive_more::Display, Debug, PartialEq, Eq)]
-pub enum BatchDecompressionError {
-    /// The buffer exceeds the [MAX_SPAN_BATCH_ELEMENTS] protocol parameter.
-    #[display("The batch exceeds the maximum number of elements: {max_size}", max_size = MAX_SPAN_BATCH_ELEMENTS)]
-    BatchTooLarge,
-}
-
-impl core::error::Error for BatchDecompressionError {}
-
-/// An [AttributesBuilder] Error.
-///
-/// [AttributesBuilder]: crate::traits::AttributesBuilder
-#[derive(derive_more::Display, Clone, Debug, PartialEq, Eq)]
-pub enum BuilderError {
-    /// Mismatched blocks.
-    #[display("Block mismatch. Expected {_0:?}, got {_1:?}")]
-    BlockMismatch(BlockNumHash, BlockNumHash),
-    /// Mismatched blocks for the start of an Epoch.
-    #[display("Block mismatch on epoch reset. Expected {_0:?}, got {_1:?}")]
-    BlockMismatchEpochReset(BlockNumHash, BlockNumHash, B256),
-    /// [SystemConfig] update failed.
-    ///
-    /// [SystemConfig]: op_alloy_genesis::SystemConfig
-    #[display("System config update failed")]
-    SystemConfigUpdate,
-    /// Broken time invariant between L2 and L1.
-    #[display("Time invariant broken. L1 origin: {_0:?} | Next L2 time: {_1} | L1 block: {_2:?} | L1 timestamp {_3:?}")]
-    BrokenTimeInvariant(BlockNumHash, u64, BlockNumHash, u64),
-    /// Attributes unavailable.
-    #[display("Attributes unavailable")]
-    AttributesUnavailable,
-    /// A custom error.
-    #[display("Error in attributes builder: {_0}")]
-    Custom(String),
-}
-
-impl core::error::Error for BuilderError {}
-
-/// An error returned by the [BlobProviderError].
-#[derive(derive_more::Display, Debug, PartialEq, Eq)]
-pub enum BlobProviderError {
-    /// The number of specified blob hashes did not match the number of returned sidecars.
-    #[display("Blob sidecar length mismatch: expected {_0}, got {_1}")]
-    SidecarLengthMismatch(usize, usize),
-    /// Slot derivation error.
-    #[display("Failed to derive slot")]
-    SlotDerivation,
-    /// Blob decoding error.
-    #[display("Blob decoding error: {_0}")]
-    BlobDecoding(BlobDecodingError),
-    /// Error pertaining to the backend transport.
-    #[display("{_0}")]
-    Backend(String),
-}
-
-impl From<BlobDecodingError> for BlobProviderError {
-    fn from(err: BlobDecodingError) -> Self {
-        Self::BlobDecoding(err)
-    }
-}
-
-impl core::error::Error for BlobProviderError {}
-
 #[cfg(test)]
 mod tests {
     use super::*;

crates/derive/src/errors/sources.rs

@@ -0,0 +1,47 @@
+//! Error types for sources.
+
+use alloc::string::String;
+
+/// Blob Decoding Error
+#[derive(derive_more::Display, Debug, PartialEq, Eq)]
+pub enum BlobDecodingError {
+    /// Invalid field element
+    #[display("Invalid field element")]
+    InvalidFieldElement,
+    /// Invalid encoding version
+    #[display("Invalid encoding version")]
+    InvalidEncodingVersion,
+    /// Invalid length
+    #[display("Invalid length")]
+    InvalidLength,
+    /// Missing Data
+    #[display("Missing data")]
+    MissingData,
+}
+
+impl core::error::Error for BlobDecodingError {}
+
+/// An error returned by the [BlobProviderError].
+#[derive(derive_more::Display, Debug, PartialEq, Eq)]
+pub enum BlobProviderError {
+    /// The number of specified blob hashes did not match the number of returned sidecars.
+    #[display("Blob sidecar length mismatch: expected {_0}, got {_1}")]
+    SidecarLengthMismatch(usize, usize),
+    /// Slot derivation error.
+    #[display("Failed to derive slot")]
+    SlotDerivation,
+    /// Blob decoding error.
+    #[display("Blob decoding error: {_0}")]
+    BlobDecoding(BlobDecodingError),
+    /// Error pertaining to the backend transport.
+    #[display("{_0}")]
+    Backend(String),
+}
+
+impl From<BlobDecodingError> for BlobProviderError {
+    fn from(err: BlobDecodingError) -> Self {
+        Self::BlobDecoding(err)
+    }
+}
+
+impl core::error::Error for BlobProviderError {}

crates/derive/src/errors/stages.rs

@@ -0,0 +1,13 @@
+//! Error types for derivation pipeline stages.
+
+use op_alloy_protocol::MAX_SPAN_BATCH_ELEMENTS;
+
+/// A frame decompression error.
+#[derive(derive_more::Display, Debug, PartialEq, Eq)]
+pub enum BatchDecompressionError {
+    /// The buffer exceeds the [MAX_SPAN_BATCH_ELEMENTS] protocol parameter.
+    #[display("The batch exceeds the maximum number of elements: {max_size}", max_size = MAX_SPAN_BATCH_ELEMENTS)]
+    BatchTooLarge,
+}
+
+impl core::error::Error for BatchDecompressionError {}

crates/derive/src/lib.rs

@@ -11,13 +11,7 @@ extern crate alloc;
 
 /// Required types and traits for kona's derivation pipeline.
 pub mod prelude {
-    pub use crate::{
-        attributes::*,
-        errors::{PipelineError, PipelineErrorKind, PipelineResult},
-        pipeline::{DerivationPipeline, PipelineBuilder},
-        sources::*,
-        traits::*,
-    };
+    pub use crate::{attributes::*, errors::*, pipeline::*, sources::*, stages::*, traits::*};
 }
 
 pub mod attributes;

crates/derive/src/pipeline/builder.rs

@@ -1,12 +1,12 @@
 //! Contains the `PipelineBuilder` object that is used to build a `DerivationPipeline`.
 
-use super::{AttributesBuilder, DataAvailabilityProvider, DerivationPipeline};
 use crate::{
+    pipeline::DerivationPipeline,
     stages::{
         AttributesQueue, BatchProvider, BatchStream, ChannelProvider, ChannelReader, FrameQueue,
         L1Retrieval, L1Traversal,
     },
-    traits::{ChainProvider, L2ChainProvider},
+    traits::{AttributesBuilder, ChainProvider, DataAvailabilityProvider, L2ChainProvider},
 };
 use alloc::sync::Arc;
 use core::fmt::Debug;

crates/derive/src/pipeline/core.rs

@@ -1,12 +1,11 @@
 //! Contains the core derivation pipeline.
 
-use super::{
-    NextAttributes, OriginAdvancer, OriginProvider, Pipeline, PipelineError, PipelineResult,
-    StepResult,
-};
 use crate::{
-    errors::PipelineErrorKind,
-    traits::{ActivationSignal, L2ChainProvider, ResetSignal, Signal, SignalReceiver},
+    errors::{PipelineError, PipelineErrorKind, PipelineResult},
+    traits::{
+        ActivationSignal, L2ChainProvider, NextAttributes, OriginAdvancer, OriginProvider,
+        Pipeline, ResetSignal, Signal, SignalReceiver, StepResult,
+    },
 };
 use alloc::{boxed::Box, collections::VecDeque, string::ToString, sync::Arc};
 use async_trait::async_trait;
@@ -174,9 +173,10 @@ where
 #[cfg(test)]
 mod tests {
     use crate::{
-        pipeline::{DerivationPipeline, PipelineError, StepResult},
-        test_utils::{TestL2ChainProvider, *},
-        traits::{ActivationSignal, Pipeline, ResetSignal, Signal, SignalReceiver},
+        errors::PipelineError,
+        pipeline::DerivationPipeline,
+        test_utils::*,
+        traits::{ActivationSignal, Pipeline, ResetSignal, Signal, SignalReceiver, StepResult},
     };
     use alloc::{string::ToString, sync::Arc};
     use alloy_rpc_types_engine::PayloadAttributes;

crates/derive/src/pipeline/mod.rs

@@ -1,14 +1,5 @@
 //! Module containing the derivation pipeline.
 
-/// Re-export trait arguments.
-pub use crate::traits::{
-    AttributesBuilder, DataAvailabilityProvider, NextAttributes, OriginAdvancer, OriginProvider,
-    Pipeline, ResetProvider, Signal, SignalReceiver, StepResult,
-};
-
-/// Re-export error types.
-pub use crate::errors::{PipelineError, PipelineResult};
-
 mod builder;
 pub use builder::PipelineBuilder;
 

crates/derive/src/stages/batch/batch_validator.rs

@@ -2,10 +2,9 @@
 
 use super::NextBatchProvider;
 use crate::{
-    errors::ResetError,
-    pipeline::{OriginAdvancer, PipelineResult, Signal, SignalReceiver},
+    errors::{PipelineResult, ResetError},
     prelude::{OriginProvider, PipelineError, PipelineErrorKind},
-    traits::{AttributesProvider, ResetSignal},
+    traits::{AttributesProvider, OriginAdvancer, ResetSignal, Signal, SignalReceiver},
 };
 use alloc::{boxed::Box, sync::Arc, vec::Vec};
 use async_trait::async_trait;

crates/derive/src/stages/batch/mod.rs

@@ -11,7 +11,7 @@
 //! [ChannelReader]: crate::stages::channel::ChannelReader
 //! [AttributesQueue]: crate::stages::attributes_queue::AttributesQueue
 
-use crate::pipeline::PipelineResult;
+use crate::errors::PipelineResult;
 use alloc::boxed::Box;
 use async_trait::async_trait;
 use op_alloy_protocol::{Batch, BlockInfo, L2BlockInfo};

crates/derive/src/stages/channel/channel_assembler.rs

@@ -2,8 +2,9 @@
 
 use super::{ChannelReaderProvider, NextFrameProvider};
 use crate::{
-    pipeline::{OriginAdvancer, PipelineResult, Signal, SignalReceiver},
+    errors::PipelineResult,
     prelude::{OriginProvider, PipelineError},
+    traits::{OriginAdvancer, Signal, SignalReceiver},
 };
 use alloc::{boxed::Box, sync::Arc};
 use alloy_primitives::{hex, Bytes};

crates/derive/src/stages/channel/mod.rs

@@ -11,7 +11,7 @@
 //! [FrameQueue]: crate::stages::FrameQueue
 //! [BatchQueue]: crate::stages::BatchQueue
 
-use crate::pipeline::PipelineResult;
+use crate::errors::PipelineResult;
 use alloc::boxed::Box;
 use async_trait::async_trait;
 use op_alloy_protocol::Frame;

crates/derive/src/test_utils/pipeline.rs

@@ -12,8 +12,8 @@ use op_alloy_rpc_types_engine::OpAttributesWithParent;
 
 // Re-export these types used internally to the test pipeline.
 use crate::{
-    errors::PipelineError,
-    pipeline::{DerivationPipeline, PipelineBuilder, PipelineResult},
+    errors::{PipelineError, PipelineResult},
+    pipeline::{DerivationPipeline, PipelineBuilder},
     stages::{
         AttributesQueue, BatchStream, ChannelProvider, ChannelReader, FrameQueue, L1Retrieval,
         L1Traversal,