@bsv/sdk 1.1.32 → 1.2.0

package/src/wallet/WalletClient.ts

@@ -0,0 +1,201 @@
+import { AcquireCertificateArgs, AcquireCertificateResult, Base64String, BasketStringUnder300Bytes, BEEF, BooleanDefaultFalse, BooleanDefaultTrue, Byte, CertificateFieldNameUnder50Bytes, CreateActionArgs, CreateActionResult, DescriptionString5to50Bytes, DiscoverCertificatesResult, EntityIconURLStringMax500Bytes, EntityNameStringMax100Bytes, HexString, InternalizeActionArgs, ISOTimestampString, KeyIDStringUnder800Bytes, LabelStringUnder300Bytes, ListActionsArgs, ListActionsResult, ListCertificatesResult, ListOutputsArgs, ListOutputsResult, OriginatorDomainNameStringUnder250Bytes, OutpointString, OutputTagStringUnder300Bytes, PositiveInteger, PositiveIntegerDefault10Max10000, PositiveIntegerMax10, PositiveIntegerOrZero, ProtocolString5To400Bytes, ProveCertificateArgs, ProveCertificateResult, PubKeyHex, SatoshiValue, SignActionArgs, SignActionResult, TXIDHexString, VersionString7To30Bytes, Wallet } from './Wallet.interfaces.js'
+import WindowCWISubstrate from './substrates/window.CWI.js'
+import XDMSubstrate from './substrates/XDM.js'
+import WalletWireTransceiver from './substrates/WalletWireTransceiver.js'
+import HTTPWalletWire from './substrates/HTTPWalletWire.js'
+
+const MAX_XDM_RESPONSE_WAIT = 200
+
+/**
+ * The SDK is how applications communicate with wallets over a communications substrate.
+ */
+export default class WalletClient implements Wallet {
+  public substrate: 'auto' | Wallet
+  originator?: OriginatorDomainNameStringUnder250Bytes
+  constructor(substrate: 'auto' | 'Cicada' | 'XDM' | 'window.CWI' | Wallet = 'auto', originator?: OriginatorDomainNameStringUnder250Bytes) {
+    if (substrate === 'Cicada') substrate = new WalletWireTransceiver(new HTTPWalletWire(originator))
+    if (substrate === 'window.CWI') substrate = new WindowCWISubstrate()
+    if (substrate === 'XDM') substrate = new XDMSubstrate()
+    this.substrate = substrate
+    this.originator = originator
+  }
+
+  async connectToSubstrate() {
+    if (typeof this.substrate === 'object') {
+      return // substrate is already connected
+    }
+    let sub: Wallet
+    const checkSub = async (timeout?: number) => {
+      let result
+      if (typeof timeout === 'number') {
+        result = await Promise.race([
+          sub.getVersion({}),
+          new Promise<never>((_, reject) => setTimeout(() => reject(new Error('Timed out.')), timeout))
+        ])
+      } else {
+        result = await sub.getVersion({})
+      }
+      if (typeof result !== 'object' || typeof result.version !== 'string') {
+        throw new Error('Failed to use substrate.')
+      }
+    }
+    try {
+      sub = new WindowCWISubstrate()
+      await checkSub()
+      this.substrate = sub
+    } catch (e) {
+      try {
+        sub = new XDMSubstrate()
+        await checkSub(MAX_XDM_RESPONSE_WAIT)
+        this.substrate = sub
+      } catch (e) {
+        try {
+          sub = new WalletWireTransceiver(new HTTPWalletWire(this.originator))
+          await checkSub()
+          this.substrate = sub
+        } catch (e) {
+          throw new Error('No wallet available over any communication substrate. Install a BSV wallet today!')
+        }
+      }
+    }
+  }
+
+  async createAction(args: CreateActionArgs): Promise<CreateActionResult> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).createAction(args, this.originator)
+  }
+
+  async signAction(args: SignActionArgs): Promise<SignActionResult> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).signAction(args, this.originator)
+  }
+
+  async abortAction(args: { reference: Base64String }): Promise<{ aborted: true }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).abortAction(args, this.originator)
+  }
+
+  async listActions(args: ListActionsArgs): Promise<ListActionsResult> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).listActions(args, this.originator)
+  }
+
+  async internalizeAction(args: InternalizeActionArgs): Promise<{ accepted: true }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).internalizeAction(args, this.originator)
+  }
+
+  async listOutputs(args: ListOutputsArgs): Promise<ListOutputsResult> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).listOutputs(args, this.originator)
+  }
+
+  async relinquishOutput(args: { basket: BasketStringUnder300Bytes, output: OutpointString }): Promise<{ relinquished: true }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).relinquishOutput(args, this.originator)
+  }
+
+  async getPublicKey(args: { identityKey?: true, protocolID?: [0 | 1 | 2, ProtocolString5To400Bytes], keyID?: KeyIDStringUnder800Bytes, privileged?: BooleanDefaultFalse, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', forSelf?: BooleanDefaultFalse }): Promise<{ publicKey: PubKeyHex }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).getPublicKey(args, this.originator)
+  }
+
+  async revealCounterpartyKeyLinkage(args: { counterparty: PubKeyHex, verifier: PubKeyHex, privilegedReason?: DescriptionString5to50Bytes, privileged?: BooleanDefaultFalse }): Promise<{ prover: PubKeyHex, verifier: PubKeyHex, counterparty: PubKeyHex, revelationTime: ISOTimestampString, encryptedLinkage: Byte[], encryptedLinkageProof: Byte[] }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).revealCounterpartyKeyLinkage(args, this.originator)
+  }
+
+  async revealSpecificKeyLinkage(args: { counterparty: PubKeyHex, verifier: PubKeyHex, protocolID: [0 | 1 | 2, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, privileged?: BooleanDefaultFalse }): Promise<{ prover: PubKeyHex, verifier: PubKeyHex, counterparty: PubKeyHex, protocolID: [0 | 1 | 2, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, encryptedLinkage: Byte[], encryptedLinkageProof: Byte[], proofType: Byte }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).revealSpecificKeyLinkage(args, this.originator)
+  }
+
+  async encrypt(args: { plaintext: Byte[], protocolID: [0 | 1 | 2, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', privileged?: BooleanDefaultFalse }): Promise<{ ciphertext: Byte[] }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).encrypt(args, this.originator)
+  }
+
+  async decrypt(args: { ciphertext: Byte[], protocolID: [0 | 1 | 2, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', privileged?: BooleanDefaultFalse }): Promise<{ plaintext: Byte[] }> {
+    return await (this.substrate as Wallet).decrypt(args, this.originator)
+  }
+
+  async createHmac(args: { data: Byte[], protocolID: [0 | 1 | 2, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', privileged?: BooleanDefaultFalse }): Promise<{ hmac: Byte[] }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).createHmac(args, this.originator)
+  }
+
+  async verifyHmac(args: { data: Byte[], hmac: Byte[], protocolID: [0 | 1 | 2, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', privileged?: BooleanDefaultFalse }): Promise<{ valid: true }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).verifyHmac(args, this.originator)
+  }
+
+  async createSignature(args: { data?: Byte[], hashToDirectlySign?: Byte[], protocolID: [0 | 1 | 2, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', privileged?: BooleanDefaultFalse }): Promise<{ signature: Byte[] }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).createSignature(args, this.originator)
+  }
+
+  async verifySignature(args: { data?: Byte[], hashToDirectlyVerify?: Byte[], signature: Byte[], protocolID: [0 | 1 | 2, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', forSelf?: BooleanDefaultFalse, privileged?: BooleanDefaultFalse }): Promise<{ valid: true }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).verifySignature(args, this.originator)
+  }
+
+  async acquireCertificate(args: AcquireCertificateArgs): Promise<AcquireCertificateResult> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).acquireCertificate(args, this.originator)
+  }
+
+  async listCertificates(args: { certifiers: PubKeyHex[], types: Base64String[], limit?: PositiveIntegerDefault10Max10000, offset?: PositiveIntegerOrZero, privileged?: BooleanDefaultFalse, privilegedReason?: DescriptionString5to50Bytes }): Promise<ListCertificatesResult> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).listCertificates(args, this.originator)
+  }
+
+  async proveCertificate(args: ProveCertificateArgs): Promise<ProveCertificateResult> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).proveCertificate(args, this.originator)
+  }
+
+  async relinquishCertificate(args: { type: Base64String, serialNumber: Base64String, certifier: PubKeyHex }): Promise<{ relinquished: true }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).relinquishCertificate(args, this.originator)
+  }
+
+  async discoverByIdentityKey(args: { identityKey: PubKeyHex, limit?: PositiveIntegerDefault10Max10000, offset?: PositiveIntegerOrZero }): Promise<DiscoverCertificatesResult> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).discoverByIdentityKey(args, this.originator)
+  }
+
+  async discoverByAttributes(args: { attributes: Record<CertificateFieldNameUnder50Bytes, string>, limit?: PositiveIntegerDefault10Max10000, offset?: PositiveIntegerOrZero }): Promise<DiscoverCertificatesResult> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).discoverByAttributes(args, this.originator)
+  }
+
+  async isAuthenticated(args: {} = {}): Promise<{ authenticated: boolean }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).isAuthenticated(args, this.originator)
+  }
+
+  async waitForAuthentication(args: {} = {}): Promise<{ authenticated: true }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).waitForAuthentication(args, this.originator)
+  }
+
+  async getHeight(args: {} = {}): Promise<{ height: PositiveInteger }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).getHeight(args, this.originator)
+  }
+
+  async getHeaderForHeight(args: { height: PositiveInteger }): Promise<{ header: HexString }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).getHeaderForHeight(args, this.originator)
+  }
+
+  async getNetwork(args: {} = {}): Promise<{ network: 'mainnet' | 'testnet' }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).getNetwork(args, this.originator)
+  }
+
+  async getVersion(args: {} = {}): Promise<{ version: VersionString7To30Bytes }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as Wallet).getVersion(args, this.originator)
+  }
+}

package/src/wallet/WalletError.ts

@@ -0,0 +1,27 @@
+export class WalletError extends Error {
+  code: number
+  isError: boolean = true
+
+  constructor(message: string, code = 1, stack?: string) {
+    super(message)
+    this.code = code
+    this.name = this.constructor.name
+
+    if (stack) {
+      this.stack = stack
+    } else if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor)
+    }
+  }
+}
+
+// NOTE: Enum values must not exceed the UInt8 range (0–255)
+enum walletErrors {
+  unknownError = 1,
+  unsupportedAction = 2,
+  invalidHmac = 3,
+  invalidSignature = 4,
+}
+
+export default walletErrors
+export type WalletErrorCode = keyof typeof walletErrors

package/src/wallet/__tests/CachedKeyDeriver.test.ts

@@ -0,0 +1,322 @@
+import { PrivateKey, PublicKey, SymmetricKey } from '../../../dist/cjs/src/primitives/index.js'
+import CachedKeyDeriver from '../../../dist/cjs/src/wallet/CachedKeyDeriver.js'
+import KeyDeriver from '../../../dist/cjs/src/wallet/KeyDeriver.js'
+
+describe('CachedKeyDeriver', () => {
+  let mockKeyDeriver: jest.Mocked<KeyDeriver>
+  let cachedKeyDeriver: CachedKeyDeriver
+  const rootKey = new PrivateKey(1)
+
+  beforeEach(() => {
+    // Reset the mocks and create a new CachedKeyDeriver instance before each test
+    jest.clearAllMocks()
+    mockKeyDeriver = new KeyDeriver(rootKey) as jest.Mocked<KeyDeriver>
+    // Mock the methods of KeyDeriver
+    mockKeyDeriver.derivePublicKey = jest.fn()
+    mockKeyDeriver.derivePrivateKey = jest.fn()
+    mockKeyDeriver.deriveSymmetricKey = jest.fn()
+    mockKeyDeriver.revealCounterpartySecret = jest.fn()
+    mockKeyDeriver.revealSpecificSecret = jest.fn()
+
+    // Replace the internal keyDeriver instance with the mocked one
+    cachedKeyDeriver = new CachedKeyDeriver(rootKey)
+    cachedKeyDeriver.keyDeriver = mockKeyDeriver
+  })
+
+  describe('derivePublicKey', () => {
+    it('should call derivePublicKey on KeyDeriver and cache the result', () => {
+      const protocolID: [0, string] = [0, 'testprotocol']
+      const keyID = 'key1'
+      const counterparty = 'self'
+      const publicKey = new PublicKey(0)
+
+      mockKeyDeriver.derivePublicKey.mockReturnValue(publicKey)
+
+      // First call - should invoke the underlying method
+      const result1 = cachedKeyDeriver.derivePublicKey(protocolID, keyID, counterparty)
+      expect(mockKeyDeriver.derivePublicKey).toHaveBeenCalledTimes(1)
+      expect(result1).toBe(publicKey)
+
+      // Second call with the same parameters - should retrieve from cache
+      const result2 = cachedKeyDeriver.derivePublicKey(protocolID, keyID, counterparty)
+      expect(mockKeyDeriver.derivePublicKey).toHaveBeenCalledTimes(1) // No additional calls
+      expect(result2).toBe(publicKey)
+    })
+
+    it('should handle different parameters correctly', () => {
+      const protocolID1: [0, string] = [0, 'protocol1']
+      const protocolID2: [1, string] = [1, 'protocol2']
+      const keyID1 = 'key1'
+      const keyID2 = 'key2'
+      const counterparty1 = 'self'
+      const counterparty2 = 'anyone'
+      const publicKey1 = new PublicKey(0)
+      const publicKey2 = new PublicKey(0)
+
+      mockKeyDeriver.derivePublicKey
+        .mockReturnValueOnce(publicKey1)
+        .mockReturnValueOnce(publicKey2)
+
+      // Different parameters - should not hit cache
+      const result1 = cachedKeyDeriver.derivePublicKey(protocolID1, keyID1, counterparty1)
+      const result2 = cachedKeyDeriver.derivePublicKey(protocolID2, keyID2, counterparty2)
+      expect(mockKeyDeriver.derivePublicKey).toHaveBeenCalledTimes(2)
+      expect(result1).toBe(publicKey1)
+      expect(result2).toBe(publicKey2)
+    })
+  })
+
+  describe('derivePrivateKey', () => {
+    it('should call derivePrivateKey on KeyDeriver and cache the result', () => {
+      const protocolID: [1, string] = [1, 'testprotocol']
+      const keyID = 'key1'
+      const counterparty = 'anyone'
+      const privateKey = new PrivateKey()
+
+      mockKeyDeriver.derivePrivateKey.mockReturnValue(privateKey)
+
+      // First call - should invoke the underlying method
+      const result1 = cachedKeyDeriver.derivePrivateKey(protocolID, keyID, counterparty)
+      expect(mockKeyDeriver.derivePrivateKey).toHaveBeenCalledTimes(1)
+      expect(result1).toBe(privateKey)
+
+      // Second call with the same parameters - should retrieve from cache
+      const result2 = cachedKeyDeriver.derivePrivateKey(protocolID, keyID, counterparty)
+      expect(mockKeyDeriver.derivePrivateKey).toHaveBeenCalledTimes(1)
+      expect(result2).toBe(privateKey)
+    })
+
+    it('should differentiate cache entries based on parameters', () => {
+      const protocolID: [1, string] = [1, 'testprotocol']
+      const keyID = 'key1'
+      const counterparty = 'anyone'
+      const privateKey1 = new PrivateKey()
+      const privateKey2 = new PrivateKey()
+
+      mockKeyDeriver.derivePrivateKey
+        .mockReturnValueOnce(privateKey1)
+        .mockReturnValueOnce(privateKey2)
+
+      // First call
+      const result1 = cachedKeyDeriver.derivePrivateKey(protocolID, keyID, counterparty)
+      expect(result1).toBe(privateKey1)
+
+      // Second call with different keyID
+      const result2 = cachedKeyDeriver.derivePrivateKey(protocolID, 'key2', counterparty)
+      expect(result2).toBe(privateKey2)
+      expect(mockKeyDeriver.derivePrivateKey).toHaveBeenCalledTimes(2)
+    })
+  })
+
+  describe('deriveSymmetricKey', () => {
+    it('should call deriveSymmetricKey on KeyDeriver and cache the result', () => {
+      const protocolID: [2, string] = [2, 'testprotocol']
+      const keyID = 'key1'
+      const counterparty = new PublicKey(0)
+      const symmetricKey = new SymmetricKey(0)
+
+      mockKeyDeriver.deriveSymmetricKey.mockReturnValue(symmetricKey)
+
+      // First call
+      const result1 = cachedKeyDeriver.deriveSymmetricKey(protocolID, keyID, counterparty)
+      expect(mockKeyDeriver.deriveSymmetricKey).toHaveBeenCalledTimes(1)
+      expect(result1).toBe(symmetricKey)
+
+      // Second call with same parameters
+      const result2 = cachedKeyDeriver.deriveSymmetricKey(protocolID, keyID, counterparty)
+      expect(mockKeyDeriver.deriveSymmetricKey).toHaveBeenCalledTimes(1)
+      expect(result2).toBe(symmetricKey)
+    })
+
+    it('should throw an error when KeyDeriver throws an error', () => {
+      const protocolID: [2, string] = [2, 'testprotocol']
+      const keyID = 'key1'
+      const counterparty = 'anyone'
+
+      mockKeyDeriver.deriveSymmetricKey.mockImplementation(() => {
+        throw new Error('Test error')
+      })
+
+      expect(() => {
+        cachedKeyDeriver.deriveSymmetricKey(protocolID, keyID, counterparty)
+      }).toThrow('Test error')
+    })
+  })
+
+  describe('revealCounterpartySecret', () => {
+    it('should call revealCounterpartySecret on KeyDeriver and cache the result', () => {
+      const counterparty = new PublicKey(0)
+      const secret = [1, 2, 3]
+
+      mockKeyDeriver.revealCounterpartySecret.mockReturnValue(secret)
+
+      // First call
+      const result1 = cachedKeyDeriver.revealCounterpartySecret(counterparty)
+      expect(mockKeyDeriver.revealCounterpartySecret).toHaveBeenCalledTimes(1)
+      expect(result1).toBe(secret)
+
+      // Second call with same parameters
+      const result2 = cachedKeyDeriver.revealCounterpartySecret(counterparty)
+      expect(mockKeyDeriver.revealCounterpartySecret).toHaveBeenCalledTimes(1)
+      expect(result2).toBe(secret)
+    })
+  })
+
+  describe('revealSpecificSecret', () => {
+    it('should call revealSpecificSecret on KeyDeriver and cache the result', () => {
+      const counterparty = 'self'
+      const protocolID: [0, string] = [0, 'testprotocol']
+      const keyID = 'key1'
+      const secret = [4, 5, 6]
+
+      mockKeyDeriver.revealSpecificSecret.mockReturnValue(secret)
+
+      // First call
+      const result1 = cachedKeyDeriver.revealSpecificSecret(counterparty, protocolID, keyID)
+      expect(mockKeyDeriver.revealSpecificSecret).toHaveBeenCalledTimes(1)
+      expect(result1).toBe(secret)
+
+      // Second call with same parameters
+      const result2 = cachedKeyDeriver.revealSpecificSecret(counterparty, protocolID, keyID)
+      expect(mockKeyDeriver.revealSpecificSecret).toHaveBeenCalledTimes(1)
+      expect(result2).toBe(secret)
+    })
+
+    it('should handle different parameters correctly', () => {
+      const counterparty = 'self'
+      const protocolID1: [0, string] = [0, 'protocol1']
+      const protocolID2: [1, string] = [1, 'protocol2']
+      const keyID1 = 'key1'
+      const keyID2 = 'key2'
+      const secret1 = [4, 5, 6]
+      const secret2 = [7, 8, 9]
+
+      mockKeyDeriver.revealSpecificSecret
+        .mockReturnValueOnce(secret1)
+        .mockReturnValueOnce(secret2)
+
+      // First call
+      const result1 = cachedKeyDeriver.revealSpecificSecret(counterparty, protocolID1, keyID1)
+      expect(result1).toBe(secret1)
+
+      // Second call with different parameters
+      const result2 = cachedKeyDeriver.revealSpecificSecret(counterparty, protocolID2, keyID2)
+      expect(result2).toBe(secret2)
+      expect(mockKeyDeriver.revealSpecificSecret).toHaveBeenCalledTimes(2)
+    })
+  })
+
+  describe('Cache management', () => {
+    it('should not exceed the max cache size and evict least recently used items', () => {
+      const maxCacheSize = 5
+      // Create a new CachedKeyDeriver with a small cache size
+      cachedKeyDeriver = new CachedKeyDeriver(rootKey, { maxCacheSize })
+      cachedKeyDeriver.keyDeriver = mockKeyDeriver
+
+      const protocolID: [0, string] = [0, 'testprotocol']
+      const counterparty = 'self'
+
+      // Mock return values
+      const mockResults = [1, 2, 3, 4, 5, 6].map((n) => new PublicKey(0))
+
+      mockKeyDeriver.derivePublicKey
+        .mockReturnValueOnce(mockResults[0])
+        .mockReturnValueOnce(mockResults[1])
+        .mockReturnValueOnce(mockResults[2])
+        .mockReturnValueOnce(mockResults[3])
+        .mockReturnValueOnce(mockResults[4])
+        .mockReturnValueOnce(mockResults[5])
+
+      // Add entries to fill the cache
+      for (let i = 0; i < maxCacheSize; i++) {
+        cachedKeyDeriver.derivePublicKey(protocolID, `key${i}`, counterparty)
+      }
+
+      // Cache should be full now
+      expect(cachedKeyDeriver.cache.size).toBe(maxCacheSize)
+
+      // Access one of the earlier keys to make it recently used
+      cachedKeyDeriver.derivePublicKey(protocolID, 'key0', counterparty)
+
+      // Add one more entry to exceed the cache size
+      cachedKeyDeriver.derivePublicKey(protocolID, 'key5', counterparty)
+
+      // Cache size should still be maxCacheSize
+      expect(cachedKeyDeriver.cache.size).toBe(maxCacheSize)
+
+      // The least recently used item (key1) should have been evicted
+      // The cache should contain keys: key0, key2, key3, key4, key5
+      expect(Array.from(cachedKeyDeriver.cache.keys())).toEqual([
+        expect.stringContaining('key2'),
+        expect.stringContaining('key3'),
+        expect.stringContaining('key4'),
+        expect.stringContaining('key0'),
+        expect.stringContaining('key5')
+      ])
+    })
+
+    it('should update the recentness of cache entries on access', () => {
+      const maxCacheSize = 3
+      cachedKeyDeriver = new CachedKeyDeriver(rootKey, { maxCacheSize })
+      cachedKeyDeriver.keyDeriver = mockKeyDeriver
+
+      const protocolID: [0, string] = [0, 'testprotocol']
+      const counterparty = 'self'
+      const keys = ['key1', 'key2', 'key3']
+      const publicKeys = keys.map(() => new PublicKey(0))
+
+      mockKeyDeriver.derivePublicKey
+        .mockReturnValueOnce(publicKeys[0])
+        .mockReturnValueOnce(publicKeys[1])
+        .mockReturnValueOnce(publicKeys[2])
+
+      // Fill the cache
+      keys.forEach((keyID) => {
+        cachedKeyDeriver.derivePublicKey(protocolID, keyID, counterparty)
+      })
+
+      // Access 'key1' to make it most recently used
+      cachedKeyDeriver.derivePublicKey(protocolID, 'key1', counterparty)
+
+      // Add a new key to trigger eviction
+      const newKeyID = 'key4'
+      const newPublicKey = new PublicKey(0)
+      mockKeyDeriver.derivePublicKey.mockReturnValueOnce(newPublicKey)
+      cachedKeyDeriver.derivePublicKey(protocolID, newKeyID, counterparty)
+
+      // 'key2' should be evicted as it is the least recently used
+      expect(Array.from(cachedKeyDeriver.cache.keys())).toEqual([
+        expect.stringContaining('key3'),
+        expect.stringContaining('key1'),
+        expect.stringContaining('key4')
+      ])
+    })
+  })
+
+  describe('Performance considerations', () => {
+    it('should improve performance by caching expensive operations', () => {
+      const protocolID: [0, string] = [0, 'testprotocol']
+      const keyID = 'key1'
+      const counterparty = 'self'
+      const publicKey = new PublicKey(0)
+
+      // Simulate an expensive operation
+      mockKeyDeriver.derivePublicKey.mockImplementation(() => {
+        const start = Date.now()
+        while (Date.now() - start < 50) { } // Busy wait for 50ms
+        return publicKey
+      })
+
+      const startTime = Date.now()
+      cachedKeyDeriver.derivePublicKey(protocolID, keyID, counterparty)
+      const firstCallDuration = Date.now() - startTime
+
+      const startTime2 = Date.now()
+      cachedKeyDeriver.derivePublicKey(protocolID, keyID, counterparty)
+      const secondCallDuration = Date.now() - startTime2
+
+      expect(firstCallDuration).toBeGreaterThanOrEqual(50)
+      expect(secondCallDuration).toBeLessThan(10) // Should be much faster due to caching
+    })
+  })
+})

package/src/wallet/__tests/KeyDeriver.test.ts

@@ -0,0 +1,118 @@
+import { PrivateKey, PublicKey, SymmetricKey, Utils, Hash } from '../../../dist/cjs/src/primitives/index.js'
+import KeyDeriver from '../../../dist/cjs/src/wallet/KeyDeriver.js'
+
+describe('KeyDeriver', () => {
+  const rootPrivateKey = new PrivateKey(42)
+  const rootPublicKey = rootPrivateKey.toPublicKey()
+  const counterpartyPrivateKey = new PrivateKey(69)
+  const counterpartyPublicKey = counterpartyPrivateKey.toPublicKey()
+  const anyonePublicKey = new PrivateKey(1).toPublicKey()
+
+  const protocolID: [0 | 1 | 2, string] = [0, 'testprotocol']
+  const keyID = '12345'
+
+  let keyDeriver: KeyDeriver
+
+  beforeEach(() => {
+    keyDeriver = new KeyDeriver(rootPrivateKey)
+  })
+
+  test('should compute the correct invoice number', () => {
+    const invoiceNumber = (keyDeriver as any).computeInvoiceNumber(protocolID, keyID)
+    expect(invoiceNumber).toBe('0-testprotocol-12345')
+  })
+
+  test('should throw if no co counterparty given', () => {
+    expect(() => (keyDeriver as any).normalizeCounterparty()).toThrow()
+  })
+
+  test('should normalize counterparty correctly for self', () => {
+    const normalized = (keyDeriver as any).normalizeCounterparty('self')
+    expect(normalized.toString()).toBe(rootPublicKey.toString())
+  })
+
+  test('should normalize counterparty correctly for anyone', () => {
+    const normalized = (keyDeriver as any).normalizeCounterparty('anyone')
+    expect(normalized.toString()).toBe(anyonePublicKey.toString())
+  })
+
+  test('should normalize counterparty correctly when given as a hex string', () => {
+    const normalized = (keyDeriver as any).normalizeCounterparty(counterpartyPublicKey.toString())
+    expect(normalized.toString()).toBe(counterpartyPublicKey.toString())
+  })
+
+  test('should normalize counterparty correctly when given as a public key', () => {
+    const normalized = (keyDeriver as any).normalizeCounterparty(counterpartyPublicKey)
+    expect(normalized.toString()).toBe(counterpartyPublicKey.toString())
+  })
+
+  test('should allow public key derivation as anyone', () => {
+    const anyoneDeriver = new KeyDeriver('anyone')
+    const derivedPublicKey = anyoneDeriver.derivePublicKey(protocolID, keyID, counterpartyPublicKey)
+    expect(derivedPublicKey).toBeInstanceOf(PublicKey)
+    expect(derivedPublicKey.toString()).toEqual(counterpartyPublicKey.deriveChild(new PrivateKey(1), '0-testprotocol-12345').toString())
+  })
+
+  test('should derive the correct public key for counterparty', () => {
+    const derivedPublicKey = keyDeriver.derivePublicKey(protocolID, keyID, counterpartyPublicKey)
+    expect(derivedPublicKey).toBeInstanceOf(PublicKey)
+    expect(derivedPublicKey.toString()).toEqual(counterpartyPublicKey.deriveChild(rootPrivateKey, '0-testprotocol-12345').toString())
+  })
+
+  test('should derive the correct public key for self', () => {
+    const derivedPublicKey = keyDeriver.derivePublicKey(protocolID, keyID, counterpartyPublicKey, true)
+    expect(derivedPublicKey).toBeInstanceOf(PublicKey)
+    expect(derivedPublicKey.toString()).toEqual(rootPrivateKey.deriveChild(counterpartyPublicKey, '0-testprotocol-12345').toPublicKey().toString())
+  })
+
+  test('should derive the correct private key', () => {
+    const derivedPrivateKey = keyDeriver.derivePrivateKey(protocolID, keyID, counterpartyPublicKey)
+    expect(derivedPrivateKey).toBeInstanceOf(PrivateKey)
+    expect(derivedPrivateKey.toString()).toEqual(rootPrivateKey.deriveChild(counterpartyPublicKey, '0-testprotocol-12345').toString())
+  })
+
+  test('should derive the correct symmetric key', () => {
+    const derivedSymmetricKey = keyDeriver.deriveSymmetricKey(protocolID, keyID, counterpartyPublicKey)
+    expect(derivedSymmetricKey).toBeInstanceOf(SymmetricKey)
+    const priv = rootPrivateKey.deriveChild(counterpartyPublicKey, '0-testprotocol-12345')
+    const pub = counterpartyPublicKey.deriveChild(rootPrivateKey, '0-testprotocol-12345')
+    expect(derivedSymmetricKey.toHex()).toEqual(new SymmetricKey(priv.deriveSharedSecret(pub).x?.toArray()).toHex())
+  })
+
+  test('should not derive symmetric key with anyone', () => {
+    expect(() => keyDeriver.deriveSymmetricKey(protocolID, keyID, 'anyone')).toThrow()
+  })
+
+  test('should reveal the correct counterparty shared secret', () => {
+    const sharedSecret = keyDeriver.revealCounterpartySecret(counterpartyPublicKey)
+    expect(sharedSecret).toBeInstanceOf(Array)
+    expect(sharedSecret.length).toBeGreaterThan(0)
+    expect(sharedSecret).toEqual(rootPrivateKey.deriveSharedSecret(counterpartyPublicKey).encode(true))
+  })
+
+  test('should not reveal shared secret for self', () => {
+    expect(() => keyDeriver.revealCounterpartySecret('self')).toThrow()
+    expect(() => keyDeriver.revealCounterpartySecret(rootPublicKey)).toThrow()
+  })
+
+  test('should reveal the specific key association', () => {
+    const specificSecret = keyDeriver.revealSpecificSecret(counterpartyPublicKey, protocolID, keyID)
+    expect(specificSecret).toBeInstanceOf(Array)
+    expect(specificSecret.length).toBeGreaterThan(0)
+    const sharedSecret = rootPrivateKey.deriveSharedSecret(counterpartyPublicKey)
+    const invoiceNumberBin = Utils.toArray((keyDeriver as any).computeInvoiceNumber(protocolID, keyID), 'utf8')
+    expect(specificSecret).toEqual(Hash.sha256hmac(sharedSecret.encode(true), invoiceNumberBin))
+  })
+
+  test('should throw an error for invalid protocol names', () => {
+    expect(() => (keyDeriver as any).computeInvoiceNumber(protocolID, 'long' + 'a'.repeat(800))).toThrow()
+    expect(() => (keyDeriver as any).computeInvoiceNumber(protocolID, '')).toThrow()
+    expect(() => (keyDeriver as any).computeInvoiceNumber([-3, 'otherwise valid'], keyID)).toThrow()
+    expect(() => (keyDeriver as any).computeInvoiceNumber([2, 'double  space'], keyID)).toThrow()
+    expect(() => (keyDeriver as any).computeInvoiceNumber([0, ''], keyID)).toThrow()
+    expect(() => (keyDeriver as any).computeInvoiceNumber([0, ' a'], keyID)).toThrow()
+    expect(() => (keyDeriver as any).computeInvoiceNumber([0, 'long' + 'a'.repeat(400)], keyID)).toThrow()
+    expect(() => (keyDeriver as any).computeInvoiceNumber([2, 'redundant protocol protocol'], keyID)).toThrow()
+    expect(() => (keyDeriver as any).computeInvoiceNumber([2, 'üñî√é®sål ©0på'], keyID)).toThrow()
+  })
+})