Overlays

Overlay services are an essential piece of BSV's architecture that make it far easier to build scalable applications without needing to index the entire blockchain. Below is a short conceptual guide covering what they are, when you might use them, and why they’re so helpful.

What Are Overlay Services?

Overlay services are specialized application-focused layers that run “on top” of the base BSV network. Each overlay service tracks only the specific transactions or data that are relevant to its own focus (its “topic”), storing and making that data queryable via a standard API.

• Topic Managers: The code that decides which new transactions get admitted into the overlay’s state and which known records get removed or updated. Essentially, this logic filters out everything that’s irrelevant to your app.
• Lookup Services: The code that provides a query endpoint for the data the topic manager has collected. Instead of you scanning the entire blockchain, you simply ask the overlay’s “lookup” API for exactly what you need.

By combining these two parts, an overlay service appears to your app as though it’s a normal database, but under the hood it remains grounded in the BSV blockchain. All admitted data is backed by Simplified Payment Verification (SPV) to ensure it’s genuinely confirmed on-chain.

When Do You Use Overlay Services?

Overlay services come into play any time you want to build an application that needs shared or global state, or that must track particular outputs on the BSV blockchain without scanning it all:

1. You need to manage on-chain data for many users If your app deals with tokens, counters, auctions, user entries, or any multi-user state, you can have an overlay track that data so all your users see the same, consistent global view.

2. You require queries beyond a single user’s scope A user’s own wallet can track data that belongs specifically to them, but for a cross-user application (e.g., leaderboards, a market of items, or game states), you need a broader vantage point. An overlay’s lookup service can answer global queries so every participant sees “the big picture.”

3. You want strong SPV-backed assurance Because overlay services rely on real blockchain confirmations and SPV proofs, they provide a verifiable record of transactions, bridging your app logic with unforgeable on-chain data integrity.

4. You’d prefer not to ingest the entire blockchain Instead of running a full node or building a custom indexer, overlays let you track precisely the outputs and transactions you care about. This drastically reduces overhead, which matters for large-scale or specialized applications.

Why Are They Helpful?

1. Scalability Rather than one node doing all the heavy lifting of scanning the entire blockchain for every possible use case, the workload is split across many overlay services—each focusing on its own topic. This approach scales as BSV’s transaction volume grows.

2. Rapid Development An overlay service acts like a typical backend microservice. Your front end can talk to it via familiar REST or HTTP-based calls:

   • /submit to send transactions related to your topic.
   • /lookup to retrieve or filter the data your app needs. Meanwhile, the service automatically filters away everything irrelevant, so you don’t have to build a custom index or handle raw blockchain parsing.

3. Custom Logic and Data You can implement precisely the topic logic your application needs. For example, if you have a “MeterCounter” app that increments numbers on-chain, you define a topic manager that admits only those “counter” transactions. This custom vantage point makes development far more streamlined—your overlay is effectively a “custom node,” but only for your corner of the data.

4. Distributed Ownership & Public or Private Multiple overlays can exist to serve different user groups, or to provide redundancy if one goes down. You could keep your overlay private—only you see your data—or opt to run a public overlay that anyone can query. A business might maintain a private overlay for internal data and provide a partial read-only public lookup if that suits their model.

5. SPV Security Overlays rely on the base BSV blockchain for proofs of validity. They do not need to become “trusted authorities.” Clients can trust the overlay is only storing transactions that actually made it onto the blockchain.

In a Nutshell

• Overlay services are your custom blockchain indexers and query engines, but without the pain of rolling an entire node or scanning everything.
• You code a Topic Manager (which UTXOs do I care about?) and a Lookup Service (how do I let others query them?).
• Tools like Overlay Express, LARS, and CARS help automate everything from local dev to cloud deployment.
• The result is a powerful, easy-to-access, and SPV-backed data service for your BSV-based application.

By using overlay services, you can build a scalable backend for Bitcoin-powered apps, focusing on the exact on-chain data you want, while letting the broader BSV blockchain function as the universal “public ledger” that underpins it all.