DSCEngine — Decentralized Stablecoin System

A decentralized, overcollateralized stablecoin system built in Solidity with Foundry. The DSC (Decentralized Stable Coin) maintains a 1 DSC = $1 USD peg, backed by WETH and WBTC collateral with real-time Chainlink price feeds.

Built as part of the Cyfrin Updraft Advanced Foundry curriculum by Apenko (Ezenwanne Ikechukwu Solomon)

---

Overview

DSCEngine is the core engine of the DSC system. It is loosely inspired by MakerDAO's DAI but with no governance, no fees, and only exogenous collateral (WETH and WBTC).

The system is designed to always remain overcollateralized — the value of all collateral must always exceed the value of all DSC in circulation.

Key properties:

• Exogenous collateral (WETH, WBTC)
• Dollar-pegged (1 DSC = $1)
• Algorithmically stable
• 200% overcollateralization required
• 10% liquidation bonus for liquidators

---

How It Works

Minting DSC

Users deposit WETH or WBTC as collateral and mint DSC against it. The system enforces a 200% collateralization ratio — to mint $100 DSC, you need at least $200 worth of collateral.

Health Factor

Every position has a health factor calculated as:

Health Factor = (Collateral Value × Liquidation Threshold / 100) × Precision / DSC Minted

If a user's health factor drops below 1e18 (1.0), their position becomes liquidatable.

Liquidation

If a user's collateral value drops and their health factor falls below 1, any external user can liquidate them — paying off their DSC debt and receiving their collateral plus a 10% bonus.

Oracle Staleness Check

Price feeds are validated using OracleLib — stale Chainlink data is rejected to protect the protocol from oracle failures.

---

Core Functions

Function	Description
depositCollateralAndMintDsc()	Deposit collateral and mint DSC in one transaction
depositCollateral()	Deposit WETH or WBTC as collateral
mintDsc()	Mint DSC against deposited collateral
burnDsc()	Burn DSC to reduce debt
redeemCollateral()	Withdraw collateral (health factor must remain above 1)
redeemCollateralForDsc()	Burn DSC and redeem collateral in one transaction
liquidate()	Liquidate an undercollateralized position and earn a 10% bonus

---

Tech Stack

• Solidity ^0.8.18
• Foundry — testing, deployment, fuzz testing
• OpenZeppelin — ReentrancyGuard, IERC20
• Chainlink — AggregatorV3Interface for ETH/USD and BTC/USD price feeds
• OracleLib — custom library for stale price feed detection

---

Security Patterns

• CEI Pattern (Checks → Effects → Interactions) applied throughout
• ReentrancyGuard on all state-changing functions
• Health factor checks before and after every position change
• Oracle staleness validation via OracleLib
• Fuzz testing to stress-test invariants with random inputs

---

Install

git clone https://github.com/Apenko/foundry-DeFi-StableCoin
cd foundry-DeFi-StableCoin
forge install

Testing

# Run all tests
forge test

# Run with verbosity
forge test -vvv

# Run fuzz tests
forge test --match-test testFuzz

Tests include unit tests, integration tests, and fuzz tests covering:

• Constructor validation
• Collateral deposit and redemption flows
• DSC minting and burning
• Health factor calculations
• Liquidation mechanics
• Oracle price feed integration

Deploy Locally (Anvil)

anvil
make deploy

Deploy to Sepolia

# Set up your keystore first
cast wallet import mykey --interactive

# Add to .env
# SEPOLIA_RPC_URL=...
# ETHERSCAN_API_KEY=...
# SENDER=0xYourWalletAddress

make deploy-sepolia

---

Project Structure

├── src/
│   ├── DSCEngine.sol                        # Core engine contract
│   ├── DecentralizedStableCoin.sol          # ERC-20 stablecoin token
│   └── libraries/
│       └── OracleLib.sol                    # Chainlink staleness check
├── script/
│   ├── DeployDsc.s.sol                      # Deployment script
│   └── HelperConfig.s.sol                   # Network config & mock setup
└── test/
    ├── fuzz/
    │   ├── Handler.t.sol                    # Fuzz handler — guides valid function calls
    │   └── Invariants.t.sol                 # Invariant tests — protocol-level guarantees
    ├── mock/
    │   ├── ERC20Mock.sol                    # Mock ERC-20 for testing
    │   └── MockV3Aggregator.sol             # Mock Chainlink price feed
    └── unit/
        ├── DecentralizedStableCoinTest.t.sol # Unit tests for DSC token
        └── DSCEngineTest.t.sol              # Unit tests for DSCEngine

---

Author

Ezenwanne Ikechukwu Solomon (Apenko)

• GitHub: github.com/Apenko
• Twitter/X: @Apenko2
• LinkedIn: linkedin.com/in/ikechukwu-ezenwanne-880a80345

---

Acknowledgements

• Cyfrin Updraft — Advanced Foundry curriculum by Patrick Collins
• MakerDAO — inspiration for the DSS system