eth: improve package and type documentation for txtracker and dropper

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.
This commit is contained in:
Csaba Kiraly 2026-04-10 08:59:09 +02:00
parent 98ffc7bd37
commit 58556173f6
2 changed files with 22 additions and 7 deletions

View file

@ -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 37 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

View file

@ -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 (