Overlay Networks

Overlay networks let you broadcast transactions to topic-specific services and query lookup services for data. @bsv/simple wraps the BSV SDK's TopicBroadcaster and LookupResolver into a clean API.

Core Concepts

Concept	Prefix	Description
Topic	tm_	A category of transactions (e.g., tm_payments, tm_tokens)
Lookup Service	ls_	A query endpoint for finding data (e.g., ls_payments)
SHIP	—	Protocol for advertising topic hosting
SLAP	—	Protocol for advertising lookup services

Important: Topics must start with tm_ and lookup services must start with ls_. The library enforces these prefixes and throws if they're missing.

Creating an Overlay

import { Overlay } from '@bsv/simple/browser'

const overlay = await Overlay.create({
  topics: ['tm_payments', 'tm_tokens'],
  network: 'mainnet'
})

Configuration

Parameter	Type	Default	Description
topics	string[]	required	Topics to broadcast to (must start with tm_)
network	string	'mainnet'	'mainnet', 'testnet', or 'local'
slapTrackers	string[]	SDK default	Custom SLAP tracker URLs
hostOverrides	Record<string, string[]>	—	Override hosts for specific topics
additionalHosts	Record<string, string[]>	—	Add extra hosts for specific topics

Managing Topics

// Get current info
const info = overlay.getInfo()
// { topics: ['tm_payments', 'tm_tokens'], network: 'mainnet' }

// Add a topic
overlay.addTopic('tm_invoices')

// Remove a topic
overlay.removeTopic('tm_tokens')

Broadcasting

Submit a pre-built transaction to overlay topics:

import { Transaction } from '@bsv/sdk'

const tx = Transaction.fromAtomicBEEF(txBytes)
const result = await overlay.broadcast(tx)

if (result.success) {
  console.log('Broadcast TXID:', result.txid)
} else {
  console.log('Failed:', result.code, result.description)
}

Broadcast to Specific Topics

// Override the default topics for this broadcast
const result = await overlay.broadcast(tx, ['tm_payments'])

Querying

Raw Query

const answer = await overlay.query('ls_payments', { tag: 'recent' })
console.log('Answer type:', answer.type)

Get Parsed Outputs

const outputs = await overlay.lookupOutputs('ls_payments', { tag: 'recent' })

for (const output of outputs) {
  console.log('BEEF:', output.beef.length, 'bytes')
  console.log('Output Index:', output.outputIndex)
}

Wallet-Integrated Methods

Advertise SHIP (Topic Hosting)

Tell the network that you host a specific topic at a domain:

await wallet.advertiseSHIP(
  'https://myserver.com',
  'tm_payments',
  'ship-tokens'     // optional: basket to store the token
)

Advertise SLAP (Lookup Service)

Tell the network that you provide a lookup service at a domain:

await wallet.advertiseSLAP(
  'https://myserver.com',
  'ls_payments',
  'slap-tokens'     // optional: basket
)

Broadcast Action

Create a transaction and broadcast to overlay in one step:

const { txid, broadcast } = await wallet.broadcastAction(
  overlay,
  {
    outputs: [{
      lockingScript: scriptHex,
      satoshis: 1,
      outputDescription: 'Overlay output'
    }],
    description: 'Overlay broadcast'
  },
  ['tm_payments']   // optional: specific topics
)

console.log('TXID:', txid)
console.log('Broadcast success:', broadcast.success)

Double-Spend Retry

Wrap an operation with automatic retry on double-spend:

const result = await wallet.withRetry(async () => {
  return await wallet.broadcastAction(overlay, { outputs: [...] })
}, overlay, 3)  // max 3 retries

Advanced: Raw SDK Access

For operations not covered by the simple API:

const broadcaster = overlay.getBroadcaster()  // TopicBroadcaster
const resolver = overlay.getResolver()        // LookupResolver

Complete Example

import { createWallet, Overlay } from '@bsv/simple/browser'

const wallet = await createWallet()

// Create overlay
const overlay = await Overlay.create({
  topics: ['tm_my_app'],
  network: 'mainnet'
})

// Advertise our services
await wallet.advertiseSHIP('https://myapp.com', 'tm_my_app')
await wallet.advertiseSLAP('https://myapp.com', 'ls_my_app')

// Broadcast a transaction
const { txid, broadcast } = await wallet.broadcastAction(
  overlay,
  {
    outputs: [{ lockingScript: '...', satoshis: 1, outputDescription: 'Data' }],
    description: 'Store data in overlay'
  }
)

// Query data
const outputs = await overlay.lookupOutputs('ls_my_app', { type: 'recent' })
console.log('Found', outputs.length, 'outputs')