mirror of
https://github.com/arkorty/B.Tech-Project-III.git
synced 2026-04-19 12:41:48 +00:00
382 lines
11 KiB
Markdown
382 lines
11 KiB
Markdown
# 🪙 D.M.T.P — Agentic AI-Verified Micro-Task Platform on Celo Blockchain
|
||
|
||
An **AI-powered decentralized task Platform** built on **Celo Sepolia Testnet**, where requesters post micro-tasks, workers complete them, AI verifies the results, and **payments are automatically released in cUSD** upon approval.
|
||
|
||
---
|
||
|
||
## 📋 Table of Contents
|
||
|
||
- [Overview](#-overview)
|
||
- [Tech Stack](#️-tech-stack)
|
||
- [AI Integration](#-ai-integration-google-gemini-15-pro)
|
||
- [Database Schema](#️-database-schema-core-entities)
|
||
- [Folder Structure](#-folder-structure)
|
||
- [Setup Guide](#️-setup-guide)
|
||
- [Smart Contract Deployment](#-smart-contract-deployment)
|
||
- [Workflow](#-workflow)
|
||
- [API Examples](#-example-api-calls)
|
||
- [Architecture](#-architecture-diagram)
|
||
- [Features](#-features-checklist)
|
||
- [Testing](#-testing)
|
||
- [Deployment](#-deployment)
|
||
- [Future Roadmap](#-future-roadmap)
|
||
- [License](#-license)
|
||
|
||
---
|
||
|
||
## ⚡ Overview
|
||
|
||
**D.M.T.P** introduces verifiable trust between micro-task requesters and workers. AI moderation (powered by **Google Gemini**) ensures submissions are **authentic and high-quality**, while the **TaskEscrow smart contract** on **Celo** guarantees transparent, secure on-chain payments.
|
||
|
||
### Key Features
|
||
|
||
- 🤖 **AI-Powered Verification** — Automated content moderation using Google Gemini
|
||
- ⛓️ **Blockchain Escrow** — Smart contract-based payment security
|
||
- 💰 **Instant Payments** — Automatic cUSD release upon task approval
|
||
- 🔐 **Wallet Authentication** — Secure login via MetaMask or MiniPay
|
||
- 📊 **Real-Time Updates** — Live task and submission status tracking
|
||
- 🎯 **Quality Control** — AI prevents spam, fraud, and low-effort submissions
|
||
|
||
---
|
||
|
||
## 🛠️ Tech Stack
|
||
|
||
### 🖥️ Frontend — Next.js (App Router)
|
||
|
||
| Feature | Library/Framework |
|
||
| ------------------ | --------------------------------------------------- |
|
||
| UI Components | [shadcn/ui](https://ui.shadcn.com) |
|
||
| Styling | [TailwindCSS](https://tailwindcss.com) |
|
||
| State Management | [Zustand](https://zustand-demo.pmnd.rs) |
|
||
| Data Fetching | [TanStack Query](https://tanstack.com/query/v5) |
|
||
| Wallet Integration | [wagmi](https://wagmi.sh) + [viem](https://viem.sh) |
|
||
| Blockchain SDK | [@celo/contractkit](https://docs.celo.org/) |
|
||
| Wallets Supported | **MiniPay** and **MetaMask** |
|
||
| AI Moderation | [Google Gemini 1.5](https://ai.google.dev/gemini-api/) |
|
||
|
||
### ⚙️ Backend — Express.js + TypeScript
|
||
|
||
| Feature | Technology |
|
||
| ----------------- | ------------------------------------------ |
|
||
| Framework | Express.js |
|
||
| Database | PostgreSQL + Prisma ORM |
|
||
| Job Queue | Bull + Redis |
|
||
| AI Verification | Gemini API |
|
||
| Blockchain | Celo Sepolia |
|
||
| Authentication | Wallet Signature (EIP-191) |
|
||
| File Verification | cUSD Escrow via TaskEscrow.sol |
|
||
| Notifications | Background service + WebSocket placeholder |
|
||
|
||
### ⛓️ Blockchain — Celo Sepolia Testnet
|
||
|
||
- **Smart Contract:** `TaskEscrow.sol`
|
||
- Holds task payments in escrow
|
||
- Releases funds when AI-verified
|
||
- Refunds requester if submissions are rejected
|
||
- **Token:** `cUSD` (Stablecoin)
|
||
- **Network RPC:** https://forno.celo-sepolia.celo-testnet.org
|
||
- **Explorer:** [CeloScan (Sepolia)](https://sepolia.celoscan.io)
|
||
|
||
---
|
||
|
||
## 🤖 AI Integration (Google Gemini 2.5 Pro)
|
||
|
||
Used for:
|
||
|
||
- ✅ Spam, fraud, and duplicate prevention
|
||
- ✅ Toxic or low-effort content rejection
|
||
- ✅ Criteria-based submission scoring
|
||
|
||
Gemini runs asynchronously in a **Bull Queue worker**, sending results via webhook to approve or reject submissions.
|
||
|
||
---
|
||
|
||
## 🗄️ Database Schema (Core Entities)
|
||
|
||
| Table | Description |
|
||
| ----------------------- | ---------------------------------------------------------------------------------- |
|
||
| **users** | Stores wallet addresses, roles (`requester` / `worker`), reputation & earnings |
|
||
| **tasks** | Contains task metadata, blockchain taskID, payment amount, expiry |
|
||
| **submissions** | Tracks worker submissions, AI verification results |
|
||
| **payments** | Logs payment releases (+txHash) |
|
||
| **notifications** | In-app notifications for verification or payment updates |
|
||
|
||
---
|
||
|
||
## 💎 Folder Structure
|
||
|
||
```
|
||
D.M.T.P/
|
||
├── client/ # Next.js frontend
|
||
│ ├── app/ # App Router pages
|
||
│ ├── components/ # shadcn + custom UI
|
||
│ ├── hooks/ # Zustand + wagmi hooks
|
||
│ ├── lib/ # API client + Celo utils
|
||
│ └── types/ # Shared TypeScript models
|
||
│
|
||
└── server/ # Express backend
|
||
├── src/
|
||
│ ├── routes/ # /api/v1 tasks, submissions, users
|
||
│ ├── controllers/ # Request handlers
|
||
│ ├── services/ # AI, blockchain, queue, moderation
|
||
│ ├── workers/ # Bull verification worker
|
||
│ └── database/ # Prisma schema + migrations
|
||
└── prisma/
|
||
```
|
||
|
||
---
|
||
|
||
## ⚙️ Setup Guide
|
||
|
||
### Prerequisites
|
||
|
||
- ✅ Node.js >= 20
|
||
- ✅ npm >= 9
|
||
- ✅ Redis (running locally or hosted)
|
||
- ✅ PostgreSQL database
|
||
- ✅ Celo wallet with test cUSD
|
||
|
||
### 1️⃣ Environment Variables
|
||
|
||
#### `.env` (Backend)
|
||
|
||
```env
|
||
# Server
|
||
PORT=3001
|
||
NODE_ENV=development
|
||
|
||
# Database
|
||
DATABASE_URL="postgresql://user:password@localhost:5432/D.M.T.P"
|
||
|
||
# Blockchain
|
||
PRIVATE_KEY=YOUR_PRIVATE_KEY_WITH_CUSD
|
||
CELO_RPC_URL=https://forno.celo-sepolia.celo-testnet.org
|
||
CONTRACT_ADDRESS=0xYourTaskEscrowAddress
|
||
CUSD_SEPOLIA_ADDRESS=0x874069fa1eb16d44d622f2e0ca25eea172369bc1
|
||
|
||
# AI (Gemini)
|
||
GEMINI_API_KEY=your_google_gemini_api_key
|
||
|
||
# Redis
|
||
REDIS_HOST=localhost
|
||
REDIS_PORT=6379
|
||
```
|
||
|
||
#### `.env.local` (Frontend)
|
||
|
||
```env
|
||
NEXT_PUBLIC_API_URL=http://localhost:3001
|
||
NEXT_PUBLIC_CELO_RPC_URL=https://forno.celo-sepolia.celo-testnet.org
|
||
NEXT_PUBLIC_CUSD_ADDRESS=0x874069fa1eb16d44d622f2e0ca25eea172369bc1
|
||
NEXT_PUBLIC_CONTRACT_ADDRESS=0xYourTaskEscrowAddress
|
||
NEXT_PUBLIC_CHAIN_ID=44787
|
||
```
|
||
|
||
### 2️⃣ Backend Setup
|
||
|
||
```bash
|
||
cd server
|
||
npm install
|
||
|
||
# Prisma setup + migrate
|
||
npx prisma generate
|
||
npx prisma db push
|
||
|
||
# Start Redis (using Docker)
|
||
docker run -d -p 6379:6379 redis:alpine
|
||
|
||
# Start backend in dev mode
|
||
npm run dev
|
||
```
|
||
|
||
### 3️⃣ Frontend Setup
|
||
|
||
```bash
|
||
cd client
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
Visit → [http://localhost:3000](http://localhost:3000)
|
||
|
||
---
|
||
|
||
## 💰 Smart Contract Deployment
|
||
|
||
### Our Deployed Smart Contract- [0xa520d207c91C0FE0e9cFe8D63AbE02fd18B2254e](https://sepolia.celoscan.io/address/0xa520d207c91c0fe0e9cfe8d63abe02fd18b2254e)
|
||
Deploy `TaskEscrow.sol` on **Celo Sepolia** using Remix or Hardhat.
|
||
|
||
### Compile & Deploy
|
||
|
||
```bash
|
||
npx hardhat run scripts/deploy.ts --network celo-sepolia
|
||
```
|
||
|
||
### Verify Contract
|
||
|
||
```bash
|
||
npx hardhat verify --network celo-sepolia 0xYourContractAddress "0x874069fa1eb16d44d622f2e0ca25eea172369bc1"
|
||
```
|
||
|
||
---
|
||
|
||
## 🧠 Workflow
|
||
|
||
### ✳️ Requester Flow
|
||
|
||
1. Connect wallet → Create Task
|
||
2. Payment locked in smart contract
|
||
3. Task visible to workers
|
||
|
||
### 🛠️ Worker Flow
|
||
|
||
1. Accept Task → Submit Response
|
||
2. Gemini AI verifies content
|
||
3. If approved ✅ → Payment auto-released (cUSD)
|
||
4. If rejected ❌ → Refund to requester
|
||
|
||
---
|
||
|
||
## 🧾 Example API Calls
|
||
|
||
### Create Task
|
||
|
||
```http
|
||
POST /api/v1/tasks/create
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"title": "Label Images",
|
||
"description": "Tag each image with emotion category",
|
||
"paymentAmount": 3.5,
|
||
"expiresAt": "2025-11-10T12:00:00Z"
|
||
}
|
||
```
|
||
|
||
### Submit Task
|
||
|
||
```http
|
||
POST /api/v1/submissions/submit
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"taskId": "uuid",
|
||
"submissionData": {
|
||
"imageUrls": ["https://ipfs.tech/image1.png"],
|
||
"metadata": { "label": "happy" }
|
||
}
|
||
}
|
||
```
|
||
|
||
**AI Queue → Gemini Verification → Payment Released**
|
||
|
||
---
|
||
|
||
## 🧱 Architecture Diagram
|
||
|
||
```
|
||
┌────────────┐
|
||
│ Next.js │────┐
|
||
└────────────┘ │
|
||
▼
|
||
┌───────────┐ ┌──────────────┐
|
||
│Express.js │◄─│ PostgreSQL │
|
||
└───────────┘ └──────────────┘
|
||
│
|
||
┌─────┼──────┐
|
||
▼ ▼ ▼
|
||
Gemini Redis Celo
|
||
AI /Bull Network
|
||
(Verify) (Queue) (Escrow)
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ Features Checklist
|
||
|
||
- [X] Wallet Signature Login (EIP-191)
|
||
- [X] Gemini-based Content Moderation
|
||
- [X] Blockchain-Backed Escrow Payments
|
||
- [X] Task + Submission CRUD
|
||
- [X] Bull Queue Worker Verification
|
||
- [X] Real-Time Status Updates
|
||
- [X] cUSD Balance Tracking
|
||
- [X] Transaction Confirmation + CeloScan Link
|
||
- [X] Admin + Requester Dashboard
|
||
- [X] Fully Responsive UI
|
||
|
||
---
|
||
|
||
## 🧪 Testing
|
||
|
||
```bash
|
||
# Run backend tests
|
||
cd server
|
||
npm run test
|
||
|
||
# Database Studio
|
||
npx prisma studio
|
||
|
||
# Queue dashboard
|
||
npm run bull:dashboard
|
||
```
|
||
|
||
---
|
||
|
||
## 🌍 Deployment
|
||
|
||
### Suggested Setup
|
||
|
||
| Layer | Platform | Notes |
|
||
| -------- | ------------------------------------------------------- | ------------------------ |
|
||
| Frontend | [Vercel](https://vercel.com) | Auto-deploy from main |
|
||
| Backend | [Railway](https://railway.app) / [Render](https://render.com) | Node + Postgres service |
|
||
| Database | Neon / Supabase | Free Postgres DB |
|
||
| Redis | Upstash / Redis Cloud | Connection for Bull jobs |
|
||
|
||
---
|
||
|
||
## 🧠 Future Roadmap
|
||
|
||
- 🪄 On-chain Gemini verification proofs
|
||
- 🧩 Decentralized task reputation scoring
|
||
- 💬 Worker messaging + chat
|
||
- 🪶 File uploads to IPFS / Web3.Storage
|
||
- ⚙️ Multi-network support (Base, Polygon)
|
||
|
||
---
|
||
|
||
## 🪙 Credits
|
||
|
||
Developed with 💚 on the Celo blockchain.
|
||
|
||
Built using **Next.js**, **Celo ContractKit**, **Gemini AI**, and **Prisma**.
|
||
|
||
---
|
||
|
||
## 📝 License
|
||
|
||
This project is licensed under the **MIT License** — feel free to fork and extend 💡
|
||
|
||
---
|
||
|
||
## 👥 Contributing
|
||
|
||
Contributions are welcome! Please feel free to submit a Pull Request.
|
||
|
||
1. Fork the repository
|
||
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
|
||
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
|
||
4. Push to the branch (`git push origin feature/AmazingFeature`)
|
||
5. Open a Pull Request
|
||
|
||
---
|
||
|
||
## 📧 Contact
|
||
|
||
For questions or support, please open an issue on [GitHub](https://github.com/Rio-awsm/micro-job-ai-agent-web3/issues).
|
||
|
||
---
|
||
|
||
<p align="center">Made with ❤️ for the Celo ecosystem</p>
|