Khoj

Khoj (meaning "search" or "discovery" in Hindi) is a geo-location based treasure hunt platform that combines real-world exploration with Web3 technology. Users can participate in location-based treasure hunts where they solve riddles, visit physical locations, and earn onchain rewards. Discover a new way to onboard users to Web3 with a Web2-native experience.

• 🔗 khoj-alpha.netlify.app
• ✨ Product Guide
• 📝 Wiki

Screenshots

Hunts list	Hunt details	Creating a team	Team invite code & QR
Join team	Team details	Clue	Hunt end

Architecture Diagram

<sub>Khoj System Architecture and Flow Diagram


Hunt Creation Flow Diagram</sub>

✨ Key Features

Core Gameplay

• Progressive Riddles: Each hunt consists of multiple interconnected clues that tell a story.
• Location-Based Verification: The answer to each clue is a physical location.
• Personalised Clues: The clues are tailored to the user's taste using AI while still keeping the answer same.
• Team based gameplay: Players can form teams and invite other players to join.
• Multiple Attempts: Players get 3 attempts per clue to verify their location
• Real-time Collaboration: Built-in video chat for team coordination.
• Rewards & Reputation: Fastest players win rewards based on a reputation score generated which can be redeemed later.

📦 Application Architecture

Frontend (/frontend)

• Framework: React 18 with TypeScript, Vite build system
• Web3: Thirdweb SDK v5, Wagmi, Viem for blockchain interactions
• UI: TailwindCSS, Radix UI primitives, Framer Motion animations
• Key dependencies: True Network SDK, Huddle01 React, Leaflet maps, React Router
• True Network SDK (/frontend/acm): True Network attestation algorithms

Backend (/backend)

• Framework: Express.js with ES modules
• Web3 Services: Lit Protocol client, Huddle01 server SDK, Pinata IPFS
• Key files: server.js (main server), huddle.js (video), pinata.js (storage)
• APIs: Location verification, file uploads, video room management

Smart Contracts (/contracts)

• Framework: Hardhat with OpenZeppelin contracts
• Contracts: Khoj.sol (main hunt contract), KhojNFT.sol (NFT rewards)
• Testing: Comprehensive test suite in /test/Khoj.test.js
• Deployment: Multi-chain support (Moonbeam, PassetHub and Base)

/frontend/          - React/TypeScript Web3 frontend
  /acm/            - AssemblyScript True Network component  
  /src/components/ - React components (Clue.tsx, HuntDetails.tsx key files)
  package.json     - Frontend dependencies and scripts
/backend/          - Express.js Web3 backend
  server.js        - Main server with Lit Protocol integration
  package.json     - Backend dependencies  
/contracts/        - Hardhat smart contracts
  /src/            - Solidity contracts (Khoj.sol, KhojNFT.sol)
  /test/           - Contract test suite
  package.json     - Contract build and test scripts

🚀 Installation Instructions

1. Fork and Clone the repository:

git clone https://github.com/yourusername/Khoj.git

Initial Setup Commands

# Install dependencies
cd frontend && npm install  # Takes ~90 seconds
cd ../backend && npm install  # Takes ~25 seconds  
cd ../contracts && npm install  # Takes ~15 seconds

Environment Setup

1. Backend environment:

   cd backend && cp .env.example .env

   Required variables: HUDDLE_PROJECT_ID, HUDDLE_API_KEY, PRIVATE_KEY, PINATA_JWT, PINATA_GATEWAY, HOST, PORT, MAX_DISTANCE_IN_METERS

2. Frontend environment:

   cd frontend && cp .env.example .env  

   Required variables: VITE_PUBLIC_THIRDWEB_CLIENT_ID, VITE_PUBLIC_HUDDLE_PROJECT_ID, VITE_PUBLIC_HUDDLE_API_KEY, VITE_PUBLIC_TRUE_NETWORK_SECRET_KEY, contract addresses for Base/Moonbase/Asset Hub, VITE_PUBLIC_BACKEND_URL, VITE_PUBLIC_GEMINI_API_KEY

👥 Team

• Abhiraj Mengade
• Ayush Kumar Singh
• Mardav Gandhi
• Parth Mittal
• Shubham Rasal

Built with ❤️ by Team Khoj!