chore: add example how to install additional rpc namespace (#4005)

examples/additional-rpc-namespace-in-cli/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "additional-rpc-namespace-in-cli"
+version = "0.0.0"
+publish = false
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+reth.workspace = true
+reth-transaction-pool.workspace = true
+
+clap = { version = "4", features = ["derive"] }
+jsonrpsee = { workspace = true, features = ["server", "macros"] }
+eyre = "0.6"

examples/additional-rpc-namespace-in-cli/src/main.rs

@@ -0,0 +1,112 @@
+//! Example of how to use additional rpc namespaces in the reth CLI
+//!
+//! Run with
+//!
+//! ```not_rust
+//! cargo run -p additional-rpc-namespace-in-cli -- node --http --ws --enable-ext
+//! ```
+//!
+//! This installs an additional RPC method `txpoolExt_transactionCount` that can queried via [cast](https://github.com/foundry-rs/foundry)
+//!
+//! ```sh
+//! cast rpc txpoolExt_transactionCount
+//! ```
+use clap::Parser;
+use jsonrpsee::{core::RpcResult, proc_macros::rpc};
+use reth::{
+    cli::{
+        ext::{RethCliExt, RethRpcConfig, RethRpcServerArgsExt},
+        Cli,
+    },
+    network::{NetworkInfo, Peers},
+    providers::{
+        BlockReaderIdExt, CanonStateSubscriptions, ChainSpecProvider, ChangeSetReader,
+        EvmEnvProvider, StateProviderFactory,
+    },
+    rpc::builder::{RethModuleRegistry, TransportRpcModules},
+    tasks::TaskSpawner,
+};
+use reth_transaction_pool::TransactionPool;
+
+fn main() {
+    Cli::<MyRethCliExt>::parse().run().unwrap();
+}
+
+/// The type that tells the reth CLI what extensions to use
+struct MyRethCliExt;
+
+impl RethCliExt for MyRethCliExt {
+    /// This tells the reth CLI to install the `txpool` rpc namespace via `RethCliTxpoolExt`
+    type RpcExt = RethCliTxpoolExt;
+}
+
+/// Our custom cli args extension that adds one flag to reth default CLI.
+#[derive(Debug, Clone, Copy, Default, clap::Args)]
+struct RethCliTxpoolExt {
+    /// CLI flag to enable the txpool extension namespace
+    #[clap(long)]
+    pub enable_ext: bool,
+}
+
+impl RethRpcServerArgsExt for RethCliTxpoolExt {
+    // This is the entrypoint for the CLI to extend the RPC server with custom rpc namespaces.
+    fn extend_rpc_modules<Conf, Provider, Pool, Network, Tasks, Events>(
+        &self,
+        _config: &Conf,
+        registry: &mut RethModuleRegistry<Provider, Pool, Network, Tasks, Events>,
+        modules: &mut TransportRpcModules<()>,
+    ) -> eyre::Result<()>
+    where
+        Conf: RethRpcConfig,
+        Provider: BlockReaderIdExt
+            + StateProviderFactory
+            + EvmEnvProvider
+            + ChainSpecProvider
+            + ChangeSetReader
+            + Clone
+            + Unpin
+            + 'static,
+        Pool: TransactionPool + Clone + 'static,
+        Network: NetworkInfo + Peers + Clone + 'static,
+        Tasks: TaskSpawner + Clone + 'static,
+        Events: CanonStateSubscriptions + Clone + 'static,
+    {
+        if !self.enable_ext {
+            return Ok(())
+        }
+
+        // here we get the configured pool type from the CLI.
+        let pool = registry.pool().clone();
+        let ext = TxpoolExt { pool };
+
+        // now we merge our extension namespace into all configured transports
+        modules.merge_configured(ext.into_rpc())?;
+
+        println!("txpool extension enabled");
+        Ok(())
+    }
+}
+
+/// trait interface for a custom rpc namespace: `txpool`
+///
+/// This defines an additional namespace where all methods are configured as trait functions.
+#[rpc(server, namespace = "txpoolExt")]
+pub trait TxpoolExtApi {
+    /// Returns the number of transactions in the pool.
+    #[method(name = "transactionCount")]
+    fn transaction_count(&self) -> RpcResult<usize>;
+}
+
+/// The type that implements the `txpool` rpc namespace trait
+pub struct TxpoolExt<Pool> {
+    pool: Pool,
+}
+
+impl<Pool> TxpoolExtApiServer for TxpoolExt<Pool>
+where
+    Pool: TransactionPool + Clone + 'static,
+{
+    fn transaction_count(&self) -> RpcResult<usize> {
+        Ok(self.pool.pool_size().total)
+    }
+}