@bsv/overlay 0.1.0-alpha.1

package/docs/examples/gs-wip.md

@@ -0,0 +1,105 @@
+### 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

@@ -0,0 +1,4 @@
+# Internals
+
+These documents cover the internal components of the Overlay Services engine. Generally, these are only useful for creating customized deployments:
+

package/mod.ts

@@ -0,0 +1,18 @@
+// Fundamentals
+export * as Engine from "./src/Engine.js"
+export * as LookupService from "./src/LookupService.js"
+export * as TopicManager from "./src/TopicManager.js"
+
+// Interfaces and structures
+export * as Storage from "./src/storage/Storage.js"
+export * as Output from './src/Output.js'
+export * as AdmittanceInstructions from './src/AdmittanceInstructions.js'
+export * as TaggedBEEF from './src/TaggedBEEF.js'
+export * as STEAK from './src/STEAK.js'
+export * as LookupQuestion from './src/LookupQuestion.js'
+export * as LookupFormula from './src/LookupFormula.js'
+export * as LookupAnswer from './src/LookupAnswer.js'
+
+// The Knex storage system
+export * as KnexStorage from './src/storage/knex/KnexStorage.js'
+export * as KnexStorageMigrations from './src/storage/knex/all-migrations.js'

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@bsv/overlay",
+  "version": "0.1.0-alpha.1",
+  "type": "module",
+  "description": "BSV Blockchain Overlay Services Engine",
+  "main": "dist/cjs/mod.js",
+  "module": "dist/esm/mod.js",
+  "types": "dist/types/mod.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "docs",
+    "mod.ts",
+    "LICENSE.txt"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/mod.d.ts",
+      "import": "./dist/esm/mod.js",
+      "require": "./dist/cjs/mod.js"
+    },
+    "./*.ts": {
+      "types": "./dist/types/src/*.d.ts",
+      "import": "./dist/esm/src/*.js",
+      "require": "./dist/cjs/src/*.js"
+    },
+    "./storage": {
+      "import": "./dist/esm/src/storage/index.js",
+      "require": "./dist/cjs/src/storage/index.js",
+      "types": "./dist/types/src/storage/index.d.ts"
+    },
+    "./storage/*": {
+      "import": "./dist/esm/src/storage/*.js",
+      "require": "./dist/cjs/src/storage/*.js",
+      "types": "./dist/types/src/storage/*.d.ts"
+    }
+  },
+  "scripts": {
+    "test": "npm run build && jest",
+    "test:watch": "npm run build && jest --watch",
+    "test:coverage": "npm run build && jest --coverage",
+    "lint": "ts-standard --fix src/**/*.ts",
+    "build": "tsc -b && tsconfig-to-dual-package tsconfig.cjs.json",
+    "dev": "tsc -b -w",
+    "prepublish": "npm run build",
+    "doc": "ts2md --inputFilename=mod.ts --outputFilename=docs/API.md --filenameSubstring=API --firstHeadingLevel=1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bitcoin-sv/overlay-services.git"
+  },
+  "keywords": [
+    "BSV",
+    "Blockchain",
+    "Overlay",
+    "Bitcoin",
+    "SV"
+  ],
+  "author": "BSV Association",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "bugs": {
+    "url": "https://github.com/bitcoin-sv/overlay-services/issues"
+  },
+  "homepage": "https://github.com/bitcoin-sv/overlay-services#readme",
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "ts-standard": "^12.0.2",
+    "ts2md": "^0.2.0",
+    "tsconfig-to-dual-package": "^1.2.0",
+    "typescript": "^5.2.2"
+  },
+  "dependencies": {
+    "@bsv/sdk": "^1.0.20",
+    "knex": "^3.1.0"
+  }
+}

package/src/AdmittanceInstructions.ts

@@ -0,0 +1,14 @@
+/**
+ * Instructs the Overlay Services Engine about which outputs to admit and which previous outputs to retain. Returned by a Topic Manager.
+ */
+export type AdmittanceInstructions = {
+    /**
+     * The indicies of all admissable outputs into the managed topic from the provided transaction.
+     */
+    outputsToAdmit: number[]
+
+    /**
+     * The indicies of all inputs from the provided transaction which spend previously-admitted outputs that should be retained for historical record-keeping.
+     */
+    coinsToRetain: number[]
+}

package/src/Engine.ts

@@ -0,0 +1,419 @@
+import TopicManager from "./TopicManager.js"
+import LookupService from "./LookupService.js"
+import Storage from './storage/Storage.js'
+import type { AdmittanceInstructions } from "./AdmittanceInstructions.js"
+import type { Output } from './Output.js'
+import { TaggedBEEF } from "./TaggedBEEF.js"
+import { STEAK } from './STEAK.js'
+import { LookupQuestion } from "./LookupQuestion.js"
+import { LookupAnswer } from "./LookupAnswer.js"
+import { LookupFormula } from "./LookupFormula.js"
+import { Transaction, ChainTracker } from '@bsv/sdk'
+
+/**
+ * Am engine for running BSV Overlay Services (topic managers and lookup services).
+ */
+export default class Engine {
+    /**
+     * Creates a new Overlay Services Engine
+     * @param {[key: string]: TopicManager} managers - manages topic admittance
+     * @param {[key: string]: LookupService} lookupServices - manages UTXO lookups
+     * @param {Storage} storage - for interacting with internally-managed persistent data
+     * @param {ChainTracker} chainTracker - Verifies SPV data associated with transactions
+     * @param {ProofNotifier[]} [proofNotifiers] - proof notifier services coming soon!
+     */
+    constructor(
+        public managers: { [key: string]: TopicManager },
+        public lookupServices: { [key: string]: LookupService },
+        public storage: Storage,
+        public chainTracker: ChainTracker
+        // public proofNotifiers: ProofNotifier[]
+    ) { }
+
+    /**
+     * Submits a transaction for processing by Overlay Services.
+     * @param taggedBEEF — The transaction to process
+     * @returns The submitted transaction execution acknowledgement
+     */
+    async submit(taggedBEEF: TaggedBEEF): Promise<STEAK> {
+        for (const t of taggedBEEF.topics) {
+            if (!this.managers[t]) throw new Error(`This server does not support this topic: ${t}`)
+        }
+        // Validate the transaction SPV information
+        const tx = Transaction.fromBEEF(taggedBEEF.beef)
+        const txid = tx.id('hex') as string
+        const txValid = await tx.verify(this.chainTracker)
+        if (!txValid) throw new Error('Unable to verify SPV information.')
+
+        // Find UTXOs belonging to a particular topic
+        const steak: STEAK = {}
+        for (const topic of taggedBEEF.topics) {
+            // Ensure transaction is not already applied to the topic
+            const dupeCheck = await this.storage.doesAppliedTransactionExist({
+                txid,
+                topic
+            })
+            if (dupeCheck) {
+                // The transaction was already processed.
+                // Currently, NO OUTPUTS ARE ADMITTED FOR DUPLICATE TRANSACTIONS.
+                // An alternative decision, one that was decided against, would be to act as if the operation was successful: looking up and returning the list of admitted outputs from when the transaction was originally processed.
+                // This was decided against, because we don't want to encourage unnecessary flooding of duplicative transactions to overlay services.
+                steak[topic] = {
+                    outputsToAdmit: [],
+                    coinsToRetain: []
+                }
+                continue
+            }
+
+            // Check if any input of this transaction is a previous UTXO, adding previous UTXOs to the list
+            const previousCoins: number[] = []
+            for (const [i, input] of tx.inputs.entries()) {
+                const previousTXID = input.sourceTXID || input.sourceTransaction?.id('hex') as string
+                // Check if a previous UTXO exists in the storage medium
+                const output = await this.storage.findOutput(
+                    previousTXID,
+                    input.sourceOutputIndex,
+                    topic
+                )
+                if (output) {
+                    previousCoins.push(i)
+
+                    // This output is now spent.
+                    await this.storage.markUTXOAsSpent(
+                        output.txid,
+                        output.outputIndex,
+                        topic
+                    )
+
+                    // Notify the lookup services about the spending of this output
+                    for (const l of Object.values(this.lookupServices)) {
+                        try {
+                            if (l.outputSpent) {
+                                await l.outputSpent(
+                                    output.txid,
+                                    output.outputIndex,
+                                    topic
+                                )
+                            }
+                        } catch (_) { }
+                    }
+                }
+            }
+
+            // Use the manager to determine which outputs are admissable
+            let admissableOutputs: AdmittanceInstructions
+            try {
+                admissableOutputs = await this.managers[topic].identifyAdmissibleOutputs(taggedBEEF.beef, previousCoins)
+            } catch (_) {
+                // If the topic manager throws an error, other topics may still succeed, so we continue to the next one.
+                // No outputs were admitted to this topic in this case. Note, however, that the transaction is still valid according to Bitcoin, so it may have spent some previous overlay members. This is unavoidable and good.
+                steak[topic] = {
+                    outputsToAdmit: [],
+                    coinsToRetain: []
+                }
+                continue
+            }
+
+            // Keep track of which outputs to admit, mark as stale, or retain
+            let outputsToAdmit: number[] = admissableOutputs.outputsToAdmit
+            let staleCoins: {
+                txid: string
+                outputIndex: number
+            }[] = []
+            let outputsConsumed: {
+                txid: string
+                outputIndex: number
+            }[] = []
+
+            // Find which outputs should not be retained and mark them as stale
+            // For each of the previous UTXOs, if the the UTXO was not included in the list of UTXOs identified for retention, then it will be marked as stale.
+            for (const inputIndex of previousCoins) {
+                const previousTXID = tx.inputs[inputIndex].sourceTXID || tx.inputs[inputIndex].sourceTransaction?.id('hex') as string
+                const previousOutputIndex = tx.inputs[inputIndex].sourceOutputIndex
+                if (!admissableOutputs.coinsToRetain.includes(inputIndex)) {
+                    staleCoins.push({
+                        txid: previousTXID,
+                        outputIndex: previousOutputIndex
+                    })
+                } else {
+                    outputsConsumed.push({
+                        txid: previousTXID,
+                        outputIndex: previousOutputIndex
+                    })
+                }
+            }
+
+            // Remove stale outputs recursively
+            for (const coin of staleCoins) {
+                const output = await this.storage.findOutput(coin.txid, coin.outputIndex, topic)
+                if (output) {
+                    await this.deleteUTXODeep(output)
+                }
+            }
+
+            // Handle admittance and notification of incoming UTXOs
+            const newUTXOs: { txid: string, outputIndex: number }[] = []
+            for (const outputIndex of outputsToAdmit) {
+                // Store the output
+                await this.storage.insertOutput({
+                    txid,
+                    outputIndex,
+                    outputScript: tx.outputs[outputIndex].lockingScript.toBinary(),
+                    satoshis: tx.outputs[outputIndex].satoshis as number,
+                    topic,
+                    spent: false,
+                    beef: taggedBEEF.beef,
+                    consumedBy: [],
+                    outputsConsumed
+                })
+                newUTXOs.push({
+                    txid,
+                    outputIndex
+                })
+
+                // Notify all the lookup services about the new UTXO
+                for (const l of Object.values(this.lookupServices)) {
+                    try {
+                        if (l.outputAdded) {
+                            await l.outputAdded(txid, outputIndex, tx.outputs[outputIndex].lockingScript, topic)
+                        }
+                    } catch (_) { }
+                }
+            }
+
+            // Update each output consumed to know who consumed it
+            for (const output of outputsConsumed) {
+                const outputToUpdate = await this.storage.findOutput(output.txid, output.outputIndex, topic)
+                if (outputToUpdate) {
+                    const newConsumedBy = [...new Set([...newUTXOs, ...outputToUpdate.consumedBy])]
+                    // Note: only update if newConsumedBy !== new Set(JSON.parse(outputToUpdate.consumedBy)) ?
+                    await this.storage.updateConsumedBy(output.txid, output.outputIndex, topic, newConsumedBy)
+                }
+            }
+
+            // Insert the applied transaction to prevent duplicate processing
+            await this.storage.insertAppliedTransaction({
+                txid,
+                topic
+            })
+
+            // Keep track of what outputs were admitted for what topic
+            steak[topic] = admissableOutputs
+        }
+
+        return steak
+        // TODO subscribe to get notified by proof notifiers when proof is found for TX if not already present, so the tree can be chopped down
+        // TODO propagate transaction to other nodes according to synchronization agreements
+    }
+
+    /**
+     * Submit a lookup question to the Overlay Services Engine, and receive bakc a Lookup Answer
+     * @param LookupQuestion — The question to ask the Overlay Services Engine
+     * @returns The answer to the question
+     */
+    async lookup(lookupQuestion: LookupQuestion): Promise<LookupAnswer> {
+        // Validate a lookup service for the provider is found
+        const lookupService = this.lookupServices[lookupQuestion.service]
+        if (!lookupService) throw new Error(`Lookup service not found for provider: ${lookupQuestion.service}`)
+
+        let lookupResult = await lookupService.lookup(lookupQuestion)
+        // Handle custom lookup service answers
+        if ((lookupResult as LookupAnswer).type === 'freeform' || (lookupResult as LookupAnswer).type === 'output-list') {
+            return lookupResult as LookupAnswer
+        }
+        lookupResult = lookupResult as LookupFormula
+
+        const hydratedOutputs: { beef: number[], outputIndex: number }[] = []
+
+        for (const { txid, outputIndex, history } of lookupResult) {
+            // Make sure this is an unspent output (UTXO)
+            const UTXO = await this.storage.findOutput(
+                txid,
+                outputIndex,
+                undefined,
+                false
+            )
+            if (!UTXO) continue
+
+            // Get the history for this utxo and construct a BRC-8 Envelope
+            const output = await this.getUTXOHistory(UTXO, history, 0)
+            if (output) {
+                hydratedOutputs.push({
+                    beef: output.beef,
+                    outputIndex: output.outputIndex
+                })
+            }
+        }
+        return {
+            type: 'output-list',
+            outputs: hydratedOutputs
+        }
+    }
+
+    /**
+     * Traverse and return the history of a UTXO
+     * @param historySelector 
+     * @param currentDepth 
+     * @param output 
+     * @param txid 
+     * @param outputIndex 
+     * @param id 
+     * @returns {Promise<EnvelopeEvidenceApi>}
+     */
+    async getUTXOHistory(
+        output: Output,
+        historySelector?: ((beef: number[], outputIndex: number, currentDepth: number) => Promise<boolean>) | number, currentDepth = 0,
+    ): Promise<Output | undefined> {
+        // If we have an output but no history selector, jsut return the output.
+        if (typeof historySelector === 'undefined') {
+            return output
+        }
+
+        // Determine if history traversal should continue for the current node
+        let shouldTraverseHistory
+        if (typeof historySelector !== 'number') {
+            shouldTraverseHistory = await historySelector(output.beef, output.outputIndex, currentDepth)
+        } else {
+            shouldTraverseHistory = currentDepth <= historySelector
+        }
+
+        if (shouldTraverseHistory === false) {
+            return undefined
+        } else if (output && output.outputsConsumed.length === 0) {
+            return output
+        }
+
+        try {
+            // Query the storage engine for UTXOs consumed by this UTXO
+            // Only retrieve unique values in case outputs are doubly referenced
+            const outputsConsumed: { txid: string, outputIndex: number }[] = output.outputsConsumed
+
+            // Find the child outputs for each utxo consumed by the current output
+            const childHistories = await (await Promise.all(
+                outputsConsumed.map(async (outputIdentifier) => {
+                    const output = await this.storage.findOutput(outputIdentifier.txid, outputIdentifier.outputIndex)
+
+                    // Make sure an output was found
+                    if (!output) {
+                        return undefined
+                    }
+
+                    // Find previousUTXO history
+                    return this.getUTXOHistory(output, historySelector, currentDepth + 1)
+                })
+            )).filter(x => x !== undefined)
+
+            const tx = Transaction.fromBEEF(output.beef)
+            for (const input of childHistories) {
+                if (!input) continue
+                const inputIndex = tx.inputs.findIndex((input) => {
+                    const sourceTXID = input.sourceTXID || input.sourceTransaction?.id('hex') as string
+                    return sourceTXID === output.txid && input.sourceOutputIndex === output.outputIndex
+                })
+                tx.inputs[inputIndex].sourceTransaction = Transaction.fromBEEF(input.beef)
+            }
+            const beef = tx.toBEEF()
+            return {
+                ...output,
+                beef
+            }
+        } catch (e) {
+            // Handle any errors that occurred
+            // Note: Test this!
+            console.error(`Error retrieving UTXO history: ${e}`)
+            // return []
+            throw new Error(`Error retrieving UTXO history: ${e}`)
+        }
+    }
+
+    /**
+      * Delete a UTXO and all stale consumed inputs
+      * @param output 
+      * @param id 
+      * @param txid 
+      * @param outputIndex 
+      * @returns {Promise<void>}
+      */
+    private async deleteUTXODeep(output: Output): Promise<void> {
+        try {
+            // Delete the current output IFF there are no references to it
+            if (output.consumedBy.length === 0) {
+                await this.storage.deleteOutput(output.txid, output.outputIndex, output.topic)
+
+                // Notify the lookup services of the UTXO being deleted
+                for (const l of Object.values(this.lookupServices)) {
+                    try {
+                        await l.outputDeleted?.(
+                            output.txid,
+                            output.outputIndex,
+                            output.topic!
+                        )
+                    } catch (_) { }
+                }
+            }
+
+            // If there are no more consumed utxos, return
+            if (output.outputsConsumed.length === 0) {
+                return
+            }
+
+            // Delete any stale outputs that were consumed as inputs
+            output.outputsConsumed.map(async (outputIdentifier) => {
+                const staleOutput = await this.storage.findOutput(outputIdentifier.txid, outputIdentifier.outputIndex, output.topic)
+
+                // Make sure an output was found
+                if (!staleOutput) {
+                    return undefined
+                }
+
+                // Parse out the existing data, then concat the new outputs with no duplicates
+                if (staleOutput.consumedBy.length !== 0) {
+                    staleOutput.consumedBy = staleOutput.consumedBy.filter(x => x.txid !== output.txid && x.outputIndex !== output.outputIndex)
+                    // Update with the new consumedBy data
+                    await this.storage.updateConsumedBy(outputIdentifier.txid, outputIdentifier.outputIndex, output.topic, staleOutput.consumedBy)
+                }
+
+                // Find previousUTXO history
+                return await this.deleteUTXODeep(staleOutput)
+            })
+        } catch (error) {
+            throw new Error(`Failed to delete all stale outputs: ${error}`)
+        }
+    }
+
+    /**
+     * Find a list of supported topic managers
+     * @public
+     * @returns {Promise<string[]>} - array of supported topic managers
+     */
+    async listTopicManagers(): Promise<string[]> {
+        return Object.keys(this.managers)
+    }
+
+    /**
+     * Find a list of supported lookup services
+     * @public
+     * @returns {Promise<string[]>} - array of supported lookup services
+     */
+    async listLookupServiceProviders(): Promise<string[]> {
+        return Object.keys(this.lookupServices)
+    }
+
+    /**
+     * Run a query to get the documentation for a particular topic manager
+     * @public
+     * @returns {Promise<string>} - the documentation for the topic manager
+     */
+    async getDocumentationForTopicManger(manager: any): Promise<string> {
+        return this.managers[manager].getDocumentation?.() || 'No documentation found!'
+    }
+
+    /**
+     * Run a query to get the documentation for a particular lookup service
+     * @public
+     * @returns {Promise<string>} -  the documentation for the lookup service
+     */
+    async getDocumentationForLookupServiceProvider(provider: any): Promise<string> {
+        return this.lookupServices[provider].getDocumentation?.() || 'No documentation found!'
+    }
+}

package/src/LookupAnswer.ts

@@ -0,0 +1,14 @@
+/**
+ * How the Overlay Services Engine responds to a Lookup Question.
+ * 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: 'freeform',
+    result: unknown
+}

package/src/LookupFormula.ts

@@ -0,0 +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,
+
+    /**
+     * 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
+}[]