@bsv/wallet-toolbox 1.7.13 → 1.7.15

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

@@ -0,0 +1,54 @@
+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

@@ -0,0 +1,126 @@
+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

@@ -0,0 +1,74 @@
+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

@@ -0,0 +1,93 @@
+// @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

@@ -0,0 +1,61 @@
+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

@@ -0,0 +1,59 @@
+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

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

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

@@ -0,0 +1,195 @@
+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
+  }
+}