fix(wallet): stop believing a socket that says OPEN after a trip to the wallet

[ehsan6sha]

Coming back from MetaMask, the page sat on Connecting Wallet… for several seconds after the user had already approved. Two causes, both ours.

1. The wake trusted a socket that only said it was open

relayer.connected is nothing but the WebSocket's own readyState === 1:

get connected(){ return this.provider?.connection?.socket?.readyState === 1 || false }

Android suspends the TCP connection underneath a socket without telling it, so it keeps reporting OPEN while the wallet's approval sits on the relay waiting for a client that thinks it needs nothing. Nothing in @walletconnect/core catches this from a browser — the ping-based liveness check (startPingTimeout) is gated on isNode(), and the heartbeat's own reconnect fires only on !connected. Our wakeRelay returned early on the very same flag. So on return, everyone looked at a dead socket that said OPEN and did nothing until Chrome's TCP stack gave up. That was the delay.

Now, when the tab has been hidden for at least BACKGROUND_STINT_MS (1 s — a trip to a wallet is never shorter, a flick between desktop tabs usually is), readyState is not consulted and the transport is restarted outright. restartTransport() tears the socket down, dials again, re-subscribes every topic, and its subscriber then calls batchFetchMessages — which is precisely the fetch of whatever the wallet published while we were dead. A socket that was actually healthy pays one reconnect, well under a second; one that was not pays nothing it did not already owe.

2. The wake never ran for the connect round-trip at all

wallet.provider comes from AppKit's ProviderController.setProvider, which runs on connection. So during the connect itself — the first trip every user makes, and the one in the report — it was undefined, and useRelayWake had nothing to act on. The socket the approval arrives over lives on AppKit's UniversalProvider, which exists from the moment the chooser opens. WalletSigner now asks AppKit for it (getUniversalProvider()) and wakes that when there is no session provider yet.

The splash-screen hang

Not fixed by this PR, and I no longer believe a web page can fix it directly — two device tests ruled out user activation and URL shape. What it does is name the likely cause in the stuck-wallet hint: Android restricting MetaMask in the background, so it is suspended or killed on every switch away and cannot handle the request it is resumed for. The fix is the user's — Settings → Apps → MetaMask → Battery → Unrestricted, and the same for the browser. This is the exact setting the mobile FxBlox app always needed for these prompts (it is already in the legacy section of the docs); with it in place the wallet comes forward already showing the prompt. Same guidance goes to docs.fx.land in functionland/docs#179.

Testing

• npm test --workspaces — 949 passing. New: wakeRelay restarts a "connected" socket after a background stint but not otherwise; a genuinely-down socket still takes the polite path; a relayer without restartTransport is left alone; a failed restart is swallowed. useRelayWake restarts after ≥ 1 s hidden, leaves an open socket alone after a shorter flick, and ignores a visible with no preceding hidden.
• npm run typecheck --workspaces, npm run lint clean.
• Not verified on a device yet — that is the reporter's phone, and the ask is: come back from MetaMask after connecting and say how long Connecting Wallet… shows now.

🤖 Generated with Claude Code

https://claude.ai/code/session_013BpqXrkEPA9odTyRdK5Mnx