@bsv/overlay 2.2.1 → 2.3.0

package/src/__tests/OverlayGASPRemote.test.ts

@@ -1,135 +0,0 @@
-import { OverlayGASPRemote } from '../GASP/OverlayGASPRemote'
-import { GASPInitialRequest, GASPInitialResponse, GASPNode } from '@bsv/gasp'
-
-global.fetch = jest.fn(async () => {
-  await Promise.resolve({
-    ok: true,
-    status: 200,
-    json: async () => await Promise.resolve({})
-  })
-}
-) as jest.Mock
-
-describe('OverlayGASPRemote', () => {
-  let overlayRemote: OverlayGASPRemote
-
-  beforeEach(() => {
-    overlayRemote = new OverlayGASPRemote('http://example.com', 'tm_test');
-    (fetch as jest.Mock).mockClear()
-  })
-
-  describe('getInitialResponse', () => {
-    it('should send a request and return a valid response', async () => {
-      const mockRequest: GASPInitialRequest = { version: 1, since: 0 }
-      const mockResponse: GASPInitialResponse = {
-        UTXOList: [{ txid: 'txid1', outputIndex: 0, score: 0 }],
-        since: 1234567890
-      };
-
-      (fetch as jest.Mock).mockResolvedValue({
-        ok: true,
-        status: 200,
-        json: jest.fn().mockResolvedValue(mockResponse)
-      })
-
-      const response = await overlayRemote.getInitialResponse(mockRequest)
-
-      expect(fetch).toHaveBeenCalledWith('http://example.com/requestSyncResponse', {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'X-BSV-Topic': 'tm_test'
-        },
-        body: JSON.stringify(mockRequest)
-      })
-      expect(response).toEqual(mockResponse)
-    })
-
-    it('should throw an error if the response status is not OK', async () => {
-      const mockRequest: GASPInitialRequest = { version: 1, since: 0 };
-
-      (fetch as jest.Mock).mockResolvedValue({
-        ok: false,
-        status: 500
-      })
-
-      await expect(overlayRemote.getInitialResponse(mockRequest)).rejects.toThrow('HTTP error! Status: 500')
-    })
-
-    it('should throw an error if the response format is invalid', async () => {
-      const mockRequest: GASPInitialRequest = { version: 1, since: 0 }
-      const invalidResponse = { invalid: 'data' };
-
-      (fetch as jest.Mock).mockResolvedValue({
-        ok: true,
-        status: 200,
-        json: jest.fn().mockResolvedValue(invalidResponse)
-      })
-
-      await expect(overlayRemote.getInitialResponse(mockRequest)).rejects.toThrow('Invalid response format')
-    })
-  })
-
-  describe('requestNode', () => {
-    it('should send a request and return a valid GASPNode', async () => {
-      const graphID = 'graphID1'
-      const txid = 'txid1'
-      const outputIndex = 0
-      const metadata = true
-      const mockResponse: GASPNode = {
-        graphID,
-        rawTx: 'rawTxData',
-        outputIndex,
-        proof: 'proofData',
-        txMetadata: 'txMetadata',
-        outputMetadata: 'outputMetadata',
-        inputs: {}
-      };
-
-      (fetch as jest.Mock).mockResolvedValue({
-        ok: true,
-        status: 200,
-        json: jest.fn().mockResolvedValue(mockResponse)
-      })
-
-      const response = await overlayRemote.requestNode(graphID, txid, outputIndex, metadata)
-
-      expect(fetch).toHaveBeenCalledWith('http://example.com/requestForeignGASPNode', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ graphID, txid, outputIndex, metadata })
-      })
-      expect(response).toEqual(mockResponse)
-    })
-
-    it('should throw an error if the response status is not OK', async () => {
-      const graphID = 'graphID1'
-      const txid = 'txid1'
-      const outputIndex = 0
-      const metadata = true;
-
-      (fetch as jest.Mock).mockResolvedValue({
-        ok: false,
-        status: 500
-      })
-
-      await expect(overlayRemote.requestNode(graphID, txid, outputIndex, metadata)).rejects.toThrow('HTTP error! Status: 500')
-    })
-
-    it('should throw an error if the response format is invalid', async () => {
-      const graphID = 'graphID1'
-      const txid = 'txid1'
-      const outputIndex = 0
-      const metadata = true
-      const invalidResponse = { invalid: 'data' };
-
-      (fetch as jest.Mock).mockResolvedValue({
-        ok: true,
-        status: 200,
-        json: jest.fn().mockResolvedValue(invalidResponse)
-      })
-
-      await expect(overlayRemote.requestNode(graphID, txid, outputIndex, metadata)).rejects.toThrow('Invalid response format')
-    })
-  })
-})

package/src/__tests/OverlayGASPStorage.test.ts

@@ -1,205 +0,0 @@
-import { GraphNode, OverlayGASPStorage } from '../GASP/OverlayGASPStorage'
-import { Transaction, MerklePath } from '@bsv/sdk'
-import { GASPNode } from '@bsv/gasp'
-
-describe('OverlayGASPStorage', () => {
-  let overlayStorage: OverlayGASPStorage
-  let mockEngine: any
-
-  beforeEach(() => {
-    mockEngine = { storage: { findOutput: jest.fn(() => undefined), findUTXOsForTopic: jest.fn() }, managers: {} }
-    overlayStorage = new OverlayGASPStorage('test-topic', mockEngine)
-  })
-
-  describe('appendToGraph', () => {
-    it('should append a new node to an empty graph', async () => {
-      const mockTx = {
-        rawTx: '001122',
-        outputIndex: 0,
-        graphID: 'txid123.0'
-      }
-
-      // Use actual Transaction implementation
-      const parsedTx = Transaction.fromHex(mockTx.rawTx)
-
-      await overlayStorage.appendToGraph(mockTx)
-
-      expect(Object.keys(overlayStorage.temporaryGraphNodeRefs).length).toBe(1)
-      expect(overlayStorage.temporaryGraphNodeRefs['txid123.0'].txid).toBe(parsedTx.id('hex'))
-    })
-
-    it('throws error when max nodes are exceeded', async () => {
-      overlayStorage.maxNodesInGraph = 1
-      const graphNode: GraphNode = { txid: 'txid123', children: [], rawTx: '', graphID: 'txid4321.2', outputIndex: 0 }
-      overlayStorage.temporaryGraphNodeRefs['txid123.0'] = graphNode
-
-      const mockTx = {
-        rawTx: '334455',
-        outputIndex: 1,
-        graphID: 'txid234.1'
-      }
-
-      await expect(overlayStorage.appendToGraph(mockTx)).rejects.toThrow('The max number of nodes in transaction graph has been reached!')
-    })
-  })
-
-  describe('findKnownUTXOs', () => {
-    it('should return known UTXOs since a given timestamp', async () => {
-      const mockUTXOs = [{ txid: 'txid1', outputIndex: 0, score: 0 }, { txid: 'txid2', outputIndex: 1, score: 0 }]
-      mockEngine.storage.findUTXOsForTopic.mockResolvedValue(mockUTXOs)
-
-      const result = await overlayStorage.findKnownUTXOs(1234567890)
-
-      expect(result).toEqual([
-        { txid: 'txid1', outputIndex: 0, score: 0 },
-        { txid: 'txid2', outputIndex: 1, score: 0 }
-      ])
-      expect(mockEngine.storage.findUTXOsForTopic).toHaveBeenCalledWith('test-topic', 1234567890)
-    })
-
-    it('should handle errors correctly', async () => {
-      mockEngine.storage.findUTXOsForTopic.mockRejectedValue(new Error('Database error'))
-
-      await expect(overlayStorage.findKnownUTXOs(1234567890)).rejects.toThrow('Database error')
-    })
-  })
-
-  describe('hydrateGASPNode', () => {
-    it('should throw an error if no output is found', async () => {
-      await expect(overlayStorage.hydrateGASPNode('graphID', 'txid', 0, false)).rejects.toThrow('No matching output found!')
-    })
-    // TODO: Further test coverage
-  })
-
-  describe('findNeededInputs', () => {
-    // TODO: Write more complicated test cases
-    it('should return inputs needed for further verification when no proof is present', async () => {
-      const mockTx: GASPNode = {
-        rawTx: '001122',
-        proof: undefined,
-        graphID: 'txid123.0',
-        outputIndex: 0
-      }
-
-      const parsedTx = {
-        inputs: [{ sourceTXID: 'inputTxid1', sourceOutputIndex: 0 }],
-        toBEEF: jest.fn(),
-        id: jest.fn().mockReturnValue('txid123')
-      }
-      Transaction.fromHex = jest.fn().mockReturnValue(parsedTx)
-
-      const result = await overlayStorage.findNeededInputs(mockTx)
-
-      expect(result).toEqual({
-        requestedInputs: { 'inputTxid1.0': { metadata: false } }
-      })
-    })
-
-    it('should return inputs needed for further verification when proof is present', async () => {
-      const mockTx: GASPNode = {
-        rawTx: '001122',
-        proof: 'someproof',
-        graphID: 'txid123.0',
-        outputIndex: 0
-      }
-
-      const parsedTx = {
-        inputs: [{ sourceTXID: 'neededTxid', sourceOutputIndex: 1 }],
-        toBEEF: jest.fn(),
-        id: jest.fn().mockReturnValue('txid123'),
-        merklePath: {}
-      }
-      Transaction.fromHex = jest.fn().mockReturnValue(parsedTx)
-      MerklePath.fromHex = jest.fn().mockReturnValue(parsedTx.merklePath)
-
-      mockEngine.managers['test-topic'] = {
-        identifyAdmissibleOutputs: jest.fn().mockResolvedValue({
-          outputsToAdmit: []
-        }),
-        identifyNeededInputs: jest.fn().mockResolvedValue([{ txid: 'neededTxid', outputIndex: 1 }])
-      }
-
-      const result = await overlayStorage.findNeededInputs(mockTx)
-
-      expect(result).toEqual({
-        requestedInputs: { 'neededTxid.1': { metadata: false } }
-      })
-    })
-
-    it.each([
-      [new Error('manager failed'), 'manager failed'],
-      ['manager failed as a string', 'manager failed as a string']
-    ])('terminates the graph and logs normalized identifyNeededInputs errors', async (failure, message) => {
-      const mockTx: GASPNode = {
-        rawTx: '001122',
-        proof: 'someproof',
-        graphID: 'txid123.0',
-        outputIndex: 0
-      }
-      const parsedTx = {
-        inputs: [],
-        toBEEF: jest.fn().mockReturnValue([1, 2, 3]),
-        id: jest.fn().mockReturnValue('txid123'),
-        merklePath: {}
-      }
-      Transaction.fromHex = jest.fn().mockReturnValue(parsedTx)
-      MerklePath.fromHex = jest.fn().mockReturnValue(parsedTx.merklePath)
-      mockEngine.managers['test-topic'] = {
-        identifyAdmissibleOutputs: jest.fn().mockResolvedValue({
-          outputsToAdmit: []
-        }),
-        identifyNeededInputs: jest.fn().mockRejectedValue(failure)
-      }
-      const consoleError = jest.spyOn(console, 'error').mockImplementation(() => {})
-
-      await expect(overlayStorage.findNeededInputs(mockTx)).resolves.toBeUndefined()
-
-      expect(consoleError).toHaveBeenCalledWith(
-        `An error occurred when identifying needed inputs for transaction: txid123.0: ${message}`
-      )
-      consoleError.mockRestore()
-    })
-  })
-
-  describe('discardGraph', () => {
-    it('should discard the graph and its nodes', async () => {
-      const graphNode1: GraphNode = {
-        txid: 'txid123',
-        graphID: 'txid123.0',
-        rawTx: 'rawTxData',
-        outputIndex: 0,
-        children: [],
-        parent: undefined
-      }
-      overlayStorage.temporaryGraphNodeRefs['txid123.0'] = graphNode1
-
-      const parentNode: GraphNode = {
-        txid: 'txid123',
-        graphID: 'txid123.0',
-        rawTx: 'rawTxData',
-        outputIndex: 0,
-        children: []
-      }
-      const graphNode2: GraphNode = {
-        txid: 'txid124',
-        graphID: 'txid123.0',
-        rawTx: 'rawTxData',
-        outputIndex: 1,
-        children: [],
-        parent: parentNode
-      }
-      overlayStorage.temporaryGraphNodeRefs['txid124.0'] = graphNode2
-
-      await overlayStorage.discardGraph('txid123.0')
-
-      expect(overlayStorage.temporaryGraphNodeRefs['txid123.0']).toBeUndefined()
-      expect(overlayStorage.temporaryGraphNodeRefs['txid124.0']).toBeUndefined()
-    })
-  })
-
-  it('should handle non-existent graphID', async () => {
-    await overlayStorage.discardGraph('nonexistent.0')
-
-    expect(Object.keys(overlayStorage.temporaryGraphNodeRefs).length).toBe(0)
-  })
-})

package/src/storage/Storage.ts

@@ -1,260 +0,0 @@
-import type { Output } from '../Output.js'
-import type {
-  AdmittedTxRef,
-  RawTransactionRecord,
-  TopicAnchorTip,
-  TopicBlockAnchor
-} from '../BASM.js'
-
-/**
- * Represents a transaction that has been applied to a topic.
- */
-export interface AppliedTransaction {
-  /** TXID of the applied transaction */
-  txid: string
-  /** Output index of the applied transaction */
-  topic: string
-  /** Block height of the transaction proof, when known */
-  blockHeight?: number
-  /** Block hash for the proven transaction's block, when known */
-  blockHash?: string
-  /** Transaction's canonical in-block index, when known */
-  blockIndex?: number
-  /** Merkle root computed from the direct proof, when known */
-  merkleRoot?: string
-  /** Chain height when this transaction was first seen by this overlay */
-  firstSeenHeight?: number
-  /** Whether this applied transaction has a direct proof of inclusion */
-  proven?: boolean
-}
-
-export interface StoredTransactionRecord {
-  txid: string
-  beef?: number[]
-  rawTx?: number[]
-  merklePath?: number[]
-  blockHeight?: number
-  blockHash?: string
-  blockIndex?: number
-  merkleRoot?: string
-}
-
-export interface AppliedTransactionProofUpdate {
-  txid: string
-  topic: string
-  blockHeight: number
-  blockHash?: string
-  blockIndex?: number
-  merkleRoot?: string
-}
-
-export interface UnprovenAppliedTransactionCandidate {
-  txid: string
-  topic: string
-  firstSeenHeight?: number
-  outputs: Array<{ txid: string, outputIndex: number }>
-}
-
-/**
- * Defines the Storage Engine interface used internally by the Overlay Services Engine.
- */
-export interface Storage {
-  /**
-   * 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 (optional)
-   * @param spent — Whether the output must be spent to be returned (optional)
-   * @param includeBEEF — Whether to include the BEEF data for the output (optional)
-   */
-  findOutput: (txid: string, outputIndex: number, topic?: string, spent?: boolean, includeBEEF?: boolean) => Promise<Output | null>
-
-  /**
-   * Finds multiple outputs from storage by txid/output index pairs.
-   * Implementations can use this to collapse many point lookups into a single query.
-   * @param outpoints — txid/output index pairs to find
-   * @param includeBEEF — Whether to include the BEEF data for the outputs (optional)
-   */
-  findOutputsByOutpoints?: (
-    outpoints: Array<{ txid: string, outputIndex: number }>,
-    includeBEEF?: boolean
-  ) => Promise<Output[]>
-
-  /**
-   * Finds outputs with a matching transaction ID from storage
-   * @param txid — TXID of the outputs to find
-   * @param includeBEEF — Whether to include the BEEF data for the outputs (optional)
-   */
-  findOutputsForTransaction: (txid: string, includeBEEF?: boolean) => Promise<Output[]>
-
-  /**
-   * Finds current UTXOs that have been admitted into a given topic
-   * @param topic - The topic for which we want to find Unspent Transaction Outputs (UTXOs).
-   * @param since - Optional parameter indicating the minimum score value to retrieve matching UTXOs from. This is used for score-based filtering.
-   * @param limit - Optional parameter to limit the number of results returned
-   * @param includeBEEF — Whether to include the BEEF data for the outputs (optional)
-   * @returns A promise that resolves to an array of matching UTXOs.
-   */
-  findUTXOsForTopic: (topic: string, since?: number, limit?: number, includeBEEF?: boolean) => 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
-  */
-  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
-  */
-  updateConsumedBy: (txid: string, outputIndex: number, topic: string, consumedBy: Array<{
-    txid: string
-    outputIndex: number
-  }>) => Promise<void>
-
-  /**
-   * Updates the beef data for a transaction
-   * @param txid — TXID of the transaction to update
-   * @param beef - BEEF data to update
-   */
-  updateTransactionBEEF: (txid: string, beef: number[]) => Promise<void>
-
-  /**
-   * Updates the block height 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 blockHeight - height of the block the transaction associated with this output was included in
-   */
-  updateOutputBlockHeight?: (txid: string, outputIndex: number, topic: string, blockHeight: number) => Promise<void>
-
-  /**
-   * Upserts transaction-level data used for compact BEEF, raw-tx BASM fetches,
-   * and direct proof retrieval.
-   */
-  upsertTransactionRecord?: (record: StoredTransactionRecord) => Promise<void>
-
-  /**
-   * Updates direct proof metadata for an applied topic transaction.
-   */
-  updateAppliedTransactionProof?: (record: AppliedTransactionProofUpdate) => 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
-   */
-  doesAppliedTransactionExist: (tx: AppliedTransaction) => Promise<boolean>
-
-  /**
-   * Returns proven topic transactions admitted in one block, in canonical block order.
-   */
-  findAdmittedTransactionsForBlock?: (topic: string, blockHeight: number, blockHash?: string) => Promise<AdmittedTxRef[]>
-
-  /**
-   * Persists or replaces a topic block anchor for one height.
-   */
-  upsertTopicBlockAnchor?: (anchor: TopicBlockAnchor) => Promise<void>
-
-  /**
-   * Returns one topic block anchor.
-   */
-  findTopicBlockAnchor?: (topic: string, blockHeight: number, blockHash?: string) => Promise<TopicBlockAnchor | undefined>
-
-  /**
-   * Returns topic block anchors across a closed height range.
-   */
-  findTopicBlockAnchors?: (topic: string, fromHeight: number, toHeight: number) => Promise<TopicBlockAnchor[]>
-
-  /**
-   * Returns the latest known topic anchor tip.
-   */
-  findTopicAnchorTip?: (topic: string) => Promise<TopicAnchorTip | undefined>
-
-  /**
-   * Returns raw transactions for the requested txids.
-   */
-  findRawTransactions?: (txids: string[]) => Promise<RawTransactionRecord[]>
-
-  /**
-   * Returns direct Merkle paths for the requested txids.
-   */
-  findTransactionMerklePaths?: (txids: string[]) => Promise<Array<{
-    txid: string
-    merklePath: string
-    blockHeight?: number
-    blockHash?: string
-    blockIndex?: number
-    merkleRoot?: string
-  }>>
-
-  /**
-   * Finds topic-applied transactions with no direct proof old enough to evict.
-   */
-  findUnprovenAppliedTransactions?: (cutoffHeight: number, topic?: string) => Promise<UnprovenAppliedTransactionCandidate[]>
-
-  /**
-   * Deletes a topic-applied transaction record.
-   */
-  deleteAppliedTransaction?: (txid: string, topic: string) => Promise<void>
-
-  /**
-   * Returns proven topic-applied transactions whose proof anchors to the given
-   * block hash. Used to demote admissions when that block is reorged out.
-   */
-  findProvenAppliedTransactionsByBlockHash?: (blockHash: string) => Promise<Array<{ txid: string, topic: string, blockHeight: number }>>
-
-  /**
-   * Returns proven topic-applied transactions in a closed block-height range,
-   * including the proof's block hash and merkle root for revalidation sweeps.
-   */
-  findProvenAppliedTransactionsInRange?: (fromHeight: number, toHeight: number, topic?: string) => Promise<Array<{ txid: string, topic: string, blockHeight: number, blockHash?: string, merkleRoot?: string }>>
-
-  /**
-   * Demotes a proven applied transaction back to unproven: clears the block
-   * proof metadata and `proven` flag while retaining `firstSeenHeight`, so the
-   * "received" record survives until re-proof or unproven eviction.
-   */
-  demoteAppliedTransactionToUnproven?: (txid: string, topic: string) => Promise<void>
-
-  /**
-   * Updates the last interaction score for a given host and topic
-   * @param host — The host identifier
-   * @param topic — The topic for which to update the interaction score
-   * @param since — The score value to store
-   */
-  updateLastInteraction: (host: string, topic: string, since: number) => Promise<void>
-
-  /**
-   * Retrieves the last interaction score for a given host and topic
-   * @param host — The host identifier
-   * @param topic — The topic to query
-   * @returns The last interaction score, or 0 if not found
-   */
-  getLastInteraction: (host: string, topic: string) => Promise<number>
-}