MitchCoin (MTC) - Gothic Street Food Loyalty Token

A production-ready ERC-20 token + React dApp for Mitch from Transylvania's gothic street food empire 🧛

⚡ Quick Start (10 Minutes)

Get MitchCoin deployed and running in 10 minutes! See QUICKSTART.md for the fastest path.

# 1. Install dependencies
pnpm install

# 2. Configure (add your keys to .env and web/.env.local)
pnpm check

# 3. Deploy
pnpm deploy:amoy

# 4. Launch dApp
pnpm web:dev

🎯 What Is MitchCoin?

MitchCoin is a complete loyalty and payment token system featuring:

• 🪙 ERC-20 Token - Standard, secure, OpenZeppelin-based
• 🎨 Web Dashboard - Beautiful gothic-themed UI
• 💸 Transfer System - Send tokens to anyone
• 🎁 Mint System - Owner can create rewards
• 📱 Wallet Connect - MetaMask, WalletConnect, etc.
• 🔍 Block Explorer - View on Polygonscan

Perfect for:

• Loyalty rewards programs
• Customer retention
• In-store payments
• Community building
• Promotional campaigns

🏗️ Features

Smart Contract (Solidity)

• ✅ ERC-20 compliant token
• ✅ Owner-controlled minting for rewards
• ✅ Burn function for supply management
• ✅ OpenZeppelin v5.0 security
• ✅ Fully tested (4/4 tests passing)
• ✅ Polygon Amoy testnet ready
• ✅ Gas optimized

Web Application (Next.js)

• ✅ Real-time balance display
• ✅ Total supply tracking
• ✅ Transfer tokens to any address
• ✅ Mint tokens (owner only)
• ✅ Transaction history links
• ✅ Responsive design
• ✅ Gothic dark theme
• ✅ Auto-refresh balances

📋 Prerequisites

Before you begin, you need:

1. Node.js 18+ - Download
2. pnpm - npm install -g pnpm
3. Test Wallet - Create a MetaMask wallet for testing
4. Testnet MATIC - Get free tokens
5. Alchemy Account - Sign up free

🚀 Installation

1. Clone & Install

cd Mitch_coin
pnpm install

2. Configure Environment

Backend (.env):

PRIVATE_KEY=0xYOUR_TEST_WALLET_PRIVATE_KEY
ALCHEMY_API_KEY=your_alchemy_api_key
POLYGONSCAN_API_KEY=your_polygonscan_key  # Optional
INITIAL_SUPPLY=1000000

Frontend (web/.env.local):

NEXT_PUBLIC_ALCHEMY_API_KEY=your_alchemy_api_key
NEXT_PUBLIC_CHAIN_ID=80002
NEXT_PUBLIC_TOKEN_ADDRESS=  # Fill after deployment

3. Compile & Test

pnpm compile
pnpm test

4. Check Configuration

pnpm check

Should show: ✅ Configuration looks good!

5. Deploy

pnpm deploy:amoy

Copy the contract address and add it to web/.env.local

6. Start Web App

pnpm web:dev

Open http://localhost:5173 🎉

📚 Documentation

• QUICKSTART.md - Deploy in 10 minutes
• SETUP.md - Detailed setup guide
• DEPLOYMENT_CHECKLIST.md - Step-by-step checklist
• PROJECT_SUMMARY.md - Complete project overview

🛠️ Available Commands

Smart Contracts

pnpm compile        # Compile Solidity contracts
pnpm test          # Run test suite
pnpm check         # Validate configuration
pnpm deploy:amoy   # Deploy to Polygon Amoy testnet
pnpm deploy:sepolia # Deploy to Sepolia testnet
pnpm verify        # Verify contract on Polygonscan
pnpm airdrop       # Bulk send tokens
pnpm node          # Start local Hardhat node

Web Application

pnpm web:dev       # Start dev server (localhost:5173)
pnpm web:build     # Build for production
pnpm web:start     # Start production server

🎨 Project Structure

Mitch_coin/
├── contracts/          # Solidity smart contracts
│   └── MitchCoin.sol  # Main ERC-20 token
├── scripts/           # Deployment & utility scripts
│   ├── deploy.ts      # Deploy to networks
│   ├── verify.ts      # Verify on Polygonscan
│   ├── check-config.ts # Config validation
│   └── airdrop.ts     # Bulk token distribution
├── test/              # Smart contract tests
│   └── MitchCoin.test.ts
├── web/               # Next.js web application
│   ├── app/          # Next.js App Router
│   ├── components/   # React components
│   └── lib/          # Configuration & utilities
└── docs/             # Documentation

🌐 Supported Networks

Testnets (Configured)

• ✅ Polygon Amoy (ChainID: 80002) - Primary testnet
• ✅ Sepolia (ChainID: 11155111) - Ethereum testnet

Production (Easy to Add)

• 🔧 Polygon Mainnet (ChainID: 137)
• 🔧 Ethereum Mainnet (ChainID: 1)
• 🔧 Base (ChainID: 8453)
• 🔧 Arbitrum (ChainID: 42161)

💡 Use Cases

For Business (Mitch's Gothic Street Food)

• Loyalty Rewards - Award MTC for purchases
• Promotions - Airdrop tokens for marketing
• Payments - Accept MTC as payment
• Community - Build engaged customer base
• Events - Special token-gated experiences

For Customers

• Earn - Get MTC with every purchase
• Save - Accumulate tokens over time
• Spend - Use MTC for discounts
• Trade - Send to friends
• Collect - Hold for VIP access

🔒 Security

• ✅ OpenZeppelin audited contracts
• ✅ Owner-controlled minting (prevents unauthorized creation)
• ✅ Standard ERC-20 implementation
• ✅ Comprehensive test coverage
• ✅ Testnet deployment first

Production Security Checklist

• Professional smart contract audit
• Multi-signature wallet for owner
• Rate limiting on mints
• Transaction monitoring
• Emergency pause mechanism
• Time-locks for critical actions

🧪 Testing

All tests passing ✅

  MitchCoin
    ✓ mints initial supply to deployer
    ✓ owner can mint
    ✓ has correct name and symbol
    ✓ owner can burn tokens

  4 passing (383ms)

🤝 Contributing

Contributions welcome! This is an open-source starter template.

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. Open Pull Request

📖 Learn More

Web3 & Blockchain

• Ethereum Documentation
• Solidity by Example
• OpenZeppelin Contracts

Tools & Frameworks

• Hardhat Docs
• Next.js Docs
• wagmi Documentation
• RainbowKit Guide

Polygon

• Polygon Docs
• Polygon Faucet
• Polygonscan

🆘 Troubleshooting

Common Issues

"Insufficient funds" error

• Get testnet MATIC from https://faucet.polygon.technology/

"Invalid API key" error

• Check .env has correct Alchemy key
• Ensure you selected "Polygon Amoy" network in Alchemy

Web dApp won't connect

• Clear browser cache
• Check MetaMask is on correct network
• Restart dev server

Tests failing

• Run pnpm install again
• Delete node_modules and reinstall
• Check Node.js version (18+)

See SETUP.md for detailed troubleshooting.

💰 Cost Estimates

Development (One-Time)

• Smart Contract Deployment: ~$5-20 (testnet: free)
• Domain: $10-30/year
• Contract Audit: $5,000-$15,000 (optional, for mainnet)

Operations (Monthly)

• Alchemy Free Tier: $0 (300M compute units)
• Hosting: $0-30 (Vercel free tier available)
• Maintenance: Variable

Transaction Costs

• Users pay their own gas fees on Polygon
• Polygon fees are very low (~$0.001-0.01 per tx)

🗺️ Roadmap

Phase 1: Foundation ✅ (DONE)

• ERC-20 smart contract
• Deployment scripts
• Web dashboard
• Transfer & mint UI
• Testnet deployment

Phase 2: Enhanced Features

• Staking/rewards system
• NFT loyalty passes
• Mobile app (React Native)
• QR code payments
• Analytics dashboard

Phase 3: Production

• Smart contract audit
• Mainnet deployment
• Exchange integration
• Marketing campaign
• Partnership program

Phase 4: Advanced

• DAO governance
• Cross-chain bridge
• Liquidity pools
• Third-party API
• Enterprise features

📜 License

MIT License - see LICENSE file for details.

Free to use, modify, and distribute.

🙏 Acknowledgments

Built with:

• OpenZeppelin - Security-audited contracts
• Hardhat - Development framework
• Next.js - React framework
• RainbowKit - Wallet connection
• wagmi - React hooks for Ethereum
• Polygon - Scaling solution

📞 Support

• Documentation: Check /docs folder
• Issues: GitHub Issues
• Community: [Discord/Telegram link]
• Email: support@mitchcoin.example

⭐ Star This Repo!

If this starter helped you, please give it a star! ⭐

---

Ready to deploy? → Start with QUICKSTART.md

Need help? → Read SETUP.md

Going to production? → Follow DEPLOYMENT_CHECKLIST.md

Made with 🧛 for Mitch from Transylvania