SquadSync

Deterministic team builder for hackathons featuring NIP-98 auth, AI role normalization, and live NIP-47 Nostr Wallet Connect (NWC) instant prize splitting to winners' Lightning addresses.

Comment

💡 Inspiration

Every hackathon and workshop starts with the same awkward scramble: who is on my team? People instinctively cluster with friends, technical skills end up heavily lopsided, and organizers routinely spend the first hour of their event doing messy, manual matchmaking on a physical whiteboard. We wanted that sorting process to take exactly one click—and above all, to be fundamentally fair, not random.

At a Bitcoin hackathon, the second realization followed naturally: once a team actually wins, paying them out is just as frustrating. Prizes get promised, then slowly trickle out over days or weeks through shared screenshots, manual coordination, and traditional bank details. If teams are already signing in using a native identity layer, why not let the winnings flow over open monetary rails the exact moment a winner is chosen? That specific mix—fair, optimized teams and instant, trustless payouts—became SquadSync.

⚙️ What it does

SquadSync turns a roomful of strangers into perfectly balanced teams, and a prize pot into instant sats in their wallets.

  • Sign in with Nostr: Zero passwords, zero emails. Secure authentication relies on NIP-98 via a browser extension, a generated ephemeral keypair, or an existing nsec.
  • Create an Event & Share a QR: Attendees self-register with no friction. Each person selects a primary strength and experience level, and can add an optional Lightning address (which auto-fills from their Nostr profile's lud16 metadata when available).
  • Build Balanced Teams in One Click: A deterministic allocation engine spreads roles and experience levels evenly across teams. AI (Claude Haiku) only steps in to read free-text "Other" strengths and map them to a standard category—so a "GIS analyst" and a "data scientist" are fully comparable before allocation. The actual team-building stays fully deterministic and reproducible.
  • Pay the Winners in Bitcoin: An organizer marks the winning team, enters a prize in sats, and connects any wallet via Nostr Wallet Connect (NIP-47). SquadSync splits the pot evenly, resolves the addresses via LNURL-pay, and broadcasts the payments live.

The Lossless Satoshi Split

To guarantee the even split is perfectly simple and lossless down to the single satoshi, a mathematical remainder distribution is applied. For a total prize pool of $P$ sats distributed across $n$ team members, each member $i$ (where $i \in {0, 1, \dots, n-1}$) receives:

$$a_i = \left\lfloor \frac{P}{n} \right\rfloor + \begin{cases} 1 & \text{if } i < (P \bmod n) \ 0 & \text{otherwise} \end{cases}$$

This ensures that any remaining dust sats are systematically handed to the earliest indexed members, ensuring every single sat in the designated pot is accounted for and paid out.

🛠️ How we built it

We engineered a clean, decoupled architecture built specifically to move value safely:

  • Frontend: Next.js 16 + React 19 + Tailwind v4, utilizing NextAuth v5 to manage the cryptographic Nostr session states.
  • Backend: FastAPI leveraging SQLAlchemy 2 and Alembic; using PostgreSQL in production and SQLite for local test isolation.
  • Nostr & Bitcoin Integration: NIP-98 login, encrypted NIP-04 feedback DMs, Schnorr signatures via coincurve, and LNURL-pay for invoice resolution. Instead of relying on heavy third-party wrappers, we wrote our own lightweight NIP-47 (Nostr Wallet Connect) client to interact directly with the relays.
  • Scoped AI Layer: Anthropic Claude Haiku normalizes messy, text-based strengths. This is entirely optional and features a deterministic string fallback, allowing the app to function flawlessly even if the AI API is offline.

We built SquadSync test-first: the split math, the custom LNURL client, and the wallet-connect event loops each have rigorous test coverage, ensuring the money path is rock-solid before a single live sat moves.

🛑 Challenges we ran into

  • Asynchronous Wallet Coordination over Nostr: Traditional Nostr clients publish an event and forget about it. Paying an invoice over NIP-47 requires the exact opposite: you publish a request event, then instantly subscribe and listen for the wallet's encrypted reply. Getting that round-trip right—ensuring the subscription is alive before the publish command is broadcast so you never miss an ultra-fast response—was our trickiest engineering hurdle.
  • Never Charging a Half-Team: If even one member of a winning team hasn't configured a valid Lightning address, executing a batch payout could result in partial, stranded transactions. We designed a strict pre-flight validation check that resolves every single LNURL endpoint upfront. If any address fails to resolve, the entire payout sequence safely aborts with an explicit error message rather than stranding funds.
  • Wallet Spec Variance: In the wild, distinct wallets implement NIP-47 parameters slightly differently—some return execution errors as highly structured JSON objects, while others pass plain strings. We had to drastically harden our error-handling middleware to gracefully parse these edge cases without crashing the payment loop.
  • Guarding Spend Credentials: A wallet connection string gives programmatic spending power. We enforced an absolute zero-storage architecture: the connection string is processed in memory for the single request context and is never written to the database, logged to stdout, or exposed via the API.

🎉 Accomplishments that we're proud of

  • A Fair Allocation Engine: A completely deterministic sorting mechanism where the exact same inputs yield the exact same teams. AI is kept out of the core logic, acting purely to level the playing field for human text inputs.
  • Real Bitcoin Over Open Rails: Live tested payout instance as real sats exit a linked wallet and fan out across the Lightning Network.
  • Money-Safe Architecture: Full-pot mathematical splits, atomic pre-flight checks to eliminate partial charges, and zero credential retention.
  • Pure FOSS: A genuinely modular, open-source tool usable out of the box for any local developer community, workshop, or study circle.

🧠 What we learned

  • Nostr is Infrastructure: It is far more than a social protocol. It functions as a global identity plane and an open payment-coordination layer; the exact same public key used to authenticate a user session can seamlessly authorize an instant, multi-peer global payout.
  • Determinism Builds Trust: Communities accept algorithmic sorting far more readily when they know the process is entirely repeatable, verifiable, and free of hidden biases, and where LLMs are tightly scoped to what they do best: parsing messy text.
  • When Code Moves Value, TDD is Mandatory: Writing the split algorithms and the asynchronous payment logic test-first turned "I hope this works" into "I can mathematically prove this works."

🚀 What's next for SquadSync

  • Localized Financial Off-Ramps: Integrating direct mobile-money off-ramps (such as M-Pesa) into the payout loop. This ensures that even if a local hackathon winner does not possess a dedicated Lightning wallet yet, they can still effortlessly claim their split in their local currency.
  • QR Fallback Mode: Developing a simple, localized QR-code renderer per team member as a backup path, allowing an organizer to manually scan and settle payouts sequentially from any mobile wallet without requiring an explicit NWC link.
  • Advanced Allocation Constraints: Introducing optional team parameters into the engine, including explicit role caps, locked developer pairs, and fixed team maximums.
  • Sponsor-Funded Pools: Allowing external event sponsors to multi-sign or fund a programmatic prize pool that handles multi-tier distribution across 1st, 2nd, and 3rd place teams automatically.

Built With

  • alembic
  • anthropic-claude
  • bolt11
  • coincurve
  • fastapi
  • lightning-network
  • lnurl
  • next.js
  • nextauth
  • nip-04
  • nip-47
  • nip-98
  • nostr
  • nostr-tools
  • nostr-wallet-connect
  • playwright
  • postgresql
  • pydantic
  • pytest
  • python
  • react
  • render
  • schnorr
  • secp256k1
  • sqlalchemy
  • sqlite
  • tailwindcss
  • typescript
  • vercel
  • vitest
Share this project:

Updates