@bsv/overlay 2.0.3 → 2.1.0

package/src/GASP/OverlayGASPRemote.ts

@@ -30,7 +30,7 @@ export class OverlayGASPRemote implements GASPRemote {
 
     // Validate and return the response in the correct format
     if (!Array.isArray(result.UTXOList) || typeof result.since !== 'number') {
-      throw new Error('Invalid response format')
+      throw new TypeError('Invalid response format')
     }
 
     return {
@@ -77,7 +77,7 @@ export class OverlayGASPRemote implements GASPRemote {
 
     // Validate and return the response in the correct format
     if (typeof result.graphID !== 'string' || typeof result.rawTx !== 'string' || typeof result.outputIndex !== 'number') {
-      throw new Error('Invalid response format')
+      throw new TypeError('Invalid response format')
     }
 
     const gaspNode: GASPNode = {

package/src/GASP/OverlayGASPStorage.ts

@@ -14,7 +14,7 @@ export interface GraphNode {
   proof?: string
   txMetadata?: string
   outputMetadata?: string
-  inputs?: Record<string, { hash: string }> | undefined
+  inputs?: Record<string, { hash: string }>
   children: GraphNode[]
   parent?: GraphNode
 }
@@ -133,24 +133,20 @@ export class OverlayGASPStorage implements GASPStorage {
       typeof tx.txMetadata === 'string' ? Utils.toArray(tx.txMetadata) : undefined,
       'historical-tx'
     )
-    if (admittanceResult.outputsToAdmit.includes(tx.outputIndex)) {
-      // The transaction is admissible, no further inputs are needed
-    } else {
+    if (!admittanceResult.outputsToAdmit.includes(tx.outputIndex) && this.engine.managers[this.topic] !== undefined && typeof this.engine.managers[this.topic].identifyNeededInputs === 'function') {
       // The transaction is not admissible, get inputs needed for further verification
       // TopicManagers should implement a function to identify which inputs are needed.
-      if (this.engine.managers[this.topic] !== undefined && typeof this.engine.managers[this.topic].identifyNeededInputs === 'function') {
-        try {
-          const neededInputs = await this.engine.managers[this.topic].identifyNeededInputs?.(parsedTx.toBEEF()) ?? []
-          for (const input of neededInputs) {
-            response.requestedInputs[`${input.txid}.${input.outputIndex}`] = {
-              metadata: false
-            }
+      try {
+        const neededInputs = await this.engine.managers[this.topic].identifyNeededInputs?.(parsedTx.toBEEF()) ?? []
+        for (const input of neededInputs) {
+          response.requestedInputs[`${input.txid}.${input.outputIndex}`] = {
+            metadata: false
           }
-          return await this.stripAlreadyKnownInputs(response)
-        } catch (e) {
-          console.error(`An error occurred when identifying needed inputs for transaction: ${parsedTx.id('hex')}.${tx.outputIndex}!`)
-          // Cut off the graph in case of an error here.
         }
+        return await this.stripAlreadyKnownInputs(response)
+      } catch (e) {
+        console.error(`An error occurred when identifying needed inputs for transaction: ${parsedTx.id('hex')}.${tx.outputIndex}: ${e}`)
+        // Cut off the graph in case of an error here.
       }
       // By default, if the topic manager isn't able to stipulate needed inputs, only the inputs necessary for SPV are requested.
     }
@@ -162,7 +158,7 @@ export class OverlayGASPStorage implements GASPStorage {
    * Also terminates graphs if the response would be empty.
    */
   private async stripAlreadyKnownInputs (response: GASPNodeResponse | undefined): Promise<GASPNodeResponse | undefined> {
-    if (typeof response === 'undefined') {
+    if (response === undefined) {
       return response
     }
     for (const inputNodeId of Object.keys(response.requestedInputs)) {
@@ -217,14 +213,13 @@ export class OverlayGASPStorage implements GASPStorage {
       // Find the parent node based on spentBy
       const parentNode = this.temporaryGraphNodeRefs[spentBy]
 
-      if (parentNode !== undefined) {
-        // Set parent-child relationship
-        parentNode.children.push(newGraphNode)
-        newGraphNode.parent = parentNode
-        this.temporaryGraphNodeRefs[`${newGraphNode.txid}.${newGraphNode.outputIndex}`] = newGraphNode
-      } else {
+      if (parentNode === undefined) {
         throw new Error(`Parent node with GraphID ${spentBy} not found`)
       }
+      // Set parent-child relationship
+      parentNode.children.push(newGraphNode)
+      newGraphNode.parent = parentNode
+      this.temporaryGraphNodeRefs[`${newGraphNode.txid}.${newGraphNode.outputIndex}`] = newGraphNode
     }
   }
 

package/src/LookupService.ts

@@ -1,5 +1,6 @@
 import { LookupFormula } from './LookupFormula.js'
-import { Script, LookupQuestion, LookupAnswer } from '@bsv/sdk'
+import { Script, LookupQuestion } from '@bsv/sdk'
+
 
 /* ---------------------------------------------------------------------------
  *  Modes a Lookup Service may request from the Overlay Services Engine

package/src/__tests/BASM.test.ts

@@ -0,0 +1,44 @@
+import { computeBasmRoot, computeTac } from '../BASM'
+
+const ZERO = '0000000000000000000000000000000000000000000000000000000000000000'
+const TXID_1 = '0101010101010101010101010101010101010101010101010101010101010101'
+const TXID_2 = '0202020202020202020202020202020202020202020202020202020202020202'
+const TXID_3 = '0303030303030303030303030303030303030303030303030303030303030303'
+const BLOCK_HASH = '0404040404040404040404040404040404040404040404040404040404040404'
+
+describe('BRC-136 BASM helpers', () => {
+  it('computes the empty BASM root as 32 zero bytes', () => {
+    expect(computeBasmRoot([])).toBe(ZERO)
+  })
+
+  it('uses the single admitted txid as the BASM root', () => {
+    expect(computeBasmRoot([TXID_1])).toBe(TXID_1)
+  })
+
+  it('hashes two txids in internal byte order and returns display hex', () => {
+    expect(computeBasmRoot([TXID_1, TXID_2])).toBe(
+      'b4100303b9e99ada4b479b0bb93d9b549cb057a1c4be08896bc982debe20ce39'
+    )
+  })
+
+  it('duplicates the odd leaf in multi-layer BASM roots', () => {
+    expect(computeBasmRoot([TXID_1, TXID_2, TXID_3])).toBe(
+      'acbd47d5022a6c5e954ad677df8ec221c893f871889826df53f0f1ad3f023e22'
+    )
+  })
+
+  it('orders admitted refs by blockIndex instead of txid', () => {
+    const root = computeBasmRoot([
+      { txid: TXID_2, blockIndex: 20 },
+      { txid: TXID_1, blockIndex: 10 }
+    ])
+    expect(root).toBe('b4100303b9e99ada4b479b0bb93d9b549cb057a1c4be08896bc982debe20ce39')
+  })
+
+  it('chains TAC in internal byte order', () => {
+    const root = computeBasmRoot([TXID_1, TXID_2, TXID_3])
+    expect(computeTac(ZERO, BLOCK_HASH, root)).toBe(
+      'd0d3e770802c7c28ca1da59cc92263d59425f00e48d421ffebb02497b4702307'
+    )
+  })
+})

package/src/__tests/BASMChain.test.ts

@@ -0,0 +1,290 @@
+// Note: references Engine from dist due to compiled code references in Engine.ts
+// (matching Engine.test.ts).
+import { Engine } from '../../dist/cjs/src/Engine.js'
+import { computeBasmRoot, computeTac } from '../BASM'
+import type { AdmittedTxRef, TopicBlockAnchor } from '../BASM'
+
+const ZERO = '0000000000000000000000000000000000000000000000000000000000000000'
+const TXID_1 = '0101010101010101010101010101010101010101010101010101010101010101'
+const TXID_2 = '0202020202020202020202020202020202020202020202020202020202020202'
+
+/** Deterministic non-zero 32-byte hex block hash for a height. */
+const blockHashFor = (height: number): string => (height + 1).toString(16).padStart(64, '0')
+
+interface AppliedRow {
+  txid: string
+  topic: string
+  blockHeight?: number
+  blockHash?: string
+  blockIndex?: number
+  merkleRoot?: string
+  firstSeenHeight?: number
+  proven: boolean
+}
+
+interface FakeStore {
+  anchors: Map<string, TopicBlockAnchor>
+  admitted?: Map<number, AdmittedTxRef[]>
+  applied?: AppliedRow[]
+}
+
+function makeStorage (store: FakeStore): any {
+  const key = (topic: string, height: number): string => `${topic}:${height}`
+  return {
+    async findTopicAnchorTip (topic: string) {
+      let tip: TopicBlockAnchor | undefined
+      for (const anchor of store.anchors.values()) {
+        if (anchor.topic === topic && (tip === undefined || anchor.blockHeight > tip.blockHeight)) {
+          tip = anchor
+        }
+      }
+      return tip ?? { topic, blockHeight: -1, tac: ZERO }
+    },
+    async upsertTopicBlockAnchor (anchor: TopicBlockAnchor) {
+      store.anchors.set(key(anchor.topic, anchor.blockHeight), { ...anchor })
+    },
+    async findTopicBlockAnchor (topic: string, height: number) {
+      return store.anchors.get(key(topic, height))
+    },
+    async findTopicBlockAnchors (topic: string, fromHeight: number, toHeight: number) {
+      const result: TopicBlockAnchor[] = []
+      for (const anchor of store.anchors.values()) {
+        if (anchor.topic === topic && anchor.blockHeight >= fromHeight && anchor.blockHeight <= toHeight) {
+          result.push(anchor)
+        }
+      }
+      return result.sort((a, b) => a.blockHeight - b.blockHeight)
+    },
+    async findAdmittedTransactionsForBlock (topic: string, height: number) {
+      // Prefer deriving from proven applied rows so demotion is reflected.
+      if (store.applied !== undefined) {
+        return store.applied
+          .filter(r => r.proven && r.topic === topic && r.blockHeight === height && r.blockIndex !== undefined)
+          .sort((a, b) => (a.blockIndex ?? 0) - (b.blockIndex ?? 0))
+          .map(r => ({ txid: r.txid, blockIndex: r.blockIndex as number }))
+      }
+      return store.admitted?.get(height) ?? []
+    },
+    async findProvenAppliedTransactionsByBlockHash (blockHash: string) {
+      return (store.applied ?? [])
+        .filter(r => r.proven && r.blockHash?.toLowerCase() === blockHash.toLowerCase())
+        .map(r => ({ txid: r.txid, topic: r.topic, blockHeight: r.blockHeight as number }))
+    },
+    async findProvenAppliedTransactionsInRange (fromHeight: number, toHeight: number, topic?: string) {
+      return (store.applied ?? [])
+        .filter(r => r.proven && r.blockHeight !== undefined && r.blockHeight >= fromHeight && r.blockHeight <= toHeight && (topic === undefined || r.topic === topic))
+        .map(r => ({ txid: r.txid, topic: r.topic, blockHeight: r.blockHeight as number, blockHash: r.blockHash, merkleRoot: r.merkleRoot }))
+    },
+    async demoteAppliedTransactionToUnproven (txid: string, topic: string) {
+      const row = (store.applied ?? []).find(r => r.txid === txid && r.topic === topic)
+      if (row !== undefined) {
+        row.proven = false
+        row.blockHeight = undefined
+        row.blockHash = undefined
+        row.blockIndex = undefined
+        row.merkleRoot = undefined
+      }
+    }
+  }
+}
+
+function makeEngine (
+  store: FakeStore,
+  opts: { resolver?: (h: number) => Promise<{ blockHeight: number, blockHash: string }>, currentHeight?: number, isValidRootForHeight?: (root: string, height: number) => Promise<boolean> } = {}
+): Engine {
+  const managers = { tm_test: { identifyAdmissibleOutputs: jest.fn(), getDocumentation: async () => '', getMetaData: async () => ({ name: 'm', shortDescription: 's' }) } } as any
+  const resolver = opts.resolver ?? (async (blockHeight: number) => ({ blockHeight, blockHash: blockHashFor(blockHeight) }))
+  return new Engine(
+    managers,
+    {},
+    makeStorage(store),
+    { isValidRootForHeight: opts.isValidRootForHeight ?? (async () => true), currentHeight: async () => opts.currentHeight ?? 105 } as any,
+    'https://example.com',
+    undefined, undefined, undefined, undefined, undefined,
+    false, '[T] ', false, undefined as any, console, true,
+    resolver, false, 144
+  )
+}
+
+describe('BRC-136 BASM anchor chain continuity', () => {
+  it('extends the chain with empty anchors so the TAC never resets across blocks with no admitted txs', async () => {
+    const store: FakeStore = { anchors: new Map(), admitted: new Map() }
+
+    // Genesis: topic admits two txs at height 100.
+    store.admitted!.set(100, [
+      { txid: TXID_1, blockIndex: 0 },
+      { txid: TXID_2, blockIndex: 1 }
+    ])
+    const genesisRoot = computeBasmRoot(store.admitted!.get(100)!)
+    const genesisTac = computeTac(ZERO, blockHashFor(100), genesisRoot)
+    store.anchors.set('tm_test:100', {
+      topic: 'tm_test',
+      blockHeight: 100,
+      blockHash: blockHashFor(100),
+      basmRoot: genesisRoot,
+      admittedCount: 2,
+      tac: genesisTac
+    })
+
+    const engine = makeEngine(store)
+    await engine.advanceTopicAnchorChains(105)
+
+    // Every height 100..105 must have an anchor — no gaps.
+    for (let h = 100; h <= 105; h++) {
+      expect(store.anchors.get(`tm_test:${h}`)).toBeDefined()
+    }
+
+    // 101..105 are empty anchors (zero root, zero count) chained off genesis.
+    let expectedTac = genesisTac
+    for (let h = 101; h <= 105; h++) {
+      const anchor = store.anchors.get(`tm_test:${h}`)!
+      expect(anchor.basmRoot).toBe(ZERO)
+      expect(anchor.admittedCount).toBe(0)
+      expectedTac = computeTac(expectedTac, blockHashFor(h), ZERO)
+      expect(anchor.tac).toBe(expectedTac)
+    }
+
+    // The tip TAC is a cumulative hash that still depends on the genesis block —
+    // i.e. it was NOT reset to a per-block value.
+    const tipTac = store.anchors.get('tm_test:105')!.tac
+    const resetTac = computeTac(ZERO, blockHashFor(105), ZERO)
+    expect(tipTac).not.toBe(resetTac)
+  })
+})
+
+/** Replacement canonical block hash for height 101 after a reorg. */
+const H101_NEW = 'aaaa000000000000000000000000000000000000000000000000000000000000'
+
+/** Header resolver where height 101's canonical block hash is H101_NEW (post-reorg). */
+const reorgResolver = async (h: number): Promise<{ blockHeight: number, blockHash: string }> =>
+  ({ blockHeight: h, blockHash: h === 101 ? H101_NEW : blockHashFor(h) })
+
+/**
+ * Builds a topic with a proven admission at height 100 (TXID_1, stays canonical)
+ * and a proven admission at height 101 (TXID_2) in a block that will be orphaned.
+ */
+function seedTwoBlockChain (): FakeStore {
+  const applied: AppliedRow[] = [
+    { txid: TXID_1, topic: 'tm_test', blockHeight: 100, blockHash: blockHashFor(100), blockIndex: 0, merkleRoot: 'm100', firstSeenHeight: 100, proven: true },
+    { txid: TXID_2, topic: 'tm_test', blockHeight: 101, blockHash: blockHashFor(101), blockIndex: 0, merkleRoot: 'm101', firstSeenHeight: 101, proven: true }
+  ]
+  const root100 = computeBasmRoot([{ txid: TXID_1, blockIndex: 0 }])
+  const tac100 = computeTac(ZERO, blockHashFor(100), root100)
+  const root101 = computeBasmRoot([{ txid: TXID_2, blockIndex: 0 }])
+  const tac101 = computeTac(tac100, blockHashFor(101), root101)
+  const anchors = new Map<string, TopicBlockAnchor>()
+  anchors.set('tm_test:100', { topic: 'tm_test', blockHeight: 100, blockHash: blockHashFor(100), basmRoot: root100, admittedCount: 1, tac: tac100 })
+  anchors.set('tm_test:101', { topic: 'tm_test', blockHeight: 101, blockHash: blockHashFor(101), basmRoot: root101, admittedCount: 1, tac: tac101 })
+  return { anchors, applied }
+}
+
+describe('BRC-136 BASM reorg handling', () => {
+  it('demotes an orphaned-block tx to unproven and rebuilds the anchor over the canonical hash', async () => {
+    const store = seedTwoBlockChain()
+    // Reorg: height 101's block (blockHashFor(101)) is orphaned; the replacement
+    // canonical block at 101 (H101_NEW) does not re-include TXID_2.
+    const engine = makeEngine(store, { resolver: reorgResolver, currentHeight: 101 })
+
+    await (engine as any).handleReorg({
+      orphanedBlockHashes: [blockHashFor(101)],
+      rebuildFromHeight: 101,
+      newTipHeight: 101
+    })
+
+    // TXID_2 is demoted: no longer proven, block metadata cleared.
+    const row = store.applied!.find(r => r.txid === TXID_2)!
+    expect(row.proven).toBe(false)
+    expect(row.blockHeight).toBeUndefined()
+    // It survives as a receipt record (firstSeenHeight retained).
+    expect(row.firstSeenHeight).toBe(101)
+
+    // Anchor at 101 rebuilt: empty admitted set, canonical hash, recomputed TAC.
+    const anchor101 = store.anchors.get('tm_test:101')!
+    expect(anchor101.admittedCount).toBe(0)
+    expect(anchor101.basmRoot).toBe(ZERO)
+    expect(anchor101.blockHash).toBe(H101_NEW)
+    const tac100 = store.anchors.get('tm_test:100')!.tac
+    expect(anchor101.tac).toBe(computeTac(tac100, H101_NEW, ZERO))
+
+    // Height 100 is untouched.
+    const root100 = computeBasmRoot([{ txid: TXID_1, blockIndex: 0 }])
+    expect(store.anchors.get('tm_test:100')!.basmRoot).toBe(root100)
+  })
+
+  it('is idempotent: orphaned hashes matching no proven rows leave the chain unchanged', async () => {
+    const store = seedTwoBlockChain()
+    const engine = makeEngine(store, { currentHeight: 101 })
+    const before = store.anchors.get('tm_test:101')!.tac
+
+    await (engine as any).handleReorg({
+      orphanedBlockHashes: ['ffff000000000000000000000000000000000000000000000000000000000000'],
+      rebuildFromHeight: 101,
+      newTipHeight: 101
+    })
+
+    expect(store.applied!.find(r => r.txid === TXID_2)!.proven).toBe(true)
+    expect(store.anchors.get('tm_test:101')!.tac).toBe(before)
+  })
+
+  it('re-proving a demoted tx at a new height restores it to the admitted set', async () => {
+    const store = seedTwoBlockChain()
+    const engine = makeEngine(store, { resolver: reorgResolver, currentHeight: 101 })
+
+    await (engine as any).handleReorg({
+      orphanedBlockHashes: [blockHashFor(101)],
+      rebuildFromHeight: 101,
+      newTipHeight: 101
+    })
+    expect(store.anchors.get('tm_test:101')!.basmRoot).toBe(ZERO)
+
+    // TXID_2 re-mined into the new canonical block at 101.
+    const row = store.applied!.find(r => r.txid === TXID_2)!
+    row.proven = true
+    row.blockHeight = 101
+    row.blockHash = H101_NEW
+    row.blockIndex = 0
+    row.merkleRoot = 'm101new'
+
+    await (engine as any).handleReorg({
+      orphanedBlockHashes: [],
+      rebuildFromHeight: 101,
+      newTipHeight: 101
+    })
+
+    const anchor101 = store.anchors.get('tm_test:101')!
+    expect(anchor101.admittedCount).toBe(1)
+    expect(anchor101.basmRoot).toBe(computeBasmRoot([{ txid: TXID_2, blockIndex: 0 }]))
+    expect(anchor101.blockHash).toBe(H101_NEW)
+  })
+})
+
+describe('BRC-136 BASM reorg revalidation sweep', () => {
+  it('detects a stale proof root within the window and reorgs the affected height', async () => {
+    const store = seedTwoBlockChain()
+    // Height 101's proof root no longer validates (block orphaned); canonical
+    // header at 101 is now H101_NEW.
+    const isValidRootForHeight = async (root: string, height: number): Promise<boolean> => !(height === 101 && root === 'm101')
+    const engine = makeEngine(store, { resolver: reorgResolver, currentHeight: 101, isValidRootForHeight })
+
+    await (engine as any).revalidateRecentAnchors(3)
+
+    expect(store.applied!.find(r => r.txid === TXID_2)!.proven).toBe(false)
+    const anchor101 = store.anchors.get('tm_test:101')!
+    expect(anchor101.basmRoot).toBe(ZERO)
+    expect(anchor101.blockHash).toBe(H101_NEW)
+    // Height 100 still valid and untouched.
+    expect(store.applied!.find(r => r.txid === TXID_1)!.proven).toBe(true)
+    expect(store.anchors.get('tm_test:100')!.basmRoot).toBe(computeBasmRoot([{ txid: TXID_1, blockIndex: 0 }]))
+  })
+
+  it('leaves the chain unchanged when every proof in the window still validates', async () => {
+    const store = seedTwoBlockChain()
+    const engine = makeEngine(store, { currentHeight: 101, isValidRootForHeight: async () => true })
+    const before = store.anchors.get('tm_test:101')!.tac
+
+    await (engine as any).revalidateRecentAnchors(3)
+
+    expect(store.applied!.find(r => r.txid === TXID_2)!.proven).toBe(true)
+    expect(store.anchors.get('tm_test:101')!.tac).toBe(before)
+  })
+})

package/src/__tests/Engine.test.ts

@@ -470,7 +470,6 @@ describe('BSV Overlay Services Engine', () => {
           beef: exampleBeef,
           topics: ['Hello']
         })
-        expect(mockStorageEngine.doesAppliedTransactionExist).toReturnWith(Promise.resolve(true))
         expect(mockStorageEngine.findOutput).not.toHaveBeenCalled()
         expect(mockStorageEngine.markUTXOAsSpent).not.toHaveBeenCalled()
         expect(mockStorageEngine.insertOutput).not.toHaveBeenCalled()
@@ -758,10 +757,10 @@ describe('BSV Overlay Services Engine', () => {
         })
 
         // Test the tx is inserted
-        expect(mockStorageEngine.insertAppliedTransaction).toHaveBeenCalledWith({
+        expect(mockStorageEngine.insertAppliedTransaction).toHaveBeenCalledWith(expect.objectContaining({
           txid: exampleTXID,
           topic: 'Hello'
-        })
+        }))
       })
       it('Returns a correct set of admitted topics and outputs', async () => {
         // Mock findUTXO to return a UTXO
@@ -1010,7 +1009,7 @@ describe('BSV Overlay Services Engine', () => {
           mockOutput.outputIndex,
           0
         )
-        expect(mockedHistorySelector).toReturnWith(Promise.resolve(true))
+        expect(mockedHistorySelector).toHaveBeenCalled()
       })
       it('Returns undefined if history should not be traversed', async () => {
         const mockedHistorySelector = jest.fn(async (beef, outputIndex, currentDepth) => {

package/src/storage/Storage.ts

@@ -1,4 +1,10 @@
 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.
@@ -8,6 +14,45 @@ export interface AppliedTransaction {
   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 }>
 }
 
 /**
@@ -102,6 +147,17 @@ export interface Storage {
    */
   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
@@ -115,6 +171,77 @@ export interface Storage {
    */
   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