lnd: wire read-only reputation subsystem behind a flag

Construct the local reputation manager in the server when the experimental
routing.reputation flag is set (default off), and wire it into the switch via
a small adapter that bridges the switch's ReputationManager interface to the
reputation package. When the flag is off the manager is nil and the hooks are
no-ops with zero overhead, so the switch is byte-for-byte unchanged.

This also registers the REPM subsystem logger with the root logger; without
it the log-only subsystem would emit nothing in a running node.

Author: GeorgeTsagk

docs/release-notes/release-notes-0.22.0.md

@@ -46,6 +46,15 @@
 
 ## Functional Enhancements
 
+* A new experimental, off-by-default [local reputation
+  subsystem](https://github.com/lightningnetwork/lnd/pull/10919) has been added
+  as a first step toward mitigating channel jamming (per
+  [bolts#1280](https://github.com/lightning/bolts/pull/1280)). When enabled with
+  `--routing.reputation`, it observes forwarded HTLCs to track the historical
+  behavior of peers and compute local reputation and resource-bucket decisions.
+  It is strictly **log-only**: it records its decisions but never affects HTLC
+  forwarding or the wire.
+
 ## RPC Additions
 
 * The `routerrpc.EstimateRouteFee` RPC now supports [restricting fee estimates

lncfg/routing.go

@@ -10,6 +10,8 @@ type Routing struct {
 
 	StrictZombiePruning bool `long:"strictgraphpruning" description:"If true, then the graph will be pruned more aggressively for zombies. In practice this means that edges with a single stale edge will be considered a zombie."`
 
+	Reputation bool `long:"reputation" description:"EXPERIMENTAL: enable the read-only local reputation subsystem (channel jamming mitigation). It only observes HTLC forwarding to compute and log reputation; it does NOT affect routing."`
+
 	BlindedPaths BlindedPaths `group:"blinding" namespace:"blinding"`
 }
 

log.go

@@ -52,6 +52,7 @@ import (
 	"github.com/lightningnetwork/lnd/peer"
 	"github.com/lightningnetwork/lnd/peernotifier"
 	"github.com/lightningnetwork/lnd/protofsm"
+	"github.com/lightningnetwork/lnd/reputation"
 	"github.com/lightningnetwork/lnd/routing"
 	"github.com/lightningnetwork/lnd/routing/blindedpath"
 	"github.com/lightningnetwork/lnd/routing/localchans"
@@ -216,6 +217,7 @@ func SetupLoggers(root *build.SubLoggerManager, interceptor signal.Interceptor)
 	)
 
 	AddSubLogger(root, onionmessage.Subsystem, interceptor, onionmessage.UseLogger)
+	AddSubLogger(root, reputation.Subsystem, interceptor, reputation.UseLogger)
 }
 
 // AddSubLogger is a helper method to conveniently create and register the

reputation_adapter.go

@@ -0,0 +1,127 @@
+package lnd
+
+import (
+	"github.com/lightningnetwork/lnd/channeldb"
+	"github.com/lightningnetwork/lnd/channelnotifier"
+	"github.com/lightningnetwork/lnd/chanstate"
+	"github.com/lightningnetwork/lnd/reputation"
+)
+
+// reputationChannelSource adapts the channel database and channel notifier to
+// the read-only reputation.ChannelSource seam. It exposes the node's active
+// channels (with their holder-side capacity limits, used to size resource
+// buckets) and a stream of open/close events. It is strictly read-only.
+type reputationChannelSource struct {
+	chanDB   chanstate.Store
+	notifier *channelnotifier.ChannelNotifier
+}
+
+// newReputationChannelSource builds a reputation.ChannelSource backed by the
+// channel state db and channel notifier.
+func newReputationChannelSource(chanDB chanstate.Store,
+	notifier *channelnotifier.ChannelNotifier) reputation.ChannelSource {
+
+	return &reputationChannelSource{
+		chanDB:   chanDB,
+		notifier: notifier,
+	}
+}
+
+// channelInfo extracts the reputation-relevant capacity limits from an open
+// channel, reading the holder (local) side limits (matching LDK's
+// get_holder_max_*).
+func channelInfo(c *channeldb.OpenChannel) reputation.ChannelInfo {
+	return reputation.ChannelInfo{
+		SCID:             c.ShortChanID(),
+		MaxAcceptedHTLCs: c.LocalChanCfg.MaxAcceptedHtlcs,
+		MaxInFlightMsat:  c.LocalChanCfg.MaxPendingAmount,
+	}
+}
+
+// ActiveChannels returns the node's currently open channels and their limits.
+func (r *reputationChannelSource) ActiveChannels() ([]reputation.ChannelInfo,
+	error) {
+
+	channels, err := r.chanDB.FetchAllOpenChannels()
+	if err != nil {
+		return nil, err
+	}
+
+	infos := make([]reputation.ChannelInfo, 0, len(channels))
+	for _, c := range channels {
+		infos = append(infos, channelInfo(c))
+	}
+
+	return infos, nil
+}
+
+// SubscribeChannelEvents returns a stream of open/close events and a cancel
+// func. A goroutine translates the channel notifier's events into the
+// reputation seam's ChannelEvent type until cancelled.
+func (r *reputationChannelSource) SubscribeChannelEvents() (
+	<-chan reputation.ChannelEvent, func(), error) {
+
+	client, err := r.notifier.SubscribeChannelEvents()
+	if err != nil {
+		return nil, nil, err
+	}
+
+	out := make(chan reputation.ChannelEvent, 16)
+	quit := make(chan struct{})
+
+	go func() {
+		defer close(out)
+		for {
+			select {
+			case <-quit:
+				return
+
+			case e, ok := <-client.Updates():
+				if !ok {
+					return
+				}
+
+				ev, relay := translateChannelEvent(e)
+				if !relay {
+					continue
+				}
+
+				select {
+				case out <- ev:
+				case <-quit:
+					return
+				}
+			}
+		}
+	}()
+
+	cancel := func() {
+		close(quit)
+		client.Cancel()
+	}
+
+	return out, cancel, nil
+}
+
+// translateChannelEvent maps a channel notifier event to the reputation seam's
+// ChannelEvent, returning relay=false for events that are not open/close.
+func translateChannelEvent(e interface{}) (reputation.ChannelEvent, bool) {
+	switch ev := e.(type) {
+	case channelnotifier.OpenChannelEvent:
+		return reputation.ChannelEvent{
+			Info: channelInfo(ev.Channel),
+			Open: true,
+		}, true
+
+	case channelnotifier.ClosedChannelEvent:
+		return reputation.ChannelEvent{
+			Info: reputation.ChannelInfo{
+				SCID: ev.CloseSummary.ShortChanID,
+			},
+			Open: false,
+		}, true
+
+	default:
+		return reputation.ChannelEvent{}, false
+	}
+}

server.go

@@ -75,6 +75,7 @@ import (
 	"github.com/lightningnetwork/lnd/peernotifier"
 	"github.com/lightningnetwork/lnd/pool"
 	"github.com/lightningnetwork/lnd/queue"
+	"github.com/lightningnetwork/lnd/reputation"
 	"github.com/lightningnetwork/lnd/routing"
 	"github.com/lightningnetwork/lnd/routing/localchans"
 	"github.com/lightningnetwork/lnd/routing/route"
@@ -357,6 +358,10 @@ type server struct {
 
 	htlcNotifier *htlcswitch.HtlcNotifier
 
+	// reputationMgr is the optional read-only local reputation subsystem,
+	// non-nil only when the experimental reputation flag is set.
+	reputationMgr *reputation.Manager
+
 	witnessBeacon contractcourt.WitnessBeacon
 
 	breachArbitrator *contractcourt.BreachArbitrator
@@ -880,6 +885,44 @@ func newServer(ctx context.Context, cfg *Config, listenAddrs []net.Addr,
 		return nil, err
 	}
 
+	// Construct the optional read-only local reputation subsystem. It only
+	// observes HTLC forwarding to compute and log reputation; it never
+	// affects routing (log-only). When the flag is off, repMgrIface stays a
+	// nil interface so the switch skips the hooks entirely.
+	var repMgrIface htlcswitch.ReputationManager
+	if cfg.Routing.Reputation {
+		chainIO := s.cc.ChainIO
+		s.reputationMgr, err = reputation.NewManager(
+			reputation.DefaultConfig(),
+			reputation.WithHeightSource(func() uint32 {
+				_, height, err := chainIO.GetBestBlock()
+				if err != nil {
+					return 0
+				}
+
+				return uint32(height)
+			}),
+			reputation.WithChannelSource(newReputationChannelSource(
+				s.chanStateDB, s.channelNotifier,
+			)),
+			reputation.WithStore(
+				reputation.NewKVDBStore(dbs.ChanStateDB),
+			),
+		)
+		if err != nil {
+			return nil, err
+		}
+
+		// Wrap the manager in a panic boundary before handing it to
+		// the switch: the hooks run on the forwarding goroutine, so a
+		// bug in the (log-only) subsystem must never take down HTLC
+		// forwarding. On a hook panic the guard logs, disables the
+		// subsystem, and forwarding continues unaffected.
+		repMgrIface = htlcswitch.NewGuardedReputationManager(
+			s.reputationMgr,
+		)
+	}
+
 	s.htlcSwitch, err = htlcswitch.New(htlcswitch.Config{
 		DB:                   dbs.ChanStateDB,
 		FetchAllOpenChannels: s.chanStateDB.FetchAllOpenChannels,
@@ -905,6 +948,7 @@ func newServer(ctx context.Context, cfg *Config, listenAddrs []net.Addr,
 		FetchLastChannelUpdate: s.fetchLastChanUpdate(),
 		Notifier:               s.cc.ChainNotifier,
 		HtlcNotifier:           s.htlcNotifier,
+		ReputationManager:      repMgrIface,
 		FwdEventTicker:         ticker.New(htlcswitch.DefaultFwdEventInterval),
 		LogEventTicker:         ticker.New(htlcswitch.DefaultLogInterval),
 		AckEventTicker:         ticker.New(htlcswitch.DefaultAckInterval),
@@ -2349,6 +2393,14 @@ func (s *server) Start(ctx context.Context) error {
 			return
 		}
 
+		if s.reputationMgr != nil {
+			cleanup = cleanup.add(s.reputationMgr.Stop)
+			if err := s.reputationMgr.Start(); err != nil {
+				startErr = err
+				return
+			}
+		}
+
 		if s.towerClientMgr != nil {
 			cleanup = cleanup.add(s.towerClientMgr.Stop)
 			if err := s.towerClientMgr.Start(); err != nil {
@@ -2835,6 +2887,12 @@ func (s *server) Stop() error {
 		if err := s.htlcNotifier.Stop(); err != nil {
 			srvrLog.Warnf("failed to stop htlcNotifier: %v", err)
 		}
+		if s.reputationMgr != nil {
+			if err := s.reputationMgr.Stop(); err != nil {
+				srvrLog.Warnf("failed to stop reputationMgr: "+
+					"%v", err)
+			}
+		}
 
 		// Update channel.backup file. Make sure to do it before
 		// stopping chanSubSwapper.