Player Matchmaking and Skill-Based Queue Service

[Mkalbani]

Location: Backend API
Estimated Time: 6 hours
Difficulty: Medium

Description

Implement a matchmaking service that pairs players for head-to-head puzzle challenges based on their skill rating. Players join a queue, the system finds the closest-rated opponent within a configurable ELO range, and creates a match session. Queue wait time expands the ELO window every 30 seconds to prevent indefinite waits.

Tasks

• MatchmakingQueue entity: playerId, puzzleType, rating, joinedAt, status (waiting/matched/cancelled)
• POST /matchmaking/join — player joins queue with preferred puzzle type
• DELETE /matchmaking/leave — player leaves queue
• GET /matchmaking/status — returns current queue position and estimated wait
• Background job runs every 10 seconds: scans queue, pairs players within ELO range (starts at ±50, expands ±25 every 30s)
• On match found: creates GameSession with both players; emits WebSocket event match_found to both
• GET /matchmaking/history — player's past match results and opponents
• Graceful handling: if opponent disconnects before game starts, re-queue the waiting player
• Tests: queue join, pairing algorithm, ELO expansion, re-queue on disconnect, concurrent queue safety

Acceptance Criteria

• Players matched within ELO range
• ELO window expands correctly over wait time
• Both players notified via WebSocket on match
• Disconnection handled gracefully with re-queue
• Tests verify pairing logic and edge cases

[pope-h]

@pope-h has applied to work on this issue as part of the Stellar Wave Program's 4th wave.

Hey there maintainer, I am a software engineer with a lot of blockchain experience. I have read through the Issue description and with my experience in stellar projects can get this delivered ASAP.

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

[xeladev4]

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

I’d like to work on this issue.
I have experience building and securing Stellar/Soroban smart contracts. I focus on clean implementations.
I’ll ensure the solution follows the project’s architecture and security best practices.

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

[mijinummi]

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

Hello I can handle this perfectly

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

[drips-wave]

Congratulations, @mijinummi! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on April 29, 2026.

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

[drips-wave]

This issue has been completed by @mijinummi as part of the Stellar Wave Program's 4th Wave 🥳

😎 @mijinummi: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.