@meshconnect/uwc-core 1.2.2 → 1.2.3-snapshot.2b4c3e4

package/src/observability/lifecycle-bridge.test.ts

@@ -55,6 +55,82 @@ describe('attachLifecycle', () => {
     expect(got.walletSessionExpired).toEqual([routing])
   })
 
+  it('forwards real accounts from subscribeAccounts to onAccountsChanged (a separate stream from telemetry)', () => {
+    const em = new EventManager()
+    let emitAccounts!: (accounts: string[]) => void
+    const seen: string[][] = []
+
+    attachLifecycle({
+      eventManager: em,
+      subscribe: () => () => {},
+      subscribeAccounts: l => {
+        emitAccounts = l
+        return () => {}
+      },
+      onAccountsChanged: accounts => seen.push(accounts),
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'eip155'
+    })
+
+    emitAccounts(['0xNEW'])
+    expect(seen).toEqual([['0xNEW']])
+  })
+
+  it('attaches subscribeAccounts even when the connector has NO telemetry subscribe (the Tron shape today)', () => {
+    // TronConnector implements onAccountsChanged but not onLifecycleEvent —
+    // the two streams must be independently attachable.
+    const em = new EventManager()
+    const unavail: unknown[] = []
+    em.on('lifecycleTelemetryUnavailable', d => unavail.push(d))
+    let emitAccounts!: (accounts: string[]) => void
+    const seen: string[][] = []
+
+    attachLifecycle({
+      eventManager: em,
+      subscribe: undefined,
+      subscribeAccounts: l => {
+        emitAccounts = l
+        return () => {}
+      },
+      onAccountsChanged: accounts => seen.push(accounts),
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'tron'
+    })
+
+    emitAccounts(['TSwitched'])
+    expect(seen).toEqual([['TSwitched']])
+    // No telemetry surface exists for this connector, but that's a SEPARATE
+    // concern from account-sync succeeding — no unavailable signal fires
+    // just because the account stream alone is present.
+    expect(unavail).toHaveLength(0)
+  })
+
+  it('teardown unsubscribes both streams', () => {
+    const em = new EventManager()
+    let lifecycleUnsubbed = false
+    let accountsUnsubbed = false
+
+    const teardown = attachLifecycle({
+      eventManager: em,
+      subscribe: () => () => {
+        lifecycleUnsubbed = true
+      },
+      subscribeAccounts: () => () => {
+        accountsUnsubbed = true
+      },
+      onAccountsChanged: () => {},
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'eip155'
+    })
+
+    teardown()
+    expect(lifecycleUnsubbed).toBe(true)
+    expect(accountsUnsubbed).toBe(true)
+  })
+
   it('a throwing getRouting never escapes into the wallet emitter dispatch', () => {
     // Wallet SDKs dispatch listeners unguarded (e.g. TonConnect's bare
     // forEach) — a throw from our listener would abort delivery to the
@@ -152,6 +228,91 @@ describe('attachLifecycle', () => {
     expect(seen).toHaveLength(1)
   })
 
+  it('suppresses an accountsChanged echo that matches the address a UWC switch just applied', () => {
+    let t = 1000
+    const em = new EventManager()
+    const seen: string[][] = []
+    let emitAccounts!: (accounts: string[]) => void
+
+    attachLifecycle({
+      eventManager: em,
+      subscribe: () => () => {},
+      subscribeAccounts: l => {
+        emitAccounts = l
+        return () => {}
+      },
+      onAccountsChanged: accounts => seen.push(accounts),
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'eip155',
+      now: () => t
+    })
+
+    em.emit('networkSwitched', {
+      network: { id: 'eip155:8453' } as any,
+      address: '0xNEW'
+    })
+    emitAccounts(['0xNEW'])
+    expect(seen).toHaveLength(0)
+
+    // Past the echo window, the same address is a genuine wallet-side switch.
+    t = 1000 + 5000
+    emitAccounts(['0xNEW'])
+    expect(seen).toHaveLength(1)
+  })
+
+  it('forwards an accountsChanged inside the echo window whose address does NOT match the switch (a real, different, user-initiated change)', () => {
+    const em = new EventManager()
+    const seen: string[][] = []
+    let emitAccounts!: (accounts: string[]) => void
+
+    attachLifecycle({
+      eventManager: em,
+      subscribe: () => () => {},
+      subscribeAccounts: l => {
+        emitAccounts = l
+        return () => {}
+      },
+      onAccountsChanged: accounts => seen.push(accounts),
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'eip155'
+    })
+
+    em.emit('networkSwitched', {
+      network: { id: 'eip155:8453' } as any,
+      address: '0xNEW'
+    })
+    emitAccounts(['0xSOMETHING_ELSE'])
+    expect(seen).toEqual([['0xSOMETHING_ELSE']])
+  })
+
+  it('never suppresses an empty accounts list (the disconnect signal), even inside the echo window', () => {
+    const em = new EventManager()
+    const seen: string[][] = []
+    let emitAccounts!: (accounts: string[]) => void
+
+    attachLifecycle({
+      eventManager: em,
+      subscribe: () => () => {},
+      subscribeAccounts: l => {
+        emitAccounts = l
+        return () => {}
+      },
+      onAccountsChanged: accounts => seen.push(accounts),
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'eip155'
+    })
+
+    em.emit('networkSwitched', {
+      network: { id: 'eip155:8453' } as any,
+      address: '0xNEW'
+    })
+    emitAccounts([])
+    expect(seen).toEqual([[]])
+  })
+
   it('caps lifecycle emissions per attachment (a storming provider cannot drive unbounded egress)', () => {
     // Every other telemetry sink added by this layer is bounded (relay / bridge /
     // observer-error all cap at 100); a wallet looping chainChanged must not be
@@ -192,6 +353,42 @@ describe('attachLifecycle', () => {
     expect(unavail[0]?.reason).toBe('emission_cap')
   })
 
+  it('does not drop a still-pending echo suppression when a SECOND switchNetwork arms before the FIRST wallet echo arrives', () => {
+    // Two rapid, back-to-back switches (A then B) each arm their OWN echo
+    // window. A's wallet echo can legitimately arrive AFTER B's switch has
+    // already completed — B arming/re-arming must not erase A's still-valid,
+    // not-yet-consumed suppression window.
+    let t = 1000
+    const em = new EventManager()
+    const seen: unknown[] = []
+    em.on('walletChainChanged', d => seen.push(d))
+
+    let emit!: (e: WalletLifecycleEvent) => void
+    attachLifecycle({
+      eventManager: em,
+      subscribe: l => {
+        emit = l
+        return () => {}
+      },
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'eip155',
+      now: () => t
+    })
+
+    em.emit('networkSwitched', switchedTo('eip155:8453')) // switch to A
+    t = 1010
+    em.emit('networkSwitched', switchedTo('eip155:137')) // switch to B, A's echo still pending
+
+    t = 1020
+    emit({ type: 'chainChanged', chainId: 'eip155:8453' }) // A's delayed echo
+    expect(seen).toHaveLength(0)
+
+    t = 1030
+    emit({ type: 'chainChanged', chainId: 'eip155:137' }) // B's delayed echo
+    expect(seen).toHaveLength(0)
+  })
+
   it('seeds echo suppression from initialSwitch (the reattach-after-switch path)', () => {
     // A cross-namespace switchNetwork re-attaches the subscription AFTER the
     // switch completed — the fresh closure never saw that switch's bus events,

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?.()
   }
 }