libp2p / libp2p/jvm-libp2p

Remove hardcoded 256-peer caps from GossipSub peer bookkeeping

Open
#514 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Kotlin
Stars
366
Forks
85
Avg merge
2d 39m
Merged PRs (30d)
6

Description

## Origin

This is the follow up to discussion in #513

## Problem

`GossipRouter` currently uses several hardcoded `256` limits for peer-scoped bookkeeping maps:

https://github.com/libp2p/jvm-libp2p/blob/8b82529755ed543f42a03e0aacec61a78255bd54/libp2p/src/main/kotlin/io/libp2p/pubsub/gossip/GossipRouter.kt#L53-L58

These constants effectively impose an accidental router-capacity assumption inside GossipSub internals. On nodes with more than 256 active pubsub peers, entries can be evicted even though the peer is still connected and relevant.

This is especially problematic because these maps are used for control-message accounting and defensive behavior, not for mesh sizing. Mesh limits such as `D`, `DLow`, and `DHigh` are per-topic mesh parameters and should not imply a global router peer limit.

## Why This Matters

Evicting peer-scoped state can weaken or distort protocol behavior at scale. For example:

- IHAVE accounting may be reset for peers evicted during a heartbeat.
- IDONTWANT state may be dropped before its intended TTL.
- slow-peer pressure tracking may lose continuity.
- behavior changes silently once the node interacts with more than 256 peers.

This makes `256` a hidden scalability limit rather than an explicit configuration or protocol parameter.

## Suggested Direction

Remove the fixed `256` caps for state that is naturally bounded by connected peers or heartbeat scope:

- use normal maps for per-heartbeat peer counters such as `iAsked` and `peerIHave`;
- rely on heartbeat clearing, TTL cleanup, peer disconnect cleanup, and existing per-peer limits;
- avoid tying these limits to mesh parameters like `D` or `DHigh`.

For caches that can grow by peer-topic or peer-message combinations, keep explicit configurable bounds instead, for example:

- backoff entries;
- IWANT follow-up request entries.

These should be exposed through `GossipParams` rather than file-level constants.

## Notes

A hard limit on total pubsub peers, if needed, should be implemented explicitly at the connection management or pubsub admission layer, not indirectly through eviction of GossipSub bookkeeping state.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in libp2p/src/main/kotlin/io/libp2p/pubsub/gossip/GossipRouter.kt at the referenced 256-entry maps, then inspect GossipParams and the cleanup paths for iAsked, peerIHave, backoff, and IWANT state. Done means heartbeat-scoped peer counters no longer use fixed caps, while peer-topic or peer-message caches retain configurable bounds exposed through GossipParams.

Written by the indexing model from the issue text.

Assessment

Tech stack
kotlin
Domain
distributed-systems, networking
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.