@bsv/overlay 0.1.0-alpha.1 → 0.1.0-alpha.2

package/src/LookupAnswer.ts

@@ -3,12 +3,12 @@
  * It may comprise either an output list or a freeform response from the Lookup Service.
  */
 export type LookupAnswer = {
-    type: 'output-list'
-    outputs: Array<{
-        beef: number[]
-        outputIndex: number
-    }>
+  type: 'output-list'
+  outputs: Array<{
+    beef: number[]
+    outputIndex: number
+  }>
 } | {
-    type: 'freeform',
-    result: unknown
+  type: 'freeform'
+  result: unknown
 }

package/src/LookupFormula.ts

@@ -1,26 +1,26 @@
 /**
  * The formula that will be used by the Overlay Services Engine to compute the Lookup Answer. Can be returned by Lookup Services in response to a Lookup Question.
  */
-export type LookupFormula = {
-    /**
-     * TXID of the transaction where an output responsive to the Lookup Question resides.
-     */
-    txid: string,
+export type LookupFormula = Array<{
+  /**
+   * TXID of the transaction where an output responsive to the Lookup Question resides.
+   */
+  txid: string
 
-    /**
-     * Index of the transaction output responsive to the Lookup Question.
-     */
-    outputIndex: number,
+  /**
+   * Index of the transaction output responsive to the Lookup Question.
+   */
+  outputIndex: number
 
-    /**
-     * Decides what history to incorporate into the Lookup Answer.
-     * 
-     * Optionally directs the Overlay Services Engine as to the historical context (preceeding outputs) to include as part of the Lookup Answer.
-     * - If a number, denotes how many previous spends (in terms of chain depth) the Engine should include with the Answer.
-     * - If a decider function, accepts a BEEF-formatted transaction, an output index and the current depth (relative to the top-level respnosive UTXO) as parameters.
-     *   The function returns a promise for a boolean indicating whether the output should be incorporated into the Lookup Answer.
-     *   If so, the function will be called again for transactions that preceeded the one provided, ultimately allowing the complete shape of the responsive spend history to be described.
-     * If not provided, no historical information will be included with the Lookup Answer, except that which may incidentally be required to fully anchor the Lookup Answer to the blockchain.
-     */
-    history?: ((beef: number[], outputIndex: number, currentDepth: number) => Promise<boolean>) | number
-}[]
+  /**
+   * Decides what history to incorporate into the Lookup Answer.
+   *
+   * Optionally directs the Overlay Services Engine as to the historical context (preceding outputs) to include as part of the Lookup Answer.
+   * - If a number, denotes how many previous spends (in terms of chain depth) the Engine should include with the Answer.
+   * - If a decider function, accepts a BEEF-formatted transaction, an output index and the current depth (relative to the top-level responsive UTXO) as parameters.
+   *   The function returns a promise for a boolean indicating whether the output should be incorporated into the Lookup Answer.
+   *   If so, the function will be called again for transactions that preceded the one provided, ultimately allowing the complete shape of the responsive spend history to be described.
+   * If not provided, no historical information will be included with the Lookup Answer, except that which may incidentally be required to fully anchor the Lookup Answer to the blockchain.
+   */
+  history?: ((beef: number[], outputIndex: number, currentDepth: number) => Promise<boolean>) | number
+}>

package/src/LookupQuestion.ts

@@ -2,14 +2,14 @@
  * 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 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
+  /**
+   * 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

@@ -6,47 +6,65 @@ import { Script } from '@bsv/sdk'
 /**
  * Defines a Lookup Service interface to be implemented for specific use-cases
  */
-export default interface LookupService {
+export 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 event when a new UTXO is let into a topic
+   * @param txid - The transaction ID (TXID) of the transaction where the new UTXO resides.
+   * @param outputIndex - The index of the transaction output (UTXO) within the transaction.
+   * @param outputScript - The script associated with the transaction output.
+   * @param topic - The topic to which the new UTXO is being added.
+   * @returns A promise that resolves when the processing of the new UTXO is complete.
+   */
+  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>
+  /**
+   * Processes the spend event for a UTXO.
+   *
+   * @param txid - The transaction ID of the spent UTXO.
+   * @param outputIndex - The index of the transaction output that was spent.
+   * @param topic - The topic from which the UTXO was spent.
+   *
+   * @returns A promise that resolves when processing is complete.
+   */
+  outputSpent?: (txid: string, outputIndex: number, topic: string) => Promise<void>
 
-    /**
-   * Process the deletion event for a UTXO
-   * @param txid 
-   * @param outputIndex 
-   * @param topic 
+  /**
+   * Processes the deletion event for a UTXO.
+   *
+   * @param txid - The transaction ID of the deleted UTXO.
+   * @param outputIndex - The index of the transaction output that was deleted.
+   * @param topic - The topic from which the UTXO was deleted.
+   *
+   * @returns A promise that resolves when processing is complete.
    */
-    outputDeleted?(txid: string, outputIndex: number, topic: string): Promise<void>
+  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>
+  /**
+   * 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 Markdown-formatted documentation string for the lookup service.
+   *
+   * @returns A promise that resolves to a documentation string.
+   */
+  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 }>
+  /**
+   * Returns a metadata object that can be used to identify the lookup service.
+   *
+   * @returns A promise that resolves to a metadata object containing the name, short description,
+   *          and optional properties such as icon URL, version, and information URL.
+   */
+  getMetaData: () => Promise<{
+    name: string
+    shortDescription: string
+    iconURL?: string
+    version?: string
+    informationURL?: string
+  }>
 }

package/src/Output.ts

@@ -2,28 +2,28 @@
  * Represents an output to be tracked by the Overlay Services Engine
  */
 export type Output = {
-    /** TXID of the 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: Array<{
     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
-    }[]
+  }>
+  /** Outputs consuming this output */
+  consumedBy: Array<{
+    txid: string
+    outputIndex: number
+  }>
 }

package/src/STEAK.ts

@@ -1,4 +1,4 @@
-import { AdmittanceInstructions } from "./AdmittanceInstructions.js"
+import { AdmittanceInstructions } from './AdmittanceInstructions.js'
 
 /**
  * Submitted Transaction Execution AcKnowledgment

package/src/TopicManager.ts

@@ -3,21 +3,27 @@ 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>
+export 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 indices 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 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 }>
+  /**
+   * 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
+  }>
 }

package/src/__tests/Engine.test.ts

@@ -1,8 +1,8 @@
-import Engine from '../Engine'
-import LookupService from '../LookupService'
-import TopicManager from '../TopicManager'
+import { Engine } from '../Engine'
+import { LookupService } from '../LookupService'
+import { TopicManager } from '../TopicManager'
 import { AdmittanceInstructions } from '../AdmittanceInstructions'
-import Storage from '../storage/Storage'
+import { Storage } from '../storage/Storage'
 import { Transaction } from '@bsv/sdk'
 import { Output } from '../Output'
 
@@ -56,8 +56,10 @@ describe('BSV Overlay Services Engine', () => {
       insertAppliedTransaction: jest.fn(),
       insertOutput: jest.fn(),
       findOutput: jest.fn(async () => null),
+      findOutputsForTransaction: jest.fn(async () => []),
       markUTXOAsSpent: jest.fn(),
       updateConsumedBy: jest.fn(),
+      updateOutputBeef: jest.fn(),
       deleteOutput: jest.fn()
     }
   })

package/src/storage/Storage.ts

@@ -1,7 +1,7 @@
 import type { Output } from '../Output.js'
 
 /**
- * Representa a transaction that has been applied to a topic.
+ * Represents a transaction that has been applied to a topic.
  */
 interface AppliedTransaction {
   /** TXID of the applied transaction */
@@ -13,60 +13,75 @@ interface AppliedTransaction {
 /**
  * Defines the Storage Engine interface used internally by the Overlay Services Engine.
  */
-export default interface Storage {
+export interface Storage {
   /**
-     * Adds a new output to storage
-     * @param utxo — The output to add
-     */
+   * Adds a new output to storage
+   * @param utxo — The output to add
+   */
   insertOutput: (utxo: Output) => Promise<void>
 
   /**
-     * Finds an output from storage
-     * @param txid — TXID of hte output to find
-     * @param outputIndex — Output index for the output to find
-     * @param topic — The topic in which the output is stored
-     * @param spent — Whether the output must be spent to be returned
-     */
+   * Finds an output from storage
+   * @param txid — TXID of hte output to find
+   * @param outputIndex — Output index for the output to find
+   * @param topic — The topic in which the output is stored
+   * @param spent — Whether the output must be spent to be returned
+   */
   findOutput: (txid: string, outputIndex: number, topic?: string, spent?: boolean) => Promise<Output | null>
 
   /**
-     * Deletes an output from storage
-     * @param txid — The TXID of the output to delete
-     * @param outputIndex — The index of the output to delete
-     * @param topic — The topic where the output should be deleted
-     */
+   * Finds outputs with a matching transaction ID from storage
+   * @param txid — TXID of the outputs to find
+   */
+  findOutputsForTransaction: (txid: string) => Promise<Output[]>
+
+  /**
+   * Deletes an output from storage
+   * @param txid — The TXID of the output to delete
+   * @param outputIndex — The index of the output to delete
+   * @param topic — The topic where the output should be deleted
+   */
   deleteOutput: (txid: string, outputIndex: number, topic: string) => Promise<void>
 
   /**
-    * Updates a UTXO as spent
-    * @param txid — TXID of the output to update
-    * @param outputIndex — Index of the output to update
-    * @param topic — Topic in which the output should be updated
-    */
+  * Updates a UTXO as spent
+  * @param txid — TXID of the output to update
+  * @param outputIndex — Index of the output to update
+  * @param topic — Topic in which the output should be updated
+  */
   markUTXOAsSpent: (txid: string, outputIndex: number, topic: string) => Promise<void>
 
   /**
-    * Updates which outputs are consumed by this output
-    * @param txid — TXID of the output to update
-    * @param outputIndex — Index of the output to update
-    * @param topic — Topic in which the output should be updated
-    * @param consumedBy — The new set of outputs consumed by this output
-    */
+  * Updates which outputs are consumed by this output
+  * @param txid — TXID of the output to update
+  * @param outputIndex — Index of the output to update
+  * @param topic — Topic in which the output should be updated
+  * @param consumedBy — The new set of outputs consumed by this output
+  */
   updateConsumedBy: (txid: string, outputIndex: number, topic: string, consumedBy: Array<{
     txid: string
     outputIndex: number
   }>) => Promise<void>
 
   /**
-     * Inserts record of the applied transaction
-     * @param tx — The transaction to insert
-     */
+   * Updates the beef data on an output
+   * @param txid — TXID of the output to update
+   * @param outputIndex — Index of the output to update
+   * @param topic — Topic in which the output should be updated
+   * @param beef - BEEF data to update
+   */
+  updateOutputBeef: (txid: string, outputIndex: number, topic: string, beef: number[]) => Promise<void>
+
+  /**
+   * Inserts record of the applied transaction
+   * @param tx — The transaction to insert
+   */
   insertAppliedTransaction: (tx: AppliedTransaction) => Promise<void>
 
   /**
-     * Checks if a duplicate transaction exists
-     * @param tx — Transaction to check
-     * @returns Whether the transaction is already applied
-     */
+   * Checks if a duplicate transaction exists
+   * @param tx — Transaction to check
+   * @returns Whether the transaction is already applied
+   */
   doesAppliedTransactionExist: (tx: AppliedTransaction) => Promise<boolean>
 }

package/src/storage/knex/KnexStorage.ts

@@ -1,90 +1,115 @@
-import Storage from '../Storage.js'
+import { Storage } from '../Storage.js'
 import { Knex } from 'knex'
 import type { Output } from '../../Output.js'
 
-export default class KnexStorage implements Storage {
-    knex: Knex
+export class KnexStorage implements Storage {
+  knex: Knex
 
-    constructor(knex: Knex) {
-        this.knex = knex
-    }
+  constructor(knex: Knex) {
+    this.knex = knex
+  }
 
-    async findOutput(txid: string, outputIndex: number, topic?: string, spent?: boolean): Promise<Output | null> {
-        const search: {
-            txid: string,
-            outputIndex: number,
-            topic?: string,
-            spent?: boolean
-        } = {
-            txid,
-            outputIndex
-        }
-        if (topic !== undefined) search.topic = topic
-        if (spent !== undefined) search.spent = spent
-        const [output] = await this.knex('outputs').where(search).select(
-            'txid', 'outputIndex', 'outputScript', 'topic', 'satoshis', 'beef', 'outputsConsumed', 'spent', 'consumedBy'
-        )
-        if (!output) {
-            return null
-        }
-        return {
-            ...output,
-            outputScript: [...output.outputScript],
-            beef: [...output.beef],
-            spent: Boolean(output.spent),
-            outputsConsumed: JSON.parse(output.outputsConsumed),
-            consumedBy: JSON.parse(output.consumedBy)
-        }
+  async findOutput(txid: string, outputIndex: number, topic?: string, spent?: boolean): Promise<Output | null> {
+    const search: {
+      txid: string
+      outputIndex: number
+      topic?: string
+      spent?: boolean
+    } = {
+      txid,
+      outputIndex
     }
-
-    async deleteOutput(txid: string, outputIndex: number, topic: string): Promise<void> {
-        await this.knex('outputs').where({
-            txid, outputIndex, topic
-        }).del()
+    if (topic !== undefined) search.topic = topic
+    if (spent !== undefined) search.spent = spent
+    const [output] = await this.knex('outputs').where(search).select(
+      'txid', 'outputIndex', 'outputScript', 'topic', 'satoshis', 'beef', 'outputsConsumed', 'spent', 'consumedBy'
+    )
+    if (output === undefined || output === null) {
+      return null
     }
-
-    async insertOutput(output: Output) {
-        await this.knex('outputs').insert({
-            txid: output.txid,
-            outputIndex: Number(output.outputIndex),
-            outputScript: Buffer.from(output.outputScript),
-            topic: output.topic,
-            satoshis: Number(output.satoshis),
-            beef: [...output.beef],
-            outputsConsumed: JSON.stringify(output.outputsConsumed),
-            consumedBy: JSON.stringify(output.consumedBy),
-            spent: output.spent
-        })
+    return {
+      ...output,
+      outputScript: [...output.outputScript],
+      beef: [...output.beef],
+      spent: Boolean(output.spent),
+      outputsConsumed: JSON.parse(output.outputsConsumed),
+      consumedBy: JSON.parse(output.consumedBy)
     }
+  }
 
-    async markUTXOAsSpent(txid: string, outputIndex: number, topic?: string): Promise<void> {
-        await this.knex('outputs').where({
-            txid,
-            outputIndex,
-            topic
-        }).update('spent', true)
+  async findOutputsForTransaction(txid: string): Promise<Output[]> {
+    const [output] = await this.knex('outputs').where({ txid }).select(
+      'txid', 'outputIndex', 'outputScript', 'topic', 'satoshis', 'beef', 'outputsConsumed', 'spent', 'consumedBy'
+    )
+    if (output === undefined || output === null) {
+      return []
     }
-
-    async updateConsumedBy(txid: string, outputIndex: number, topic: string, consumedBy: { txid: string, outputIndex: number }[]) {
-        await this.knex('outputs').where({
-            txid,
-            outputIndex,
-            topic
-        }).update('consumedBy', consumedBy)
+    return {
+      ...output,
+      outputScript: [...output.outputScript],
+      beef: [...output.beef],
+      spent: Boolean(output.spent),
+      outputsConsumed: JSON.parse(output.outputsConsumed),
+      consumedBy: JSON.parse(output.consumedBy)
     }
+  }
 
-    async insertAppliedTransaction(tx: { txid: string, topic: string }) {
-        await this.knex('applied_transactions').insert({
-            txid: tx.txid,
-            topic: tx.topic
-        })
-    }
+  async deleteOutput(txid: string, outputIndex: number, topic: string): Promise<void> {
+    await this.knex('outputs').where({
+      txid, outputIndex, topic
+    }).del()
+  }
 
-    async doesAppliedTransactionExist(tx: { txid: string, topic: string }): Promise<boolean> {
-        const appliedTransactions = await this.knex('applied_transactions').where({
-            txid: tx.txid,
-            topic: tx.topic
-        }).select('txid', 'topic')
-        return appliedTransactions.length > 0
-    }
+  async insertOutput(output: Output): Promise<void> {
+    await this.knex('outputs').insert({
+      txid: output.txid,
+      outputIndex: Number(output.outputIndex),
+      outputScript: Buffer.from(output.outputScript),
+      topic: output.topic,
+      satoshis: Number(output.satoshis),
+      beef: Buffer.from(new Uint8Array(output.beef)),
+      outputsConsumed: JSON.stringify(output.outputsConsumed),
+      consumedBy: JSON.stringify(output.consumedBy),
+      spent: output.spent
+    })
+  }
+
+  async markUTXOAsSpent(txid: string, outputIndex: number, topic?: string): Promise<void> {
+    await this.knex('outputs').where({
+      txid,
+      outputIndex,
+      topic
+    }).update('spent', true)
+  }
+
+  async updateConsumedBy(txid: string, outputIndex: number, topic: string, consumedBy: Array<{ txid: string, outputIndex: number }>): Promise<void> {
+    await this.knex('outputs').where({
+      txid,
+      outputIndex,
+      topic
+    }).update('consumedBy', consumedBy)
+  }
+
+  async updateOutputBeef(txid: string, outputIndex: number, topic: string, beef: number[]): Promise<void> {
+    await this.knex('outputs').where({
+      txid,
+      outputIndex,
+      topic
+    }).update('beef', beef)
+  }
+
+  async insertAppliedTransaction(tx: { txid: string, topic: string }): Promise<void> {
+    await this.knex('applied_transactions').insert({
+      txid: tx.txid,
+      topic: tx.topic
+    })
+  }
+
+  async doesAppliedTransactionExist(tx: { txid: string, topic: string }): Promise<boolean> {
+    const appliedTransactions = await this.knex('applied_transactions').where({
+      txid: tx.txid,
+      topic: tx.topic
+    }).select('txid', 'topic')
+    return appliedTransactions.length > 0
+  }
 }