@bsv/sdk 2.0.1 → 2.0.3

package/package.json

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

package/src/identity/ContactsManager.ts

@@ -88,33 +88,45 @@ export class ContactsManager {
       return []
     }
 
-    const contacts: Contact[] = []
+    // Pre-process outputs synchronously to extract decode data, then decrypt in parallel
+    const decryptTasks: Array<{ keyID: string, ciphertext: number[] }> = []
 
-    // Process each contact output
     for (const output of outputs.outputs) {
       try {
         if (output.lockingScript == null) continue
-
-        // Decode the PushDrop data
         const decoded = PushDrop.decode(LockingScript.fromHex(output.lockingScript))
         if (output.customInstructions == null) continue
         const keyID = JSON.parse(output.customInstructions).keyID
+        decryptTasks.push({ keyID, ciphertext: decoded.fields[0] })
+      } catch (error) {
+        console.warn('ContactsManager: Failed to decode contact output:', error)
+      }
+    }
 
-        // Decrypt the contact data
-        const { plaintext } = await this.wallet.decrypt({
-          ciphertext: decoded.fields[0],
+    // Decrypt all contacts in parallel — each call is a network round-trip over localhost
+    const decryptResults = await Promise.allSettled(
+      decryptTasks.map(async task =>
+        await this.wallet.decrypt({
+          ciphertext: task.ciphertext,
           protocolID: CONTACT_PROTOCOL_ID,
-          keyID,
+          keyID: task.keyID,
           counterparty: 'self'
         }, this.originator)
+      )
+    )
 
-        // Parse the contact data
-        const contactData: Contact = JSON.parse(Utils.toUTF8(plaintext))
-
-        contacts.push(contactData)
-      } catch (error) {
-        console.warn('ContactsManager: Failed to decode contact output:', error)
-        // Skip this contact and continue with others
+    const contacts: Contact[] = []
+    for (let i = 0; i < decryptResults.length; i++) {
+      const result = decryptResults[i]
+      if (result.status === 'fulfilled') {
+        try {
+          const contactData: Contact = JSON.parse(Utils.toUTF8(result.value.plaintext))
+          contacts.push(contactData)
+        } catch (error) {
+          console.warn('ContactsManager: Failed to parse contact data:', error)
+        }
+      } else {
+        console.warn('ContactsManager: Failed to decrypt contact output:', result.reason)
       }
     }
 

package/src/identity/IdentityClient.ts

@@ -138,19 +138,21 @@ export class IdentityClient {
     args: DiscoverByIdentityKeyArgs,
     overrideWithContacts = true
   ): Promise<DisplayableIdentity[]> {
-    if (overrideWithContacts) {
-      // Override results with personal contacts if available
-      const contacts = await this.contactsManager.getContacts(args.identityKey)
-      if (contacts.length > 0) {
-        return contacts
-      }
+    // Run both queries in parallel for better performance
+    const [contacts, certificatesResult] = await Promise.all([
+      overrideWithContacts
+        ? this.contactsManager.getContacts(args.identityKey)
+        : Promise.resolve([]),
+      this.wallet.discoverByIdentityKey(args, this.originator)
+    ])
+
+    // Override results with personal contacts if available
+    if (contacts.length > 0) {
+      return contacts
     }
 
-    const { certificates } = await this.wallet.discoverByIdentityKey(
-      args,
-      this.originator
-    )
-    return certificates.map((cert) => {
+    const certs = certificatesResult?.certificates ?? []
+    return certs.map((cert) => {
       return IdentityClient.parseIdentity(cert)
     })
   }

package/src/identity/__tests/IdentityClient.test.ts

@@ -264,8 +264,8 @@ describe('IdentityClient', () => {
 
       expect(identities).toHaveLength(1)
       expect(identities[0].name).toBe('Alice Smith (Personal Contact)') // Contact should be returned, not discovered identity
-      // Wallet method should not be called when contact is found
-      expect(walletMock.discoverByIdentityKey).not.toHaveBeenCalled()
+      // Both calls fire in parallel, but contacts take priority in the result
+      expect(walletMock.discoverByIdentityKey).toHaveBeenCalled()
     })
   })
 

package/src/overlay-tools/LookupResolver.ts

@@ -264,7 +264,6 @@ export default class LookupResolver {
       competentHosts = await this.getCompetentHostsCached(question.service)
     }
     if (this.additionalHosts[question.service]?.length > 0) {
-      // preserve order: resolved hosts first, then additional (unique)
       const extra = this.additionalHosts[question.service]
       const seen = new Set(competentHosts)
       for (const h of extra) if (!seen.has(h)) competentHosts.push(h)
@@ -283,28 +282,47 @@ export default class LookupResolver {
       throw new Error(`All competent hosts for ${question.service} are temporarily unavailable due to backoff.`)
     }
 
-    // Fire all hosts with per-host timeout, harvest successful output-list responses
-    const hostResponses = await Promise.allSettled(
-      rankedHosts.map(async (host) => {
-        return await this.lookupHostWithTracking(host, question, timeout)
-      })
-    )
+    // Fire all hosts; resolve as soon as we have results from any host,
+    // then allow a short grace window for additional hosts to contribute.
+    const GRACE_MS = 200
+    const answers: LookupAnswer[] = await new Promise<LookupAnswer[]>((resolve) => {
+      const collected: LookupAnswer[] = []
+      let pending = rankedHosts.length
+      let graceTimer: ReturnType<typeof setTimeout> | null = null
+
+      const tryResolve = (): void => {
+        if (graceTimer !== null) clearTimeout(graceTimer)
+        resolve(collected)
+      }
+
+      for (const host of rankedHosts) {
+        this.lookupHostWithTracking(host, question, timeout)
+          .then((answer) => {
+            if (answer?.type === 'output-list' && Array.isArray(answer.outputs) && answer.outputs.length > 0) {
+              collected.push(answer)
+              // First valid response: start a grace window for others
+              if (collected.length === 1 && pending > 1) {
+                graceTimer = setTimeout(tryResolve, GRACE_MS)
+              }
+            }
+          })
+          .catch(() => { /* host failed; tracked by lookupHostWithTracking */ })
+          .finally(() => {
+            pending--
+            if (pending === 0) tryResolve()
+          })
+      }
+    })
 
     const outputsMap = new Map<string, { beef: number[], context?: number[], outputIndex: number }>()
 
     // Memo key helper for tx parsing
     const beefKey = (beef: number[]): string => {
       if (typeof beef !== 'object') return '' // The invalid BEEF has an empty key.
-      // A fast and deterministic key for memoization; avoids large JSON strings
-      // since beef is an array of integers, join is safe and compact.
       return beef.join(',')
     }
 
-    for (const result of hostResponses) {
-      if (result.status !== 'fulfilled') continue
-      const response = result.value
-      if (response?.type !== 'output-list' || !Array.isArray(response.outputs)) continue
-
+    for (const response of answers) {
       for (const output of response.outputs) {
         const keyForBeef = beefKey(output.beef)
         let memo = this.txMemo.get(keyForBeef)
@@ -313,7 +331,6 @@ export default class LookupResolver {
           try {
             const txId = Transaction.fromBEEF(output.beef).id('hex')
             memo = { txId, expiresAt: now + this.txMemoTtlMs }
-            // prune opportunistically if the map gets too large (cheap heuristic)
             if (this.txMemo.size > 4096) this.evictOldest(this.txMemo)
             this.txMemo.set(keyForBeef, memo)
           } catch {
@@ -322,7 +339,6 @@ export default class LookupResolver {
         }
 
         const uniqKey = `${memo.txId}.${output.outputIndex}`
-        // last-writer wins is fine here; outputs are identical if uniqKey matches
         outputsMap.set(uniqKey, output)
       }
     }
@@ -391,8 +407,33 @@ export default class LookupResolver {
     return hosts
   }
 
+  /**
+   * Extracts competent host domains from a SLAP tracker response.
+   */
+  private extractHostsFromAnswer (answer: LookupAnswer, service: string): string[] {
+    const hosts: string[] = []
+    if (answer.type !== 'output-list') return hosts
+    for (const output of answer.outputs) {
+      try {
+        const tx = Transaction.fromBEEF(output.beef)
+        const script = tx.outputs[output.outputIndex]?.lockingScript
+        if (typeof script !== 'object' || script === null) continue
+        const parsed = OverlayAdminTokenTemplate.decode(script)
+        if (parsed.topicOrService !== service || parsed.protocol !== 'SLAP') continue
+        if (typeof parsed.domain === 'string' && parsed.domain.length > 0) {
+          hosts.push(parsed.domain)
+        }
+      } catch {
+        continue
+      }
+    }
+    return hosts
+  }
+
   /**
    * Returns a list of competent hosts for a given lookup service.
+   * Resolves as soon as the first SLAP tracker responds with valid hosts.
+   * Remaining trackers continue in the background for reputation tracking.
    * @param service Service for which competent hosts are to be returned
    * @returns Array of hosts competent for resolving queries
    */
@@ -402,43 +443,39 @@ export default class LookupResolver {
       query: { service }
     }
 
-    // Query all SLAP trackers; tolerate failures.
     const trackerHosts = this.prepareHostsForQuery(
       this.slapTrackers,
       'SLAP trackers'
     )
     if (trackerHosts.length === 0) return []
 
-    const trackerResponses = await Promise.allSettled(
-      trackerHosts.map(async (tracker) =>
-        await this.lookupHostWithTracking(tracker, query, MAX_TRACKER_WAIT_TIME)
-      )
-    )
-
-    const hosts = new Set<string>()
-
-    for (const result of trackerResponses) {
-      if (result.status !== 'fulfilled') continue
-      const answer = result.value
-      if (answer.type !== 'output-list') continue
-
-      for (const output of answer.outputs) {
-        try {
-          const tx = Transaction.fromBEEF(output.beef)
-          const script = tx.outputs[output.outputIndex]?.lockingScript
-          if (typeof script !== 'object' || script === null) continue
-          const parsed = OverlayAdminTokenTemplate.decode(script)
-          if (parsed.topicOrService !== service || parsed.protocol !== 'SLAP') continue
-          if (typeof parsed.domain === 'string' && parsed.domain.length > 0) {
-            hosts.add(parsed.domain)
-          }
-        } catch {
-          continue
-        }
+    // Fire all trackers, resolve as soon as any returns valid hosts.
+    // Remaining trackers continue in the background for reputation tracking.
+    return await new Promise<string[]>((resolve) => {
+      const allHosts = new Set<string>()
+      let resolved = false
+      let pending = trackerHosts.length
+
+      for (const tracker of trackerHosts) {
+        this.lookupHostWithTracking(tracker, query, MAX_TRACKER_WAIT_TIME)
+          .then((answer) => {
+            const hosts = this.extractHostsFromAnswer(answer, service)
+            for (const h of hosts) allHosts.add(h)
+            if (!resolved && allHosts.size > 0) {
+              resolved = true
+              resolve([...allHosts])
+            }
+          })
+          .catch(() => { /* tracker failed; tracked by lookupHostWithTracking */ })
+          .finally(() => {
+            pending--
+            if (pending === 0 && !resolved) {
+              resolved = true
+              resolve([...allHosts])
+            }
+          })
       }
-    }
-
-    return [...hosts]
+    })
   }
 
   /** Evict an arbitrary “oldest” entry from a Map (iteration order). */

package/src/overlay-tools/SHIPBroadcaster.ts

@@ -133,6 +133,11 @@ export default class TopicBroadcaster implements Broadcaster {
   private readonly requireAcknowledgmentFromSpecificHostsForTopics: Record<string, 'all' | 'any' | string[]>
   private readonly networkPreset: 'mainnet' | 'testnet' | 'local'
 
+  // Cache for findInterestedHosts to avoid repeated SHIP tracker lookups
+  private interestedHostsCache: { hosts: Record<string, Set<string>>, expiresAt: number } | null = null
+  private interestedHostsInFlight: Promise<Record<string, Set<string>>> | null = null
+  private readonly interestedHostsTtlMs: number
+
   /**
    * Constructs an instance of the SHIP broadcaster.
    *
@@ -156,6 +161,7 @@ export default class TopicBroadcaster implements Broadcaster {
       config.requireAcknowledgmentFromAnyHostForTopics ?? 'all'
     this.requireAcknowledgmentFromSpecificHostsForTopics =
       config.requireAcknowledgmentFromSpecificHostsForTopics ?? {}
+    this.interestedHostsTtlMs = 5 * 60 * 1000 // 5 minutes
   }
 
   /**
@@ -461,10 +467,33 @@ export default class TopicBroadcaster implements Broadcaster {
       }
       return { 'http://localhost:8080': resultSet }
     }
-    // TODO: cache the list of interested hosts to avoid spamming SHIP trackers.
-    // TODO: Monetize the operation of the SHIP tracker system.
-    // TODO: Cache ship/slap lookup with expiry (every 5min)
 
+    // Return cached result if still valid
+    const now = Date.now()
+    if (this.interestedHostsCache != null && this.interestedHostsCache.expiresAt > now) {
+      return this.interestedHostsCache.hosts
+    }
+
+    // Deduplicate concurrent requests
+    if (this.interestedHostsInFlight != null) {
+      return await this.interestedHostsInFlight
+    }
+
+    this.interestedHostsInFlight = this.fetchInterestedHosts()
+    try {
+      const hosts = await this.interestedHostsInFlight
+      this.interestedHostsCache = { hosts, expiresAt: Date.now() + this.interestedHostsTtlMs }
+      return hosts
+    } finally {
+      this.interestedHostsInFlight = null
+    }
+  }
+
+  /**
+   * Performs the actual SHIP lookup to discover interested hosts.
+   * @private
+   */
+  private async fetchInterestedHosts (): Promise<Record<string, Set<string>>> {
     // Find all SHIP advertisements for the topics we care about
     const results: Record<string, Set<string>> = {}
     const answer = await this.resolver.query(
@@ -488,7 +517,6 @@ export default class TopicBroadcaster implements Broadcaster {
           !this.topics.includes(parsed.topicOrService) ||
           parsed.protocol !== 'SHIP'
         ) {
-          // This should make us think a LOT less highly of this SHIP tracker if it ever happens...
           continue
         }
         if (results[parsed.domain] === undefined) {

package/src/overlay-tools/__tests/LookupResolver.test.ts

@@ -367,7 +367,7 @@ describe('LookupResolver', () => {
     ])
   })
 
-  it('should handle multiple SLAP trackers and aggregate results from multiple hosts', async () => {
+  it('should handle multiple SLAP trackers and resolve with first responder hosts', async () => {
     const slapHostKey1 = new PrivateKey(42)
     const slapWallet1 = new CompletedProtoWallet(slapHostKey1)
     const slapLib1 = new OverlayAdminTokenTemplate(slapWallet1)
@@ -408,7 +408,7 @@ describe('LookupResolver', () => {
       0
     )
 
-    // SLAP trackers return hosts
+    // SLAP trackers return hosts — first responder wins
     mockFacilitator.lookup
       .mockReturnValueOnce({
         type: 'output-list',
@@ -429,7 +429,7 @@ describe('LookupResolver', () => {
         ]
       })
 
-    // Hosts respond to the query
+    // Only the first-resolved tracker's host gets queried
     mockFacilitator.lookup
       .mockReturnValueOnce({
         type: 'output-list',
@@ -440,15 +440,6 @@ describe('LookupResolver', () => {
           }
         ]
       })
-      .mockReturnValueOnce({
-        type: 'output-list',
-        outputs: [
-          {
-            beef: sampleBeef4,
-            outputIndex: 1
-          }
-        ]
-      })
 
     const r = new LookupResolver({
       facilitator: mockFacilitator,
@@ -460,55 +451,45 @@ describe('LookupResolver', () => {
       query: { test: 1 }
     })
 
+    // Only the first tracker's host results are returned
     expect(res).toEqual({
       type: 'output-list',
       outputs: [
-        { beef: sampleBeef3, outputIndex: 0 },
-        { beef: sampleBeef4, outputIndex: 1 }
+        { beef: sampleBeef3, outputIndex: 0 }
       ]
     })
 
-    expect(mockFacilitator.lookup.mock.calls).toEqual([
-      [
-        'https://mock.slap1',
-        {
-          service: 'ls_slap',
-          query: {
-            service: 'ls_foo'
-          }
-        },
-        5000
-      ],
-      [
-        'https://mock.slap2',
-        {
-          service: 'ls_slap',
-          query: {
-            service: 'ls_foo'
-          }
-        },
-        5000
-      ],
-      [
-        'https://slaphost1.com',
-        {
-          service: 'ls_foo',
-          query: {
-            test: 1
-          }
-        },
-        undefined
-      ],
-      [
-        'https://slaphost2.com',
-        {
-          service: 'ls_foo',
-          query: {
-            test: 1
-          }
-        },
-        undefined
-      ]
+    // Both SLAP trackers are queried, but only the first host is used for the actual query
+    expect(mockFacilitator.lookup.mock.calls.length).toBeGreaterThanOrEqual(3)
+    expect(mockFacilitator.lookup.mock.calls[0]).toEqual([
+      'https://mock.slap1',
+      {
+        service: 'ls_slap',
+        query: {
+          service: 'ls_foo'
+        }
+      },
+      5000
+    ])
+    expect(mockFacilitator.lookup.mock.calls[1]).toEqual([
+      'https://mock.slap2',
+      {
+        service: 'ls_slap',
+        query: {
+          service: 'ls_foo'
+        }
+      },
+      5000
+    ])
+    expect(mockFacilitator.lookup.mock.calls[2]).toEqual([
+      'https://slaphost1.com',
+      {
+        service: 'ls_foo',
+        query: {
+          test: 1
+        }
+      },
+      undefined
     ])
   })
 

package/src/overlay-tools/__tests/SHIPBroadcaster.test.ts

@@ -19,7 +19,7 @@ describe('SHIPCast', () => {
   beforeEach(() => {
     mockFacilitator.send.mockReset()
     mockResolver.query.mockReset()
-    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => { })
   })
 
   afterEach(() => {
@@ -190,7 +190,7 @@ describe('SHIPCast', () => {
     })
     mockFacilitator.send.mockClear()
 
-    // Resolver returns the wrong type of data
+    // Resolver returns the wrong type of data — new broadcaster so cache is empty
     mockResolver.query.mockReturnValueOnce({
       type: 'invalid',
       bogus: true,
@@ -198,19 +198,27 @@ describe('SHIPCast', () => {
         different: 'structure'
       }
     })
-    await expect(async () => await b.broadcast(testTx)).rejects.toThrow(
+    const b2 = new SHIPCast(['tm_foo'], {
+      facilitator: mockFacilitator,
+      resolver: mockResolver as unknown as LookupResolver
+    })
+    await expect(async () => await b2.broadcast(testTx)).rejects.toThrow(
       'SHIP answer is not an output list.'
     )
     expect(mockFacilitator.send).not.toHaveBeenCalled()
 
-    // Resolver returns the wrong output structure
+    // Resolver returns the wrong output structure — new broadcaster so cache is empty
     mockResolver.query.mockReturnValueOnce({
       type: 'output-list',
       outputs: {
         different: 'structure'
       }
     })
-    await expect(async () => await b.broadcast(testTx)).rejects.toThrow(
+    const b3 = new SHIPCast(['tm_foo'], {
+      facilitator: mockFacilitator,
+      resolver: mockResolver as unknown as LookupResolver
+    })
+    await expect(async () => await b3.broadcast(testTx)).rejects.toThrow(
       'answer.outputs is not iterable'
     )
     expect(mockFacilitator.send).not.toHaveBeenCalled()
@@ -237,7 +245,11 @@ describe('SHIPCast', () => {
         }
       ]
     })
-    response = await b.broadcast(testTx)
+    const b4 = new SHIPCast(['tm_foo'], {
+      facilitator: mockFacilitator,
+      resolver: mockResolver as unknown as LookupResolver
+    })
+    response = await b4.broadcast(testTx)
     expect(response).toEqual({
       status: 'success',
       txid: testTx.id('hex'),

package/src/wallet/WalletClient.ts

@@ -119,13 +119,13 @@ export default class WalletClient implements WalletInterface {
       }
     }
 
-    // Try fast substrates first
+    // Try all substrates concurrently, select first available by priority order
     const fastAttempts = [
       attemptSubstrate(() => new WindowCWISubstrate()),
+      attemptSubstrate(() => new WalletWireTransceiver(new HTTPWalletWire(this.originator))),
       attemptSubstrate(() => new HTTPWalletJSON(this.originator, 'https://localhost:2121')),
       attemptSubstrate(() => new HTTPWalletJSON(this.originator)),
-      attemptSubstrate(() => new ReactNativeWebView(this.originator)),
-      attemptSubstrate(() => new WalletWireTransceiver(new HTTPWalletWire(this.originator)))
+      attemptSubstrate(() => new ReactNativeWebView(this.originator))
     ]
 
     const fastResults = await Promise.allSettled(fastAttempts)

package/src/wallet/substrates/WalletWireTransceiver.ts

@@ -1686,7 +1686,7 @@ export default class WalletWireTransceiver implements WalletInterface {
           const fieldKey = Utils.toUTF8(resultReader.read(fieldKeyLength))
           const fieldValueLength = resultReader.readVarIntNum()
           keyringForVerifier[fieldKey] = Utils.toBase64(
-              resultReader.read(fieldValueLength)
+            resultReader.read(fieldValueLength)
           )
         }
       }