chore: update docs based on clippy warnings

src/common/mod.rs

@@ -15,9 +15,13 @@ use crate::engine::ExecutionPayload;
 /// Selected block header info
 #[derive(Debug, Clone, Copy, Eq, PartialEq, Default, Serialize, Deserialize)]
 pub struct BlockInfo {
+    /// The block hash
     pub hash: H256,
+    /// The block number
     pub number: u64,
+    /// The parent block hash
     pub parent_hash: H256,
+    /// The block timestamp
     pub timestamp: u64,
 }
 
@@ -28,8 +32,11 @@ pub struct RawTransaction(pub Vec<u8>);
 /// L1 epoch block
 #[derive(Copy, Clone, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
 pub struct Epoch {
+    /// The block number
     pub number: u64,
+    /// The block hash
     pub hash: H256,
+    /// The block timestamp
     pub timestamp: u64,
 }
 
@@ -110,7 +117,9 @@ pub struct AttributesDepositedCall {
     pub fee_scalar: U256,
 }
 
+/// A type alias for the `setL1BlockValues` function parameter types
 type SetL1BlockValueInput = (u64, u64, U256, H256, u64, H256, U256, U256);
+/// The `setL1BlockValues` human-readable ABI
 const L1_BLOCK_CONTRACT_ABI: &str = r#"[
     function setL1BlockValues(uint64 _number,uint64 _timestamp, uint256 _basefee, bytes32 _hash,uint64 _sequenceNumber,bytes32 _batcherHash,uint256 _l1FeeOverhead,uint256 _l1FeeScalar) external
 ]"#;

src/config/mod.rs

@@ -97,18 +97,25 @@ impl Config {
 /// Magi config items derived from the CLI
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct CliConfig {
+    /// The L1 RPC
     #[serde(skip_serializing_if = "Option::is_none")]
     pub l1_rpc_url: Option<String>,
+    /// The L2 execution client RPC
     #[serde(skip_serializing_if = "Option::is_none")]
     pub l2_rpc_url: Option<String>,
+    /// The L2 engine RPC
     #[serde(skip_serializing_if = "Option::is_none")]
     pub l2_engine_url: Option<String>,
+    /// The JWT secret used to authenticate with the engine
     #[serde(skip_serializing_if = "Option::is_none")]
     pub jwt_secret: Option<String>,
+    /// A trusted L2 RPC used to obtain data from when using checkpoint sync mode.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub checkpoint_sync_url: Option<String>,
+    /// The port to serve the Magi RPC on.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub rpc_port: Option<u16>,
+    /// If Magi is running in devnet mode.
     #[serde(default)]
     pub devnet: bool,
 }
@@ -190,14 +197,18 @@ impl SystemConfig {
 /// System accounts
 #[derive(Debug, Clone)]
 pub struct SystemAccounts {
+    /// The address that submits attributes deposited transactions in every L2 block
     pub attributes_depositor: Address,
+    /// The contract address that attributes deposited transactions are submitted to
     pub attributes_predeploy: Address,
+    /// The contract address that holds fees paid to the sequencer during transaction execution & block production
     pub fee_vault: Address,
 }
 
 /// Wrapper around a [ChainConfig]
 #[derive(Debug, Clone, Serialize, Deserialize)]
 struct ChainProvider {
+    /// The [ChainConfig] which is unique for each blockchain
     chain: ChainConfig,
 }
 
@@ -210,8 +221,11 @@ impl From<ChainConfig> for Serialized<ChainProvider> {
 /// Provides default values for the L2 RPC & engine.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 struct DefaultsProvider {
+    /// The L2 execution node RPC
     l2_rpc_url: String,
+    /// The L2 engine RPC
     l2_engine_url: String,
+    /// The port to serve the Magi RPC server on
     rpc_port: u16,
 }
 
@@ -570,10 +584,14 @@ struct ExternalGenesisInfo {
 /// System config settings
 #[derive(Debug, Clone, Serialize, Deserialize)]
 struct SystemConfigInfo {
+    /// The authorized batch sender that sends batcher transactions to the batch inbox on L1
     #[serde(rename = "batcherAddr")]
     batcher_addr: Address,
+    /// The current L1 fee overhead to apply to L2 transactions cost computation. Unused after Ecotone hard fork.
     overhead: H256,
+    /// The current L1 fee scalar to apply to L2 transactions cost computation. Unused after Ecotone hard fork.
     scalar: H256,
+    /// The gas limit for L2 blocks
     #[serde(rename = "gasLimit")]
     gas_limit: u64,
 }

src/derive/mod.rs

@@ -14,9 +14,12 @@ use self::{
     state::State,
 };
 
+/// A module that handles the block derivation stages
 pub mod stages;
+/// A module that keeps track of the current derivation state, caching previous L1 and L2 blocks
 pub mod state;
 
+/// A module that extends the [Iterator] trait with a `purge` method
 mod purgeable;
 pub use purgeable::PurgeableIterator;
 

src/derive/purgeable.rs

@@ -1,4 +1,5 @@
 /// Iterator that can purge itself
 pub trait PurgeableIterator: Iterator {
+    /// Purges and resets an iterator
     fn purge(&mut self);
 }

src/derive/stages/attributes.rs

@@ -51,7 +51,7 @@ impl PurgeableIterator for Attributes {
 }
 
 impl Attributes {
-    /// Creates new [Attributes] and sets [epoch_hash](Attributes::epoch_hash) to the current L1 safe epoch block hash.
+    /// Creates new [Attributes] and sets the `epoch_hash` to the current L1 safe epoch block hash.
     pub fn new(
         block_input_iter: Box<dyn PurgeableIterator<Item = BlockInput<u64>>>,
         state: Arc<RwLock<State>>,
@@ -284,15 +284,25 @@ impl Encodable for DepositedTransaction {
 /// Represents the attributes provided as calldata in an attributes deposited transaction.
 #[derive(Debug)]
 struct AttributesDeposited {
+    /// The L1 epoch block number
     number: u64,
+    /// The L1 epoch block timestamp
     timestamp: u64,
+    /// The L1 epoch base fee
     base_fee: U256,
+    /// The L1 epoch block hash
     hash: H256,
+    /// The L2 block's position in the epoch
     sequence_number: u64,
+    /// A versioned hash of the current authorized batcher sender.
     batcher_hash: H256,
+    /// The current L1 fee overhead to apply to L2 transactions cost computation. Unused after Ecotone hard fork.
     fee_overhead: U256,
+    /// The current L1 fee scalar to apply to L2 transactions cost computation. Unused after Ecotone hard fork.
     fee_scalar: U256,
+    /// Gas limit: 1_000_000 if post-Regolith, otherwise 150_000_000
     gas: u64,
+    /// False if post-Regolith, otherwise true
     is_system_tx: bool,
 }
 

src/derive/stages/batcher_transactions.rs

@@ -96,7 +96,7 @@ impl BatcherTransaction {
 /// A channel frame.
 #[derive(Debug, Default, Clone)]
 pub struct Frame {
-    // A unique identifier for the channel containing the frame.
+    /// A unique identifier for the channel containing the frame.
     pub channel_id: u128,
     /// The index of the frame within the channel
     pub frame_number: u16,

src/derive/stages/batches.rs

@@ -445,6 +445,7 @@ fn decode_batches(channel: &Channel, chain_id: u64) -> Result<Vec<Batch>> {
     Ok(batches)
 }
 
+/// The type of batch - either a [SingleBatch] or [SpanBatch]
 #[derive(Debug, Clone)]
 pub enum Batch {
     /// A [SingleBatch]
@@ -471,6 +472,7 @@ impl Batch {
     }
 }
 
+/// The status of a batch.
 #[derive(Debug, Clone, PartialEq)]
 enum BatchStatus {
     /// The batch is invalid

src/derive/stages/block_input.rs

@@ -7,6 +7,7 @@ use crate::{
     derive::state::State,
 };
 
+/// A marker trait to allow representing an epoch as either a block number or an [Epoch]
 pub trait EpochType {}
 impl EpochType for u64 {}
 impl EpochType for Epoch {}

src/derive/stages/mod.rs

@@ -1,7 +1,20 @@
+/// A module to handle the payload attributes derivation stage
 pub mod attributes;
+
+/// A module to handle batcher transactions and frames
 pub mod batcher_transactions;
+
+/// A module to handle processing of a [Batch](crate::derive::stages::batches::Batch)
 pub mod batches;
+
+/// A module to handle building a [BlockInput](crate::derive::stages::block_input::BlockInput)
 mod block_input;
+
+/// A module to handle the channel bank derivation stage
 pub mod channels;
+
+/// A module to handle processing of a [SingleBatch](crate::derive::stages::single_batch::SingleBatch)
 mod single_batch;
+
+/// A module to handle processing of a [SpanBatch](crate::derive::stages::span_batch::SpanBatch)
 mod span_batch;

src/derive/stages/span_batch.rs

@@ -370,27 +370,40 @@ fn decode_tx_data(data: &[u8], tx_count: u64) -> (Vec<TxData>, &[u8]) {
     (tx_datas, data_ref)
 }
 
+/// The transaction type - Legacy, EIP-2930, or EIP-1559
 #[derive(Debug)]
 enum TxData {
     /// A legacy transaction type
     Legacy {
+        /// Transaction value
         value: U256,
+        /// Transaction gas price
         gas_price: U256,
+        /// Transaction calldata
         data: Bytes,
     },
     /// An EIP-2930 transaction type
     Type1 {
+        /// Transaction value
         value: U256,
+        /// Transaction gas price
         gas_price: U256,
+        /// Transaction calldata
         data: Bytes,
+        /// Access list as specified in EIP-2930
         access_list: AccessList,
     },
     /// An EIP-1559 transaction type
     Type2 {
+        /// Transaction value
         value: U256,
+        /// Max fee per gas as specified in EIP-1559
         max_fee: U256,
+        /// Max priority fee as specified in EIP-1559
         max_priority_fee: U256,
+        /// Transaction calldata
         data: Bytes,
+        /// Access list as specified in EIP-2930
         access_list: AccessList,
     },
 }

src/derive/state.rs

@@ -31,6 +31,7 @@ pub struct State {
 }
 
 impl State {
+    /// Creates a new [State] and fetches and caches a range of L2 blocks.
     pub async fn new(
         finalized_head: BlockInfo,
         finalized_epoch: Epoch,
@@ -63,8 +64,8 @@ impl State {
     }
 
     /// Returns a cached L2 block by block timestamp
-    pub fn l2_info_by_timestamp(&self, timestmap: u64) -> Option<&(BlockInfo, Epoch)> {
-        let block_num = (timestmap - self.config.chain.l2_genesis.timestamp)
+    pub fn l2_info_by_timestamp(&self, timestamp: u64) -> Option<&(BlockInfo, Epoch)> {
+        let block_num = (timestamp - self.config.chain.l2_genesis.timestamp)
             / self.config.chain.blocktime
             + self.config.chain.l2_genesis.number;
 
@@ -80,7 +81,7 @@ impl State {
         })
     }
 
-    /// Returns an epoch by number. Same as the first L1 block number in the epoch's seqencing window.
+    /// Returns an epoch by number. Same as the first L1 block number in the epoch's sequencing window.
     pub fn epoch_by_number(&self, num: u64) -> Option<Epoch> {
         self.l1_info_by_number(num).map(|info| Epoch {
             number: info.block_info.number,

src/driver/info.rs

@@ -4,8 +4,10 @@ use ethers::middleware::Middleware;
 use ethers::providers::{JsonRpcClient, Provider, ProviderError};
 use ethers::types::{Block, BlockId, BlockNumber, Transaction};
 
+/// An asynchronous trait for fetching blocks along with their transactions.
 #[async_trait::async_trait]
 pub trait InnerProvider {
+    /// Retrieves a block and its transactions
     async fn get_block_with_txs(
         &self,
         block_id: BlockId,
@@ -14,6 +16,7 @@ pub trait InnerProvider {
 
 /// Wrapper around a [Provider]
 pub struct HeadInfoFetcher<'a, P: JsonRpcClient> {
+    /// An ethers [Provider] implementing the [JsonRpcClient] trait
     inner: &'a Provider<P>,
 }
 
@@ -35,6 +38,7 @@ impl<'a, P: JsonRpcClient> InnerProvider for HeadInfoFetcher<'a, P> {
     }
 }
 
+/// Provides a method to fetch the latest finalized block
 pub struct HeadInfoQuery {}
 
 impl HeadInfoQuery {

src/driver/mod.rs

@@ -28,8 +28,13 @@ use crate::{
 
 use self::engine_driver::EngineDriver;
 
+/// A module to handle block production & validation
 mod engine_driver;
+
+/// A module to handle fetching blocks
 mod info;
+
+/// A module to handle conversions to a [HeadInfo] struct
 mod types;
 pub use types::*;
 

src/engine/api.rs

@@ -245,6 +245,7 @@ impl Engine for EngineApi {
 #[derive(Debug, Serialize, Deserialize, Default)]
 #[serde(rename_all = "camelCase")]
 struct GetPayloadResponse {
+    /// The execution payload returned by the engine via `engine_getPayloadV2` (`engine_getPayloadV3` post Ecotone)
     execution_payload: ExecutionPayload,
 }
 

src/engine/auth.rs

@@ -39,7 +39,7 @@ impl JwtSecret {
         }
     }
 
-    /// Generates a random [`JwtSecret`][crate::auth::JwtSecret].
+    /// Generates a random [`JwtSecret`]
     pub fn random() -> Self {
         let random_bytes: [u8; 32] = rand::thread_rng().gen();
         let secret = hex::encode(random_bytes);

src/engine/traits.rs

@@ -72,7 +72,7 @@ pub trait Engine: Send + Sync + 'static {
     /// ## get_payload
     ///
     /// No modifications to [`engine_getPayloadV2`](https://github.com/ethereum/execution-apis/blob/main/src/engine/shanghai.md#engine_getpayloadv2)
-    /// were made for L2. Retrieves a payload by ID, prepared by [engine_forkchoiceUpdatedV1](EngineApi::engine_forkchoiceUpdatedV1)
+    /// were made for L2. Retrieves a payload by ID, prepared by [engine_forkchoiceUpdatedV2](super::EngineApi)
     /// when called with [PayloadAttributes].
     ///
     /// ### Specification

src/l1/mod.rs

@@ -114,6 +114,7 @@ struct InnerWatcher {
     system_config_update: (u64, Option<SystemConfig>),
 }
 
+/// A type alias for a vector of bytes. Represents the calldata in a batcher transaction
 type BatcherTransactionData = Vec<u8>;
 
 impl Drop for ChainWatcher {