StadiumMesh 🏟️⚽

Football Fan Mesh Network + Local AI + Self-Custodial Tipping

A peer-to-peer stadium mesh platform that connects football fans via P2P networking (Pears/Hyperswarm), delivers AI-powered match predictions running entirely on-device (QVAC SDK), and enables self-custodial tipping and payments (WDK/Tether).

Tether Developers Cup 2026 — 3-Track Entry

🧠 QVAC / Local AI — On-device match predictions, fan message classification, RAG knowledge base
📡 Pears / P2P — Distributed fan messaging over Hyperswarm P2P network
💰 WDK / Wallets — Self-custodial wallet creation, fan tipping, goal celebration tips

🏟️ StadiumMesh
├── ⚽ Live Match — Scoreboard, goals, events, real-time SSE
├── 💬 Fan Chat — P2P messaging (Pears) + categorized messages (QVAC)
├── 🤖 AI Predict — QVAC-powered match predictions & RAG
├── 💰 Wallet & Tips — WDK self-custodial tipping
└── 📡 Network — P2P mesh, peer discovery, integration status

Quick Start

# 1. Start the Python server
./server.py

# 2. Start the QVAC sidecar (separate terminal)
cd qvac && npm install && node qvac-service.js

# 3. Open the dashboard
open http://localhost:4180/dashboard

# 4. Use the CLI
./stadium status
./stadium match start "FC Barcelona" "Real Madrid"
./stadium match goal "Messi" 23
./stadium predict "FC Barcelona" "Real Madrid"
./stadium wallet create "My Wallet"

Architecture

┌──────────────────────────────────────────────────────────────┐
│                  StadiumMesh Python Server                   │
│  :4180 — HTTP API, Dashboard, Match Engine, Fan State       │
│  :4191 — P2P Mesh (UDP peer discovery & messaging)          │
└────────────────────┬─────────────────────────────────────────┘
                     │ HTTP (localhost :4198)
┌────────────────────▼─────────────────────────────────────────┐
│              StadiumMesh Node.js Sidecar                     │
│                                                              │
│  ┌─────────────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │  QVAC SDK        │  │  Pears Stack  │  │  WDK Wallet    │  │
│  │  @qvac/sdk       │  │  hyperswarm   │  │  @tether/wdk   │  │
│  │                  │  │  hypercore    │  │                │  │
│  │  • Predictions   │  │  hyperbee     │  │  • Create      │  │
│  │  • Classification│  │              │  │  • Balance      │  │
│  │  • RAG           │  │  • P2P chat  │  │  • Transfer     │  │
│  │  • AI Agents     │  │  • Fan mesh  │  │  • Goal tips    │  │
│  └─────────────────┘  └──────────────┘  └────────────────┘  │
└──────────────────────────────────────────────────────────────┘

Why This Architecture?

The Python server handles real-time match state, HTTP routing, SSE events, and lightweight P2P mesh discovery (stadium-to-stadium). The Node.js sidecar handles all three mandated SDKs:

QVAC requires the Node.js JS/TS SDK (@qvac/sdk)
Pears requires the Pear/Hyperswarm JS runtime
WDK is a JS/TS SDK for self-custodial wallets

The two processes communicate over localhost HTTP, keeping each layer clean and independently testable.

Features by Track

🧠 QVAC — Local AI (Track 1)

Feature	Description
Match Predictor	AI predicts scores, key players, match dynamics
Fan Message Classification	Auto-categorizes messages (celebration, complaint, question, tip-request, general)
RAG Knowledge Base	Ask questions about teams, players, rules — answered from local context
Zero Cloud	All inference runs on-device via `@qvac/sdk` — no API keys, no data exfiltration

AI runs entirely on the user's device using the QVAC SDK (@qvac/sdk). Default model: LLAMA_3_2_1B_INST_Q4_0 (~1B params). Works on laptops, desktops, and SBCs.

📡 Pears — P2P Networking (Track 2)

Feature	Description
Hyperswarm P2P	Distributed fan messaging over the Hyperswarm DHT
Hypercore + Hyperbee	Persistent, append-only message stores per topic
Stadium Topics	Fans join match-specific topics (`stadium-global`, `match-<id>`)
No Central Server	Messages are distributed across the P2P network

Built on the Pears Stack: Hyperswarm for peer discovery, Hypercore for storage, Hyperbee for queryable indexes.

💰 WDK — Self-Custodial Wallets (Track 3)

Feature	Description
Wallet Creation	Create self-custodial wallets for fans
Balance Check	Query wallet balances
Fan Tipping	Send tips between fans during the match
Goal Celebration Tips	Tip a player when they score — celebration economy

Built on the Tether Wallet Development Kit (WDK) — users hold their own keys, non-custodial by design.

API Reference

Match

Method	Path	Description
`GET`	`/status`	Full stadium status
`GET`	`/match/status`	Match state (score, minute, teams)
`POST`	`/match/start`	Start match
`POST`	`/match/stop`	End match
`POST`	`/match/goal`	Score a goal
`GET`	`/match/goals`	Goal history
`GET`	`/match/events`	Match event log

Fans

Method	Path	Description
`POST`	`/fan/message`	Send a fan message (auto-classified by QVAC)
`GET`	`/fan/messages`	Message history
`POST`	`/fan/predict`	Submit a fan prediction
`GET`	`/fan/predictions`	All predictions
`GET`	`/fan/tips`	Tip history

QVAC AI

Method	Path	Description
`GET`	`/qvac/status`	QVAC sidecar status
`POST`	`/qvac/predict`	AI match prediction
`POST`	`/qvac/classify`	Classify a message
`POST`	`/qvac/rag`	Query knowledge base

Pears P2P

Method	Path	Description
`GET`	`/pears/status`	Pears mesh status
`POST`	`/pears/send`	Send P2P message
`GET`	`/pears/messages`	Get P2P messages

WDK Wallet

Method	Path	Description
`GET`	`/wdk/status`	WDK status
`POST`	`/wdk/wallet`	Create wallet
`POST`	`/wdk/balance`	Check balance
`POST`	`/wdk/transfer`	Send tip
`POST`	`/wdk/tip-goal`	Tip a goal!

Events

Method	Path	Description
`GET`	`/events`	Server-Sent Events stream

Football Theme

StadiumMesh wraps the football experience in a playful stadium metaphor:

Element	Meaning
Match	Active game session
Goal	Score event with celebration alert
Fan	Connected user
Message	Fan chat, classified by AI
Tip	P2P payment between fans
Stadium	A mesh node (each stadium is a server)
Pears	P2P messaging layer
Kick Off	Start match
Full Time	End match

CLI Usage

./stadium status                    # Server status
./stadium match start "Arsenal" "Chelsea"  # Start a match
./stadium match goal "Saka" 32     # Score a goal
./stadium match stop               # End match
./stadium predict "Liverpool" "Man City"  # AI prediction
./stadium classify "What a goal!"  # Categorize message
./stadium rag "Who won the 2026 World Cup?"  # RAG query
./stadium wallet create "John"     # Create wallet
./stadium wallet balance <addr>    # Check balance
./stadium wallet transfer <from> <to> 10  # Send tip
./stadium wallet tip-goal <from> "Salah" 5  # Tip a goal!
./stadium pears send global "Hello stadium!"  # P2P broadcast

Environment Variables

Variable	Default	Description
`STADIUM_PORT`	`4180`	HTTP server port
`STADIUM_QVAC_PORT`	`4198`	QVAC sidecar port
`STADIUM_HOST`	localhost	Server hostname
`STADIUM_MESH`	`1`	Enable P2P mesh
`STADIUM_MESH_PORT`	`4191`	Mesh UDP port
`STADIUM_HOME_TEAM`	StadiumMesh FC	Home team name
`STADIUM_AWAY_TEAM`	Hash United	Away team name
`STADIUM_LEAGUE`	Premier League	League name
`STADIUM_NAME`	(hostname)	Stadium name

Project Structure

├── server.py              # Python HTTP + mesh server
├── stadium                # CLI client
├── qvac/
│   ├── package.json       # Node.js dependencies
│   ├── qvac-service.js    # QVAC + Pears + WDK sidecar
│   ├── pears.js           # Pears/Hyperswarm P2P mesh
│   └── wdk.js             # WDK wallet integration
├── web/
│   └── index.html         # Football-themed dashboard SPA
├── README.md
└── LICENSE

How to Run

Prerequisites

Python 3.10+
Node.js 22.17+
npm 10.9+

Step 1: Start the Server

python3 server.py

Step 2: Start the QVAC Sidecar (separate terminal)

cd qvac
npm install
# Fix Bare runtime binary permissions (linux-arm64)
chmod +x node_modules/bare-runtime-linux-arm64/bin/bare 2>/dev/null || true
node qvac-service.js

Step 3: Open Dashboard

Navigate to http://localhost:4180/dashboard

Tether Developers Cup Submission

Track 1 — QVAC (Local AI): All inference via @qvac/sdk — match predictions, message classification, RAG. Zero cloud dependencies. On-device privacy.

Track 2 — Pears (P2P): Hyperswarm-based distributed fan messaging. Hypercore/Hyperbee persistence. Topic-based P2P channels.

Track 3 — WDK (Wallets): Self-custodial wallet creation and tipping. Fan-to-fan transfers. Goal celebration tipping economy.

Judging Criteria:

✅ Technical ambition: 3 independent SDK integrations in a single application
✅ User experience: Real-time dashboard, live SSE events, CLI, AI interactions
✅ Real-world use: Stadium fan engagement, P2P messaging, AI predictions, tipping economy
✅ Creativity: Football-themed mesh protocol, AI-classified fan messages, goal celebration tips
✅ Real use of track: All three SDKs meaningfully integrated and demonstrable

Submission Links

GitHub: https://github.com/WilliamMajanja/StadiumMesh
Demo Video: (create unlisted YouTube link, add to DoraHacks BUIDL)
BUIDL: https://dorahacks.io/hackathon/tether-developers-cup

Track Selection

When submitting on DoraHacks, select all three tracks:

QVAC : Local AI
Pears : Peer to Peer
WDK : Wallets

License

Apache 2.0 — see LICENSE.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

StadiumMesh 🏟️⚽

Quick Start

Architecture

Why This Architecture?

Features by Track

🧠 QVAC — Local AI (Track 1)

📡 Pears — P2P Networking (Track 2)

💰 WDK — Self-Custodial Wallets (Track 3)

API Reference

Match

Fans

QVAC AI

Pears P2P

WDK Wallet

Events

Football Theme

CLI Usage

Environment Variables

Project Structure

How to Run

Prerequisites

Step 1: Start the Server

Step 2: Start the QVAC Sidecar (separate terminal)

Step 3: Open Dashboard

Tether Developers Cup Submission

Submission Links

Track Selection

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
qvac		qvac
web		web
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
server.py		server.py
stadium		stadium

Folders and files

Latest commit

History

Repository files navigation

StadiumMesh 🏟️⚽

Quick Start

Architecture

Why This Architecture?

Features by Track

🧠 QVAC — Local AI (Track 1)

📡 Pears — P2P Networking (Track 2)

💰 WDK — Self-Custodial Wallets (Track 3)

API Reference

Match

Fans

QVAC AI

Pears P2P

WDK Wallet

Events

Football Theme

CLI Usage

Environment Variables

Project Structure

How to Run

Prerequisites

Step 1: Start the Server

Step 2: Start the QVAC Sidecar (separate terminal)

Step 3: Open Dashboard

Tether Developers Cup Submission

Submission Links

Track Selection

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages