@meshconnect/uwc-core 1.2.3 → 1.3.0

package/src/observability/instrument-handoff.test.ts

@@ -47,6 +47,68 @@ describe('instrumentHandoff', () => {
     expect(end.timedOut).toBe(false)
   })
 
+  it('counts relay-socket drops seen during the handoff onto the terminal', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    const wcCtx: HandoffContext = { ...CTX, connectionMode: 'walletConnect' }
+    await instrumentHandoff(
+      { eventManager: em, timeoutMs: 0 },
+      wcCtx,
+      async () => {
+        // The relay socket drops (and recovers) while the sign request is pending.
+        em.emit('relayDisconnected', undefined)
+        em.emit('relayReconnected', undefined)
+        em.emit('relayDisconnected', undefined)
+        return 'sig'
+      }
+    )
+    const end = seen.find(s => s.name === 'walletSucceeded')?.data as {
+      relayDropCount: number
+      backgroundCount: number
+      backgroundedMs: number
+    }
+    expect(end.relayDropCount).toBe(2)
+    // No backgrounding occurred in this test runtime.
+    expect(end.backgroundCount).toBe(0)
+    expect(end.backgroundedMs).toBe(0)
+  })
+
+  it('stops counting relay drops once the handoff settles', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    const wcCtx: HandoffContext = { ...CTX, connectionMode: 'walletConnect' }
+    await instrumentHandoff(
+      { eventManager: em, timeoutMs: 0 },
+      wcCtx,
+      async () => 'sig'
+    )
+    // A drop after settle must be ignored (listener removed) and never throw.
+    expect(() => em.emit('relayDisconnected', undefined)).not.toThrow()
+    const end = seen.find(s => s.name === 'walletSucceeded')?.data as {
+      relayDropCount: number
+    }
+    expect(end.relayDropCount).toBe(0)
+  })
+
+  it('omits relayDropCount for non-WalletConnect handoffs (no misattribution)', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    // A WC relay flap firing during an injected handoff must NOT be attributed to it.
+    await instrumentHandoff(
+      { eventManager: em, timeoutMs: 0 },
+      CTX,
+      async () => {
+        em.emit('relayDisconnected', undefined)
+        return 'sig'
+      }
+    )
+    const end = seen.find(s => s.name === 'walletSucceeded')?.data as {
+      relayDropCount?: number
+    }
+    // Undefined on the bus → dropped by compactUndefined on the telemetry egress.
+    expect(end.relayDropCount).toBeUndefined()
+  })
+
   it('carries targetAlreadyActive through awaitingWallet and the terminal', async () => {
     const em = new EventManager()
     const seen = record(em)

package/src/observability/instrument-handoff.ts

@@ -15,6 +15,7 @@ import {
 } from '../utils/to-wallet-error'
 import { derivePlatform, deriveWalletFlowType } from './telemetry'
 import { trackFocusDuringHandoff } from './focus-tracker'
+import { trackRelayDropsDuringHandoff } from './relay-drop-tracker'
 
 /** Routing facets known at the moment of a wallet handoff. No address, no payload. */
 export interface HandoffContext {
@@ -141,7 +142,32 @@ export async function instrumentHandoff<T>(
   // Observe page-visibility transitions ONLY while this handoff is pending — the
   // app-switch signal for deep-link flows (left for the wallet / came back). The
   // teardown in `finally` removes the listeners the instant the op settles.
-  const stopFocus = trackFocusDuringHandoff(eventManager, handoffId, platform)
+  // Pass `now` through so backgroundedMs shares the same clock as durationMs
+  // (consistent, and deterministic under an injected clock in tests).
+  const focus = trackFocusDuringHandoff(
+    eventManager,
+    handoffId,
+    platform,
+    undefined,
+    undefined,
+    now
+  )
+
+  // Count relay-socket drops seen while this handoff is pending (WalletConnect
+  // only — the tracker is a no-op for other modes so a WC relay flap isn't
+  // misattributed to an injected/TON handoff in flight at the same time).
+  const relayDrops = trackRelayDropsDuringHandoff(
+    eventManager,
+    context.connectionMode
+  )
+
+  // Backgrounding + relay-drop summary, snapshotted onto each terminal so ONE
+  // event answers "backgrounded? how long? socket dropped? recovered?".
+  // `relayDropCount` is undefined off WalletConnect so `compactUndefined` drops it.
+  const handoffMetrics = () => ({
+    ...focus.summary(),
+    ...relayDrops.summary()
+  })
 
   // Same routing facets as `awaitingWallet` so every terminal is self-describing
   // (no handoffId self-join needed to know which wallet / chain / mode it closed).
@@ -164,7 +190,8 @@ export async function instrumentHandoff<T>(
           operation: context.operation,
           durationMs: now() - start,
           timeoutMs,
-          ...routing
+          ...routing,
+          ...handoffMetrics()
         })
       }, timeoutMs)
     : undefined
@@ -177,7 +204,8 @@ export async function instrumentHandoff<T>(
       durationMs: now() - start,
       timedOut,
       timeoutMs: timedOut ? timeoutMs : undefined,
-      ...routing
+      ...routing,
+      ...handoffMetrics()
     })
     return result
   } catch (error) {
@@ -207,7 +235,8 @@ export async function instrumentHandoff<T>(
         errorCode,
         failureKind,
         source,
-        ...routing
+        ...routing,
+        ...handoffMetrics()
       })
     } else {
       eventManager.emit('walletFailed', {
@@ -220,12 +249,14 @@ export async function instrumentHandoff<T>(
         errorCode,
         failureKind,
         source,
-        ...routing
+        ...routing,
+        ...handoffMetrics()
       })
     }
     throw error
   } finally {
     if (timer) clearTimeout(timer)
-    stopFocus()
+    relayDrops.stop()
+    focus.stop()
   }
 }

package/src/observability/relay-drop-tracker.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest'
+import { EventManager } from '../managers/event-manager'
+import { trackRelayDropsDuringHandoff } from './relay-drop-tracker'
+
+describe('trackRelayDropsDuringHandoff', () => {
+  it('counts each relay drop seen during a WalletConnect handoff', () => {
+    const em = new EventManager()
+    const tracker = trackRelayDropsDuringHandoff(em, 'walletConnect')
+
+    expect(tracker.summary()).toEqual({ relayDropCount: 0 })
+
+    em.emit('relayDisconnected', undefined)
+    em.emit('relayDisconnected', undefined)
+    expect(tracker.summary()).toEqual({ relayDropCount: 2 })
+  })
+
+  it('reports undefined (not 0) off WalletConnect so the terminal omits the field', () => {
+    // A `0` on an injected handoff would read as "a relay we watched, and it
+    // held" — but no relay is in play, so the field must be absent entirely.
+    const em = new EventManager()
+    for (const mode of ['injected', 'tonConnect'] as const) {
+      const tracker = trackRelayDropsDuringHandoff(em, mode)
+      expect(tracker.summary()).toEqual({ relayDropCount: undefined })
+    }
+  })
+
+  it('does NOT subscribe off WalletConnect — a relay flap on the shared bus is ignored', () => {
+    const em = new EventManager()
+    const tracker = trackRelayDropsDuringHandoff(em, 'injected')
+
+    // The bus is client-global; a WC relay drop firing while an injected handoff
+    // is in flight must not be attributed to it.
+    em.emit('relayDisconnected', undefined)
+    em.emit('relayDisconnected', undefined)
+    expect(tracker.summary()).toEqual({ relayDropCount: undefined })
+  })
+
+  it('stops counting after stop() — drops outside the blind window do not accrue', () => {
+    const em = new EventManager()
+    const tracker = trackRelayDropsDuringHandoff(em, 'walletConnect')
+
+    em.emit('relayDisconnected', undefined)
+    tracker.stop()
+    em.emit('relayDisconnected', undefined)
+    em.emit('relayDisconnected', undefined)
+
+    expect(tracker.summary()).toEqual({ relayDropCount: 1 })
+  })
+
+  it('only counts relayDisconnected — reconnects and other bus events are ignored', () => {
+    const em = new EventManager()
+    const tracker = trackRelayDropsDuringHandoff(em, 'walletConnect')
+
+    em.emit('relayDisconnected', undefined)
+    em.emit('relayReconnected', undefined)
+    em.emit('relayReconnected', undefined)
+
+    expect(tracker.summary()).toEqual({ relayDropCount: 1 })
+  })
+
+  it('stop() is a safe no-op off WalletConnect (nothing was subscribed)', () => {
+    const em = new EventManager()
+    const tracker = trackRelayDropsDuringHandoff(em, 'tonConnect')
+    expect(() => tracker.stop()).not.toThrow()
+    expect(tracker.summary()).toEqual({ relayDropCount: undefined })
+  })
+
+  it('two concurrent WalletConnect handoffs count independently and unsubscribe independently', () => {
+    // The bus is shared; each tracker owns its own listener, so stopping one
+    // must not silence the other (and both saw the same drop).
+    const em = new EventManager()
+    const a = trackRelayDropsDuringHandoff(em, 'walletConnect')
+    const b = trackRelayDropsDuringHandoff(em, 'walletConnect')
+
+    em.emit('relayDisconnected', undefined)
+    expect(a.summary()).toEqual({ relayDropCount: 1 })
+    expect(b.summary()).toEqual({ relayDropCount: 1 })
+
+    a.stop()
+    em.emit('relayDisconnected', undefined)
+    expect(a.summary()).toEqual({ relayDropCount: 1 })
+    expect(b.summary()).toEqual({ relayDropCount: 2 })
+  })
+})

package/src/observability/relay-drop-tracker.ts

@@ -0,0 +1,53 @@
+import type { ConnectionMode } from '@meshconnect/uwc-types'
+import type { EventManager } from '../managers/event-manager'
+
+/** Handle returned by `trackRelayDropsDuringHandoff`. */
+export interface RelayDropHandoffTracker {
+  /**
+   * Remove the relay-drop subscription. Always call on settle (no-op off
+   * WalletConnect, where nothing was subscribed).
+   */
+  stop: () => void
+  /**
+   * Relay-drop count at call time, or `undefined` off WalletConnect. Undefined
+   * (not `0`) so the terminal's `compactUndefined` omits the field entirely — a
+   * `0` on an injected/TON handoff would falsely imply "a WC relay we watched,
+   * and it held", when in fact no relay was in play.
+   */
+  summary: () => { relayDropCount: number | undefined }
+}
+
+/**
+ * While a wallet handoff is pending, count relay-socket drops seen on the UWC
+ * event bus. The WalletConnect client emits `relayDisconnected` once per outage
+ * (see `attachRelayLifecycleListeners`); this is the CARE-263 signal — an
+ * iOS-suspended WebView drops the relay socket mid-handoff and strands the
+ * in-flight sign/connect response until WC core's slow heartbeat reconnects, so
+ * the drop count on a terminal explains a long/failed handoff that focus timing
+ * alone can't.
+ *
+ * WalletConnect ONLY. The relay bus is client-global, so an injected or TON
+ * handoff that happens to be in flight during a WC relay flap would otherwise
+ * misattribute the drop; off WalletConnect this is a no-op tracker whose
+ * `summary()` reports `undefined`. Mirrors `trackFocusDuringHandoff`: attach
+ * right after `awaitingWallet`, and `stop()` (called the instant the op settles)
+ * removes the subscription so drops are only counted during the blind window.
+ */
+export function trackRelayDropsDuringHandoff(
+  eventManager: EventManager,
+  connectionMode: ConnectionMode
+): RelayDropHandoffTracker {
+  if (connectionMode !== 'walletConnect') {
+    return { stop: () => {}, summary: () => ({ relayDropCount: undefined }) }
+  }
+
+  let relayDropCount = 0
+  const off = eventManager.on('relayDisconnected', () => {
+    relayDropCount++
+  })
+
+  return {
+    stop: off,
+    summary: () => ({ relayDropCount })
+  }
+}

package/src/observability/telemetry.test.ts

@@ -520,6 +520,24 @@ describe('normalizeEvent', () => {
     expect(JSON.stringify(out)).not.toContain('0xAbC123')
   })
 
+  it('normalizes relayDisconnected as an unclassified walletConnect signal (void, no reason)', () => {
+    // The relayer carries no payload, so the event is void — never an error, and
+    // observational (no failureKind, so it can't inflate failure metrics).
+    const out = normalizeEvent('relayDisconnected', undefined, SDK_SESSION, NOW)
+    expect(out.connectionMode).toBe('walletConnect')
+    expect(out.source).toBe('provider')
+    expect(out.error).toBeUndefined()
+    expect(out.failureKind).toBeUndefined()
+  })
+
+  it('normalizes relayReconnected as an unclassified walletConnect signal', () => {
+    const out = normalizeEvent('relayReconnected', undefined, SDK_SESSION, NOW)
+    expect(out.name).toBe('relayReconnected')
+    expect(out.connectionMode).toBe('walletConnect')
+    expect(out.source).toBe('provider')
+    expect(out.failureKind).toBeUndefined()
+  })
+
   it('normalizes walletConnectInitError as a walletConnect client_init_failed, message scrubbed', () => {
     const out = normalizeEvent(
       'walletConnectInitError',

package/src/observability/telemetry.ts

@@ -154,6 +154,14 @@ export interface UWCTelemetryEvent {
    * handoffCovered to avoid double-counting.
    */
   handoffCovered?: boolean | undefined
+  /** `pageVisibleDuringHandoff` only: how long the page was hidden for that segment (ms). */
+  hiddenMs?: number | undefined
+  /** Handoff terminals: cumulative time the page was backgrounded during the handoff (ms). */
+  backgroundedMs?: number | undefined
+  /** Handoff terminals: how many times the page was backgrounded during the handoff. */
+  backgroundCount?: number | undefined
+  /** Handoff terminals, WalletConnect only: relay-socket drops seen while the handoff was pending. */
+  relayDropCount?: number | undefined
 }
 
 /**
@@ -362,7 +370,10 @@ function buildTelemetryEvent<K extends UWCEventName>(
         durationMs: d.durationMs,
         timedOut: d.timedOut,
         timeoutMs: d.timeoutMs,
-        targetAlreadyActive: d.targetAlreadyActive
+        targetAlreadyActive: d.targetAlreadyActive,
+        backgroundedMs: d.backgroundedMs,
+        backgroundCount: d.backgroundCount,
+        relayDropCount: d.relayDropCount
       }
     }
     case 'walletRejected': {
@@ -381,7 +392,10 @@ function buildTelemetryEvent<K extends UWCEventName>(
         targetAlreadyActive: d.targetAlreadyActive,
         errorCode: d.errorCode,
         failureKind: d.failureKind,
-        source: d.source
+        source: d.source,
+        backgroundedMs: d.backgroundedMs,
+        backgroundCount: d.backgroundCount,
+        relayDropCount: d.relayDropCount
       }
     }
     case 'walletTimedOut': {
@@ -396,7 +410,10 @@ function buildTelemetryEvent<K extends UWCEventName>(
         handoffId: d.handoffId,
         durationMs: d.durationMs,
         timeoutMs: d.timeoutMs,
-        targetAlreadyActive: d.targetAlreadyActive
+        targetAlreadyActive: d.targetAlreadyActive,
+        backgroundedMs: d.backgroundedMs,
+        backgroundCount: d.backgroundCount,
+        relayDropCount: d.relayDropCount
       }
     }
     case 'walletFailed': {
@@ -416,7 +433,10 @@ function buildTelemetryEvent<K extends UWCEventName>(
         errorCode: d.errorCode,
         failureKind: d.failureKind,
         source: d.source,
-        error: { type: d.error.type, message: scrubMessage(d.error.message) }
+        error: { type: d.error.type, message: scrubMessage(d.error.message) },
+        backgroundedMs: d.backgroundedMs,
+        backgroundCount: d.backgroundCount,
+        relayDropCount: d.relayDropCount
       }
     }
     case 'capabilitiesUpdated': {
@@ -448,8 +468,15 @@ function buildTelemetryEvent<K extends UWCEventName>(
     }
     case 'pageHiddenDuringHandoff':
     case 'pageVisibleDuringHandoff': {
-      const d = data as UWCEventMap['pageHiddenDuringHandoff']
-      return { ...base, handoffId: d.handoffId, platform: d.platform }
+      // Cast to the visible shape (superset). `hiddenMs` is absent on the hidden
+      // event → undefined → dropped by compactUndefined.
+      const d = data as UWCEventMap['pageVisibleDuringHandoff']
+      return {
+        ...base,
+        handoffId: d.handoffId,
+        platform: d.platform,
+        hiddenMs: d.hiddenMs
+      }
     }
     case 'bridgeError': {
       const d = data as UWCEventMap['bridgeError']
@@ -473,6 +500,14 @@ function buildTelemetryEvent<K extends UWCEventName>(
         error: { type: d.error.type, message: scrubMessage(d.error.message) }
       }
     }
+    case 'relayDisconnected':
+    case 'relayReconnected': {
+      // Relay transport lifecycle (WalletConnect). Observational — NOT a failure,
+      // so deliberately no `failureKind` (never inflates failure metrics). The
+      // relayer carries no payload; pair the two by sdkSessionId + timestamp for
+      // the dead-window duration.
+      return { ...base, connectionMode: 'walletConnect', source: 'provider' }
+    }
     case 'walletConnectInitError': {
       const d = data as UWCEventMap['walletConnectInitError']
       // SignClient.init failed — the WC client never came up. Distinct from

package/src/universal-wallet-connector.observability.test.ts

@@ -26,10 +26,10 @@ const reattachLifecycleMock = vi.fn()
 const switchNetworkMock = vi.fn()
 const sendTransactionMock = vi.fn()
 const getWalletCapabilitiesMock = vi.fn()
-// Captures the positional args the façade passes to the WalletConnect connector
-// (config, networkRpcMap, onRelayError, onInitError) so a test can invoke the
-// detached-error sinks and assert the emitted telemetry — this is the only place
-// the sink→event wiring (and its arg order) is exercised.
+// Captures the args the façade passes to the WalletConnect connector
+// (config, networkRpcMap, telemetryObserver) so a test can invoke the relay
+// telemetry sinks and assert the emitted event — this is the only place the
+// sink→bus wiring is exercised.
 const wcConnectorCapture: { args: unknown[] } = { args: [] }
 
 const connectedSession: Session = {
@@ -187,10 +187,14 @@ describe('UniversalWalletConnector — observability wiring', () => {
       walletConnectConfig: { projectId: 'test' }
     })
 
-    // The façade passes the connector (config, networkRpcMap, onRelayError,
-    // onInitError). Grabbing arg[3] and firing it guards both the wiring and the
-    // positional arg order — a swap with onRelayError would surface the wrong event.
-    const onInitError = wcConnectorCapture.args[3] as (e: unknown) => void
+    // The façade passes the connector (config, networkRpcMap, telemetryObserver).
+    // Grabbing the observer's onInitError sink and firing it guards the wiring;
+    // the named field can't be confused with onRelayError the way a positional
+    // arg could (the reason #3350 moved to a typed options object).
+    const telemetryObserver = wcConnectorCapture.args[2] as {
+      onInitError: (e: unknown) => void
+    }
+    const onInitError = telemetryObserver.onInitError
     expect(typeof onInitError).toBe('function')
     onInitError(
       new Error(
@@ -207,6 +211,48 @@ describe('UniversalWalletConnector — observability wiring', () => {
     expect(JSON.stringify(initError)).not.toContain('0xAbC123')
   })
 
+  it('wires the relay observer sinks → each emits its own telemetry event to the observer', () => {
+    // The whole point of #3350: a single typed observer whose named sinks map
+    // 1:1 to bus events. Fire each and assert the right event lands — this is
+    // the connector→bus lambda wiring, previously only covered end-to-end.
+    const events: UWCTelemetryEvent[] = []
+    const observer: UWCObserver = { onEvent: e => events.push(e) }
+    new UniversalWalletConnector({
+      networks,
+      wallets,
+      observer,
+      walletConnectConfig: { projectId: 'test' }
+    })
+
+    const telemetryObserver = wcConnectorCapture.args[2] as {
+      onRelayError: (e: unknown) => void
+      onRelayDisconnect: () => void
+      onRelayReconnect: () => void
+    }
+
+    telemetryObserver.onRelayError(
+      new Error(
+        'WebSocket closed abnormally 0xAbC1230000000000000000000000000000000000'
+      )
+    )
+    telemetryObserver.onRelayDisconnect()
+    telemetryObserver.onRelayReconnect()
+
+    const relayError = events.find(e => e.name === 'relayError')
+    expect(relayError).toBeDefined()
+    expect(relayError!.connectionMode).toBe('walletConnect')
+    // Same egress scrubbing as every other error record.
+    expect(JSON.stringify(relayError)).not.toContain('0xAbC123')
+
+    const dropped = events.find(e => e.name === 'relayDisconnected')
+    expect(dropped).toBeDefined()
+    expect(dropped!.connectionMode).toBe('walletConnect')
+
+    const recovered = events.find(e => e.name === 'relayReconnected')
+    expect(recovered).toBeDefined()
+    expect(recovered!.connectionMode).toBe('walletConnect')
+  })
+
   it('stamps a consumer-supplied correlationId (string) as its own field', async () => {
     const events: UWCTelemetryEvent[] = []
     const uwc = new UniversalWalletConnector({

package/src/universal-wallet-connector.ts

@@ -314,18 +314,28 @@ export class UniversalWalletConnector {
         new WalletConnectConnector(
           configuredWalletConnectConfig,
           this.networkRpcMap,
-          // Surface relay-socket failures (e.g. code 3000 JWT clock skew) that are
-          // detached from the connect handoff, as a telemetry event.
-          (error: unknown) =>
-            this.eventManager.emit('relayError', {
-              error: toWalletError(error)
-            }),
-          // Surface a failed SignClient.init as its own signal — otherwise it has no
-          // dedicated telemetry and only appears as a generic connect failure.
-          (error: unknown) =>
-            this.eventManager.emit('walletConnectInitError', {
-              error: toWalletError(error)
-            })
+          {
+            // Surface relay-socket failures (e.g. code 3000 JWT clock skew) that are
+            // detached from the connect handoff, as a telemetry event.
+            onRelayError: (error: unknown) =>
+              this.eventManager.emit('relayError', {
+                error: toWalletError(error)
+              }),
+            // Surface a failed SignClient.init as its own signal — otherwise it has no
+            // dedicated telemetry and only appears as a generic connect failure.
+            onInitError: (error: unknown) =>
+              this.eventManager.emit('walletConnectInitError', {
+                error: toWalletError(error)
+              }),
+            // Relay transport dropped (once per outage) — the FACT is the signal; the
+            // relayer carries no payload, so emit the bare event (CARE-263).
+            onRelayDisconnect: () =>
+              this.eventManager.emit('relayDisconnected', undefined),
+            // Relay transport recovered — pair with `relayDisconnected` (same
+            // sdkSessionId) to measure the dead window.
+            onRelayReconnect: () =>
+              this.eventManager.emit('relayReconnected', undefined)
+          }
         )
       )
     }

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated from package.json by scripts/generate-version.mjs — do not edit.
-export const UWC_CORE_VERSION = '1.2.3'
+export const UWC_CORE_VERSION = '1.3.0'