Token Hunt

Token Hunt is a location-based treasure hunt game built on Worldcoin that enables sponsors to create geofenced token reward campaigns and allows verified users to discover and claim WLD tokens by physically moving to specific locations.

HOW IT WORKS: Sponsors create "hunts" by dropping a pin on a Mapbox map, setting a radius (5-500m), and funding the campaign with WLD tokens. The system automatically spawns reward tokens uniformly distributed within the hunt area. Each reward represents a fraction of the total pot, calculated as rewardAmount / maxClaims (capped at 50 claims per hunt).

Hunters use the app to see all active hunts globally on an interactive map. Their live GPS location is tracked in real-time, and when they get within 10 meters of an unclaimed reward token, a celebratory animation automatically triggers, claiming the reward. The system uses World ID verification (device-level) to ensure unique users and wallet authentication via Sign-In With Ethereum (SIWE) for secure transactions.

KEY FEATURES:

• World ID verification for unique user identity
• Wallet authentication with SIWE
• Interactive Mapbox maps with real-time GPS tracking
• Automatic reward spawning with uniform geographic distribution
• Proximity-based auto-claiming (10m range)
• Payment integration via Worldcoin MiniKit
• PostgreSQL database for global hunt persistence
• Mobile-responsive design with dark mode support
• Celebration animations and visual feedback

TECHNOLOGY: Built with Next.js 14, TypeScript, Tailwind CSS, shadcn/ui components, Mapbox GL JS, Worldcoin MiniKit SDK, and Vercel Postgres (Neon). All data is stored off-chain in PostgreSQL, with plans for future smart contract integration.

USE CASES: Perfect for location-based marketing campaigns, event engagement, community building, and gamified token distribution. Sponsors can drive foot traffic to specific locations while rewarding users for their participation.

Token Hunt is built as a Next.js 14 App Router application with TypeScript, leveraging server-side rendering for API routes and client-side interactivity for map components.

FRONTEND ARCHITECTURE: The app uses React Server Components with client-side components for interactive features. The UI is built with Tailwind CSS and shadcn/ui components for consistent design. Mapbox GL JS powers the interactive maps via react-map-gl, with dynamic imports to prevent SSR hydration issues. Real-time GPS tracking uses the browser's Geolocation API with watchPosition, implementing distance-based map updates (only re-centers if user moves ≥5m) to minimize API calls.

BACKEND & DATABASE: API routes handle all data operations using Vercel Postgres (Neon serverless PostgreSQL). The database schema includes hunts and rewards tables with CASCADE foreign keys for automatic cleanup. Tables auto-initialize on first request using CREATE TABLE IF NOT EXISTS. All file-based JSON storage was migrated to PostgreSQL while maintaining identical API response formats, ensuring zero frontend changes.

WORLDCOIN INTEGRATION: World ID verification uses MiniKit SDK with device-level verification (no Orb required). The flow: client calls MiniKit.commandsAsync.verify → backend verifies proof via verifyCloudProof → stores verification state. Wallet authentication implements SIWE (Sign-In With Ethereum): backend generates UUID nonce stored in httpOnly cookie → client signs message via MiniKit.commandsAsync.walletAuth → backend verifies signature with verifySiweMessage. Payment flow uses MiniKit.commandsAsync.pay with transaction verification via Worldcoin Developer Portal API.

REWARD SPAWNING ALGORITHM: The most mathematically interesting part: uniform geographic distribution within circular hunt areas. Uses polar coordinates with r = R * sqrt(u) where u is uniform [0,1] to ensure uniform area distribution (not biased toward center). Converts meters to lat/lng deltas using Earth's radius (111,320m/degree) with latitude correction. Idempotent spawning checks existing rewards by huntId before generating new ones.

HACKY SOLUTIONS:

1. Hardcoded database connection string in all API routes (hackathon scope) instead of environment variables
2. Client-side reward claiming detection runs in useEffect with 10m proximity check, avoiding backend polling
3. Distance-based map flyTo optimization prevents unnecessary Mapbox API calls
4. Local state Set tracks claimed rewards to prevent duplicate popups
5. Auto-dismiss popup with 4-second timeout to prevent UI clutter

PARTNER TECHNOLOGIES:

• Worldcoin MiniKit: Seamless wallet integration, World ID verification, and payment processing without custom wallet connectors
• Mapbox: High-performance map rendering with custom markers, geolocation controls, and smooth animations
• Vercel Postgres (Neon): Serverless database with automatic connection pooling, zero-config setup, and CASCADE deletes for data integrity

PERFORMANCE OPTIMIZATIONS:

• useMemo for filtering unclaimed rewards prevents unnecessary re-renders
• Dynamic imports for map components reduce initial bundle size
• Indexed database queries on hunt_id and claimed status for fast lookups
• Batch reward spawning with single API call instead of individual inserts