@bsv/overlay 0.1.0-alpha.1

package/src/LookupQuestion.ts

@@ -0,0 +1,15 @@
+/**
+ * The question asked to the Overlay Services Engine when a consumer of state wishes to look up information.
+ */
+export type LookupQuestion = {
+    /**
+     * The identifier for a Lookup Service which the person asking the question wishes to use.
+     */
+    service: string
+
+    /**
+     * The query which will be forwarded to the Lookup Service.
+     * Its type depends on that prescribed by the Lookup Service employed.
+     */
+    query: unknown
+}

package/src/LookupService.ts

@@ -0,0 +1,52 @@
+import { LookupQuestion } from './LookupQuestion.js'
+import { LookupFormula } from './LookupFormula.js'
+import { LookupAnswer } from './LookupAnswer.js'
+import { Script } from '@bsv/sdk'
+
+/**
+ * Defines a Lookup Service interface to be implemented for specific use-cases
+ */
+export default interface LookupService {
+
+    /**
+     * Process the event when a new UTXO is let into a topic
+     * @param txid 
+     * @param outputIndex 
+     * @param outputScript 
+     * @param topic 
+     */
+    outputAdded?(txid: string, outputIndex: number, outputScript: Script, topic: string): Promise<void>
+
+    /**
+     * Process the spend event for a UTXO
+     * @param txid 
+     * @param outputIndex 
+     * @param topic 
+     */
+    outputSpent?(txid: string, outputIndex: number, topic: string): Promise<void>
+
+    /**
+   * Process the deletion event for a UTXO
+   * @param txid 
+   * @param outputIndex 
+   * @param topic 
+   */
+    outputDeleted?(txid: string, outputIndex: number, topic: string): Promise<void>
+
+    /**
+     * Queries the lookup service for information
+     * @param question — The question to be answered by the lookup service
+     * @returns — The Lookup Answer or Lookup Formula used to answer the question
+     */
+    lookup(question: LookupQuestion): Promise<LookupAnswer | LookupFormula>
+
+    /**
+     * Returns a Markdown-formatted documentation string for the lookup service.
+     */
+    getDocumentation(): Promise<string>
+
+    /**
+     * Returns a metadata object that can be used to identify the lookup service.
+     */
+    getMetaData(): Promise<{ name: string, shortDescription: string, iconURL?: string, version?: string, informationURL?: string }>
+}

package/src/Output.ts

@@ -0,0 +1,29 @@
+/**
+ * Represents an output to be tracked by the Overlay Services Engine
+ */
+export type Output = {
+    /** TXID of the output */
+    txid: string
+    /** index of the output */
+    outputIndex: number
+    /** script of the output */
+    outputScript: number[]
+    /** number of satoshis in the output */
+    satoshis: number
+    /** topic to which the output belongs */
+    topic: string
+    /** Whether the output is spent */
+    spent: boolean
+    /** The transaction data for the output */
+    beef: number[]
+    /** Outputs consumed by the transaction associated with the output */
+    outputsConsumed: {
+        txid: string
+        outputIndex: number
+    }[]
+    /** Outputs consuming this output */
+    consumedBy: {
+        txid: string
+        outputIndex: number
+    }[]
+}

package/src/STEAK.ts

@@ -0,0 +1,10 @@
+import { AdmittanceInstructions } from "./AdmittanceInstructions.js"
+
+/**
+ * Submitted Transaction Execution AcKnowledgment
+ *
+ * @description
+ * Comprises the topics where a transaction was submitted, and for each one, the output indices for the UTXOs newly admitted into the topics, and the coins retained.
+ * An object whose keys are topic names and whose values are topical admittance instructions denoting the state of the submitted transaction with respect to the associated topic.
+ */
+export type STEAK = Record<string, AdmittanceInstructions>

package/src/TaggedBEEF.ts

@@ -0,0 +1,10 @@
+/**
+ * Tagged BEEF
+ *
+ * @description
+ * Tagged BEEF ([Background Evaluation Extended Format](https://brc.dev/62)) structure. Comprises a transaction, its SPV information, and the overlay topics where its inclusion is requested.
+ */
+export type TaggedBEEF = {
+  beef: number[]
+  topics: string[]
+}

package/src/TopicManager.ts

@@ -0,0 +1,23 @@
+import { AdmittanceInstructions } from './AdmittanceInstructions.js'
+
+/**
+ * Defines a Topic Manager interface that can be implemented for specific use-cases
+ */
+export default interface TopicManager {
+    /**
+     * Returns instructions that denote which outputs from the provided transaction to admit into the topic, and which previous coins should be retained.
+     * Accepts the transaction in BEEF format and an array of those input indicies which spend previously-admitted outputs from the same topic.
+     * The transaction's BEEF structure will always contain the transactions associated with previous coins for reference (if any), regardless of whether the current transaction was directly proven.
+     */
+    identifyAdmissibleOutputs(beef: number[], previousCoins: number[]): Promise<AdmittanceInstructions>
+
+    /**
+    * Returns a Markdown-formatted documentation string for the topic manager.
+    */
+    getDocumentation(): Promise<string>
+
+    /**
+     * Returns a metadata object that can be used to identify the topic manager.
+     */
+    getMetaData(): Promise<{ name: string, shortDescription: string, iconURL?: string, version?: string, informationURL?: string }>
+}