StarkMole — Backend README

Decentralized Whack-a-Mole Gaming on Stellar

---

Overview

StarkMole's backend is a lightweight Node.js service that indexes on-chain events from the Stellar blockchain, serves game data via REST API, and syncs leaderboard state for the Next.js frontend.

---

Tech Stack

Layer	Technology
Blockchain	Stellar (Soroban Smart Contracts)
Indexer	Node.js + Stellar SDK
API	Express.js
Cache	Redis
Auth	Stellar Wallet Signature Verification

---

Folder Structure

backend/ ├── src/ │ ├── api/ │ │ ├── routes/ │ │ │ ├── game.routes.js │ │ │ ├── leaderboard.routes.js │ │ │ └── player.routes.js │ │ └── middleware/ │ │ └── auth.middleware.js │ ├── indexer/ │ │ ├── eventListener.js │ │ └── leaderboardSync.js │ ├── services/ │ │ ├── stellar.service.js │ │ └── redis.service.js │ └── app.js ├── .env.example └── package.json

---

Environment Variables

STELLAR_NETWORK=testnet
STELLAR_RPC_URL=https://soroban-testnet.stellar.org
STELLAR_CONTRACT_ID=your_contract_id_here
REDIS_URL=redis://localhost:6379
PORT=4000
ADMIN_SECRET_KEY=your_stellar_secret_key

---

API Endpoints

Method	Route	Description
GET	/api/leaderboard/daily	Fetch today's leaderboard
GET	/api/player/:address	Get player stats
POST	/api/game/start	Start a game session
POST	/api/game/end	Submit final score
GET	/api/rewards/:address	Get claimable rewards

---

Setup & Run

# Install dependencies
npm install

# Copy env file
cp .env.example .env

# Start dev server
npm run dev

# Start production
npm start

---

How It Works

1. Player connects their Stellar-compatible wallet (Freighter, xBull, etc.)
2. Backend verifies wallet signature on every request
3. Game session is opened via Soroban contract invocation
4. Score events are indexed in real time and cached in Redis
5. At session end, final score is submitted on-chain
6. Daily reward distribution is triggered by an automated keeper job