@bsv/sdk 2.1.0 → 2.1.2

package/src/kvstore/GlobalKVStore.ts

@@ -146,7 +146,7 @@ export class GlobalKVStore {
       throw new Error('Key must be a non-empty string.')
     }
     if (typeof value !== 'string') {
-      throw new Error('Value must be a string.')
+      throw new TypeError('Value must be a string.')
     }
 
     const controller = await this.getIdentityKey()
@@ -186,7 +186,30 @@ export class GlobalKVStore {
         const existingEntries = await this.queryOverlay({ key, controller }, { includeToken: true })
         const existingToken = existingEntries.length > 0 ? existingEntries[0].token : undefined
 
-        if (existingToken != null) {
+        if (existingToken == null) {
+          // Create new token
+          const { tx } = await this.wallet.createAction({
+            description: tokenSetDescription,
+            outputs: [{
+              satoshis: tokenAmount ?? this.config.tokenAmount as number,
+              lockingScript: lockingScript.toHex(),
+              outputDescription: 'KVStore token'
+            }],
+            options: {
+              acceptDelayedBroadcast: this.config.acceptDelayedBroadcast,
+              noSend: this.config.overlayBroadcast,
+              randomizeOutputs: false
+            }
+          }, this.config.originator)
+
+          if (tx == null) {
+            throw new Error('Failed to create transaction')
+          }
+
+          const transaction = Transaction.fromAtomicBEEF(tx)
+          await this.submitToOverlay(transaction)
+          return `${transaction.id('hex')}.0`
+        } else {
           // Update existing token
           const inputs: CreateActionInput[] = [{
             outpoint: `${existingToken.txid}.${existingToken.outputIndex}`,
@@ -239,29 +262,6 @@ export class GlobalKVStore {
           const transaction = Transaction.fromAtomicBEEF(finalTx)
           await this.submitToOverlay(transaction)
           return `${transaction.id('hex')}.0`
-        } else {
-          // Create new token
-          const { tx } = await this.wallet.createAction({
-            description: tokenSetDescription,
-            outputs: [{
-              satoshis: tokenAmount ?? this.config.tokenAmount as number,
-              lockingScript: lockingScript.toHex(),
-              outputDescription: 'KVStore token'
-            }],
-            options: {
-              acceptDelayedBroadcast: this.config.acceptDelayedBroadcast,
-              noSend: this.config.overlayBroadcast,
-              randomizeOutputs: false
-            }
-          }, this.config.originator)
-
-          if (tx == null) {
-            throw new Error('Failed to create transaction')
-          }
-
-          const transaction = Transaction.fromAtomicBEEF(tx)
-          await this.submitToOverlay(transaction)
-          return `${transaction.id('hex')}.0`
         }
       }, this.topicBroadcaster)
 
@@ -421,9 +421,7 @@ export class GlobalKVStore {
    * @private
    */
   private async getIdentityKey (): Promise<PubKeyHex> {
-    if (this.cachedIdentityKey == null) {
-      this.cachedIdentityKey = (await this.wallet.getPublicKey({ identityKey: true }, this.config.originator)).publicKey
-    }
+    this.cachedIdentityKey ??= (await this.wallet.getPublicKey({ identityKey: true }, this.config.originator)).publicKey
     return this.cachedIdentityKey
   }
 
@@ -467,13 +465,13 @@ export class GlobalKVStore {
         const signature = decoded.fields.pop() as number[]
         try {
           await anyoneWallet.verifySignature({
-            data: decoded.fields.reduce((a, e) => [...a, ...e], []),
+            data: decoded.fields.flat(),
             signature,
             counterparty: Utils.toHex(decoded.fields[kvProtocol.controller]),
             protocolID: JSON.parse(Utils.toUTF8(decoded.fields[kvProtocol.protocolID])),
             keyID: Utils.toUTF8(decoded.fields[kvProtocol.key])
           })
-        } catch (error) {
+        } catch (_signatureVerificationError) {
           // Skip all outputs that fail signature verification
           continue
         }
@@ -483,7 +481,7 @@ export class GlobalKVStore {
         if (hasTagsField && decoded.fields[kvProtocol.tags] != null) {
           try {
             tags = JSON.parse(Utils.toUTF8(decoded.fields[kvProtocol.tags]))
-          } catch (e) {
+          } catch (_tagsParseError) {
             // If tags parsing fails, continue without tags
             tags = undefined
           }
@@ -514,7 +512,8 @@ export class GlobalKVStore {
         }
 
         entries.push(entry)
-      } catch (error) {
+      } catch (_malformedOutputError) {
+        // Skip malformed or undecodable outputs rather than failing the entire query
         continue
       }
     }

package/src/kvstore/LocalKVStore.ts

@@ -155,7 +155,7 @@ export default class LocalKVStore {
     if (outputs.length === 0) {
       return r
     }
-    const output = outputs.slice(-1)[0]
+    const output = outputs.at(-1)!
     r.outpoint = output.outpoint
     let field: number[]
     try {
@@ -169,23 +169,23 @@ export default class LocalKVStore {
     } catch (error) {
       throw new Error(`Invalid value found. You need to call set to collapse the corrupted state (or relinquish the corrupted ${outputs[0].outpoint} output from the ${this.context} basket) before you can get this value again. Original error: ${error instanceof Error ? error.message : String(error)}`)
     }
-    if (!this.encrypt) {
-      r.value = Utils.toUTF8(field)
-    } else {
+    if (this.encrypt) {
       const { plaintext } = await this.wallet.decrypt({
         ...this.getProtocol(key),
         ciphertext: field
       }, this.originator)
       r.value = Utils.toUTF8(plaintext)
+    } else {
+      r.value = Utils.toUTF8(field)
     }
     return r
   }
 
   private getInputs (outputs: WalletOutput[]): CreateActionInput[] {
     const inputs: CreateActionInput[] = []
-    for (let i = 0; i < outputs.length; i++) {
+    for (const output of outputs) {
       inputs.push({
-        outpoint: outputs[i].outpoint,
+        outpoint: output.outpoint,
         unlockingScriptLength: 74,
         inputDescription: 'Previous key-value token'
       })
@@ -197,7 +197,7 @@ export default class LocalKVStore {
     const p = this.getProtocol(key)
     const tx = Transaction.fromAtomicBEEF(atomicBEEF)
     const spends: Record<number, SignActionSpend> = {}
-    for (let i = 0; i < outputs.length; i++) {
+    for (const [i] of outputs.entries()) {
       const unlocker = pushdrop.unlock(p.protocolID, p.keyID, 'self')
       const unlockingScript = await unlocker.sign(tx, i)
       spends[i] = {
@@ -328,7 +328,7 @@ export default class LocalKVStore {
               }
             }, this.originator)
             if (typeof signableTransaction !== 'object') {
-              throw new Error('Wallet did not return a signable transaction when expected.')
+              throw new TypeError('Wallet did not return a signable transaction when expected.')
             }
             const spends = await this.getSpends(key, outputs, pushdrop, signableTransaction.tx)
             const { txid } = await this.wallet.signAction({

package/src/kvstore/kvStoreInterpreter.ts

@@ -25,8 +25,8 @@ export interface KVContext { key: string, protocolID: WalletProtocol }
 export const kvStoreInterpreter: InterpreterFunction<string, KVContext> = async (transaction: Transaction, outputIndex: number, ctx?: KVContext): Promise<string | undefined> => {
   try {
     const output = transaction.outputs[outputIndex]
-    if (output == null || output.lockingScript == null) return undefined
-    if (ctx == null || ctx.key == null) return undefined
+    if (output?.lockingScript == null) return undefined
+    if (ctx?.key == null) return undefined
 
     // Decode the KVStore token
     const decoded = PushDrop.decode(output.lockingScript)

package/src/messages/SignedMessage.ts

@@ -72,7 +72,7 @@ export const verify = (
     const verifierRest = reader.read(32)
     const verifierDER = toHex([verifierFirst, ...verifierRest])
     if (typeof recipient !== 'object') {
-      throw new Error(
+      throw new TypeError(
         `This signature can only be verified with knowledge of a specific private key. The associated public key is: ${verifierDER}`
       )
     }

package/src/overlay-tools/Historian.ts

@@ -181,7 +181,7 @@ export class Historian<T, C = unknown> {
 
     // History is built in reverse chronological order during traversal,
     // so we reverse it to return oldest-first
-    const chronological = history.reverse()
+    const chronological = history.toReversed()
 
     if (this.historyCache != null) {
       const cacheKey = this.historyKey(startTransaction, context)

package/src/overlay-tools/LookupResolver.ts

@@ -1,4 +1,5 @@
 import { Transaction } from '../transaction/index.js'
+import { Beef } from '../transaction/Beef.js'
 import OverlayAdminTokenTemplate from './OverlayAdminTokenTemplate.js'
 import * as Utils from '../primitives/utils.js'
 import { getOverlayHostReputationTracker, HostReputationTracker } from './HostReputationTracker.js'
@@ -35,9 +36,49 @@ export type LookupAnswer =
       beef: number[]
       outputIndex: number
       context?: number[]
+      /** Optional txid hint. When present, consumers can skip re-parsing beef to derive the txid. */
+      txid?: string
     }>
   }
 
+/**
+ * Per-call options for {@link LookupResolver.query} and {@link LookupResolver.query$}.
+ * All optional; defaults preserve prior behavior.
+ */
+export interface LookupQueryOptions {
+  /**
+   * Override the grace window (ms) between the first valid response and the resolution of the query.
+   * Late responders arriving within this window are merged into the result. Default 80 ms.
+   * Raise for identity-style paths (e.g. ~300 ms) where divergence between hosts matters.
+   */
+  graceMs?: number
+  /**
+   * Soft timeout (ms). When set:
+   *  - `query()` resolves with whatever has arrived as soon as any host answers, or after this timeout.
+   *  - `query$()` emits a (possibly empty) snapshot after this timeout if no host has answered yet,
+   *    then continues yielding late-host enrichments until the iterator is broken or final emission.
+   */
+  softTimeoutMs?: number
+}
+
+/**
+ * One emission from {@link LookupResolver.query$}. Carries the cumulative output set discovered so far
+ * plus a small envelope describing progress across hosts. Callers can render fast on the first emission
+ * and refine in place as more hosts answer.
+ */
+export interface LookupAnswerProgress {
+  type: 'output-list'
+  outputs: Array<{ beef: number[], outputIndex: number, context?: number[], txid?: string }>
+  /** Parallel array of resolved tx ids for each output (same index as `outputs`). */
+  txIds: string[]
+  /** True only for the final emission, after every in-flight host has settled. */
+  isFinal: boolean
+  /** Number of ranked hosts that were queried. */
+  hostCount: number
+  /** Number of hosts that have settled (success / fail / timeout). */
+  completedHosts: number
+}
+
 /** Default SLAP trackers */
 export const DEFAULT_SLAP_TRACKERS: string[] = [
   // BSVA clusters
@@ -119,7 +160,7 @@ export class HTTPSOverlayLookupFacilitator implements OverlayLookupFacilitator {
 
   constructor (httpClient = defaultFetch, allowHTTP: boolean = false) {
     if (typeof httpClient !== 'function') {
-      throw new Error(
+      throw new TypeError(
         'HTTPSOverlayLookupFacilitator requires a fetch implementation. ' +
         'In environments without fetch, provide a polyfill or custom implementation.'
       )
@@ -131,7 +172,7 @@ export class HTTPSOverlayLookupFacilitator implements OverlayLookupFacilitator {
   async lookup (
     url: string,
     question: LookupQuestion,
-    timeout: number = 5000
+    timeout: number = 2000
   ): Promise<LookupAnswer> {
     if (!url.startsWith('https:') && !this.allowHTTP) {
       throw new Error(
@@ -139,7 +180,7 @@ export class HTTPSOverlayLookupFacilitator implements OverlayLookupFacilitator {
       )
     }
 
-    const controller = typeof AbortController !== 'undefined' ? new AbortController() : undefined
+    const controller = typeof AbortController === 'undefined' ? undefined : new AbortController()
     const timer = setTimeout(() => {
       try { controller?.abort() } catch { /* noop */ }
     }, timeout)
@@ -158,44 +199,61 @@ export class HTTPSOverlayLookupFacilitator implements OverlayLookupFacilitator {
 
       if (!response.ok) throw new Error(`Failed to facilitate lookup (HTTP ${response.status})`)
       if (response.headers.get('content-type') === 'application/octet-stream') {
-        const payload = await response.arrayBuffer()
-        const r = new Utils.Reader([...new Uint8Array(payload)])
-        const nOutpoints = r.readVarIntNum()
-        const outpoints: Array<{ txid: string, outputIndex: number, context?: number[] }> = []
-        for (let i = 0; i < nOutpoints; i++) {
-          const txid = Utils.toHex(r.read(32))
-          const outputIndex = r.readVarIntNum()
-          const contextLength = r.readVarIntNum()
-          let context
-          if (contextLength > 0) {
-            context = r.read(contextLength)
-          }
-          outpoints.push({
-            txid,
-            outputIndex,
-            context
-          })
-        }
-        const beef = r.read()
-        return {
-          type: 'output-list',
-          outputs: outpoints.map(x => ({
-            outputIndex: x.outputIndex,
-            context: x.context,
-            beef: Transaction.fromBEEF(beef, x.txid).toBEEF()
-          }))
-        }
-      } else {
-        return await response.json()
+        return await this.parseOctetStreamLookup(response)
       }
+      return await response.json()
     } catch (e) {
       // Normalize timeouts to a consistent error message
-      if ((e as any)?.name === 'AbortError') throw new Error('Request timed out')
+      if ((e as { name?: string })?.name === 'AbortError') {
+        throw new Error('Request timed out')
+      }
       throw e
     } finally {
       clearTimeout(timer)
     }
   }
+
+  /** Parse the aggregated octet-stream lookup response into an output-list LookupAnswer. */
+  private async parseOctetStreamLookup (response: Response): Promise<LookupAnswer> {
+    const payload = await response.arrayBuffer()
+    const r = new Utils.Reader([...new Uint8Array(payload)])
+    const nOutpoints = r.readVarIntNum()
+    const outpoints: Array<{ txid: string, outputIndex: number, context?: number[] }> = []
+    for (let i = 0; i < nOutpoints; i++) {
+      const txid = Utils.toHex(r.read(32))
+      const outputIndex = r.readVarIntNum()
+      const contextLength = r.readVarIntNum()
+      const context = contextLength > 0 ? r.read(contextLength) : undefined
+      outpoints.push({ txid, outputIndex, context })
+    }
+    const beef = r.read()
+    const beefObj = Beef.fromBinary(beef)
+    const outputs = await this.extractAtomicOutputs(outpoints, beefObj)
+    return { type: 'output-list', outputs }
+  }
+
+  /** Memoize per-txid atomic BEEF extraction, yielding to the event loop between outputs. */
+  private async extractAtomicOutputs (
+    outpoints: Array<{ txid: string, outputIndex: number, context?: number[] }>,
+    beefObj: Beef
+  ): Promise<Array<{ outputIndex: number, context?: number[], beef: number[], txid: string }>> {
+    const beefByTxid = new Map<string, number[]>()
+    const outputs: Array<{ outputIndex: number, context?: number[], beef: number[], txid: string }> = new Array(outpoints.length)
+    for (let idx = 0; idx < outpoints.length; idx++) {
+      const x = outpoints[idx]
+      let beefBytes = beefByTxid.get(x.txid)
+      if (beefBytes === undefined) {
+        beefBytes = beefObj.toBinaryAtomic(x.txid)
+        beefByTxid.set(x.txid, beefBytes)
+      }
+      outputs[idx] = { outputIndex: x.outputIndex, context: x.context, beef: beefBytes, txid: x.txid }
+      // Yield to event loop so UI animations and other JS don't starve.
+      if (idx > 0 && idx < outpoints.length - 1) {
+        await new Promise<void>((resolve) => setTimeout(resolve, 0))
+      }
+    }
+    return outputs
+  }
 }
 
 /**
@@ -248,11 +306,53 @@ export default class LookupResolver {
 
   /**
    * Given a LookupQuestion, returns a LookupAnswer. Aggregates across multiple services and supports resiliency.
+   *
+   * Optional `options.graceMs` overrides the per-call grace window (default 80 ms).
+   * Optional `options.softTimeoutMs` resolves the query early with whatever has arrived once any host has
+   * answered (or with an empty result if no host has answered by `softTimeoutMs`).
    */
   async query (
     question: LookupQuestion,
-    timeout?: number
+    timeout?: number,
+    options?: LookupQueryOptions
   ): Promise<LookupAnswer> {
+    // Existing fast-but-narrow contract: return at the first cumulative emission
+    // (the post-grace aggregate, or the final emission when every host settles
+    // before the grace window). Callers wanting progressive enrichment use query$().
+    // Take only the first emission, then explicitly close the iterator so the
+    // generator's `finally` block runs and clears any outstanding timers.
+    const iter = this.query$(question, timeout, options)[Symbol.asyncIterator]()
+    let last: LookupAnswerProgress | null = null
+    try {
+      const { value, done } = await iter.next()
+      if (done !== true && value != null) last = value
+    } finally {
+      await iter.return?.(undefined)
+    }
+    return {
+      type: 'output-list',
+      outputs: last?.outputs ?? []
+    }
+  }
+
+  /**
+   * Iterable form of {@link query}. Emits partial results as hosts answer.
+   *
+   * Emission order:
+   *  - First emission: after the grace window expires (or as soon as the soft timeout elapses), containing
+   *    every output gathered from hosts that answered by then.
+   *  - Subsequent emissions: re-emitted whenever a late host returns extra outputs that weren't in earlier
+   *    emissions. Each emission contains the cumulative `outputs` set.
+   *  - Final emission: `isFinal: true` once all in-flight hosts have settled (success / fail / timeout). The
+   *    caller can `break` early; outstanding work is bounded by the per-host timeout.
+   *
+   * No host work runs past its per-host `timeout` — there is no leak risk on early break.
+   */
+  async * query$ (
+    question: LookupQuestion,
+    timeout?: number,
+    options?: LookupQueryOptions
+  ): AsyncIterable<LookupAnswerProgress> {
     let competentHosts: string[] = []
     if (question.service === 'ls_slap') {
       competentHosts = this.networkPreset === 'local' ? ['http://localhost:8080'] : this.slapTrackers
@@ -282,69 +382,116 @@ export default class LookupResolver {
       throw new Error(`All competent hosts for ${question.service} are temporarily unavailable due to backoff.`)
     }
 
-    // Fire all hosts; resolve as soon as we have results from any host,
-    // then allow a short grace window for additional hosts to contribute.
-    const GRACE_MS = 80
-    const answers: LookupAnswer[] = await new Promise<LookupAnswer[]>((resolve) => {
-      const collected: LookupAnswer[] = []
-      let pending = rankedHosts.length
-      let graceTimer: ReturnType<typeof setTimeout> | null = null
-
-      const tryResolve = (): void => {
-        if (graceTimer !== null) clearTimeout(graceTimer)
-        resolve(collected)
-      }
+    const graceMs = options?.graceMs ?? 80
+    const softTimeoutMs = options?.softTimeoutMs
 
-      for (const host of rankedHosts) {
-        this.lookupHostWithTracking(host, question, timeout)
-          .then((answer) => {
-            if (answer?.type === 'output-list' && Array.isArray(answer.outputs) && answer.outputs.length > 0) {
-              collected.push(answer)
-              // First valid response: start a grace window for others
-              if (collected.length === 1 && pending > 1) {
-                graceTimer = setTimeout(tryResolve, GRACE_MS)
-              }
-            }
-          })
-          .catch(() => { /* host failed; tracked by lookupHostWithTracking */ })
-          .finally(() => {
-            pending--
-            if (pending === 0) tryResolve()
-          })
+    const hostCount = rankedHosts.length
+    const outputsMap = new Map<string, { beef: number[], context?: number[], outputIndex: number }>()
+    const txIds: string[] = []
+    let completedHosts = 0
+    let firstResponseAt: number | null = null
+
+    type Event = { kind: 'answer', answer: LookupAnswer } | { kind: 'done' } | { kind: 'soft' }
+    const queue: Event[] = []
+    let waiter: ((v: void) => void) | null = null
+    const push = (e: Event): void => {
+      queue.push(e)
+      if (waiter !== null) {
+        const w = waiter
+        waiter = null
+        w()
       }
-    })
+    }
 
-    const outputsMap = new Map<string, { beef: number[], context?: number[], outputIndex: number }>()
+    for (const host of rankedHosts) {
+      this.lookupHostWithTracking(host, question, timeout)
+        .then((answer) => {
+          if (answer?.type === 'output-list' && Array.isArray(answer.outputs) && answer.outputs.length > 0) {
+            push({ kind: 'answer', answer })
+          }
+        })
+        .catch(() => { /* tracked already */ })
+        .finally(() => {
+          completedHosts++
+          push({ kind: 'done' })
+        })
+    }
 
-    // Memo key helper for tx parsing
-    const beefKey = (beef: number[]): string => {
-      if (typeof beef !== 'object') return '' // The invalid BEEF has an empty key.
-      return beef.join(',')
+    let softTimer: ReturnType<typeof setTimeout> | null = null
+    if (typeof softTimeoutMs === 'number' && softTimeoutMs >= 0) {
+      softTimer = setTimeout(() => push({ kind: 'soft' }), softTimeoutMs)
     }
 
-    for (const response of answers) {
-      for (const output of response.outputs) {
-        const keyForBeef = beefKey(output.beef)
-        let memo = this.txMemo.get(keyForBeef)
-        const now = Date.now()
-        if (typeof memo !== 'object' || memo === null || memo.expiresAt <= now) {
-          try {
-            const txId = Transaction.fromBEEF(output.beef).id('hex')
-            memo = { txId, expiresAt: now + this.txMemoTtlMs }
-            if (this.txMemo.size > 4096) this.evictOldest(this.txMemo)
-            this.txMemo.set(keyForBeef, memo)
-          } catch {
-            continue
-          }
+    let graceTimer: ReturnType<typeof setTimeout> | null = null
+    let graceFired = false
+    let emittedOnce = false
+
+    const mergeAnswer = (answer: LookupAnswer): boolean => {
+      let added = false
+      const now = Date.now()
+      for (const output of answer.outputs) {
+        const txId = this.resolveTxIdForOutput(output, now)
+        if (txId === null) continue
+        const uniqKey = `${txId}.${output.outputIndex}`
+        if (!outputsMap.has(uniqKey)) {
+          outputsMap.set(uniqKey, output)
+          txIds.push(txId)
+          added = true
         }
-
-        const uniqKey = `${memo.txId}.${output.outputIndex}`
-        outputsMap.set(uniqKey, output)
       }
+      return added
     }
-    return {
+
+    const snapshot = (isFinal: boolean): LookupAnswerProgress => ({
       type: 'output-list',
-      outputs: Array.from(outputsMap.values())
+      outputs: Array.from(outputsMap.values()),
+      txIds: txIds.slice(),
+      isFinal,
+      hostCount,
+      completedHosts
+    })
+
+    try {
+      while (completedHosts < hostCount) {
+        if (queue.length === 0) {
+          await new Promise<void>((resolve) => { waiter = resolve })
+        }
+        const e = queue.shift() as Event
+        if (e.kind === 'answer') {
+          const added = mergeAnswer(e.answer)
+          if (firstResponseAt === null) {
+            firstResponseAt = Date.now()
+            if (!graceFired && graceMs > 0) {
+              graceTimer = setTimeout(() => {
+                graceFired = true
+                push({ kind: 'soft' })
+              }, graceMs)
+            } else {
+              graceFired = true
+            }
+          }
+          if (graceFired && added) {
+            emittedOnce = true
+            yield snapshot(false)
+          }
+        } else if (e.kind === 'soft') {
+          if (!emittedOnce) {
+            graceFired = true
+            emittedOnce = true
+            yield snapshot(false)
+          }
+          if (typeof softTimeoutMs === 'number' && firstResponseAt !== null) {
+            // Soft timeout: caller asked to bail out once any answer is in. Yield final.
+            break
+          }
+        } else if (e.kind === 'done') {
+          // continue loop; final emission happens after the loop
+        }
+      }
+      yield snapshot(true)
+    } finally {
+      if (graceTimer !== null) clearTimeout(graceTimer)
+      if (softTimer !== null) clearTimeout(softTimer)
     }
   }
 
@@ -375,7 +522,7 @@ export default class LookupResolver {
       try {
         const hosts = await this.hostsInFlight.get(service)
         if (typeof hosts !== 'object') {
-          throw new Error('Hosts is not defined.')
+          throw new TypeError('Hosts is not defined.')
         }
         return hosts.slice()
       } catch {
@@ -466,7 +613,7 @@ export default class LookupResolver {
               resolve([...allHosts])
             }
           })
-          .catch(() => { /* tracker failed; tracked by lookupHostWithTracking */ })
+          .catch(() => { /* tracker failure tracked in reputation */ })
           .finally(() => {
             pending--
             if (pending === 0 && !resolved) {
@@ -478,7 +625,34 @@ export default class LookupResolver {
     })
   }
 
-  /** Evict an arbitrary “oldest” entry from a Map (iteration order). */
+  /**
+   * Resolve a txid for an aggregated lookup output. Uses the threaded-through `output.txid`
+   * fast path when present; otherwise memoizes Transaction.fromBEEF(beef).id('hex') keyed by
+   * the BEEF byte sequence. Returns null when the BEEF is unparseable.
+   */
+  private resolveTxIdForOutput (
+    output: { txid?: string, beef: number[], outputIndex: number, context?: number[] },
+    now: number
+  ): string | null {
+    if (typeof output.txid === 'string' && output.txid.length > 0) {
+      return output.txid
+    }
+    const keyForBeef = Array.isArray(output.beef) ? output.beef.join(',') : ''
+    const memo = this.txMemo.get(keyForBeef)
+    if (typeof memo === 'object' && memo !== null && memo.expiresAt > now) {
+      return memo.txId
+    }
+    try {
+      const txId = Transaction.fromBEEF(output.beef).id('hex')
+      if (this.txMemo.size > 4096) this.evictOldest(this.txMemo)
+      this.txMemo.set(keyForBeef, { txId, expiresAt: now + this.txMemoTtlMs })
+      return txId
+    } catch {
+      return null
+    }
+  }
+
+  /** Evict an arbitrary "oldest" entry from a Map (iteration order). */
   private evictOldest<T>(m: Map<string, T>): void {
     const firstKey = m.keys().next().value
     if (firstKey !== undefined) m.delete(firstKey)