@bsv/wallet-toolbox 1.7.16 → 1.7.17

package/mobile/node_modules/@bsv/sdk/src/kvstore/__tests/GlobalKVStore.test.ts

@@ -1,1104 +0,0 @@
-/** eslint-env jest */
-import GlobalKVStore from '../GlobalKVStore.js'
-import { WalletInterface, CreateActionResult, SignActionResult } from '../../wallet/Wallet.interfaces.js'
-import Transaction from '../../transaction/Transaction.js'
-import { Historian } from '../../overlay-tools/Historian.js'
-import { kvStoreInterpreter } from '../kvStoreInterpreter.js'
-import { PushDrop } from '../../script/index.js'
-import * as Utils from '../../primitives/utils.js'
-import { TopicBroadcaster, LookupResolver } from '../../overlay-tools/index.js'
-import { KVStoreConfig } from '../types.js'
-import { Beef } from '../../transaction/Beef.js'
-import { ProtoWallet } from '../../wallet/ProtoWallet.js'
-
-// --- Module mocks ------------------------------------------------------------
-jest.mock('../../transaction/Transaction.js')
-jest.mock('../../transaction/Beef.js')
-jest.mock('../../overlay-tools/Historian.js')
-jest.mock('../kvStoreInterpreter.js')
-jest.mock('../../script/index.js')
-jest.mock('../../primitives/utils.js')
-jest.mock('../../overlay-tools/index.js', () => {
-  const actual = jest.requireActual('../../overlay-tools/index.js')
-  return {
-    ...actual,
-    // Keep withDoubleSpendRetry as the real implementation
-    withDoubleSpendRetry: actual.withDoubleSpendRetry,
-    // Mock the classes
-    TopicBroadcaster: jest.fn(),
-    LookupResolver: jest.fn()
-  }
-})
-jest.mock('../../wallet/ProtoWallet.js')
-jest.mock('../../wallet/WalletClient.js')
-
-// --- Typed shortcuts to mocked classes --------------------------------------
-const MockTransaction = Transaction as jest.MockedClass<typeof Transaction>
-const MockBeef = Beef as jest.MockedClass<typeof Beef>
-const MockHistorian = Historian as jest.MockedClass<typeof Historian>
-const MockPushDrop = PushDrop as jest.MockedClass<typeof PushDrop>
-const MockUtils = Utils as jest.Mocked<typeof Utils>
-const MockTopicBroadcaster = TopicBroadcaster as jest.MockedClass<typeof TopicBroadcaster>
-const MockLookupResolver = LookupResolver as jest.MockedClass<typeof LookupResolver>
-const MockProtoWallet = ProtoWallet as jest.MockedClass<typeof ProtoWallet>
-
-// --- Test constants ----------------------------------------------------------
-const TEST_TXID =
-  '1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
-const TEST_CONTROLLER =
-  '02e3f2c4a5b6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3'
-const TEST_KEY = 'testKey'
-const TEST_VALUE = 'testValue'
-
-// --- Helpers ----------------------------------------------------------------
-type MTx = jest.Mocked<InstanceType<typeof Transaction>>
-type MBeef = jest.Mocked<InstanceType<typeof Beef>> & { findOutput: jest.Mock }
-type MHistorian = jest.Mocked<InstanceType<typeof Historian>>
-type MResolver = jest.Mocked<InstanceType<typeof LookupResolver>>
-type MBroadcaster = jest.Mocked<InstanceType<typeof TopicBroadcaster>>
-type MProtoWallet = jest.Mocked<InstanceType<typeof ProtoWallet>>
-
-function makeMockTx(): MTx {
-  return {
-    id: jest.fn().mockReturnValue(TEST_TXID),
-    // Only the properties used by GlobalKVStore are needed
-    outputs: [
-      {
-        lockingScript: {
-          toHex: jest.fn().mockReturnValue('mock_script'),
-          toArray: jest.fn().mockReturnValue([1, 2, 3]),
-        },
-        satoshis: 1,
-      },
-    ],
-    inputs: [],
-  } as any
-}
-
-function primeTransactionMocks(tx: MTx) {
-  ; (MockTransaction.fromAtomicBEEF as jest.Mock).mockReturnValue(tx)
-    ; (MockTransaction.fromBEEF as jest.Mock).mockReturnValue(tx)
-}
-
-function primeBeefMocks(beef: MBeef, tx: MTx) {
-  beef.toBinary.mockReturnValue(Array.from(new Uint8Array([1, 2, 3])))
-  beef.findTxid.mockReturnValue({ tx } as any)
-  beef.findOutput = jest.fn().mockReturnValue(tx.outputs[0] as any)
-  MockBeef.mockImplementation(() => beef)
-    ; (MockBeef as any).fromBinary = jest.fn().mockReturnValue(beef)
-}
-
-function primePushDropDecodeToValidValue() {
-  ; (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
-      Array.from(Buffer.from('signature')), // signature
-    ],
-  })
-}
-
-function primeUtilsDefaults() {
-  MockUtils.toUTF8.mockImplementation((arr: any) => {
-    if (typeof arr === 'string') return arr
-    if (!Array.isArray(arr)) return TEST_VALUE
-
-    // Check for protocolID field (JSON for [1,"kvstore"])
-    if (arr.join(',') === '91,49,44,34,107,118,115,116,111,114,101,34,93') {
-      return '[1,"kvstore"]'
-    }
-
-    // Check for key field (TEST_KEY as bytes)
-    const testKeyBytes = Array.from(Buffer.from(TEST_KEY))
-    if (arr.join(',') === testKeyBytes.join(',')) {
-      return TEST_KEY
-    }
-
-    // Default to TEST_VALUE for value field
-    return TEST_VALUE
-  })
-  MockUtils.toHex.mockImplementation((arr: any) => {
-    if (Array.isArray(arr) && arr.length > 0) {
-      return TEST_CONTROLLER
-    }
-    return 'mock_hex'
-  })
-  MockUtils.toBase64.mockReturnValue('dGVzdEtleQ==') // base64 of 'testKey'
-  MockUtils.toArray.mockReturnValue([1, 2, 3, 4])
-}
-
-function primeWalletMocks() {
-  return {
-    getPublicKey: jest.fn().mockResolvedValue({ publicKey: TEST_CONTROLLER }),
-    createAction: jest.fn().mockResolvedValue({
-      tx: Array.from(new Uint8Array([1, 2, 3])),
-      txid: TEST_TXID,
-      signableTransaction: {
-        tx: Array.from(new Uint8Array([1, 2, 3])),
-        reference: 'ref123',
-      },
-    } as CreateActionResult),
-    signAction: jest.fn().mockResolvedValue({
-      tx: Array.from(new Uint8Array([1, 2, 3])),
-      txid: TEST_TXID,
-    } as SignActionResult),
-  } as unknown as jest.Mocked<WalletInterface>
-}
-
-function primeResolverEmpty(resolver: MResolver) {
-  resolver.query.mockResolvedValue({ type: 'output-list', outputs: [] } as any)
-}
-
-function primeResolverWithOneOutput(resolver: MResolver) {
-  const mockOutput = {
-    beef: Array.from(new Uint8Array([1, 2, 3])),
-    outputIndex: 0,
-    context: Array.from(new Uint8Array([4, 5, 6])),
-  }
-  resolver.query.mockResolvedValue({
-    type: 'output-list',
-    outputs: [mockOutput],
-  } as any)
-}
-
-function primeResolverWithMultipleOutputs(resolver: MResolver, count: number = 3) {
-  const mockOutputs = Array.from({ length: count }, (_, i) => ({
-    beef: Array.from(new Uint8Array([1, 2, 3, i])),
-    outputIndex: i,
-    context: Array.from(new Uint8Array([4, 5, 6, i])),
-  }))
-  resolver.query.mockResolvedValue({
-    type: 'output-list',
-    outputs: mockOutputs,
-  } as any)
-}
-
-// --- Test suite --------------------------------------------------------------
-describe('GlobalKVStore', () => {
-  let kvStore: GlobalKVStore
-  let mockWallet: jest.Mocked<WalletInterface>
-  let mockHistorian: MHistorian
-  let mockResolver: MResolver
-  let mockBroadcaster: MBroadcaster
-  let mockBeef: MBeef
-  let mockProtoWallet: MProtoWallet
-  let tx: MTx
-
-  beforeEach(() => {
-    jest.clearAllMocks()
-
-    // Wallet
-    mockWallet = primeWalletMocks()
-
-    // Tx/BEEF
-    tx = makeMockTx()
-    primeTransactionMocks(tx)
-    mockBeef = {
-      toBinary: jest.fn(),
-      findTxid: jest.fn(),
-      findOutput: jest.fn(),
-    } as any
-    primeBeefMocks(mockBeef, tx)
-
-    // Historian
-    mockHistorian = {
-      buildHistory: jest.fn().mockResolvedValue([TEST_VALUE]),
-    } as any
-    MockHistorian.mockImplementation(() => mockHistorian)
-
-    // PushDrop lock/unlock plumbing
-    const mockLockingScript = { toHex: () => 'mockLockingScriptHex' }
-    const mockPushDrop = {
-      lock: jest.fn().mockResolvedValue(mockLockingScript),
-      unlock: jest.fn().mockReturnValue({
-        sign: jest.fn().mockResolvedValue({ toHex: () => 'mockUnlockingScript' }),
-      }),
-    }
-    MockPushDrop.mockImplementation(() => mockPushDrop as any)
-    primePushDropDecodeToValidValue()
-
-    // Utils
-    primeUtilsDefaults()
-
-    // Resolver / Broadcaster
-    mockResolver = {
-      query: jest.fn(),
-    } as any
-    MockLookupResolver.mockImplementation(() => mockResolver)
-    mockBroadcaster = {
-      broadcast: jest.fn().mockResolvedValue({ success: true }),
-    } as any
-    MockTopicBroadcaster.mockImplementation(() => mockBroadcaster)
-
-    // Proto wallet
-    mockProtoWallet = {
-      createHmac: jest.fn().mockResolvedValue({ hmac: new Uint8Array(32) }),
-      verifySignature: jest.fn().mockResolvedValue({ valid: true }),
-    } as any
-    MockProtoWallet.mockImplementation(() => mockProtoWallet)
-
-    // SUT
-    kvStore = new GlobalKVStore({ wallet: mockWallet })
-  })
-
-  // --------------------------------------------------------------------------
-  describe('Constructor', () => {
-    it('creates with default config', () => {
-      const store = new GlobalKVStore()
-      expect(store).toBeInstanceOf(GlobalKVStore)
-    })
-
-    it('creates with custom config', () => {
-      const config: KVStoreConfig = {
-        wallet: mockWallet,
-        protocolID: [2, 'custom'],
-        tokenAmount: 500,
-        networkPreset: 'testnet',
-      }
-      const store = new GlobalKVStore(config)
-      expect(store).toBeInstanceOf(GlobalKVStore)
-    })
-
-    it('initializes Historian with kvStoreInterpreter', () => {
-      expect(MockHistorian).toHaveBeenCalledWith(kvStoreInterpreter)
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  describe('get', () => {
-    describe('happy paths', () => {
-      it('returns empty array when key not found', async () => {
-        primeResolverEmpty(mockResolver)
-        const result = await kvStore.get({ key: TEST_KEY })
-        expect(Array.isArray(result)).toBe(true)
-        expect(result).toHaveLength(0)
-      })
-
-
-      it('returns KVStoreEntry when a valid token exists', async () => {
-        primeResolverWithOneOutput(mockResolver)
-
-        const result = await kvStore.get({ key: TEST_KEY, controller: TEST_CONTROLLER })
-
-        expect(result).toEqual({
-          key: TEST_KEY,
-          value: TEST_VALUE,
-          controller: expect.any(String),
-          protocolID: [1, 'kvstore']
-        })
-        expect(mockResolver.query).toHaveBeenCalledWith({
-          service: 'ls_kvstore',
-          query: expect.objectContaining({
-            key: TEST_KEY,
-            controller: TEST_CONTROLLER
-          })
-        })
-      })
-
-      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])
-
-        const result = await kvStore.get({ key: TEST_KEY, controller: TEST_CONTROLLER }, { history: true })
-
-        expect(result).toEqual({
-          key: TEST_KEY,
-          value: TEST_VALUE,
-          controller: expect.any(String),
-          protocolID: [1, 'kvstore'],
-          history: ['oldValue', TEST_VALUE]
-        })
-        expect(mockHistorian.buildHistory).toHaveBeenCalledWith(
-          expect.any(Object),
-          expect.objectContaining({ key: TEST_KEY })
-        )
-      })
-
-      it('supports querying by protocolID', async () => {
-        primeResolverWithOneOutput(mockResolver)
-
-        const result = await kvStore.get({ protocolID: [1, 'kvstore'] })
-
-        expect(Array.isArray(result)).toBe(true)
-        expect(mockResolver.query).toHaveBeenCalledWith({
-          service: 'ls_kvstore',
-          query: expect.objectContaining({
-            protocolID: [1, 'kvstore']
-          })
-        })
-      })
-
-      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)
-
-        const result = await kvStore.get({ key: TEST_KEY }, { includeToken: true })
-
-        expect(Array.isArray(result)).toBe(true)
-        expect(result).toHaveLength(1)
-        if (Array.isArray(result) && result.length > 0) {
-          expect(result[0].token).toBeDefined()
-          expect(result[0].token).toEqual({
-            txid: TEST_TXID,
-            outputIndex: 0,
-            satoshis: 1,
-            beef: expect.any(Object)
-          })
-        }
-      })
-
-      it('includes token data when includeToken=true for protocolID queries', async () => {
-        primeResolverWithOneOutput(mockResolver)
-
-        const result = await kvStore.get({ protocolID: [1, 'kvstore'] }, { includeToken: true })
-
-        expect(Array.isArray(result)).toBe(true)
-        if (Array.isArray(result) && result.length > 0) {
-          expect(result[0].token).toBeDefined()
-          expect(result[0].token).toEqual({
-            txid: TEST_TXID,
-            outputIndex: 0,
-            satoshis: 1,
-            beef: expect.any(Object)
-          })
-        }
-      })
-
-      it('excludes token data when includeToken=false (default)', async () => {
-        primeResolverWithOneOutput(mockResolver)
-
-        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].token).toBeUndefined()
-        }
-      })
-
-      it('supports protocolID queries with history', async () => {
-        primeResolverWithOneOutput(mockResolver)
-        mockHistorian.buildHistory.mockResolvedValue(['oldValue', TEST_VALUE])
-
-        const result = await kvStore.get({ protocolID: [1, 'kvstore'] }, { history: true })
-
-        expect(Array.isArray(result)).toBe(true)
-        if (Array.isArray(result) && result.length > 0) {
-          expect(result[0].history).toEqual(['oldValue', TEST_VALUE])
-        }
-        expect(mockHistorian.buildHistory).toHaveBeenCalled()
-      })
-
-      it('excludes history for protocolID queries when history=false', async () => {
-        primeResolverWithOneOutput(mockResolver)
-
-        const result = await kvStore.get({ protocolID: [1, 'kvstore'] }, { history: false })
-
-        expect(Array.isArray(result)).toBe(true)
-        if (Array.isArray(result) && result.length > 0) {
-          expect(result[0].history).toBeUndefined()
-        }
-        expect(mockHistorian.buildHistory).not.toHaveBeenCalled()
-      })
-
-      it('calls buildHistory for each valid token when multiple outputs exist', async () => {
-        // This test verifies the key behavior: history building is called for each processed token
-        primeResolverWithMultipleOutputs(mockResolver, 3)
-
-        // Don't worry about making unique tokens - just verify the calls
-        mockHistorian.buildHistory.mockResolvedValue(['sample_history'])
-
-        const result = await kvStore.get({ protocolID: [1, 'kvstore'] }, { history: true })
-
-        expect(Array.isArray(result)).toBe(true)
-
-        // The key assertion: buildHistory should be called once per valid token processed
-        // Even if some tokens are duplicates due to mocking, we're testing the iteration logic
-        expect(mockHistorian.buildHistory).toHaveBeenCalledWith(
-          expect.any(Object),
-          expect.objectContaining({ key: expect.any(String) })
-        )
-
-        // Since we have 3 outputs but they may resolve to the same token due to mocking,
-        // we just verify that buildHistory was called at least once
-        expect(mockHistorian.buildHistory).toHaveBeenCalled()
-
-        // Verify each returned entry has history
-        if (Array.isArray(result)) {
-          result.forEach(entry => {
-            expect(entry.history).toEqual(['sample_history'])
-          })
-        }
-      })
-
-      it('handles history building failures gracefully', async () => {
-        primeResolverWithOneOutput(mockResolver)
-
-        // Mock history building to fail
-        mockHistorian.buildHistory.mockRejectedValue(new Error('History build failed'))
-
-        const result = await kvStore.get({ protocolID: [1, 'kvstore'] }, { history: true })
-
-        expect(Array.isArray(result)).toBe(true)
-
-        // Implementation should continue processing even if history fails
-        // The entry should be skipped due to the continue in the catch block
-        if (Array.isArray(result)) {
-          expect(result.length).toBe(0)
-        }
-      })
-
-      it('combines includeToken and history options correctly', async () => {
-        primeResolverWithOneOutput(mockResolver)
-        mockHistorian.buildHistory.mockResolvedValue(['combined_test_history'])
-
-        const result = await kvStore.get({ protocolID: [1, 'kvstore'] }, {
-          history: true,
-          includeToken: true
-        })
-
-        expect(Array.isArray(result)).toBe(true)
-
-        if (Array.isArray(result) && result.length > 0) {
-          const entry = result[0]
-          // Entry should have both history and token data
-          expect(entry.history).toEqual(['combined_test_history'])
-          expect(entry.token).toBeDefined()
-          expect(entry.token?.txid).toBe(TEST_TXID)
-          expect(entry.token?.outputIndex).toBe(0)
-        }
-
-        // Verify buildHistory was called
-        expect(mockHistorian.buildHistory).toHaveBeenCalled()
-      })
-    })
-
-    describe('sad paths', () => {
-      it('rejects when no query parameters provided', async () => {
-        await expect(kvStore.get({})).rejects.toThrow('Must specify either key, controller, or protocolID')
-      })
-
-      it('propagates overlay errors', async () => {
-        mockResolver.query.mockRejectedValue(new Error('Network error'))
-
-        await expect(kvStore.get({ key: TEST_KEY })).rejects.toThrow('Network error')
-      })
-
-      it('skips malformed candidates and returns empty array (invalid PushDrop format)', async () => {
-        primeResolverWithOneOutput(mockResolver)
-
-        const originalDecode = (MockPushDrop as any).decode
-          ; (MockPushDrop as any).decode = jest.fn(() => {
-            throw new Error('Invalid PushDrop format')
-          })
-
-        try {
-          const result = await kvStore.get({ key: TEST_KEY })
-          expect(Array.isArray(result)).toBe(true)
-          expect(result).toHaveLength(0)
-        } finally {
-          ; (MockPushDrop as any).decode = originalDecode
-        }
-      })
-    })
-
-    describe('Query Parameter Combinations', () => {
-      describe('Single parameter queries (return arrays)', () => {
-        it('key only - returns array of entries matching key across all controllers', async () => {
-          primeResolverWithOneOutput(mockResolver)
-
-          const result = await kvStore.get({ key: TEST_KEY })
-
-          expect(Array.isArray(result)).toBe(true)
-          expect(mockResolver.query).toHaveBeenCalledWith({
-            service: 'ls_kvstore',
-            query: { key: TEST_KEY }
-          })
-        })
-
-        it('controller only - returns array of entries by specific controller', async () => {
-          primeResolverWithOneOutput(mockResolver)
-
-          const result = await kvStore.get({ controller: TEST_CONTROLLER })
-
-          expect(Array.isArray(result)).toBe(true)
-          expect(mockResolver.query).toHaveBeenCalledWith({
-            service: 'ls_kvstore',
-            query: { controller: TEST_CONTROLLER }
-          })
-        })
-
-        it('protocolID only - returns array of entries under protocol', async () => {
-          primeResolverWithOneOutput(mockResolver)
-
-          const result = await kvStore.get({ protocolID: [1, 'kvstore'] })
-
-          expect(Array.isArray(result)).toBe(true)
-          expect(mockResolver.query).toHaveBeenCalledWith({
-            service: 'ls_kvstore',
-            query: { protocolID: [1, 'kvstore'] }
-          })
-        })
-      })
-
-      describe('Combined parameter queries', () => {
-        it('key + controller - returns single result (unique combination)', async () => {
-          primeResolverWithOneOutput(mockResolver)
-
-          const result = await kvStore.get({
-            key: TEST_KEY,
-            controller: TEST_CONTROLLER
-          })
-
-          // Should return single entry, not array
-          expect(result).not.toBeNull()
-          expect(Array.isArray(result)).toBe(false)
-          if (result && !Array.isArray(result)) {
-            expect(result.key).toBe(TEST_KEY)
-            expect(result.controller).toBe(TEST_CONTROLLER)
-          }
-        })
-
-        it('key + protocolID - returns array (multiple results possible)', async () => {
-          primeResolverWithOneOutput(mockResolver)
-
-          const result = await kvStore.get({
-            key: TEST_KEY,
-            protocolID: [1, 'kvstore']
-          })
-
-          expect(Array.isArray(result)).toBe(true)
-        })
-
-        it('controller + protocolID - returns array (multiple results possible)', async () => {
-          primeResolverWithOneOutput(mockResolver)
-
-          const result = await kvStore.get({
-            controller: TEST_CONTROLLER,
-            protocolID: [1, 'kvstore']
-          })
-
-          expect(Array.isArray(result)).toBe(true)
-        })
-
-        it('key + controller + protocolID - returns single result (most specific)', async () => {
-          primeResolverWithOneOutput(mockResolver)
-
-          const result = await kvStore.get({
-            key: TEST_KEY,
-            controller: TEST_CONTROLLER,
-            protocolID: [1, 'kvstore']
-          })
-
-          // key + controller combination should return single result
-          expect(result).not.toBeNull()
-          expect(Array.isArray(result)).toBe(false)
-        })
-      })
-
-      describe('Return type consistency', () => {
-        it('key+controller always returns single result or undefined', async () => {
-          primeResolverEmpty(mockResolver)
-
-          const result = await kvStore.get({
-            key: TEST_KEY,
-            controller: TEST_CONTROLLER
-          })
-
-          expect(result).toBeUndefined()
-          expect(Array.isArray(result)).toBe(false)
-        })
-
-        it('all other combinations always return arrays', async () => {
-          primeResolverEmpty(mockResolver)
-
-          const testCases = [
-            { key: TEST_KEY },
-            { controller: TEST_CONTROLLER },
-            { protocolID: [1, 'kvstore'] as [1, 'kvstore'] },
-            { key: TEST_KEY, protocolID: [1, 'kvstore'] as [1, 'kvstore'] },
-            { controller: TEST_CONTROLLER, protocolID: [1, 'kvstore'] as [1, 'kvstore'] }
-          ]
-
-          for (const query of testCases) {
-            const result = await kvStore.get(query)
-            expect(Array.isArray(result)).toBe(true)
-            expect((result as any[]).length).toBe(0)
-          }
-        })
-      })
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  describe('set', () => {
-    describe('happy paths', () => {
-      it('creates a new token when key does not exist', async () => {
-        primeResolverEmpty(mockResolver)
-        const outpoint = await kvStore.set(TEST_KEY, TEST_VALUE)
-
-        expect(mockWallet.createAction).toHaveBeenCalledWith(
-          expect.objectContaining({
-            description: `Create KVStore value for ${TEST_KEY}`,
-            outputs: expect.arrayContaining([
-              expect.objectContaining({
-                satoshis: 1,
-                outputDescription: 'KVStore token',
-              }),
-            ])
-          }),
-          undefined
-        )
-        expect(outpoint).toBe(`${TEST_TXID}.0`)
-        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')
-        mockQueryOverlay.mockResolvedValue([{
-          key: TEST_KEY,
-          value: 'oldValue',
-          controller: TEST_CONTROLLER,
-          token: {
-            txid: TEST_TXID,
-            outputIndex: 0,
-            beef: mockBeef,
-            satoshis: 1
-          }
-        }])
-
-        const outpoint = await kvStore.set(TEST_KEY, TEST_VALUE)
-
-        expect(mockWallet.createAction).toHaveBeenCalledWith(
-          expect.objectContaining({
-            description: `Update KVStore value for ${TEST_KEY}`,
-            inputs: expect.arrayContaining([
-              expect.objectContaining({
-                inputDescription: 'Previous KVStore token'
-              })
-            ])
-          }),
-          undefined
-        )
-        expect(mockWallet.signAction).toHaveBeenCalled()
-        expect(outpoint).toBe(`${TEST_TXID}.0`)
-
-        mockQueryOverlay.mockRestore()
-      })
-
-      it('is safe under concurrent operations (key locking)', async () => {
-        primeResolverEmpty(mockResolver)
-
-        const promise1 = kvStore.set(TEST_KEY, 'value1')
-        const promise2 = kvStore.set(TEST_KEY, 'value2')
-
-        await Promise.all([promise1, promise2])
-
-        // Both operations should have completed successfully
-        expect(mockWallet.createAction).toHaveBeenCalledTimes(2)
-      })
-    })
-
-    describe('sad paths', () => {
-      it('rejects invalid key', async () => {
-        await expect(kvStore.set('', TEST_VALUE)).rejects.toThrow('Key must be a non-empty string.')
-      })
-
-      it('rejects invalid value', async () => {
-        await expect(kvStore.set(TEST_KEY, null as any)).rejects.toThrow('Value must be a string.')
-      })
-
-      it('propagates wallet createAction failures', async () => {
-        primeResolverEmpty(mockResolver)
-        mockWallet.createAction.mockRejectedValue(new Error('Wallet error'))
-
-        await expect(kvStore.set(TEST_KEY, TEST_VALUE)).rejects.toThrow('Wallet error')
-      })
-
-      it('surface broadcast errors in set', async () => {
-        primeResolverEmpty(mockResolver)
-        mockBroadcaster.broadcast.mockRejectedValue(new Error('overlay down'))
-        await expect(kvStore.set(TEST_KEY, TEST_VALUE)).rejects.toThrow('overlay down')
-      })
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  describe('remove', () => {
-    describe('happy paths', () => {
-      it('removes an existing token', async () => {
-        // Mock the queryOverlay to return an entry with a token
-        const mockQueryOverlay = jest.spyOn(kvStore as any, 'queryOverlay')
-        mockQueryOverlay.mockResolvedValue([{
-          key: TEST_KEY,
-          value: TEST_VALUE,
-          controller: TEST_CONTROLLER,
-          token: {
-            txid: TEST_TXID,
-            outputIndex: 0,
-            beef: mockBeef,
-            satoshis: 1
-          }
-        }])
-
-        const txid = await kvStore.remove(TEST_KEY)
-
-        expect(mockWallet.createAction).toHaveBeenCalledWith(
-          expect.objectContaining({
-            description: `Remove KVStore value for ${TEST_KEY}`,
-            inputs: expect.arrayContaining([
-              expect.objectContaining({
-                inputDescription: 'KVStore token to remove'
-              })
-            ])
-          }),
-          undefined
-        )
-        expect(txid).toBe(TEST_TXID)
-
-        mockQueryOverlay.mockRestore()
-      })
-
-      it('supports custom outputs on removal', async () => {
-        // Mock the queryOverlay to return an entry with a token
-        const mockQueryOverlay = jest.spyOn(kvStore as any, 'queryOverlay')
-        mockQueryOverlay.mockResolvedValue([{
-          key: TEST_KEY,
-          value: TEST_VALUE,
-          controller: TEST_CONTROLLER,
-          token: {
-            txid: TEST_TXID,
-            outputIndex: 0,
-            beef: mockBeef,
-            satoshis: 1
-          }
-        }])
-
-        const customOutputs = [
-          {
-            satoshis: 500,
-            lockingScript: 'customTransferScript',
-            outputDescription: 'Custom token transfer output',
-          },
-        ]
-
-        const txid = await kvStore.remove(TEST_KEY, customOutputs)
-
-        expect(mockWallet.createAction).toHaveBeenCalledWith(
-          expect.objectContaining({
-            outputs: customOutputs,
-          }),
-          undefined
-        )
-        expect(txid).toBe(TEST_TXID)
-
-        mockQueryOverlay.mockRestore()
-      })
-    })
-
-    describe('sad paths', () => {
-      it('rejects invalid key', async () => {
-        await expect(kvStore.remove('')).rejects.toThrow('Key must be a non-empty string.')
-      })
-
-      it('throws when key does not exist', async () => {
-        primeResolverEmpty(mockResolver)
-
-        await expect(kvStore.remove(TEST_KEY)).rejects.toThrow(
-          'The item did not exist, no item was deleted.'
-        )
-      })
-
-      it('propagates wallet signAction failures', async () => {
-        // Mock the queryOverlay to return an entry with a token
-        const mockQueryOverlay = jest.spyOn(kvStore as any, 'queryOverlay')
-        mockQueryOverlay.mockResolvedValue([{
-          key: TEST_KEY,
-          value: TEST_VALUE,
-          controller: TEST_CONTROLLER,
-          token: {
-            txid: TEST_TXID,
-            outputIndex: 0,
-            beef: mockBeef,
-            satoshis: 1
-          }
-        }])
-
-          ; (mockWallet.signAction as jest.Mock).mockRejectedValue(new Error('Sign failed'))
-
-        await expect(kvStore.remove(TEST_KEY)).rejects.toThrow('Sign failed')
-
-        mockQueryOverlay.mockRestore()
-      })
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  describe('getWithHistory', () => {
-    it('delegates to get(key, undefined, controller, true) and returns value + history', async () => {
-      primeResolverWithOneOutput(mockResolver)
-      mockHistorian.buildHistory.mockResolvedValue([TEST_VALUE])
-
-      const result = await kvStore.get({ key: TEST_KEY }, { history: true })
-
-      expect(Array.isArray(result)).toBe(true)
-      expect(result).toHaveLength(1)
-      if (Array.isArray(result) && result.length > 0) {
-        expect(result[0]).toEqual({
-          key: TEST_KEY,
-          value: TEST_VALUE,
-          controller: expect.any(String),
-          protocolID: [1, 'kvstore'],
-          history: [TEST_VALUE],
-        })
-      }
-    })
-
-    it('returns empty array when key not found', async () => {
-      primeResolverEmpty(mockResolver)
-
-      const result = await kvStore.get({ key: TEST_KEY }, { history: true })
-      expect(Array.isArray(result)).toBe(true)
-      expect(result).toHaveLength(0)
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  describe('Integration-ish behaviors', () => {
-    it('uses PushDrop for signature verification', async () => {
-      primeResolverWithOneOutput(mockResolver)
-
-      await kvStore.get({ key: TEST_KEY })
-
-      expect(MockProtoWallet).toHaveBeenCalledWith('anyone')
-      expect(mockProtoWallet.verifySignature).toHaveBeenCalledWith({
-        data: expect.any(Array),
-        signature: expect.any(Array),
-        counterparty: TEST_CONTROLLER,
-        protocolID: [1, 'kvstore'],
-        keyID: TEST_KEY
-      })
-    })
-
-    it('caches identity key (single wallet.getPublicKey call across operations)', async () => {
-      primeResolverEmpty(mockResolver)
-      await kvStore.set('key1', 'value1')
-      await kvStore.set('key2', 'value2')
-
-      expect(mockWallet.getPublicKey).toHaveBeenCalledTimes(1)
-      expect(mockWallet.createAction).toHaveBeenCalledTimes(2)
-    })
-
-    it('properly cleans up empty lock queues to prevent memory leaks', async () => {
-      primeResolverEmpty(mockResolver)
-
-      // Get reference to private keyLocks Map
-      const keyLocks = (kvStore as any).keyLocks as Map<string, Array<() => void>>
-
-      // Initially empty
-      expect(keyLocks.size).toBe(0)
-
-      // Perform operations on different keys
-      await kvStore.set('key1', 'value1')
-      await kvStore.set('key2', 'value2')
-      await kvStore.set('key3', 'value3')
-
-      // After operations complete, keyLocks should be empty (no memory leak)
-      expect(keyLocks.size).toBe(0)
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  describe('Error recovery & edge cases', () => {
-    it('returns empty array for empty overlay response', async () => {
-      primeResolverEmpty(mockResolver)
-      const result = await kvStore.get({ key: TEST_KEY })
-      expect(Array.isArray(result)).toBe(true)
-      expect(result).toHaveLength(0)
-    })
-
-    it('skips malformed transactions and returns empty array', async () => {
-      primeResolverWithOneOutput(mockResolver)
-
-      const originalFromBEEF = (MockTransaction as any).fromBEEF
-        ; (MockTransaction as any).fromBEEF = jest.fn(() => {
-          throw new Error('Malformed transaction data')
-        })
-
-      try {
-        const result = await kvStore.get({ key: TEST_KEY })
-        expect(Array.isArray(result)).toBe(true)
-        expect(result).toHaveLength(0)
-      } finally {
-        ; (MockTransaction as any).fromBEEF = originalFromBEEF
-      }
-    })
-
-    it('handles edge cases where no valid tokens pass full validation', async () => {
-      // This test verifies that when tokens exist but fail validation (signature, etc),
-      // the method gracefully returns empty array rather than throwing
-      primeResolverWithOneOutput(mockResolver)
-
-      // Make signature verification fail (this could be a realistic failure mode)
-      const originalVerifySignature = mockProtoWallet.verifySignature
-      mockProtoWallet.verifySignature = jest.fn().mockRejectedValue(new Error('Signature verification failed'))
-
-      try {
-        const result = await kvStore.get({ key: TEST_KEY }, { history: true })
-        expect(Array.isArray(result)).toBe(true)
-        expect(result).toHaveLength(0)
-      } finally {
-        // Restore original mock
-        mockProtoWallet.verifySignature = originalVerifySignature
-      }
-    })
-
-    it('when no valid outputs (decode fails), get(..., history=true) still returns empty array', async () => {
-      primeResolverWithOneOutput(mockResolver)
-
-      const originalDecode = (MockPushDrop as any).decode
-        ; (MockPushDrop as any).decode = jest.fn(() => {
-          throw new Error('Invalid token format')
-        })
-
-      try {
-        const result = await kvStore.get({ key: TEST_KEY }, { history: true })
-        expect(Array.isArray(result)).toBe(true)
-        expect(result).toHaveLength(0)
-      } finally {
-        ; (MockPushDrop as any).decode = originalDecode
-      }
-    })
-  })
-})