modules/network-discovery/hyper-p2p-capability-discovery

hyper-p2p-capability-discovery

Gossip capability names and metadata so peers can find who offers a given service on a shared Hyperswarm topic.

Category: network-discovery · Protocol: capability-discovery/v1 · Exports: HyperP2PCapabilityDiscovery, PROTOCOL

When to use

Capability-based peer selection (relay, storage, compute tags) on one swarm topic.

When not to use

Fixed peer lists or discovery without gossip.

Quick start

const { HyperP2PCapabilityDiscovery } = require('hyper-p2p-capability-discovery')
const cap = new HyperP2PCapabilityDiscovery({ topic: 'discover' })
await cap.ready()
cap.registerCapability('storage', { region: 'eu' })
console.log(cap.findByCapability('storage'))
await cap.close()

Docs

• docs/api.md · docs/architecture.md

Test

npm install && npm test

API

Member	Description
new HyperP2PCapabilityDiscovery(opts?)	topic, keyPair (default random). Sets peerHex from public key.
registerCapability(name, meta?)	Local register + gossip. Returns { name, meta, peer, at }.
findByCapability(name)	All entries for name (local + remote).
listCapabilities()	Distinct capability names.
getStats()	{ registered, gossipIn, gossipOut, capabilities, peers, protocol }.
ready() / close()	Join swarm when topic set; clear maps and destroy swarm.

Events: register, remote-register, closed. Gossip only after ready() with topic.

Architecture

Peer A --cap-register--> swarm peers --merge by (name, peer)--> in-memory Map<name, Map<peerHex, entry>>

State is _byName: capability → peer hex → entry. Remote updates apply last-write-wins on at. Local registerCapability always wins for this peer’s hex bucket. Works without topic (local-only; no gossip).

Wire table

type	Fields	Direction
cap-register	name, meta, peer, at	Any peer → all

Errors

• Empty name on registerCapability / findByCapability (assertNonEmpty).
• Without topic, ready() is a no-op for swarm; gossip requires joined peers.

Composition

• Hyperswarm topic is the discovery plane; capability name is the app-level index.
• Pair with hyper-p2p-seeder-registry when capabilities imply content topics.
• Local-only mode: omit topic and use registerCapability / findByCapability in-process.

Example

const { HyperP2PCapabilityDiscovery } = require('hyper-p2p-capability-discovery')

const disc = new HyperP2PCapabilityDiscovery({ topic: process.argv[2] })
disc.on('remote-register', (e) => console.log('remote', e.name, e.peer))

await disc.ready()
disc.registerCapability('relay', { version: 1 })
console.log(disc.findByCapability('relay'))
console.log(disc.getStats())
await disc.close()

Test

npm install && npm test