@bsv/wallet-toolbox 1.7.16 → 1.7.17

package/mobile/node_modules/@bsv/sdk/src/kvstore/kvStoreInterpreter.ts

@@ -1,54 +0,0 @@
-import { PushDrop } from '../script/index.js'
-import Transaction from '../transaction/Transaction.js'
-import * as Utils from '../primitives/utils.js'
-import { kvProtocol } from './types.js'
-import { InterpreterFunction } from '../overlay-tools/Historian.js'
-import { WalletProtocol } from '../wallet/Wallet.interfaces.js'
-
-export interface KVContext { key: string, protocolID: WalletProtocol }
-
-/**
- * KVStore interpreter used by Historian.
- *
- * Validates the KVStore PushDrop tokens: [protocolID, key, value, controller, signature] (old format)
- * or [protocolID, key, value, controller, tags, signature] (new format).
- * Filters outputs by the provided key in the interpreter context.
- * Produces the plaintext value for matching outputs; returns undefined otherwise.
- *
- * @param transaction - The transaction to inspect.
- * @param outputIndex - The index of the output within transaction.outputs.
- * @param ctx - { key: string, protocolID: WalletProtocol } — per-call context specifying which key to match.
- *
- * @returns string | undefined — the decoded KV value if the output is a valid KVStore token for the
- *   given key; otherwise undefined.
- */
-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
-
-    // Decode the KVStore token
-    const decoded = PushDrop.decode(output.lockingScript)
-
-    // Support backwards compatibility: old format without tags, new format with tags
-    const expectedFieldCount = Object.keys(kvProtocol).length
-    const hasTagsField = decoded.fields.length === expectedFieldCount
-    const isOldFormat = decoded.fields.length === expectedFieldCount - 1
-
-    if (!isOldFormat && !hasTagsField) return undefined
-
-    // Only return values for the given key and protocolID
-    const key = Utils.toUTF8(decoded.fields[kvProtocol.key])
-    const protocolID = Utils.toUTF8(decoded.fields[kvProtocol.protocolID])
-    if (key !== ctx.key || protocolID !== JSON.stringify(ctx.protocolID)) return undefined
-    try {
-      return Utils.toUTF8(decoded.fields[kvProtocol.value])
-    } catch {
-      return undefined
-    }
-  } catch {
-    // Skip non-KVStore outputs or malformed tokens
-    return undefined
-  }
-}

package/mobile/node_modules/@bsv/sdk/src/kvstore/types.ts

@@ -1,126 +0,0 @@
-import { Beef } from '../transaction/Beef.js'
-import { PubKeyHex, WalletProtocol } from '../wallet/Wallet.interfaces.js'
-import { WalletInterface } from '../wallet/index.js'
-
-/**
- * Configuration interface for GlobalKVStore operations.
- * Defines all options for connecting to overlay services and managing KVStore behavior.
- */
-export interface KVStoreConfig {
-  /** The overlay service host URL */
-  overlayHost?: string
-  /** Protocol ID for the KVStore protocol */
-  protocolID?: WalletProtocol
-  /** Service name for overlay submission */
-  serviceName?: string
-  /** Amount of satoshis for each token */
-  tokenAmount?: number
-  /** Topics for overlay submission */
-  topics?: string[]
-  /** Originator */
-  originator?: string
-  /** Wallet interface for operations */
-  wallet?: WalletInterface
-  /** Network preset for overlay services */
-  networkPreset?: 'mainnet' | 'testnet' | 'local'
-  /** Whether to accept delayed broadcast */
-  acceptDelayedBroadcast?: boolean
-  /** Whether to let overlay handle broadcasting (prevents UTXO spending on rejection) */
-  overlayBroadcast?: boolean
-  /** Description for token set */
-  tokenSetDescription?: string
-  /** Description for token update */
-  tokenUpdateDescription?: string
-  /** Description for token removal */
-  tokenRemovalDescription?: string
-}
-
-/**
- * Query parameters for KVStore lookups from overlay services.
- * Used when searching for existing key-value pairs in the network.
- */
-export interface KVStoreQuery {
-  key?: string
-  controller?: PubKeyHex
-  protocolID?: WalletProtocol
-  tags?: string[]
-  /**
-   * Controls tag matching behavior when tags are specified.
-   * - 'all': Requires all specified tags to be present (default)
-   * - 'any': Requires at least one of the specified tags to be present
-   */
-  tagQueryMode?: 'all' | 'any'
-  limit?: number
-  skip?: number
-  sortOrder?: 'asc' | 'desc'
-}
-
-/**
- * Options for configuring KVStore get operations (local processing)
- */
-export interface KVStoreGetOptions {
-  /** Whether to build and include history for each entry */
-  history?: boolean
-  /** Whether to include token transaction data in results */
-  includeToken?: boolean
-  /** Service name for overlay retrieval */
-  serviceName?: string
-}
-
-export interface KVStoreSetOptions {
-  protocolID?: WalletProtocol
-  tokenSetDescription?: string
-  tokenUpdateDescription?: string
-  tokenAmount?: number
-  tags?: string[]
-}
-
-export interface KVStoreRemoveOptions {
-  protocolID?: WalletProtocol
-  tokenRemovalDescription?: string
-}
-
-/**
- * KVStore entry returned from queries
- */
-export interface KVStoreEntry {
-  key: string
-  value: string
-  controller: PubKeyHex
-  protocolID: WalletProtocol
-  tags?: string[]
-  token?: KVStoreToken
-  history?: string[]
-}
-
-/**
- * Result structure for KVStore lookups from overlay services.
- * Contains the transaction output information for a found key-value pair.
- */
-export interface KVStoreLookupResult {
-  txid: string
-  outputIndex: number
-  outputScript: string
-  satoshis: number
-  history?: (output: any, currentDepth: number) => Promise<boolean>
-}
-
-/**
- * Token structure containing a KVStore token from overlay services.
- * Wraps the transaction data and metadata for a key-value pair.
- */
-export interface KVStoreToken {
-  txid: string
-  outputIndex: number
-  satoshis: number
-  beef: Beef
-}
-
-export const kvProtocol = {
-  protocolID: 0,
-  key: 1,
-  value: 2,
-  controller: 3,
-  tags: 4,
-  signature: 5 // Note: signature moves to position 5 when tags are present
-}

package/mobile/node_modules/@bsv/sdk/src/messages/EncryptedMessage.ts

@@ -1,74 +0,0 @@
-import PublicKey from '../primitives/PublicKey.js'
-import PrivateKey from '../primitives/PrivateKey.js'
-import SymmetricKey from '../primitives/SymmetricKey.js'
-import Random from '../primitives/Random.js'
-import { toBase64, toArray, Reader, toHex } from '../primitives/utils.js'
-
-const VERSION = '42421033'
-
-/**
- * Encrypts a message from one party to another using the BRC-78 message encryption protocol.
- * @param message The message to encrypt
- * @param sender The private key of the sender
- * @param recipient The public key of the recipient
- *
- * @returns The encrypted message
- */
-export const encrypt = (
-  message: number[],
-  sender: PrivateKey,
-  recipient: PublicKey
-): number[] => {
-  const keyID = Random(32)
-  const keyIDBase64 = toBase64(keyID)
-  const invoiceNumber = `2-message encryption-${keyIDBase64}`
-  const signingPriv = sender.deriveChild(recipient, invoiceNumber)
-  const recipientPub = recipient.deriveChild(sender, invoiceNumber)
-  const sharedSecret = signingPriv.deriveSharedSecret(recipientPub)
-  const symmetricKey = new SymmetricKey(sharedSecret.encode(true).slice(1))
-  const encrypted = symmetricKey.encrypt(message) as number[]
-  const senderPublicKey = sender.toPublicKey().encode(true)
-  const version = toArray(VERSION, 'hex')
-  return [
-    ...version,
-    ...senderPublicKey,
-    ...recipient.encode(true),
-    ...keyID,
-    ...encrypted
-  ]
-}
-
-/**
- * Decrypts a message from one party to another using the BRC-78 message encryption protocol.
- * @param message The message to decrypt
- * @param sender The private key of the recipient
- *
- * @returns The decrypted message
- */
-export const decrypt = (message: number[], recipient: PrivateKey): number[] => {
-  const reader = new Reader(message)
-  const messageVersion = toHex(reader.read(4))
-  if (messageVersion !== VERSION) {
-    throw new Error(
-      `Message version mismatch: Expected ${VERSION}, received ${messageVersion}`
-    )
-  }
-  const sender = PublicKey.fromString(toHex(reader.read(33)))
-  const expectedRecipientDER = toHex(reader.read(33))
-  const actualRecipientDER = recipient
-    .toPublicKey()
-    .encode(true, 'hex') as string
-  if (expectedRecipientDER !== actualRecipientDER) {
-    throw new Error(
-      `The encrypted message expects a recipient public key of ${expectedRecipientDER}, but the provided key is ${actualRecipientDER}`
-    )
-  }
-  const keyID = toBase64(reader.read(32))
-  const encrypted = reader.read(reader.bin.length - reader.pos)
-  const invoiceNumber = `2-message encryption-${keyID}`
-  const signingPriv = sender.deriveChild(recipient, invoiceNumber)
-  const recipientPub = recipient.deriveChild(sender, invoiceNumber)
-  const sharedSecret = signingPriv.deriveSharedSecret(recipientPub)
-  const symmetricKey = new SymmetricKey(sharedSecret.encode(true).slice(1))
-  return symmetricKey.decrypt(encrypted) as number[]
-}

package/mobile/node_modules/@bsv/sdk/src/messages/SignedMessage.ts

@@ -1,93 +0,0 @@
-// @ts-nocheck
-import PublicKey from '../primitives/PublicKey.js'
-import PrivateKey from '../primitives/PrivateKey.js'
-import Signature from '../primitives/Signature.js'
-import Curve from '../primitives/Curve.js'
-import Random from '../primitives/Random.js'
-import { toBase64, toArray, Reader, toHex } from '../primitives/utils.js'
-
-const VERSION = '42423301'
-
-/**
- * Signs a message from one party to be verified by another, or for verification by anyone, using the BRC-77 message signing protocol.
- * @param message The message to sign
- * @param signer The private key of the message signer
- * @param [verifier] The public key of the person who can verify the message. If not provided, anyone will be able to verify the message signature.
- *
- * @returns The message signature.
- */
-export const sign = (
-  message: number[],
-  signer: PrivateKey,
-  verifier?: PublicKey
-): number[] => {
-  const recipientAnyone = typeof verifier !== 'object'
-  if (recipientAnyone) {
-    const curve = new Curve()
-    const anyone = new PrivateKey(1)
-    const anyonePoint = curve.g.mul(anyone)
-    verifier = new PublicKey(anyonePoint.x, anyonePoint.y)
-  }
-  const keyID = Random(32)
-  const keyIDBase64 = toBase64(keyID)
-  const invoiceNumber = `2-message signing-${keyIDBase64}`
-  const signingKey = signer.deriveChild(verifier, invoiceNumber)
-  const signature = signingKey.sign(message).toDER()
-  const senderPublicKey = signer.toPublicKey().encode(true)
-  const version = toArray(VERSION, 'hex')
-  return [
-    ...version,
-    ...senderPublicKey,
-    ...(recipientAnyone ? [0] : verifier.encode(true)),
-    ...keyID,
-    ...signature
-  ]
-}
-
-/**
- * Verifies a message using the BRC-77 message signing protocol.
- * @param message The message to verify.
- * @param sig The message signature to be verified.
- * @param [recipient] The private key of the message verifier. This can be omitted if the message is verifiable by anyone.
- *
- * @returns True if the message is verified.
- */
-export const verify = (
-  message: number[],
-  sig: number[],
-  recipient?: PrivateKey
-): boolean => {
-  const reader = new Reader(sig)
-  const messageVersion = toHex(reader.read(4))
-  if (messageVersion !== VERSION) {
-    throw new Error(
-      `Message version mismatch: Expected ${VERSION}, received ${messageVersion}`
-    )
-  }
-  const signer = PublicKey.fromString(toHex(reader.read(33)))
-  const [verifierFirst] = reader.read(1)
-  if (verifierFirst === 0) {
-    recipient = new PrivateKey(1)
-  } else {
-    const verifierRest = reader.read(32)
-    const verifierDER = toHex([verifierFirst, ...verifierRest])
-    if (typeof recipient !== 'object') {
-      throw new Error(
-        `This signature can only be verified with knowledge of a specific private key. The associated public key is: ${verifierDER}`
-      )
-    }
-    const recipientDER = recipient.toPublicKey().encode(true, 'hex') as string
-    if (verifierDER !== recipientDER) {
-      throw new Error(
-        `The recipient public key is ${recipientDER} but the signature requres the recipient to have public key ${verifierDER}`
-      )
-    }
-  }
-  const keyID = toBase64(reader.read(32))
-  const signatureDER = toHex(reader.read(reader.bin.length - reader.pos))
-  const signature = Signature.fromDER(signatureDER, 'hex')
-  const invoiceNumber = `2-message signing-${keyID}`
-  const signingKey = signer.deriveChild(recipient, invoiceNumber)
-  const verified = signingKey.verify(message, signature)
-  return verified
-}

package/mobile/node_modules/@bsv/sdk/src/messages/__tests/EncryptedMessage.test.ts

@@ -1,61 +0,0 @@
-import { encrypt, decrypt } from '../../messages/EncryptedMessage'
-import PrivateKey from '../../primitives/PrivateKey'
-
-describe('EncryptedMessage', () => {
-  it('Encrypts a message for a recipient', () => {
-    const sender = new PrivateKey(15)
-    const recipient = new PrivateKey(21)
-    const recipientPub = recipient.toPublicKey()
-    const message = [1, 2, 4, 8, 16, 32]
-    const encrypted = encrypt(message, sender, recipientPub)
-    const decrypted = decrypt(encrypted, recipient)
-    expect(decrypted).toEqual(message)
-  })
-  it('Encrypts a message for a recipient with rare key length', () => {
-    const recipient = new PrivateKey(21)
-    {
-      // Rare length case... Leading zeros in key BigNumber array.
-      const encrypted = [
-        66, 66, 16, 51, 2, 215, 146, 77, 79, 125, 67, 234, 150, 90, 70, 90, 227,
-        9, 95, 244, 17, 49, 229, 148, 111, 60, 133, 247, 158, 68, 173, 188, 248,
-        226, 126, 8, 14, 2, 53, 43, 191, 74, 76, 221, 18, 86, 79, 147, 250, 51,
-        44, 227, 51, 48, 29, 154, 212, 2, 113, 248, 16, 113, 129, 52, 10, 239,
-        37, 190, 89, 213,
-
-        75, 148, 8, 235, 104, 137, 80, 129, 55, 68, 182, 141, 118, 212, 215,
-        121, 161, 107, 62, 247, 12, 172, 244, 170, 208, 37, 213, 198, 103, 118,
-        75, 166, 166, 131, 191, 105, 48, 232, 101, 223, 255, 169, 176, 204, 126,
-        249, 78, 178, 10, 51, 13, 163, 58, 232, 122, 111, 210, 218, 187, 247,
-        164, 101, 207, 15, 37, 227, 108, 82, 70, 35, 5, 148, 18, 162, 120, 64,
-        46, 40, 227, 197, 6, 112, 207, 200, 238, 81
-      ]
-      expect(() => decrypt(encrypted, recipient)).not.toThrow()
-    }
-  })
-  it('Fails to decrypt a message with wrong version', () => {
-    const sender = new PrivateKey(15)
-    const recipient = new PrivateKey(21)
-    const recipientPub = recipient.toPublicKey()
-    const message = [1, 2, 4, 8, 16, 32]
-    const encrypted = encrypt(message, sender, recipientPub)
-    encrypted[0] = 1
-    expect(() => decrypt(encrypted, recipient)).toThrow(
-      new Error(
-        'Message version mismatch: Expected 42421033, received 01421033'
-      )
-    )
-  })
-  it('Fails to decrypt a message with wrong recipient', () => {
-    const sender = new PrivateKey(15)
-    const recipient = new PrivateKey(21)
-    const wrongRecipient = new PrivateKey(22)
-    const recipientPub = recipient.toPublicKey()
-    const message = [1, 2, 4, 8, 16, 32]
-    const encrypted = encrypt(message, sender, recipientPub)
-    expect(() => decrypt(encrypted, wrongRecipient)).toThrow(
-      new Error(
-        'The encrypted message expects a recipient public key of 02352bbf4a4cdd12564f93fa332ce333301d9ad40271f8107181340aef25be59d5, but the provided key is 03421f5fc9a21065445c96fdb91c0c1e2f2431741c72713b4b99ddcb316f31e9fc'
-      )
-    )
-  })
-})

package/mobile/node_modules/@bsv/sdk/src/messages/__tests/SignedMessage.test.ts

@@ -1,59 +0,0 @@
-import { sign, verify } from '../../messages/SignedMessage'
-import PrivateKey from '../../primitives/PrivateKey'
-
-describe('SignedMessage', () => {
-  it('Signs a message for a recipient', () => {
-    const sender = new PrivateKey(15)
-    const recipient = new PrivateKey(21)
-    const recipientPub = recipient.toPublicKey()
-    const message = [1, 2, 4, 8, 16, 32]
-    const signature = sign(message, sender, recipientPub)
-    const verified = verify(message, signature, recipient)
-    expect(verified).toEqual(true)
-  })
-  it('Signs a message for anyone', () => {
-    const sender = new PrivateKey(15)
-    const message = [1, 2, 4, 8, 16, 32]
-    const signature = sign(message, sender)
-    const verified = verify(message, signature)
-    expect(verified).toEqual(true)
-  })
-  it('Fails to verify a message with a wrong version', () => {
-    const sender = new PrivateKey(15)
-    const recipient = new PrivateKey(21)
-    const recipientPub = recipient.toPublicKey()
-    const message = [1, 2, 4, 8, 16, 32]
-    const signature = sign(message, sender, recipientPub)
-    signature[0] = 1
-    expect(() => verify(message, signature, recipient)).toThrow(
-      new Error(
-        'Message version mismatch: Expected 42423301, received 01423301'
-      )
-    )
-  })
-  it('Fails to verify a message with no verifier when required', () => {
-    const sender = new PrivateKey(15)
-    const recipient = new PrivateKey(21)
-    const recipientPub = recipient.toPublicKey()
-    const message = [1, 2, 4, 8, 16, 32]
-    const signature = sign(message, sender, recipientPub)
-    expect(() => verify(message, signature)).toThrow(
-      new Error(
-        'This signature can only be verified with knowledge of a specific private key. The associated public key is: 02352bbf4a4cdd12564f93fa332ce333301d9ad40271f8107181340aef25be59d5'
-      )
-    )
-  })
-  it('Fails to verify a message with a wrong verifier', () => {
-    const sender = new PrivateKey(15)
-    const recipient = new PrivateKey(21)
-    const wrongRecipient = new PrivateKey(22)
-    const recipientPub = recipient.toPublicKey()
-    const message = [1, 2, 4, 8, 16, 32]
-    const signature = sign(message, sender, recipientPub)
-    expect(() => verify(message, signature, wrongRecipient)).toThrow(
-      new Error(
-        'The recipient public key is 03421f5fc9a21065445c96fdb91c0c1e2f2431741c72713b4b99ddcb316f31e9fc but the signature requres the recipient to have public key 02352bbf4a4cdd12564f93fa332ce333301d9ad40271f8107181340aef25be59d5'
-      )
-    )
-  })
-})

package/mobile/node_modules/@bsv/sdk/src/messages/index.ts

@@ -1,2 +0,0 @@
-export * as SignedMessage from './SignedMessage.js'
-export * as EncryptedMessage from './EncryptedMessage.js'

package/mobile/node_modules/@bsv/sdk/src/overlay-tools/Historian.ts

@@ -1,195 +0,0 @@
-import Transaction from '../transaction/Transaction.js'
-
-/**
- * Interpreter function signature used by Historian.
- *
- * Generics:
- * - T: The decoded/typed value produced for a matching output. Returning `undefined`
- *      means “this output does not contribute to history.”
- * - C: The per-call context passed through Historian to the interpreter. This carries
- *      any metadata needed to interpret outputs (e.g., `{ key: string }` for KVStore).
- *
- * Params:
- * - tx: The transaction containing the output to interpret.
- * - outputIndex: Index of the output within `tx.outputs`.
- * - ctx: Optional context object of type C, supplied at [Historian.buildHistory(startTx, context)]
- *
- * Returns:
- * - `T | undefined` (or a Promise thereof). `undefined` indicates a non-applicable or
- *   un-decodable output for the given context.
- */
-export type InterpreterFunction<T, C = unknown> =
-  (tx: Transaction, outputIndex: number, ctx?: C) => Promise<T | undefined> | T | undefined
-
-/**
- * Historian builds a chronological history (oldest → newest) of typed values by traversing
- * a transaction's input ancestry and interpreting each output with a provided interpreter.
- *
- * Core ideas:
- * - You provide an interpreter `(tx, outputIndex) => T | undefined` that decodes one output
- *   into your domain value (e.g., kvstore entries). If it returns `undefined`, that output
- *   contributes nothing to history.
- * - Traversal follows `Transaction.inputs[].sourceTransaction` recursively, so callers must
- *   supply transactions whose inputs have `sourceTransaction` populated (e.g., via overlay
- *   history reconstruction).
- * - The traversal visits each transaction once (cycle-safe) and collects interpreted values
- *   in reverse-chronological order, then returns them as chronological (oldest-first).
- * - Optional caching support: provide a `historyCache` Map to cache complete history results
- *   and avoid re-traversing identical transaction chains with the same context.
- *
- * Usage:
- * - Construct with an interpreter (and optional cache)
- * - Call historian.buildHistory(tx, context) to get an array of values representing the history of a token over time.
- *
- * Example:
- *   const cache = new Map() // Optional: for caching repeated queries
- *   const historian = new Historian(interpreter, { historyCache: cache })
- *   const history = await historian.buildHistory(tipTransaction, context)
- *   // history: T[] (e.g., prior values for a protected kvstore key)
- *
- * Caching:
- * - Cache keys are generated from `interpreterVersion|txid|contextKey`
- * - Cached results are immutable snapshots to prevent external mutation
- * - Bump `interpreterVersion` when interpreter semantics change to invalidate old cache entries
- */
-export class Historian<T, C = unknown> {
-  private readonly interpreter: InterpreterFunction<T, C>
-  private readonly debug: boolean
-
-  // --- minimal cache support ---
-  private readonly historyCache?: Map<string, readonly T[]>
-  private readonly interpreterVersion: string
-  private readonly ctxKeyFn: (ctx?: C) => string
-
-  /**
-   * Create a new Historian instance
-   *
-   * @param interpreter - Function to interpret transaction outputs into typed values
-   * @param options - Configuration options
-   * @param options.debug - Enable debug logging (default: false)
-   * @param options.historyCache - Optional external cache for complete history results
-   * @param options.interpreterVersion - Version identifier for cache invalidation (default: 'v1')
-   * @param options.ctxKeyFn - Custom function to serialize context for cache keys (default: JSON.stringify)
-   */
-  constructor (
-    interpreter: InterpreterFunction<T, C>,
-    options?: {
-      debug?: boolean
-      /** Optional cache for entire history results keyed by (version|txid|ctxKey) */
-      historyCache?: Map<string, readonly T[]>
-      /** Bump this if interpreter semantics change to invalidate cache */
-      interpreterVersion?: string
-      /** Deterministic, non-secret key for context. Default is JSON.stringify(ctx) */
-      ctxKeyFn?: (ctx?: C) => string
-    }
-  ) {
-    this.interpreter = interpreter
-    this.debug = options?.debug ?? false
-
-    // Configure caching (all optional)
-    this.historyCache = options?.historyCache
-    this.interpreterVersion = options?.interpreterVersion ?? 'v1'
-    this.ctxKeyFn = options?.ctxKeyFn ?? ((ctx?: C) => {
-      try { return JSON.stringify(ctx ?? null) } catch { return '' }
-    })
-  }
-
-  private historyKey (startTransaction: Transaction, context?: C): string {
-    const txid = startTransaction.id('hex')
-    const ctxKey = this.ctxKeyFn(context)
-    return `${this.interpreterVersion}|${txid}|${ctxKey}`
-  }
-
-  /**
-   * Build history by traversing input chain from a starting transaction
-   * Returns values in chronological order (oldest first)
-   *
-   * If caching is enabled, will first check for cached results matching the
-   * startTransaction and context. On cache miss, performs full traversal and
-   * stores the result for future queries.
-   *
-   * @param startTransaction - The transaction to start traversal from
-   * @param context - The context to pass to the interpreter
-   * @returns Array of interpreted values in chronological order
-   */
-  async buildHistory (startTransaction: Transaction, context?: C): Promise<T[]> {
-    // --- minimal cache fast path ---
-    if (this.historyCache != null) {
-      const cacheKey = this.historyKey(startTransaction, context)
-      if (this.historyCache.has(cacheKey)) {
-        const cached = this.historyCache.get(cacheKey)
-        if (cached != null) {
-          if (this.debug) console.log('[Historian] History cache hit:', cacheKey)
-          // Return a shallow copy to avoid external mutation of the cached array
-          return cached.slice()
-        }
-      }
-    }
-
-    const history: T[] = []
-    const visited = new Set<string>()
-
-    // Recursively traverse input transactions to build history
-    const traverseHistory = async (transaction: Transaction): Promise<void> => {
-      const txid = transaction.id('hex')
-
-      // Prevent infinite loops
-      if (visited.has(txid)) {
-        if (this.debug) {
-          console.log(`[Historian] Skipping already visited transaction: ${txid}`)
-        }
-        return
-      }
-      visited.add(txid)
-
-      if (this.debug) {
-        console.log(`[Historian] Processing transaction: ${txid}`)
-      }
-
-      // Check all outputs in this transaction for interpretable values
-      for (let outputIndex = 0; outputIndex < transaction.outputs.length; outputIndex++) {
-        try {
-          // Try to interpret this output
-          const interpretedValue = await Promise.resolve(this.interpreter(transaction, outputIndex, context))
-
-          if (interpretedValue !== undefined) {
-            history.push(interpretedValue)
-            if (this.debug) {
-              console.log('[Historian] Added value to history:', interpretedValue)
-            }
-          }
-        } catch (error) {
-          if (this.debug) {
-            console.log(`[Historian] Failed to interpret output ${outputIndex}:`, error)
-          }
-          // Skip outputs that can't be interpreted
-        }
-      }
-
-      // Recursively traverse input transactions
-      for (const input of transaction.inputs) {
-        if (input.sourceTransaction != null) {
-          await traverseHistory(input.sourceTransaction)
-        } else if (this.debug) {
-          console.log('[Historian] Input missing sourceTransaction, skipping')
-        }
-      }
-    }
-
-    // Start traversal from the provided transaction
-    await traverseHistory(startTransaction)
-
-    // History is built in reverse chronological order during traversal,
-    // so we reverse it to return oldest-first
-    const chronological = history.reverse()
-
-    if (this.historyCache != null) {
-      const cacheKey = this.historyKey(startTransaction, context)
-      // Store an immutable snapshot to avoid accidental external mutation
-      this.historyCache.set(cacheKey, Object.freeze(chronological.slice()))
-      if (this.debug) console.log('[Historian] History cached:', cacheKey)
-    }
-
-    return chronological
-  }
-}