ZeaZDev Mini App

A World App Mini App with World ID verification for Sybil-resistant rewards and DeFi features

ZeaZDev is a production-ready World App Mini App that uses Zero-Knowledge Proof (ZKP) via World ID to provide Proof of Personhood verification. Users can claim daily rewards, receive airdrops, manage their wallets, and swap tokens - all with gasless transactions powered by a relayer service.

✨ Key Features

🌍 World ID Verification (ZKP) - Zero-Knowledge Proof verification for Proof of Personhood, preventing Sybil attacks without revealing personal data
📱 React Native Mini App - Mobile-first experience built with Expo, runs natively in World App
🎁 Daily Check-in Rewards - Earn ZEA tokens every 24 hours with streak tracking to incentivize continuous engagement
💰 One-time Airdrop - Welcome bonus for verified World ID users (1000 ZEA tokens)
⚡ Gasless Transactions - Relayer service pays gas fees, enabling frictionless onboarding for new users
💱 DEX Token Swap - Integrated decentralized exchange functionality for swapping WLD, ETH, ZEA, and USDC
👛 Multi-Token Wallet - Manage WLD tokens and gas tokens (ETH/MATIC) with send functionality
🔒 Nullifier Hash Protection - Prevents the same World ID from being used multiple times (anti-replay attack)
🔄 Automatic Streak Tracking - Consecutive daily check-ins build streaks for potential bonus rewards

🛠️ Technology Stack

Frontend (Mini App)

Framework: React Native 0.73 with Expo ~50.0
Navigation: Expo Router ~3.4
World ID SDK: @worldcoin/idkit-core ^1.0
Web3 Integration: ethers.js ^6.10
Storage: @react-native-async-storage/async-storage
Language: TypeScript 5.3+

Backend (Verifier & Relayer)

Runtime: Node.js 18+
API Framework: Express.js 4.18
Web3 Library: ethers.js 6.10
CORS: cors 2.8
Environment: dotenv 16.3

Smart Contracts

Language: Solidity ^0.8.20
Development: Hardhat
Libraries: OpenZeppelin Contracts (Ownable, ReentrancyGuard, IERC20)
Token Standard: ERC-20
Networks: WorldChain (Primary), Ethereum, Base, Sepolia

Key Smart Contract Features

World ID ZKP verification with nullifier tracking
Daily check-in with 24-hour cooldown
One-time airdrop claim system
Check-in streak tracking
Idempotency protection

🚀 Getting Started

⚡ Quick Start: For the fastest way to get started, see QUICK_START.md - includes a one-command setup!

📊 Phase Tracking: Check PHASE_STATUS.md to see the development roadmap and track progress across all phases.

Prerequisites

Before you begin, ensure you have the following installed and configured:

Node.js v18+ - Download here
npm or yarn - Package manager (comes with Node.js)
Expo CLI - Install with npm install -g expo-cli
Expo Go App (iOS/Android) - For testing Mini App on real devices
World ID Account - Register at World App
World ID Developer Portal Access - developer.worldcoin.org
Private Keys:
- Deployer wallet private key (for smart contract deployment)
- Relayer wallet private key (for gasless transactions)
RPC Endpoints - Alchemy or Infura API keys for target blockchain networks

World ID Setup Instructions

Step 1: Register Your Mini App on Worldcoin Developer Portal

Visit the Developer Portal:
- Go to https://developer.worldcoin.org/
- Sign in with your Worldcoin account
Create a New App:
- Click "Create New App"
- Enter app details:
  - App Name: ZeaZDev Mini App
  - App Description: World ID verified rewards and DeFi platform
  - App Type: Mini App
Configure Actions:
- Create an action for verification:
  - Action Name: verify-humanity
  - Action ID: (will be auto-generated, e.g., verify-humanity_12345)
  - Description: Verify user is a unique human for rewards
  - Max Verifications: 1 (per person)
Get Your Credentials:
- App ID: (e.g., app_staging_abc123def456...) - For frontend
- API Key: (e.g., api_secret_xyz789...) - For backend verification
- Action ID: Use for specific verification flows
Configure Callback URLs (if using web version):
- Development: http://localhost:3000
- Production: https://app.zeaz.dev

Step 2: Set Environment Variables

Create a .env file in both mini-app/ and server/ directories:

Installation & Configuration

Clone the Repository

git clone https://github.com/ZeaZDev/ZeaZDev.git
cd ZeaZDev

Configure Mini App (Frontend)

cd mini-app
npm install

Create mini-app/.env:

# World ID Configuration (from Developer Portal)
WORLD_APP_ID=app_staging_your_app_id_here
WORLD_ACTION_ID=verify-humanity_your_action_id

# API Configuration
API_URL=http://localhost:3000
RPC_URL=https://worldchain-mainnet.g.alchemy.com/v2/your-key

Configure Backend Verifier

cd ../server
npm install

Create server/.env:

# Server Configuration
PORT=3000

# World ID Configuration
WORLD_APP_ID=app_staging_your_app_id_here
WORLD_APP_API_KEY=api_your_secret_api_key_here
WORLD_ACTION_ID=verify-humanity_your_action_id

# Blockchain Configuration
RPC_URL=https://worldchain-mainnet.g.alchemy.com/v2/your-key
RELAYER_PRIVATE_KEY=0xYOUR_RELAYER_PRIVATE_KEY

# Contract Addresses (update after deployment)
WORLD_ID_REWARDS_CONTRACT=0x0000000000000000000000000000000000000000
ZEA_TOKEN_CONTRACT=0x0000000000000000000000000000000000000000

Deploy Smart Contracts

cd ../contracts
npm install
npx hardhat compile

# Deploy WorldIDRewards contract
npx hardhat run scripts/deploy-worldid-rewards.js --network worldchain

Copy the deployed contract addresses and update them in server/.env

Legacy Configuration (if using original deployment scripts)

For backward compatibility with existing deployment scripts:

Create .env file in the project root:

# === ZeaZDev Configuration ===

# 1. Network Configuration (Required)
# Format: network_name=rpc_url (comma-separated, no spaces)
MULTI_RPC_LIST="worldchain=https://worldchain-mainnet.g.alchemy.com/v2/YOUR_KEY,base=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY,sepolia=https://sepolia.infura.io/v3/YOUR_KEY"

# 2. Private Keys (Required)
# Deployer Key: Used to deploy contracts and own them
PRIVATE_KEY="0xYOUR_DEPLOYER_PRIVATE_KEY"
# Relayer Key: Hot wallet for gasless transactions
RELAYER_PRIVATE_KEY="0xYOUR_RELAYER_PRIVATE_KEY"

# 3. WorldID Configuration (Required for identity features)
# Public App ID for Frontend/IDKit
WORLD_APP_ID="app_staging_YOUR_APP_ID"
# Secret API Key for Backend verification
WORLD_APP_API_KEY="api_YOUR_API_KEY"

# 4. Domain Configuration (Required for production)
FRONT_DOMAIN="app.zeaz.dev"
DASH_DOMAIN="dash.zeaz.dev"
API_DOMAIN="api.zeaz.dev"

# 5. Block Explorer Verification (Optional)
ETHERSCAN_API_KEY="YOUR_ETHERSCAN_API_KEY"

# 6. Notifications (Optional)
TELEGRAM_BOT_TOKEN="YOUR_BOT_TOKEN"
TELEGRAM_CHAT_ID="YOUR_CHAT_ID"

# 7. Git Logging (Optional)
GIT_LOG_REPO="https://github.com/yourusername/logs.git"
GIT_LOG_BRANCH="main"

Configure Whitelist for Airdrop

Edit the whitelist file for Merkle tree generation:

nano packages/merkle-generator/whitelist.example.json

Example format:

[
  {
    "address": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
    "amount": "100000000000000000000"
  },
  {
    "address": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
    "amount": "250000000000000000000"
  }
]

Running the Project

Quick Start - All Phases (Recommended)

Automated Startup with npm (Easiest)

The simplest way to start all components using npm scripts:

# First-time setup: Validate configuration
npm run check

# Install dependencies for all components
npm run install:all

# Start all services (backend + frontend)
npm start
# or
npm run start:all

# Or for specific components:
npm run start:backend    # Backend only
npm run start:frontend   # Frontend only
npm run status           # Check status
npm run stop             # Stop all services

Alternative: Direct Script Usage

You can also run the script directly:

# First-time setup: Validate configuration
bash start-all-phases.sh --check

# Install dependencies only
bash start-all-phases.sh --install

# Start all services (backend + frontend)
bash start-all-phases.sh --all

# Or for specific components:
bash start-all-phases.sh --backend    # Backend only
bash start-all-phases.sh --frontend   # Frontend only
bash start-all-phases.sh --status     # Check status
bash start-all-phases.sh --stop       # Stop all services
bash start-all-phases.sh --help       # Show help

Environment Setup (First Time):

Before starting services, create your environment configuration files:

# Copy example files
cp server/.env.example server/.env
cp mini-app/.env.example mini-app/.env

# Edit the files with your actual configuration
nano server/.env
nano mini-app/.env

The script will:

✅ Check prerequisites (Node.js, npm)
✅ Validate environment configuration
✅ Install dependencies if needed
✅ Start backend verifier service
✅ Start mini-app with Expo
✅ Display service status
✅ Create logs in Logs/ directory

Phase Status Tracking:

Check PHASE_STATUS.md for development roadmap
Track progress across all 4 phases (Q1-Q4 2025)
View completed and planned features

Manual Startup (Alternative Method)

Step 1: Start Backend Verifier Server

cd server
npm start

The backend will start on http://localhost:3000 and handle:

World ID proof verification
Gasless transaction relay
Reward distribution
Swap quotes

Step 2: Start Mini App

cd mini-app
npm start
# or
expo start

This will open the Expo Dev Tools in your browser.

Step 3: Test on Device

Scan the QR code with Expo Go app (iOS/Android)
The Mini App will load on your device
Test World ID verification flow
Test all features (Wallet, Rewards, Swap)

Running on World App (Production)

To deploy your Mini App to World App:

Build for Production:

cd mini-app
eas build --platform ios
eas build --platform android

Submit to World App:
- Follow World App Mini App submission guidelines
- Provide App ID and action configurations
- Wait for approval

Production Backend:

cd server
npm start
# Use PM2 for process management in production
pm2 start verifier.js --name zeazdev-verifier

Legacy Deployment (Original Scripts)

For backward compatibility with existing deployment infrastructure:

# Run the automated installer
sudo bash run.sh

This will deploy the original Web3 infrastructure including Merkle-based airdrops.

Accessing the Application

Development:

Mini App: Via Expo Go app (scan QR code)
Backend API: http://localhost:3000
Smart Contracts: Deployed on configured networks

Production (World App):

Mini App: Available in World App's Mini Apps section
Backend API: Your production API URL
Smart Contracts: Deployed on WorldChain/Ethereum Mainnet

🧪 Running Tests

To run the automated tests for smart contracts:

cd packages/hardhat
npx hardhat test

To run tests with coverage:

npx hardhat coverage

To run frontend tests:

cd packages/frontend
npm test

📖 Usage Guide

For End Users

First Time Setup

Open ZeaZDev Mini App
- Launch World App on your device
- Navigate to Mini Apps section
- Open ZeaZDev Mini App
Verify with World ID (Required)
- The app will show "Verify with World ID" screen
- Click the verification button
- World App will prompt you to scan with Orb or use Device verification
- Complete the verification process
- Your Zero-Knowledge Proof will be generated and verified
- Once successful, you'll gain access to all features

Daily Usage

Claim Welcome Airdrop (One-time)

After verification, go to "Rewards" tab
Find the "Welcome Airdrop" section
Click "Claim Airdrop"
Confirm the transaction
Receive 1000 ZEA tokens instantly (gasless!)

Daily Check-in

Open "Rewards" tab
Click "Check In Now" button (available every 24 hours)
Earn 100 ZEA tokens per check-in
Build your streak by checking in daily
Track your total rewards and current streak

Manage Wallet

Go to "Wallet" tab
View your WLD and Gas token balances
Send tokens:
- Click "Send" button
- Select token (WLD or ETH)
- Enter recipient address
- Enter amount
- Confirm transaction (gasless!)

Swap Tokens

Go to "Swap" tab
Select tokens to swap (e.g., WLD → ETH)
Enter amount
Review exchange rate and price impact
Click "Swap" and confirm
Transaction executes via DEX (gasless!)

For Developers

Deploy New Instance

Register Mini App:

# Get World App ID and API Key from developer portal
# Update .env files in mini-app/ and server/

Deploy Smart Contracts:

cd contracts
npx hardhat run scripts/deploy-worldid-rewards.js --network worldchain
# Note the contract address

Fund Reward Contract:

# Send ZEA tokens to WorldIDRewards contract
# Ensure relayer wallet has gas tokens

Update Configuration:

# Update contract addresses in server/.env
# Update API URL in mini-app/.env

Start Services:

# Terminal 1: Backend
cd server && npm start

# Terminal 2: Mini App
cd mini-app && expo start

Monitor System

Check Backend Logs:

cd server
npm start
# Watch console for verification requests, transactions

Check Contract Status:

npx hardhat console --network worldchain
> const contract = await ethers.getContractAt("WorldIDRewards", "0x...")
> await contract.getContractBalance()
> await contract.isUserVerified("0x...")

Monitor User Activity:

All events are emitted on-chain
Parse UserVerified, DailyCheckIn, AirdropClaimed events
Track via blockchain explorer

📁 Project Structure

ZeaZDev/
├── contracts/                  # Smart contracts
│   ├── Reward.sol             # Reward distribution contract
│   └── ...
├── scripts/                    # Deployment and utility scripts
│   ├── deploy.js              # Main deployment script
│   └── ...
├── packages/                   # Monorepo packages (if used)
│   ├── hardhat/               # Hardhat configuration
│   ├── frontend/              # Next.js frontend dApp
│   ├── merkle-generator/      # Merkle tree generator
│   └── installer-app/         # Electron installer (optional)
├── Rewards/                    # Reward system documentation
├── .github/                    # GitHub Actions workflows
├── docker-compose.yml          # Docker Compose configuration
├── run.sh                      # Main execution wrapper
├── ZeaZDev-Release-v10.1.sh   # Main installer script
├── PROJECT_BLUEPRINT.md        # Comprehensive project blueprint
├── .env.example               # Environment variables template
└── README.md                  # This file

🔐 Security Considerations

Smart Contract Security

All contracts use OpenZeppelin's battle-tested implementations
Ownable pattern for access control
Idempotency protection to prevent double-spending
ReentrancyGuard for external calls
Regular security audits recommended

Operational Security

Private Keys: Store securely, never commit to version control
Environment Variables: Use .env files, add to .gitignore
Relayer Wallet: Fund with minimal amount, monitor balance
Rate Limiting: Implement on API endpoints
SSL/TLS: Always use HTTPS in production
Firewall: Configure proper firewall rules
Monitoring: Set up alerts for suspicious activities

Best Practices

Use separate deployer and relayer keys
Test on testnets before mainnet deployment
Verify all contracts on block explorers
Implement multi-signature for critical operations
Regular backups of configuration and data
Keep dependencies up to date
Monitor gas prices and adjust strategies
Use hardware wallets for deployer keys in production

🤝 Contributing

Contributions are welcome! To contribute to ZeaZDev:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Please ensure your code follows the existing style and includes appropriate tests.

Development Guidelines

Write clear commit messages
Add tests for new features
Update documentation as needed
Follow Solidity and JavaScript best practices
Run linter before committing

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License Summary

✅ Commercial use
✅ Modification
✅ Distribution
✅ Private use
⚠️ Liability and warranty limitations apply

👤 Contact & Support

Developer: PHIPHAT PHOEMSUK (ZeaZDev)

Email: admin@zeaz.dev

Website: https://app.zeaz.dev/

GitHub: https://github.com/ZeaZDev

Support Channels

GitHub Issues: For bug reports and feature requests
Email: For general inquiries and support
Telegram: Community support (check website for link)

🙏 Acknowledgments

OpenZeppelin - For secure smart contract libraries
Hardhat - For excellent development framework
Worldcoin - For WorldID integration
Ethereum Community - For continuous innovation
Contributors - Thank you to all who have contributed to this project

📊 Project Status

Current Version: v10.1
Status: Active Development
Stability: Beta (use with caution in production)
Last Updated: 2025

Roadmap

📚 Additional Resources

Project Blueprint (Thai) - Comprehensive technical documentation
Smart Contract Documentation - Contract specifications
API Documentation - Backend API reference
Deployment Guide - Detailed deployment instructions
Troubleshooting - Common issues and solutions

Note: This is a living document and will be updated as the project evolves. Always refer to the latest version in the repository.

Made with ❤️ by ZeaZDev Team

Name		Name	Last commit message	Last commit date
Latest commit History 61 Commits
.github		.github
Logs		Logs
Release		Release
Rewards		Rewards
contracts		contracts
mini-app		mini-app
scripts		scripts
server		server
.gitignore		.gitignore
AUTH_SYSTEM.md		AUTH_SYSTEM.md
Changelog		Changelog
DATABASE_SCHEMA.md		DATABASE_SCHEMA.md
DEPLOYMENT.md		DEPLOYMENT.md
DEVELOPER_FOLLOWUP_ROADMAP.md		DEVELOPER_FOLLOWUP_ROADMAP.md
PHASE_STATUS.md		PHASE_STATUS.md
PROJECT_BLUEPRINT.md		PROJECT_BLUEPRINT.md
QUICK_START.md		QUICK_START.md
README.md		README.md
ROADMAP.md		ROADMAP.md
Rev1.md		Rev1.md
Smart Contract — Reward.sol		Smart Contract — Reward.sol
TECH_STACK.md		TECH_STACK.md
TOKENOMICS.md		TOKENOMICS.md
ZEAZDEV_COMPLETE_SUMMARY.md		ZEAZDEV_COMPLETE_SUMMARY.md
ZeaZDev-Release-v10.1.sh		ZeaZDev-Release-v10.1.sh
ZeaZDev-Repair-Dashboard.sh		ZeaZDev-Repair-Dashboard.sh
ZeaZDev-Rewards-Integration.md		ZeaZDev-Rewards-Integration.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
run.sh		run.sh
start-all-phases.sh		start-all-phases.sh
zeazdev-repair.sh		zeazdev-repair.sh

ZeaZDev/ZeaZDev

Folders and files

Latest commit

History

Repository files navigation