A full-stack educational Web3 platform — mint mock tokens, swap them on a simulated DEX, and track live market analytics.
📸 Screenshots • ✨ Features • 🛠️ Tech Stack • 🚀 Quick Start • 🏛️ Structure • 🧪 Testing
 |
 |
| 🏠 Home Dashboard | 📊 Analytics & Charts |
 |
 |
| 💰 Token Faucet | 🔄 Swap Interface |
Mint mETH, mBTC, and mUSDC mock tokens with a 24-hour cooldown per token per wallet. Track your lifetime claims, remaining cooldown timers, and token statistics — all on-chain.
Trade mock tokens with 6 swap paths powered by a fixed-ratio pricing engine:
| Pair | Direction |
|---|---|
| mETH ↔ mUSDC | Direct swap via ratio |
| mBTC ↔ mUSDC | Direct swap via ratio |
| mETH ↔ mBTC | Cross-rate derivation through mUSDC |
Includes slippage protection (set your minimum output), reserve tracking, and approval management.
- Market Stats — 24h volume, total trades, active users, TVL (powered by CoinGecko API)
- Candlestick Charts — Real-time price action for ETH, BTC, and combined overview
- Token Statistics — Price, 24h change, market cap, and volume per token
- Trade History — Recent swaps with timestamps, amounts, and participants
- Portfolio Overview — Token balances, USD values, allocation breakdown
Connect any wallet via wagmi + viem. View your address, connected status, and token balances across pages.
Animated hero section with CTA buttons, live stats counters (total mints, swaps, users, TVL), feature cards with gradient icons, and tech stack badges.
| Layer | Technology |
|---|---|
| Smart Contracts | Foundry + OpenZeppelin |
| Language (Contracts) | Solidity ^0.8.27 |
| Frontend | Next.js 16 (App Router, static generation) |
| Language (Frontend) | TypeScript (strict mode) |
| UI Library | shadcn/ui + Tailwind CSS v4 |
| Charts | Recharts |
| Wallet | wagmi + viem |
| Icons | Lucide |
| Market Data | CoinGecko API (Free Tier) |
| Testing | Foundry (forged), Vitest, Testing Library |
| Automation | Makefile |
| Contract | Description |
|---|---|
MockERC20 |
ERC20 token with faucet-restricted minting. Deployed as mETH, mBTC, mUSDC. |
Faucet |
Time-locked faucet — claim 10 tokens per 24 hours per token. |
MockDEX |
Fixed-ratio DEX with 6 swap paths, slippage protection, and reserve tracking. |
All contracts inherit from OpenZeppelin (Ownable, ERC20, SafeERC20) for battle-tested security.
git clone https://github.com/Men6d656e/DEX.git
cd DEX
make installmake build-contractsmake test-contracts# Terminal 1: Start Anvil
make anvil
# Terminal 2: Deploy contracts
make deploy-anvilFor live CoinGecko market data, create frontend/.env.local:
NEXT_PUBLIC_COINGECKO_API_KEY=your_api_key_heremake dev
# Or step by step: make install-frontend && make dev-frontendOpen http://localhost:3000 in your browser.
make deploy-anvil
# Builds → deploys to Anvil → prompts for private key → auto-captures addressesFor Sepolia testnet:
# First, configure contracts/.env:
# cp contracts/.env.example contracts/.env
# Edit with your RPC URL and Etherscan API key
make deploy-sepolia
# Builds → deploys to Sepolia → verifies on Etherscan → auto-captures addressesmake prodDEX/
├── contracts/ # Foundry smart contracts
│ ├── src/
│ │ ├── MockERC20.sol # Mock tokens (mETH, mBTC, mUSDC)
│ │ ├── Faucet.sol # Time-locked token faucet
│ │ └── MockDEX.sol # Fixed-ratio DEX with 6 swap paths
│ ├── test/ # Solidity tests (182+ tests)
│ ├── script/
│ │ └── Deploy.s.sol # Deployment script
│ └── foundry.toml # Foundry configuration
├── frontend/ # Next.js 16 application
│ ├── src/
│ │ ├── app/
│ │ │ ├── page.tsx # Home / Landing page
│ │ │ ├── faucet/ # Token faucet page
│ │ │ ├── swap/ # Token swap page
│ │ │ └── analytics/ # Market analytics page
│ │ ├── components/
│ │ │ ├── ui/ # shadcn/ui primitives (13 components)
│ │ │ ├── home/ # Landing page components
│ │ │ ├── swap/ # Swap panel components
│ │ │ ├── faucet/ # Faucet claim & analytics
│ │ │ ├── analytics/ # Charts, stats, portfolio
│ │ │ └── layout/ # Header, navigation
│ │ ├── hooks/ # Custom React hooks
│ │ ├── lib/ # Utilities, constants, ABI types
│ │ └── providers.tsx # Web3 provider setup
│ └── package.json
├── images/ # Screenshots for README
├── docs/ # GitHub Pages documentation
├── scripts/ # Utility scripts
│ └── update-addresses.sh # Auto-capture deployed contract addresses
├── Makefile # Automation (install, build, test, deploy)
└── README.md # This file
make test # Run all tests (contracts + frontend)
make test-contracts # Run only Foundry tests (182+ tests)
make test-frontend # Run only frontend tests
make coverage # Generate Foundry coverage reportThe Solidity test suite includes:
- 35 tests for MockERC20 (minting, faucet, ownership, ERC20 standards)
- 51 tests for Faucet (claims, cooldowns, edge cases, ownership)
- 96 tests for MockDEX (swaps, liquidity, cross-rate ETH↔BTC, fuzz tests, invariant tests)
16 fuzz functions × 256 runs each + 4 invariant tests × 256 runs × 15 depth.
User and developer documentation is available via GitHub Pages:
| Command | Description |
|---|---|
make install |
Install all dependencies (forge + npm) |
make build |
Build contracts + frontend |
make test |
Run all tests |
make anvil |
Start local Anvil node (port 8545) |
make deploy-anvil |
Deploy to Anvil + auto-update frontend addresses |
make deploy-sepolia |
Deploy to Sepolia testnet + verify on Etherscan + auto-update |
make update-addresses |
Re-capture addresses from broadcast JSON |
make dev |
Install frontend deps + start dev server (localhost:3000) |
make dev-frontend |
Start frontend dev server (localhost:3000) |
make prod |
Build + serve production |
make prod-frontend |
Serve production build |
make generate-abi |
Generate type-safe wagmi hooks from ABIs |
make coverage |
Generate coverage report |
make clean |
Clean all artifacts |
make fmt |
Format Solidity + TypeScript |
make docs |
Serve docs locally (port 3001) |
MIT — see LICENSE for details.
- 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