Document the WebSocket event protocol as a standalone reference

[james2177]

Description

The /ws event types (connected, snapshot, intent_created, intent_accepted, intent_filled, intent_cancelled, intent_expired) are currently only discoverable by reading scripts/solver-bot.ts's switch statement or IntentsGateway/IntentsController source directly — there's no dedicated protocol doc.

Requirements and context

• Document each event's exact payload shape, and note this should get an update once issue Write a backup/restore runbook for the persistent intents store #61 (topic subscriptions) and issue Add an audit trail for cancelled and expired intents #62 (event sequencing) land

Suggested execution

1. Fork the repo and create a branch

   git checkout -b docs/websocket-protocol-reference
   

2. Implement changes
   Relevant files:

• docs/websocket-protocol.md

3. Test and commit

   • Run npm run lint && npm run typecheck && npm test && npm run test:e2e
   • Include test output / screenshots or logs demonstrating the fix in the PR

   Example commit message:

   docs: document the WebSocket event protocol
   

Guidelines

• Assignment required before starting — comment to claim this issue
• PR description must include: Closes #[this issue's number]
• Timeframe: 96 hours from assignment
• Complexity: High (200 points)

---

Part of the Drips Wave for vortex-backend.

[iBotayo]

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

I can resolve this issue

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

[sam-boyega]

@sam-boyega has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I took time to understand the complete scope of this request. I’m confident in my ability to address it cleanly and efficiently—would love to claim this task and move forward.

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

[kulkan-IV]

@kulkan-IV has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

hi team kindly assign me i can work on this issue am a pro dev

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

[drips-wave]

Congratulations, @kulkan-IV! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @kulkan-IV: 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 🌊