Dau Bets - Decentralized Betting Platform

A decentralized sports and casino betting platform built on Base network using Solidity smart contracts and React frontend.

📚 Documentation Map

• README.md – High-level overview, architecture, and usage.
• QUICK_START.md – Fastest path to running everything locally.
• TESTNET_DEPLOYMENT_GUIDE.md – Step-by-step Base Goerli deployment.
• GAS_OPTIMIZATION_GUIDE.md – Gas patterns, reporter usage, and analysis.
• CHAINLINK_VRF_INTEGRATION_PLAN.md – Technical design for future randomness upgrade.
• PAUSE_MECHANISM_SUMMARY.md – Detailed explanation of pause/unpause controls.
• PREDICTION_MARKETS_SUMMARY.md – Design and flows for prediction markets.
• LOCAL_DEPLOYMENT_SUCCESS.md – Reference for a known-good local setup.
• TEST_RESULTS_SUMMARY.md & VERIFICATION_COMPLETE.md – Testing and readiness snapshots.
• RUNBOOK.md – Operational checklist and emergency procedures.

🎯 Features

🏀 Sports Betting

• Decentralized sports betting with custom oracle integration
• Support for multiple bet types and game outcomes
• Transparent and immutable bet resolution

🎰 Casino Games

• Dice Roll: Guess numbers 1-6 for 5x payout
• Coin Flip: Heads or tails for 1.95x payout
• Roulette: Red/Black/Number betting with varying payouts
• Baccarat: Player/Banker/Tie betting
• Blackjack: Classic card game with 2x payout
• Slots: Symbol matching with variable payouts

📈 Prediction Markets

• On-chain prediction markets with market creation, betting, resolution, and claims
• Market analytics dashboard with volume over time, category distribution, and key insights

🌍 Localization & UX

• Full multi-language support (English & Kiswahili)
• Modern / Enhanced layouts for sports and casino play
• Accessible tooltips, responsible gambling limits, and glassmorphism UI

💰 Tokenomics

• TZS Token: Tanzanian Shilling Stablecoin for betting
• ERC20 compliant with mint/burn functionality
• 1 billion token max supply

🏗️ Architecture

Smart Contracts

contracts/
├── TanzanianStablecoin.sol  # ERC20 betting token
├── SportsBetting.sol        # Sports betting logic
├── PredictionMarkets.sol    # On-chain prediction markets
├── DiceRoll.sol             # Dice game
├── CoinFlip.sol             # Coin flip game
├── Roulette.sol             # Roulette game
├── Baccarat.sol             # Baccarat game
├── Blackjack.sol            # Blackjack game
└── Slots.sol                # Slots game

Frontend

frontend/src/
├── App.js                  # Main React application
├── contractConfig.js       # Contract addresses & ABIs
├── App.css                 # Global styling
├── components/             # Feature components (AdminPanel, History, Prediction, etc.)
└── index.js                # Entry point

High-Level Flow

User Wallet (MetaMask)
        ↓
React Frontend (Play / History / Admin / Prediction)
        ↓  via ethers.js
Solidity Contracts on Base (TZS, SportsBetting, Casino Games, PredictionMarkets)
        ↓
Base Network (Local / Goerli / Mainnet)

🚀 Quick Start

Prerequisites

• Node.js >= 14.0.0
• MetaMask wallet extension
• Git

Installation

1. Clone the repository

   git clone <repository-url>
   cd daubet

2. Install contract dependencies

   cd contracts
   npm install

3. Install frontend dependencies

   cd ../frontend
   npm install

   Or, from the repo root, you can run the provided helper script:

   # Unix
   ./setup-dev.sh
   
   # Windows
   setup-dev.bat

Development Setup

1. Start local Hardhat network

   cd contracts
   npx hardhat node

   Keep this terminal open - it will show deployed contract addresses.

2. Deploy contracts and create config

   # In a new terminal
   cd contracts
   npx hardhat deploy-with-config --network localhost

   This will:

   • Deploy all contracts to local network
   • Mint 1M TZS tokens to deployer
   • Create frontend/src/contractConfig.js with addresses

3. Start frontend

   cd frontend
   npm start

   Opens http://localhost:3000

4. Configure MetaMask

   • Add localhost network: RPC URL http://127.0.0.1:8545, Chain ID 31337
   • Import the private key from Hardhat node output (Account #0)

🔧 Development Commands

Contracts

cd contracts

# Compile contracts
npx hardhat compile

# Run tests  
npx hardhat test

# Deploy to localhost with config generation
npx hardhat deploy-with-config --network localhost

# Deploy to testnet (requires PRIVATE_KEY in .env)
npx hardhat deploy-with-config --network baseGoerli

Frontend Commands

cd frontend

# Start development server
npm start

# Build for production
npm run build

# Run tests
npm test

🌐 Network Configuration

Localhost (Development)

• Network: Hardhat Local
• RPC URL: http://127.0.0.1:8545
• Chain ID: 31337

Base Goerli (Testnet)

• Network: Base Goerli
• RPC URL: https://goerli.base.org
• Chain ID: 84531

Base Mainnet (Production)

• Network: Base Mainnet
• RPC URL: https://mainnet.base.org
• Chain ID: 8453

🔐 Environment Variables

Create .env file in contracts/ directory:

# Required for testnet/mainnet deployment
PRIVATE_KEY=your_wallet_private_key_here

# Optional: Contract verification
BASESCAN_API_KEY=your_basescan_api_key

🧪 Testing

Run the test suite:

cd contracts
npx hardhat test

Current test coverage:

• ✅ TanzanianStablecoin
• ✅ SportsBetting
• ✅ Baccarat
• ✅ Slots
• ✅ DiceRoll
• ✅ CoinFlip
• ✅ Roulette
• ✅ Blackjack
• ✅ PredictionMarkets

Overall: 200+ tests and ~85% coverage across all core contracts. See VERIFICATION_COMPLETE.md and TEST_RESULTS_SUMMARY.md for details.

📱 How to Use

1. Connect Wallet: Click "Connect MetaMask"
2. Get TZS Tokens: Deploy contracts (includes 1M TZS mint)
3. Approve Spending: First game interaction will prompt token approval
4. Start Betting & Markets:
   • Use the Play / History / Admin tabs to navigate
   • Within Play, switch between Sports, Casino, and Prediction Markets and choose Enhanced or Modern layout
   • Set optional responsible gambling limits, enter bet amounts/parameters, and confirm transactions in MetaMask

🛡️ Security Features

• Access Control: Owner-only functions protected
• Reentrancy Protection: SafeMath and proper state management
• Token Approvals: Explicit approval required for spending
• Custom Errors: Gas-efficient error handling
• Input Validation: Comprehensive parameter checking

🏆 Contract Addresses

After deployment, addresses will be automatically saved to:

• frontend/src/contractConfig.js (JavaScript imports)
• frontend/src/contractAddresses.json (JSON format)

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature-name
3. Commit changes: git commit -am 'Add feature'
4. Push to branch: git push origin feature-name
5. Submit a Pull Request

🚀 Production Deployment

Testnet Deployment (Base Goerli)

cd contracts

# Set environment variables
echo "PRIVATE_KEY=your_private_key_here" > .env
echo "BASESCAN_API_KEY=your_basescan_api_key" >> .env

# Deploy contracts
npm run deploy:testnet

# Verify contracts (optional)
npm run verify:testnet <CONTRACT_ADDRESS>

Mainnet Deployment (Base)

cd contracts

# Ensure you have mainnet funds and API keys
npm run deploy:mainnet

# Verify contracts
npm run verify:mainnet <CONTRACT_ADDRESS>

Frontend Deployment

cd frontend

# Install dependencies
npm install

# Build for production
npm run build

# Deploy to your hosting service (Vercel, Netlify, etc.)
# The build/ folder contains the static assets

🧪 Advanced Testing

Run the complete test suite:

cd contracts
npm test

# Run with coverage
npm run test:coverage

# Test specific contract
npx hardhat test test/DiceRoll.test.js

🖼 Screenshots (Recommended)

Consider adding a few screenshots under a docs/screenshots/ folder, for example:

• Play – Sports (Modern layout): Main betting view with responsible gambling controls.
• Play – Casino (Enhanced layout): Glassmorphism cards for casino games.
• Prediction Markets: Market list and analytics.
• History & Admin: Glass headers, stats, and admin controls.

Once available, you can embed them here with standard Markdown image tags.

📋 Development Checklist

Completed ✅

• Complete smart contract suite (9 contracts, including prediction markets)
• Comprehensive test coverage across core contracts (~85%+)
• Modern React frontend with Web3 integration
• Token approval system for seamless UX
• Responsive glassmorphism UI design
• Transaction history and analytics dashboards
• Admin panel for platform risk and liquidity management
• Multi-language support (English & Kiswahili)
• Proper error handling and loading states
• Contract deployment automation
• Contract verification setup
• Comprehensive documentation

Future Enhancements 🚀

• Implement Chainlink VRF for true randomness (see CHAINLINK_VRF_INTEGRATION_PLAN.md)
• Add production-grade sports data oracle integration
• Add liquidity pool mechanics
• Implement referral / rewards system
• Add mobile app with React Native
• Explore additional game types and market categories

📄 License

This project is licensed under the MIT License.

🎮 Responsible Gambling & Legal Notes

• The frontend includes optional responsible gambling controls:
  • Max bet per wager (soft cap per bet).
  • Max total stake per session (soft cap per session).
• When these limits are set, the app will block or warn on bets that exceed them.
• Limits are user-configurable and can be changed or reset at any time.
• You are responsible for how you use the platform and for staying within your own limits.

Gambling and crypto use may be restricted or illegal in some jurisdictions.
Always verify local laws and consider this project a technical demonstration, not production advice.

♿ Accessibility & Localization

• Localization:
  • Full English and Kiswahili support for core flows (Play, History, Admin, Prediction Markets).
  • All new UI copy and tooltips are wired through the i18n layer.
• UX & accessibility touches:
  • Clear navigation hierarchy (Play / History / Admin, and Sports / Casino / Prediction within Play).
  • Layout toggle with descriptive tooltips for Enhanced vs Modern views.
  • Responsible gambling inputs with labels, helper text, and hints.
  • Status messages for loading, errors, and approvals.
• Known limitations:
  • Not yet fully audited against WCAG; some components may need additional ARIA roles and keyboard testing.
  • Screen reader experience is improving but not guaranteed to be perfect across all browsers.

Contributions that improve accessibility, copy, or localization coverage are very welcome.

⚠️ Disclaimer

This is a demonstration project. Do not use with real funds without proper security audits. Gambling may be illegal in your jurisdiction.