@bsv/overlay 2.0.2 → 2.0.3

package/docs/examples/README.md

@@ -4,11 +4,11 @@
 
 ---
 
-Here, you will find documentation for common example usages of the Overlay Services Engine.
+Here, you will find documentation for common example usages of the Overlay Services Engine. These examples focus on direct `@bsv/overlay` integration. For a ready-to-run HTTP overlay node, use [`@bsv/overlay-express`](https://github.com/bsv-blockchain/overlay-express) and [`overlay-express-examples`](https://github.com/bsv-blockchain/overlay-express-examples).
 
 ## Available Examples
 
-- [Getting Started (WIP)](./gs-wip.md) — Introduction and getting started guide
+- [Getting Started](./gs-wip.md) — Introduction and low-level engine setup guide
 
 ---
 

package/docs/examples/gs-wip.md

@@ -6,106 +6,114 @@
 
 ## Introduction to BSV Overlay Services Engine
 
-The BSV Overlay Services Engine is designed to process transactions and manage data within a blockchain-based system, specifically targeting the Bitcoin SV (BSV) blockchain. It integrates various components such as Topic Managers, Lookup Services, Storage, and Chain Tracker to provide a robust environment for managing transaction data and overlay services.
+The BSV Overlay Services Engine is the low-level runtime for topic managers and lookup services. It validates candidate outputs, stores admitted UTXOs, tracks spends, answers lookup questions, and coordinates synchronization between overlay nodes.
+
+If you want to run an HTTP overlay node, start with [`@bsv/overlay-express`](https://github.com/bsv-blockchain/overlay-express). If you want a local or cloud application runtime, use LARS or CARS with the BRC-102 `deployment-info.json` structure. Use `@bsv/overlay` directly when you are building custom infrastructure around the engine.
 
 ### Components of the System
 
-1. **Topic Managers**: Responsible for managing the admittance of transactions related to specific topics.
-2. **Lookup Services**: Handle the lookup of UTXO (Unspent Transaction Output) data for transactions.
-3. **Storage**: Manages persistent data storage, tracking UTXOs and their states within the system.
-4. **Chain Tracker**: Verifies SPV (Simplified Payment Verification) data associated with transactions to ensure their validity.
+1. **Topic Managers** decide which transaction outputs are admitted for a topic.
+2. **Lookup Services** index admitted and spent outputs and answer domain-specific lookup questions.
+3. **Storage** persists admitted outputs, spend state, history, sync state, and interaction timestamps.
+4. **Chain Tracker** verifies SPV data for transactions unless the engine is configured for script-only validation.
+5. **Broadcaster** submits accepted transactions to the network.
+6. **Advertiser** publishes SHIP and SLAP availability records when peer discovery is enabled.
 
 ### Setting Up the Engine
 
-Before you can use the engine, you must initialize it with the required components:
-
-```ts
-import { Engine, KnexStorage } from "@bsv/overlay";
-import { HelloTopicManager, HelloLookupService } from 'hello-services';
-import { WoChain } from "@bsv/sdk";
-
-// Initialize components
-const managers = {
-    "exampleTopic": new HelloTopicManager()
-};
+Install the current packages:
 
-const lookupServices = {
-    "exampleLookup": new HelloLookupService()
-};
+```bash
+npm i @bsv/overlay @bsv/sdk knex
+```
 
-const storage = new KnexStorage();
-const chainTracker = new WoChain();
+Create the engine with your concrete implementations:
 
-// Create the engine instance
-const engine = new Engine(managers, lookupServices, storage, chainTracker);
+```ts
+import { Engine, KnexStorage } from '@bsv/overlay'
+import { WhatsOnChain, NodejsHttpClient, ARC } from '@bsv/sdk'
+import knexFactory from 'knex'
+
+import { ExampleLookupService } from './services/ExampleLookupService.js'
+import { ExampleTopicManager } from './services/ExampleTopicManager.js'
+
+const knex = knexFactory({
+  client: 'mysql2',
+  connection: process.env.KNEX_URL
+})
+
+const engine = new Engine(
+  {
+    tm_example: new ExampleTopicManager()
+  },
+  {
+    ls_example: new ExampleLookupService()
+  },
+  new KnexStorage(knex),
+  new WhatsOnChain('test', { httpClient: new NodejsHttpClient() }),
+  process.env.HOSTING_URL,
+  process.env.SHIP_TRACKERS?.split(',') ?? [],
+  process.env.SLAP_TRACKERS?.split(',') ?? [],
+  new ARC(process.env.ARC_URL ?? 'https://arc.taal.com', {
+    apiKey: process.env.ARC_API_KEY
+  }),
+  undefined,
+  {
+    tm_example: 'SHIP'
+  }
+)
 ```
 
+Use the string `'scripts only'` for the chain tracker only when the service intentionally skips SPV validation and relies only on script-level checks.
+
 ### Submitting a Transaction
 
-To submit a transaction for processing by the Overlay Services:
+Submit tagged BEEF bytes with the topics that should evaluate the transaction:
 
 ```ts
 import { Transaction } from '@bsv/sdk'
 
-const tx = new Transaction(/* ... */);
+const tx = new Transaction(/* ... */)
 
-const transaction = {
-    beef: tx.toBEEF(),
-    topics: ['exampleTopic']
-}
+const steak = await engine.submit({
+  beef: tx.toBEEF(),
+  topics: ['tm_example']
+})
 
-// Submit transaction
-engine.submit(transaction).then(steak => {
-    console.log("Transaction processed:", steak);
-}).catch(error => {
-    console.error("Error processing transaction:", error);
-});
+console.log('Transaction processed:', steak)
 ```
 
 ### Lookup Queries
 
-To perform a lookup query using the engine:
+Ask a lookup service a domain-specific question:
 
 ```ts
-const question = {
-    service: 'exampleLookup',
-    query: {
-        name: 'Bob'
-    }
-}
-
-// Perform a lookup
-engine.lookup(question).then(answer => {
-    console.log("Lookup result:", answer);
-}).catch(error => {
-    console.error("Error performing lookup:", error);
-});
+const answer = await engine.lookup({
+  service: 'ls_example',
+  query: {
+    identityKey: '03...'
+  }
+})
+
+console.log('Lookup result:', answer)
 ```
 
-### Managing UTXOs
+### Service Documentation
 
-The system's core functionality involves managing UTXOs:
+Overlay clients and dashboards can retrieve service documentation and metadata directly from the engine:
 
-1. **Inserting a New UTXO**: Store new UTXO data when transactions are processed.
-2. **Deleting a UTXO**: Remove UTXOs that are no longer needed or have been consumed by newer transactions.
-3. **Tracking UTXO Consumption**: Monitor which transactions consume which UTXOs.
+```ts
+const topicDocs = await engine.getDocumentationForTopicManger('tm_example')
+const lookupDocs = await engine.getDocumentationForLookupServiceProvider('ls_example')
 
-### Retrieving Documentation
+const topics = await engine.listTopicManagers()
+const lookupServices = await engine.listLookupServiceProviders()
+```
 
-To retrieve documentation for specific managers or services:
+### Deployment Path
 
-```ts
-// For a topic manager
-engine.getDocumentationForTopicManger("exampleTopic").then(doc => {
-    console.log("Documentation for Topic Manager:", doc);
-});
-
-// For a lookup service
-engine.getDocumentationForLookupServiceProvider("exampleLookup").then(doc => {
-    console.log("Documentation for Lookup Service:", doc);
-});
-```
+For a public overlay node, wire the engine into HTTP routes using `@bsv/overlay-express` instead of hand-rolling routes. Overlay Express already exposes the standard submit, lookup, sync, health, documentation, and admin surfaces expected by the rest of the BSV overlay ecosystem.
 
 ### Conclusion
 
-The BSV Overlay Services Engine provides a powerful toolset for managing transactions and data on the Bitcoin SV blockchain. It's designed to handle complex data structures and ensure the integrity and security of transactions through rigorous validation and management processes. By following this tutorial, developers can effectively integrate and utilize these capabilities within their blockchain applications.
+The BSV Overlay Services Engine is the shared core for overlay validation, indexing, lookup, and synchronization. Keep direct engine usage focused on infrastructure-level integrations, and use Overlay Express, LARS, and CARS for the standard application path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/overlay",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "type": "module",
   "description": "BSV Blockchain Overlay Services Engine",
   "main": "dist/cjs/mod.js",
@@ -74,7 +74,7 @@
   },
   "dependencies": {
     "@bsv/gasp": "^1.2.2",
-    "@bsv/sdk": "^2.0.4",
+    "@bsv/sdk": "^2.0.14",
     "knex": "^3.1.0"
   }
 }