@bsv/overlay-discovery-services

Discovery layer for the BSV overlay network. Implements SHIP (Service Host Interconnect Protocol) and SLAP (Service Lookup Availability Protocol) — the two protocols that let overlay nodes advertise the topics they host and the lookup services they expose, so peers can find each other without a central registry.

This package ships:

• SHIPTopicManager / SHIPLookupService — admission and querying for SHIP advertisement tokens
• SLAPTopicManager / SLAPLookupService — admission and querying for SLAP advertisement tokens
• WalletAdvertiser — a turnkey Advertiser implementation that creates, finds, and revokes SHIP/SLAP advertisements using a BRC-100 wallet

Install

npm install @bsv/overlay-discovery-services

Peer dependencies: @bsv/sdk, @bsv/overlay, @bsv/wallet-toolbox-client.

Quick start (advertiser)

import { WalletAdvertiser } from '@bsv/overlay-discovery-services'

const advertiser = new WalletAdvertiser(
  'main',                                // chain
  privateKeyHex,                         // signing key
  'https://my-storage.example.com',      // wallet storage URL
  'https://my-overlay.example.com'       // advertisable URI clients should connect to
)
await advertiser.init()

// Advertise that we host the tm_did topic and ls_did lookup service.
await advertiser.createAdvertisements([
  { protocol: 'SHIP', topicOrServiceName: 'tm_did' },
  { protocol: 'SLAP', topicOrServiceName: 'ls_did' },
])

// Discover everyone else hosting tm_did.
const peers = await advertiser.findAllAdvertisements('SHIP')

Quick start (overlay operator)

Mount the SHIP/SLAP topic managers and lookup services on your overlay node so peers can publish and discover advertisements through your endpoint:

import {
  SHIPTopicManager,
  SLAPTopicManager,
  SHIPLookupServiceFactory,
  SLAPLookupServiceFactory,
} from '@bsv/overlay-discovery-services'

engine.registerTopicManager('tm_ship', new SHIPTopicManager())
engine.registerTopicManager('tm_slap', new SLAPTopicManager())
engine.registerLookupService('ls_ship', SHIPLookupServiceFactory(db))
engine.registerLookupService('ls_slap', SLAPLookupServiceFactory(db))

Use cases

Run a discoverable overlay service

Host a topic (e.g. tm_did) and publish a SHIP advertisement so other nodes route relevant transactions to you.

Find peers for a given topic

const hosts = await advertiser.findAllAdvertisements('SHIP')
const didHosts = hosts.filter(a => a.topicOrServiceName === 'tm_did')

Take a service offline

const mine = await advertiser.findAllAdvertisements('SLAP')
await advertiser.revokeAdvertisements(mine.filter(a => a.topicOrServiceName === 'ls_did'))

API

| Export | Purpose | |--------|---------| | SHIPTopicManager | Admits well-formed SHIP advertisement outputs to the tm_ship topic | | SLAPTopicManager | Admits well-formed SLAP advertisement outputs to the tm_slap topic | | SHIPLookupServiceFactory / SLAPLookupServiceFactory | Build the matching lookup services | | WalletAdvertiser | High-level advertise/find/revoke API backed by a wallet | | isAdvertisableURI / isValidTopicOrServiceName | Validation helpers |

License

Open BSV License — see LICENSE.txt.