From 58556173f65bf86803f76ea5626dbaf8e9ad33cb Mon Sep 17 00:00:00 2001
From: Csaba Kiraly <csaba.kiraly@gmail.com>
Date: Fri, 10 Apr 2026 08:59:09 +0200
Subject: [PATCH] eth: improve package and type documentation for txtracker and
 dropper
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Expand the txtracker package doc to describe the tracking flow
(NotifyReceived → chain head → finalization → peer credit) and its
role as stats provider for the dropper.

Rewrite the dropper struct comment to document the full behavior
including the inclusion-based peer protection: two scoring categories
(total finalized + recent EMA), top 10% per pool, union of protected
sets.
---
 eth/dropper.go           | 18 +++++++++++++-----
 eth/txtracker/tracker.go | 11 +++++++++--
 2 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/eth/dropper.go b/eth/dropper.go
index e8710c3ec7..87c72cfa0f 100644
--- a/eth/dropper.go
+++ b/eth/dropper.go
@@ -83,11 +83,19 @@ var protectionCategories = []protectionCategory{
 	{"recent-included", func(s PeerInclusionStats) float64 { return s.RecentIncluded }, inclusionProtectionFrac},
 }
 
-// dropper monitors the state of the peer pool and makes changes as follows:
-//   - during sync the Downloader handles peer connections, so dropper is disabled
-//   - if not syncing and the peer count is close to the limit, it drops peers
-//     randomly every peerDropInterval to make space for new peers
-//   - peers are dropped separately from the inboud pool and from the dialed pool
+// dropper monitors the state of the peer pool and introduces churn by
+// periodically disconnecting a random peer to make room for new connections.
+//
+// Behavior:
+//   - During sync the Downloader handles peer connections, so dropper is disabled.
+//   - When not syncing and a peer category (inbound or dialed) is close to its
+//     limit, a random peer from that category is disconnected every 3–7 minutes.
+//   - Trusted, static, and recently connected peers are never dropped.
+//   - Peers that contribute the most on-chain transaction inclusions are
+//     protected from dropping. Two scoring categories are used (total finalized
+//     inclusions and recent inclusion EMA), each protecting the top 10% of
+//     inbound and dialed peers independently. The union of all protected sets
+//     is shielded; the drop target is chosen randomly from the remainder.
 type dropper struct {
 	maxDialPeers    int // maximum number of dialed peers
 	maxInboundPeers int // maximum number of inbound peers
diff --git a/eth/txtracker/tracker.go b/eth/txtracker/tracker.go
index 5fc479a49c..aa962cdf32 100644
--- a/eth/txtracker/tracker.go
+++ b/eth/txtracker/tracker.go
@@ -1,6 +1,13 @@
 // Package txtracker provides minimal per-peer transaction inclusion tracking.
-// It records which peer delivered each transaction and credits peers when
-// their delivered transactions are included on chain.
+//
+// It records which peer delivered each transaction body (via NotifyReceived)
+// and monitors the chain for inclusion and finalization events. When a
+// delivered transaction is finalized on chain, the delivering peer is
+// credited. A per-block exponential moving average (EMA) of inclusions
+// tracks recent peer productivity.
+//
+// The primary consumer is the peer dropper (eth/dropper.go), which uses
+// these stats to protect high-value peers from random disconnection.
 package txtracker
 
 import (