Feature: --p2p-colocation-whitelist flag to allow certain IPs to bypass colocation restrictions (#15685)

* Add flag for colocation whitelisting. --p2p-ip-colocation-whitelist

This change updates the peer IP colocation checking to respect the
configured CIDR whitelist (--p2p-ip-colocation-whitelist flag).

Changes:
- Added IPColocationWhitelist field to peers.StatusConfig
- Added ipColocationWhitelist field to Status struct to store parsed IPNets
- Parse CIDR strings into net.IPNet in NewStatus constructor
- Updated isfromBadIP method to skip colocation limits for whitelisted IPs
- Pass IPColocationWhitelist from Service config when creating Status

The IP colocation whitelist allows operators to exempt specific IP ranges
from the colocation limit, useful for deployments with known trusted
address ranges or legitimate node clustering.

Only check if an IP is in the whitelist when the colocation limit
is actually exceeded, rather than checking for every IP. This is
more efficient and matches the intended behavior.

* Changelog fragment

* Apply suggestion from @nalepae

Co-authored-by: Manu NALEPA <enalepa@offchainlabs.com>

* Apply suggestion from @nalepae

Co-authored-by: Manu NALEPA <enalepa@offchainlabs.com>

* @kasey feedback: Move IP colocation parsing to the node construction

---------

Co-authored-by: Manu NALEPA <enalepa@offchainlabs.com>

beacon-chain/node/node.go

@@ -621,35 +621,55 @@ func (b *BeaconNode) startStateGen(ctx context.Context, bfs coverage.AvailableBl
 	return nil
 }
 
+func parseIPNetStrings(ipWhitelist []string) ([]*net.IPNet, error) {
+	ipNets := make([]*net.IPNet, 0, len(ipWhitelist))
+	for _, cidr := range ipWhitelist {
+		_, ipNet, err := net.ParseCIDR(cidr)
+		if err != nil {
+			log.WithError(err).WithField("cidr", cidr).Error("Invalid CIDR in IP colocation whitelist")
+			return nil, err
+		}
+		ipNets = append(ipNets, ipNet)
+		log.WithField("cidr", cidr).Info("Added IP to colocation whitelist")
+	}
+	return ipNets, nil
+}
+
 func (b *BeaconNode) registerP2P(cliCtx *cli.Context) error {
 	bootstrapNodeAddrs, dataDir, err := registration.P2PPreregistration(cliCtx)
 	if err != nil {
 		return errors.Wrapf(err, "could not register p2p service")
 	}
 
+	colocationWhitelist, err := parseIPNetStrings(slice.SplitCommaSeparated(cliCtx.StringSlice(cmd.P2PColocationWhitelist.Name)))
+	if err != nil {
+		return fmt.Errorf("failed to register p2p service: %w", err)
+	}
+
 	svc, err := p2p.NewService(b.ctx, &p2p.Config{
-		NoDiscovery:          cliCtx.Bool(cmd.NoDiscovery.Name),
-		StaticPeers:          slice.SplitCommaSeparated(cliCtx.StringSlice(cmd.StaticPeers.Name)),
-		Discv5BootStrapAddrs: p2p.ParseBootStrapAddrs(bootstrapNodeAddrs),
-		RelayNodeAddr:        cliCtx.String(cmd.RelayNode.Name),
-		DataDir:              dataDir,
-		DiscoveryDir:         filepath.Join(dataDir, "discovery"),
-		LocalIP:              cliCtx.String(cmd.P2PIP.Name),
-		HostAddress:          cliCtx.String(cmd.P2PHost.Name),
-		HostDNS:              cliCtx.String(cmd.P2PHostDNS.Name),
-		PrivateKey:           cliCtx.String(cmd.P2PPrivKey.Name),
-		StaticPeerID:         cliCtx.Bool(cmd.P2PStaticID.Name),
-		QUICPort:             cliCtx.Uint(cmd.P2PQUICPort.Name),
-		TCPPort:              cliCtx.Uint(cmd.P2PTCPPort.Name),
-		UDPPort:              cliCtx.Uint(cmd.P2PUDPPort.Name),
-		MaxPeers:             cliCtx.Uint(cmd.P2PMaxPeers.Name),
-		QueueSize:            cliCtx.Uint(cmd.PubsubQueueSize.Name),
-		AllowListCIDR:        cliCtx.String(cmd.P2PAllowList.Name),
-		DenyListCIDR:         slice.SplitCommaSeparated(cliCtx.StringSlice(cmd.P2PDenyList.Name)),
-		EnableUPnP:           cliCtx.Bool(cmd.EnableUPnPFlag.Name),
-		StateNotifier:        b,
-		DB:                   b.db,
-		ClockWaiter:          b.clockWaiter,
+		NoDiscovery:           cliCtx.Bool(cmd.NoDiscovery.Name),
+		StaticPeers:           slice.SplitCommaSeparated(cliCtx.StringSlice(cmd.StaticPeers.Name)),
+		Discv5BootStrapAddrs:  p2p.ParseBootStrapAddrs(bootstrapNodeAddrs),
+		RelayNodeAddr:         cliCtx.String(cmd.RelayNode.Name),
+		DataDir:               dataDir,
+		DiscoveryDir:          filepath.Join(dataDir, "discovery"),
+		LocalIP:               cliCtx.String(cmd.P2PIP.Name),
+		HostAddress:           cliCtx.String(cmd.P2PHost.Name),
+		HostDNS:               cliCtx.String(cmd.P2PHostDNS.Name),
+		PrivateKey:            cliCtx.String(cmd.P2PPrivKey.Name),
+		StaticPeerID:          cliCtx.Bool(cmd.P2PStaticID.Name),
+		QUICPort:              cliCtx.Uint(cmd.P2PQUICPort.Name),
+		TCPPort:               cliCtx.Uint(cmd.P2PTCPPort.Name),
+		UDPPort:               cliCtx.Uint(cmd.P2PUDPPort.Name),
+		MaxPeers:              cliCtx.Uint(cmd.P2PMaxPeers.Name),
+		QueueSize:             cliCtx.Uint(cmd.PubsubQueueSize.Name),
+		AllowListCIDR:         cliCtx.String(cmd.P2PAllowList.Name),
+		DenyListCIDR:          slice.SplitCommaSeparated(cliCtx.StringSlice(cmd.P2PDenyList.Name)),
+		IPColocationWhitelist: colocationWhitelist,
+		EnableUPnP:            cliCtx.Bool(cmd.EnableUPnPFlag.Name),
+		StateNotifier:         b,
+		DB:                    b.db,
+		ClockWaiter:           b.clockWaiter,
 	})
 	if err != nil {
 		return err

beacon-chain/node/node_test.go

@@ -262,3 +262,46 @@ func TestCORS(t *testing.T) {
 		})
 	}
 }
+
+func TestParseIPNetStrings(t *testing.T) {
+	tests := []struct {
+		name      string
+		whitelist []string
+		wantCount int
+		wantError string
+	}{
+		{
+			name:      "empty whitelist",
+			whitelist: []string{},
+			wantCount: 0,
+		},
+		{
+			name:      "single IP whitelist",
+			whitelist: []string{"192.168.1.1/32"},
+			wantCount: 1,
+		},
+		{
+			name:      "multiple IPs whitelist",
+			whitelist: []string{"192.168.1.0/24", "10.0.0.0/8", "34.42.19.170/32"},
+			wantCount: 3,
+		},
+		{
+			name:      "invalid CIDR returns error",
+			whitelist: []string{"192.168.1.0/24", "invalid-cidr", "10.0.0.0/8"},
+			wantCount: 0,
+			wantError: "invalid CIDR address",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result, err := parseIPNetStrings(tt.whitelist)
+			assert.Equal(t, tt.wantCount, len(result))
+			if len(tt.wantError) == 0 {
+				assert.Equal(t, nil, err)
+			} else {
+				assert.ErrorContains(t, tt.wantError, err)
+			}
+		})
+	}
+}

beacon-chain/p2p/config.go

@@ -1,6 +1,7 @@
 package p2p
 
 import (
+	"net"
 	"time"
 
 	statefeed "github.com/OffchainLabs/prysm/v6/beacon-chain/core/feed/state"
@@ -14,30 +15,31 @@ const defaultPubsubQueueSize = 600
 // Config for the p2p service. These parameters are set from application level flags
 // to initialize the p2p service.
 type Config struct {
-	NoDiscovery          bool
-	EnableUPnP           bool
-	StaticPeerID         bool
-	DisableLivenessCheck bool
-	StaticPeers          []string
-	Discv5BootStrapAddrs []string
-	RelayNodeAddr        string
-	LocalIP              string
-	HostAddress          string
-	HostDNS              string
-	PrivateKey           string
-	DataDir              string
-	DiscoveryDir         string
-	QUICPort             uint
-	TCPPort              uint
-	UDPPort              uint
-	PingInterval         time.Duration
-	MaxPeers             uint
-	QueueSize            uint
-	AllowListCIDR        string
-	DenyListCIDR         []string
-	StateNotifier        statefeed.Notifier
-	DB                   db.ReadOnlyDatabaseWithSeqNum
-	ClockWaiter          startup.ClockWaiter
+	NoDiscovery           bool
+	EnableUPnP            bool
+	StaticPeerID          bool
+	DisableLivenessCheck  bool
+	StaticPeers           []string
+	Discv5BootStrapAddrs  []string
+	RelayNodeAddr         string
+	LocalIP               string
+	HostAddress           string
+	HostDNS               string
+	PrivateKey            string
+	DataDir               string
+	DiscoveryDir          string
+	QUICPort              uint
+	TCPPort               uint
+	UDPPort               uint
+	PingInterval          time.Duration
+	MaxPeers              uint
+	QueueSize             uint
+	AllowListCIDR         string
+	DenyListCIDR          []string
+	IPColocationWhitelist []*net.IPNet
+	StateNotifier         statefeed.Notifier
+	DB                    db.ReadOnlyDatabaseWithSeqNum
+	ClockWaiter           startup.ClockWaiter
 }
 
 // validateConfig validates whether the values provided are accurate and will set

beacon-chain/p2p/gossip_scoring_params.go

@@ -3,6 +3,7 @@ package p2p
 import (
 	"context"
 	"math"
+	"net"
 	"reflect"
 	"strings"
 	"time"
@@ -75,7 +76,7 @@ var (
 	tenEpochs          = 10 * oneEpochDuration()
 )
 
-func peerScoringParams() (*pubsub.PeerScoreParams, *pubsub.PeerScoreThresholds) {
+func peerScoringParams(colocationWhitelist []*net.IPNet) (*pubsub.PeerScoreParams, *pubsub.PeerScoreThresholds) {
 	thresholds := &pubsub.PeerScoreThresholds{
 		GossipThreshold:             -4000,
 		PublishThreshold:            -8000,
@@ -83,6 +84,7 @@ func peerScoringParams() (*pubsub.PeerScoreParams, *pubsub.PeerScoreThresholds)
 		AcceptPXThreshold:           100,
 		OpportunisticGraftThreshold: 5,
 	}
+
 	scoreParams := &pubsub.PeerScoreParams{
 		Topics:        make(map[string]*pubsub.TopicScoreParams),
 		TopicScoreCap: 32.72,
@@ -92,7 +94,7 @@ func peerScoringParams() (*pubsub.PeerScoreParams, *pubsub.PeerScoreThresholds)
 		AppSpecificWeight:           1,
 		IPColocationFactorWeight:    -35.11,
 		IPColocationFactorThreshold: 10,
-		IPColocationFactorWhitelist: nil,
+		IPColocationFactorWhitelist: colocationWhitelist,
 		BehaviourPenaltyWeight:      -15.92,
 		BehaviourPenaltyThreshold:   6,
 		BehaviourPenaltyDecay:       scoreDecay(tenEpochs),

beacon-chain/p2p/peers/status.go

@@ -25,6 +25,7 @@ package peers
 import (
 	"context"
 	"math"
+	"net"
 	"sort"
 	"strings"
 	"time"
@@ -87,11 +88,12 @@ const (
 
 // Status is the structure holding the peer status information.
 type Status struct {
-	ctx       context.Context
-	scorers   *scorers.Service
-	store     *peerdata.Store
-	ipTracker map[string]uint64
-	rand      *rand.Rand
+	ctx                   context.Context
+	scorers               *scorers.Service
+	store                 *peerdata.Store
+	ipTracker             map[string]uint64
+	rand                  *rand.Rand
+	ipColocationWhitelist []*net.IPNet
 }
 
 // StatusConfig represents peer status service params.
@@ -100,6 +102,8 @@ type StatusConfig struct {
 	PeerLimit int
 	// ScorerParams holds peer scorer configuration params.
 	ScorerParams *scorers.Config
+	// IPColocationWhitelist contains CIDR ranges that are exempt from IP colocation limits.
+	IPColocationWhitelist []*net.IPNet
 }
 
 // NewStatus creates a new status entity.
@@ -107,11 +111,13 @@ func NewStatus(ctx context.Context, config *StatusConfig) *Status {
 	store := peerdata.NewStore(ctx, &peerdata.StoreConfig{
 		MaxPeers: maxLimitBuffer + config.PeerLimit,
 	})
+
 	return &Status{
-		ctx:       ctx,
-		store:     store,
-		scorers:   scorers.NewService(ctx, store, config.ScorerParams),
-		ipTracker: map[string]uint64{},
+		ctx:                   ctx,
+		store:                 store,
+		scorers:               scorers.NewService(ctx, store, config.ScorerParams),
+		ipTracker:             map[string]uint64{},
+		ipColocationWhitelist: config.IPColocationWhitelist,
 		// Random generator used to calculate dial backoff period.
 		// It is ok to use deterministic generator, no need for true entropy.
 		rand: rand.NewDeterministicGenerator(),
@@ -1046,6 +1052,13 @@ func (p *Status) isfromBadIP(pid peer.ID) error {
 
 	if val, ok := p.ipTracker[ip.String()]; ok {
 		if val > CollocationLimit {
+			// Check if IP is in the whitelist
+			for _, ipNet := range p.ipColocationWhitelist {
+				if ipNet.Contains(ip) {
+					// IP is whitelisted, skip colocation limit check
+					return nil
+				}
+			}
 			return errors.Errorf(
 				"colocation limit exceeded: got %d - limit %d for peer %v with IP %v",
 				val, CollocationLimit, pid, ip.String(),

beacon-chain/p2p/pubsub.go

@@ -145,7 +145,7 @@ func (s *Service) pubsubOptions() []pubsub.Option {
 		pubsub.WithPeerOutboundQueueSize(int(s.cfg.QueueSize)),
 		pubsub.WithMaxMessageSize(int(MaxMessageSize())), // lint:ignore uintcast -- Max Message Size is a config value and is naturally bounded by networking limitations.
 		pubsub.WithValidateQueueSize(int(s.cfg.QueueSize)),
-		pubsub.WithPeerScore(peerScoringParams()),
+		pubsub.WithPeerScore(peerScoringParams(s.cfg.IPColocationWhitelist)),
 		pubsub.WithPeerScoreInspect(s.peerInspector, time.Minute),
 		pubsub.WithGossipSubParams(pubsubGossipParam()),
 		pubsub.WithRawTracer(gossipTracer{host: s.host}),

beacon-chain/p2p/service.go

@@ -178,7 +178,8 @@ func NewService(ctx context.Context, cfg *Config) (*Service, error) {
 	s.pubsub = gs
 
 	s.peers = peers.NewStatus(ctx, &peers.StatusConfig{
-		PeerLimit: int(s.cfg.MaxPeers),
+		PeerLimit:             int(s.cfg.MaxPeers),
+		IPColocationWhitelist: s.cfg.IPColocationWhitelist,
 		ScorerParams: &scorers.Config{
 			BadResponsesScorerConfig: &scorers.BadResponsesScorerConfig{
 				Threshold:     maxBadResponses,

changelog/pvl-p2p-colocation-whitelist.md

@@ -0,0 +1,3 @@
+### Added
+
+- Added flag `--p2p-colocation-whitelist` to accept CIDRs which will bypass the p2p colocation restrictions.

cmd/beacon-chain/main.go

@@ -105,6 +105,7 @@ var appFlags = []cli.Flag{
 	cmd.P2PStaticID,
 	cmd.P2PAllowList,
 	cmd.P2PDenyList,
+	cmd.P2PColocationWhitelist,
 	cmd.PubsubQueueSize,
 	cmd.DataDirFlag,
 	cmd.VerbosityFlag,

cmd/beacon-chain/usage.go

@@ -84,6 +84,7 @@ var appHelpFlagGroups = []flagGroup{
 			cmd.NoDiscovery,
 			cmd.P2PAllowList,
 			cmd.P2PDenyList,
+			cmd.P2PColocationWhitelist,
 			cmd.P2PHost,
 			cmd.P2PHostDNS,
 			cmd.P2PIP,

cmd/flags.go

@@ -180,6 +180,13 @@ var (
 			"192.168.0.0/16 would deny connections from peers on your local network only. The " +
 			"default is to accept all connections.",
 	}
+	// P2PColocationWhitelist defines a list of CIDR addresses to exempt from IP colocation restrictions.
+	P2PColocationWhitelist = &cli.StringSliceFlag{
+		Name: "p2p-colocation-whitelist",
+		Usage: "CIDR addresses to exempt from gossip sub IP colocation restrictions. " +
+			"Can be specified multiple times. Example: " +
+			"192.168.1.1/32 would exempt that specific IP from colocation restrictions.",
+	}
 	PubsubQueueSize = &cli.IntFlag{
 		Name:  "pubsub-queue-size",
 		Usage: "The size of the pubsub validation and outbound queue for the node.",