Inspiration

My friends with iPhones spend half their group chat playing GamePigeon, the little games built into iMessage, and as the one Android user I've always been stuck watching from the outside. I wanted a way to share quick, fun games with friends that works on any phone, without anyone needing to own the right device or download the right app.

The other half of the idea came from penny poker. Back home we loved putting small stakes on games, nothing serious, just enough to make winning feel like it meant something. Once we all left for different colleges, that pretty much stopped, because there wasn't an easy way to play each other for a few dollars online without trusting some sketchy site or chasing people for Venmo payments afterwards.

CoinClash is our answer to both. The games are cross-platform, fun, and modular enough that adding a new one is a small, well-defined job, and the money runs on Bitcoin through the Breez SDK, which means payments are instant, secure and private, and the winner is paid the moment the game ends instead of whenever their friend remembers.

What it does

You sign up with a passkey (your fingerprint or face, no seed phrase and no password), and the Breez SDK derives a self-custodial Bitcoin wallet from it. You pick one of five games (tic-tac-toe, Connect 4, rock paper scissors, trivia or 8-ball pool), set a stake in sats with the dollar value shown beside it, and send a challenge by link, QR code, or a six-digit code. Anyone you've played before becomes a friend you can challenge directly, and they get a push notification. You can haggle over the stake, both of you pay it into escrow, and then you play turn by turn in real time. The winner gets the whole pot instantly, and your history shows who you played and what you won or lost against each friend. There's also a free practice mode against a bot, so anyone can try it without an account.

How we built it

CoinClash is a TypeScript monorepo with a React progressive web app on the front end and a Node, Express and Socket.IO server behind it. We kept a written record of every major decision as an Architecture Decision Record in docs/decisions/ (there are 21 of them now), so anyone reading the repo can see not just what we built but why.

Why a web app. We seriously considered building this as a Discord activity or a Telegram mini-app, since that's where friends already hang out, but both platforms' terms of service forbid real-money gaming, so that was a dead end. A progressive web app turned out to be the better choice anyway: it runs on Android and iPhone from the same code, installs to the home screen, supports push notifications, and nobody needs an app store's permission to ship it.

Games as plug-ins. Every game implements a small GamePlugin interface and is written as a pure, deterministic engine with a seeded random number generator, so it has no network calls, no clocks and no randomness we can't replay. That makes engines easy to test (we fuzz them with random legal moves), lets the server replay any match from its move log, and means the same engine can run in the browser for practice mode. Game code never touches money, and payment code never touches game rules.

The server is the referee. Clients only send intentions like "drop a disc in column 4". The server validates every message, applies the move, enforces turn timers (if you stall, you lose the pot to the player who showed up), and sends each player only what they're allowed to see, so nobody can cheat by editing their app or peeking at their opponent's rock paper scissors pick.

Money behind one interface. All money moves through a payment rail interface with three implementations: an in-memory mock network for tests, Breez on regtest, and Breez on mainnet. Matches run as an explicit state machine with every transition recorded, and every payout carries an idempotency key and a ledger entry inside the match itself, so even if the server crashes halfway through paying someone it reconciles on restart and pays exactly once.

Trying to keep ourselves out of the middle

The design I really wanted was one where CoinClash never holds anyone's money at all. We built an HTLC "oracle" escrow: each player locks their stake directly to their opponent with a hash-locked payment, and the server only reveals the secret that unlocks the winner's side once the game is decided. If anything goes wrong, the locks simply expire and the money goes back to its owner, without the server ever having custody of a single sat.

When we went to run it on the network, we found that direct Spark HTLC payments between user wallets are currently disabled (breez/spark-sdk#1123). Every attempt failed with a permission error. So, with the deadline approaching, we switched to a custodial escrow: each player pays a Spark invoice that only their own wallet can pay, and the winner is paid out the moment the game ends. To keep that honest, there's a public escrow page that shows, live, what the escrow wallet holds against what it owes to every match in play. The full HTLC flow is still in the codebase, tested and switched off, ready to turn back on the moment the network supports it.

Sponsor tools

Vultr. CoinClash runs on a Vultr cloud server in Docker, with Caddy in front handling HTTPS certificates automatically. Every push to main runs our full test suite in GitHub Actions, and only if everything passes does a deploy workflow ship the new version to the Vultr box over SSH, so the live site at coinclash.vip is always the last version that passed every test.

MongoDB. MongoDB Atlas stores users, matches and push-notification subscriptions. Each match is a single document that carries its game state, its full transition history and its own payment ledger, which made MongoDB a natural fit. Saves use a version number for optimistic concurrency, so two simultaneous moves can't clobber each other, and indexes on unpaid payouts let the server find and finish any interrupted payout after a restart. Our tests run against a real in-memory MongoDB instance, so the database code is exercised exactly as it runs in production.

GoDaddy Registry. Our domain, coinclash.vip, is on GoDaddy Registry's .vip extension, and it does more than look nice in an invite link. Passkeys are cryptographically bound to the domain they were created on, so every player's wallet is tied to coinclash.vip. Picking a permanent home early was one of the first decisions we documented, because a wallet created on a temporary domain would have been locked to it forever.

Challenges we ran into

Beyond the HTLC surprise, the funniest problem was that our own campus Wi-Fi refused to resolve one of the Spark operators' servers, so payments that worked everywhere else failed from my laptop. We ended up running payment tests from the cloud server and added a banner in the app that tells players when their network is blocking a payment server and what to do about it. Pool was its own adventure: getting physics that replays identically on both phones, plus a landscape full-table mode where you pull a cue down to set power, took several rounds of real-phone testing to feel right.

What we learned

We learned a lot about Bitcoin's newer layers: how Spark makes instant self-custodial payments possible, how passkeys can stand in for seed phrases, and how much careful engineering "pay the winner exactly once" really takes. I also worked with Claude Code as a pair programmer for the whole build, which taught me how much faster you can move when every decision is written down and every change is tested before it ships.

What's next

  • Fully non-custodial matches, by switching the dormant HTLC escrow back on once direct Spark HTLCs are enabled.
  • Real money on mainnet (the switch is already in the app, marked "coming soon"), along with Lightning deposits from any wallet and a proper legal review.
  • More games and bigger formats, such as battleship, checkers, group pots for three or more players, tournaments, and spectator links.
  • Other uses for the same engine. Escrowed, instantly settled stakes between friends fit plenty of other things too: friendly sports predictions, fantasy league pots, fitness challenges where you pay out if you skip the gym, or milestone payments for small freelance jobs. Because games are plug-ins, independent developers could also bring their own games and get instant, trust-minimized payouts for free.

Built With

Share this project:

Updates

Submission history