feat: add @bsv/overlay-topics canonical package with all 19 topic/lookup pairs

Aggregates topic managers and lookup services from overlay-express-examples,
identity-services, did-services, registry-services, kvstore-services, and
ump-services into a single canonical ESM TypeScript library.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: sirdeggen

packages/overlays/topics/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@bsv/overlay-topics",
+  "version": "1.0.0",
+  "description": "Canonical BSV overlay topic managers and lookup services",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "ts-standard --fix src/**/*.ts"
+  },
+  "dependencies": {
+    "@bsv/overlay": "^2.0.2",
+    "@bsv/sdk": "^2.0.13",
+    "mongodb": "^7.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.3",
+    "ts-standard": "^12.0.0",
+    "typescript": "^5.8.3"
+  },
+  "license": "Open BSV",
+  "author": "BSV Blockchain Association",
+  "private": false
+}

packages/overlays/topics/src/any/AnyLookupService.ts

@@ -0,0 +1,91 @@
+import {
+  LookupService,
+  LookupQuestion,
+  LookupFormula,
+  AdmissionMode,
+  SpendNotificationMode,
+  OutputAdmittedByTopic,
+  OutputSpent
+} from '@bsv/overlay'
+import { AnyStorage } from './AnyStorage.js'
+import { Db } from 'mongodb'
+import { AnyQuery } from './types.js'
+
+export class AnyLookupService implements LookupService {
+  readonly admissionMode: AdmissionMode = 'locking-script'
+  readonly spendNotificationMode: SpendNotificationMode = 'txid'
+
+  constructor(public storage: AnyStorage) { }
+
+  async outputAdmittedByTopic(payload: OutputAdmittedByTopic): Promise<void> {
+    if (payload.mode !== 'locking-script') throw new Error('Invalid mode')
+    const { txid, outputIndex } = payload
+    if (payload.topic !== 'tm_anytx') return
+
+    try {
+      await this.storage.storeRecord(txid, outputIndex)
+    } catch (err) {
+      console.error(`AnyLookupService: failed to index ${txid}.${outputIndex}`, err)
+    }
+  }
+
+  async outputSpent(payload: OutputSpent): Promise<void> {
+    if (payload.mode !== 'txid') throw new Error('Invalid mode')
+    const { topic, txid, outputIndex, spendingTxid } = payload
+    if (topic !== 'tm_anytx') return
+    await this.storage.spendRecord(txid, outputIndex, spendingTxid)
+  }
+
+  async outputEvicted(txid: string, outputIndex: number): Promise<void> {
+    await this.storage.deleteRecord(txid, outputIndex)
+  }
+
+  async lookup(question: LookupQuestion): Promise<LookupFormula> {
+    if (!question) throw new Error('A valid query must be provided!')
+    if (question.service !== 'ls_anytx') throw new Error('Lookup service not supported!')
+
+    const {
+      txid,
+      limit = 50,
+      skip = 0,
+      startDate,
+      endDate,
+      sortOrder
+    } = question.query as AnyQuery
+
+    if (limit < 0) throw new Error('Limit must be a non-negative number')
+    if (skip < 0) throw new Error('Skip must be a non-negative number')
+
+    const from = startDate ? new Date(startDate) : undefined
+    const to = endDate ? new Date(endDate) : undefined
+    if (from && isNaN(from.getTime())) throw new Error('Invalid startDate provided!')
+    if (to && isNaN(to.getTime())) throw new Error('Invalid endDate provided!')
+
+    if (txid) {
+      const result = await this.storage.findByTxid(txid)
+      return [result]
+    }
+
+    return await this.storage.findAll(limit, skip, from, to, sortOrder || 'desc')
+  }
+
+  async getDocumentation(): Promise<string> {
+    return 'Any Lookup Service: lookup your outputs.'
+  }
+
+  async getMetaData(): Promise<{
+    name: string
+    shortDescription: string
+    iconURL?: string
+    version?: string
+    informationURL?: string
+  }> {
+    return {
+      name: 'Any Lookup Service',
+      shortDescription: 'Lookup your outputs.'
+    }
+  }
+}
+
+// Factory
+export default (db: Db): AnyLookupService => new AnyLookupService(new AnyStorage(db))

packages/overlays/topics/src/any/AnyStorage.ts

@@ -0,0 +1,62 @@
+import { Collection, Db } from 'mongodb'
+import { AnyRecord, UTXOReference } from './types.js'
+
+// Implements a Lookup StorageEngine for Any
+export class AnyStorage {
+  private readonly records: Collection<AnyRecord>
+
+  constructor(private readonly db: Db) {
+    this.records = db.collection<AnyRecord>('anyRecords')
+    this.createSearchableIndex()
+  }
+
+  private async createSearchableIndex(): Promise<void> {
+    await this.records.createIndex({ txid: 1 }, { name: 'txidIndex' })
+  }
+
+  async storeRecord(txid: string, outputIndex: number): Promise<void> {
+    await this.records.insertOne({
+      txid,
+      outputIndex,
+      createdAt: new Date()
+    })
+  }
+
+  async spendRecord(txid: string, outputIndex: number, spendingTxid: string): Promise<void> {
+    await this.records.updateOne({ txid, outputIndex }, { $set: { spendingTxid } })
+  }
+
+  async deleteRecord(txid: string, outputIndex: number): Promise<void> {
+    await this.records.deleteOne({ txid, outputIndex })
+  }
+
+  async findByTxid(txid: string): Promise<UTXOReference | null> {
+    if (!txid) return null
+    return this.records.findOne(
+      { txid },
+      { projection: { txid: 1, outputIndex: 1 } }
+    )
+  }
+
+  async findAll(
+    limit = 50,
+    skip = 0,
+    startDate?: Date,
+    endDate?: Date,
+    sortOrder: 'asc' | 'desc' = 'desc'
+  ): Promise<UTXOReference[]> {
+    const query: any = {}
+    if (startDate || endDate) {
+      query.createdAt = {}
+      if (startDate) query.createdAt.$gte = startDate
+      if (endDate) query.createdAt.$lte = endDate
+    }
+    const sortDirection = sortOrder === 'asc' ? 1 : -1
+    return this.records.find(query)
+      .sort({ createdAt: sortDirection })
+      .skip(skip)
+      .limit(limit)
+      .project<UTXOReference>({ txid: 1, outputIndex: 1 })
+      .toArray()
+  }
+}

packages/overlays/topics/src/any/AnyTopicManager.ts

@@ -0,0 +1,54 @@
+import { AdmittanceInstructions, TopicManager } from '@bsv/overlay'
+import { Transaction } from '@bsv/sdk'
+
+/**
+ * Topic manager for the simple "Any" messaging protocol.
+ * Each valid output must satisfy the following rules:
+ * 1. There are no rules.
+ */
+export default class AnyTopicManager implements TopicManager {
+  async identifyAdmissibleOutputs(
+    beef: number[],
+    previousCoins: number[]
+  ): Promise<AdmittanceInstructions> {
+    const outputsToAdmit: number[] = []
+
+    try {
+      console.log('Any topic manager invoked')
+      const parsedTx = Transaction.fromBEEF(beef)
+
+      if (!Array.isArray(parsedTx.outputs) || parsedTx.outputs.length === 0) {
+        throw new Error('Missing parameter: outputs')
+      }
+
+      // Admit all outputs
+      outputsToAdmit.push(...Array.from({ length: parsedTx.outputs.length }, (_, i) => i))
+    } catch (err) {
+      if (outputsToAdmit.length === 0 && (!previousCoins || previousCoins.length === 0)) {
+        console.error('Error identifying admissible outputs:', err)
+      }
+    }
+
+    return {
+      outputsToAdmit,
+      coinsToRetain: []
+    }
+  }
+
+  async getDocumentation(): Promise<string> {
+    return 'Any Topic Manager: admits all transaction outputs.'
+  }
+
+  async getMetaData(): Promise<{
+    name: string
+    shortDescription: string
+    iconURL?: string
+    version?: string
+    informationURL?: string
+  }> {
+    return {
+      name: 'Any Topic Manager',
+      shortDescription: 'Any transaction is admitted by the Any Topic Manager.'
+    }
+  }
+}

packages/overlays/topics/src/any/types.ts

@@ -0,0 +1,19 @@
+export interface UTXOReference {
+  txid: string
+  outputIndex: number
+}
+
+export interface AnyRecord {
+  txid: string
+  outputIndex: number
+  createdAt: Date
+}
+
+export interface AnyQuery {
+  txid?: string
+  limit?: number
+  skip?: number
+  startDate?: Date
+  endDate?: Date
+  sortOrder?: 'asc' | 'desc'
+}

packages/overlays/topics/src/apps/AppsLookupService.ts

@@ -0,0 +1,81 @@
+import { AppsStorageManager } from './AppsStorageManager.js'
+import { AdmissionMode, LookupFormula, LookupQuestion, LookupService, OutputAdmittedByTopic, OutputSpent, SpendNotificationMode } from '@bsv/overlay'
+import { PushDrop, Utils } from '@bsv/sdk'
+import { Db } from 'mongodb'
+import { AppCatalogQuery, PublishedAppMetadata } from './types.js'
+
+class AppsLookupService implements LookupService {
+  readonly admissionMode: AdmissionMode = 'locking-script'
+  readonly spendNotificationMode: SpendNotificationMode = 'none'
+
+  private static readonly TOPIC = 'tm_apps'
+  private static readonly SERVICE_ID = 'ls_apps'
+
+  constructor(public storageManager: AppsStorageManager) { }
+
+  async outputAdmittedByTopic(payload: OutputAdmittedByTopic): Promise<void> {
+    if (payload.mode !== 'locking-script') throw new Error('Invalid payload')
+    const { txid, outputIndex, topic, lockingScript } = payload
+    if (topic !== AppsLookupService.TOPIC) return
+
+    const decoded = PushDrop.decode(lockingScript)
+    if (decoded.fields.length !== 2) throw new Error('App token must have exactly one metadata field + signature')
+
+    const metadataJSON = Utils.toUTF8(decoded.fields[0])
+    let metadata: PublishedAppMetadata
+    try {
+      metadata = JSON.parse(metadataJSON)
+    } catch {
+      throw new Error('Metadata field is not valid JSON')
+    }
+    if (metadata == null) throw new Error('App token must contain valid metadata')
+
+    await this.storageManager.storeRecord(txid, outputIndex, metadata)
+  }
+
+  async outputSpent(payload: OutputSpent): Promise<void> {
+    if (payload.mode !== 'none') throw new Error('Invalid payload')
+    const { topic, txid, outputIndex } = payload
+    if (topic !== AppsLookupService.TOPIC) return
+    await this.storageManager.deleteRecord(txid, outputIndex)
+  }
+
+  async outputEvicted(txid: string, outputIndex: number): Promise<void> {
+    await this.storageManager.deleteRecord(txid, outputIndex)
+  }
+
+  async lookup(question: LookupQuestion): Promise<LookupFormula> {
+    if (question.query === undefined || question.query === null) throw new Error('A valid query must be provided!')
+    if (question.service !== AppsLookupService.SERVICE_ID) throw new Error('Lookup service not supported!')
+
+    const query = (question.query as AppCatalogQuery)
+
+    if (query.domain) return await this.storageManager.findByDomain(query.domain, query.limit, query.skip, query.sortOrder)
+    if (query.publisher) return await this.storageManager.findByPublisher(query.publisher, query.limit, query.skip, query.sortOrder)
+    if (query.tags?.length) return await this.storageManager.findByTags(query.tags, query.limit, query.skip, query.sortOrder)
+    if (query.category) return await this.storageManager.findByCategory(query.category, query.limit, query.skip, query.sortOrder)
+    if (query.name) return await this.storageManager.findByNameFuzzy(query.name, query.limit, query.skip, query.sortOrder)
+    if (query.outpoint) return await this.storageManager.findByOutpoint(query.outpoint)
+
+    return await this.storageManager.findAllApps(query.limit, query.skip, query.sortOrder)
+  }
+
+  async getDocumentation(): Promise<string> {
+    return 'Apps Lookup Service: find published Metanet Apps.'
+  }
+
+  async getMetaData(): Promise<{
+    name: string
+    shortDescription: string
+    iconURL?: string
+    version?: string
+    informationURL?: string
+  }> {
+    return {
+      name: 'Apps Lookup Service',
+      shortDescription: 'Find published Metanet Apps with ease.'
+    }
+  }
+}
+
+export default (db: Db): AppsLookupService => new AppsLookupService(new AppsStorageManager(db))