Hackathon: Live Balance and Allowance tracking using SSE

[anxolin]

During the hackathon, I’m building a live balance tracking service to make it easier and faster to display and update balances for CoW Protocol users.

Overview

The system works as follows:

1. Subscription

   • Users subscribe to an SSE endpoint to track balances and allowances.
   • The client provides: walletAddress, chainId, tokenAddresses.
   • Eventually, tokenAddresses will be replaced by tokenLists and walletAddresses.

2. Instant Initial Data

   • The endpoint responds immediately with initial_balances using cached data.

3. Ongoing Tracking

   • The server monitors balances and allowances for the requested tokens.
   • Any changes are pushed in real time:
     • Balance changes: include the token, old balance, and new balance.
     • Allowance changes: include the token, old allowance, and new allowance.

4. Persistent Connection

   • The server keeps the SSE connection open, periodically sending PINGs.
   • If the client misses a PING, it closes the connection and stops tracking.

5. Graceful Shutdown

   • If the user closes the window/connection, the server detects it and stops tracking.

Why This Matters

• Better UX: Balances are always fresh and load instantly
• Efficiency: Significantly reduces node calls
• Infrastructure for Notifications: Cached balances/allowances enable advanced alerts (e.g., when an order becomes UNFILLABLE due to balance/allowance changes)
• Lightweight Clients: Less polling means reduced CPU/battery usage, especially on mobile
• Faster Feedback: Immediate updates remove the polling delay currently present when trading or receiving funds

Plan & Related PRs

Initial Scope

• Balance Repository – Interface + reference implementation to fetch balances and allowances for multiple tokens . See feat: add user balance repository #156
• SSE Service – Handles client subscriptions/unsubscriptions and pushes initial + updated data . See feat: add sse service #158
• Balance Tracking Service – Manages start/stop tracking logic, delegates to the repository, and pushes updates via SSE . See feat: add tracking service #160
• Balance & Allowance Tracking API – Exposes the SSE endpoint for initial + live updates . See feat: Expose SSR endpoints to track balances #161
• SSE Web app: Creates a convenient webapp to easily test the new endpoint and see how your balance changes when you do trades in CoW Swap or send tokens in/out. See feat: implement a webapp to test sse balance updates #162

Future Improvements

• Token List Repository – Map tokenLists and walletAddresses to token addresses, reducing required arguments. Users will mostly pass a list instead of individual tokens, leveraging cached mappings
• Improve startTrackingUser in the tracking service, so its resilient to repository failures or broadcasting failures.
• Improve some TODOs from feat: Expose SSR endpoints to track balances #161. Also, the file contains too many lines, can we split it?
• Potentially create additional implementations of UserBalanceRepository (like using Moralis)
• Technically I don't need broadcastToUser exposed in the service layer. I just left it for convenience, but probably better to only define very specific methods like the ones we have for notification of balance changes.
• Improves on polling 1: Review POLLING_INTERVAL_MS to fit our needs. We could also consider having ways to query more often some tokens than others, similarly to what we do in the UI.
• Improves on polling 2: Watch for events to poll in that moment
• API should not depend on repository:The API route should not use directly a repository. Implemented in feat: use cache for token details and improve architecture #186

Misc

• feat: tag endpoints #163

Teaser

This is a teaser of what these PRs add