@meshconnect/uwc-core 1.1.0 → 1.1.1-snapshot.3edcb6c

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/services/connection-service.test.ts

@@ -863,5 +863,170 @@ describe('ConnectionService', () => {
       // No connection → no lifecycle evaluation, so no "unavailable" noise.
       expect(unavail).toHaveLength(0)
     })
+
+    it('a real accountsChanged from the connector updates activeAddress and emits sessionChanged', async () => {
+      let emitAccounts!: (accounts: string[]) => void
+      mockConnector.onAccountsChanged = (l: (accounts: string[]) => void) => {
+        emitAccounts = l
+        return () => {}
+      }
+      const sessions: Array<{ activeAddress: string | null }> = []
+      eventManager.on('sessionChanged', d =>
+        sessions.push({ activeAddress: d.session.activeAddress })
+      )
+
+      await connectionService.connect('injected', 'metamask', 'eip155:1')
+      emitAccounts(['0xNEW'])
+
+      expect(sessionManager.getSession().activeAddress).toBe('0xNEW')
+      expect(sessions[sessions.length - 1]?.activeAddress).toBe('0xNEW')
+    })
+
+    it('updates the matching availableAddresses entries for the changed namespace', async () => {
+      let emitAccounts!: (accounts: string[]) => void
+      mockConnector.onAccountsChanged = (l: (accounts: string[]) => void) => {
+        emitAccounts = l
+        return () => {}
+      }
+
+      await connectionService.connect('injected', 'metamask', 'eip155:1')
+      emitAccounts(['0xNEW'])
+
+      expect(sessionManager.getSession().availableAddresses).toEqual([
+        { address: '0xNEW', networkId: 'eip155:1' }
+      ])
+    })
+
+    it('an empty accounts list triggers a full disconnect AND calls connector.disconnect for local-state cleanup', async () => {
+      // The wallet already ended the session on its own side, but the
+      // connector's own LOCAL state (e.g. EthereumWalletService's cached
+      // account/uuid) still needs clearing — otherwise a later connect to a
+      // DIFFERENT wallet reads the stale cached account via
+      // checkExistingConnections() and never rebinds to the new wallet's
+      // provider/uuid. disconnect() must still be called here; it's a
+      // fire-and-forget, error-swallowed call (see the next test) so a
+      // protocol-based connector that rejects on an already-closed session
+      // can't break this path.
+      let emitAccounts!: (accounts: string[]) => void
+      mockConnector.onAccountsChanged = (l: (accounts: string[]) => void) => {
+        emitAccounts = l
+        return () => {}
+      }
+      const disconnectSpy = vi.fn().mockResolvedValue(undefined)
+      mockConnector.disconnect = disconnectSpy
+
+      await connectionService.connect('injected', 'metamask', 'eip155:1')
+      emitAccounts([])
+
+      expect(sessionManager.getSession().activeAddress).toBeNull()
+      expect(sessionManager.getSession().connectionMode).toBeNull()
+      expect(disconnectSpy).toHaveBeenCalledTimes(1)
+    })
+
+    it('does not let a rejecting connector.disconnect() break the wallet-initiated disconnect path', async () => {
+      let emitAccounts!: (accounts: string[]) => void
+      mockConnector.onAccountsChanged = (l: (accounts: string[]) => void) => {
+        emitAccounts = l
+        return () => {}
+      }
+      mockConnector.disconnect = vi
+        .fn()
+        .mockRejectedValue(new Error('already closed'))
+
+      await connectionService.connect('injected', 'metamask', 'eip155:1')
+
+      expect(() => emitAccounts([])).not.toThrow()
+      expect(sessionManager.getSession().activeAddress).toBeNull()
+      // Let the fire-and-forget rejection settle so it doesn't surface as an
+      // unhandled rejection in a later test.
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+
+    it('a wallet that double-fires an empty accountsChanged does not double-emit disconnected/sessionChanged', async () => {
+      // handleAccountsChanged([]) -> finishDisconnect() runs synchronously
+      // FROM INSIDE the connector's own accountsChanged dispatch (the
+      // teardown it triggers removes that very listener re-entrantly). If a
+      // wallet emits the empty-array disconnect signal twice in quick
+      // succession — or the second emission slips through before teardown
+      // takes effect — finishDisconnect must be a no-op the second time
+      // rather than clearing an already-cleared session and re-emitting.
+      let emitAccounts!: (accounts: string[]) => void
+      mockConnector.onAccountsChanged = (l: (accounts: string[]) => void) => {
+        emitAccounts = l
+        return () => {}
+      }
+      mockConnector.disconnect = vi.fn().mockResolvedValue(undefined)
+      const disconnectedEvents: unknown[] = []
+      const sessionChangedEvents: unknown[] = []
+      eventManager.on('disconnected', d => disconnectedEvents.push(d))
+      eventManager.on('sessionChanged', d => sessionChangedEvents.push(d))
+
+      await connectionService.connect('injected', 'metamask', 'eip155:1')
+      sessionChangedEvents.length = 0 // drop the connect's own sessionChanged
+
+      emitAccounts([])
+      emitAccounts([]) // the wallet (or a race) delivers the same signal again
+
+      expect(disconnectedEvents).toHaveLength(1)
+      expect(sessionChangedEvents).toHaveLength(1)
+      expect(mockConnector.disconnect).toHaveBeenCalledTimes(1)
+    })
+
+    it('reattachLifecycle() seeds address-echo suppression with the just-active address', async () => {
+      const accountSubscribers: Array<(accounts: string[]) => void> = []
+      mockConnector.onAccountsChanged = (l: (accounts: string[]) => void) => {
+        accountSubscribers.push(l)
+        return () => {}
+      }
+      const sessions: unknown[] = []
+      eventManager.on('sessionChanged', d => sessions.push(d))
+
+      await connectionService.connect('injected', 'metamask', 'eip155:1')
+      sessions.length = 0
+      connectionService.reattachLifecycle()
+
+      // The reattached provider echoes the session's own current address →
+      // suppressed, no redundant sessionChanged.
+      accountSubscribers[1]!(['0x1234'])
+      expect(sessions).toHaveLength(0)
+
+      // A later, genuinely different address is a real change.
+      accountSubscribers[1]!(['0xDIFFERENT'])
+      expect(sessions).toHaveLength(1)
+    })
+
+    it("does not move activeAddress when the changed namespace no longer matches the session's active namespace (stale subscription after a cross-namespace switch)", async () => {
+      let emitAccounts!: (accounts: string[]) => void
+      mockConnector.onAccountsChanged = (l: (accounts: string[]) => void) => {
+        emitAccounts = l
+        return () => {}
+      }
+
+      await connectionService.connect('injected', 'metamask', 'eip155:1')
+      const connectTimeAddress = sessionManager.getSession().activeAddress
+
+      // Simulate the session's active network having already moved to a
+      // different namespace (e.g. mid-cross-namespace-switch) WITHOUT this
+      // stream having been reattached yet — it's still the eip155 one from
+      // connect time.
+      sessionManager.updateSession({
+        activeNetwork: {
+          ...sessionManager.getSession().activeNetwork,
+          namespace: 'solana'
+        } as any
+      })
+
+      emitAccounts(['0xNEW'])
+
+      // activeAddress belongs to the now-active (solana) namespace and must
+      // not be clobbered by a stale eip155 subscription's account change.
+      expect(sessionManager.getSession().activeAddress).toBe(connectTimeAddress)
+      // availableAddresses for the eip155 entry IS still updated — the address
+      // change is real, just not the currently-active one.
+      expect(sessionManager.getSession().availableAddresses).toEqual([
+        { address: '0xNEW', networkId: 'eip155:1' }
+      ])
+    })
   })
 })