🚀 Stablecoin Challenge Tutorial

README.md

🚀 Stablecoin Challenge - Complete Developer Tutorial 💰

Welcome to the most exciting DeFi adventure! 🎉 Get ready to dive into the world of stablecoins, yield farming, and automated market making!

📚 Table of Contents

1. 🌟 Project Overview
2. 🏗️ Architecture
3. 🔍 Smart Contracts Deep Dive
4. 🎨 Frontend Components
5. 🚀 Getting Started
6. 💻 Code Examples
7. 🛡️ Security Considerations

🌟 Project Overview

The Stablecoin Challenge is a comprehensive DeFi protocol that implements a collateralized stablecoin system with the following key features:

• 💵 MyUSD: An ETH-collateralized stablecoin that stays stable like a rock!
• 📈 Staking System: Earn juicy yield on MyUSD deposits 💰
• 🔄 DEX Integration: Trade MyUSD/ETH with automated market making magic ✨
• ⚡ Liquidation Engine: Maintain system stability through liquidations (sorry not sorry! 😅)
• 🎛️ Rate Controls: Dynamic interest rate management for maximum profits! 📊

🏗️ Architecture

Behold the beautiful architecture of our DeFi masterpiece! 🎨

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  💵 MyUSD Token │    │ ⚙️ MyUSDEngine   │    │ 📈 MyUSDStaking │
│   (ERC20) 🪙    │◄───┤ (Core Logic) 🧠 │◄───┤ (Yield System)💰│
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   🔄 DEX        │    │  📊 Oracle      │    │ 🎛️ RateController│
│ (AMM Trading)🔀 │    │ (Price Feed) 📈 │    │ (Rate Mgmt) ⚡  │
└─────────────────┘    └─────────────────┘    └─────────────────┘

🔍 Smart Contracts Deep Dive

1. 💵 MyUSD Token Contract

Purpose: ERC20 stablecoin with special handling for staking integration 🎯

Key Features ✨:

• 🏭 Mintable only by the engine contract (no funny business!)
• 🔥 Burnable by engine and owner (poof! gone!)
• 👻 Virtual balance handling for staking contract (it's like magic!)
• 📊 Custom totalSupply() that includes staked tokens

📋 State Variables Deep Dive

contract MyUSD is ERC20, Ownable {
    address public stakingContract;  // 📈 Address of the staking contract
    address public engineContract;   // ⚙️ Address of the engine contract
}

Variable Explanations:

• stakingContract 📈: Points to MyUSDStaking contract for virtual balance calculations
• engineContract ⚙️: Only this address can mint new MyUSD tokens (maintains collateral backing!)

🏗️ Constructor Logic

constructor(address _engineContract, address _stakingContract)
    ERC20("MyUSD", "MyUSD")
    Ownable(msg.sender) {
    engineContract = _engineContract;
    stakingContract = _stakingContract;
}

What happens here 🎯:

1. 🏷️ Sets token name and symbol to "MyUSD"
2. 👑 Makes deployer the owner
3. 🔗 Links to engine and staking contracts
4. 🚀 Ready to mint some stablecoins!

🔥 burnFrom Function

function burnFrom(address account, uint256 amount) external returns (bool) {
    // 🛡️ Security check: Only engine or owner can burn
    if (msg.sender != engineContract && msg.sender != owner())
        revert MyUSD__NotAuthorized();

    uint256 balance = balanceOf(account);  // 📊 Get current balance

    // 🚫 Validation checks
    if (amount == 0) revert MyUSD__InvalidAmount();
    if (balance < amount) revert MyUSD__InsufficientBalance();

    _burn(account, amount);  // 🔥 Burn the tokens
    return true;
}

Step-by-step breakdown 📝:

1. Authorization Check 🔐: Ensures only engine or owner can burn tokens
2. Balance Retrieval 📊: Gets account balance (handles virtual balances for staking!)
3. Amount Validation ✅: Prevents burning 0 tokens or more than available
4. Token Destruction 🔥: Actually burns the tokens from circulation
5. Success Signal ✅: Returns true to confirm operation

🏭 mintTo Function

function mintTo(address to, uint256 amount) external returns (bool) {
    // 🛡️ CRITICAL: Only engine can mint (maintains collateral backing!)
    if (msg.sender != engineContract) revert MyUSD__NotAuthorized();

    // 🚫 Validation checks
    if (to == address(0)) revert MyUSD__InvalidAddress();
    if (amount == 0) revert MyUSD__InvalidAmount();

    _mint(to, amount);  // 🏭 Create new tokens
    return true;
}

Why only engine can mint 🤔:

• 💎 Every MyUSD must be backed by collateral
• ⚙️ Engine ensures proper collateralization before minting
• 🛡️ Prevents unauthorized token creation (no infinite money glitch!)

👻 balanceOf Function (The Magic!)

function balanceOf(address account) public view override returns (uint256) {
    // 👤 For normal accounts, return standard balance
    if (account != stakingContract) {
        return super.balanceOf(account);
    }

    // 🎭 For staking contract, return virtual balance
    MyUSDStaking staking = MyUSDStaking(stakingContract);
    return staking.getSharesValue(staking.totalShares());
}

The Virtual Balance Trick 🎪:

1. Normal Users 👤: Get their actual token balance
2. Staking Contract 📈: Gets the total value of all staked shares
3. Why Virtual? 🤔: Staking contract doesn't hold actual tokens, just shares that represent value!

🔄 _update Function (Transfer Logic)

function _update(address from, address to, uint256 value) internal override {
    // 📈 If staking contract is sending tokens
    if (from == stakingContract) {
        super._mint(to, value);  // 🏭 Mint new tokens (virtual → real)
    }
    // 📈 If sending tokens to staking contract
    else if (to == stakingContract) {
        super._burn(from, value);  // 🔥 Burn tokens (real → virtual)
    }
    // 👤 Normal transfer between users
    else {
        super._update(from, to, value);  // 🔄 Standard transfer
    }
}

Transfer Magic Explained ✨:

• To Staking 📈: Burns real tokens, creates virtual shares
• From Staking 📉: Mints real tokens, destroys virtual shares
• Normal Transfer 👥: Standard ERC20 behavior

📊 totalSupply Function

function totalSupply() public view override returns (uint256) {
    MyUSDStaking staking = MyUSDStaking(stakingContract);
    uint256 stakedTotalSupply = staking.getSharesValue(staking.totalShares());
    return super.totalSupply() + stakedTotalSupply;
}

Total Supply Calculation 🧮:

1. Circulating Supply 🔄: Tokens in wallets and contracts
2. Staked Supply 📈: Value of all staked shares
3. True Total 📊: Both combined for accurate accounting

Security Features 🛡️:

• 🔐 Access control for minting/burning (Fort Knox level security!)
• 🚫 Virtual balance prevents double counting (no cheating allowed!)
• ⛽ Custom errors for gas efficiency (save those precious gwei!)

2. ⚙️ MyUSDEngine Contract

Purpose: Core protocol logic for collateralization, minting, and liquidations 🎯

Key Mechanisms 🔧:

📋 State Variables Deep Dive

contract MyUSDEngine is Ownable {
    // 🔢 Constants - The Rules of the Game!
    uint256 private constant COLLATERAL_RATIO = 150;    // 150% minimum collateral
    uint256 private constant LIQUIDATOR_REWARD = 10;    // 10% bonus for liquidators
    uint256 private constant SECONDS_PER_YEAR = 365 days; // Time calculations
    uint256 private constant PRECISION = 1e18;           // 18 decimal precision

    // 🔗 Contract References
    MyUSD private i_myUSD;              // The stablecoin contract
    Oracle private i_oracle;            // Price feed oracle
    MyUSDStaking private i_staking;     // Staking contract
    address private i_rateController;   // Rate management contract

    // 📊 Interest Rate System
    uint256 public borrowRate;          // Annual rate in basis points (100 = 1%)
    uint256 public lastUpdateTime;      // Last interest accrual timestamp
    uint256 public totalDebtShares;     // Total debt shares in circulation
    uint256 public debtExchangeRate;    // Shares to MyUSD conversion rate

    // 👤 User Data
    mapping(address => uint256) public s_userCollateral;   // ETH collateral per user
    mapping(address => uint256) public s_userDebtShares;   // Debt shares per user
}

Variable Explanations 📝:

• COLLATERAL_RATIO 💎: Minimum 150% backing required (safety first!)
• LIQUIDATOR_REWARD 🎁: 10% bonus for liquidators (incentivizes protocol health)
• borrowRate 📈: Interest rate borrowers pay (in basis points)
• debtExchangeRate 🔄: Converts debt shares to actual MyUSD debt (grows with interest!)
• totalDebtShares 📊: Total debt shares across all users
• s_userCollateral 💰: Each user's ETH collateral amount
• s_userDebtShares 📋: Each user's debt shares (not actual debt amount!)

🏗️ Constructor Logic

constructor(address _oracle, address _myUSDAddress, address _stakingAddress, address _rateController)
    Ownable(msg.sender) {
    i_oracle = Oracle(_oracle);
    i_myUSD = MyUSD(_myUSDAddress);
    i_staking = MyUSDStaking(_stakingAddress);
    i_rateController = _rateController;
    lastUpdateTime = block.timestamp;
    debtExchangeRate = PRECISION; // 1:1 initially (1 share = 1 MyUSD)
}

Setup Process 🚀:

1. 🔗 Links all contract dependencies
2. ⏰ Sets initial timestamp for interest calculations
3. 📊 Initializes debt exchange rate at 1:1 (no interest yet!)

💎 Collateralization System

• Minimum Ratio: 150% (1.5 ETH value per 1 MyUSD) 📏
• Liquidation Threshold: Below 150% ⚠️
• Liquidator Reward: 10% bonus 🎁 (thanks for keeping us safe!)

💰 addCollateral Function

function addCollateral() public payable {
    if (msg.value == 0) {
        revert Engine__InvalidAmount(); // 🚫 No zero deposits!
    }

    s_userCollateral[msg.sender] += msg.value; // 📈 Add to user's collateral
    emit CollateralAdded(msg.sender, msg.value, i_oracle.getPrice()); // 📡 Broadcast event
}

Step-by-step 📝:

1. Validation ✅: Ensures user sent ETH with transaction
2. Storage Update 💾: Adds ETH to user's collateral balance
3. Event Emission 📡: Logs the deposit with current ETH price

💸 withdrawCollateral Function

function withdrawCollateral(uint256 amount) external {
    // 🚫 Validation checks
    if (amount == 0 || s_userCollateral[msg.sender] < amount) {
        revert Engine__InvalidAmount();
    }

    // 🧮 Temporarily update collateral for safety check
    uint256 newCollateral = s_userCollateral[msg.sender] - amount;
    s_userCollateral[msg.sender] = newCollateral;

    // 🛡️ Ensure position remains safe after withdrawal
    if (s_userDebtShares[msg.sender] > 0) {
        _validatePosition(msg.sender);
    }

    // 💸 Transfer ETH to user
    payable(msg.sender).transfer(amount);
    emit CollateralWithdrawn(msg.sender, msg.sender, amount, i_oracle.getPrice());
}

Safety First Approach 🛡️:

1. Pre-validation ✅: Checks amount and user balance
2. Optimistic Update 🔄: Updates collateral first
3. Safety Check 🛡️: Validates position is still safe
4. Transfer 💸: Sends ETH to user (reverts if position unsafe!)

📈 Interest Rate System Deep Dive

The engine uses a debt shares system for compound interest! 🤯

🔄 _accrueInterest Function

function _accrueInterest() internal {
    if (totalDebtShares == 0) {
        lastUpdateTime = block.timestamp; // 📅 Update timestamp
        return; // 🚪 Exit if no debt
    }

    uint256 timeElapsed = block.timestamp - lastUpdateTime;
    if (timeElapsed == 0 || borrowRate == 0) return; // 🚫 No time passed or no rate

    // 🧮 Calculate total debt value
    uint256 totalDebtValue = (totalDebtShares * debtExchangeRate) / PRECISION;

    // 💰 Calculate interest owed
    uint256 interest = (totalDebtValue * borrowRate * timeElapsed) / (SECONDS_PER_YEAR * 10000);

    if (interest > 0) {
        // 📈 Increase exchange rate (makes shares worth more MyUSD!)
        debtExchangeRate += (interest * PRECISION) / totalDebtShares;
    }
    lastUpdateTime = block.timestamp; // 📅 Update timestamp
}

Interest Magic Explained ✨:

1. Time Check ⏰: Calculates time since last update
2. Debt Calculation 🧮: Gets total debt value using current exchange rate
3. Interest Formula 📊: (debt × rate × time) / (year × 10000)
4. Rate Update 📈: Increases exchange rate so shares represent more debt!

🔍 _getUpdatedExchangeRate Function

function _getUpdatedExchangeRate() internal view returns (uint256) {
    uint256 timeElapsed = block.timestamp - lastUpdateTime;
    if (timeElapsed == 0 || borrowRate == 0 || totalDebtShares == 0) {
        return debtExchangeRate; // 📊 Return current rate
    }

    // 🧮 Calculate interest without updating state
    uint256 totalDebtValue = (totalDebtShares * debtExchangeRate) / PRECISION;
    uint256 interest = (totalDebtValue * borrowRate * timeElapsed) / (SECONDS_PER_YEAR * 10000);

    return debtExchangeRate + (interest * PRECISION) / totalDebtShares; // 📈 Return new rate
}

View Function Magic 🔮:

• Same calculation as _accrueInterest but read-only
• Used for getting current debt without updating state
• Perfect for UI displays and calculations!

💵 getCurrentDebtValue Function

function getCurrentDebtValue(address user) public view returns (uint256) {
    if (s_userDebtShares[user] == 0) return 0; // 🚫 No debt

    uint256 updatedExchangeRate = _getUpdatedExchangeRate(); // 📊 Get current rate
    return ((s_userDebtShares[user] * updatedExchangeRate) / PRECISION) + 1; // 🧮 Calculate debt
}

Debt Calculation 🧮:

• userShares × exchangeRate = actualDebt
• The + 1 prevents rounding errors in user's favor
• Always returns the current debt including accrued interest!

🏭 mintMyUSD Function

function mintMyUSD(uint256 mintAmount) public {
    if (mintAmount == 0) {
        revert Engine__InvalidAmount(); // 🚫 No zero minting
    }

    // 🧮 Calculate debt shares for this mint amount
    uint256 debtShares = _getMyUSDToShares(mintAmount);

    // 📈 Update user and total debt shares
    s_userDebtShares[msg.sender] += debtShares;
    totalDebtShares += debtShares;

    _validatePosition(msg.sender); // 🛡️ Ensure position is safe

    bool success = i_myUSD.mintTo(msg.sender, mintAmount); // 🏭 Mint tokens
    if (!success) {
        revert Engine__MintingFailed();
    }

    emit DebtSharesMinted(msg.sender, mintAmount, debtShares); // 📡 Log event
}

Minting Process 🏭:

1. Amount Validation ✅: No zero minting allowed
2. Share Calculation 🧮: Converts MyUSD amount to debt shares
3. State Updates 📊: Updates user and total debt shares
4. Safety Check 🛡️: Validates collateralization ratio
5. Token Creation 🏭: Actually mints the MyUSD tokens
6. Event Logging 📡: Records the mint operation

💸 repayUpTo Function

function repayUpTo(uint256 amount) public {
    if (amount == 0) {
        revert Engine__InvalidAmount(); // 🚫 No zero repayment
    }

    uint256 amountInShares = _getMyUSDToShares(amount); // 🧮 Convert to shares

    // 🔍 Check if user has enough debt
    if (amountInShares > s_userDebtShares[msg.sender]) {
        // 📊 Only repay what they owe
        amountInShares = s_userDebtShares[msg.sender];
        amount = getCurrentDebtValue(msg.sender);
    }

    // 📉 Reduce debt shares
    s_userDebtShares[msg.sender] -= amountInShares;
    totalDebtShares -= amountInShares;

    bool success = i_myUSD.burnFrom(msg.sender, amount); // 🔥 Burn tokens
    if (!success) {
        revert Engine__BurningFailed();
    }

    emit DebtSharesBurned(msg.sender, amount, amountInShares); // 📡 Log event
}

Repayment Logic 💸:

1. Amount Validation ✅: No zero repayments
2. Share Conversion 🧮: Converts MyUSD to debt shares
3. Overpayment Protection 🛡️: Prevents paying more than owed
4. State Updates 📉: Reduces user and total debt shares
5. Token Burning 🔥: Destroys the repaid MyUSD
6. Event Logging 📡: Records the repayment

🛡️ Position Validation System

📊 calculateCollateralValue Function

function calculateCollateralValue(address user) public view returns (uint256) {
    uint256 collateralAmount = s_userCollateral[user]; // 💰 Get user's ETH
    return (collateralAmount * i_oracle.getPrice()) / 1e18; // 🧮 Convert to USD value
}

🧮 _calculatePositionRatio Function

function _calculatePositionRatio(address user) private view returns (uint256) {
    uint256 mintedAmount = getCurrentDebtValue(user); // 💵 Get current debt
    uint256 collateralValue = calculateCollateralValue(user); // 💰 Get collateral value

    if (mintedAmount == 0) return type(uint256).max; // ♾️ Infinite ratio if no debt

    return (collateralValue * 1e18) / mintedAmount; // 🧮 Calculate ratio
}

Ratio Calculation 📊:

• collateralValue / debtValue = ratio
• Ratio of 1.5 (1.5e18) = 150% collateralization
• Higher ratio = safer position!

🛡️ _validatePosition Function

function _validatePosition(address user) internal view {
    uint256 positionRatio = _calculatePositionRatio(user);
    if ((positionRatio * 100) < COLLATERAL_RATIO * 1e18) {
        revert Engine__UnsafePositionRatio(); // 🚨 Position too risky!
    }
}

Safety Check 🛡️:

• Ensures ratio ≥ 150%
• Called after every mint/withdrawal
• Prevents risky positions!

📈 Interest Rate System

• Debt Shares: Users receive shares representing their debt 🎫
• Exchange Rate: Increases over time based on borrow rate 📊
• Compound Interest: Automatically accrued 🔄 (money makes money!)

// Calculate current debt including accrued interest
function getCurrentDebtValue(address user) public view returns (uint256) {
    if (s_userDebtShares[user] == 0) return 0;
    uint256 updatedExchangeRate = _getUpdatedExchangeRate();
    return ((s_userDebtShares[user] * updatedExchangeRate) / PRECISION) + 1;
}

// Accrue interest on total debt
function _accrueInterest() internal {
    uint256 timeElapsed = block.timestamp - lastUpdateTime;
    uint256 totalDebtValue = (totalDebtShares * debtExchangeRate) / PRECISION;
    uint256 interest = (totalDebtValue * borrowRate * timeElapsed) / (SECONDS_PER_YEAR * 10000);

    if (interest > 0) {
        debtExchangeRate += (interest * PRECISION) / totalDebtShares;
    }
    lastUpdateTime = block.timestamp;
}

⚡ Liquidation Mechanism (The Cleanup Crew!)

The liquidation system keeps the protocol healthy by removing risky positions! 🚨

🔍 isLiquidatable Function

function isLiquidatable(address user) public view returns (bool) {
    uint256 positionRatio = _calculatePositionRatio(user);
    return (positionRatio * 100) < COLLATERAL_RATIO * 1e18; // Below 150%
}

Liquidation Check 🔍:

• Calculates user's position ratio
• Returns true if ratio < 150%
• Public function so anyone can check!

⚡ liquidate Function (The Big One!)

function liquidate(address user) external {
    if (!isLiquidatable(user)) {
        revert Engine__NotLiquidatable(); // 🚫 Position is safe
    }

    // 📊 Get user's financial state
    uint256 userDebtValue = getCurrentDebtValue(user);
    uint256 userCollateral = s_userCollateral[user];
    uint256 collateralValue = calculateCollateralValue(user);

    // 🛡️ Ensure liquidator has enough MyUSD
    if (i_myUSD.balanceOf(msg.sender) < userDebtValue) {
        revert MyUSD__InsufficientBalance();
    }

    // 🛡️ Ensure liquidator approved the transfer
    if (i_myUSD.allowance(msg.sender, address(this)) < userDebtValue) {
        revert MyUSD__InsufficientAllowance();
    }

    // 💸 Transfer MyUSD from liquidator to engine
    i_myUSD.transferFrom(msg.sender, address(this), userDebtValue);

    // 🔥 Burn the MyUSD (removes from circulation)
    i_myUSD.burnFrom(address(this), userDebtValue);

    // 📉 Clear user's debt completely
    totalDebtShares -= s_userDebtShares[user];
    s_userDebtShares[user] = 0;

    // 🧮 Calculate liquidator reward
    uint256 collateralPurchased = (userDebtValue * userCollateral) / collateralValue;
    uint256 liquidatorReward = (collateralPurchased * LIQUIDATOR_REWARD) / 100;
    uint256 amountForLiquidator = collateralPurchased + liquidatorReward;

    // 🛡️ Don't exceed user's collateral
    amountForLiquidator = amountForLiquidator > userCollateral ? userCollateral : amountForLiquidator;

    // 📉 Update user's collateral
    s_userCollateral[user] = userCollateral - amountForLiquidator;

    // 💰 Send ETH reward to liquidator
    (bool sent, ) = payable(msg.sender).call{ value: amountForLiquidator }("");
    require(sent, "Failed to send Ether");

    emit Liquidation(user, msg.sender, amountForLiquidator, userDebtValue, i_oracle.getPrice());
}

Liquidation Process ⚡:

1. Safety Check 🛡️: Ensures position is actually liquidatable
2. Financial Assessment 📊: Gets user's debt and collateral values
3. Liquidator Validation ✅: Ensures liquidator has enough MyUSD and approval
4. Debt Payment 💸: Transfers MyUSD from liquidator to engine
5. Token Burning 🔥: Removes MyUSD from circulation
6. Debt Clearing 📉: Zeros out user's debt shares
7. Reward Calculation 🧮: Calculates 110% reward for liquidator
8. Collateral Transfer 💰: Sends ETH reward to liquidator
9. Event Logging 📡: Records the liquidation

Why Liquidation Works 🤔:

• Liquidator Incentive 💰: Gets 110% value (10% bonus!)
• Protocol Safety 🛡️: Removes risky positions
• User Protection 👤: Saves remaining collateral from total loss
• System Stability ⚖️: Maintains overall health

🎛️ setBorrowRate Function

function setBorrowRate(uint256 newRate) external onlyRateController {
    if (newRate < i_staking.savingsRate()) revert Engine__InvalidBorrowRate();
    _accrueInterest(); // 📊 Update interest before changing rate
    borrowRate = newRate;
    emit BorrowRateUpdated(newRate);
}

Rate Setting Logic 🎛️:

1. Authorization 🔐: Only rate controller can call
2. Rate Validation ✅: Borrow rate must be ≥ savings rate
3. Interest Accrual 📊: Updates all existing debt first
4. Rate Update 🔄: Sets new borrow rate
5. Event Emission 📡: Logs the rate change

Why Borrow Rate ≥ Savings Rate? 🤔:

• Ensures protocol profitability
• Borrowers pay more than savers earn
• Prevents arbitrage opportunities

3. 📈 MyUSDStaking Contract

Purpose: Yield-bearing savings account for MyUSD holders 💰

Key Features 🌟:

• Share-based System: Users receive shares representing their stake 🎫
• Compound Interest: Automatic yield accrual 🔄 (set it and forget it!)
• Exchange Rate: Increases over time based on savings rate 📊 (watch your money grow!)

📋 State Variables Deep Dive

contract MyUSDStaking is Ownable, ReentrancyGuard {
    MyUSD public immutable myUSD;        // 💵 The stablecoin contract
    MyUSDEngine public engine;           // ⚙️ The engine contract
    address private i_rateController;    // 🎛️ Rate management contract

    // 📊 Staking Pool State
    uint256 public totalShares;          // Total shares in the pool
    uint256 public exchangeRate;         // Shares to MyUSD conversion rate
    uint256 public lastUpdateTime;       // Last interest accrual timestamp
    uint256 public savingsRate;          // Annual rate in basis points

    // 👤 User Data
    mapping(address => uint256) public userShares; // Each user's share balance

    // 🔢 Constants
    uint256 private constant PRECISION = 1e18;
    uint256 private constant SECONDS_PER_YEAR = 365 days;
}

Variable Explanations 📝:

• totalShares 📊: Total shares across all stakers
• exchangeRate 🔄: How much MyUSD each share is worth (grows with yield!)
• savingsRate 💰: Interest rate stakers earn (in basis points)
• userShares 👤: Each user's share balance (not MyUSD amount!)
• PRECISION 🔢: 18 decimal precision for calculations

🏗️ Constructor Logic

constructor(address _myUSD, address _engine, address _rateController) Ownable(msg.sender) {
    myUSD = MyUSD(_myUSD);
    engine = MyUSDEngine(_engine);
    i_rateController = _rateController;
    exchangeRate = PRECISION; // 1:1 initially (1 share = 1 MyUSD)
    lastUpdateTime = block.timestamp;
}

Setup Process 🚀:

1. 🔗 Links to MyUSD and Engine contracts
2. 📊 Initializes exchange rate at 1:1 (no yield yet!)
3. ⏰ Sets initial timestamp for interest calculations

🎛️ setSavingsRate Function

function setSavingsRate(uint256 newRate) external onlyRateController {
    if (newRate > engine.borrowRate()) revert Staking__InvalidSavingsRate();
    _accrueInterest(); // 📊 Update interest before changing rate
    savingsRate = newRate;
    emit SavingsRateUpdated(newRate);
}

Rate Setting Logic 🎛️:

1. Authorization 🔐: Only rate controller can call
2. Rate Validation ✅: Savings rate must be ≤ borrow rate
3. Interest Accrual 📊: Updates all existing stakes first
4. Rate Update 🔄: Sets new savings rate
5. Event Emission 📡: Logs the rate change

📈 Interest Accrual System

🔄 _accrueInterest Function

function _accrueInterest() internal {
    if (totalShares == 0) {
        lastUpdateTime = block.timestamp; // 📅 Update timestamp
        return; // 🚪 Exit if no stakes
    }

    uint256 timeElapsed = block.timestamp - lastUpdateTime;
    if (timeElapsed == 0) return; // 🚫 No time passed

    // 🧮 Calculate total staked value
    uint256 totalValue = getSharesValue(totalShares);

    // 💰 Calculate interest earned
    uint256 interest = (totalValue * savingsRate * timeElapsed) / (SECONDS_PER_YEAR * 10000);

    if (interest > 0) {
        // 📈 Increase exchange rate (makes shares worth more MyUSD!)
        exchangeRate += (interest * PRECISION) / totalShares;
    }

    lastUpdateTime = block.timestamp; // 📅 Update timestamp
}

Interest Magic Explained ✨:

1. Time Check ⏰: Calculates time since last update
2. Value Calculation 🧮: Gets total staked value using current exchange rate
3. Interest Formula 📊: (value × rate × time) / (year × 10000)
4. Rate Update 📈: Increases exchange rate so shares represent more MyUSD!

🔍 _getCurrentExchangeRate Function

function _getCurrentExchangeRate() internal view returns (uint256) {
    if (totalShares == 0) return exchangeRate; // 📊 Return current rate

    uint256 timeElapsed = block.timestamp - lastUpdateTime;
    if (timeElapsed == 0) return exchangeRate; // 🚫 No time passed

    // 🧮 Calculate interest without updating state
    uint256 totalValue = (totalShares * exchangeRate) / PRECISION;
    uint256 interest = (totalValue * savingsRate * timeElapsed) / (SECONDS_PER_YEAR * 10000);

    if (interest == 0) return exchangeRate;

    return exchangeRate + ((interest * PRECISION) / totalShares); // 📈 Return new rate
}

View Function Magic 🔮:

• Same calculation as _accrueInterest but read-only
• Used for getting current exchange rate without updating state
• Perfect for UI displays and calculations!

💰 stake Function

function stake(uint256 amount) external nonReentrant {
    if (amount == 0) revert Staking__InvalidAmount(); // 🚫 No zero staking

    // 🧮 Calculate shares based on current exchange rate
    uint256 shares = (amount * PRECISION) / _getCurrentExchangeRate();

    // 📈 Update user and total shares
    userShares[msg.sender] += shares;
    totalShares += shares;

    // 💸 Transfer MyUSD to contract
    bool success = myUSD.transferFrom(msg.sender, address(this), amount);
    if (!success) revert Staking__TransferFailed();

    emit Staked(msg.sender, amount, shares); // 📡 Log event
}

Staking Process 💰:

1. Amount Validation ✅: No zero staking allowed
2. Share Calculation 🧮: Converts MyUSD amount to shares using current rate
3. State Updates 📊: Updates user and total shares
4. Token Transfer 💸: Moves MyUSD from user to contract
5. Event Logging 📡: Records the stake operation

Share Calculation Example 📊:

• If exchange rate is 1.1 (shares worth 10% more)
• Staking 100 MyUSD gives: 100 × 1e18 / 1.1e18 = ~90.9 shares
• Those shares will be worth more MyUSD over time!

💸 withdraw Function

function withdraw(uint256 shareAmount) external nonReentrant {
    if (shareAmount == 0) revert Staking__InvalidAmount(); // 🚫 No zero withdrawal
    if (userShares[msg.sender] < shareAmount) revert Staking__InsufficientBalance(); // 🚫 Not enough shares
    if (address(engine) == address(0)) revert Staking__EngineNotSet(); // 🚫 Engine not set

    // 🧮 Calculate MyUSD amount including yield
    uint256 amount = getSharesValue(shareAmount);

    // 📉 Update user's shares
    userShares[msg.sender] -= shareAmount;

    // 💸 Transfer MyUSD to user
    bool success = myUSD.transfer(msg.sender, amount);
    if (!success) revert Staking__TransferFailed();

    // 📉 Update total shares (after transfer for virtual balance calculation)
    totalShares -= shareAmount;

    emit Withdrawn(msg.sender, amount, shareAmount); // 📡 Log event
}

Withdrawal Process 💸:

1. Amount Validation ✅: No zero withdrawals, sufficient shares
2. Value Calculation 🧮: Converts shares to MyUSD using current rate
3. Share Update 📉: Reduces user's shares
4. Token Transfer 💸: Sends MyUSD to user
5. Total Update 📊: Updates total shares (order matters for virtual balance!)
6. Event Logging 📡: Records the withdrawal

Why Order Matters 🤔:

• MyUSD contract checks totalShares for virtual balance
• Must update totalShares after transfer for correct calculation!

🔍 Helper Functions

📊 getSharesValue Function

function getSharesValue(uint256 shares) public view returns (uint256) {
    return (shares * _getCurrentExchangeRate()) / PRECISION;
}

Value Calculation 📊:

• shares × exchangeRate = MyUSD value
• Shows how much MyUSD the shares are worth
• Includes all accrued yield!

💰 getBalance Function

function getBalance(address user) external view returns (uint256) {
    if (userShares[user] == 0) return 0;
    return getSharesValue(userShares[user]);
}

User Balance 👤:

• Returns user's total MyUSD value (shares + yield)
• Perfect for UI displays
• Always up-to-date with current exchange rate!

4. 🔄 DEX Contract

Purpose: Automated Market Maker for MyUSD/ETH trading 🔀

AMM Formula: Constant Product (x * y = k) 🧮 (the magic formula!)

📋 State Variables Deep Dive

contract DEX {
    IERC20 token;                              // 💵 The MyUSD token contract
    uint256 public totalLiquidity;             // 🌊 Total liquidity pool tokens
    mapping(address => uint256) public liquidity; // 👤 Each user's liquidity tokens
}

Variable Explanations 📝:

• token 💵: Reference to MyUSD token contract
• totalLiquidity 🌊: Total liquidity provider tokens in circulation
• liquidity 👤: Each user's share of the liquidity pool

🏗️ Constructor Logic

constructor(address tokenAddr) {
    token = IERC20(tokenAddr); // 🔗 Link to MyUSD token
}

Setup Process 🚀:

• Links to the MyUSD token contract
• Ready to facilitate trading!

🌊 init Function (Pool Initialization)

function init(uint256 tokens) public payable returns (uint256) {
    require(totalLiquidity == 0, "DEX: init - already has liquidity"); // 🚫 One-time only

    totalLiquidity = address(this).balance; // 📊 Set initial liquidity to ETH amount
    liquidity[msg.sender] = totalLiquidity; // 👤 Give all LP tokens to initializer

    require(token.transferFrom(msg.sender, address(this), tokens), "DEX: init - transfer did not transact");
    return totalLiquidity;
}

Initialization Process 🌊:

1. One-time Check ✅: Ensures pool isn't already initialized
2. Liquidity Setting 📊: Sets total liquidity to ETH amount sent
3. Token Assignment 👤: Gives all LP tokens to initializer
4. Token Transfer 💸: Moves MyUSD tokens to DEX
5. Return Value 📊: Returns amount of LP tokens minted

🧮 AMM Pricing Functions

📊 price Function (The Core Formula!)

function price(uint256 xInput, uint256 xReserves, uint256 yReserves)
    public pure returns (uint256 yOutput) {
    uint256 numerator = xInput * yReserves;     // 🧮 Input × Output Reserve
    uint256 denominator = (xReserves) + xInput; // 🧮 Input Reserve + Input
    return (numerator / denominator);           // 🧮 Final calculation
}

AMM Magic Explained ✨:

• Formula: yOutput = (xInput × yReserves) / (xReserves + xInput)
• Constant Product: Maintains x × y = k relationship
• Slippage: Larger trades get worse prices (protects liquidity!)

Example Calculation 📊:

• ETH Reserve: 100 ETH, MyUSD Reserve: 180,000 MyUSD
• Input: 1 ETH
• Output: (1 × 180,000) / (100 + 1) = 1,782.18 MyUSD
• Price: ~1,782 MyUSD per ETH

💱 currentPrice Function

function currentPrice() public view returns (uint256 _currentPrice) {
    _currentPrice = price(1 ether, address(this).balance, token.balanceOf(address(this)));
}

Current Price Calculation 💱:

• Calculates price for 1 ETH in MyUSD
• Uses current pool reserves
• Perfect for price displays!

🔄 Trading Functions

💰 ethToToken Function

function ethToToken() internal returns (uint256 tokenOutput) {
    require(msg.value > 0, "cannot swap 0 ETH"); // 🚫 No zero swaps

    uint256 ethReserve = address(this).balance - msg.value; // 📊 Reserve before swap
    uint256 tokenReserve = token.balanceOf(address(this));  // 📊 Token reserve

    tokenOutput = price(msg.value, ethReserve, tokenReserve); // 🧮 Calculate output

    require(token.transfer(msg.sender, tokenOutput), "ethToToken(): reverted swap.");
    emit Swap(msg.sender, address(0), msg.value, address(token), tokenOutput);
    return tokenOutput;
}

ETH → MyUSD Process 💰:

1. Validation ✅: No zero ETH swaps
2. Reserve Calculation 📊: Gets reserves before adding new ETH
3. Price Calculation 🧮: Uses AMM formula for output amount
4. Token Transfer 💸: Sends MyUSD to user
5. Event Emission 📡: Logs the swap

💸 tokenToEth Function

function tokenToEth(uint256 tokenInput) internal returns (uint256 ethOutput) {
    require(tokenInput > 0, "cannot swap 0 tokens"); // 🚫 No zero swaps
    require(token.balanceOf(msg.sender) >= tokenInput, "insufficient token balance"); // 🚫 Check balance
    require(token.allowance(msg.sender, address(this)) >= tokenInput, "insufficient allowance"); // 🚫 Check approval

    uint256 tokenReserve = token.balanceOf(address(this)); // 📊 Current token reserve
    ethOutput = price(tokenInput, tokenReserve, address(this).balance); // 🧮 Calculate ETH output

    require(token.transferFrom(msg.sender, address(this), tokenInput), "tokenToEth(): reverted swap.");
    (bool sent,) = msg.sender.call{value: ethOutput}("");
    require(sent, "tokenToEth: revert in transferring eth to you!");

    emit Swap(msg.sender, address(token), tokenInput, address(0), ethOutput);
    return ethOutput;
}

MyUSD → ETH Process 💸:

1. Validation ✅: No zero swaps, sufficient balance and approval
2. Reserve Check 📊: Gets current token reserve
3. Price Calculation 🧮: Uses AMM formula for ETH output
4. Token Transfer 💸: Takes MyUSD from user
5. ETH Transfer 💰: Sends ETH to user
6. Event Emission 📡: Logs the swap

🔄 swap Function (Public Interface)

function swap(uint256 inputAmount) public payable returns (uint256 outputAmount) {
    if (msg.value > 0 && inputAmount == msg.value) {
        outputAmount = ethToToken(); // 💰 ETH → MyUSD
    } else {
        outputAmount = tokenToEth(inputAmount); // 💸 MyUSD → ETH
    }
    emit PriceUpdated(currentPrice()); // 📊 Update price after swap
}

Smart Swap Logic 🔄:

• ETH Input: If msg.value > 0, swap ETH for MyUSD
• Token Input: Otherwise, swap MyUSD for ETH
• Price Update: Emits new price after swap

🌊 Liquidity Provision Functions

💰 deposit Function

function deposit() public payable returns (uint256 tokensDeposited) {
    require(msg.value > 0, "Must send value when depositing"); // 🚫 Must send ETH

    uint256 ethReserve = address(this).balance - msg.value; // 📊 ETH reserve before deposit
    uint256 tokenReserve = token.balanceOf(address(this));  // 📊 Token reserve

    // 🧮 Calculate proportional token amount needed
    uint256 tokenDeposit = (msg.value * tokenReserve / ethReserve) + 1;

    require(token.balanceOf(msg.sender) >= tokenDeposit, "insufficient token balance");
    require(token.allowance(msg.sender, address(this)) >= tokenDeposit, "insufficient allowance");

    // 🧮 Calculate LP tokens to mint
    uint256 liquidityMinted = msg.value * totalLiquidity / ethReserve;
    liquidity[msg.sender] += liquidityMinted; // 👤 Add to user's LP tokens
    totalLiquidity += liquidityMinted;        // 📊 Add to total LP tokens

    require(token.transferFrom(msg.sender, address(this), tokenDeposit));
    emit LiquidityProvided(msg.sender, liquidityMinted, msg.value, tokenDeposit);
    return tokenDeposit;
}

Liquidity Provision Process 🌊:

1. ETH Validation ✅: Must send ETH with transaction
2. Reserve Calculation 📊: Gets current reserves
3. Proportional Calculation 🧮: Calculates required MyUSD amount
4. Balance Checks ✅: Ensures user has enough tokens and approval
5. LP Token Minting 🏭: Calculates and mints LP tokens proportionally
6. Token Transfer 💸: Takes MyUSD from user
7. Event Emission 📡: Logs the liquidity provision

LP Token Formula 🧮:

• liquidityMinted = (ethDeposited × totalLiquidity) / ethReserve
• Proportional to existing pool size
• Maintains fair share distribution!

💸 withdraw Function

function withdraw(uint256 amount) public returns (uint256 ethAmount, uint256 tokenAmount) {
    require(liquidity[msg.sender] >= amount, "withdraw: sender does not have enough liquidity to withdraw.");

    uint256 ethReserve = address(this).balance;   // 📊 Current ETH reserve
    uint256 tokenReserve = token.balanceOf(address(this)); // 📊 Current token reserve

    // 🧮 Calculate proportional withdrawals
    uint256 ethWithdrawn = amount * ethReserve / totalLiquidity;
    tokenAmount = amount * tokenReserve / totalLiquidity;

    // 📉 Update LP token balances
    liquidity[msg.sender] -= amount;
    totalLiquidity -= amount;

    // 💸 Transfer assets to user
    (bool sent,) = payable(msg.sender).call{value: ethWithdrawn}("");
    require(sent, "withdraw(): revert in transferring eth to you!");
    require(token.transfer(msg.sender, tokenAmount));

    emit LiquidityRemoved(msg.sender, amount, tokenAmount, ethWithdrawn);
    return (ethWithdrawn, tokenAmount);
}

Withdrawal Process 💸:

1. LP Token Check ✅: Ensures user has enough LP tokens
2. Reserve Calculation 📊: Gets current pool reserves
3. Proportional Calculation 🧮: Calculates fair share of both assets
4. LP Token Burning 🔥: Reduces user and total LP tokens
5. Asset Transfer 💰: Sends ETH and MyUSD to user
6. Event Emission 📡: Logs the withdrawal

Withdrawal Formula 🧮:

• ethWithdrawn = (lpTokens × ethReserve) / totalLiquidity
• tokensWithdrawn = (lpTokens × tokenReserve) / totalLiquidity
• Fair proportional distribution!

🧮 calculateXInput Function (Reverse Calculation)

function calculateXInput(uint256 yOutput, uint256 xReserves, uint256 yReserves)
    public pure returns (uint256 xInput) {
    uint256 numerator = yOutput * xReserves;   // 🧮 Output × Input Reserve
    uint256 denominator = yReserves - yOutput; // 🧮 Output Reserve - Output
    return (numerator / denominator) + 1;      // 🧮 Add 1 for rounding
}

Reverse AMM Calculation 🔄:

• Given desired output, calculates required input
• Formula: xInput = (yOutput × xReserves) / (yReserves - yOutput)
• Useful for exact output swaps!

5. 📊 Oracle Contract

Purpose: Price feed for ETH/USD conversion 💱 (the crystal ball of prices!)

📋 State Variables Deep Dive

contract Oracle {
    DEX public dexAddress; // 🔄 Reference to the DEX contract
}

Variable Explanations 📝:

• dexAddress 🔄: Points to DEX contract for price data

🏗️ Constructor Logic

constructor(address _dexAddress) {
    dexAddress = DEX(_dexAddress); // 🔗 Link to DEX contract
}

Setup Process 🚀:

• Links to the DEX contract for price feeds
• Ready to provide price data!

💱 getPrice Function (The Oracle Speaks!)

function getPrice() public view returns (uint256) {
    // 📊 Get price from DEX
    uint256 _price = dexAddress.currentPrice();

    if (_price == 0) {
        _price = 1800 ether; // 🔄 Default fallback price
    }
    return _price;
}

Price Oracle Logic 💱:

1. DEX Price Query 📊: Gets current price from DEX
2. Fallback Protection 🛡️: Uses default price if DEX has no liquidity
3. Price Return 💰: Returns ETH price in MyUSD terms

Why This Design? 🤔:

• Decentralized: Uses DEX price instead of external oracle
• Resilient: Has fallback price for edge cases
• Simple: Minimal complexity for demo purposes
• Real-world: Production would use Chainlink or similar!

6. 🎛️ RateController Contract

Purpose: Centralized rate management for borrowing and savings ⚡ (the puppet master!)

📋 State Variables Deep Dive

contract RateController {
    MyUSDEngine private i_myUSD;  // ⚙️ Reference to engine contract
    MyUSDStaking private i_staking; // 📈 Reference to staking contract
}

Variable Explanations 📝:

• i_myUSD ⚙️: Points to MyUSDEngine for borrow rate control
• i_staking 📈: Points to MyUSDStaking for savings rate control

🏗️ Constructor Logic

constructor(address _myUSD, address _staking) {
    i_myUSD = MyUSDEngine(_myUSD);     // 🔗 Link to engine
    i_staking = MyUSDStaking(_staking); // 🔗 Link to staking
}

Setup Process 🚀:

• Links to both engine and staking contracts
• Ready to control interest rates!

📈 setBorrowRate Function

function setBorrowRate(uint256 newRate) external {
    i_myUSD.setBorrowRate(newRate); // ⚙️ Update engine's borrow rate
}

Borrow Rate Control 📈:

• Direct Control: Calls engine's rate setting function
• No Restrictions: Anyone can call (in this demo!)
• Immediate Effect: Updates rate instantly

💰 setSavingsRate Function

function setSavingsRate(uint256 newRate) external {
    i_staking.setSavingsRate(newRate); // 📈 Update staking's savings rate
}

Savings Rate Control 💰:

• Direct Control: Calls staking's rate setting function
• No Restrictions: Anyone can call (in this demo!)
• Immediate Effect: Updates rate instantly

Why Separate Controller? 🤔:

• Centralization: Single point for rate management
• Flexibility: Easy to add governance or restrictions
• Separation of Concerns: Keeps rate logic separate from core contracts
• Future Upgrades: Can add complex rate algorithms later!

Production Considerations 🏭:

• Add access control (only governance can call)
• Implement rate change limits
• Add time delays for security
• Include rate validation logic

🎨 Frontend Components

Time to make it pretty! Let's explore the UI magic ✨

🎯 Core UI Components

1. 💰 TokenActions Component

Purpose: MyUSD wallet interface with transfer and swap functionality 🔄

const TokenActions = () => {
    const { data: stablecoinBalance } = useScaffoldReadContract({
        contractName: "MyUSD",
        functionName: "balanceOf",
        args: [address],
    });

    const { data: ethPrice } = useScaffoldReadContract({
        contractName: "Oracle",
        functionName: "getPrice",
    });

    const myUSDPrice = 1 / (Number(formatEther(ethPrice || 0n)) / 1800);

    return (
        <div className="absolute mt-10 right-0 bg-base-100 w-fit border-base-300 border shadow-md rounded-xl z-10">
            {/* Wallet display and action buttons */}
        </div>
    );
};

2. 🎛️ RateControls Component

Purpose: Interface for adjusting borrow and savings rates 📊 (control the money flow!)

const RateControls: React.FC = () => {
    const { data: savingsRate } = useScaffoldReadContract({
        contractName: "MyUSDStaking",
        functionName: "savingsRate",
    });

    const { data: borrowRate } = useScaffoldReadContract({
        contractName: "MyUSDEngine",
        functionName: "borrowRate",
    });

    const { writeContractAsync: writeRateControllerContractAsync } =
        useScaffoldWriteContract({
            contractName: "RateController",
        });

    const handleSaveBorrowRate = useCallback(
        async (value: string) => {
            await writeRateControllerContractAsync({
                functionName: "setBorrowRate",
                args: [BigInt(Math.round(Number(value) * 100))],
            });
        },
        [writeRateControllerContractAsync]
    );

    // UI for rate editing
};

3. 📊 UserPositionsTable Component

Purpose: Display user's collateral and debt positions 💎 (know your worth!)

4. 🏆 StakersTable Component

Purpose: Show staking positions and yields 💰 (leaderboard of earners!)

5. 📈 PriceGraph Component

Purpose: Real-time price visualization 📊 (watch the magic happen!)

6. 📉 SupplyGraph Component

Purpose: MyUSD supply metrics visualization 📊 (see the big picture!)

🚀 Getting Started

Ready to launch? Let's get this rocket ship moving! 🚀

📋 Prerequisites

# Install dependencies 📦
yarn install

# Start local blockchain ⛓️
yarn chain

# Deploy contracts 🚀
yarn deploy

# Start frontend 🎨
yarn start

🎯 Basic Usage Flow

Time to make some money! 💰

1. 💎 Add Collateral (Put your ETH to work!):

// Add ETH collateral
const { writeContractAsync } = useScaffoldWriteContract({
    contractName: "MyUSDEngine",
});

await writeContractAsync({
    functionName: "addCollateral",
    value: parseEther("1.0"), // 1 ETH
});

2. 🏭 Mint MyUSD (Create money from thin air!):

// Mint MyUSD against collateral
await writeContractAsync({
    functionName: "mintMyUSD",
    args: [parseEther("1000")], // 1000 MyUSD
});

3. 📈 Stake for Yield (Let your money work while you sleep!):

// First approve staking contract
await writeContractAsync({
    contractName: "MyUSD",
    functionName: "approve",
    args: [stakingContractAddress, parseEther("1000")],
});

// Then stake
await writeContractAsync({
    contractName: "MyUSDStaking",
    functionName: "stake",
    args: [parseEther("1000")],
});

4. 🔄 Trade on DEX (Be your own market maker!):

// Swap ETH for MyUSD
await writeContractAsync({
    contractName: "DEX",
    functionName: "swap",
    args: [parseEther("0.5")],
    value: parseEther("0.5"),
});

💻 Code Examples

Time to get our hands dirty with some code! 👨‍💻

🎢 Complete User Journey

From zero to DeFi hero in 4 easy steps! 🦸‍♂️

// 1. Connect wallet and check balances
const { address } = useAccount();
const { data: ethBalance } = useBalance({ address });
const { data: myUSDBalance } = useScaffoldReadContract({
    contractName: "MyUSD",
    functionName: "balanceOf",
    args: [address],
});

// 2. Add collateral and mint MyUSD
const addCollateralAndMint = async () => {
    try {
        // Add 2 ETH as collateral
        await writeContractAsync({
            contractName: "MyUSDEngine",
            functionName: "addCollateral",
            value: parseEther("2.0"),
        });

        // Mint 2000 MyUSD (safe ratio: 150%)
        await writeContractAsync({
            contractName: "MyUSDEngine",
            functionName: "mintMyUSD",
            args: [parseEther("2000")],
        });
    } catch (error) {
        console.error("Transaction failed:", error);
    }
};

// 3. Stake MyUSD for yield
const stakeMyUSD = async (amount: string) => {
    try {
        // Approve staking contract
        await writeContractAsync({
            contractName: "MyUSD",
            functionName: "approve",
            args: [stakingContractAddress, parseEther(amount)],
        });

        // Stake tokens
        await writeContractAsync({
            contractName: "MyUSDStaking",
            functionName: "stake",
            args: [parseEther(amount)],
        });
    } catch (error) {
        console.error("Staking failed:", error);
    }
};

// 4. Monitor position health
const { data: isLiquidatable } = useScaffoldReadContract({
    contractName: "MyUSDEngine",
    functionName: "isLiquidatable",
    args: [address],
});

const { data: currentDebt } = useScaffoldReadContract({
    contractName: "MyUSDEngine",
    functionName: "getCurrentDebtValue",
    args: [address],
});

const { data: collateralValue } = useScaffoldReadContract({
    contractName: "MyUSDEngine",
    functionName: "calculateCollateralValue",
    args: [address],
});

🚀 Advanced Integration Examples

Ready for some advanced wizardry? 🧙‍♂️

🤖 Custom Liquidation Bot

Be the hero that saves the protocol! 🦸‍♂️

const liquidationBot = async () => {
    // Monitor all positions
    const positions = await getAllPositions();

    for (const position of positions) {
        const isLiquidatable = await myUSDEngine.isLiquidatable(position.user);

        if (isLiquidatable) {
            const debtValue = await myUSDEngine.getCurrentDebtValue(
                position.user
            );
            const myUSDBalance = await myUSD.balanceOf(botAddress);

            if (myUSDBalance >= debtValue) {
                // Approve and liquidate
                await myUSD.approve(engineAddress, debtValue);
                await myUSDEngine.liquidate(position.user);
                console.log(`Liquidated position: ${position.user}`);
            }
        }
    }
};

🌾 Yield Farming Strategy

Time to farm some serious yield! 🚜💰

const yieldFarmingStrategy = async () => {
    // 1. Check current rates
    const borrowRate = await myUSDEngine.borrowRate();
    const savingsRate = await myUSDStaking.savingsRate();
    const spread = savingsRate - borrowRate;

    if (spread > 200) {
        // 2% spread minimum
        // 2. Add collateral
        await myUSDEngine.addCollateral({ value: parseEther("10") });

        // 3. Mint MyUSD at borrow rate
        await myUSDEngine.mintMyUSD(parseEther("6000"));

        // 4. Stake at savings rate
        await myUSD.approve(stakingAddress, parseEther("6000"));
        await myUSDStaking.stake(parseEther("6000"));

        console.log(`Yield farming active with ${spread / 100}% spread`);
    }
};

🛡️ Security Considerations

Safety first! Let's keep those funds SAFU! 🔒

🔐 Smart Contract Security

1. 🔄 Reentrancy Protection:

   • All external calls use ReentrancyGuard 🛡️
   • Checks-Effects-Interactions pattern followed ✅

2. 🔐 Access Control:

   • Only engine can mint MyUSD 🏭
   • Only rate controller can set rates 🎛️
   • Owner controls for emergency functions 🚨

3. 🔢 Integer Overflow Protection:

   • Solidity 0.8+ built-in protection 🛡️
   • Custom errors for gas efficiency ⛽

4. 📊 Price Oracle Security:

   • Fallback price mechanism 🔄
   • DEX-based pricing with safeguards 🛡️

🎨 Frontend Security

1. Input Validation:

const validateAmount = (amount: string): boolean => {
    const num = Number(amount);
    return num > 0 && num <= MAX_SAFE_AMOUNT && !isNaN(num);
};

2. Transaction Safety:

const safeTransactionCall = async (contractCall: () => Promise<any>) => {
    try {
        const result = await contractCall();
        await result.wait(); // Wait for confirmation
        return result;
    } catch (error) {
        console.error("Transaction failed:", error);
        throw error;
    }
};

3. State Management:
   • Real-time balance updates
   • Position health monitoring
   • Error handling and user feedback

🎯 Best Practices

1. Always check position health before operations 🏥
2. Use slippage protection for DEX trades 🛡️
3. Monitor liquidation risk continuously 👀
4. Implement proper error handling 🚨
5. Use events for off-chain monitoring 📡
6. Test all edge cases thoroughly 🧪

🎉 Conclusion

The Stablecoin Challenge demonstrates a complete DeFi protocol with:

• 💪 Robust collateralization mechanics
• 💰 Yield-bearing staking system
• 🌊 Integrated DEX for liquidity
• 🎛️ Dynamic rate management
• ⚡ Comprehensive liquidation system

This tutorial provides the foundation for understanding and extending the protocol. The modular architecture allows for easy customization and additional features. 🚀

For further development, consider:

• 🏗️ Multi-collateral support
• 🗳️ Governance mechanisms
• 📈 Advanced yield strategies
• 🌉 Cross-chain integration
• 🔮 Enhanced oracle systems

Happy coding, DeFi builders! 🎉💻✨