Overlay Module

The overlay module wraps BSV SDK's TopicBroadcaster and LookupResolver into a clean API for broadcasting transactions to topic-specific services and querying lookup services.

Source: src/modules/overlay.ts

Overlay Class

Overlay.create()

static async create(config: OverlayConfig): Promise<Overlay>

Create a new overlay instance.

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

Throws: Error if no topics provided or any topic doesn't start with tm_.

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

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

overlay.getInfo()

getInfo(): OverlayInfo

Returns:

{
  topics: string[]  // Current topic list
  network: string   // Network name
}

overlay.addTopic()

addTopic(topic: string): void

Add a topic to the overlay. Rebuilds the internal broadcaster.

Throws: Error if topic doesn't start with tm_.

overlay.removeTopic()

removeTopic(topic: string): void

Remove a topic from the overlay. Rebuilds the internal broadcaster if topics remain.

overlay.broadcast()

async broadcast(tx: Transaction, topics?: string[]): Promise<OverlayBroadcastResult>

Submit a pre-built transaction to overlay topics.

Parameter	Type	Required	Description
tx	Transaction	Yes	BSV SDK Transaction object
topics	string[]	No	Override topics for this broadcast (must start with tm_)

Returns:

{
  success: boolean
  txid?: string         // Present if successful
  code?: string         // Error code if failed
  description?: string  // Error description if failed
}

overlay.query()

async query(service: string, query: unknown, timeout?: number): Promise<LookupAnswer>

Query a lookup service.

Parameter	Type	Required	Description
service	string	Yes	Lookup service name (should start with ls_)
query	unknown	Yes	Query parameters
timeout	number	No	Timeout in milliseconds

Returns: LookupAnswer from the BSV SDK.

overlay.lookupOutputs()

async lookupOutputs(service: string, query: unknown): Promise<OverlayOutput[]>

Query a lookup service and extract parsed outputs.

Parameter	Type	Description
service	string	Lookup service name
query	unknown	Query parameters

Returns:

{
  beef: number[]        // BEEF data
  outputIndex: number   // Output index
  context?: number[]    // Optional context data
}[]

Returns an empty array if the answer type is not 'output-list'.

overlay.getBroadcaster()

getBroadcaster(): TopicBroadcaster

Access the raw BSV SDK TopicBroadcaster for advanced use.

overlay.getResolver()

getResolver(): LookupResolver

Access the raw BSV SDK LookupResolver for advanced use.

Wallet Methods

advertiseSHIP()

async advertiseSHIP(
  domain: string,
  topic: string,
  basket?: string
): Promise<TransactionResult>

Create a SHIP advertisement: "I host topic X at domain Y".

Parameter	Type	Required	Description
domain	string	Yes	Hosting domain URL
topic	string	Yes	Topic name (must start with tm_)
basket	string	No	Store the SHIP token in a basket

Throws: Error if topic doesn't start with tm_.

Uses OverlayAdminTokenTemplate from @bsv/sdk to create the locking script.

advertiseSLAP()

async advertiseSLAP(
  domain: string,
  service: string,
  basket?: string
): Promise<TransactionResult>

Create a SLAP advertisement: "I provide lookup service X at domain Y".

Parameter	Type	Required	Description
domain	string	Yes	Service domain URL
service	string	Yes	Service name (must start with ls_)
basket	string	No	Store the SLAP token in a basket

Throws: Error if service doesn't start with ls_.

broadcastAction()

async broadcastAction(
  overlay: Overlay,
  actionOptions: { outputs: any[]; description?: string },
  topics?: string[]
): Promise<{ txid: string; broadcast: OverlayBroadcastResult }>

Create a transaction and broadcast to overlay in one step.

Parameter	Type	Required	Description
overlay	Overlay	Yes	Overlay instance
actionOptions.outputs	any[]	Yes	Output specifications for createAction()
actionOptions.description	string	No	Transaction description
topics	string[]	No	Override topics for broadcast

What happens:

1. Calls createAction() with the outputs

2. Parses the result as Transaction.fromAtomicBEEF()

3. Broadcasts via overlay.broadcast()

Throws: Error if result.tx is missing from createAction().

withRetry()

async withRetry<T>(
  operation: () => Promise<T>,
  overlay: Overlay,
  maxRetries?: number
): Promise<T>

Wrap an operation with automatic retry on double-spend errors.

Parameter	Type	Default	Description
operation	() => Promise<T>	required	The operation to retry
overlay	Overlay	required	Overlay instance (provides the broadcaster)
maxRetries	number	SDK default	Maximum retry attempts

Uses withDoubleSpendRetry() from @bsv/sdk under the hood.