@bsv/overlay 2.2.1 → 2.3.0

package/docs/examples/gs-wip.md

@@ -1,111 +0,0 @@
-# Getting Started with BSV Overlay Services Engine
-
-[🏠 Home](../README.md) | [📚 API](../API.md) | [💡 Concepts](../concepts/README.md) | [📖 Examples](./README.md) | [⚙️ Internal](../internal/README.md)
-
----
-
-## 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.
-
-### 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.
-
-### 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()
-};
-
-const lookupServices = {
-    "exampleLookup": new HelloLookupService()
-};
-
-const storage = new KnexStorage();
-const chainTracker = new WoChain();
-
-// Create the engine instance
-const engine = new Engine(managers, lookupServices, storage, chainTracker);
-```
-
-### Submitting a Transaction
-
-To submit a transaction for processing by the Overlay Services:
-
-```ts
-import { Transaction } from '@bsv/sdk'
-
-const tx = new Transaction(/* ... */);
-
-const transaction = {
-    beef: tx.toBEEF(),
-    topics: ['exampleTopic']
-}
-
-// Submit transaction
-engine.submit(transaction).then(steak => {
-    console.log("Transaction processed:", steak);
-}).catch(error => {
-    console.error("Error processing transaction:", error);
-});
-```
-
-### Lookup Queries
-
-To perform a lookup query using the engine:
-
-```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);
-});
-```
-
-### Managing UTXOs
-
-The system's core functionality involves managing UTXOs:
-
-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.
-
-### Retrieving Documentation
-
-To retrieve documentation for specific managers or services:
-
-```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);
-});
-```
-
-### 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.

package/docs/internal/README.md

@@ -1,11 +0,0 @@
-# Internals
-
-[🏠 Home](../README.md) | [📚 API](../API.md) | [💡 Concepts](../concepts/README.md) | [📖 Examples](../examples/README.md) | [⚙️ Internal](./README.md)
-
----
-
-These documents cover the internal components of the Overlay Services engine. Generally, these are only useful for creating customized deployments.
-
----
-
-[🏠 Home](../README.md) | [📚 API](../API.md) | [💡 Concepts](../concepts/README.md) | [📖 Examples](../examples/README.md) | [⚙️ Internal](./README.md)

package/mod.ts

@@ -1,40 +0,0 @@
-// Fundamentals
-export { Engine } from "./src/Engine.js"
-export type * from "./src/LookupService.js"
-export type { TopicManager } from "./src/TopicManager.js"
-
-// Interfaces and structures
-export type { Storage, AppliedTransaction } from "./src/storage/Storage.js"
-export type { Output } from './src/Output.js'
-export type { TaggedBEEF, STEAK, LookupQuestion, LookupAnswer, AdmittanceInstructions } from '@bsv/sdk'
-export type { LookupFormula } from './src/LookupFormula.js'
-export type { Advertisement } from './src/Advertisement.js'
-export type { AdvertisementData, Advertiser } from './src/Advertiser.js'
-export {
-  BASM_ZERO_HASH,
-  computeBasmRoot,
-  computeTac,
-  extractMerkleProofMetadata
-} from './src/BASM.js'
-export type {
-  AdmittedListRequest,
-  AdmittedListResponse,
-  AdmittedTxRef,
-  BASMPeerSyncReport,
-  CompoundMerklePathRequest,
-  CompoundMerklePathResponse,
-  MerkleProofMetadata,
-  RawTransactionRecord,
-  RawTransactionRequest,
-  RawTransactionResponse,
-  TopicAnchorHeader,
-  TopicAnchorHeaderResolver,
-  TopicAnchorRangeRequest,
-  TopicAnchorRangeResponse,
-  TopicAnchorTip,
-  TopicBlockAnchor
-} from './src/BASM.js'
-
-// The Knex storage system
-export { KnexStorage } from './src/storage/knex/KnexStorage.js'
-export * as KnexStorageMigrations from './src/storage/knex/all-migrations.js'

package/src/Advertisement.ts

@@ -1,8 +0,0 @@
-export interface Advertisement {
-  protocol: 'SHIP' | 'SLAP'
-  identityKey: string
-  domain: string
-  topicOrService: string
-  beef?: number[]
-  outputIndex?: number
-}

package/src/Advertiser.ts

@@ -1,41 +0,0 @@
-import { Script, TaggedBEEF } from '@bsv/sdk'
-import { Advertisement } from './Advertisement.js'
-
-export interface AdvertisementData {
-  protocol: 'SHIP' | 'SLAP'
-  topicOrServiceName: string
-}
-
-/**
- * Interface for managing SHIP and SLAP advertisements.
- * Provides methods for creating, finding, and revoking advertisements.
- */
-export interface Advertiser {
-
-  /**
-   * Creates a new SHIP/SLAP advertisement for a given topic.
-   * @param adsData - The data indicating the type of advertisement.
-   * @returns A promise that resolves to the created advertisement as TaggedBEEF.
-   */
-  createAdvertisements: (adsData: AdvertisementData[]) => Promise<TaggedBEEF>
-
-  /**
-   * Finds all SHIP/SLAP advertisements.
-   * @returns A promise that resolves to an array of SHIP/SLAP advertisements.
-   */
-  findAllAdvertisements: (protocol: 'SHIP' | 'SLAP') => Promise<Advertisement[]>
-
-  /**
-   * Revokes an existing advertisement, either SHIP or SLAP.
-   * @param advertisements - The advertisements to revoke, either SHIP or SLAP.
-   * @returns A promise that resolves to the revocation transaction as TaggedBEEF.
-   */
-  revokeAdvertisements: (advertisements: Advertisement[]) => Promise<TaggedBEEF>
-
-  /**
-   * Parses an output script to extract an advertisement.
-   * @param outputScript - The script of the output to be parsed.
-   * @returns The parsed advertisement
-   */
-  parseAdvertisement: (outputScript: Script) => Advertisement
-}

package/src/BASM.ts

@@ -1,208 +0,0 @@
-import { createHash } from 'node:crypto'
-import { MerklePath } from '@bsv/sdk'
-
-export const BASM_ZERO_HASH = '0000000000000000000000000000000000000000000000000000000000000000'
-
-export interface TopicBlockAnchor {
-  topic: string
-  blockHeight: number
-  blockHash: string
-  basmRoot: string
-  admittedCount: number
-  tac: string
-}
-
-export interface TopicAnchorTip {
-  topic: string
-  blockHeight: number
-  blockHash?: string
-  basmRoot?: string
-  admittedCount?: number
-  tac: string
-}
-
-export interface AdmittedTxRef {
-  txid: string
-  blockIndex: number
-}
-
-export interface RawTransactionRecord {
-  txid: string
-  rawTx: string
-}
-
-export interface RawTransactionRequest {
-  txids: string[]
-}
-
-export interface RawTransactionResponse {
-  transactions: RawTransactionRecord[]
-  missing: string[]
-}
-
-export interface TopicAnchorHeader {
-  blockHeight: number
-  blockHash: string
-  merkleRoot?: string
-}
-
-export type TopicAnchorHeaderResolver = (blockHeight: number) => Promise<TopicAnchorHeader | undefined>
-
-export interface TopicAnchorRangeRequest {
-  fromHeight: number
-  toHeight: number
-}
-
-export interface TopicAnchorRangeResponse {
-  topic: string
-  anchors: TopicBlockAnchor[]
-}
-
-export interface AdmittedListRequest {
-  blockHeight: number
-  blockHash?: string
-}
-
-export interface AdmittedListResponse {
-  topic: string
-  blockHeight: number
-  blockHash?: string
-  admitted: AdmittedTxRef[]
-}
-
-export interface CompoundMerklePathRequest {
-  blockHeight: number
-  txids: string[]
-}
-
-export interface CompoundMerklePathResponse {
-  topic: string
-  blockHeight: number
-  txids: string[]
-  merklePath: string
-}
-
-export interface MerkleProofMetadata {
-  blockHeight: number
-  blockIndex: number
-  merkleRoot: string
-}
-
-export interface ReorgReport {
-  perTopic: Array<{
-    topic: string
-    demotedTxids: string[]
-    rebuiltFrom: number
-    rebuiltTo: number
-  }>
-}
-
-export interface BASMPeerSyncReport {
-  topic: string
-  endpoint: string
-  status: 'matched' | 'advanced' | 'diverged' | 'skipped' | 'error'
-  localTip?: TopicAnchorTip
-  remoteTip?: TopicAnchorTip
-  checkedHeights: number[]
-  missingTxids: string[]
-  fetchedTxCount: number
-  message?: string
-}
-
-type AdmittedTxLike = string | AdmittedTxRef
-
-function sha256d(buffer: Buffer): Buffer {
-  const first = createHash('sha256').update(buffer).digest()
-  return createHash('sha256').update(first).digest()
-}
-
-function assertHashHex(hash: string, label: string): void {
-  if (!/^[0-9a-fA-F]{64}$/.test(hash)) {
-    throw new Error(`${label} must be 32 bytes of hex`)
-  }
-}
-
-function displayHexToInternal(hash: string): Buffer {
-  assertHashHex(hash, 'hash')
-  return Buffer.from(hash, 'hex').reverse()
-}
-
-function internalToDisplayHex(hash: Buffer): string {
-  return Buffer.from(hash).reverse().toString('hex')
-}
-
-function normalizeAdmittedTxids(admitted: AdmittedTxLike[]): string[] {
-  return admitted
-    .map((item, originalIndex) => {
-      if (typeof item === 'string') {
-        return { txid: item, blockIndex: originalIndex }
-      }
-      return item
-    })
-    .sort((a, b) => a.blockIndex - b.blockIndex)
-    .map(item => item.txid.toLowerCase())
-}
-
-/**
- * Computes a BRC-136 BASM root from admitted topic txids.
- *
- * The API accepts normal display-order txid hex because that is what the BSV
- * TypeScript stack exposes at its public boundaries. Hashing is performed on
- * internal byte order as required by the BRC, and the returned root is display
- * order for JSON/wire compatibility.
- */
-export function computeBasmRoot(admitted: AdmittedTxLike[]): string {
-  const txids = normalizeAdmittedTxids(admitted)
-
-  if (txids.length === 0) {
-    return BASM_ZERO_HASH
-  }
-
-  let layer = txids.map(txid => displayHexToInternal(txid))
-  if (layer.length === 1) {
-    return internalToDisplayHex(layer[0])
-  }
-
-  while (layer.length > 1) {
-    const next: Buffer[] = []
-    for (let i = 0; i < layer.length; i += 2) {
-      const left = layer[i]
-      const right = i + 1 < layer.length ? layer[i + 1] : left
-      next.push(sha256d(Buffer.concat([left, right])))
-    }
-    layer = next
-  }
-
-  return internalToDisplayHex(layer[0])
-}
-
-/**
- * Computes the BRC-136 cumulative Topic Anchor Chain hash:
- * SHA256d(prevTac || blockHash || basmRoot), with all inputs reversed to
- * internal byte order before hashing and the output returned as display hex.
- */
-export function computeTac(prevTac: string, blockHash: string, basmRoot: string): string {
-  const input = Buffer.concat([
-    displayHexToInternal(prevTac.toLowerCase()),
-    displayHexToInternal(blockHash.toLowerCase()),
-    displayHexToInternal(basmRoot.toLowerCase())
-  ])
-  return internalToDisplayHex(sha256d(input))
-}
-
-export function extractMerkleProofMetadata(txid: string, proof?: MerklePath): MerkleProofMetadata | undefined {
-  if (proof === undefined) {
-    return undefined
-  }
-
-  const leaf = proof.path[0]?.find(candidate => candidate.hash === txid)
-  if (leaf === undefined) {
-    return undefined
-  }
-
-  return {
-    blockHeight: proof.blockHeight,
-    blockIndex: leaf.offset,
-    merkleRoot: proof.computeRoot(txid)
-  }
-}

package/src/BASMRemote.ts

@@ -1,54 +0,0 @@
-import type {
-  AdmittedListResponse,
-  CompoundMerklePathResponse,
-  RawTransactionResponse,
-  TopicAnchorRangeResponse,
-  TopicAnchorTip
-} from './BASM.js'
-
-export class BASMRemote {
-  constructor(
-    private readonly endpoint: string,
-    private readonly topic: string,
-    private readonly fetchImpl: typeof fetch = fetch.bind(globalThis)
-  ) { }
-
-  async requestTopicAnchorTip(): Promise<TopicAnchorTip> {
-    return await this.post<TopicAnchorTip>('/requestTopicAnchorTip', {})
-  }
-
-  async requestTopicAnchorRange(fromHeight: number, toHeight: number): Promise<TopicAnchorRangeResponse> {
-    return await this.post<TopicAnchorRangeResponse>('/requestTopicAnchorRange', { fromHeight, toHeight })
-  }
-
-  async requestAdmittedList(blockHeight: number, blockHash?: string): Promise<AdmittedListResponse> {
-    return await this.post<AdmittedListResponse>('/requestAdmittedList', { blockHeight, blockHash })
-  }
-
-  async requestCompoundMerklePath(blockHeight: number, txids: string[]): Promise<CompoundMerklePathResponse> {
-    return await this.post<CompoundMerklePathResponse>('/requestCompoundMerklePath', { blockHeight, txids })
-  }
-
-  async requestRawTransactions(txids: string[]): Promise<RawTransactionResponse> {
-    return await this.post<RawTransactionResponse>('/requestRawTransactions', { txids })
-  }
-
-  private async post<T>(path: string, body: unknown): Promise<T> {
-    const response = await this.fetchImpl(new URL(path, this.endpoint).toString(), {
-      method: 'POST',
-      headers: {
-        Accept: 'application/json',
-        'Content-Type': 'application/json',
-        'x-bsv-topic': this.topic
-      },
-      body: JSON.stringify(body)
-    })
-
-    const text = await response.text()
-    if (!response.ok) {
-      throw new Error(`BASM peer ${this.endpoint} returned ${response.status}: ${text}`)
-    }
-
-    return (text.length === 0 ? {} : JSON.parse(text)) as T
-  }
-}