modules/network-discovery/hyper-p2p-topic-announcer

hyper-p2p-topic-announcer

Announce and revoke logical topics (with metadata) on a gossip mesh; track remote announcements.

Category: network-discovery · Protocol: topic-announcer/v1 · Exports: HyperP2PTopicAnnouncer, PROTOCOL

When to use

Peers advertise interest in named topicIds (channels, feeds) without joining each topic’s swarm yet.

When not to use

When topic membership is implicit from DHT only.

Quick start

const { HyperP2PTopicAnnouncer } = require('hyper-p2p-topic-announcer')
const ann = new HyperP2PTopicAnnouncer({ topic: 'discover' })
await ann.ready()
ann.announce('channel-1', { priority: 1 })
console.log(ann.list())
await ann.close()

Docs

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

Test

npm test

API

Member	Description
new HyperP2PTopicAnnouncer(opts?)	topic (swarm), keyPair; peerHex.
announce(topicId, meta?)	Set local + gossip announce.
revoke(topicId)	Delete if held; gossip revoke. Returns boolean.
list() / get(topicId)	All entries / one.
getStats()	{ announced, revoked, gossipIn, gossipOut, topics, protocol }.
ready() / close()	Swarm lifecycle.

Events: announce, revoke, remote-announce, remote-revoke, closed.

Architecture

_topics Map(topicId -> { topicId, meta, peer, at })
announce: LWW by at; revoke: delete if cur.peer matches revoker peer (or no cur)

Revoke only removes when the revoking peer matches the announcer (or entry absent).

Wire table

type	Fields	Direction
announce	topicId, meta, peer, at	Any → all
revoke	topicId, peer, at	Any → all

Errors

• Empty topicId on announce, revoke, get.
• revoke returns false when topic was not locally announced.

Composition

• topicId is logical; constructor topic is the Hyperswarm discovery topic.
• Downstream: join per-topic swarms using announced ids + hyper-p2p-seeder-registry.
• Listen to remote-announce to build subscription UI or routing tables.

Example

const { HyperP2PTopicAnnouncer } = require('hyper-p2p-topic-announcer')

const ann = new HyperP2PTopicAnnouncer({ topic: process.argv[2] })
ann.on('remote-announce', (e) => console.log('seen', e.topicId))

await ann.ready()
ann.announce('channel-1', { priority: 1 })
console.log(ann.list())
ann.revoke('channel-1')
await ann.close()