overlay-express

Overlay Express

BSV BLOCKCHAIN | Overlay Express

An opinionated but configurable Overlay Services deployment system:

• Uses express for HTTP on a given local port
• Easy setup with just a private key and a hosting URL
• Import and configure your topic managers the way you want
• Add lookup services, with easy factories for Mongo and Knex
• Implements a configurable web UI to show your custom overlay service docs to the world
• Uses common Knex/SQL and Mongo databases across all services for efficiency
• Supports SHIP, SLAP, and GASP sync out of the box (or it can be disabled)
• Supports Arc callbacks natively for production (or disable it for simplicity during local development)

Example Usage

Here's a quick example:

import OverlayExpress from '@bsv/overlay-express'
import dotenv from 'dotenv'
dotenv.config()

// Hi there! Let's configure Overlay Express!
const main = async () => {

    // We'll make a new server for our overlay node.
    const server = new OverlayExpress(

        // Name your overlay node with a one-word lowercase string
        `testnode`,

        // Provide the private key that gives your node its identity
        process.env.SERVER_PRIVATE_KEY!,

        // Provide the HTTPS URL where your node is available on the internet
        process.env.HOSTING_URL!
    )

    // Decide what port you want the server to listen on.
    server.configurePort(8080)

    // Connect to your SQL database with Knex
    await server.configureKnex(process.env.KNEX_URL!)

    // Also, be sure to connect to MongoDB
    await server.configureMongo(process.env.MONGO_URL!)

    // Here, you will configure the overlay topic managers and lookup services you want.
    // - Topic managers decide what outputs can go in your overlay
    // - Lookup services help people find things in your overlay
    // - Make use of functions like `configureTopicManager` and `configureLookupServiceWithMongo`
    // ADD YOUR OVERLAY SERVICES HERE

    // For simple local deployments, sync can be disabled.
    server.configureEnableGASPSync(false)

    // Lastly, configure the engine and start the server!
    await server.configureEngine()
    await server.start()
}

// Happy hacking :)
main()

Full API Docs

Check out API.md for the API docs.

Additional Features

Advanced Engine Configuration

We've introduced a new method, configureEngineParams, that allows you to pass advanced configuration options to the underlying Overlay Engine. Here's an example usage:

server.configureEngineParams({
  logTime: true,
  throwOnBroadcastFailure: true,
  overlayBroadcastFacilitator: new MyCustomFacilitator()
})

Admin-Protected Endpoints

We also now provide admin-protected endpoints for certain advanced operations like manually syncing advertisements or triggering GASP sync. These endpoints require a Bearer token. You can supply a custom token in the constructor of OverlayExpress, or retrieve the auto-generated token by calling server.getAdminToken(). You can then include this token as a Bearer token in the Authorization header of requests to the /admin/syncAdvertisements and /admin/startGASPSync endpoints.

Health Endpoints

Overlay Express now exposes three health endpoints:

• GET /health/live: liveness-only status for process-level checks.
• GET /health/ready: readiness status for critical dependencies such as the Overlay engine, Knex, and MongoDB.
• GET /health: full component report combining liveness, readiness, service metadata, and any registered custom checks.

You can attach additional application-aware checks and context:

server.configureHealth({
  contextProvider: async () => ({
    deployment: 'cars-project-backend',
    network: process.env.NETWORK
  })
})

server.registerHealthCheck({
  name: 'custom-cache',
  critical: false,
  handler: async () => ({
    status: 'ok',
    details: { warmed: true }
  })
})

The janitor service also understands the richer /health response format, so existing SHIP/SLAP health validation remains compatible.

Overlay Monitor

OverlayMonitor provides a reusable worker for monitoring Overlay Express lookup behavior. It posts configured /lookup probes to any Overlay Express deployment, measures response size, parses returned BEEF, and reports whether responsive output transactions have direct Merkle proofs or are being served with deeper proof ancestry.

This is intended to be run by deployments as a long-running monitor process or by cluster scheduling. It is not tied to a specific deployment platform.

import { OverlayMonitor } from '@bsv/overlay-express'

const monitor = new OverlayMonitor({
  intervalMs: 24 * 60 * 60 * 1000,
  targets: [
    {
      name: 'example-overlay',
      baseUrl: 'https://overlay.example',
      probes: [
        {
          name: 'example-topic',
          service: 'ls_example',
          query: { topic: 'tm_example' },
          maxOutputs: 20
        }
      ]
    }
  ],
  onReport: async report => {
    console.log(JSON.stringify(report.summary))
  }
})

monitor.start()

License

The license for the code in this repository is the Open BSV License. Refer to LICENSE.txt for the license text.

Thank you for being a part of the BSV Blockchain Overlay Express Project. Let's build the future of BSV Blockchain together!