Wiki home

Documentation index · Source repository

This reference covers the declarative node configuration for the pinned go-libp2p-pubsub v0.13.1 and go-libp2p-kad-dht v0.31.0 dependencies. Use these blocks under a scenario profile or a join phase's node; see scenario configuration and the protocol example. Experiments run on Swarm. Validate YAML before deployment with kpl validate --scenario FILE.

Duration fields use Go strings such as 250ms, 1s, and 5m. Numeric tuning pointers preserve explicit 0, and boolean pointers preserve explicit false, wherever those values are valid. Lists and maps replace inherited lists and maps. Optional object blocks such as score, peerGater, and discovery replace the inherited object as a whole: repeat the settings you want to retain. A score block without enabled: true remains disabled, including after replacing an enabled profile score.

Version 3 profile schedules can update a defined subset of routing parameters and network conditions on existing and future selected Peers. Construction-only settings remain fixed. The schedule reference owns supported fields, timing, selection and failure behavior.

All fields in this section are under gossipsub. Omitted optional library settings retain the pinned library defaults. Built-in node presets can supply different mesh settings, as listed below.

GossipSub mesh parameters, HopWave, mesh freeze, active scoring, flood publishing, peer exchange, direct peers, and PeerGater apply to the GossipSub router. FloodSub can use custom protocol IDs without mesh features; RandomSub does not support a custom protocol list. Shared filters, validation, message IDs, publication, and discovery policies apply through the common PubSub API.

Set gossipsub.meshFreeze: true in a profile or join phase's node block to allow that Peer to freeze its GossipSub mesh later. The default is disabled. Let the mesh form, then use the scenario v3 mesh-freeze action. This option alone does not freeze startup with an empty mesh. Each command freezes all current topic meshes on each selected Peer; there is no topic selector or unfreeze command. Repeated calls succeed without changing the pinned membership.

The Peer adapter uses the vendored WithMeshFreeze() option and calls PubSub.FreezeMesh(ctx). Success acknowledges application on the PubSub event loop. After that point, heartbeat degree repair, score pruning, and opportunistic grafting cannot change mesh membership. Incoming GRAFT/PRUNE, remote unsubscription, and peer removal cannot add or remove pinned members. Pending and retried GRAFT/PRUNE controls are discarded. Pre-existing controls already dequeued for transmission or in flight can still arrive after the acknowledgment, which does not establish a network-wide instantaneous barrier.

The pinned mesh retains a bounded set of topic/Peer IDs for the lifetime of that PubSub instance. A disconnected member is not replaced; transport cleanup and the original positive/negative score-retention rules still apply. Reconnection restores an active mesh link only if the negotiated protocol supports mesh routing. Losing a local subscription or relay stops participation in that topic; rejoining an original topic can use its pinned members and clears publication-only fanout as usual. A newly joined topic receives no mesh members but can still exchange IHAVE/IWANT and heartbeat gossip. Starting new Peer processes creates a new unfrozen mesh.

Physical connections and remote subscriptions can still disappear. Pinned membership therefore does not guarantee usable links or message delivery. Caches, validation, scoring, lazy gossip, fanout, direct peers, flood publishing, and optional HopWave forwarding continue under their own rules. Messages already being validated can still finish caching and forwarding after local unsubscription, following normal PubSub behavior. Enable the option and send the command to every participant whose mesh must remain fixed. A multi-Peer command is applied separately on each Peer, so it cannot create one simultaneous network-wide snapshot; a timeout or failure can leave a subset frozen. Updated Controller, Agent, and Peer images are required.

The scenario topology action also uses meshFreeze: true to install an explicit graph before freezing. Its vendored ValidateMeshPlan and SetMeshAndFreeze APIs validate all requested neighbors; the latter replaces one participating topic and freezes all local topic meshes atomically on the router event loop. Identical frozen memberships are idempotent, while different frozen memberships conflict. Existing scoring arithmetic and connection accounting remain active; no synthetic GRAFT/PRUNE exchange is recorded.

HopWave is a broadcast protocol that combines reduced forwarding with periodic propagation reinforcement based on message hops. Its scholarly reference is Sungwook Lee and Hongtaek Ju, HopWave, APNOMS 2026, not yet published. The operational details below describe KPL's current implementation.

KPL implements HopWave within its pinned GossipSub copy, retaining the score inspection patch. It changes publication recipient selection; mesh maintenance and scoring keep their existing behavior. The source revision used for the port is recorded in the patch provenance linked below. Enable it on every participating profile, including PubSub-enabled boot nodes:

gossipsub:
  hopwave: true
  params:
    hopwaveFactor: 0.5
    hopwaveInterval: 3

The Peer adapter enables the vendored Go API with WithHopwavePublish(true) and maps the parameters to GossipSubParams.HopwaveFactor and HopwaveInterval. WithHopwave() enables metadata alone. Go identifiers treat hopwave as one word, with an initial capital where required for exported names.

The complete HopWave scenario runs on Swarm. Validate it with kpl validate --scenario examples/hopwave.yaml.

New publications seed the counter at zero. Each outgoing transmission advances the cached arrival counter once; reaching the configured interval resets it to zero. A zero outgoing counter sends to all eligible publication recipients, while other values use the factor. Selection includes direct peers and flood-publish targets after the existing sender/author exclusions and protocol/score/IDONTWANT rules. IWANT replies bypass the factor and keep normal request eligibility and retransmission limits. Defaults 1/1 preserve full forwarding when enabled without tuning.

Normal publication forwarding reports eager-push; IWANT responses report lazy-pull. Outgoing copies leave subscribers, cached arrivals and queued pushes unchanged, and repeated pull replies do not accumulate the counter. Missing, negative or overflowing counters remain unknown and use full publication forwarding.

With HopWave enabled, the library removes these mutable fields from the input to default and per-topic message ID callbacks. This keeps IDs stable across forwarding, duplicate detection and IWANT lookup. The declarative default, sha256 and topic-sha256 policies already use stable fields. Disabled HopWave preserves callback inputs; custom callbacks used with mixed settings must also use stable fields.

The wire hopCount is a cyclic wave counter, so it cannot replace absolute path length in research metrics. Propagation type describes the reported last transmission, not the complete publisher-to-receiver path. Both fields are unsigned mutable reports; the payload, topic, author and sequence remain signed. KPL retains them separately in detailed Peer logs, and existing reconstructed-path and eager/lazy estimates retain their definitions. Historical logs without the fields remain uninstrumented.

Protocol IDs remain GossipSub's, matching the reference fork. Unpatched signed-message verifiers do not support these wire fields. Use compatible builds and the same HopWave settings along the path; custom protocol IDs can isolate instrumented experiments through the existing protocol configuration. Updated Controller, Agent and Peer images are required. Patch provenance and upgrade notes identify the exact source and adaptation.

These fields live under gossipsub.params. Defaults below are KPL's base defaults before a node preset or profile override.

Initial heartbeat and direct-peer connection timers stop when the Peer context is canceled. Periodic direct-peer reconnects use the bounded connector queue; if it is full, remaining peers are retried on a later eligible heartbeat.

The router retains its address book until cancellation even if its event subscription fails or closes, and releases it on shutdown. A closed event stream does not trigger a polling loop.

Degree constraints include dLow <= d <= dHigh, 0 <= dScore <= d, dOut < dLow, and dOut <= d/2. History requires 0 <= historyGossip <= historyLength; d, dHigh, and historyLength are positive. Heartbeat interval and both tick counters are positive; other counts and durations are nonnegative. Gossip factor is finite and in [0,1]; slow-heartbeat warning is finite and nonnegative. Zero values can suppress activity and are not automatically replaced by defaults.

When PubSub is enabled on boot, its preset sets dScore: 3. Worker presets inherit dLow: 5, dScore: 3, maxIHaveLength: 5500, and heartbeatInitialDelay: 1s from v2. The typed schema and default resolver define the effective values.

Set gossipsub.score.enabled: true to install PeerScore. Omitting score, omitting score.enabled, or setting it to false disables scoring and inspection. An inactive block may preserve incomplete tuning; malformed durations, non-finite numbers, invalid CIDRs, invalid Peer IDs, and empty topic keys are still rejected. Active configurations additionally validate all relationships required by the router.

P5 is calculated as the selected value multiplied by appSpecificWeight. The peer-specific map takes precedence over the default, and values remain fixed for that Peer instance. These are libp2p Peer IDs, not scenario node IDs, groups, or profile names. Every value and its weighted result must be finite. The callback reads an immutable in-memory map and does not make network requests.

With active selective validation, omitting the entire decayInterval/decayToZero group fills 1s/0.01. Omitting the entire disabled time-in-mesh group fills a harmless timeInMeshQuantum: 1s. Explicit 0s is rejected for these ticker/divisor settings. These defaults prevent crashes that the pinned library's selective validator otherwise permits; they do not turn on any scoring weight.

gossipsub:
  topics: [kpl/default]
  score:
    enabled: true
    skipAtomicValidation: true
    appSpecificWeight: 1
    appSpecificScore:
      default: 2
    topics:
      kpl/default:
        skipAtomicValidation: true
        topicWeight: 1
        timeInMeshWeight: 0.01
        timeInMeshQuantum: 1s
        timeInMeshCap: 100

Under gossipsub.score.thresholds:

Under gossipsub.score.topics.<joined-topic>:

All floating-point score values must be finite, even for inactive weight terms. A missing topic score block leaves that topic unscored. With complete-group validation, supply a valid time-in-mesh quantum and invalid-delivery decay even when their weights are zero. The topology UI displays Peer scores: Disabled when scoring is off. Active score snapshots are available as peerScores through node/network/snapshot APIs and SSE; they are observations of the router, not fixed expected experiment outcomes.

Scoring remains opt-in (gossipsub.score.enabled: true). A positive scoreInspectInterval (default 1s when enabled) records weighted P1–P7 contributions; 0s disables inspection. Existing total scores remain available. P3b and the topic-cap adjustment are separate, so the decomposition can be reconciled with the total rather than hiding those effects.

Topic terms are summed across scored topics. Zero weights produce measured zeros; missing/disabled inspection produces gaps. Retained disconnected-peer scores are included, matching the router inspector. P3 may stay active after pruning, and P3b cannot be recovered reliably from a capped total. The pinned libp2p-pubsub copy has an score inspection extension exposing the actual activation flag, sticky counter and snapshot time. Router scoring/decay/routing arithmetic is unchanged, and out-of-order callbacks cannot overwrite newer measurements.

Each inspection emits one peer_score event per observing Peer with component count/mean/min/max across valid scored peers. No per-pair/topic matrix is serialized; this bounds event size rather than multiplying it by every observer/target/topic combination. Events follow existing telemetry buffering/drop reporting and local-first result storage. The node status also carries the latest scoreSample; the Controller records pair-count-weighted group statistics in observations.jsonl on its existing five-second observation cycle. Samples older than max(30s, 2 × inspection interval + 5s) are excluded. Group names identify the observer, not the scored target.

Score samples carry an inspection sequence within each Peer process, so a backwards clock-offset correction cannot make the Agent reject a newer sample or an empty snapshot. observedAt retains the corrected observation time for freshness and analysis; it is not forced forward to establish ordering. See the score API fields.

Saved Results → Metrics → GossipSub → Peer Scores adds a separate graph for each component, P3b, cap adjustment and the matching measured total. Existing overall score graphs remain. Group lines use measured pair counts, not equal weight per observer. Repetition graphs use equal run weight and the existing sample-SD shading. Graphs can be exported through the existing image controls; run ZIPs retain events and observations. These fields cannot be reconstructed for old recordings that contain only totals. Updated Controller, Agent and Peer builds are required.

A gossipsub.peerGater block installs the validation-load gate; omit the block to leave it off. It is independent of PeerScore. Defaults come from the pinned library's DefaultPeerGaterParams.

An omitted feature list uses the library's feature mapping for a known protocol ID. A custom ID with no declared features has no mesh features. Peers in the same experiment must use compatible wire protocols and message ID policies.

defaultValidators is a list of common validators; topicOptions.<topic>.validator adds that topic's validator. All supplied validators participate in validation. Each validator supports:

rpcInspector inspects incoming RPC envelopes. Optional nonnegative maxMessages, maxSubscriptions, maxControlEntries, maxMessageIds, and maxBytes reject envelopes exceeding their limits; zero is an actual zero limit. rejectPeers rejects named sender Peer IDs. Control entries count IHAVE, IWANT, GRAFT, PRUNE, and IDONTWANT protobuf entries; message-ID counts sum IHAVE/IWANT/IDONTWANT references. Byte limits use protobuf serialized RPC size.

An omitted discovery block retains KPL's capacity-aware Controller discovery loop. Explicit discovery.mode: controller (also the mode of {}) uses Controller candidates through libp2p's discovery pipeline; routing uses Kademlia and prefixes the namespace with the run ID; none disables topic discovery. Routing discovery requires Kademlia with providers and provider storage enabled. These options do not remove the separate initial bootstrap connection procedure.

discovery.ttl is a positive advertisement TTL and limit is a positive requested result limit. For Controller discovery, TTL controls renewal of the no-op advertisement callback; Controller liveness still follows Agent reports. An optional connector configures exponential connection backoff:

Without a connector block, libp2p supplies its connector defaults. Routing discovery is affected by DHT admission, storage, provider, and refresh settings.

author selects the PubSub author independently of the Peer transport identity. Fields are peerId, base64 libp2p-marshaled privateKey, or noAuthor. A supplied Peer ID must match the private key; a signed author supplied only by ID needs its key in the host peerstore. noAuthor: true conflicts with the other fields, requires an unsigned signature policy, and requires a content-based message ID on every topic. Explicit private keys are part of saved scenario inputs and downloadable archives; use experiment keys.

publish configures each application publication:

All fields below are under kademlia; they are applied when Kademlia is enabled. The library's datastore and provider interfaces are exposed through the named policies below.

Filter policies are all (empty/default), public, private, and non-loopback. Query/routing-table public/private policies use the corresponding library filters; notably, the library's private query policy accepts any nonempty address set. Use CIDR constraints for exact experiment ranges. Address filtering applies per address. A deny CIDR on any address rejects a whole query/routing-table candidate; allow lists require at least one matching IP. non-loopback requires a non-loopback global-unicast IP, including private unicast addresses.

An omitted DHT bootstrap source retains the library option default; it does not replace KPL's initial Controller bootstrap. An explicit empty static list or none supplies no DHT recovery bootstrap peers. The public-key policy is restricted to the pk namespace, and ipns to the ipns namespace. The bytes record validator accepts opaque values and selects the lexicographically greatest candidate; reject rejects all records. These policies configure protocol behavior and do not add scenario DHT Put/Get/Provide actions.

The standard /ipfs namespace, including exact protocolId: /ipfs/kad/1.0.0, keeps upstream constraints: bucket size 20, values/providers enabled, and only standard pk/ipns validators. A custom experiment prefix or exact protocol ID allows different policies. For a custom exact ID, KPL also sets an internal validation prefix so upstream default-namespace checks do not reject its tuning; the configured exact wire ID remains unchanged. Public-address filtering can exclude Swarm's private overlay addresses; choose filters that match the intended experiment network.

The schema is split across common node configuration, GossipSub parameters, PubSub policies, scoring, and Kademlia policies. Runtime adapters live in matching internal/peer files.

Scalar struct fields are covered by the typed schema. Library options that accept Go functions or interfaces use the named policies described here. Arbitrary score functions, validators, stores, discovery providers, feature tests, tracer implementations, request hooks, and Kademlia WithCustomMessageSender implementations require a code extension; YAML does not execute Go or load arbitrary implementations. KPL retains its telemetry tracers and Peer network isolation so protocol options remain observable within the experiment system.

Korean translation: 한국어.