🛡️ Hexora

Hexora is a bug bounty platform for web games and websites. People find bugs, submit a report, and once it’s approved, they get paid automatically in crypto (ETH) — straight to their wallet, no manual transfer needed.

This is a learning project — built to practice full-stack development, wallet-based login, and smart contracts.

---

✨ What it does

• 🔐 Login with Google — simple and free, no extra email verification needed.
• 🦊 Connect a wallet — users link MetaMask by signing a message to prove it’s really theirs.
• 📋 Bug bounty programs — a list of websites/games open for testing, each with reward tiers.
• 🐛 Submit a bug report — title, description, attachments, steps to reproduce, and evidence.
• 🧮 Automatic severity suggestion — a simple scoring system suggests how serious the bug is, based on its category and impact.
• ✅ Admin gives final approval — a real person always makes the final call before any money is sent.
• ⚡ Automatic payout — once approved, a smart contract sends the reward to the bug finder’s wallet by itself.

---

🧱 Tech Stack

Layer	Tech
Frontend	Next.js, Tailwind CSS, shadcn/ui, Framer Motion
Wallet login	wagmi, ethers.js, SIWE
Google login	NextAuth.js
Backend	Express.js, TypeScript
Database	PostgreSQL, Prisma
Smart contract	Solidity, Hardhat
Network	Ethereum Sepolia (test network, not real money)

---

🏗️ Project Structure

hexora/
├── apps/
│   ├── web/        # Next.js frontend
│   └── api/         # Express backend
├── contracts/         # Hardhat + Solidity escrow contract
├── README.md
└── ARCHITECTURE.md

---

🚀 Getting Started

What you need first

• Node.js (version 18 or higher)
• PostgreSQL (running locally or hosted somewhere)
• A free Google Cloud project with OAuth login set up
• MetaMask installed in your browser
• Some free Sepolia test ETH (get some here)

1. Clone the project

git clone https://github.com/your-username/hexora.git
cd hexora
npm install

2. Set up your environment variables

Create a .env file in apps/api and another in apps/web:

# apps/api/.env
DATABASE_URL="postgresql://user:password@localhost:5432/hexora"
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""
BACKEND_SIGNER_PRIVATE_KEY=""   # the wallet allowed to trigger payouts
ESCROW_CONTRACT_ADDRESS=""
SEPOLIA_RPC_URL=""

# apps/web/.env
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET=""
NEXT_PUBLIC_API_URL="http://localhost:4000"

3. Set up the database

cd apps/api
npx prisma migrate dev
npx prisma db seed   # adds a few example programs to test with

4. Deploy the smart contract (test network)

cd contracts
npx hardhat compile
npx hardhat run scripts/deploy.ts --network sepolia
# copy the deployed contract address into apps/api/.env

5. Run everything

npm run dev

• Frontend: http://localhost:3000
• Backend: http://localhost:4000

---

🔄 How It Works (Step by Step)

1. Log in with Google — this confirms your email is real.
2. Connect your wallet — sign a message to prove you own it.
3. Pick a program — choose a website or game to test.
4. Submit a report — describe the bug, how to reproduce it, and add evidence.
5. The system suggests a severity — automatically, using simple rules (no AI needed).
6. Admin reviews and approves — a person checks it and confirms or adjusts the severity.
7. You get paid automatically — the smart contract sends the reward straight to your wallet.

---

⚠️ Disclaimer

This is a learning project. It runs on the Ethereum Sepolia test network, using free test coins — not real money. The smart contract has not been professionally audited, so it should never be used with real funds on the main Ethereum network.

---