@meshconnect/uwc-core 1.2.3-snapshot.bd9aae7 → 1.2.3-snapshot.dcfdbbf

package/src/observability/lifecycle-bridge.ts

@@ -29,11 +29,23 @@ export interface AttachLifecycleOptions {
    * The active connector's `onLifecycleEvent` (already bound). `undefined` when the
    * connector can't observe lifecycle at all; the value it returns is `undefined`
    * when THIS session can't be observed (e.g. no live `.on`). Either way the
-   * bridge emits `lifecycleTelemetryUnavailable` and becomes a no-op.
+   * bridge emits `lifecycleTelemetryUnavailable` and becomes a no-op FOR THIS
+   * STREAM — `subscribeAccounts` below is attached independently.
    */
   subscribe:
     | ((l: (e: WalletLifecycleEvent) => void) => (() => void) | undefined)
     | undefined
+  /**
+   * The active connector's `onAccountsChanged` (already bound), carrying the
+   * REAL account list — a separate concern from `subscribe` above (some
+   * connectors, e.g. Tron today, implement one without the other). Absent
+   * entirely when the connector doesn't support real account-sync.
+   */
+  subscribeAccounts?:
+    | ((l: (accounts: string[]) => void) => (() => void) | undefined)
+    | undefined
+  /** Invoked with the resolved (post-echo-filter) real account list whenever `subscribeAccounts` delivers one. Required whenever `subscribeAccounts` is provided. */
+  onAccountsChanged?: (accounts: string[]) => void
   /** Resolved per-event so a mid-session account/chain change is reflected. */
   getRouting: () => LifecycleRouting
   connectionMode: ConnectionMode
@@ -42,8 +54,9 @@ export interface AttachLifecycleOptions {
   /** Direct page vs production iframe — stamped on `lifecycleTelemetryUnavailable`. */
   runtime?: 'direct' | 'iframe'
   /**
-   * Window (ms) within which a wallet `chainChanged` is treated as the echo of a
-   * UWC-initiated `switchNetwork` and suppressed. Default 3000.
+   * Window (ms) within which a wallet `chainChanged`/`accountsChanged` is
+   * treated as the echo of a UWC-initiated `switchNetwork` and suppressed.
+   * Default 3000.
    */
   echoWindowMs?: number
   /**
@@ -53,29 +66,37 @@ export interface AttachLifecycleOptions {
    * provider's echo would otherwise surface as wallet-initiated. Same one-shot
    * consume semantics as a bus-armed switch.
    */
-  initialSwitch?: { chainId: NetworkId; at: number } | undefined
+  initialSwitch?:
+    | { chainId: NetworkId; address?: string; at: number }
+    | undefined
   now?: () => number
 }
 
 /**
  * Bridge a connector's PII-safe `WalletLifecycleEvent` stream onto the event bus
  * as `walletAccountChanged` / `walletChainChanged` / `walletDisconnected` /
- * `walletSessionExpired`.
+ * `walletSessionExpired`, AND (separately) forward the connector's real
+ * account list to `onAccountsChanged` for session-sync.
  *
- * Two correctness concerns are handled here:
+ * Three correctness concerns are handled here:
  *  - **Echo suppression.** When UWC drives a `switchNetwork`, the wallet emits its
- *    own `chainChanged` for the same chain — that's already captured by UWC's
- *    `networkSwitched` / the switch handoff, so re-emitting it as a wallet-
- *    initiated `walletChainChanged` would double-count. We watch the bus for
- *    `networkSwitched` and drop a matching `chainChanged` inside `echoWindowMs`.
- *  - **Availability is signal.** If the connector can't observe lifecycle, we emit
- *    `lifecycleTelemetryUnavailable` ONCE so a dashboard can tell "silent" from
- *    "unwired".
+ *    own `chainChanged`/`accountsChanged` for the same change — that's already
+ *    captured by UWC's `networkSwitched` / the switch handoff, so re-emitting it
+ *    would double-count. We watch the bus for `networkSwitched` and drop a
+ *    matching echo of either kind inside `echoWindowMs`.
+ *  - **Availability is signal, per stream.** If the connector can't observe
+ *    telemetry lifecycle, we emit `lifecycleTelemetryUnavailable` ONCE — but
+ *    that signal is specific to the TELEMETRY stream. A connector missing
+ *    `onLifecycleEvent` but implementing `onAccountsChanged` (e.g. Tron today)
+ *    still gets real account-sync; the two streams are independently attached.
+ *  - **Shared emission budget.** Both streams count against the same
+ *    `MAX_LIFECYCLE_EVENTS_PER_ATTACHMENT` ceiling — a storming provider
+ *    doesn't get double budget just because two streams exist.
  *
- * @returns a teardown that removes the connector subscription AND the bus watcher.
+ * @returns a teardown that removes both connector subscriptions AND the bus watcher.
  */
 export function attachLifecycle(opts: AttachLifecycleOptions): () => void {
-  const { eventManager, subscribe, getRouting } = opts
+  const { eventManager, subscribe, subscribeAccounts, getRouting } = opts
   const runtime = opts.runtime ?? 'direct'
   const now = opts.now ?? Date.now
   const echoWindowMs = opts.echoWindowMs ?? 3000
@@ -89,11 +110,11 @@ export function attachLifecycle(opts: AttachLifecycleOptions): () => void {
       runtime
     })
 
-  if (!subscribe) {
+  if (!subscribe && !subscribeAccounts) {
     // In the production iframe the injected subscription is deliberately not
     // attempted (the provider is a Comlink proxy) — the BRIDGE, not the connector,
-    // is why lifecycle is unobservable. On the direct page, a connector with no
-    // `onLifecycleEvent` simply has no lifecycle support for this namespace yet.
+    // is why lifecycle is unobservable. On the direct page, a connector with
+    // neither stream simply has no lifecycle support for this namespace yet.
     emitUnavailable(
       runtime === 'iframe'
         ? 'bridge_subscription_unavailable'
@@ -102,115 +123,206 @@ export function attachLifecycle(opts: AttachLifecycleOptions): () => void {
     return () => {}
   }
 
-  // Record UWC-initiated switches so the wallet's chainChanged echo can be
-  // dropped. Armed from BOTH signals: `awaitingWallet` (operation switchNetwork)
-  // arms at the handoff START, because some providers emit their chainChanged
-  // BEFORE the switch request resolves — i.e. before `networkSwitched` exists —
-  // and `networkSwitched` re-arms at completion for the late-echo case. The
-  // re-arm means one extra suppression window can follow an early echo; the
-  // only event it could swallow is a sub-window user re-switch to the chain
-  // that just became active — accepted over double-counting every early echo.
-  let lastSwitch: { chainId: NetworkId; at: number } | undefined =
-    opts.initialSwitch
+  // Record UWC-initiated switches so a wallet echo can be dropped. Armed from
+  // BOTH signals: `awaitingWallet` (operation switchNetwork) arms at the
+  // handoff START, because some providers emit their chainChanged BEFORE the
+  // switch request resolves, and `networkSwitched` re-arms at completion
+  // (also carrying the resolved address, for the accounts echo check — the
+  // target address isn't known before the switch resolves, so there is no
+  // early-arm equivalent for the address half).
+  //
+  // A LIST, not a single slot: two rapid, back-to-back switches (A then B)
+  // each get their own pending entry. A single slot would have the SECOND
+  // switch's arm silently erase the FIRST switch's still-unconsumed window,
+  // so a delayed wallet echo for A (arriving after B has already completed)
+  // would be misclassified as a genuine wallet-initiated change instead of
+  // the suppressed echo it actually is.
+  type PendingSwitch = {
+    chainId?: NetworkId | undefined
+    address?: string | undefined
+    at: number
+  }
+  let pendingSwitches: PendingSwitch[] = opts.initialSwitch
+    ? [opts.initialSwitch]
+    : []
+  const pruneExpired = () => {
+    pendingSwitches = pendingSwitches.filter(p => now() - p.at <= echoWindowMs)
+  }
+  // `awaitingWallet` then `networkSwitched` are usually the START and
+  // COMPLETION of the SAME switch — re-arming updates that existing entry
+  // (refreshing `at`, adding the resolved address) rather than pushing a
+  // duplicate, which would otherwise leave a phantom entry behind after only
+  // one of the two is consumed by a single wallet echo.
+  const armOrRearm = (partial: {
+    chainId?: NetworkId | undefined
+    address?: string | undefined
+  }) => {
+    pruneExpired()
+    if (partial.chainId !== undefined) {
+      const idx = pendingSwitches.findIndex(p => p.chainId === partial.chainId)
+      if (idx !== -1) {
+        pendingSwitches[idx] = {
+          ...pendingSwitches[idx]!,
+          ...partial,
+          at: now()
+        }
+        return
+      }
+    }
+    pendingSwitches.push({ ...partial, at: now() })
+  }
   const offAwaiting = eventManager.on('awaitingWallet', data => {
     if (data.operation === 'switchNetwork' && data.chainId !== undefined) {
-      lastSwitch = { chainId: data.chainId, at: now() }
+      armOrRearm({ chainId: data.chainId })
     }
   })
   const offSwitched = eventManager.on('networkSwitched', data => {
-    lastSwitch = { chainId: data.network.id, at: now() }
+    armOrRearm({ chainId: data.network.id, address: data.address })
   })
   const detachBusWatchers = () => {
     offAwaiting()
     offSwitched()
   }
 
+  // Emission budget for THIS attachment, shared across both streams —
+  // suppressed echoes don't spend it.
+  let emitted = 0
+  let capNotified = false
+  const overCap = (): boolean => {
+    if (emitted >= MAX_LIFECYCLE_EVENTS_PER_ATTACHMENT) {
+      // Mark the trip ONCE — a silent cap would be indistinguishable from a
+      // provider that simply went quiet.
+      if (!capNotified) {
+        capNotified = true
+        emitUnavailable('emission_cap')
+      }
+      return true
+    }
+    return false
+  }
+
   // Defense-in-depth: a connector whose subscribe THROWS (e.g. a provider whose
   // `.on` rejects an un-proxied handler across the iframe bridge) must degrade to
   // "unavailable", never break the connect path that called us.
   let unsub: (() => void) | undefined
-  // Emission budget for THIS attachment — suppressed echoes don't spend it.
-  let emitted = 0
-  let capNotified = false
-  try {
-    unsub = subscribe(e => {
-      // The whole body is guarded: wallet SDKs dispatch their listeners
-      // unguarded (e.g. TonConnect's bare `forEach`), so a throw here — from
-      // `getRouting()` or any future edit — would abort delivery to the
-      // wallet's OWN later subscribers, including one resolving a pending
-      // connect. Telemetry must never do that.
-      try {
-        if (emitted >= MAX_LIFECYCLE_EVENTS_PER_ATTACHMENT) {
-          // Mark the trip ONCE — a silent cap would be indistinguishable from a
-          // provider that simply went quiet.
-          if (!capNotified) {
-            capNotified = true
-            emitUnavailable('emission_cap')
+  if (subscribe) {
+    try {
+      unsub = subscribe(e => {
+        // The whole body is guarded: wallet SDKs dispatch their listeners
+        // unguarded (e.g. TonConnect's bare `forEach`), so a throw here would
+        // abort delivery to the wallet's OWN later subscribers, including one
+        // resolving a pending connect. Telemetry must never do that.
+        try {
+          if (overCap()) return
+          const routing = getRouting()
+          switch (e.type) {
+            case 'accountChanged':
+              emitted++
+              eventManager.emit('walletAccountChanged', routing)
+              return
+            case 'chainChanged': {
+              pruneExpired()
+              const idx =
+                e.chainId !== undefined
+                  ? pendingSwitches.findIndex(
+                      p => p.chainId !== undefined && p.chainId === e.chainId
+                    )
+                  : -1
+              if (idx !== -1) {
+                // Consume the echo: a UWC switch produces exactly one wallet echo, so
+                // a LATER chainChanged to the same chain inside the window is a genuine
+                // user-initiated switch-back and must not be suppressed. Only the
+                // chain half is consumed — a still-pending address echo (if the
+                // switch also changed address format) must still be checked; drop the
+                // entry entirely once nothing is left pending on it.
+                const entry = pendingSwitches[idx]!
+                if (entry.address !== undefined) {
+                  pendingSwitches[idx] = { ...entry, chainId: undefined }
+                } else {
+                  pendingSwitches.splice(idx, 1)
+                }
+                return
+              }
+              emitted++
+              eventManager.emit('walletChainChanged', {
+                ...routing,
+                ...(e.chainId !== undefined ? { chainId: e.chainId } : {})
+              })
+              return
+            }
+            case 'disconnect':
+              emitted++
+              eventManager.emit('walletDisconnected', routing)
+              return
+            case 'sessionExpired':
+              emitted++
+              eventManager.emit('walletSessionExpired', routing)
+              return
           }
-          return
+        } catch {
+          // Swallowed: better to drop one lifecycle record than to break the
+          // wallet's event dispatch.
         }
-        const routing = getRouting()
-        switch (e.type) {
-          case 'accountChanged':
-            emitted++
-            eventManager.emit('walletAccountChanged', routing)
-            return
-          case 'chainChanged': {
-            const isEcho =
-              !!lastSwitch &&
-              e.chainId !== undefined &&
-              lastSwitch.chainId === e.chainId &&
-              now() - lastSwitch.at <= echoWindowMs
-            if (isEcho) {
-              // Consume the echo: a UWC switch produces exactly one wallet echo, so
-              // a LATER chainChanged to the same chain inside the window is a genuine
-              // user-initiated switch-back and must not be suppressed.
-              lastSwitch = undefined
-              return
+      })
+    } catch {
+      unsub = undefined
+    }
+    if (!unsub) {
+      // The connector accepted the subscribe call but this session has no
+      // observable telemetry surface (returned undefined or threw). Over the
+      // bridge, that absence is the bridge's doing, not the provider's.
+      emitUnavailable(
+        runtime === 'iframe'
+          ? 'bridge_subscription_unavailable'
+          : 'provider_subscription_unavailable'
+      )
+    }
+  }
+
+  let unsubAccounts: (() => void) | undefined
+  if (subscribeAccounts) {
+    try {
+      unsubAccounts = subscribeAccounts(accounts => {
+        try {
+          if (overCap()) return
+          const primary = accounts[0]
+          pruneExpired()
+          const idx =
+            accounts.length > 0
+              ? pendingSwitches.findIndex(
+                  p => p.address !== undefined && p.address === primary
+                )
+              : -1
+          if (idx !== -1) {
+            // Same one-shot consume as the chainChanged echo above, mirrored
+            // for the address half.
+            const entry = pendingSwitches[idx]!
+            if (entry.chainId !== undefined) {
+              pendingSwitches[idx] = { ...entry, address: undefined }
+            } else {
+              pendingSwitches.splice(idx, 1)
             }
-            emitted++
-            eventManager.emit('walletChainChanged', {
-              ...routing,
-              ...(e.chainId !== undefined ? { chainId: e.chainId } : {})
-            })
             return
           }
-          case 'disconnect':
-            emitted++
-            eventManager.emit('walletDisconnected', routing)
-            return
-          case 'sessionExpired':
-            emitted++
-            eventManager.emit('walletSessionExpired', routing)
-            return
+          emitted++
+          opts.onAccountsChanged?.(accounts)
+        } catch {
+          // Swallowed: never break the wallet SDK's own listener dispatch.
         }
-      } catch {
-        // Swallowed: better to drop one lifecycle record than to break the
-        // wallet's event dispatch.
-      }
-    })
-  } catch {
-    unsub = undefined
+      })
+    } catch {
+      unsubAccounts = undefined
+    }
   }
 
-  // The connector accepted the subscribe call but this session has no observable
-  // surface (returned undefined) or threw — treat as "unavailable" and don't
-  // leave the bus watchers attached.
-  if (!unsub) {
+  if (!unsub && !unsubAccounts) {
     detachBusWatchers()
-    // `onLifecycleEvent` ran but exposed no live subscription surface for this
-    // session (returned undefined or threw). Over the bridge, that absence is the
-    // bridge's doing, not the provider's.
-    emitUnavailable(
-      runtime === 'iframe'
-        ? 'bridge_subscription_unavailable'
-        : 'provider_subscription_unavailable'
-    )
     return () => {}
   }
 
   return () => {
     detachBusWatchers()
-    unsub()
+    unsub?.()
+    unsubAccounts?.()
   }
 }

package/src/observability/telemetry.test.ts

@@ -520,41 +520,6 @@ describe('normalizeEvent', () => {
     expect(JSON.stringify(out)).not.toContain('0xAbC123')
   })
 
-  it('normalizes relayDisconnected as an unclassified walletConnect signal, message scrubbed', () => {
-    const out = normalizeEvent(
-      'relayDisconnected',
-      {
-        error: {
-          type: 'unknown',
-          message: 'transport closed 0xAbC1230000000000000000000000000000000000'
-        }
-      },
-      SDK_SESSION,
-      NOW
-    )
-    expect(out.connectionMode).toBe('walletConnect')
-    expect(out.source).toBe('provider')
-    // A drop is observational, NOT a failure — must never carry a failureKind
-    // (else it inflates failure metrics).
-    expect(out.failureKind).toBeUndefined()
-    expect(JSON.stringify(out)).not.toContain('0xAbC123')
-  })
-
-  it('normalizes relayDisconnected with no reason (clean drop) — no error field', () => {
-    const out = normalizeEvent('relayDisconnected', {}, SDK_SESSION, NOW)
-    expect(out.connectionMode).toBe('walletConnect')
-    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,14 +154,6 @@ 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
 }
 
 /**
@@ -370,10 +362,7 @@ function buildTelemetryEvent<K extends UWCEventName>(
         durationMs: d.durationMs,
         timedOut: d.timedOut,
         timeoutMs: d.timeoutMs,
-        targetAlreadyActive: d.targetAlreadyActive,
-        backgroundedMs: d.backgroundedMs,
-        backgroundCount: d.backgroundCount,
-        relayDropCount: d.relayDropCount
+        targetAlreadyActive: d.targetAlreadyActive
       }
     }
     case 'walletRejected': {
@@ -392,10 +381,7 @@ function buildTelemetryEvent<K extends UWCEventName>(
         targetAlreadyActive: d.targetAlreadyActive,
         errorCode: d.errorCode,
         failureKind: d.failureKind,
-        source: d.source,
-        backgroundedMs: d.backgroundedMs,
-        backgroundCount: d.backgroundCount,
-        relayDropCount: d.relayDropCount
+        source: d.source
       }
     }
     case 'walletTimedOut': {
@@ -410,10 +396,7 @@ function buildTelemetryEvent<K extends UWCEventName>(
         handoffId: d.handoffId,
         durationMs: d.durationMs,
         timeoutMs: d.timeoutMs,
-        targetAlreadyActive: d.targetAlreadyActive,
-        backgroundedMs: d.backgroundedMs,
-        backgroundCount: d.backgroundCount,
-        relayDropCount: d.relayDropCount
+        targetAlreadyActive: d.targetAlreadyActive
       }
     }
     case 'walletFailed': {
@@ -433,10 +416,7 @@ function buildTelemetryEvent<K extends UWCEventName>(
         errorCode: d.errorCode,
         failureKind: d.failureKind,
         source: d.source,
-        error: { type: d.error.type, message: scrubMessage(d.error.message) },
-        backgroundedMs: d.backgroundedMs,
-        backgroundCount: d.backgroundCount,
-        relayDropCount: d.relayDropCount
+        error: { type: d.error.type, message: scrubMessage(d.error.message) }
       }
     }
     case 'capabilitiesUpdated': {
@@ -468,15 +448,8 @@ function buildTelemetryEvent<K extends UWCEventName>(
     }
     case 'pageHiddenDuringHandoff':
     case 'pageVisibleDuringHandoff': {
-      // 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
-      }
+      const d = data as UWCEventMap['pageHiddenDuringHandoff']
+      return { ...base, handoffId: d.handoffId, platform: d.platform }
     }
     case 'bridgeError': {
       const d = data as UWCEventMap['bridgeError']
@@ -500,31 +473,6 @@ function buildTelemetryEvent<K extends UWCEventName>(
         error: { type: d.error.type, message: scrubMessage(d.error.message) }
       }
     }
-    case 'relayDisconnected': {
-      const d = data as UWCEventMap['relayDisconnected']
-      // The relay socket dropped. Observational, NOT a failure: a drop only
-      // matters if a round-trip was in flight — deliberately left without a
-      // `failureKind` so it never inflates failure metrics. Pair with
-      // `relayReconnected` (same sdkSessionId) for the dead-window duration.
-      return {
-        ...base,
-        connectionMode: 'walletConnect',
-        source: 'provider',
-        ...(d.error
-          ? {
-              error: {
-                type: d.error.type,
-                message: scrubMessage(d.error.message)
-              }
-            }
-          : {})
-      }
-    }
-    case 'relayReconnected': {
-      // Socket recovered. Name-only + mode; the diagnostic value is the timestamp
-      // relative to the paired `relayDisconnected`.
-      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