feat(rpc): add txpool inspection API (#433)

Adds a `txpool_*` JSON-RPC namespace for inspecting the node's local transaction pool, modeled after Ethereum's `txpool_*` methods and= adapted for Starknet transactions. This is primarily intended for debugging and diagnostics.

Methods: `txpool_status`, `txpool_content`, `txpool_contentFrom`, `txpool_inspect`.

All responses distinguish between `pending` (ready to execute) and `queued` (waiting on a nonce gap) transactions. Katana currently has no queued pool so the `queued` fields are always empty — they exist for forward-compatibility.

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: kariy

crates/node/config/src/rpc.rs

@@ -33,6 +33,7 @@ pub enum RpcModuleKind {
     Starknet,
     Dev,
     Katana,
+    TxPool,
     #[cfg(feature = "cartridge")]
     Cartridge,
     #[cfg(feature = "tee")]
@@ -106,6 +107,7 @@ impl RpcModulesList {
             RpcModuleKind::Starknet,
             RpcModuleKind::Katana,
             RpcModuleKind::Dev,
+            RpcModuleKind::TxPool,
             #[cfg(feature = "cartridge")]
             RpcModuleKind::Cartridge,
             #[cfg(feature = "tee")]

crates/node/full/src/lib.rs

@@ -203,6 +203,12 @@ impl Node {
             rpc_modules.merge(KatanaApiServer::into_rpc(starknet_api.clone()))?;
         }
 
+        if config.rpc.apis.contains(&RpcModuleKind::TxPool) {
+            use katana_rpc_api::txpool::TxPoolApiServer;
+            let api = katana_rpc_server::txpool::TxPoolApi::new(pool.clone());
+            rpc_modules.merge(TxPoolApiServer::into_rpc(api))?;
+        }
+
         #[allow(unused_mut)]
         let mut rpc_server =
             RpcServer::new().metrics(true).health_check(true).cors(cors).module(rpc_modules)?;

crates/node/sequencer/src/lib.rs

@@ -326,6 +326,11 @@ where
             rpc_modules.merge(DevApiServer::into_rpc(api))?;
         }
 
+        if config.rpc.apis.contains(&RpcModuleKind::TxPool) {
+            let api = katana_rpc_server::txpool::TxPoolApi::new(pool.clone());
+            rpc_modules.merge(katana_rpc_api::txpool::TxPoolApiServer::into_rpc(api))?;
+        }
+
         // --- build tee api (if configured)
         #[cfg(feature = "tee")]
         if config.rpc.apis.contains(&RpcModuleKind::Tee) {

crates/pool/pool-api/src/lib.rs

@@ -74,6 +74,9 @@ pub trait TransactionPool: Send + Sync {
     /// where nonce is the next expected nonce (highest pending nonce + 1).
     /// Returns `None` if no pending transactions exist for this account.
     fn get_nonce(&self, address: ContractAddress) -> Option<Nonce>;
+
+    /// Returns a point-in-time snapshot of all transactions currently in the pool.
+    fn take_transactions_snapshot(&self) -> Vec<Arc<Self::Transaction>>;
 }
 
 // the transaction type is recommended to implement a cheap clone (eg ref-counting) so that it

crates/pool/pool/src/pool.rs

@@ -240,6 +240,10 @@ where
             .max()
             .map(|max_nonce| max_nonce + 1)
     }
+
+    fn take_transactions_snapshot(&self) -> Vec<Arc<T>> {
+        self.inner.transactions.read().iter().map(|tx| Arc::clone(&tx.tx)).collect()
+    }
 }
 
 impl<T, V, O> Clone for Pool<T, V, O>

crates/rpc/rpc-api/src/lib.rs

@@ -5,6 +5,7 @@ pub mod error;
 pub mod katana;
 pub mod starknet;
 pub mod starknet_ext;
+pub mod txpool;
 
 #[cfg(feature = "cartridge")]
 pub mod cartridge;

crates/rpc/rpc-api/src/txpool.rs

@@ -0,0 +1,51 @@
+use jsonrpsee::core::RpcResult;
+use jsonrpsee::proc_macros::rpc;
+use katana_primitives::ContractAddress;
+use katana_rpc_types::txpool::{TxPoolContent, TxPoolInspect, TxPoolStatus};
+
+/// Inspection API for the node's local transaction pool.
+///
+/// This exposes the node's own pending-transaction pool — not a network-wide mempool.
+/// Unlike Ethereum, Starknet does not yet have a shared peer-to-peer mempool; each sequencer
+/// maintains its own pool of transactions waiting to be included in a block. The
+/// transactions visible here are only those that have been submitted to *this* node.
+///
+/// This API is primarily intended for debugging and diagnostics.
+///
+/// Modeled after Ethereum's `txpool_*` namespace, adapted for Starknet transactions.
+///
+/// All responses distinguish between `pending` (ready to execute) and `queued` (waiting on
+/// a nonce gap) transactions. Currently Katana has no queued pool — dependent transactions
+/// are rejected at submission — so the `queued` fields are always empty/zero. They exist
+/// for forward-compatibility.
+#[cfg_attr(not(feature = "client"), rpc(server, namespace = "txpool"))]
+#[cfg_attr(feature = "client", rpc(client, server, namespace = "txpool"))]
+pub trait TxPoolApi {
+    /// Returns the number of pending and queued transactions in the pool.
+    ///
+    /// This is a cheap call that avoids snapshotting individual transactions.
+    #[method(name = "status")]
+    async fn txpool_status(&self) -> RpcResult<TxPoolStatus>;
+
+    /// Returns the full content of the pool, grouped by sender address and nonce.
+    ///
+    /// Each transaction is represented as a lightweight [`TxPoolTransaction`] containing
+    /// the hash, nonce, sender, max_fee, and tip. The full transaction can be retrieved
+    /// via `starknet_getTransactionByHash`.
+    #[method(name = "content")]
+    async fn txpool_content(&self) -> RpcResult<TxPoolContent>;
+
+    /// Same as `txpool_content` but filtered to a single sender address.
+    ///
+    /// Returns only the transactions from the given address. The `queued` map is always empty.
+    #[method(name = "contentFrom")]
+    async fn txpool_content_from(&self, address: ContractAddress) -> RpcResult<TxPoolContent>;
+
+    /// Returns a textual summary of all pooled transactions, grouped by sender and nonce.
+    ///
+    /// Each transaction is represented as a human-readable string
+    /// (`hash=0x… nonce=0x… max_fee=… tip=…`) rather than a structured object —
+    /// useful for quick inspection or logging.
+    #[method(name = "inspect")]
+    async fn txpool_inspect(&self) -> RpcResult<TxPoolInspect>;
+}

crates/rpc/rpc-server/src/lib.rs

@@ -29,6 +29,7 @@ pub mod health;
 pub mod metrics;
 pub mod permit;
 pub mod starknet;
+pub mod txpool;
 
 mod logger;
 mod utils;

crates/rpc/rpc-server/src/txpool.rs

@@ -0,0 +1,87 @@
+use std::collections::BTreeMap;
+
+use jsonrpsee::core::{async_trait, RpcResult};
+use katana_pool::{PoolTransaction, TransactionPool};
+use katana_primitives::ContractAddress;
+use katana_rpc_api::txpool::TxPoolApiServer;
+use katana_rpc_types::txpool::{TxPoolContent, TxPoolInspect, TxPoolStatus, TxPoolTransaction};
+
+/// Handler for the `txpool_*` RPC namespace.
+///
+/// Operates on the node's local transaction pool (not a network-wide mempool).
+/// Generic over any [`TransactionPool`] implementation, so it works with both
+/// the sequencer pool ([`TxPool`]) and the full-node pool ([`FullNodePool`]).
+#[allow(missing_debug_implementations)]
+pub struct TxPoolApi<P> {
+    pool: P,
+}
+
+impl<P> TxPoolApi<P> {
+    pub fn new(pool: P) -> Self {
+        Self { pool }
+    }
+}
+
+impl<P: TransactionPool> TxPoolApi<P> {
+    fn build_content(&self, filter: Option<ContractAddress>) -> TxPoolContent {
+        let txs = self.pool.take_transactions_snapshot();
+        let mut pending: BTreeMap<ContractAddress, BTreeMap<_, _>> = BTreeMap::new();
+
+        for tx in txs {
+            let sender = tx.sender();
+
+            if let Some(addr) = filter {
+                if sender != addr {
+                    continue;
+                }
+            }
+
+            let entry = TxPoolTransaction {
+                hash: tx.hash(),
+                nonce: tx.nonce(),
+                sender,
+                max_fee: tx.max_fee(),
+                tip: tx.tip(),
+            };
+
+            pending.entry(sender).or_default().insert(tx.nonce(), entry);
+        }
+
+        TxPoolContent { pending, queued: BTreeMap::new() }
+    }
+}
+
+#[async_trait]
+impl<P: TransactionPool + 'static> TxPoolApiServer for TxPoolApi<P> {
+    async fn txpool_status(&self) -> RpcResult<TxPoolStatus> {
+        let pending = self.pool.size() as u64;
+        Ok(TxPoolStatus { pending, queued: 0 })
+    }
+
+    async fn txpool_content(&self) -> RpcResult<TxPoolContent> {
+        Ok(self.build_content(None))
+    }
+
+    async fn txpool_content_from(&self, address: ContractAddress) -> RpcResult<TxPoolContent> {
+        Ok(self.build_content(Some(address)))
+    }
+
+    async fn txpool_inspect(&self) -> RpcResult<TxPoolInspect> {
+        let txs = self.pool.take_transactions_snapshot();
+        let mut pending: BTreeMap<ContractAddress, BTreeMap<_, _>> = BTreeMap::new();
+
+        for tx in txs {
+            let summary = format!(
+                "hash={:#x} nonce={:#x} max_fee={} tip={}",
+                tx.hash(),
+                tx.nonce(),
+                tx.max_fee(),
+                tx.tip(),
+            );
+
+            pending.entry(tx.sender()).or_default().insert(tx.nonce(), summary);
+        }
+
+        Ok(TxPoolInspect { pending, queued: BTreeMap::new() })
+    }
+}