@bsv/sdk 2.1.0 → 2.1.2

package/src/identity/IdentityClient.ts

@@ -18,6 +18,74 @@ import { PrivateKey, Utils } from '../primitives/index.js'
 import { LookupResolver, SHIPBroadcaster, TopicBroadcaster, withDoubleSpendRetry } from '../overlay-tools/index.js'
 import { ContactsManager, Contact } from './ContactsManager.js'
 
+/**
+ * Maximum number of identity certificates to parse synchronously before yielding to the
+ * event loop. Keeps the main thread responsive when an overlay query returns many results
+ * (e.g. a bulk enrichment of N identityKeys).
+ */
+const PARSE_BATCH_SIZE = 32
+
+/**
+ * Yield control to the event loop so queued microtasks / timers can run. Uses
+ * `scheduler.yield()` when available (Chromium) or a 0ms macrotask fallback.
+ */
+async function yieldToEventLoop (): Promise<void> {
+  const sched = (globalThis as any).scheduler
+  if (sched != null && typeof sched.yield === 'function') {
+    return await sched.yield()
+  }
+  return await new Promise<void>((resolve) => setTimeout(resolve, 0))
+}
+
+/** Options for {@link IdentityClient.resolveByIdentityKey}. */
+export interface ResolveByIdentityKeyOptions {
+  /**
+   * Opt-in to consulting personal contacts before/alongside the overlay. Default `false`.
+   *
+   * Most callers (including any client without a populated contacts basket) pay no benefit
+   * from the contacts path and incur its setup cost. Set `true` only in UI contexts where
+   * the user has likely saved contacts and a local cache hit is preferable to a fresh overlay
+   * answer.
+   */
+  useContacts?: boolean
+  /**
+   * Legacy alias for {@link useContacts}. When provided, takes precedence over the new flag.
+   * Kept for binary compatibility — new code should use `useContacts`.
+   */
+  overrideWithContacts?: boolean
+  /**
+   * When `true` (and {@link useContacts} is also true), fire contacts and overlay in parallel
+   * rather than short-circuiting on a contacts hit. Use only when callers specifically need a
+   * fresh overlay answer alongside any cached contact record.
+   */
+  parallel?: boolean
+}
+
+/** Options for {@link IdentityClient.resolveByAttributes}. */
+export interface ResolveByAttributesOptions {
+  /**
+   * Opt-in to consulting personal contacts before/alongside the overlay. Default `false`.
+   * See {@link ResolveByIdentityKeyOptions.useContacts}.
+   */
+  useContacts?: boolean
+  /** Legacy alias for {@link useContacts}. Takes precedence when provided. */
+  overrideWithContacts?: boolean
+  /**
+   * When `true` (and {@link useContacts} is also true), fire contacts and overlay in parallel.
+   */
+  parallel?: boolean
+}
+
+/** Normalize either legacy boolean / new options object into a canonical { useContacts, parallel }. */
+function normalizeOpts (
+  raw: boolean | ResolveByIdentityKeyOptions | ResolveByAttributesOptions | undefined
+): { useContacts: boolean, parallel: boolean } {
+  if (raw === undefined) return { useContacts: false, parallel: false }
+  if (typeof raw === 'boolean') return { useContacts: raw, parallel: false }
+  const useContacts = raw.overrideWithContacts ?? raw.useContacts ?? false
+  return { useContacts, parallel: raw.parallel === true }
+}
+
 /**
  * IdentityClient lets you discover who others are, and let the world know who you are.
  */
@@ -69,7 +137,8 @@ export class IdentityClient {
         certificate.signature
       )
       await masterCert.verify()
-    } catch (error) {
+    } catch (_certVerificationError) {
+      // Low-level cert error details are suppressed — surface a user-facing message only
       throw new Error('Public reveal failed: Certificate verification failed!')
     }
 
@@ -97,7 +166,7 @@ export class IdentityClient {
       true,
       true
     )
-    // TODO: Consider verification and if this is necessary
+    // Consider verification and if this is necessary
     // counterpartyCanVerifyMyOwnership: true
 
     const { tx } = await this.wallet.createAction(
@@ -128,67 +197,125 @@ export class IdentityClient {
   }
 
   /**
-   * Resolves displayable identity certificates, issued to a given identity key by a trusted certifier.
+   * Resolves displayable identity certificates issued to a given identity key.
+   *
+   * **Default behavior (changed): contacts are NOT consulted.** Most clients have no
+   * contacts saved locally, so the previous "contacts-first" default paid setup cost for no
+   * gain. Pass `{ useContacts: true }` to opt in — appropriate when you know the user has
+   * saved contacts and prefers a local hit over a fresh overlay answer.
+   *
+   * When `useContacts: true`:
+   *  - Default short-circuits: if a contact matches, the overlay is skipped entirely.
+   *  - `{ parallel: true }` fires contacts and overlay in parallel; contact wins on hit.
    *
-   * @param {DiscoverByIdentityKeyArgs} args - Arguments for requesting the discovery based on the identity key.
-   * @param {boolean} [overrideWithContacts=true] - Whether to override the results with personal contacts if available.
-   * @returns {Promise<DisplayableIdentity[]>} The promise resolves to displayable identities.
+   * @param args - Arguments for requesting the discovery based on the identity key.
+   * @param opts - Boolean (legacy) or options object. Boolean `true` ≡ `{ useContacts: true }`.
    */
   async resolveByIdentityKey (
     args: DiscoverByIdentityKeyArgs,
-    overrideWithContacts = true
+    opts: boolean | ResolveByIdentityKeyOptions = false
   ): Promise<DisplayableIdentity[]> {
-    // Run both queries in parallel for better performance
+    const { useContacts, parallel } = normalizeOpts(opts)
+
+    // Fast path: skip contacts entirely. Default — straight overlay query,
+    // no listOutputs / decrypt / cache churn.
+    if (!useContacts) {
+      const certificatesResult = await this.wallet.discoverByIdentityKey(args, this.originator)
+      const certs = certificatesResult?.certificates ?? []
+      return await IdentityClient.parseIdentities(certs)
+    }
+
+    if (!parallel) {
+      const contacts = await this.contactsManager.getContacts(args.identityKey)
+      if (contacts.length > 0) return contacts
+
+      const certificatesResult = await this.wallet.discoverByIdentityKey(args, this.originator)
+      const certs = certificatesResult?.certificates ?? []
+      return await IdentityClient.parseIdentities(certs)
+    }
+
     const [contacts, certificatesResult] = await Promise.all([
-      overrideWithContacts
-        ? this.contactsManager.getContacts(args.identityKey)
-        : Promise.resolve([]),
+      this.contactsManager.getContacts(args.identityKey),
       this.wallet.discoverByIdentityKey(args, this.originator)
     ])
 
-    // Override results with personal contacts if available
-    if (contacts.length > 0) {
-      return contacts
-    }
-
+    if (contacts.length > 0) return contacts
     const certs = certificatesResult?.certificates ?? []
-    return certs.map((cert) => {
-      return IdentityClient.parseIdentity(cert)
-    })
+    return await IdentityClient.parseIdentities(certs)
   }
 
   /**
-   * Resolves displayable identity certificates by specific identity attributes, issued by a trusted entity.
+   * Resolves displayable identity certificates by specific identity attributes.
    *
-   * @param {DiscoverByAttributesArgs} args - Attributes and optional parameters used to discover certificates.
-   * @param {boolean} [overrideWithContacts=true] - Whether to override the results with personal contacts if available.
-   * @returns {Promise<DisplayableIdentity[]>} The promise resolves to displayable identities.
+   * **Default behavior (changed): contacts are NOT consulted.** See
+   * {@link resolveByIdentityKey} for the reasoning. Pass `{ useContacts: true }` to opt in.
+   *
+   * @param args - Attributes and optional parameters used to discover certificates.
+   * @param opts - Boolean (legacy) or options object. Boolean `true` ≡ `{ useContacts: true }`.
    */
   async resolveByAttributes (
     args: DiscoverByAttributesArgs,
-    overrideWithContacts = true
+    opts: boolean | ResolveByAttributesOptions = false
   ): Promise<DisplayableIdentity[]> {
-    // Run both queries in parallel for better performance
+    const { useContacts, parallel } = normalizeOpts(opts)
+
+    // Fast path: skip contacts entirely.
+    if (!useContacts) {
+      const certificatesResult = await this.wallet.discoverByAttributes(args, this.originator)
+      const certs = certificatesResult?.certificates ?? []
+      return await IdentityClient.parseIdentities(certs)
+    }
+
+    if (!parallel) {
+      const contacts = await this.contactsManager.getContacts()
+      const matches = this.matchContactsByAttributes(contacts, args)
+      if (matches.length > 0) return matches
+
+      const certificatesResult = await this.wallet.discoverByAttributes(args, this.originator)
+      const certs = certificatesResult?.certificates ?? []
+      if (contacts.length === 0) return await IdentityClient.parseIdentities(certs)
+      const contactByKey = new Map<PubKeyHex, Contact>(
+        contacts.map((contact) => [contact.identityKey, contact] as const)
+      )
+      return await IdentityClient.parseIdentitiesWithOverrides(certs, contactByKey)
+    }
+
     const [contacts, certificatesResult] = await Promise.all([
-      overrideWithContacts
-        ? this.contactsManager.getContacts()
-        : Promise.resolve([]),
+      this.contactsManager.getContacts(),
       this.wallet.discoverByAttributes(args, this.originator)
     ])
 
-    // Fast lookup by identityKey
+    const certs = certificatesResult?.certificates ?? []
+    if (contacts.length === 0) return await IdentityClient.parseIdentities(certs)
     const contactByKey = new Map<PubKeyHex, Contact>(
       contacts.map((contact) => [contact.identityKey, contact] as const)
     )
+    return await IdentityClient.parseIdentitiesWithOverrides(certs, contactByKey)
+  }
 
-    // Guard if certificates might be absent
-    const certs = certificatesResult?.certificates ?? []
-
-    // Parse certificates and substitute with contacts where available
-    return certs.map(
-      (cert) =>
-        contactByKey.get(cert.subject) ?? IdentityClient.parseIdentity(cert)
-    )
+  /**
+   * Best-effort match of contacts against a `DiscoverByAttributesArgs.attributes` shape.
+   * Used by the contacts-first path of {@link resolveByAttributes} to decide whether the overlay
+   * can be skipped. Compares string-valued attributes against same-named fields on the contact's
+   * decrypted record. Returns the subset of contacts that match every supplied attribute.
+   */
+  private matchContactsByAttributes (
+    contacts: Contact[],
+    args: DiscoverByAttributesArgs
+  ): Contact[] {
+    const attrs = (args).attributes
+    if (attrs == null || typeof attrs !== 'object' || Array.isArray(attrs)) return []
+    const entries = Object.entries(attrs as Record<string, unknown>).filter(
+      ([, v]) => typeof v === 'string' && v.length > 0
+    ) as Array<[string, string]>
+    if (entries.length === 0) return []
+    return contacts.filter((contact) => {
+      const bag: Record<string, unknown> = {
+        name: contact.name,
+        identityKey: contact.identityKey
+      }
+      return entries.every(([k, v]) => typeof bag[k] === 'string' && (bag[k] as string).toLowerCase() === v.toLowerCase())
+    })
   }
 
   /**
@@ -328,6 +455,45 @@ export class IdentityClient {
     return await this.contactsManager.removeContact(identityKey)
   }
 
+  /**
+   * Parse an array of certificates into DisplayableIdentity records, yielding to the
+   * event loop every {@link PARSE_BATCH_SIZE} entries so large result sets don't hog
+   * the main thread. Equivalent to `certs.map(parseIdentity)` for small inputs.
+   */
+  static async parseIdentities (certs: IdentityCertificate[]): Promise<DisplayableIdentity[]> {
+    const n = certs.length
+    if (n <= PARSE_BATCH_SIZE) {
+      return certs.map((c) => IdentityClient.parseIdentity(c))
+    }
+    const out: DisplayableIdentity[] = new Array(n)
+    for (let i = 0; i < n; i++) {
+      out[i] = IdentityClient.parseIdentity(certs[i])
+      if ((i + 1) % PARSE_BATCH_SIZE === 0) await yieldToEventLoop()
+    }
+    return out
+  }
+
+  /**
+   * Same as {@link parseIdentities} but consults a contact override map keyed by subject
+   * identity key. Used by `resolveByAttributes` when contacts are loaded.
+   */
+  static async parseIdentitiesWithOverrides (
+    certs: IdentityCertificate[],
+    contactByKey: Map<PubKeyHex, Contact>
+  ): Promise<DisplayableIdentity[]> {
+    const n = certs.length
+    if (n <= PARSE_BATCH_SIZE) {
+      return certs.map((cert) => contactByKey.get(cert.subject) ?? IdentityClient.parseIdentity(cert))
+    }
+    const out: DisplayableIdentity[] = new Array(n)
+    for (let i = 0; i < n; i++) {
+      const cert = certs[i]
+      out[i] = contactByKey.get(cert.subject) ?? IdentityClient.parseIdentity(cert)
+      if ((i + 1) % PARSE_BATCH_SIZE === 0) await yieldToEventLoop()
+    }
+    return out
+  }
+
   /**
    * Parse out identity and certifier attributes to display from an IdentityCertificate
    * @param identityToParse - The Identity Certificate to parse
@@ -346,42 +512,42 @@ export class IdentityClient {
         avatarURL = decryptedFields.profilePhoto
         badgeLabel = `X account certified by ${certifierInfo.name}`
         badgeIconURL = certifierInfo.iconUrl
-        badgeClickURL = 'https://socialcert.net' // TODO Make a specific page for this.
+        badgeClickURL = 'https://socialcert.net' // (no dedicated page yet)
         break
       case KNOWN_IDENTITY_TYPES.discordCert:
         name = decryptedFields.userName
         avatarURL = decryptedFields.profilePhoto
         badgeLabel = `Discord account certified by ${certifierInfo.name}`
         badgeIconURL = certifierInfo.iconUrl
-        badgeClickURL = 'https://socialcert.net' // TODO Make a specific page for this.
+        badgeClickURL = 'https://socialcert.net' // (no dedicated page yet)
         break
       case KNOWN_IDENTITY_TYPES.emailCert:
         name = decryptedFields.email
         avatarURL = 'XUTZxep7BBghAJbSBwTjNfmcsDdRFs5EaGEgkESGSgjJVYgMEizu'
         badgeLabel = `Email certified by ${certifierInfo.name}`
         badgeIconURL = certifierInfo.iconUrl
-        badgeClickURL = 'https://socialcert.net' // TODO Make a specific page for this.
+        badgeClickURL = 'https://socialcert.net' // (no dedicated page yet)
         break
       case KNOWN_IDENTITY_TYPES.phoneCert:
         name = decryptedFields.phoneNumber
         avatarURL = 'XUTLxtX3ELNUwRhLwL7kWNGbdnFM8WG2eSLv84J7654oH8HaJWrU'
         badgeLabel = `Phone certified by ${certifierInfo.name}`
         badgeIconURL = certifierInfo.iconUrl
-        badgeClickURL = 'https://socialcert.net' // TODO Make a specific page for this.
+        badgeClickURL = 'https://socialcert.net' // (no dedicated page yet)
         break
       case KNOWN_IDENTITY_TYPES.identiCert:
         name = `${decryptedFields.firstName} ${decryptedFields.lastName}`
         avatarURL = decryptedFields.profilePhoto
         badgeLabel = `Government ID certified by ${certifierInfo.name}`
         badgeIconURL = certifierInfo.iconUrl
-        badgeClickURL = 'https://identicert.me' // TODO Make a specific page for this.
+        badgeClickURL = 'https://identicert.me' // (no dedicated page yet)
         break
       case KNOWN_IDENTITY_TYPES.registrant:
         name = decryptedFields.name
         avatarURL = decryptedFields.icon
         badgeLabel = `Entity certified by ${certifierInfo.name}`
         badgeIconURL = certifierInfo.iconUrl
-        badgeClickURL = 'https://bsv-blockchain.github.io/ts-sdk/reference/identity/' // TODO: Make this doc page exist
+        badgeClickURL = 'https://bsv-blockchain.github.io/ts-sdk/reference/identity/' // (no dedicated page yet)
         break
       case KNOWN_IDENTITY_TYPES.coolCert:
         name = decryptedFields.cool === 'true' ? 'Cool Person!' : 'Not cool!'
@@ -392,14 +558,14 @@ export class IdentityClient {
         badgeLabel =
           'Represents the ability for anyone to access this information.'
         badgeIconURL = 'XUUV39HVPkpmMzYNTx7rpKzJvXfeiVyQWg2vfSpjBAuhunTCA9uG'
-        badgeClickURL = 'https://bsv-blockchain.github.io/ts-sdk/reference/identity/' // TODO: Make this doc page exist
+        badgeClickURL = 'https://bsv-blockchain.github.io/ts-sdk/reference/identity/' // (no dedicated page yet)
         break
       case KNOWN_IDENTITY_TYPES.self:
         name = 'You'
         avatarURL = 'XUT9jHGk2qace148jeCX5rDsMftkSGYKmigLwU2PLLBc7Hm63VYR'
         badgeLabel = 'Represents your ability to access this information.'
         badgeIconURL = 'XUUV39HVPkpmMzYNTx7rpKzJvXfeiVyQWg2vfSpjBAuhunTCA9uG'
-        badgeClickURL = 'https://bsv-blockchain.github.io/ts-sdk/reference/identity/' // TODO: Make this doc page exist
+        badgeClickURL = 'https://bsv-blockchain.github.io/ts-sdk/reference/identity/' // (no dedicated page yet)
         break
       default: {
         const parsed = IdentityClient.tryToParseGenericIdentity(
@@ -455,34 +621,41 @@ export class IdentityClient {
     // Try to construct a name from common field patterns
     const firstName = decryptedFields.firstName
     const lastName = decryptedFields.lastName
-    const fullName =
-      IdentityClient.hasValue(firstName) && IdentityClient.hasValue(lastName)
-        ? `${firstName} ${lastName}`
-        : IdentityClient.hasValue(firstName)
-          ? firstName
-          : IdentityClient.hasValue(lastName)
-            ? lastName
-            : undefined
-
-    const name = IdentityClient.hasValue(decryptedFields.name)
-      ? decryptedFields.name
-      : IdentityClient.hasValue(decryptedFields.userName)
-        ? decryptedFields.userName
-        : (fullName ??
-          (IdentityClient.hasValue(decryptedFields.email)
-            ? decryptedFields.email
-            : defaultIdentity.name))
+    let fullName: string | undefined
+    if (IdentityClient.hasValue(firstName) && IdentityClient.hasValue(lastName)) {
+      fullName = `${firstName} ${lastName}`
+    } else if (IdentityClient.hasValue(firstName)) {
+      fullName = firstName
+    } else if (IdentityClient.hasValue(lastName)) {
+      fullName = lastName
+    }
+
+    let name: string | undefined
+    if (IdentityClient.hasValue(decryptedFields.name)) {
+      name = decryptedFields.name
+    } else if (IdentityClient.hasValue(decryptedFields.userName)) {
+      name = decryptedFields.userName
+    } else if (fullName !== undefined) {
+      name = fullName
+    } else if (IdentityClient.hasValue(decryptedFields.email)) {
+      name = decryptedFields.email
+    } else {
+      name = defaultIdentity.name
+    }
 
     // Try to find an avatar/photo from common field names
-    const avatarURL = IdentityClient.hasValue(decryptedFields.profilePhoto)
-      ? decryptedFields.profilePhoto
-      : IdentityClient.hasValue(decryptedFields.avatar)
-        ? decryptedFields.avatar
-        : IdentityClient.hasValue(decryptedFields.icon)
-          ? decryptedFields.icon
-          : IdentityClient.hasValue(decryptedFields.photo)
-            ? decryptedFields.photo
-            : defaultIdentity.avatarURL
+    let avatarURL: string | undefined
+    if (IdentityClient.hasValue(decryptedFields.profilePhoto)) {
+      avatarURL = decryptedFields.profilePhoto
+    } else if (IdentityClient.hasValue(decryptedFields.avatar)) {
+      avatarURL = decryptedFields.avatar
+    } else if (IdentityClient.hasValue(decryptedFields.icon)) {
+      avatarURL = decryptedFields.icon
+    } else if (IdentityClient.hasValue(decryptedFields.photo)) {
+      avatarURL = decryptedFields.photo
+    } else {
+      avatarURL = defaultIdentity.avatarURL
+    }
 
     // Generate badge information
     const badgeLabel = IdentityClient.hasValue(certifierInfo?.name)

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

@@ -571,7 +571,7 @@ describe('IdentityClient (additional coverage)', () => {
       mockContactsManager.getContacts = jest.fn().mockResolvedValue([contact])
       walletMock.discoverByAttributes = jest.fn().mockResolvedValue({ certificates: [discoveredCertificate] })
 
-      const result = await identityClient.resolveByAttributes({ attributes: { email: 'alice@example.com' } })
+      const result = await identityClient.resolveByAttributes({ attributes: { email: 'alice@example.com' } }, { useContacts: true })
       expect(result[0].name).toBe('Alice From Contact')
     })
 
@@ -764,4 +764,153 @@ describe('IdentityClient (additional coverage)', () => {
       expect(mockContactsManager.removeContact).toHaveBeenCalledWith('key-to-remove')
     })
   })
+
+  // ─── useContacts branches in resolveByIdentityKey / resolveByAttributes ─────
+
+  // Shared helpers — extracted to keep new tests DRY (avoid Sonar duplication gate).
+  const xCert = (subject: string, userName: string): any => ({
+    type: KNOWN_IDENTITY_TYPES.xCert,
+    subject,
+    decryptedFields: { userName, profilePhoto: '' },
+    certifierInfo: { name: 'CX', iconUrl: '' }
+  })
+  const emailCertOf = (subject: string, email: string): any => ({
+    type: KNOWN_IDENTITY_TYPES.emailCert,
+    subject,
+    decryptedFields: { email },
+    certifierInfo: { name: 'EC', iconUrl: '' }
+  })
+  const contactOf = (name: string, identityKey: string): any => ({
+    name, identityKey, avatarURL: '', abbreviatedKey: '', badgeIconURL: '', badgeLabel: '', badgeClickURL: ''
+  })
+  const stubDiscoveryByKey = (contacts: any[], certificates: any[]): void => {
+    identityClient['contactsManager'].getContacts = jest.fn().mockResolvedValue(contacts)
+    walletMock.discoverByIdentityKey = jest.fn().mockResolvedValue({ certificates })
+  }
+  const stubDiscoveryByAttr = (contacts: any[], certificates: any[]): void => {
+    identityClient['contactsManager'].getContacts = jest.fn().mockResolvedValue(contacts)
+    walletMock.discoverByAttributes = jest.fn().mockResolvedValue({ certificates })
+  }
+
+  describe('resolveByIdentityKey with useContacts opt-in', () => {
+    it('contacts miss falls through to overlay (sequential)', async () => {
+      stubDiscoveryByKey([], [xCert('k1', 'XUser')])
+      const result = await identityClient.resolveByIdentityKey({ identityKey: 'k1' }, { useContacts: true })
+      expect(walletMock.discoverByIdentityKey).toHaveBeenCalled()
+      expect(result[0].name).toBe('XUser')
+    })
+
+    it('parallel mode returns contact on hit even though overlay runs', async () => {
+      const contact = contactOf('Cached Alice', 'k2')
+      stubDiscoveryByKey([contact], [])
+      const result = await identityClient.resolveByIdentityKey({ identityKey: 'k2' }, { useContacts: true, parallel: true })
+      expect(walletMock.discoverByIdentityKey).toHaveBeenCalled()
+      expect(result).toEqual([contact])
+    })
+
+    it('parallel mode contacts miss returns parsed overlay results', async () => {
+      stubDiscoveryByKey([], [xCert('k3', 'XOnly')])
+      const result = await identityClient.resolveByIdentityKey({ identityKey: 'k3' }, { useContacts: true, parallel: true })
+      expect(result[0].name).toBe('XOnly')
+    })
+
+    it('legacy boolean opt-in (true) consults contacts', async () => {
+      stubDiscoveryByKey([contactOf('Legacy True', 'k4')], [])
+      const result = await identityClient.resolveByIdentityKey({ identityKey: 'k4' }, true)
+      expect(result[0].name).toBe('Legacy True')
+      expect(walletMock.discoverByIdentityKey).not.toHaveBeenCalled()
+    })
+
+    it('overrideWithContacts legacy alias takes precedence over useContacts', async () => {
+      stubDiscoveryByKey([contactOf('Override Wins', 'k5')], [])
+      const result = await identityClient.resolveByIdentityKey(
+        { identityKey: 'k5' },
+        { useContacts: false, overrideWithContacts: true }
+      )
+      expect(result[0].name).toBe('Override Wins')
+    })
+  })
+
+  describe('resolveByAttributes with useContacts opt-in', () => {
+    it('contacts no-match falls through to overlay with contact overrides applied', async () => {
+      stubDiscoveryByAttr([contactOf('Override Alice', 'k-over')], [emailCertOf('k-over', 'alice@example.com')])
+      const result = await identityClient.resolveByAttributes(
+        { attributes: { email: 'alice@example.com' } },
+        { useContacts: true }
+      )
+      expect(result[0].name).toBe('Override Alice')
+    })
+
+    it('contacts empty + overlay miss returns empty', async () => {
+      stubDiscoveryByAttr([], [])
+      const result = await identityClient.resolveByAttributes(
+        { attributes: { email: 'nobody@example.com' } },
+        { useContacts: true }
+      )
+      expect(result).toEqual([])
+    })
+
+    it('parallel mode with no contacts parses overlay only', async () => {
+      stubDiscoveryByAttr([], [emailCertOf('no-contact-key', 'lone@example.com')])
+      const result = await identityClient.resolveByAttributes(
+        { attributes: { email: 'lone@example.com' } },
+        { useContacts: true, parallel: true }
+      )
+      expect(result[0].name).toBe('lone@example.com')
+    })
+
+    it('parallel mode with contacts applies overrides on overlay results', async () => {
+      stubDiscoveryByAttr([contactOf('Parallel Contact', 'pk')], [emailCertOf('pk', 'p@example.com')])
+      const result = await identityClient.resolveByAttributes(
+        { attributes: { email: 'p@example.com' } },
+        { useContacts: true, parallel: true }
+      )
+      expect(result[0].name).toBe('Parallel Contact')
+    })
+
+    it('matchContactsByAttributes ignores non-string attribute values', async () => {
+      stubDiscoveryByAttr([contactOf('X', 'kkkk')], [])
+      const result = await identityClient.resolveByAttributes(
+        { attributes: { count: 5 as unknown as string } },
+        { useContacts: true }
+      )
+      // No string-valued attrs → matchContactsByAttributes returns [] → overlay path
+      expect(walletMock.discoverByAttributes).toHaveBeenCalled()
+      expect(result).toEqual([])
+    })
+  })
+
+  describe('parseIdentities batched path', () => {
+    it('yields to event loop when batch > PARSE_BATCH_SIZE', async () => {
+      const certs = Array.from({ length: 64 }, (_, i) => xCert(`subject-${i}`, `user-${i}`))
+      const result = await IdentityClient.parseIdentities(certs)
+      expect(result).toHaveLength(64)
+      expect(result[63].name).toBe('user-63')
+    })
+
+    it('parseIdentitiesWithOverrides batches with overrides applied', async () => {
+      const certs = Array.from({ length: 50 }, (_, i) => xCert(`subject-${i}`, `user-${i}`))
+      const overrideMap = new Map<string, any>([
+        ['subject-5', contactOf('Override 5', 'subject-5')],
+        ['subject-40', contactOf('Override 40', 'subject-40')]
+      ])
+      const result = await IdentityClient.parseIdentitiesWithOverrides(certs, overrideMap)
+      expect(result[5].name).toBe('Override 5')
+      expect(result[40].name).toBe('Override 40')
+      expect(result[6].name).toBe('user-6')
+    })
+  })
+
+  describe('yieldToEventLoop scheduler.yield path', () => {
+    const origScheduler = (globalThis as any).scheduler
+    afterEach(() => { (globalThis as any).scheduler = origScheduler })
+
+    it('uses scheduler.yield when available', async () => {
+      const yieldFn = jest.fn().mockResolvedValue(undefined)
+      ;(globalThis as any).scheduler = { yield: yieldFn }
+      const certs = Array.from({ length: 64 }, (_, i) => xCert(`s-${i}`, `u-${i}`))
+      await IdentityClient.parseIdentities(certs)
+      expect(yieldFn).toHaveBeenCalled()
+    })
+  })
 })

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

@@ -260,11 +260,35 @@ describe('IdentityClient', () => {
       mockContactsManager.getContacts = jest.fn().mockResolvedValue([contact])
       walletMock.discoverByIdentityKey = jest.fn().mockResolvedValue({ certificates: [discoveredCertificate] })
 
-      const identities = await identityClient.resolveByIdentityKey({ identityKey: 'alice-identity-key' })
+      const identities = await identityClient.resolveByIdentityKey({ identityKey: 'alice-identity-key' }, { useContacts: true })
 
       expect(identities).toHaveLength(1)
       expect(identities[0].name).toBe('Alice Smith (Personal Contact)') // Contact should be returned, not discovered identity
-      // Both calls fire in parallel, but contacts take priority in the result
+      // With useContacts opt-in, contacts hit short-circuits the overlay query entirely.
+      expect(walletMock.discoverByIdentityKey).not.toHaveBeenCalled()
+    })
+
+    it('should still call the overlay when parallel: true is passed', async () => {
+      const contact = {
+        name: 'Alice Smith (Personal Contact)',
+        identityKey: 'alice-identity-key',
+        avatarURL: 'alice-avatar.png',
+        abbreviatedKey: 'alice-i...',
+        badgeIconURL: '',
+        badgeLabel: '',
+        badgeClickURL: ''
+      }
+      const mockContactsManager = identityClient['contactsManager']
+      mockContactsManager.getContacts = jest.fn().mockResolvedValue([contact])
+      walletMock.discoverByIdentityKey = jest.fn().mockResolvedValue({ certificates: [] })
+
+      const identities = await identityClient.resolveByIdentityKey(
+        { identityKey: 'alice-identity-key' },
+        { useContacts: true, parallel: true }
+      )
+
+      expect(identities).toHaveLength(1)
+      expect(identities[0].name).toBe('Alice Smith (Personal Contact)')
       expect(walletMock.discoverByIdentityKey).toHaveBeenCalled()
     })
   })
@@ -356,7 +380,7 @@ describe('IdentityClient', () => {
       mockContactsManager.getContacts = jest.fn().mockResolvedValue([contact])
       walletMock.discoverByAttributes = jest.fn().mockResolvedValue({ certificates: [discoveredCertificate] })
 
-      const identities = await identityClient.resolveByAttributes({ attributes: { name: 'Alice' } })
+      const identities = await identityClient.resolveByAttributes({ attributes: { name: 'Alice' } }, { useContacts: true })
 
       expect(identities).toHaveLength(1)
       expect(identities[0].name).toBe('Alice Smith (Personal)') // Contact should be returned, not discovered identity