[Frontend] WebSocket Client for Real-Time Escrow and Notification Updates

[KuchiMercy]

Problem

The frontend currently polls for notifications every 10 seconds (hooks/useNotifications.ts) and has no real-time escrow status updates. The backend already has a WebSocket gateway (gateways/escrow.gateway.ts) broadcasting events, but the frontend has no WebSocket client.

Current State

• Backend: EscrowGateway broadcasts events via Socket.IO:
  • escrow:status_changed, escrow:funded, escrow:completed
  • escrow:milestone_released, escrow:condition_fulfilled, escrow:condition_confirmed
  • escrow:dispute_filed, escrow:dispute_resolved
  • notification:new
• Frontend: No Socket.IO client installed, no WebSocket connection logic
• Frontend: hooks/useNotifications.ts polls every 10 seconds (inefficient)

Acceptance Criteria

• Install socket.io-client as a dependency
• Create a lib/websocket.ts client that:
  • Connects to the backend WebSocket server with the JWT auth token
  • Handles reconnection with exponential backoff
  • Provides typed event listeners for all escrow and notification events
  • Manages room subscriptions (join/leave escrow rooms)
• Create a providers/WebSocketProvider.tsx that:
  • Initializes the socket connection on auth
  • Disconnects on logout/token expiry
  • Provides socket instance via React context
• Create hooks/useEscrowEvents.ts hook for listening to escrow-specific real-time events
• Update hooks/useNotifications.ts to use WebSocket notification:new events instead of polling
• Show connection status indicator (connected/reconnecting/disconnected)
• Handle edge cases: multiple tabs, token refresh, network errors

Technical Notes

• Backend Socket.IO namespace: /escrow (verify in gateway config)
• Auth token passed in handshake.auth.token or handshake.headers.authorization
• Room format: escrow:{escrowId}

Points: 150 (Medium)

[5elc0uth]

@5elc0uth has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

I’d like to work on this issue because it adds the real-time WebSocket foundation needed for live escrow and notification updates, and I can implement it cleanly with authenticated Socket.IO connection handling, reconnection logic, room subscriptions, and frontend state updates.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @5elc0uth to this issue.

[Malcolm-Wander]

@Malcolm-Wander has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Hello maintainer, I’d love to work on this issue please …thank you

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Malcolm-Wander to this issue.

[drips-wave]

Congratulations, @Malcolm-Wander! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @Malcolm-Wander: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[amina69]

@amina69 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

i would love to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @amina69 to this issue.