@bsv/overlay

The core engine and storage contracts for BSV Overlay Services. The engine admits transactions through topic managers, maintains UTXO state, serves lookup services, and supports SHIP, SLAP, GASP, and BASM synchronization.

Use @bsv/overlay-express when you want the standard HTTP server, operational endpoints, edge policy, and health checks. Use this package directly when you are embedding the engine in another runtime or implementing a custom transport.

Requirements

• Node.js 22 or newer
• @bsv/sdk installed as a peer dependency
• A Storage implementation
• A ChainTracker, or the explicit 'scripts only' validation mode

Install

npm install @bsv/overlay @bsv/sdk

Create an engine

import { Engine, KnexStorage } from '@bsv/overlay'
import type { LookupService, TopicManager } from '@bsv/overlay'
import knex from 'knex'

const database = knex({
  client: 'pg',
  connection: process.env.DATABASE_URL
})

const topicManagers: Record<string, TopicManager> = {
  tm_example: exampleTopicManager
}

const lookupServices: Record<string, LookupService> = {
  ls_example: exampleLookupService
}

const engine = new Engine(
  topicManagers,
  lookupServices,
  new KnexStorage(database),
  chainTracker,
  'https://overlay.example'
)

await engine.submit({
  beef: transaction.toBEEF(),
  topics: ['tm_example']
})

const answer = await engine.lookup({
  service: 'ls_example',
  query: { txid }
})

The constructor also accepts SHIP/SLAP trackers, broadcasters, an advertiser, sync configuration, a logger, a topic-anchor header resolver, and BASM/unproven state controls. Type declarations document the complete configuration surface.

Public API

The root entry point exports:

• Engine
• KnexStorage and KnexStorageMigrations
• the topic-manager, lookup-service, storage, advertisement, and sync contracts
• BASM utilities and types
• safe structured-log serializers

@bsv/overlay/storage exports the Storage contract. Existing supported deep imports remain available through the documented package export map, but new applications should prefer the root entry point wherever possible.

Runtime and package formats

The package supports both module systems:

import { Engine } from '@bsv/overlay'

const { Engine } = require('@bsv/overlay')

ES modules load from dist/esm; CommonJS loads from dist/cjs. Each condition has matching declarations. Published artifacts contain compiled output, the README, and the license only—tests, compiler caches, workspace source, and lock files are excluded.

Security and operations

The engine is transport-neutral. Authentication, CORS, CSP, body limits, timeouts, rate or concurrency controls, and administrative authorization belong at the HTTP or application boundary.

Overlay endpoints are commonly public protocol services used by browsers, mobile wallets, WUI, and applications on previously unknown origins. A wrapper should therefore remain public-by-default unless an operator deliberately configures an exact-origin allowlist. CORS is not an authentication mechanism, and CSP for a hosted UI should be configured independently.

For production deployments:

• validate all untrusted request data before invoking the engine;
• use a durable storage implementation and tested database migrations;
• configure transaction broadcast and proof providers;
• protect administrative and callback routes with explicit credentials;
• avoid logging raw secrets, authorization headers, or unbounded payloads;
• monitor readiness, proof acquisition, synchronization, and unproven state.

@bsv/overlay-express supplies these standard HTTP controls while preserving public protocol access by default.

Development

From the repository root:

pnpm --filter @bsv/overlay format:check
pnpm --filter @bsv/overlay lint
pnpm --filter @bsv/overlay typecheck
pnpm --filter @bsv/overlay test
pnpm --filter @bsv/overlay test:coverage
pnpm --filter @bsv/overlay pack:check

pack:check verifies the actual npm tarball with publint, strict type resolution, and clean ESM/CommonJS consumer projects.

License

Current TS Stack changes are licensed under the Open BSV License Version 6; see LICENSE.txt. This package also retains pre-uniformization code under the Open BSV License Version 4. Redistributors must preserve THIRD_PARTY_NOTICES.md and the applicable text in LICENSES/.