paradigmxyz · mattsse · May 24, 2025 · May 24, 2025 · May 24, 2025 · May 24, 2025
@@ -16,21 +16,21 @@ use tracing::error;
 /// An extension trait for providers that implement the engine API, to wait for a VALID response.
 #[async_trait::async_trait]
 pub trait EngineApiValidWaitExt<N>: Send + Sync {
-    /// Calls `engine_newPayloadV1` with the given [ExecutionPayloadV1], and waits until the
+    /// Calls `engine_newPayloadV1` with the given [`ExecutionPayloadV1`], and waits until the
     /// response is VALID.
     async fn new_payload_v1_wait(
         &self,
         payload: ExecutionPayloadV1,
     ) -> TransportResult<PayloadStatus>;
 
-    /// Calls `engine_newPayloadV2` with the given [ExecutionPayloadInputV2], and waits until the
+    /// Calls `engine_newPayloadV2` with the given [`ExecutionPayloadInputV2`], and waits until the
     /// response is VALID.
     async fn new_payload_v2_wait(
         &self,
         payload: ExecutionPayloadInputV2,
     ) -> TransportResult<PayloadStatus>;
 
-    /// Calls `engine_newPayloadV3` with the given [ExecutionPayloadV3], parent beacon block root,
+    /// Calls `engine_newPayloadV3` with the given [`ExecutionPayloadV3`], parent beacon block root,
     /// and versioned hashes, and waits until the response is VALID.
     async fn new_payload_v3_wait(
         &self,
@@ -39,7 +39,7 @@ pub trait EngineApiValidWaitExt<N>: Send + Sync {
         parent_beacon_block_root: B256,
     ) -> TransportResult<PayloadStatus>;
 
-    /// Calls `engine_newPayloadV4` with the given [ExecutionPayloadV3], parent beacon block root,
+    /// Calls `engine_newPayloadV4` with the given [`ExecutionPayloadV3`], parent beacon block root,
     /// versioned hashes, and requests hash, and waits until the response is VALID.
     async fn new_payload_v4_wait(
         &self,
@@ -49,24 +49,24 @@ pub trait EngineApiValidWaitExt<N>: Send + Sync {
         requests_hash: B256,
     ) -> TransportResult<PayloadStatus>;
 
-    /// Calls `engine_forkChoiceUpdatedV1` with the given [ForkchoiceState] and optional
-    /// [PayloadAttributes], and waits until the response is VALID.
+    /// Calls `engine_forkChoiceUpdatedV1` with the given [`ForkchoiceState`] and optional
+    /// [`PayloadAttributes`], and waits until the response is VALID.
     async fn fork_choice_updated_v1_wait(
         &self,
         fork_choice_state: ForkchoiceState,
         payload_attributes: Option<PayloadAttributes>,
     ) -> TransportResult<ForkchoiceUpdated>;
 
-    /// Calls `engine_forkChoiceUpdatedV2` with the given [ForkchoiceState] and optional
-    /// [PayloadAttributes], and waits until the response is VALID.
+    /// Calls `engine_forkChoiceUpdatedV2` with the given [`ForkchoiceState`] and optional
+    /// [`PayloadAttributes`], and waits until the response is VALID.
     async fn fork_choice_updated_v2_wait(
         &self,
         fork_choice_state: ForkchoiceState,
         payload_attributes: Option<PayloadAttributes>,
     ) -> TransportResult<ForkchoiceUpdated>;
 
-    /// Calls `engine_forkChoiceUpdatedV3` with the given [ForkchoiceState] and optional
-    /// [PayloadAttributes], and waits until the response is VALID.
+    /// Calls `engine_forkChoiceUpdatedV3` with the given [`ForkchoiceState`] and optional
+    /// [`PayloadAttributes`], and waits until the response is VALID.
     async fn fork_choice_updated_v3_wait(
         &self,
         fork_choice_state: ForkchoiceState,

@@ -71,7 +71,7 @@ pub trait Consensus<B: Block>: HeaderValidator<B::Header> {
     fn validate_block_pre_execution(&self, block: &SealedBlock<B>) -> Result<(), Self::Error>;
 }
 
-/// HeaderValidator is a protocol that validates headers and their relationships.
+/// `HeaderValidator` is a protocol that validates headers and their relationships.
 #[auto_impl::auto_impl(&, Arc)]
 pub trait HeaderValidator<H = Header>: Debug + Send + Sync {
     /// Validate if header is correct and follows consensus specification.
@@ -87,7 +87,7 @@ pub trait HeaderValidator<H = Header>: Debug + Send + Sync {
     ///
     /// **This should not be called for the genesis block**.
     ///
-    /// Note: Validating header against its parent does not include other HeaderValidator
+    /// Note: Validating header against its parent does not include other `HeaderValidator`
     /// validations.
     fn validate_header_against_parent(
         &self,

@@ -499,7 +499,8 @@ where
 
     /// When the Consensus layer receives a new block via the consensus gossip protocol,
     /// the transactions in the block are sent to the execution layer in the form of a
-    /// [`PayloadTypes::ExecutionData`](reth_payload_primitives::PayloadTypes::ExecutionData). The
+    /// [`PayloadTypes::ExecutionData`], for example
+    /// [`ExecutionData`](reth_payload_primitives::PayloadTypes::ExecutionData). The
     /// Execution layer executes the transactions and validates the state in the block header,
     /// then passes validation data back to Consensus layer, that adds the block to the head of
     /// its own blockchain and attests to it. The block is then broadcast over the consensus p2p

@@ -7,7 +7,7 @@ use derive_more::Display;
 use reth_codecs_derive::add_arbitrary_tests;
 use thiserror::Error;
 
-/// RLPx disconnect reason.
+/// `RLPx` disconnect reason.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Display)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(any(test, feature = "arbitrary"), derive(arbitrary::Arbitrary))]

@@ -163,7 +163,7 @@ impl From<EthVersion> for &'static str {
     }
 }
 
-/// RLPx `p2p` protocol version
+/// `RLPx` `p2p` protocol version
 #[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(any(test, feature = "arbitrary"), derive(arbitrary::Arbitrary))]

@@ -100,7 +100,7 @@ impl HelloMessageWithProtocols {
 
 // TODO: determine if we should allow for the extra fields at the end like EIP-706 suggests
 /// Raw rlpx protocol message used in the `p2p` handshake, containing information about the
-/// supported RLPx protocol version and capabilities.
+/// supported `RLPx` protocol version and capabilities.
 ///
 /// See also <https://github.com/ethereum/devp2p/blob/master/rlpx.md#hello-0x00>
 #[derive(Clone, Debug, PartialEq, Eq, RlpEncodable, RlpDecodable)]

@@ -203,7 +203,7 @@ where
     }
 }
 
-/// A P2PStream wraps over any `Stream` that yields bytes and makes it compatible with `p2p`
+/// A `P2PStream` wraps over any `Stream` that yields bytes and makes it compatible with `p2p`
 /// protocol messages.
 ///
 /// This stream supports multiple shared capabilities, that were negotiated during the handshake.

@@ -6,7 +6,7 @@ use std::{
 };
 use tokio::sync::oneshot::{error::RecvError, Receiver};
 
-/// Flatten a [Receiver] message in order to get rid of the [RecvError] result
+/// Flatten a [Receiver] message in order to get rid of the [`RecvError`] result
 #[derive(Debug)]
 #[pin_project]
 pub struct FlattenedResponse<T> {

@@ -23,7 +23,7 @@ pub trait SyncStateProvider: Send + Sync {
 /// which point the node is considered fully synced.
 #[auto_impl::auto_impl(&, Arc, Box)]
 pub trait NetworkSyncUpdater: std::fmt::Debug + Send + Sync + 'static {
-    /// Notifies about a [SyncState] update.
+    /// Notifies about a [`SyncState`] update.
     fn update_sync_state(&self, state: SyncState);
 
     /// Updates the status of the p2p node.

@@ -204,7 +204,7 @@ pub trait OpEngineApi<Engine: EngineTypes> {
     /// Returns the execution payload bodies by the range starting at `start`, containing `count`
     /// blocks.
     ///
-    /// WARNING: This method is associated with the BeaconBlocksByRange message in the consensus
+    /// WARNING: This method is associated with the `BeaconBlocksByRange` message in the consensus
     /// layer p2p specification, meaning the input should be treated as untrusted or potentially
     /// adversarial.
     ///

@@ -11,7 +11,7 @@ mod tests {
     use serde::{Deserialize, Serialize};
 
     /// This type is kept for compatibility tests after the codec support was added to alloy-eips
-    /// AccessList type natively
+    /// `AccessList` type natively
     #[derive(
         Clone,
         Debug,

@@ -54,7 +54,7 @@ where
     }
 }
 
-/// Drives an [IpcConn] forward.
+/// Drives an [`IpcConn`] forward.
 ///
 /// This forwards received requests from the connection to the service and sends responses to the
 /// connection.

@@ -53,7 +53,7 @@ pub trait DebugApi {
     /// This expects an rlp encoded block
     ///
     /// Note, the parent of this block must be present, or it will fail. For the second parameter
-    /// see [GethDebugTracingOptions] reference.
+    /// see [`GethDebugTracingOptions`] reference.
     #[method(name = "traceBlock")]
     async fn debug_trace_block(
         &self,
@@ -63,7 +63,7 @@ pub trait DebugApi {
 
     /// Similar to `debug_traceBlock`, `debug_traceBlockByHash` accepts a block hash and will replay
     /// the block that is already present in the database. For the second parameter see
-    /// [GethDebugTracingOptions].
+    /// [`GethDebugTracingOptions`].
     #[method(name = "traceBlockByHash")]
     async fn debug_trace_block_by_hash(
         &self,
@@ -72,8 +72,8 @@ pub trait DebugApi {
     ) -> RpcResult<Vec<TraceResult>>;
 
     /// Similar to `debug_traceBlockByHash`, `debug_traceBlockByNumber` accepts a block number
-    /// [BlockNumberOrTag] and will replay the block that is already present in the database.
-    /// For the second parameter see [GethDebugTracingOptions].
+    /// [`BlockNumberOrTag`] and will replay the block that is already present in the database.
+    /// For the second parameter see [`GethDebugTracingOptions`].
     #[method(name = "traceBlockByNumber")]
     async fn debug_trace_block_by_number(
         &self,
@@ -99,7 +99,7 @@ pub trait DebugApi {
     /// The block can optionally be specified either by hash or by number as
     /// the second argument.
     /// The trace can be configured similar to `debug_traceTransaction`,
-    /// see [GethDebugTracingOptions]. The method returns the same output as
+    /// see [`GethDebugTracingOptions`]. The method returns the same output as
     /// `debug_traceTransaction`.
     #[method(name = "traceCall")]
     async fn debug_trace_call(
@@ -115,7 +115,7 @@ pub trait DebugApi {
     ///
     /// The first argument is a list of bundles. Each bundle can overwrite the block headers. This
     /// will affect all transaction in that bundle.
-    /// BlockNumber and transaction_index are optional. Transaction_index
+    /// `BlockNumber` and `transaction_index` are optional. `Transaction_index`
     /// specifies the number of tx in the block to replay and -1 means all transactions should be
     /// replayed.
     /// The trace can be configured similar to `debug_traceTransaction`.
@@ -382,7 +382,7 @@ pub trait DebugApi {
 
     /// Returns the structured logs created during the execution of EVM against a block pulled
     /// from the pool of bad ones and returns them as a JSON object. For the second parameter see
-    /// TraceConfig reference.
+    /// `TraceConfig` reference.
     #[method(name = "traceBadBlock")]
     async fn debug_trace_bad_block(
         &self,

@@ -191,7 +191,7 @@ pub trait EngineApi<Engine: EngineTypes> {
     /// Returns the execution payload bodies by the range starting at `start`, containing `count`
     /// blocks.
     ///
-    /// WARNING: This method is associated with the BeaconBlocksByRange message in the consensus
+    /// WARNING: This method is associated with the `BeaconBlocksByRange` message in the consensus
     /// layer p2p specification, meaning the input should be treated as untrusted or potentially
     /// adversarial.
     ///
@@ -205,9 +205,9 @@ pub trait EngineApi<Engine: EngineTypes> {
         count: U64,
     ) -> RpcResult<ExecutionPayloadBodiesV1>;
 
-    /// This function will return the ClientVersionV1 object.
+    /// This function will return the [`ClientVersionV1`] object.
     /// See also:
-    /// <https://github.com/ethereum/execution-apis/blob/03911ffc053b8b806123f1fc237184b0092a485a/src/engine/identification.md#engine_getclientversionv1>make fmt
+    /// <https://github.com/ethereum/execution-apis/blob/03911ffc053b8b806123f1fc237184b0092a485a/src/engine/identification.md#engine_getclientversionv1>
     ///
     ///
     /// - When connected to a single execution client, the consensus client **MUST** receive an

@@ -66,8 +66,8 @@ pub trait GanacheApi {
 
     /// Snapshot the state of the blockchain at the current block. Takes no parameters. Returns the
     /// id of the snapshot that was created. A snapshot can only be reverted once. After a
-    /// successful evm_revert, the same snapshot id cannot be used again. Consider creating a new
-    /// snapshot after each evm_revert if you need to revert to the same point multiple times.
+    /// successful `evm_revert`, the same snapshot id cannot be used again. Consider creating a new
+    /// snapshot after each `evm_revert` if you need to revert to the same point multiple times.
     ///
     /// Returns the hex-encoded identifier for this snapshot.
     #[method(name = "snapshot")]

@@ -44,12 +44,13 @@ pub trait Otterscan<T: RpcObject, H: RpcObject> {
     #[method(name = "traceTransaction")]
     async fn trace_transaction(&self, tx_hash: TxHash) -> RpcResult<Option<Vec<TraceEntry>>>;
 
-    /// Tailor-made and expanded version of eth_getBlockByNumber for block details page in
+    /// Tailor-made and expanded version of `eth_getBlockByNumber` for block details page in
     /// Otterscan.
     #[method(name = "getBlockDetails")]
     async fn get_block_details(&self, block_number: u64) -> RpcResult<BlockDetails<H>>;
 
-    /// Tailor-made and expanded version of eth_getBlockByHash for block details page in Otterscan.
+    /// Tailor-made and expanded version of `eth_getBlockByHash` for block details page in
+    /// Otterscan.
     #[method(name = "getBlockDetailsByHash")]
     async fn get_block_details_by_hash(&self, block_hash: B256) -> RpcResult<BlockDetails<H>>;
 

@@ -80,7 +80,7 @@ pub trait TraceApi {
     /// `indices` represent the index positions of the traces.
     ///
     /// Note: This expects a list of indices but only one is supported since this function returns a
-    /// single [LocalizedTransactionTrace].
+    /// single [`LocalizedTransactionTrace`].
     #[method(name = "get")]
     async fn trace_get(
         &self,

@@ -1090,7 +1090,7 @@ where
     /// Returns the execution payload bodies by the range starting at `start`, containing `count`
     /// blocks.
     ///
-    /// WARNING: This method is associated with the BeaconBlocksByRange message in the consensus
+    /// WARNING: This method is associated with the `BeaconBlocksByRange` message in the consensus
     /// layer p2p specification, meaning the input should be treated as untrusted or potentially
     /// adversarial.
     ///

@@ -55,15 +55,15 @@ pub trait EthBundleApi {
     /// The `eth_sendPrivateRawTransaction` method can be used to send private transactions to
     /// the RPC endpoint. Private transactions are protected from frontrunning and kept
     /// private until included in a block. A request to this endpoint needs to follow
-    /// the standard eth_sendRawTransaction
+    /// the standard `eth_sendRawTransaction`
     #[method(name = "sendPrivateRawTransaction")]
     async fn send_private_raw_transaction(&self, bytes: Bytes) -> jsonrpsee::core::RpcResult<B256>;
 
     /// The `eth_cancelPrivateTransaction` method stops private transactions from being
     /// submitted for future blocks.
     ///
     /// A transaction can only be cancelled if the request is signed by the same key as the
-    /// eth_sendPrivateTransaction call submitting the transaction in first place.
+    /// `eth_sendPrivateTransaction` call submitting the transaction in first place.
     #[method(name = "cancelPrivateTransaction")]
     async fn cancel_private_transaction(
         &self,

@@ -247,7 +247,7 @@ pub trait EthApi<T: RpcObject, B: RpcObject, R: RpcObject, H: RpcObject> {
     /// It returns list of addresses and storage keys used by the transaction, plus the gas
     /// consumed when the access list is added. That is, it gives you the list of addresses and
     /// storage keys that will be used by that transaction, plus the gas consumed if the access
-    /// list is included. Like eth_estimateGas, this is an estimation; the list could change
+    /// list is included. Like `eth_estimateGas`, this is an estimation; the list could change
     /// when the transaction is actually mined. Adding an accessList to your transaction does
     /// not necessary result in lower gas usage compared to a transaction without an access
     /// list.

@@ -704,7 +704,7 @@ where
     }
 }
 
-/// Helper trait for [FullTransactionsReceiver] to erase the `Transaction` type.
+/// Helper trait for [`FullTransactionsReceiver`] to erase the `Transaction` type.
 #[async_trait]
 trait FullTransactionsFilter<T>: fmt::Debug + Send + Sync + Unpin + 'static {
     async fn drain(&self) -> FilterChanges<T>;

@@ -184,7 +184,7 @@ pub struct UnwindOutput {
 /// transactions, and persist their results to a database.
 ///
 /// Stages must have a unique [ID][StageId] and implement a way to "roll forwards"
-/// ([Stage::execute]) and a way to "roll back" ([Stage::unwind]).
+/// ([`Stage::execute`]) and a way to "roll back" ([`Stage::unwind`]).
 ///
 /// Stages are executed as part of a pipeline where they are executed serially.
 ///

@@ -309,7 +309,7 @@ mod tests {
         assert!(runner.validate_execution(input, output.ok()).is_ok(), "execution validation");
     }
 
-    /// Same as [partial_body_download] except the `batch_size` is not hit.
+    /// Same as [`partial_body_download`] except the `batch_size` is not hit.
     #[tokio::test]
     async fn full_body_download() {
         let (stage_progress, previous_stage) = (1, 20);
@@ -348,7 +348,7 @@ mod tests {
         assert!(runner.validate_execution(input, output.ok()).is_ok(), "execution validation");
     }
 
-    /// Same as [full_body_download] except we have made progress before
+    /// Same as [`full_body_download`] except we have made progress before
     #[tokio::test]
     async fn sync_from_previous_progress() {
         let (stage_progress, previous_stage) = (1, 21);

@@ -73,7 +73,7 @@ impl reth_codecs::Compact for MerkleCheckpoint {
     }
 }
 
-/// Saves the progress of AccountHashing stage.
+/// Saves the progress of `AccountHashing` stage.
 #[derive(Default, Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(any(test, feature = "test-utils"), derive(arbitrary::Arbitrary))]
 #[cfg_attr(any(test, feature = "reth-codec"), derive(reth_codecs::Compact))]
@@ -88,7 +88,7 @@ pub struct AccountHashingCheckpoint {
     pub progress: EntitiesCheckpoint,
 }
 
-/// Saves the progress of StorageHashing stage.
+/// Saves the progress of `StorageHashing` stage.
 #[derive(Default, Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(any(test, feature = "test-utils"), derive(arbitrary::Arbitrary))]
 #[cfg_attr(any(test, feature = "reth-codec"), derive(reth_codecs::Compact))]
@@ -281,9 +281,9 @@ impl StageCheckpoint {
 #[cfg_attr(any(test, feature = "reth-codec"), reth_codecs::add_arbitrary_tests(compact))]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub enum StageUnitCheckpoint {
-    /// Saves the progress of AccountHashing stage.
+    /// Saves the progress of `AccountHashing` stage.
     Account(AccountHashingCheckpoint),
-    /// Saves the progress of StorageHashing stage.
+    /// Saves the progress of `StorageHashing` stage.
     Storage(StorageHashingCheckpoint),
     /// Saves the progress of abstract stage iterating over or downloading entities.
     Entities(EntitiesCheckpoint),