📄 Smart Contracts

Three contracts form the backend of the DEX Dashboard: MockERC20 (token), Faucet (distribution), and MockDEX (trading). All contracts inherit from OpenZeppelin for battle-tested security.

1. MockERC20 — Mock Tokens

OpenZeppelin-based ERC20 token with mint capability restricted to a designated faucet address. Deployed as three independent instances.

Deployed Instances

Token	Symbol	Contract	Decimal
Mock Ethereum	mETH	MockERC20("Mock ETH", "mETH", faucetAddress)	18
Mock Bitcoin	mBTC	MockERC20("Mock BTC", "mBTC", faucetAddress)	18
Mock USDC	mUSDC	MockERC20("Mock USDC", "mUSDC", faucetAddress)	18

Key Functions

• mint(to, amount) — Only callable by the designated faucet address. Emits TokensMinted event.
• setFaucet(newFaucet) — onlyOwner. Updates the address authorized to mint.

Errors

• MockERC20__NotFaucet() — Caller is not the faucet address
• MockERC20__InvalidFaucet() — Faucet address is zero

2. Faucet — Token Distribution

Time-locked faucet distributing 10 tokens per claim with an independent 24-hour cooldown per wallet per token. Supports all three mock tokens (mETH, mBTC, mUSDC).

State Variables

mapping(address => mapping(uint256 => uint256)) lastClaim;
// user => tokenIndex => unix timestamp

mapping(address => mapping(uint256 => uint256)) lifetimeClaimed;
// user => tokenIndex => total tokens claimed

uint256 claimAmount;    // Default: 10 * 10**18
uint256 cooldown;       // Default: 24 hours (86400s)
MockERC20[] tokens;     // [mETH, mBTC, mUSDC]

Key Functions

• claimToken(tokenIndex) — Claims tokens. 0=mETH, 1=mBTC, 2=mUSDC. Reverts if cooldown hasn't elapsed.
• getClaimInfo(user, tokenIndex) → (canClaim, timeRemaining, totalClaimed, lastClaimTime) — View function for claim eligibility.
• getTokenCount() → uint256 — Returns number of supported tokens (3).
• getTokenAddress(tokenIndex) → address — Returns token contract address by index.
• setClaimAmount(amount) — onlyOwner. Updates tokens per claim.
• setCooldown(seconds) — onlyOwner. Updates cooldown period.

Errors

• Faucet__CooldownNotElapsed(remaining) — Must wait remaining seconds
• Faucet__InvalidToken() — Token index out of range
• Faucet__InvalidAddress() — Zero address in constructor
• Faucet__InvalidClaimAmount() — Claim amount set to zero
• Faucet__InvalidCooldown() — Cooldown set to zero

3. MockDEX — Swap Engine

A fixed-ratio DEX supporting 6 swap paths across 3 tokens. Uses a simplified reserve-based model (not a constant product AMM like Uniswap).

State Variables

IERC20 public immutable mETH;     // mETH token contract
IERC20 public immutable mBTC;     // mBTC token contract
IERC20 public immutable mUSDC;    // mUSDC token contract

uint256 public ethReserve;        // Current mETH reserve
uint256 public btcReserve;        // Current mBTC reserve
uint256 public usdcReserve;       // Current mUSDC reserve

uint256 public ethSwapRate;       // mUSDC per 1 mETH (scaled 1e18)
uint256 public btcSwapRate;       // mUSDC per 1 mBTC (scaled 1e18)

Swap Paths (6 total)

Direction	Function	Calculation	Reserve Check
mETH → mUSDC	swapETHForUSDC()	usdcOut = ethIn × ethRate / 1e18	usdcReserve
mUSDC → mETH	swapUSDCForETH()	ethOut = usdcIn × 1e18 / ethRate	ethReserve
mBTC → mUSDC	swapBTCForUSDC()	usdcOut = btcIn × btcRate / 1e18	usdcReserve
mUSDC → mBTC	swapUSDCForBTC()	btcOut = usdcIn × 1e18 / btcRate	btcReserve
mETH → mBTC	swapETHForBTC()	usdcValue = ethIn × ethRate / 1e18 btcOut = usdcValue × 1e18 / btcRate	btcReserve
mBTC → mETH	swapBTCForETH()	usdcValue = btcIn × btcRate / 1e18 ethOut = usdcValue × 1e18 / ethRate	ethReserve

Cross-rate swaps (mETH ↔ mBTC) route through mUSDC internally. For example, swapping mETH → mBTC first converts ETH to USDC value via ethSwapRate, then converts that USDC value to BTC via btcSwapRate.

Key Functions

• addLiquidity(ethAmount, btcAmount, usdcAmount) — onlyOwner. Deposits tokens into DEX reserves. Emits LiquidityAdded.
• getEthRate() → uint256 — Returns current mETH→mUSDC rate.
• getBtcRate() → uint256 — Returns current mBTC→mUSDC rate.
• setEthRate(newRate) — onlyOwner. Updates mETH swap rate.
• setBtcRate(newRate) — onlyOwner. Updates mBTC swap rate.

Security

• SafeERC20 — All token transfers use OpenZeppelin's SafeERC20 for secure handling.
• Checks-Effects-Interactions — State updates happen before token transfers to prevent reentrancy.
• Slippage protection — Every swap function accepts a minOutput parameter. If the calculated output is less than the minimum, the transaction reverts with MockDEX__SlippageExceeded(actual, minimum).
• Reserve invariants — Reserves are updated atomically with swaps and tested with Foundry invariant tests (256 runs × 15 depth).

Errors

• MockDEX__InsufficientLiquidity() — Not enough tokens in reserve
• MockDEX__SlippageExceeded(actual, minimum) — Output below minimum
• MockDEX__ZeroAmount() — Input amount is zero
• MockDEX__InvalidAddress() — Zero address in constructor
• MockDEX__InvalidRate() — Swap rate set to zero

Events

• LiquidityAdded(provider, ethAmount, btcAmount, usdcAmount)
• Swapped(user, fromToken, toToken, amountIn, amountOut)
• EthRateUpdated(oldRate, newRate)
• BtcRateUpdated(oldRate, newRate)

See the Testing Guide for details on the test suite covering all contracts.