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.
• Schedule hunts with start/end datetimes, timezone-aware display, countdowns for upcoming hunts, and reminder emails before launch.
• 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

Prerequisites

• Node.js 18+ and pnpm
• Git
• For blockchain features: Stellar wallet (e.g., Freighter)
• For file uploads: Pinata account (Get API key)
• For email features: Resend account (Get API key)

Installation

1. Clone the repository:

git clone https://github.com/Samuel1-ona/hunty.git
cd hunty

2. Install dependencies at the root:

pnpm install

3. Set up environment variables:

# Copy the example environment file
cp .env.example .env.local

Open .env.local and configure your environment variables. See .env.example for detailed documentation of all available options. Key variables include:

• PINATA_JWT - Required for IPFS file uploads
• RESEND_API_KEY - Required for email notifications
• NEXT_PUBLIC_WC_PROJECT_ID - Required for WalletConnect support
• DATABASE_URL - PostgreSQL connection string
• Contract addresses - Your deployed Soroban smart contract addresses

For detailed setup instructions, see DEVELOPMENT.md.

4. Run the web app in development:

pnpm dev

The app will be available at http://localhost:3000.

5. Start the mobile app from mobile/:

cd mobile
pnpm install
expo start

6. Mobile EAS Build & OTA setup:

cd mobile
pnpm run build:android:dev
pnpm run build:ios:preview
pnpm run update:preview

5. Configure reminder emails (optional but recommended for scheduled start reminders):

export RESEND_API_KEY=your_api_key

6. Run tests:
7. Run tests:

pnpm test
pnpm run test:coverage
pnpm run e2e

The local coverage command writes an HTML report to coverage/index.html.

Hunt scheduling

Creators can now define a hunt start and end time in their local timezone. The app stores those values in UTC internally and displays them for viewers in their browser timezone. Scheduled hunts automatically transition through scheduled → active → ended, and the reminder API can send a start-notice email to the creator ahead of launch.

Docker development

This repository includes a local Docker development environment for the web app and a PostgreSQL database container.

1. Build and start the development stack:

docker compose up --build

2. Open the web app at:

http://localhost:3000

3. PostgreSQL is available at localhost:5432 with:

• POSTGRES_USER=hunty
• POSTGRES_PASSWORD=hunty
• POSTGRES_DB=hunty_dev

4. Code changes are mounted from the host into the container, so hot reload works automatically.

5. Stop the stack:

docker compose down

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.