From 6d5607dc2bac1acaf5e94a01da1c09264a8f9241 Mon Sep 17 00:00:00 2001
From: Matthias Seitz <matthias.seitz@outlook.de>
Date: Wed, 5 Feb 2025 02:12:33 +0100
Subject: [PATCH] docs: add docs for instantiating EthFilter (#14224)

Co-authored-by: Dan Cline <6798349+Rjected@users.noreply.github.com>
---
 crates/ethereum/evm/src/lib.rs      |  7 ++++++-
 crates/rpc/rpc-eth-api/src/types.rs | 19 +++++++++++-------
 crates/rpc/rpc/src/eth/core.rs      | 31 ++++++++++++++++++++++++++++-
 crates/rpc/rpc/src/eth/filter.rs    | 21 +++++++++++++++++++
 4 files changed, 69 insertions(+), 9 deletions(-)

diff --git a/crates/ethereum/evm/src/lib.rs b/crates/ethereum/evm/src/lib.rs
index ac2fea59e..a2cb79a45 100644
--- a/crates/ethereum/evm/src/lib.rs
+++ b/crates/ethereum/evm/src/lib.rs
@@ -21,7 +21,7 @@ use alloc::{sync::Arc, vec::Vec};
 use alloy_consensus::{BlockHeader, Header};
 use alloy_primitives::{Address, U256};
 use core::{convert::Infallible, fmt::Debug};
-use reth_chainspec::{ChainSpec, EthChainSpec};
+use reth_chainspec::{ChainSpec, EthChainSpec, MAINNET};
 use reth_evm::{env::EvmEnv, ConfigureEvm, ConfigureEvmEnv, Database, Evm, NextBlockEnvAttributes};
 use reth_primitives::TransactionSigned;
 use reth_primitives_traits::transaction::execute::FillTxEnv;
@@ -130,6 +130,11 @@ impl EthEvmConfig {
         Self { chain_spec }
     }
 
+    /// Creates a new Ethereum EVM configuration for the ethereum mainnet.
+    pub fn mainnet() -> Self {
+        Self::new(MAINNET.clone())
+    }
+
     /// Returns the chain spec associated with this configuration.
     pub const fn chain_spec(&self) -> &Arc<ChainSpec> {
         &self.chain_spec
diff --git a/crates/rpc/rpc-eth-api/src/types.rs b/crates/rpc/rpc-eth-api/src/types.rs
index f73dbb5a1..b4aa4a991 100644
--- a/crates/rpc/rpc-eth-api/src/types.rs
+++ b/crates/rpc/rpc-eth-api/src/types.rs
@@ -1,19 +1,24 @@
 //! Trait for specifying `eth` network dependent API types.
 
-use std::{
-    error::Error,
-    fmt::{self},
-};
-
+use crate::{AsEthApiError, FromEthApiError, RpcNodeCore};
 use alloy_network::Network;
 use alloy_rpc_types_eth::Block;
 use reth_provider::{ProviderTx, ReceiptProvider, TransactionsProvider};
 use reth_rpc_types_compat::TransactionCompat;
 use reth_transaction_pool::{PoolTransaction, TransactionPool};
-
-use crate::{AsEthApiError, FromEthApiError, RpcNodeCore};
+use std::{
+    error::Error,
+    fmt::{self},
+};
 
 /// Network specific `eth` API types.
+///
+/// This trait defines the network specific rpc types and helpers required for the `eth_` and
+/// adjacent endpoints. `NetworkTypes` is [`Network`] as defined by the alloy crate, see also
+/// [`alloy_network::Ethereum`].
+///
+/// This type is stateful so that it can provide additional context if necessary, e.g. populating
+/// receipts with additional data.
 pub trait EthApiTypes: Send + Sync + Clone {
     /// Extension of [`FromEthApiError`], with network specific errors.
     type Error: Into<jsonrpsee_types::error::ErrorObject<'static>>
diff --git a/crates/rpc/rpc/src/eth/core.rs b/crates/rpc/rpc/src/eth/core.rs
index 63978871e..7eb85e264 100644
--- a/crates/rpc/rpc/src/eth/core.rs
+++ b/crates/rpc/rpc/src/eth/core.rs
@@ -40,6 +40,11 @@ const DEFAULT_BROADCAST_CAPACITY: usize = 2000;
 /// separately in submodules. The rpc handler implementation can then delegate to the main impls.
 /// This way [`EthApi`] is not limited to [`jsonrpsee`] and can be used standalone or in other
 /// network handlers (for example ipc).
+///
+/// ## Trait requirements
+///
+/// While this type requires various unrestricted generic components, trait bounds are enforced when
+/// additional traits are implemented for this type.
 #[derive(Deref)]
 pub struct EthApi<Provider: BlockReader, Pool, Network, EvmConfig> {
     /// All nested fields bundled together.
@@ -62,7 +67,31 @@ impl<Provider, Pool, Network, EvmConfig> EthApi<Provider, Pool, Network, EvmConf
 where
     Provider: BlockReaderIdExt,
 {
-    /// Convenience fn to obtain a new [`EthApiBuilder`] instance with mandatory components
+    /// Convenience fn to obtain a new [`EthApiBuilder`] instance with mandatory components.
+    ///
+    /// Creating an [`EthApi`] requires a few mandatory components:
+    ///  - provider: The type responsible for fetching requested data from disk.
+    ///  - transaction pool: To interact with the pool, submitting new transactions (e.g.
+    ///    `eth_sendRawTransactions`).
+    ///  - network: required to handle requests related to network state (e.g. `eth_syncing`).
+    ///  - evm config: Knows how create a new EVM instance to transact,estimate,call,trace.
+    ///
+    /// # Create an instance with noop ethereum implementations
+    ///
+    /// ```no_run
+    /// use reth_evm_ethereum::EthEvmConfig;
+    /// use reth_network_api::noop::NoopNetwork;
+    /// use reth_provider::noop::NoopProvider;
+    /// use reth_rpc::EthApi;
+    /// use reth_transaction_pool::noop::NoopTransactionPool;
+    /// let eth_api = EthApi::builder(
+    ///     NoopProvider::default(),
+    ///     NoopTransactionPool::default(),
+    ///     NoopNetwork::default(),
+    ///     EthEvmConfig::mainnet(),
+    /// )
+    /// .build();
+    /// ```
     pub fn builder(
         provider: Provider,
         pool: Pool,
diff --git a/crates/rpc/rpc/src/eth/filter.rs b/crates/rpc/rpc/src/eth/filter.rs
index e7337f6e7..aa998dc15 100644
--- a/crates/rpc/rpc/src/eth/filter.rs
+++ b/crates/rpc/rpc/src/eth/filter.rs
@@ -43,6 +43,8 @@ use tracing::{error, trace};
 const MAX_HEADERS_RANGE: u64 = 1_000; // with ~530bytes per header this is ~500kb
 
 /// `Eth` filter RPC implementation.
+///
+/// This type handles `eth_` rpc requests related to filters (`eth_getLogs`).
 pub struct EthFilter<Eth: EthApiTypes> {
     /// All nested fields bundled together
     inner: Arc<EthFilterInner<Eth>>,
@@ -69,6 +71,25 @@ where
     /// See also [`EthFilterConfig`].
     ///
     /// This also spawns a task that periodically clears stale filters.
+    ///
+    /// # Create a new instance with [`EthApi`](crate::EthApi)
+    ///
+    /// ```no_run
+    /// use reth_evm_ethereum::EthEvmConfig;
+    /// use reth_network_api::noop::NoopNetwork;
+    /// use reth_provider::noop::NoopProvider;
+    /// use reth_rpc::{EthApi, EthFilter};
+    /// use reth_tasks::TokioTaskExecutor;
+    /// use reth_transaction_pool::noop::NoopTransactionPool;
+    /// let eth_api = EthApi::builder(
+    ///     NoopProvider::default(),
+    ///     NoopTransactionPool::default(),
+    ///     NoopNetwork::default(),
+    ///     EthEvmConfig::mainnet(),
+    /// )
+    /// .build();
+    /// let filter = EthFilter::new(eth_api, Default::default(), TokioTaskExecutor::default().boxed());
+    /// ```
     pub fn new(eth_api: Eth, config: EthFilterConfig, task_spawner: Box<dyn TaskSpawner>) -> Self {
         let EthFilterConfig { max_blocks_per_filter, max_logs_per_response, stale_filter_ttl } =
             config;