@bsv/sdk 1.8.7 → 1.8.9

package/docs/reference/kvstore.md

@@ -169,6 +169,7 @@ export interface KVStoreEntry {
     value: string;
     controller: PubKeyHex;
     protocolID: WalletProtocol;
+    tags?: string[];
     token?: KVStoreToken;
     history?: string[];
 }
@@ -246,6 +247,8 @@ export interface KVStoreQuery {
     key?: string;
     controller?: PubKeyHex;
     protocolID?: WalletProtocol;
+    tags?: string[];
+    tagQueryMode?: "all" | "any";
     limit?: number;
     skip?: number;
     sortOrder?: "asc" | "desc";
@@ -254,6 +257,16 @@ export interface KVStoreQuery {
 
 See also: [PubKeyHex](./wallet.md#type-pubkeyhex), [WalletProtocol](./wallet.md#type-walletprotocol)
 
+#### Property tagQueryMode
+
+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
+
+```ts
+tagQueryMode?: "all" | "any"
+```
+
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
 ---
@@ -279,6 +292,7 @@ export interface KVStoreSetOptions {
     tokenSetDescription?: string;
     tokenUpdateDescription?: string;
     tokenAmount?: number;
+    tags?: string[];
 }
 ```
 
@@ -577,7 +591,8 @@ kvProtocol = {
     key: 1,
     value: 2,
     controller: 3,
-    signature: 4
+    tags: 4,
+    signature: 5
 }
 ```
 
@@ -595,7 +610,10 @@ kvStoreInterpreter: InterpreterFunction<string, KVContext> = async (transaction:
         if (ctx == null || ctx.key == null)
             return undefined;
         const decoded = PushDrop.decode(output.lockingScript);
-        if (decoded.fields.length !== Object.keys(kvProtocol).length)
+        const expectedFieldCount = Object.keys(kvProtocol).length;
+        const hasTagsField = decoded.fields.length === expectedFieldCount;
+        const isOldFormat = decoded.fields.length === expectedFieldCount - 1;
+        if (!isOldFormat && !hasTagsField)
             return undefined;
         const key = Utils.toUTF8(decoded.fields[kvProtocol.key]);
         const protocolID = Utils.toUTF8(decoded.fields[kvProtocol.protocolID]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "1.8.7",
+  "version": "1.8.9",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",

package/src/auth/transports/SimplifiedFetchTransport.ts

@@ -3,8 +3,10 @@
 import { AuthMessage, RequestedCertificateSet, Transport } from '../types.js'
 import * as Utils from '../../primitives/utils.js'
 
-// Only bind window.fetch in the browser
-const defaultFetch = typeof window !== 'undefined' ? fetch.bind(window) : fetch
+const defaultFetch: typeof fetch = 
+  typeof globalThis !== 'undefined' && typeof globalThis.fetch === 'function'
+    ? globalThis.fetch.bind(globalThis)
+    : fetch
 
 /**
  * Implements an HTTP-specific transport for handling Peer mutual authentication messages.
@@ -21,6 +23,12 @@ export class SimplifiedFetchTransport implements Transport {
    * @param fetchClient - A fetch implementation to use for HTTP requests (default: global fetch).
    */
   constructor (baseUrl: string, fetchClient = defaultFetch) {
+    if (typeof fetchClient !== 'function') {
+      throw new Error(
+        'SimplifiedFetchTransport requires a fetch implementation. ' +
+        'In environments without fetch, provide a polyfill or custom implementation.'
+      )
+    }
     this.fetchClient = fetchClient
     this.baseUrl = baseUrl
   }

package/src/kvstore/GlobalKVStore.ts

@@ -138,6 +138,7 @@ export class GlobalKVStore {
     const tokenSetDescription = (options.tokenSetDescription != null && options.tokenSetDescription !== '') ? options.tokenSetDescription : `Create KVStore value for ${key}`
     const tokenUpdateDescription = (options.tokenUpdateDescription != null && options.tokenUpdateDescription !== '') ? options.tokenUpdateDescription : `Update KVStore value for ${key}`
     const tokenAmount = options.tokenAmount ?? this.config.tokenAmount
+    const tags = options.tags ?? []
 
     try {
       // Check for existing token to spend
@@ -146,13 +147,20 @@ export class GlobalKVStore {
 
       // Create PushDrop locking script
       const pushdrop = new PushDrop(this.wallet, this.config.originator)
+      const lockingScriptFields = [
+        Utils.toArray(JSON.stringify(protocolID), 'utf8'),
+        Utils.toArray(key, 'utf8'),
+        Utils.toArray(value, 'utf8'),
+        Utils.toArray(controller, 'hex')
+      ]
+
+      // Add tags as optional 5th field for backwards compatibility
+      if (tags.length > 0) {
+        lockingScriptFields.push(Utils.toArray(JSON.stringify(tags), 'utf8'))
+      }
+
       const lockingScript = await pushdrop.lock(
-        [
-          Utils.toArray(JSON.stringify(protocolID), 'utf8'),
-          Utils.toArray(key, 'utf8'),
-          Utils.toArray(value, 'utf8'),
-          Utils.toArray(controller, 'hex')
-        ],
+        lockingScriptFields,
         protocolID ?? this.config.protocolID as WalletProtocol,
         Utils.toUTF8(Utils.toArray(key, 'utf8')),
         'anyone',
@@ -409,7 +417,12 @@ export class GlobalKVStore {
         const output = tx.outputs[result.outputIndex]
         const decoded = PushDrop.decode(output.lockingScript)
 
-        if (decoded.fields.length !== 5) {
+        // 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) {
           continue
         }
 
@@ -429,11 +442,23 @@ export class GlobalKVStore {
           continue
         }
 
+        // Extract tags if present (backwards compatible)
+        let tags: string[] | undefined
+        if (hasTagsField && decoded.fields[kvProtocol.tags] != null) {
+          try {
+            tags = JSON.parse(Utils.toUTF8(decoded.fields[kvProtocol.tags]))
+          } catch (e) {
+            // If tags parsing fails, continue without tags
+            tags = undefined
+          }
+        }
+
         const entry: KVStoreEntry = {
           key: Utils.toUTF8(decoded.fields[kvProtocol.key]),
           value: Utils.toUTF8(decoded.fields[kvProtocol.value]),
           controller: Utils.toHex(decoded.fields[kvProtocol.controller]),
-          protocolID: JSON.parse(Utils.toUTF8(decoded.fields[kvProtocol.protocolID]))
+          protocolID: JSON.parse(Utils.toUTF8(decoded.fields[kvProtocol.protocolID])),
+          tags
         }
 
         if (options.includeToken === true) {

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

@@ -287,6 +287,46 @@ describe('GlobalKVStore', () => {
         })
       })
 
+      it('returns entry with tags when token includes tags field', async () => {
+        primeResolverWithOneOutput(mockResolver)
+
+        const originalDecode = (MockPushDrop as any).decode
+        ;(MockPushDrop as any).decode = jest.fn().mockReturnValue({
+          fields: [
+            Array.from(Buffer.from(JSON.stringify([1, 'kvstore']))), // protocolID
+            Array.from(Buffer.from(TEST_KEY)), // key
+            Array.from(Buffer.from(TEST_VALUE)), // value
+            Array.from(Buffer.from(TEST_CONTROLLER, 'hex')), // controller
+            // tags field as JSON string so Utils.toUTF8 returns it directly
+            '["alpha","beta"]',
+            Array.from(Buffer.from('signature')) // signature
+          ]
+        })
+
+        const result = await kvStore.get({ key: TEST_KEY })
+
+        expect(Array.isArray(result)).toBe(true)
+        expect(result).toHaveLength(1)
+        if (Array.isArray(result) && result.length > 0) {
+          expect(result[0].tags).toEqual(['alpha', 'beta'])
+        }
+
+        ;(MockPushDrop as any).decode = originalDecode
+      })
+
+      it('omits tags when token is in old-format (no tags field)', async () => {
+        primeResolverWithOneOutput(mockResolver)
+
+        // primePushDropDecodeToValidValue() already sets old-format (no tags)
+        const result = await kvStore.get({ key: TEST_KEY })
+
+        expect(Array.isArray(result)).toBe(true)
+        expect(result).toHaveLength(1)
+        if (Array.isArray(result) && result.length > 0) {
+          expect(result[0].tags).toBeUndefined()
+        }
+      })
+
       it('returns entry with history when history=true', async () => {
         primeResolverWithOneOutput(mockResolver)
         mockHistorian.buildHistory.mockResolvedValue(['oldValue', TEST_VALUE])
@@ -320,6 +360,67 @@ describe('GlobalKVStore', () => {
         })
       })
 
+      it('forwards tags-only queries to the resolver', async () => {
+        primeResolverEmpty(mockResolver)
+
+        const tags = ['group:music', 'env:prod']
+        const result = await kvStore.get({ tags })
+
+        expect(Array.isArray(result)).toBe(true)
+        expect(mockResolver.query).toHaveBeenCalledWith({
+          service: 'ls_kvstore',
+          query: expect.objectContaining({ tags })
+        })
+      })
+
+      it('forwards tagQueryMode "all" to the resolver (default)', async () => {
+        primeResolverEmpty(mockResolver)
+
+        const tags = ['music', 'rock']
+        const result = await kvStore.get({ tags, tagQueryMode: 'all' })
+
+        expect(Array.isArray(result)).toBe(true)
+        expect(mockResolver.query).toHaveBeenCalledWith({
+          service: 'ls_kvstore',
+          query: expect.objectContaining({ 
+            tags,
+            tagQueryMode: 'all'
+          })
+        })
+      })
+
+      it('forwards tagQueryMode "any" to the resolver', async () => {
+        primeResolverEmpty(mockResolver)
+
+        const tags = ['music', 'jazz']
+        const result = await kvStore.get({ tags, tagQueryMode: 'any' })
+
+        expect(Array.isArray(result)).toBe(true)
+        expect(mockResolver.query).toHaveBeenCalledWith({
+          service: 'ls_kvstore',
+          query: expect.objectContaining({ 
+            tags,
+            tagQueryMode: 'any'
+          })
+        })
+      })
+
+      it('defaults to tagQueryMode "all" when not specified', async () => {
+        primeResolverEmpty(mockResolver)
+
+        const tags = ['category:news']
+        const result = await kvStore.get({ tags })
+
+        expect(Array.isArray(result)).toBe(true)
+        expect(mockResolver.query).toHaveBeenCalledWith({
+          service: 'ls_kvstore',
+          query: expect.objectContaining({ tags })
+        })
+        // Verify tagQueryMode is not explicitly set (will default to 'all' on server side)
+        const call = (mockResolver.query as jest.Mock).mock.calls[0][0]
+        expect(call.query.tagQueryMode).toBeUndefined()
+      })
+
       it('includes token data when includeToken=true for key queries', async () => {
         primeResolverWithOneOutput(mockResolver)
 
@@ -644,6 +745,34 @@ describe('GlobalKVStore', () => {
         expect(mockBroadcaster.broadcast).toHaveBeenCalled()
       })
 
+      it('includes tags field in locking script when options.tags provided', async () => {
+        primeResolverEmpty(mockResolver)
+
+        // Override PushDrop to capture the instance used within set()
+        const originalImpl = (MockPushDrop as any).mockImplementation
+        const mockLockingScript = { toHex: () => 'mockLockingScriptHex' }
+        const localPushDrop = {
+          lock: jest.fn().mockResolvedValue(mockLockingScript),
+          unlock: jest.fn().mockReturnValue({
+            sign: jest.fn().mockResolvedValue({ toHex: () => 'mockUnlockingScript' })
+          })
+        }
+        ;(MockPushDrop as any).mockImplementation(() => localPushDrop as any)
+
+        const providedTags = ['primary', 'news']
+        await kvStore.set(TEST_KEY, TEST_VALUE, { tags: providedTags })
+
+        // Validate PushDrop.lock was called with 5 fields (protocolID, key, value, controller, tags)
+        expect(localPushDrop.lock).toHaveBeenCalled()
+        const lockArgs = (localPushDrop.lock as jest.Mock).mock.calls[0]
+        const fields = lockArgs[0]
+        expect(Array.isArray(fields)).toBe(true)
+        expect(fields.length).toBe(5)
+
+        // Restore original implementation
+        ;(MockPushDrop as any).mockImplementation = originalImpl
+      })
+
       it('updates existing token when one exists', async () => {
         // Mock the queryOverlay to return an entry with a token
         const mockQueryOverlay = jest.spyOn(kvStore as any, 'queryOverlay')

package/src/kvstore/kvStoreInterpreter.ts

@@ -10,7 +10,8 @@ export interface KVContext { key: string, protocolID: WalletProtocol }
 /**
  * KVStore interpreter used by Historian.
  *
- * Validates the KVStore PushDrop tokens: [protocolID, key, value, controller, signature].
+ * 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.
  *
@@ -30,8 +31,12 @@ export const kvStoreInterpreter: InterpreterFunction<string, KVContext> = async
     // 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
+    // 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])

package/src/kvstore/types.ts

@@ -41,6 +41,13 @@ 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'
@@ -63,6 +70,7 @@ export interface KVStoreSetOptions {
   tokenSetDescription?: string
   tokenUpdateDescription?: string
   tokenAmount?: number
+  tags?: string[]
 }
 
 export interface KVStoreRemoveOptions {
@@ -78,6 +86,7 @@ export interface KVStoreEntry {
   value: string
   controller: PubKeyHex
   protocolID: WalletProtocol
+  tags?: string[]
   token?: KVStoreToken
   history?: string[]
 }
@@ -110,5 +119,6 @@ export const kvProtocol = {
   key: 1,
   value: 2,
   controller: 3,
-  signature: 4
+  tags: 4,
+  signature: 5 // Note: signature moves to position 5 when tags are present
 }

package/src/overlay-tools/LookupResolver.ts

@@ -2,8 +2,10 @@ import { Transaction } from '../transaction/index.js'
 import OverlayAdminTokenTemplate from './OverlayAdminTokenTemplate.js'
 import * as Utils from '../primitives/utils.js'
 
-// Only bind window.fetch in the browser
-const defaultFetch = typeof window !== 'undefined' ? fetch.bind(window) : fetch
+const defaultFetch: typeof fetch =
+  typeof globalThis !== 'undefined' && typeof globalThis.fetch === 'function'
+    ? globalThis.fetch.bind(globalThis)
+    : fetch
 
 /**
  * The question asked to the Overlay Services Engine when a consumer of state wishes to look up information.
@@ -113,6 +115,12 @@ export class HTTPSOverlayLookupFacilitator implements OverlayLookupFacilitator {
   allowHTTP: boolean
 
   constructor (httpClient = defaultFetch, allowHTTP: boolean = false) {
+    if (typeof httpClient !== 'function') {
+      throw new Error(
+        'HTTPSOverlayLookupFacilitator requires a fetch implementation. ' +
+        'In environments without fetch, provide a polyfill or custom implementation.'
+      )
+    }
     this.fetchClient = httpClient
     this.allowHTTP = allowHTTP
   }