diff --git a/bin/reth/src/cli/components.rs b/bin/reth/src/cli/components.rs index 18ef804f4..b7d60c08c 100644 --- a/bin/reth/src/cli/components.rs +++ b/bin/reth/src/cli/components.rs @@ -101,13 +101,19 @@ pub struct RethRpcComponents<'a, Reth: RethNodeComponents> { } /// A Generic implementation of the RethNodeComponents trait. +/// +/// Represents components required for the Reth node. #[derive(Clone, Debug)] -#[allow(missing_docs)] pub struct RethNodeComponentsImpl { + /// Represents the provider instance. pub provider: Provider, + /// Represents the transaction pool instance. pub pool: Pool, + /// Represents the network instance used for communication. pub network: Network, + /// Represents the task executor instance. pub task_executor: Tasks, + /// Represents the events subscription handler instance. pub events: Events, } diff --git a/crates/interfaces/src/p2p/error.rs b/crates/interfaces/src/p2p/error.rs index 29c238e5f..667d9d548 100644 --- a/crates/interfaces/src/p2p/error.rs +++ b/crates/interfaces/src/p2p/error.rs @@ -72,18 +72,29 @@ impl EthResponseValidator for RequestResult> { } /// Error variants that can happen when sending requests to a session. +/// +/// Represents errors encountered when sending requests. #[derive(Clone, Debug, Error, Eq, PartialEq)] -#[allow(missing_docs)] pub enum RequestError { + /// Closed channel to the peer. #[error("closed channel to the peer")] + /// Indicates the channel to the peer is closed. ChannelClosed, + /// Connection to a peer dropped while handling the request. #[error("connection to a peer dropped while handling the request")] + /// Represents a dropped connection while handling the request. ConnectionDropped, + /// Capability message is not supported by the remote peer. #[error("capability message is not supported by remote peer")] + /// Indicates an unsupported capability message from the remote peer. UnsupportedCapability, + /// Request timed out while awaiting response. #[error("request timed out while awaiting response")] + /// Represents a timeout while waiting for a response. Timeout, + /// Received bad response. #[error("received bad response")] + /// Indicates a bad response was received. BadResponse, } diff --git a/crates/net/discv4/src/error.rs b/crates/net/discv4/src/error.rs index 19ab703cb..1fbd67d47 100644 --- a/crates/net/discv4/src/error.rs +++ b/crates/net/discv4/src/error.rs @@ -4,17 +4,26 @@ use tokio::sync::{mpsc::error::SendError, oneshot::error::RecvError}; /// Error thrown when decoding a UDP packet. #[derive(Debug, thiserror::Error)] -#[allow(missing_docs)] pub enum DecodePacketError { + /// Failed to RLP decode the packet. #[error("failed to rlp decode: {0}")] + /// Indicates a failure to RLP decode the packet. Rlp(#[from] alloy_rlp::Error), + /// Received packet length is too short. #[error("received packet length is too short")] + /// Indicates the received packet length is insufficient. PacketTooShort, + /// Header/data hash mismatch. #[error("header/data hash mismatch")] + /// Indicates a mismatch between header and data hashes. HashMismatch, + /// Unsupported message ID. #[error("message ID {0} is not supported")] + /// Indicates an unsupported message ID. UnknownMessage(u8), + /// Failed to recover public key. #[error("failed to recover public key: {0}")] + /// Indicates a failure to recover the public key. Secp256k1(#[from] secp256k1::Error), } diff --git a/crates/net/dns/src/error.rs b/crates/net/dns/src/error.rs index d24c83ab9..cd65f5699 100644 --- a/crates/net/dns/src/error.rs +++ b/crates/net/dns/src/error.rs @@ -3,38 +3,59 @@ use crate::tree::TreeRootEntry; /// Alias for a parse result pub(crate) type ParseEntryResult = Result; +/// Alias for lookup results pub(crate) type LookupResult = Result; /// Error while parsing a [DnsEntry](crate::tree::DnsEntry) #[derive(thiserror::Error, Debug)] -#[allow(missing_docs)] pub enum ParseDnsEntryError { + /// Unknown entry error. #[error("unknown entry: {0}")] + /// Indicates an unknown entry encountered during parsing. UnknownEntry(String), + /// Field not found error. #[error("field {0} not found")] + /// Indicates a field was not found during parsing. FieldNotFound(&'static str), + /// Base64 decoding error. #[error("base64 decoding failed: {0}")] + /// Indicates a failure during Base64 decoding. Base64DecodeError(String), + /// Base32 decoding error. #[error("base32 decoding failed: {0}")] + /// Indicates a failure during Base32 decoding. Base32DecodeError(String), + /// RLP decoding error. #[error("{0}")] + /// Indicates an error during RLP decoding. RlpDecodeError(String), + /// Invalid child hash error in a branch. #[error("invalid child hash in branch: {0}")] + /// Indicates an invalid child hash within a branch. InvalidChildHash(String), + /// Other error. #[error("{0}")] + /// Indicates other unspecified errors. Other(String), } /// Errors that can happen during lookups #[derive(thiserror::Error, Debug)] -#[allow(missing_docs)] pub(crate) enum LookupError { + /// Parse error. #[error(transparent)] + /// Represents errors during parsing. Parse(#[from] ParseDnsEntryError), + /// Invalid root error. #[error("failed to verify root {0}")] + /// Indicates failure while verifying the root entry. InvalidRoot(TreeRootEntry), + /// Request timed out error. #[error("request timed out")] + /// Indicates a timeout occurred during the request. RequestTimedOut, + /// Entry not found error. #[error("entry not found")] + /// Indicates the requested entry was not found. EntryNotFound, } diff --git a/crates/net/network-api/src/error.rs b/crates/net/network-api/src/error.rs index 66e1fd0b0..457214540 100644 --- a/crates/net/network-api/src/error.rs +++ b/crates/net/network-api/src/error.rs @@ -2,9 +2,9 @@ use thiserror::Error; use tokio::sync::{mpsc, oneshot}; /// Network Errors -#[allow(missing_docs)] #[derive(Error, Debug, Clone, PartialEq, Eq)] pub enum NetworkError { + /// Indicates that the sender has been dropped. #[error("sender has been dropped")] ChannelClosed, } diff --git a/crates/net/network/src/message.rs b/crates/net/network/src/message.rs index 8f8a5e13e..b6861267a 100644 --- a/crates/net/network/src/message.rs +++ b/crates/net/network/src/message.rs @@ -61,45 +61,66 @@ pub enum PeerMessage { /// Request Variants that only target block related data. #[derive(Debug, Clone, PartialEq, Eq)] -#[allow(missing_docs)] pub enum BlockRequest { + /// Requests block headers from the peer. + /// + /// The response should be sent through the channel. GetBlockHeaders(GetBlockHeaders), + + /// Requests block bodies from the peer. + /// + /// The response should be sent through the channel. GetBlockBodies(GetBlockBodies), } /// Protocol related request messages that expect a response #[derive(Debug)] -#[allow(missing_docs)] pub enum PeerRequest { - /// Request Block headers from the peer. + /// Requests block headers from the peer. /// /// The response should be sent through the channel. GetBlockHeaders { + /// The request for block headers. request: GetBlockHeaders, + /// The channel to send the response for block headers. response: oneshot::Sender>, }, - /// Request Block headers from the peer. + /// Requests block bodies from the peer. /// /// The response should be sent through the channel. GetBlockBodies { + /// The request for block bodies. request: GetBlockBodies, + /// The channel to send the response for block bodies. response: oneshot::Sender>, }, - /// Request pooled transactions from the peer. + /// Requests pooled transactions from the peer. /// /// The response should be sent through the channel. GetPooledTransactions { + /// The request for pooled transactions. request: GetPooledTransactions, + /// The channel to send the response for pooled transactions. response: oneshot::Sender>, }, - /// Request NodeData from the peer. + /// Requests NodeData from the peer. /// /// The response should be sent through the channel. - GetNodeData { request: GetNodeData, response: oneshot::Sender> }, - /// Request Receipts from the peer. + GetNodeData { + /// The request for NodeData. + request: GetNodeData, + /// The channel to send the response for NodeData. + response: oneshot::Sender>, + }, + /// Requests receipts from the peer. /// /// The response should be sent through the channel. - GetReceipts { request: GetReceipts, response: oneshot::Sender> }, + GetReceipts { + /// The request for receipts. + request: GetReceipts, + /// The channel to send the response for receipts. + response: oneshot::Sender>, + }, } // === impl PeerRequest === @@ -156,18 +177,32 @@ impl PeerRequest { /// Corresponding variant for [`PeerRequest`]. #[derive(Debug)] -#[allow(missing_docs)] pub enum PeerResponse { - /// Response to a [`GetBlockHeaders`] request. - BlockHeaders { response: oneshot::Receiver> }, - /// Response to a [`GetBlockBodies`] request. - BlockBodies { response: oneshot::Receiver> }, - /// Response to a [`GetPooledTransactions`] request. - PooledTransactions { response: oneshot::Receiver> }, - /// Response to a [`GetNodeData`] request. - NodeData { response: oneshot::Receiver> }, - /// Response to a [`GetReceipts`] request. - Receipts { response: oneshot::Receiver> }, + /// Represents a response to a request for block headers. + BlockHeaders { + /// The receiver channel for the response to a block headers request. + response: oneshot::Receiver>, + }, + /// Represents a response to a request for block bodies. + BlockBodies { + /// The receiver channel for the response to a block bodies request. + response: oneshot::Receiver>, + }, + /// Represents a response to a request for pooled transactions. + PooledTransactions { + /// The receiver channel for the response to a pooled transactions request. + response: oneshot::Receiver>, + }, + /// Represents a response to a request for NodeData. + NodeData { + /// The receiver channel for the response to a NodeData request. + response: oneshot::Receiver>, + }, + /// Represents a response to a request for receipts. + Receipts { + /// The receiver channel for the response to a receipts request. + response: oneshot::Receiver>, + }, } // === impl PeerResponse === @@ -207,12 +242,16 @@ impl PeerResponse { /// All response variants for [`PeerResponse`] #[derive(Debug)] -#[allow(missing_docs)] pub enum PeerResponseResult { + /// Represents a result containing block headers or an error. BlockHeaders(RequestResult>), + /// Represents a result containing block bodies or an error. BlockBodies(RequestResult>), + /// Represents a result containing pooled transactions or an error. PooledTransactions(RequestResult>), + /// Represents a result containing node data or an error. NodeData(RequestResult>), + /// Represents a result containing receipts or an error. Receipts(RequestResult>>), } diff --git a/crates/net/network/src/network.rs b/crates/net/network/src/network.rs index 3e2419a5b..432529259 100644 --- a/crates/net/network/src/network.rs +++ b/crates/net/network/src/network.rs @@ -376,52 +376,64 @@ pub trait NetworkProtocols: Send + Sync { } /// Internal messages that can be passed to the [`NetworkManager`](crate::NetworkManager). -#[allow(missing_docs)] #[derive(Debug)] pub(crate) enum NetworkHandleMessage { - /// Adds an address for a peer. + /// Adds an address for a peer, including its ID, kind, and socket address. AddPeerAddress(PeerId, PeerKind, SocketAddr), /// Removes a peer from the peerset corresponding to the given kind. RemovePeer(PeerId, PeerKind), - /// Disconnect a connection to a peer if it exists. + /// Disconnects a connection to a peer if it exists, optionally providing a disconnect reason. DisconnectPeer(PeerId, Option), - /// Add a new listener for [`NetworkEvent`]. + /// Adds a new listener for `NetworkEvent`. EventListener(UnboundedSender), - /// Broadcast event to announce a new block to all nodes. + /// Broadcasts an event to announce a new block to all nodes. AnnounceBlock(NewBlock, B256), - /// Sends the list of transactions to the given peer. - SendTransaction { peer_id: PeerId, msg: SharedTransactions }, - /// Sends the list of transactions hashes to the given peer. - SendPooledTransactionHashes { peer_id: PeerId, msg: NewPooledTransactionHashes }, - /// Send an `eth` protocol request to the peer. + /// Sends a list of transactions to the given peer. + SendTransaction { + /// The ID of the peer to which the transactions are sent. + peer_id: PeerId, + /// The shared transactions to send. + msg: SharedTransactions, + }, + /// Sends a list of transaction hashes to the given peer. + SendPooledTransactionHashes { + /// The ID of the peer to which the transaction hashes are sent. + peer_id: PeerId, + /// The new pooled transaction hashes to send. + msg: NewPooledTransactionHashes, + }, + /// Sends an `eth` protocol request to the peer. EthRequest { /// The peer to send the request to. peer_id: PeerId, /// The request to send to the peer's sessions. request: PeerRequest, }, - /// Apply a reputation change to the given peer. + /// Applies a reputation change to the given peer. ReputationChange(PeerId, ReputationChangeKind), /// Returns the client that can be used to interact with the network. FetchClient(oneshot::Sender), - /// Apply a status update. - StatusUpdate { head: Head }, - /// Get the current status + /// Applies a status update. + StatusUpdate { + /// The head status to apply. + head: Head, + }, + /// Retrieves the current status via a oneshot sender. GetStatus(oneshot::Sender), - /// Get PeerInfo for the given peerids + /// Gets `PeerInfo` for the specified peer IDs. GetPeerInfosByIds(Vec, oneshot::Sender>), - /// Get PeerInfo from all the peers + /// Gets `PeerInfo` from all the peers via a oneshot sender. GetPeerInfos(oneshot::Sender>), - /// Get PeerInfo for a specific peer + /// Gets `PeerInfo` for a specific peer via a oneshot sender. GetPeerInfoById(PeerId, oneshot::Sender>), - /// Get PeerInfo for a specific peer + /// Gets `PeerInfo` for a specific peer kind via a oneshot sender. GetPeerInfosByPeerKind(PeerKind, oneshot::Sender>), - /// Get the reputation for a specific peer + /// Gets the reputation for a specific peer via a oneshot sender. GetReputationById(PeerId, oneshot::Sender>), - /// Gracefully shutdown network + /// Initiates a graceful shutdown of the network via a oneshot sender. Shutdown(oneshot::Sender<()>), - /// Add a new listener for `DiscoveryEvent`. + /// Adds a new listener for `DiscoveryEvent`. DiscoveryListener(UnboundedSender), - /// Add an additional [RlpxSubProtocol]. + /// Adds an additional `RlpxSubProtocol`. AddRlpxSubProtocol(RlpxSubProtocol), } diff --git a/crates/net/network/src/transactions.rs b/crates/net/network/src/transactions.rs index bc7b0c958..76da5e3b9 100644 --- a/crates/net/network/src/transactions.rs +++ b/crates/net/network/src/transactions.rs @@ -1255,18 +1255,30 @@ enum TransactionsCommand { /// All events related to transactions emitted by the network. #[derive(Debug)] -#[allow(missing_docs)] pub enum NetworkTransactionEvent { - /// Received list of transactions from the given peer. + /// Represents the event of receiving a list of transactions from a peer. /// - /// This represents transactions that were broadcasted to use from the peer. - IncomingTransactions { peer_id: PeerId, msg: Transactions }, - /// Received list of transactions hashes to the given peer. - IncomingPooledTransactionHashes { peer_id: PeerId, msg: NewPooledTransactionHashes }, - /// Incoming `GetPooledTransactions` request from a peer. - GetPooledTransactions { + /// This indicates transactions that were broadcasted to us from the peer. + IncomingTransactions { + /// The ID of the peer from which the transactions were received. peer_id: PeerId, + /// The received transactions. + msg: Transactions, + }, + /// Represents the event of receiving a list of transaction hashes from a peer. + IncomingPooledTransactionHashes { + /// The ID of the peer from which the transaction hashes were received. + peer_id: PeerId, + /// The received new pooled transaction hashes. + msg: NewPooledTransactionHashes, + }, + /// Represents the event of receiving a `GetPooledTransactions` request from a peer. + GetPooledTransactions { + /// The ID of the peer from which the request was received. + peer_id: PeerId, + /// The received `GetPooledTransactions` request. request: GetPooledTransactions, + /// The sender for responding to the request with a result of `PooledTransactions`. response: oneshot::Sender>, }, } diff --git a/crates/primitives/src/chain/mod.rs b/crates/primitives/src/chain/mod.rs index f377674ea..7c8cd3420 100644 --- a/crates/primitives/src/chain/mod.rs +++ b/crates/primitives/src/chain/mod.rs @@ -47,37 +47,55 @@ pub use info::ChainInfo; #[serde(rename_all = "snake_case")] #[strum(serialize_all = "snake_case")] #[repr(u64)] -#[allow(missing_docs)] pub enum NamedChain { + /// Ethereum Mainnet. Mainnet = 1, + /// Morden Testnet. Morden = 2, + /// Ropsten Testnet. Ropsten = 3, + /// Rinkeby Testnet. Rinkeby = 4, + /// Goerli Testnet. Goerli = 5, + /// Kovan Testnet. Kovan = 42, + /// Holesky Testnet. Holesky = 17000, + /// Sepolia Testnet. Sepolia = 11155111, + /// Optimism Mainnet. Optimism = 10, + /// Optimism Kovan Testnet. OptimismKovan = 69, + /// Optimism Goerli Testnet. OptimismGoerli = 420, + /// Base chain. Base = 8453, + /// Base Goerli Testnet. BaseGoerli = 84531, + /// Base Sepolia Testnet. BaseSepolia = 84532, + /// Arbitrum Mainnet. Arbitrum = 42161, + /// Arbitrum Testnet. ArbitrumTestnet = 421611, + /// Arbitrum Goerli Testnet. ArbitrumGoerli = 421613, + /// Arbitrum Nova. ArbitrumNova = 42170, + /// Binance Smart Chain Mainnet. #[serde(alias = "bsc")] - #[strum(to_string = "bsc")] BinanceSmartChain = 56, + /// Binance Smart Chain Testnet. #[serde(alias = "bsc_testnet")] - #[strum(to_string = "bsc_testnet")] BinanceSmartChainTestnet = 97, + /// Development Testnet. Dev = 1337, } diff --git a/crates/primitives/src/fs.rs b/crates/primitives/src/fs.rs index 5a23465db..f9dac8fb5 100644 --- a/crates/primitives/src/fs.rs +++ b/crates/primitives/src/fs.rs @@ -9,44 +9,116 @@ use std::{ /// Various error variants for `std::fs` operations that serve as an addition to the io::Error which /// does not provide any information about the path. #[derive(Debug, thiserror::Error)] -#[allow(missing_docs)] pub enum FsPathError { - /// Provides additional path context for [`std::fs::write`]. + /// Error variant for failed write operation with additional path context. #[error("failed to write to {path:?}: {source}")] - Write { source: io::Error, path: PathBuf }, - /// Provides additional path context for [`std::fs::read`]. + Write { + /// The source `io::Error`. + source: io::Error, + /// The path related to the operation. + path: PathBuf, + }, + + /// Error variant for failed read operation with additional path context. #[error("failed to read from {path:?}: {source}")] - Read { source: io::Error, path: PathBuf }, - /// Provides additional path context for [`std::fs::read_link`]. + Read { + /// The source `io::Error`. + source: io::Error, + /// The path related to the operation. + path: PathBuf, + }, + + /// Error variant for failed read link operation with additional path context. #[error("failed to read from {path:?}: {source}")] - ReadLink { source: io::Error, path: PathBuf }, - /// Provides additional path context for [`std::fs::File::create`]. + ReadLink { + /// The source `io::Error`. + source: io::Error, + /// The path related to the operation. + path: PathBuf, + }, + + /// Error variant for failed file creation operation with additional path context. #[error("failed to create file {path:?}: {source}")] - CreateFile { source: io::Error, path: PathBuf }, - /// Provides additional path context for [`std::fs::remove_file`]. + CreateFile { + /// The source `io::Error`. + source: io::Error, + /// The path related to the operation. + path: PathBuf, + }, + + /// Error variant for failed file removal operation with additional path context. #[error("failed to remove file {path:?}: {source}")] - RemoveFile { source: io::Error, path: PathBuf }, - /// Provides additional path context for [`std::fs::create_dir`]. + RemoveFile { + /// The source `io::Error`. + source: io::Error, + /// The path related to the operation. + path: PathBuf, + }, + + /// Error variant for failed directory creation operation with additional path context. #[error("failed to create dir {path:?}: {source}")] - CreateDir { source: io::Error, path: PathBuf }, - /// Provides additional path context for [`std::fs::remove_dir`]. + CreateDir { + /// The source `io::Error`. + source: io::Error, + /// The path related to the operation. + path: PathBuf, + }, + + /// Error variant for failed directory removal operation with additional path context. #[error("failed to remove dir {path:?}: {source}")] - RemoveDir { source: io::Error, path: PathBuf }, - /// Provides additional path context for [`std::fs::read_dir`]. + RemoveDir { + /// The source `io::Error`. + source: io::Error, + /// The path related to the operation. + path: PathBuf, + }, + + /// Error variant for failed directory read operation with additional path context. #[error("failed to read dir {path:?}: {source}")] - ReadDir { source: io::Error, path: PathBuf }, - /// Provides additional context for [`std::fs::rename`]. + ReadDir { + /// The source `io::Error`. + source: io::Error, + /// The path related to the operation. + path: PathBuf, + }, + + /// Error variant for failed file renaming operation with additional path context. #[error("failed to rename {from:?} to {to:?}: {source}")] - Rename { source: io::Error, from: PathBuf, to: PathBuf }, - /// Provides additional path context for [`std::fs::File::open`]. + Rename { + /// The source `io::Error`. + source: io::Error, + /// The original path. + from: PathBuf, + /// The target path. + to: PathBuf, + }, + + /// Error variant for failed file opening operation with additional path context. #[error("failed to open file {path:?}: {source}")] - Open { source: io::Error, path: PathBuf }, - /// Provides additional path context for the file whose contents should be parsed as JSON. + Open { + /// The source `io::Error`. + source: io::Error, + /// The path related to the operation. + path: PathBuf, + }, + + /// Error variant for failed file read as JSON operation with additional path context. #[error("failed to parse json file: {path:?}: {source}")] - ReadJson { source: serde_json::Error, path: PathBuf }, - /// Provides additional path context for the new JSON file. + ReadJson { + /// The source `serde_json::Error`. + source: serde_json::Error, + /// The path related to the operation. + path: PathBuf, + }, + + /// Error variant for failed JSON write to file operation with additional path context. #[error("failed to write to json file: {path:?}: {source}")] - WriteJson { source: serde_json::Error, path: PathBuf }, + WriteJson { + /// The source `serde_json::Error`. + source: serde_json::Error, + /// The path related to the operation. + path: PathBuf, + }, } impl FsPathError { diff --git a/crates/primitives/src/snapshot/compression.rs b/crates/primitives/src/snapshot/compression.rs index 69fe4b2a4..2d5599c2c 100644 --- a/crates/primitives/src/snapshot/compression.rs +++ b/crates/primitives/src/snapshot/compression.rs @@ -1,16 +1,19 @@ use strum::AsRefStr; +/// Snapshot compression types. #[derive(Debug, Copy, Clone, Default, AsRefStr)] #[cfg_attr(feature = "clap", derive(clap::ValueEnum))] -#[allow(missing_docs)] -/// Snapshot compression pub enum Compression { + /// LZ4 compression algorithm. #[strum(serialize = "lz4")] Lz4, + /// Zstandard (Zstd) compression algorithm. #[strum(serialize = "zstd")] Zstd, + /// Zstandard (Zstd) compression algorithm with a dictionary. #[strum(serialize = "zstd-dict")] ZstdWithDictionary, + /// No compression, uncompressed snapshot. #[strum(serialize = "uncompressed")] #[default] Uncompressed, diff --git a/crates/primitives/src/stage/id.rs b/crates/primitives/src/stage/id.rs index 4b82298a1..ac44a5e46 100644 --- a/crates/primitives/src/stage/id.rs +++ b/crates/primitives/src/stage/id.rs @@ -2,21 +2,34 @@ /// /// For custom stages, use [`StageId::Other`] #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] -#[allow(missing_docs)] pub enum StageId { + /// Header stage in the process. Headers, + /// Total difficulty stage in the process. TotalDifficulty, + /// Bodies stage in the process. Bodies, + /// Sender recovery stage in the process. SenderRecovery, + /// Execution stage in the process. Execution, + /// Merkle unwind stage in the process. MerkleUnwind, + /// Account hashing stage in the process. AccountHashing, + /// Storage hashing stage in the process. StorageHashing, + /// Merkle execute stage in the process. MerkleExecute, + /// Transaction lookup stage in the process. TransactionLookup, + /// Index storage history stage in the process. IndexStorageHistory, + /// Index account history stage in the process. IndexAccountHistory, + /// Finish stage in the process. Finish, + /// Other custom stage with a provided string identifier. Other(&'static str), } diff --git a/crates/revm/revm-inspectors/src/tracing/js/mod.rs b/crates/revm/revm-inspectors/src/tracing/js/mod.rs index 3d82365f0..0910d6f8b 100644 --- a/crates/revm/revm-inspectors/src/tracing/js/mod.rs +++ b/crates/revm/revm-inspectors/src/tracing/js/mod.rs @@ -547,23 +547,38 @@ struct CallStackItem { gas_limit: u64, } +/// Error variants that can occur during JavaScript inspection. #[derive(Debug, thiserror::Error)] -#[allow(missing_docs)] pub enum JsInspectorError { + /// Error originating from a JavaScript operation. #[error(transparent)] JsError(#[from] JsError), + + /// Failure during the evaluation of JavaScript code. #[error("failed to evaluate JS code: {0}")] EvalCode(JsError), + + /// The evaluated code is not a JavaScript object. #[error("the evaluated code is not a JS object")] ExpectedJsObject, + + /// The trace object must expose a function named `result()`. #[error("trace object must expose a function result()")] ResultFunctionMissing, + + /// The trace object must expose a function named `fault()`. #[error("trace object must expose a function fault()")] FaultFunctionMissing, + + /// The setup object must be a callable function. #[error("setup object must be a function")] SetupFunctionNotCallable, + + /// Failure during the invocation of the `setup()` function. #[error("failed to call setup(): {0}")] SetupCallFailed(JsError), + + /// Invalid JSON configuration encountered. #[error("invalid JSON config: {0}")] InvalidJsonConfig(JsError), } diff --git a/crates/revm/revm-inspectors/src/tracing/types.rs b/crates/revm/revm-inspectors/src/tracing/types.rs index beafb7f4c..1f3091e95 100644 --- a/crates/revm/revm-inspectors/src/tracing/types.rs +++ b/crates/revm/revm-inspectors/src/tracing/types.rs @@ -369,17 +369,22 @@ impl CallTraceNode { } } -/// A unified representation of a call +/// A unified representation of a call. #[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "UPPERCASE")] -#[allow(missing_docs)] pub enum CallKind { + /// Represents a regular call. #[default] Call, + /// Represents a static call. StaticCall, + /// Represents a call code operation. CallCode, + /// Represents a delegate call. DelegateCall, + /// Represents a contract creation operation. Create, + /// Represents a contract creation operation using the CREATE2 opcode. Create2, } diff --git a/crates/rpc/ipc/src/client.rs b/crates/rpc/ipc/src/client.rs index f440664fc..602da3d41 100644 --- a/crates/rpc/ipc/src/client.rs +++ b/crates/rpc/ipc/src/client.rs @@ -116,7 +116,6 @@ impl IpcTransportClientBuilder { /// Error variants that can happen in IPC transport. #[derive(Debug, thiserror::Error)] -#[allow(missing_docs)] pub enum IpcError { /// Operation not supported #[error("operation not supported")] @@ -128,9 +127,13 @@ pub enum IpcError { #[error("failed to connect to socket {path}: {err}")] FailedToConnect { /// The path of the socket. + #[doc(hidden)] path: PathBuf, + /// The error occurred while connecting. + #[doc(hidden)] err: io::Error, }, + /// Wrapped IO Error #[error(transparent)] Io(#[from] io::Error), } diff --git a/crates/rpc/rpc/src/eth/error.rs b/crates/rpc/rpc/src/eth/error.rs index ac659aaa1..e0370d840 100644 --- a/crates/rpc/rpc/src/eth/error.rs +++ b/crates/rpc/rpc/src/eth/error.rs @@ -22,44 +22,49 @@ pub type EthResult = Result; /// Errors that can occur when interacting with the `eth_` namespace #[derive(Debug, thiserror::Error)] -#[allow(missing_docs)] pub enum EthApiError { /// When a raw transaction is empty #[error("empty transaction data")] EmptyRawTransactionData, + /// When decoding a signed transaction fails #[error("failed to decode signed transaction")] FailedToDecodeSignedTransaction, + /// When the transaction signature is invalid #[error("invalid transaction signature")] InvalidTransactionSignature, + /// Errors related to the transaction pool #[error(transparent)] PoolError(RpcPoolError), + /// When an unknown block number is encountered #[error("unknown block number")] UnknownBlockNumber, /// Thrown when querying for `finalized` or `safe` block before the merge transition is /// finalized, #[error("unknown block")] UnknownSafeOrFinalizedBlock, + /// Thrown when an unknown block or transaction index is encountered #[error("unknown block or tx index")] UnknownBlockOrTxIndex, + /// When an invalid block range is provided #[error("invalid block range")] InvalidBlockRange, /// An internal error where prevrandao is not set in the evm's environment #[error("prevrandao not in the EVM's environment after merge")] PrevrandaoNotSet, - /// Excess_blob_gas is not set for Cancun and above. - #[error("excess blob gas missing the EVM's environment after Cancun")] + /// `excess_blob_gas` is not set for Cancun and above + #[error("excess blob gas missing in the EVM's environment after Cancun")] ExcessBlobGasNotSet, /// Thrown when a call or transaction request (`eth_call`, `eth_estimateGas`, /// `eth_sendTransaction`) contains conflicting fields (legacy, EIP-1559) #[error("both gasPrice and (maxFeePerGas or maxPriorityFeePerGas) specified")] ConflictingFeeFieldsInRequest, + /// Errors related to invalid transactions #[error(transparent)] InvalidTransaction(#[from] RpcInvalidTransactionError), - /// Thrown when constructing an RPC block from a primitive block data failed. + /// Thrown when constructing an RPC block from primitive block data fails #[error(transparent)] InvalidBlockData(#[from] BlockError), - /// Thrown when a [AccountOverride](reth_rpc_types::state::AccountOverride) contains - /// conflicting `state` and `stateDiff` fields + /// Thrown when an `AccountOverride` contains conflicting `state` and `stateDiff` fields #[error("account {0:?} has both 'state' and 'stateDiff'")] BothStateAndStateDiffInOverride(Address), /// Other internal error @@ -68,7 +73,7 @@ pub enum EthApiError { /// Error related to signing #[error(transparent)] Signing(#[from] SignError), - /// Thrown when a transaction was requested but not matching transaction exists + /// Thrown when a requested transaction is not found #[error("transaction not found")] TransactionNotFound, /// Some feature is unsupported @@ -77,10 +82,10 @@ pub enum EthApiError { /// General purpose error for invalid params #[error("{0}")] InvalidParams(String), - /// When tracer config does not match the tracer + /// When the tracer config does not match the tracer #[error("invalid tracer config")] InvalidTracerConfig, - /// Percentile array is invalid + /// When the percentile array is invalid #[error("invalid reward percentiles")] InvalidRewardPercentiles, /// Error thrown when a spawned blocking task failed to deliver an anticipated response. @@ -89,16 +94,17 @@ pub enum EthApiError { /// response back to the request handler. #[error("internal blocking task error")] InternalBlockingTaskError, - /// Error thrown when a spawned blocking task failed to deliver an anticipated response. + /// Error thrown when a spawned blocking task failed to deliver an anticipated response #[error("internal eth error")] InternalEthError, - /// Error thrown when a (tracing) call exceeded the configured timeout. + /// Error thrown when a (tracing) call exceeds the configured timeout #[error("execution aborted (timeout = {0:?})")] ExecutionTimedOut(Duration), /// Internal Error thrown by the javascript tracer #[error("{0}")] InternalJsTracerError(String), #[error(transparent)] + /// Call Input error when both `data` and `input` fields are set and not equal. CallInputError(#[from] CallInputError), /// Optimism related error #[error(transparent)] @@ -563,26 +569,35 @@ impl std::error::Error for RevertError {} /// A helper error type that's mainly used to mirror `geth` Txpool's error messages #[derive(Debug, thiserror::Error)] -#[allow(missing_docs)] pub enum RpcPoolError { + /// When the transaction is already known #[error("already known")] AlreadyKnown, + /// When the sender is invalid #[error("invalid sender")] InvalidSender, + /// When the transaction is underpriced #[error("transaction underpriced")] Underpriced, + /// When the transaction pool is full #[error("txpool is full")] TxPoolOverflow, + /// When the replacement transaction is underpriced #[error("replacement transaction underpriced")] ReplaceUnderpriced, + /// When the transaction exceeds the block gas limit #[error("exceeds block gas limit")] ExceedsGasLimit, + /// When a negative value is encountered #[error("negative value")] NegativeValue, + /// When oversized data is encountered #[error("oversized data")] OversizedData, + /// When the max initcode size is exceeded #[error("max initcode size exceeded")] ExceedsMaxInitCodeSize, + /// Errors related to invalid transactions #[error(transparent)] Invalid(#[from] RpcInvalidTransactionError), /// Custom pool error @@ -597,6 +612,7 @@ pub enum RpcPoolError { /// constraint (blob vs normal tx) #[error("address already reserved")] AddressAlreadyReserved, + /// Other unspecified error #[error(transparent)] Other(Box), } diff --git a/crates/rpc/rpc/src/layers/jwt_secret.rs b/crates/rpc/rpc/src/layers/jwt_secret.rs index 6c855cbf5..3b19e02e6 100644 --- a/crates/rpc/rpc/src/layers/jwt_secret.rs +++ b/crates/rpc/rpc/src/layers/jwt_secret.rs @@ -15,24 +15,41 @@ use thiserror::Error; /// Errors returned by the [`JwtSecret`] #[derive(Error, Debug)] -#[allow(missing_docs)] pub enum JwtError { + /// An error encountered while decoding the hexadecimal string for the JWT secret. #[error(transparent)] JwtSecretHexDecodeError(#[from] hex::FromHexError), + + /// The JWT key length provided is invalid, expecting a specific length. #[error("JWT key is expected to have a length of {0} digits. {1} digits key provided")] InvalidLength(usize, usize), + + /// The signature algorithm used in the JWT is not supported. Only HS256 is supported. #[error("unsupported signature algorithm. Only HS256 is supported")] UnsupportedSignatureAlgorithm, + + /// The provided signature in the JWT is invalid. #[error("provided signature is invalid")] InvalidSignature, + + /// The "iat" (issued-at) claim in the JWT is not within the allowed ±60 seconds from the + /// current time. #[error("IAT (issued-at) claim is not within ±60 seconds from the current time")] InvalidIssuanceTimestamp, + + /// The Authorization header is missing or invalid in the context of JWT validation. #[error("Authorization header is missing or invalid")] MissingOrInvalidAuthorizationHeader, + + /// An error occurred during JWT decoding. #[error("JWT decoding error: {0}")] JwtDecodingError(String), + + /// An error related to file system path handling encountered during JWT operations. #[error(transparent)] JwtFsPathError(#[from] FsPathError), + + /// An I/O error occurred during JWT operations. #[error(transparent)] IOError(#[from] std::io::Error), } diff --git a/crates/snapshot/src/error.rs b/crates/snapshot/src/error.rs index 20da642be..302803835 100644 --- a/crates/snapshot/src/error.rs +++ b/crates/snapshot/src/error.rs @@ -5,17 +5,21 @@ use thiserror::Error; /// Error returned by [crate::Snapshotter::run] #[derive(Error, Debug)] -#[allow(missing_docs)] +/// Errors that can occur during snapshotting. pub enum SnapshotterError { + /// Inconsistent data error. #[error("inconsistent data: {0}")] InconsistentData(&'static str), + /// Error related to the interface. #[error(transparent)] Interface(#[from] RethError), + /// Error related to the database. #[error(transparent)] Database(#[from] DatabaseError), + /// Error related to the provider. #[error(transparent)] Provider(#[from] ProviderError), } diff --git a/crates/stages/src/stages/merkle.rs b/crates/stages/src/stages/merkle.rs index fadee1107..7b74ca47b 100644 --- a/crates/stages/src/stages/merkle.rs +++ b/crates/stages/src/stages/merkle.rs @@ -54,11 +54,13 @@ pub enum MerkleStage { }, /// The unwind portion of the merkle stage. Unwind, - /// Able to execute and unwind. Used for tests #[cfg(any(test, feature = "test-utils"))] - #[allow(missing_docs)] - Both { clean_threshold: u64 }, + Both { + /// The threshold (in number of blocks) for switching from incremental trie building + /// of changes to whole rebuild. + clean_threshold: u64, + }, } impl MerkleStage { diff --git a/crates/storage/db/src/metrics.rs b/crates/storage/db/src/metrics.rs index a81ff1623..971ae194f 100644 --- a/crates/storage/db/src/metrics.rs +++ b/crates/storage/db/src/metrics.rs @@ -5,14 +5,16 @@ use std::time::{Duration, Instant}; const LARGE_VALUE_THRESHOLD_BYTES: usize = 4096; +/// Transaction mode for the database, either read-only or read-write. #[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)] -#[allow(missing_docs)] pub(crate) enum TransactionMode { + /// Read-only transaction mode. ReadOnly, + /// Read-write transaction mode. ReadWrite, } - impl TransactionMode { + /// Returns the transaction mode as a string. pub(crate) const fn as_str(&self) -> &'static str { match self { TransactionMode::ReadOnly => "read-only", @@ -26,15 +28,19 @@ impl TransactionMode { } } +/// Transaction outcome after a database operation - commit, abort, or drop. #[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)] -#[allow(missing_docs)] pub(crate) enum TransactionOutcome { + /// Successful commit of the transaction. Commit, + /// Aborted transaction. Abort, + /// Dropped transaction. Drop, } impl TransactionOutcome { + /// Returns the transaction outcome as a string. pub(crate) const fn as_str(&self) -> &'static str { match self { TransactionOutcome::Commit => "commit", @@ -44,21 +50,31 @@ impl TransactionOutcome { } } +/// Types of operations conducted on the database: get, put, delete, and various cursor operations. #[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)] -#[allow(missing_docs)] pub(crate) enum Operation { + /// Database get operation. Get, + /// Database put operation. Put, + /// Database delete operation. Delete, + /// Database cursor upsert operation. CursorUpsert, + /// Database cursor insert operation. CursorInsert, + /// Database cursor append operation. CursorAppend, + /// Database cursor append duplicates operation. CursorAppendDup, + /// Database cursor delete current operation. CursorDeleteCurrent, + /// Database cursor delete current duplicates operation. CursorDeleteCurrentDuplicates, } impl Operation { + /// Returns the operation as a string. pub(crate) const fn as_str(&self) -> &'static str { match self { Operation::Get => "get", @@ -74,14 +90,20 @@ impl Operation { } } +/// Enum defining labels for various aspects used in metrics. enum Labels { + /// Label representing a table. Table, + /// Label representing a transaction mode. TransactionMode, + /// Label representing a transaction outcome. TransactionOutcome, + /// Label representing a database operation. Operation, } impl Labels { + /// Converts each label variant into its corresponding string representation. pub(crate) fn as_str(&self) -> &'static str { match self { Labels::Table => "table", diff --git a/crates/storage/db/src/version.rs b/crates/storage/db/src/version.rs index 380c170c5..63357b8e9 100644 --- a/crates/storage/db/src/version.rs +++ b/crates/storage/db/src/version.rs @@ -12,20 +12,33 @@ pub const DB_VERSION_FILE_NAME: &str = "database.version"; pub const DB_VERSION: u64 = 1; /// Error when checking a database version using [check_db_version_file] -#[allow(missing_docs)] #[derive(thiserror::Error, Debug)] pub enum DatabaseVersionError { + /// Unable to determine the version of the database; the file is missing. #[error("unable to determine the version of the database, file is missing")] MissingFile, + /// Unable to determine the version of the database; the file is malformed. #[error("unable to determine the version of the database, file is malformed")] MalformedFile, + /// Breaking database change detected. + /// + /// Your database version is incompatible with the latest database version. #[error( "breaking database change detected: your database version (v{version}) \ is incompatible with the latest database version (v{DB_VERSION})" )] - VersionMismatch { version: u64 }, + VersionMismatch { + /// The detected version in the database. + version: u64, + }, + /// IO error occurred while reading the database version file. #[error("IO error occurred while reading {path}: {err}")] - IORead { err: io::Error, path: PathBuf }, + IORead { + /// The encountered IO error. + err: io::Error, + /// The path to the database version file. + path: PathBuf, + }, } /// Checks the database version file with [DB_VERSION_FILE_NAME] name. diff --git a/crates/storage/provider/src/traits/chain.rs b/crates/storage/provider/src/traits/chain.rs index 833982d1a..397fea79b 100644 --- a/crates/storage/provider/src/traits/chain.rs +++ b/crates/storage/provider/src/traits/chain.rs @@ -63,13 +63,20 @@ impl Stream for CanonStateNotificationStream { /// and will return all [`crate::BundleStateWithReceipts`] and /// [`reth_primitives::SealedBlockWithSenders`] of both reverted and committed blocks. #[derive(Clone, Debug)] -#[allow(missing_docs)] pub enum CanonStateNotification { /// Chain got extended without reorg and only new chain is returned. - Commit { new: Arc }, + Commit { + /// The newly extended chain. + new: Arc, + }, /// Chain reorgs and both old and new chain are returned. /// Revert is just a subset of reorg where the new chain is empty. - Reorg { old: Arc, new: Arc }, + Reorg { + /// The old chain before reorganization. + old: Arc, + /// The new chain after reorganization. + new: Arc, + }, } // For one reason or another, the compiler can't derive PartialEq for CanonStateNotification. diff --git a/crates/transaction-pool/src/blobstore/disk.rs b/crates/transaction-pool/src/blobstore/disk.rs index 43caf112b..ba0ffc605 100644 --- a/crates/transaction-pool/src/blobstore/disk.rs +++ b/crates/transaction-pool/src/blobstore/disk.rs @@ -367,16 +367,22 @@ impl fmt::Debug for DiskFileBlobStoreInner { /// Errors that can occur when interacting with a disk file blob store. #[derive(Debug, thiserror::Error)] -#[allow(missing_docs)] pub enum DiskFileBlobStoreError { /// Thrown during [DiskFileBlobStore::open] if the blob store directory cannot be opened. #[error("failed to open blobstore at {0}: {1}")] + /// Indicates a failure to open the blob store directory. Open(PathBuf, io::Error), + /// Failure while reading a blob file. #[error("[{0}] failed to read blob file at {1}: {2}")] + /// Indicates a failure while reading a blob file. ReadFile(TxHash, PathBuf, io::Error), + /// Failure while writing a blob file. #[error("[{0}] failed to write blob file at {1}: {2}")] + /// Indicates a failure while writing a blob file. WriteFile(TxHash, PathBuf, io::Error), + /// Failure while deleting a blob file. #[error("[{0}] failed to delete blob file at {1}: {2}")] + /// Indicates a failure while deleting a blob file. DeleteFile(TxHash, PathBuf, io::Error), } diff --git a/crates/transaction-pool/src/pool/txpool.rs b/crates/transaction-pool/src/pool/txpool.rs index c58a9e7fb..84a7c07a0 100644 --- a/crates/transaction-pool/src/pool/txpool.rs +++ b/crates/transaction-pool/src/pool/txpool.rs @@ -1621,8 +1621,10 @@ impl AllTransactions { } #[cfg(test)] -#[allow(missing_docs)] impl AllTransactions { + /// This function retrieves the number of transactions stored in the pool for a specific sender. + /// + /// If there are no transactions for the given sender, it returns zero by default. pub(crate) fn tx_count(&self, sender: SenderId) -> usize { self.tx_counter.get(&sender).copied().unwrap_or_default() }