Token Snatcher (Whack-to-Earn)

A decentralized arcade game where players “snatch” tokens before they disappear and earn real on-chain rewards.

This project demonstrates:

Skill-based Web3 gaming

Secure score validation

On-chain reward distribution

Transparent leaderboard

NFT-powered multipliers

📁 Project Structure token-snatcher/ │ ├── frontend/ → Next.js game client ├── backend/ → NestJS API server ├── contract/ → Soroban smart contract │ └── README.md 🖥 FRONTEND — Next.js 📌 Overview

The frontend is responsible for:

Rendering the game UI

Handling player interactions

Connecting wallet

Starting game sessions

Submitting scores

Displaying leaderboard

It does NOT control rewards. All rewards are validated on-chain.

🏗 Tech Stack

Next.js

TypeScript

Phaser.js (game engine)

Stellar Wallet integration (Freighter compatible)

Tailwind (optional styling)

📁 Folder Structure frontend/ │ ├── app/ │ ├── page.tsx │ ├── leaderboard/ │ ├── ranked/ │ └── free/ │ ├── components/ │ ├── GameCanvas.tsx │ ├── WalletButton.tsx │ ├── ScoreBoard.tsx │ └── Leaderboard.tsx │ ├── game/ │ ├── scenes/ │ │ ├── GameScene.ts │ │ └── ResultScene.ts │ │ │ ├── spawnLogic.ts │ └── scoring.ts │ ├── services/ │ ├── contract.service.ts │ ├── wallet.service.ts │ └── api.service.ts │ ├── utils/ │ └── constants.ts │ └── package.json 🎮 Game Flow (Ranked Mode)

Player connects wallet

Player clicks “Start Ranked Game”

Frontend calls contract → start_session()

Contract returns session ID + randomness seed

Game starts using that seed

Player finishes round

Frontend calls → submit_score()

Smart contract validates score

Reward distributed automatically

▶ Installation cd frontend npm install npm run dev

App runs at:

http://localhost:3000 🖥 BACKEND — NestJS 📌 Overview

The backend is optional but recommended.

It handles:

Leaderboard caching

Tournament scheduling

Analytics

Bot detection

Listening to blockchain events

The backend does NOT control rewards.

🏗 Tech Stack

NestJS

TypeScript

PostgreSQL

Stellar SDK

📁 Folder Structure backend/ │ ├── src/ │ ├── modules/ │ │ ├── game/ │ │ │ ├── game.controller.ts │ │ │ └── game.service.ts │ │ │ │ │ ├── leaderboard/ │ │ │ ├── leaderboard.controller.ts │ │ │ └── leaderboard.service.ts │ │ │ │ │ └── tournaments/ │ │ │ ├── blockchain/ │ │ ├── stellar.service.ts │ │ └── contract.listener.ts │ │ │ ├── database/ │ │ └── entities/ │ │ │ └── main.ts │ └── package.json 🔁 Backend Responsibilities 1️⃣ Listen to Smart Contract Events

New session started

Score submitted

Reward paid

2️⃣ Cache Leaderboard

Instead of querying blockchain every time.

3️⃣ Anti-Bot Monitoring

Detect abnormal play frequency.

▶ Installation cd backend npm install npm run start:dev

Runs at:

http://localhost:4000 🦀 SMART CONTRACT — Stellar (Soroban) 📌 Overview

The smart contract is the core of the system.

It handles:

Game sessions

Random seed generation

Score validation

Reward distribution

Leaderboard updates

NFT multiplier logic

All financial logic lives here.

📁 Folder Structure contract/ │ ├── src/ │ ├── lib.rs │ ├── game.rs │ ├── rewards.rs │ ├── leaderboard.rs │ ├── storage.rs │ └── errors.rs │ ├── tests/ │ ├── test_game.rs │ ├── test_rewards.rs │ └── test_leaderboard.rs │ ├── Cargo.toml └── README.md 🔑 Core Contract Functions start_session(player: Address) -> u64

submit_score(session_id: u64, score: u32)

claim_reward(session_id: u64)

get_leaderboard() -> Vec 🔐 Anti-Cheat Mechanism

The contract:

Generates randomness seed

Stores start timestamp

Enforces time limit

Calculates max theoretical score

Rejects impossible values

Prevents duplicate submissions

Frontend scores are verified mathematically.

▶ Build Contract cd contract cargo build --target wasm32-unknown-unknown --release 🚀 Deploy to Testnet soroban contract deploy
--wasm target/wasm32-unknown-unknown/release/token_snatcher.wasm
--source your-identity 🔄 How Everything Works Together Player clicks token ↓ Frontend updates score ↓ Player submits score ↓ Contract verifies logic ↓ Reward distributed ↓ Backend caches event ↓ Leaderboard updates