Case study
SpotKick
Real-time PvP penalty duel with commit-reveal
0 duplicatescharges or prizes in tests with lost responses and restartsat-least-once delivery with idempotent consumers (single effect)
Live demo
Play-money demo: fictitious chips, no real money and no prizes. 18+. Play responsibly.
Hosted on my own server: the first load after a quiet period can take a little longer.
What it is and what it solves
A real-time player-versus-player penalty shoot-out: three rounds and sudden death. Both players choose at the same time, so the system must make it impossible to react to the rival's move, survive disconnections and pay each prize once (at-least-once delivery with idempotent consumers, verified in tests).
Business version: SpotKick →
Architecture
- Browser A → API instance (WebSocket)
- Browser B → API instance (WebSocket)
- API instance → Redis
- API instance → Redis
- API instance → PostgreSQL
- API instance → PostgreSQL
- PostgreSQL → Outbox workers
- Outbox workers → Redis (at-least-once)
- API instance → Platform Core
Drawn from the architecture diagram in the repository README.
Three technical decisions
Commit-reveal for simultaneous choices
Each player first sends a hash of the choice plus a random salt, and reveals both only once the two hashes are in, so nobody can pick after seeing the other side's move. If someone does not reveal in time, an auditable fallback choice is applied.
Escrow in a double-entry ledger
Stakes are locked atomically when the match starts and either paid to the winner or refunded on abandonment, with idempotency keys so a retried request has a single effect: no double charge in tests.
Horizontally scalable rooms
Several NestJS instances share presence, queues and redacted snapshots through Redis and the Socket.IO Redis adapter, so a player can reconnect to any instance.
Tests, with numbers
- 200 simultaneous matches and 400 connections without errors, spread across two API instances.
- Lost responses, restarts and self-exclusion with no duplicated charges or prizes.
- 14 mutation checks.
Verified
- Integrated with Platform Core using batched settlement.
- Solo mode is provably fair: the goalkeeper's zone is derived with HMAC-SHA256 from the server seed, the client seed and a counter, and the server seed is revealed at the end so anyone can verify it.
Not claimed
- Real-money operation or a third-party audit. All chips are fictitious.
- Figures come from test runs, not from production traffic.