Zolymarket

Private Prediction Markets on Zama FHEVM

A fully decentralized prediction market platform that leverages Fully Homomorphic Encryption (FHE) to keep your bet amounts completely private while maintaining transparent market outcomes. Built on Zama's FHEVM technology, Zolymarket enables users to place encrypted bets on real-world events without revealing their positions to other participants.

Built with Zama FHEVM

This is a production-ready FHEVM implementation showcasing private prediction markets with encrypted bet amounts, option selections, and oracle-based decryption.

👉 Technical Deep Dive: FHEVM_INTEGRATION.md - Complete guide on encryption workflows, smart contract patterns, relayer callbacks, and privacy architecture

🌟 Key Features

🔒 Privacy-First Architecture

Encrypted Bet Amounts: Individual bet amounts are encrypted using FHEVM (euint64) - no one can see how much you bet
Encrypted Option Selection: Your chosen options are encrypted on-chain using FHEVM (euint8) - other users cannot see your positions
Encrypted User Balances: Total platform balance encrypted using FHEVM homomorphic encryption
Encrypted Pool Totals: Total amounts staked on each option encrypted during betting period
Oracle-Based Decryption: After bet ends, admin requests decryption and Zama oracle reveals encrypted totals for payout calculation
Transparent Outcomes: Final results and statistics become publicly visible after decryption

🎯 Multiple Market Types

Binary Markets: Simple Yes/No predictions (e.g., "Will Bitcoin reach $100K?")
Multiple Choice: Select from 3+ exclusive outcomes (e.g., "Who will win the championship?")
Nested Markets: Independent propositions with Yes/No outcomes for each

📊 Advanced Features

Parimutuel Odds System: Fair, pool-based payout calculation
Real-time Statistics: Live volume tracking with encrypted data aggregation
Category Management: Organized markets with drag-and-drop reordering
Admin Dashboard: Complete market management interface with analytics
Two-Step Payout System: Request payout → Relayer decrypts → Claim winnings
Mobile Responsive: Seamless experience across all devices

🛡️ Security & Decentralization

Smart Contract Powered: All logic runs on-chain with zero downtime
Role-Based Access: Granular admin permissions (Super Admin, Bet Manager, Category Manager)
Relayer Decryption: Off-chain decryption only when users claim payouts, keeping bets private throughout the betting period
MongoDB for UX: Stores metadata like bet titles, categories, and user positions for quick filtering and sorting without exposing encrypted amounts

📚 Documentation

🔍 Deep Dive: FHEVM Integration

For a comprehensive technical guide on how Fully Homomorphic Encryption is integrated into this project, including:

Encryption/decryption workflows
Smart contract FHEVM patterns
Frontend FHEVM client integration
Relayer callback architecture
Privacy guarantees and trade-offs

👉 Read the full guide: FHEVM_INTEGRATION.md

📖 User Guides

User Guide: Complete guide for placing bets, claiming winnings, and using the platform
Admin Guide: Comprehensive guide for administrators managing markets and categories

🏗️ Architecture

zolymarket/
├── hardhat/              # Smart contracts & deployment
│   ├── contracts/        # Solidity contracts with FHEVM
│   │   ├── BetMarketCore.sol       # Core betting logic
│   │   ├── BetMarketPayout.sol     # Payout & claiming
│   │   ├── BetMarketStats.sol      # Statistics aggregation
│   │   └── CategoryManager.sol     # Category management
│   └── scripts/          # Deployment scripts
│
├── frontend/             # React.js application
│   ├── src/
│   │   ├── components/   # Reusable UI components
│   │   ├── pages/        # Page components (Home, Dashboard, Admin)
│   │   ├── hooks/        # Custom hooks (useWallet, useFHEVM)
│   │   ├── lib/          # FHEVM client integration
│   │   └── services/     # API clients & utilities
│   └── vite.config.js    # Build configuration
│
└── backend/              # Node.js + Express API
    ├── routes/           # API endpoints
    ├── models/           # MongoDB schemas
    └── middleware/       # Auth & validation

🚀 Quick Start

Prerequisites Installation

Before starting, you need to install the following tools:

1. Install Node.js v20+

IMPORTANT: This project requires Node.js 20 or higher (fhevmjs dependency requires node >=20)

Recommended: Use Node.js 22.x for best compatibility

Windows:

Download Node.js from nodejs.org
Download Node.js 22.x (Current release)
Run the installer (.msi file)
Follow the installation wizard (keep default settings)

Verify installation:

node --version  # Should be v22.x.x (e.g., v22.20.0)
npm --version

Ubuntu/Debian:

# Update package list
sudo apt update

# Install Node.js 22.x (recommended for consistency)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version  # Should be v22.x.x (e.g., v22.20.0)
npm --version

2. Install Git

Windows:

Download Git from git-scm.com
Run the installer
Use default settings during installation
Verify installation:
```
git --version
```

Ubuntu/Debian:

# Install Git
sudo apt update
sudo apt install -y git

# Verify installation
git --version

3. Install MetaMask Wallet

Open your browser (Chrome, Firefox, or Brave)
Go to metamask.io
Click "Download" and install the browser extension
Create a new wallet or import existing one
Save your seed phrase securely!

1️⃣ Clone the Repository

git clone https://github.com/Farukest/Zolymarket.git
cd Zolymarket

2️⃣ Install Dependencies

# Install Hardhat dependencies
cd hardhat && npm install && cd ..

# Install backend dependencies
cd backend && npm install && cd ..

# Install frontend dependencies
cd frontend && npm install && cd ..

3️⃣ Environment Configuration

IMPORTANT: Copy the .env.example files and create your own .env files with your API keys.

Backend Configuration

cd backend
cp .env.example .env

Edit backend/.env and update:

SEPOLIA_RPC_URL - Add your Alchemy API key
MONGODB_URI - Your MongoDB connection string (if using cloud)
Contract addresses (after deployment)

Frontend Configuration

cd frontend
cp .env.example .env

Edit frontend/.env and update:

VITE_FHEVM_NETWORK_URL - Add your Alchemy API key
VITE_ADMIN_ADDRESSES - Your admin wallet address
Contract addresses (after deployment)

Hardhat Configuration (For Deployment)

cd hardhat
cp .env.example .env

Edit hardhat/.env and update:

PRIVATE_KEY - Your wallet private key (for deploying contracts)
ALCHEMY_API_KEY - Your Alchemy API key
SEPOLIA_URL - Add your Alchemy API key

⚠️ Security Warning:

Never commit .env files to GitHub
Keep your private keys and API keys secret
Use .env.example files as templates only

4️⃣ Start Backend Server

cd backend
npm run dev

Note: Configure database and contract addresses in backend/.env before starting.

5️⃣ Start Frontend

cd frontend
npm run dev

6️⃣ Access the Application

Open http://localhost:5173 in your browser
Connect your MetaMask wallet
Switch to Sepolia Testnet in MetaMask
Wait for FHEVM initialization (~2 seconds)
Start placing encrypted bets! 🎉

Requirements:

MetaMask connected to Sepolia Testnet
Sepolia ETH for gas fees
Test USDC for placing bets

7️⃣ Get Test Tokens

You need Sepolia ETH and Test USDC to use the platform.

Sepolia ETH:

Use public faucets like sepoliafaucet.com
Or contact me on Twitter: @0xflydev

Test USDC (Built-in Faucet):

The platform features an integrated faucet system for obtaining test USDC tokens. Users can claim 1000 USDC every 24 hours directly through the interface to participate in encrypted prediction markets.

Built-in faucet interface - Click the 💧 button to claim 1000 USDC every 24 hours

How to use:

Connect your MetaMask wallet to the platform (Sepolia Network)
Locate the faucet button (💧) in the header area
Click to claim 1000 test USDC tokens
Use your USDC to place encrypted bets on prediction markets
Return after 24 hours to claim again

Note: The platform is currently in beta testing. For deployment assistance or advanced configuration, reach out via Twitter or open a GitHub issue.

🎮 Usage Examples

For Users

1. Browse Markets

Home → Filter by Trending/New/Ending Soon → Select a market

2. Place a Private Bet

Connect Wallet → Select Market → Choose Option → Enter Amount → Place Bet
✅ Your bet amount is encrypted and stored on-chain privately

3. Claim Winnings

Dashboard → Claims Tab → Request Payout → Wait 1-2 minutes → Claim
✅ Relayer decrypts your position and calculates your payout

For Admins

1. Create a Market

Admin Panel → Bet Management → Create Bet → Fill details → Deploy

2. Resolve a Market

Admin Panel → Bet Management → Select Bet → Resolve → Select Winner
✅ Smart contract marks winning options

3. Manage Categories

Admin Panel → Categories → Create/Edit/Reorder categories
✅ Drag-and-drop reordering supported

🔐 Privacy Technology

How FHEVM Protects Your Bets

Traditional Prediction Markets:

❌ Bet amounts visible on-chain
❌ Large bets can manipulate market sentiment
❌ Privacy concerns for high-value traders

Zolymarket with FHEVM:

✅ Bet amounts encrypted before submission
✅ Smart contracts compute on encrypted data
✅ Only you can decrypt your position
✅ Market odds remain accurate without revealing individual positions

Encryption Flow

User Places $100 Bet
         ↓
Frontend encrypts: $100 → 0x7f8e9a3b...
         ↓
Smart contract stores encrypted value
         ↓
Other users see: "Position exists" (amount hidden)
         ↓
On resolution: Relayer decrypts for payout calculation
         ↓
Final payout: Publicly visible (needed for claiming)

Learn more: See FHEVM_INTEGRATION.md for technical details

🧪 Smart Contract Overview

Core Contracts

Contract	Purpose	Key Features
BetMarketCore.sol	Core betting logic	FHEVM-encrypted bets, 3 bet types, position tracking
BetMarketPayout.sol	Payout management	Relayer callback, payout calculation, claiming
BetMarketStats.sol	Statistics aggregation	Oracle decryption, volume tracking
CategoryManager.sol	Category system	Hierarchical categories, display ordering

Key Functions

Place Bet (Encrypted):

function placeBet(
    uint256 betId,
    uint256 optionIndex,
    einput encryptedAmount,
    bytes calldata inputProof
) external {
    // Amount remains encrypted on-chain
    euint64 amount = TFHE.asEuint64(encryptedAmount, inputProof);
    // ... betting logic
}

Request Payout (Triggers Relayer):

function requestPayout(uint256 betId) external {
    // Emit event for relayer to process
    emit PayoutRequested(betId, msg.sender);
}

Claim Payout (After Decryption):

function claimPayout(uint256 betId) external {
    uint256 payout = payouts[betId][msg.sender];
    // Transfer USDC to winner
    usdc.transfer(msg.sender, payout);
}

🛠️ Tech Stack

Smart Contracts

Solidity 0.8.24 - Smart contract language
Zama FHEVM - Fully homomorphic encryption library
Hardhat - Development framework
fhEVM.sol - FHEVM Solidity library

Frontend

React 18 - UI framework
Vite - Build tool & dev server
Ethers.js 6 - Web3 library
fhevmjs - FHEVM client library
TailwindCSS - Styling framework
React Router - Navigation
Lucide React - Icon library

Backend

Node.js - Runtime environment
Express.js - Web framework
MongoDB - Database for metadata
Mongoose - ODM library

📊 Project Status

✅ Completed Features

FHEVM-encrypted bet placement
Three bet types (Binary, Multiple, Nested)
Relayer callback system for payouts
Admin panel with analytics
Category management with drag-and-drop
User dashboard with position tracking
MongoDB winner/loser tracking
Mobile-responsive UI
Dark mode support

🚧 Planned Features

🤝 Contributing

Contributions are welcome! Please follow these steps:

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

Development Guidelines

Follow existing code style and conventions
Add comments for complex logic
Test all changes thoroughly
Update documentation as needed

📄 License

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

🔗 Links & Resources

GitHub Repository: github.com/Farukest/Zolymarket
Twitter: @0xflydev
Zama FHEVM Docs: docs.zama.ai/fhevm
FHEVM Integration Guide: FHEVM_INTEGRATION.md

⚠️ Disclaimer

This project is experimental and deployed on testnets only
Not financial advice - use at your own risk
Ensure compliance with local regulations before using prediction markets
Smart contracts are unaudited - do not use with real funds on mainnet

🙏 Acknowledgments

Zama - For pioneering FHEVM technology and making privacy-preserving smart contracts possible
React & Vite communities - For excellent developer tools
Open source contributors - For inspiration and shared knowledge

📧 Contact & Support

Issues: GitHub Issues
Twitter: @0xflydev
GitHub: @Farukest

Built with ❤️ using Zama FHEVM, React, and Solidity

⭐ Star this repo if you find it useful!

FilesExpand file tree

README.md

Latest commit

History