@meshconnect/uwc-core 1.10.4 → 2.0.0

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,235 @@ 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)
+  }
+  // Address equality for echo suppression is case-insensitive on EVM: a
+  // UWC-initiated `switchNetwork` echo and the wallet's `accountsChanged` can
+  // differ in casing (checksummed vs lowercased), and a missed match would
+  // double-count the echo as a wallet-initiated account change. Solana / TRON /
+  // TON addresses are case-sensitive, so only fold case for eip155.
+  const normAddr = (addr: string | undefined): string | undefined =>
+    addr !== undefined && opts.namespace === 'eip155'
+      ? addr.toLowerCase()
+      : addr
+  // `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 — telemetry ONLY. Account-sync
+  // (`onAccountsChanged`) is a BEHAVIOUR path (it keeps the live signer fresh),
+  // so it must never be silenced by a telemetry ceiling: a wallet that re-fires
+  // `accountsChanged` on focus would otherwise burn the budget and re-serve a
+  // stale signer — the exact bug this attachment closes. It's deduped instead
+  // (see `lastAccountSignal`). Suppressed echoes don't spend the budget.
+  let emitted = 0
+  // Last account signal actually reflected into the session (normalized primary,
+  // or '' for a disconnect). Dedupes an unchanged re-fire so account-sync stays
+  // uncapped without churning `updateSession` on every focus event.
+  let lastAccountSignal: string | undefined = undefined
+  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 {
+          // NOT gated by the telemetry cap — account-sync is a behaviour path
+          // and must always follow a real switch (see `lastAccountSignal`).
+          const primary = accounts[0]
+          const primaryNorm = normAddr(primary)
+          const signal = accounts.length === 0 ? '' : (primaryNorm ?? '')
+          pruneExpired()
+          const idx =
+            accounts.length > 0
+              ? pendingSwitches.findIndex(
+                  p =>
+                    p.address !== undefined &&
+                    normAddr(p.address) === primaryNorm
+                )
+              : -1
+          if (idx !== -1) {
+            // Same one-shot consume as the chainChanged echo above, mirrored
+            // for the address half. The session already reflects this address
+            // (the UWC switch set it), so record the signal to dedupe a later
+            // identical re-fire, then swallow the echo.
+            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 } : {})
-            })
+            lastAccountSignal = signal
             return
           }
-          case 'disconnect':
-            emitted++
-            eventManager.emit('walletDisconnected', routing)
-            return
-          case 'sessionExpired':
-            emitted++
-            eventManager.emit('walletSessionExpired', routing)
-            return
+          // Dedupe an unchanged re-fire (e.g. the wallet re-emitting the same
+          // account on window focus) so we don't re-write the session for a
+          // non-change. A genuine A→B→A still propagates each leg.
+          if (signal === lastAccountSignal) return
+          lastAccountSignal = signal
+          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?.()
   }
 }