@bsv/sdk 1.7.7 → 1.8.1

package/src/kvstore/__tests/LocalKVStore.test.ts

@@ -481,6 +481,51 @@ describe('localKVStore', () => {
       })
       expect(mockWallet.relinquishOutput).not.toHaveBeenCalled()
     })
+
+    it('should preserve original error message when createAction fails', async () => {
+      const originalErrorMessage = 'Network connection timeout while creating transaction'
+      const originalError = new Error(originalErrorMessage)
+      
+      // Mock the lookupValue to return a value that differs from what we're setting
+      // to ensure set() will attempt to create a transaction
+      const mockedLor: ListOutputsResult = {
+        totalOutputs: 0,
+        outputs: [],
+        BEEF: undefined
+      }
+
+      const lookupValueReal = kvStore['lookupValue']
+      kvStore['lookupValue'] = jest.fn().mockResolvedValue({
+        value: 'different_value', // Different from testValue to trigger createAction
+        outpoint: undefined,
+        lor: mockedLor
+      })
+
+      // Mock wallet.createAction to fail with a specific error
+      mockWallet.createAction.mockRejectedValue(originalError)
+
+      // Mock other required methods
+      const valueArray = Array.from(testRawValueBuffer)
+      const encryptedArray = Array.from(testEncryptedValue)
+      MockedUtils.toArray.mockReturnValue(valueArray)
+      mockWallet.encrypt.mockResolvedValue({ ciphertext: encryptedArray } as WalletEncryptResult)
+
+      try {
+        await kvStore.set(testKey, testValue)
+        fail('Expected set() to throw an error but it succeeded')
+      } catch (error) {
+        // Verify that the thrown error contains both the contextual message and the original error
+        expect(error).toBeInstanceOf(Error)
+        const errorMessage = (error as Error).message
+        expect(errorMessage).toContain('outputs with tag')
+        expect(errorMessage).toContain('cannot be unlocked')
+        expect(errorMessage).toContain('Original error:')
+        expect(errorMessage).toContain(originalErrorMessage)
+      } finally {
+        // Restore the original method
+        kvStore['lookupValue'] = lookupValueReal
+      }
+    })
   })
 
   // --- Remove Method Tests ---
@@ -610,5 +655,32 @@ describe('localKVStore', () => {
       expect(mockWallet.signAction).toHaveBeenCalled() // Called but failed
 
     })
+
+    it('should preserve original error message when wallet operations fail during removal', async () => {
+      const originalErrorMessage = 'Insufficient funds to cover transaction fees'
+      const originalError = new Error(originalErrorMessage)
+      
+      const existingOutpoint = 'failTxId.0'
+      const existingOutput = { outpoint: existingOutpoint, txid: 'failTxId', vout: 0, lockingScript: 's1' }
+      const mockBEEF = Buffer.from('mockBEEFFail')
+
+      // Mock wallet to have outputs but createAction fails
+      mockWallet.listOutputs.mockResolvedValue({ outputs: [existingOutput], totalOutputs: 1, BEEF: mockBEEF } as any)
+      mockWallet.createAction.mockRejectedValue(originalError)
+
+      try {
+        await kvStore.remove(testKey)
+        fail('Expected remove() to throw an error but it succeeded')
+      } catch (error) {
+        // Verify that the thrown error contains both the contextual message and the original error
+        expect(error).toBeInstanceOf(Error)
+        const errorMessage = (error as Error).message
+        expect(errorMessage).toContain('1 outputs with tag')
+        expect(errorMessage).toContain(testKey)
+        expect(errorMessage).toContain('cannot be unlocked')
+        expect(errorMessage).toContain('Original error:')
+        expect(errorMessage).toContain(originalErrorMessage)
+      }
+    })
   })
 })

package/src/kvstore/kvStoreInterpreter.ts

@@ -0,0 +1,49 @@
+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].
+ * 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)
+
+    // Validate KVStore token format (must have 5 fields: [protocolID, key, value, controller, signature])
+    if (decoded.fields.length !== Object.keys(kvProtocol).length) 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/src/kvstore/types.ts

@@ -0,0 +1,114 @@
+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
+  /** 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
+  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
+}
+
+export interface KVStoreRemoveOptions {
+  protocolID?: WalletProtocol
+  tokenRemovalDescription?: string
+}
+
+/**
+ * KVStore entry returned from queries
+ */
+export interface KVStoreEntry {
+  key: string
+  value: string
+  controller: PubKeyHex
+  protocolID: WalletProtocol
+  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,
+  signature: 4
+}

package/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
+  }
+}