@bsv/overlay 0.3.0 → 0.4.0

package/src/Engine.ts

@@ -114,12 +114,13 @@ export class Engine {
    * @param {TaggedBEEF} taggedBEEF - The transaction to process
    * @param {function(STEAK): void} [onSTEAKReady] - Optional callback function invoked when the STEAK is ready.
    * @param {string} mode — Indicates the submission behavior, whether historical or current. Historical transactions are not broadcast or propagated.
+   * @param {number[]} offChainValues — Values necessary to evaluate topical admittance that are not stored on-chain.
    *
    * The optional callback function should be used to get STEAK when ready, and avoid waiting for broadcast and transaction propagation to complete.
    *
    * @returns {Promise<STEAK>} The submitted transaction execution acknowledgement
    */
-  async submit (taggedBEEF: TaggedBEEF, onSteakReady?: (steak: STEAK) => void, mode: 'historical-tx' | 'current-tx' = 'current-tx'): Promise<STEAK> {
+  async submit (taggedBEEF: TaggedBEEF, onSteakReady?: (steak: STEAK) => void, mode: 'historical-tx' | 'current-tx' = 'current-tx', offChainValues?: number[]): Promise<STEAK> {
     for (const t of taggedBEEF.topics) {
       if (this.managers[t] === undefined || this.managers[t] === null) {
         throw new Error(`This server does not support this topic: ${t}`)
@@ -209,7 +210,8 @@ export class Engine {
                       unlockingScript: tx.inputs[inputIndex].unlockingScript!,
                       txid: output.txid,
                       outputIndex: output.outputIndex,
-                      topic
+                      topic,
+                      offChainValues
                     })
                   } else if (l.spendNotificationMode === 'whole-tx') {
                     await l.outputSpent({
@@ -217,7 +219,8 @@ export class Engine {
                       spendingAtomicBEEF: tx.toAtomicBEEF(),
                       txid: output.txid,
                       outputIndex: output.outputIndex,
-                      topic
+                      topic,
+                      offChainValues
                     })
                   } else { // none
                     await l.outputSpent({
@@ -243,7 +246,7 @@ export class Engine {
       const admissibleOutputsPromise = (async () => {
         try {
           this.startTime(`identifyAdmissibleOutputs_${txid.substring(0, 10)}`)
-          admissibleOutputs = await this.managers[topic].identifyAdmissibleOutputs(taggedBEEF.beef, previousCoins)
+          admissibleOutputs = await this.managers[topic].identifyAdmissibleOutputs(taggedBEEF.beef, previousCoins, offChainValues)
           this.endTime(`identifyAdmissibleOutputs_${txid.substring(0, 10)}`)
         } catch (_) {
           steak[topic] = { outputsToAdmit: [], coinsToRetain: [] }
@@ -372,14 +375,16 @@ export class Engine {
               outputIndex,
               lockingScript: tx.outputs[outputIndex].lockingScript,
               satoshis: tx.outputs[outputIndex].satoshis,
-              topic
+              topic,
+              offChainValues
             })
           } else {
             await l.outputAdmittedByTopic({
               mode: 'whole-tx',
               atomicBEEF: tx.toAtomicBEEF(),
               outputIndex,
-              topic
+              topic,
+              offChainValues
             })
           }
         }))
@@ -453,16 +458,9 @@ export class Engine {
     const lookupService = this.lookupServices[lookupQuestion.service]
     if (lookupService === undefined || lookupService === null) 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: Array<{ beef: number[], outputIndex: number }> = []
-
-    for (const { txid, outputIndex, history } of lookupResult) {
+    const lookupResult = await lookupService.lookup(lookupQuestion)
+    const hydratedOutputs: Array<{ beef: number[], outputIndex: number, context?: number[] }> = []
+    for (const { txid, outputIndex, history, context } of lookupResult) {
       // Make sure this is an unspent output (UTXO)
       const UTXO = await this.storage.findOutput(
         txid,
@@ -478,7 +476,8 @@ export class Engine {
       if (output?.beef !== undefined) {
         hydratedOutputs.push({
           beef: output.beef,
-          outputIndex: output.outputIndex
+          outputIndex: output.outputIndex,
+          context
         })
       }
     }

package/src/GASP/OverlayGASPStorage.ts

@@ -1,5 +1,5 @@
 import { GASPNode, GASPNodeResponse, GASPStorage } from '@bsv/gasp'
-import { MerklePath, Transaction } from '@bsv/sdk'
+import { MerklePath, Transaction, Utils } from '@bsv/sdk'
 import { Engine } from '../Engine.js'
 
 /**
@@ -90,7 +90,7 @@ export class OverlayGASPStorage implements GASPStorage {
 
     // Attempt to check if the current transaction is admissible
     parsedTx.merklePath = MerklePath.fromHex(tx.proof)
-    const admittanceResult = await this.engine.managers[this.topic].identifyAdmissibleOutputs(parsedTx.toBEEF(), [])
+    const admittanceResult = await this.engine.managers[this.topic].identifyAdmissibleOutputs(parsedTx.toBEEF(), [], typeof tx.txMetadata === 'string' ? Utils.toArray(tx.txMetadata) : undefined)
 
     if (admittanceResult.outputsToAdmit.includes(tx.outputIndex)) {
       // The transaction is admissible, no further inputs are needed

package/src/LookupFormula.ts

@@ -23,4 +23,9 @@ export type LookupFormula = Array<{
    * 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
+
+  /**
+   * Context for the UTXO, derived from the off-chain values.
+   */
+  context?: number[]
 }>

package/src/LookupService.ts

@@ -18,12 +18,14 @@ export type OutputAdmittedByTopic =
     topic: string // topic into which it was admitted
     satoshis: number // value of the output
     lockingScript: Script // script in this output
+    offChainValues?: number[] // off-chain values associated with the output
   }
   | { // «whole-tx» mode
     mode: 'whole-tx'
     atomicBEEF: number[] // whole transaction (Atomic BEEF)
     outputIndex: number
     topic: string
+    offChainValues?: number[]
   }
 
 /* ---------------------------------------------------------------------------
@@ -52,6 +54,7 @@ export type OutputSpent =
     inputIndex: number
     unlockingScript: Script
     sequenceNumber: number
+    offChainValues?: number[]
   }
   | { // «whole-tx»  – full spending TX
     mode: 'whole-tx'
@@ -59,6 +62,7 @@ export type OutputSpent =
     outputIndex: number
     topic: string
     spendingAtomicBEEF: number[]
+    offChainValues?: number[]
   }
 
 /* ---------------------------------------------------------------------------
@@ -121,7 +125,7 @@ export interface LookupService {
   /* -------------------------------------------------------------------------
    *  Query API
    * ----------------------------------------------------------------------- */
-  lookup: (question: LookupQuestion) => Promise<LookupAnswer | LookupFormula>
+  lookup: (question: LookupQuestion) => Promise<LookupFormula>
 
   /* -------------------------------------------------------------------------
    *  Documentation helpers

package/src/TopicManager.ts

@@ -9,13 +9,13 @@ export interface TopicManager {
    * 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>
+  identifyAdmissibleOutputs: (beef: number[], previousCoins: number[], offChainValues?: number[]) => Promise<AdmittanceInstructions>
 
   /**
    * Identifies and returns the inputs needed to anchor any topical outputs from this transaction to their associated previous history.
    * @throws - if there are no potentially valid topical outputs in this transaction
    */
-  identifyNeededInputs?: (beef: number[]) => Promise<Array<{ txid: string, outputIndex: number }>>
+  identifyNeededInputs?: (beef: number[], offChainValues?: number[]) => Promise<Array<{ txid: string, outputIndex: number }>>
 
   /**
   * Returns a Markdown-formatted documentation string for the topic manager.

package/src/__tests/Engine.test.ts

@@ -534,7 +534,7 @@ describe('BSV Overlay Services Engine', () => {
           beef: exampleBeef,
           topics: ['Hello']
         })
-        expect(engine.managers.Hello.identifyAdmissibleOutputs).toHaveBeenCalledWith(exampleBeef, [0])
+        expect(engine.managers.Hello.identifyAdmissibleOutputs).toHaveBeenCalledWith(exampleBeef, [0], undefined)
       })
       describe('When previous UTXOs were retained by the topic manager', () => {
         it('Notifies all lookup services about the output being spent (not deleted, see the comment about this in deleteUTXODeep)', async () => {