Frequently Asked Questions

The DEX Dashboard is a full-stack educational Web3 platform that simulates a decentralized exchange experience. It lets you mint mock tokens, trade them on a simulated DEX, and track live market analytics — all without risking real funds.

It's built for developers, students, and crypto enthusiasts who want to understand how DeFi protocols work by interacting with one directly.

The DEX Dashboard works with two networks:

• Anvil (Local) — A local Ethereum node provided by the Foundry toolchain. This is the default for development and testing. It runs on http://127.0.0.1:8545 and gives you instant transactions with no gas costs.
• Sepolia (Testnet) — A public Ethereum testnet. You'll need test ETH from a Sepolia faucet to deploy contracts. The frontend automatically detects which network your wallet is connected to and shows the relevant contract addresses.

💡 Tip: Start with Anvil for local development, then deploy to Sepolia for public testing.

This dashboard is designed for:

• 👨‍💻 Developers — Learn Solidity smart contract development, Foundry testing, and full-stack Web3 integration with Next.js and wagmi.
• 🎓 Students — Understand DeFi mechanics like token swaps, liquidity pools, and market analytics in a safe sandbox environment.
• 🧪 Crypto Enthusiasts — Explore how DEXes work under the hood without risking real assets.
• 🏫 Educators — Use this as a teaching tool for blockchain development courses and workshops.

The project is divided into two main parts:

• Smart Contracts (Backend): Solidity ^0.8.27 + Foundry + OpenZeppelin
• Frontend: Next.js 16 (App Router) + TypeScript (strict) + shadcn/ui + Tailwind CSS v4 + wagmi + viem
• Charts & Data: Recharts for candlestick charts, CoinGecko API for market data
• Testing: Foundry (forge) — 182+ Solidity tests including fuzz and invariant tests; Vitest + Testing Library — frontend component tests

Follow these steps:

1. Clone the repository: git clone https://github.com/Men6d656e/DEX.git
2. Install dependencies: make install
3. Build contracts: make build-contracts
4. Start Anvil: make anvil (Terminal 1)
5. Deploy contracts: make deploy-anvil (Terminal 2)
6. Start the frontend: make dev
7. Open http://localhost:3000 and connect your wallet

💡 New to Foundry? The make commands automate everything. Just run make dev and the frontend will start with hot reload enabled.

The repository is organized into these main directories:

• contracts/ — Foundry smart contracts (MockERC20, Faucet, MockDEX) with tests and deployment scripts.
• frontend/ — Next.js 16 application with pages, components, hooks, and utilities.
• docs/ — GitHub Pages documentation (this documentation hub).
• scripts/ — Utility scripts like update-addresses.sh for auto-capturing deployed contract addresses.

The root Makefile provides automation for install, build, test, deploy, and dev commands.

The Faucet is a smart contract that distributes mock tokens to users for testing and learning purposes. It's like a water faucet for tokens — turn it on and get free tokens to play with.

Each user can claim a fixed amount of tokens once per cooldown period (24 hours), tracked independently for each token type. The faucet ensures fair distribution while preventing abuse.

The Faucet supports 3 mock tokens:

• Token Index 0 → mETH (Mock Ethereum): MockERC20("Mock ETH", "mETH", faucetAddress)
• Token Index 1 → mBTC (Mock Bitcoin): MockERC20("Mock BTC", "mBTC", faucetAddress)
• Token Index 2 → mUSDC (Mock USD Coin): MockERC20("Mock USDC", "mUSDC", faucetAddress)

Each token is a full ERC20 implementation from OpenZeppelin with faucet-restricted minting. The faucet is the only address that can mint new tokens.

When you select a token in the Faucet page, its contract address is displayed in the section below the claim button. To import a token into MetaMask (or any wallet):

1. Copy the contract address shown on the Faucet page.
2. In MetaMask, click "Import tokens" (scroll to the bottom of your assets list).
3. Paste the contract address. MetaMask will auto-detect the symbol and decimals (18).
4. Click "Add Custom Token" then "Import Tokens".

✅ After importing, you'll see your balance update in real-time as you claim more tokens.

Each token has an independent 24-hour cooldown per wallet address. Here's the breakdown:

• Per token, per wallet — Claiming mETH doesn't reset your mBTC cooldown. You can claim all 3 tokens on the same day, just not the same token twice.
• Countdown timer — The UI shows an exact HH:MM:SS countdown until your next claim is available.
• Progress indicator — A circular progress bar shows how much of the cooldown has elapsed.
• State badges — The claim button shows "Claim Ready" (green) when available, or a disabled state with remaining time when on cooldown.
• On-chain tracking — The lastClaim mapping and cooldown variable are stored in the Faucet contract. Even if you reload the page, the state persists.

You can claim 10 tokens (with 18 decimal places, so 10 × 10¹⁸ wei) per token per 24-hour period.

Example:

• Day 1: Claim 10 mETH, claim 10 mBTC, claim 10 mUSDC = 30 tokens total
• Day 2: Claim 10 mETH again (cooldown for mETH has reset)

The claim amount and cooldown duration can be adjusted by the contract owner (the deployer) using the setClaimAmount() and setCooldown() admin functions.

The Faucet page shows detailed analytics for each token:

• Lifetime Claimed — Total tokens you've claimed for this token over your entire history.
• Last Claim — Timestamp of your most recent successful claim.
• Cooldown Remaining — Time until your next claim becomes available.
• Claim Count — Total number of claims you've made.

All this data comes from the Faucet contract's on-chain state (lastClaim and lifetimeClaimed mappings). It persists across sessions and browser restarts.

The DEX supports 6 swap paths across 3 token pairs:

• Direct Pairs (via fixed ratio): mETH ↔ mUSDC, mBTC ↔ mUSDC
• Cross-Rate Pairs (derived through mUSDC): mETH ↔ mBTC

The cross-rate is calculated by routing through mUSDC internally: ethAmount → USDC value (via ethSwapRate) → BTC output (via btcSwapRate)

The DEX uses a fixed-ratio pricing model — not an AMM (Automated Market Maker) like Uniswap.

• The contract owner sets ethSwapRate and btcSwapRate on deployment.
• Simple ratio math: output = input × rate. Cross-rate swaps calculate through the USDC value.
• Reserve limits: Each swap checks that the DEX has enough reserves to fulfill the order.

There is no swap fee in this educational DEX. The full swap amount goes to the user without any deduction.

The DEX contract owner is the sole liquidity provider. They call the addLiquidity() function to deposit mETH, mBTC, and mUSDC tokens into the DEX.

The current liquidity is visible on the Swap page in the Reserves panel.

Slippage is the difference between the expected price of a trade and the price at which it's actually executed. Even though this DEX uses fixed rates, slippage protection is implemented as a safety mechanism (minOutput). If the calculated output is less than your minOutput, the transaction reverts.

You can set the slippage tolerance in the Swap page via the ⚙️ Settings button (gear icon). Default is 0.5%.

Before you can swap, the DEX contract needs permission to spend your tokens via the ERC20 approve() function.

1. Select your input token and enter an amount.
2. Click "Approve" and confirm the MetaMask transaction.
3. Once approved, the button changes to "Swap".

Approval is per-token and persists across swaps.

This DEX uses a simplified reserve-based model, not a constant product AMM. Reserves track exactly how many tokens the DEX holds (ethReserve, btcReserve, usdcReserve).

It does NOT use the x × y = k formula, have automated price discovery, or LP tokens.

The Analytics page shows:

• 📈 Market Stats Cards: 24h Volume, Total Trades, Active Users, TVL.
• 📊 Candlestick Charts: Interactive charts for ETH, BTC, and an overview.
• 📋 Token Statistics: Price, 24h change, market cap, and volume for each token.
• 🔄 Trade History: Recent swap transactions.
• 👛 Portfolio Overview: Connected wallet balance and allocation.

Market data is powered by the CoinGecko API (Free Tier). The frontend fetches candlestick data, prices, and market metrics.

Each candle shows 4 data points for a period: Open, Close, High, and Low. Green means the price increased (Close > Open), Red means it decreased (Close < Open). The wicks show the high/low range, and the body shows open/close.

• 24h Volume: Total value of swaps; higher means more activity.
• Total Trades: Count of successful swaps.
• Active Users: Wallets that performed a swap or claim in the last 24h.
• TVL: Total USD value locked in the DEX.

All include trend indicators (↑ or ↓) vs. yesterday.

It displays your token balances (mETH, mBTC, mUSDC), USD values, and an allocation pie chart. It uses balanceOf() calls to fetch data directly from the blockchain via wagmi/viem.

It displays a chronological list of transactions, including Time, Swap Type, Amount In, Amount Out, and the User address.

Price, 24h Change, Market Cap, 24h Volume, and Circulating Supply.

They use a modular architecture:

• MockERC20: Standard ERC20 with minting restricted to a faucet address.
• Faucet: Manages time-locked distributions and claim history.
• MockDEX: Manages 3 reserves, 2 swap rates, and 6 swap paths using SafeERC20.

Uses custom errors and the checks-effects-interactions pattern for security.

182+ Solidity tests across all contracts:

• MockERC20: 35 tests
• Faucet: 51 tests
• MockDEX: 96 tests (including 14 fuzz tests and 4 invariant tests to ensure reserves match balances)
• Frontend: Vitest + Testing Library