Hunty

Hunty is a cross-platform scavenger-hunt platform and dApp that combines web, mobile, and on-chain rewards. Creators publish location-based hunts and players complete challenges to earn NFTs, tokens, and other reward assets via Stellar/Soroban.

Highlights

• Multi-platform: Web app built with Next.js App Router and a React Native mobile app in mobile/.
• On-chain rewards: Stellar/Soroban smart-contract integrations, wallet adapters, and NFT reward flows.
• Decentralized assets: IPFS-hosted media and metadata for hunts, NFTs, and rewards.
• Developer tooling: Type-safe TypeScript code, Vitest unit tests, and Playwright E2E tests.

Key Features

• Create, publish, and manage hunts from a creator dashboard.
• Play hunts with location and clue validation, progress tracking, and completion flows.
• Mint and claim NFT rewards and on-chain token payouts for completed hunts.
• Community and leaderboard features for social play and competition.

Tech Stack

• Frontend: Next.js, React, TypeScript
• Mobile: Expo / React Native
• Storage: IPFS for media and metadata
• Blockchain: Stellar + Soroban smart contracts, Freighter wallet support
• Testing: Vitest for unit tests, Playwright for E2E
• Tooling: pnpm, Tailwind CSS, PostCSS

Repository Structure

• app/ — Next.js app router routes and pages for the web UI
• components/ — Reusable React components and UI patterns
• lib/ — Core utilities, blockchain adapters, stores, and helpers
• mobile/ — Expo React Native mobile app and mobile-specific assets
• public/ — Static assets served by the web app
• e2e/ — End-to-end Playwright tests
• components/__tests__/, lib/__tests__/ — Unit tests

Getting Started

1. Install dependencies at the root:

pnpm install

2. Run the web app in development:

pnpm dev

3. Start the mobile app from mobile/:

cd mobile
pnpm install
expo start

4. Run tests:

pnpm test
pnpm run e2e

Notes

• This project prefers pnpm; a pnpm-lock.yaml is included.
• On-chain reward flows require wallet integrations and a local or testnet Stellar environment.
• See lib/walletAdapter.ts and lib/stellarErrors.ts for wallet helpers and common error handling.

Roadmap

• Finalize and audit Soroban reward contracts.
• Improve on-chain UX with clearer signing prompts and gasless flows.
• Add persistent IPFS pinning and CDN fallback for asset availability.
• Expand mobile parity with offline play support.
• Add creator templates, analytics, and better minting tools.
• Build community features like messaging, team hunts, and governance.

Contributing

• See CONTRIBUTING.md for contribution guidelines.
• Use branches for feature work and include tests with focused changes.

Contact

• Open issues or PRs on the repository.
• Tag maintainers for urgent review requests.

License

This project is open source under the MIT License.