DSC Stablecoin - Complete Interactive Guide

🪙 What is a Stablecoin?

Let's start from the very basics

The Piggy Bank Analogy

Imagine you have a special piggy bank. For every $2 worth of toys you put in, you get a special golden coin worth $1.

📦 You put in: $2 worth of toys (WETH/WBTC)

🪙 You get: $1 golden coin (DSC)

Why $2 for $1? Because even if your toys lose some value, there's still enough to back your golden coin!

The Three Properties of Our Stablecoin

Property	What It Means	Real World Example
🌍 Exogenous	Backed by EXTERNAL assets (WETH, WBTC)	Like a gold-backed currency - the gold exists outside the money system
🤖 Algorithmic	Rules-based, no human decisions	Like a vending machine - put in money, get product, no cashier needed
💵 USD Pegged	1 DSC = $1 always	Like how arcade tokens are always worth the same in that arcade

Why 200% Collateralization?

👤

You deposit

$2000

worth of ETH

→ Protocol holds it

🏦

DSCEngine

$2000

collateral locked

→ You can mint

🪙

You receive

$1000

DSC tokens

Why not just 100%?

Imagine ETH price drops 30%. If you only had 100% backing:

❌ Your $1000 collateral is now worth $700 → Can't back $1000 DSC!

With 200% backing:

✅ Your $2000 collateral is now worth $1400 → Still backs $1000 DSC!

❤️ Understanding Health Factor

The most important number in DeFi lending

What is Health Factor?

Health Factor Formula:

(Collateral Value × 50%)

Total DSC Minted

The Safety Score

Think of Health Factor like a safety score for your loan:

Above 1.0 = You're safe! 😊
Exactly 1.0 = Danger zone! 😰
Below 1.0 = You can be liquidated! 😱

Interactive Health Bar (adjust values below)

1.5

🧮 Interactive Health Factor Calculator

ETH Deposited:

ETH Price (USD):

DSC Minted:

Your Health Factor:

2.0

✅ Safe - You cannot be liquidated

📝 Step-by-Step Calculation:

1 Collateral Value = 1 ETH × $2000 = $2000

2 Adjusted Collateral = $2000 × 50% = $1000

3 Health Factor = $1000 ÷ $500 = 2.0

⚡ How Liquidation Works

The Bounty Hunter Analogy

When your safety score drops below 1.0, you become a "wanted" person. Anyone can be a bounty hunter!

🤠 Bounty Hunter (Liquidator): "I'll pay off some of your debt!"

💰 Reward: They get your collateral + 10% bonus!

This keeps the whole system healthy because bad positions get cleaned up.

1

Bob's Position Goes Underwater

Bob deposited 1 ETH at $2000, minted $1000 DSC. ETH crashes to $1500.

Health Factor: ($1500 × 50%) ÷ $1000 = 0.75 ❌

2

Alice Sees an Opportunity

Alice has $500 DSC and wants to liquidate Bob's position.

3

The Math

Alice pays: $500 DSC

Alice receives: $500 worth of ETH + 10% bonus = $550 worth of ETH

Alice profit: $50! 🎉

⚡ Liquidation Profit Calculator

DSC to Pay Off:

Current ETH Price:

You pay: $500 DSC

You receive: 0.367 ETH ($550)

+$50

That's your 10% liquidation bonus! 🎉

🏗️ Protocol Architecture

How all the pieces fit together

System Overview

👤

User

Deposits collateral Mints/Burns DSC

↔️

⚙️

DSCEngine

Core Logic ~700 lines

↔️

🪙

DSC Token

ERC20 ~60 lines

🔗

Chainlink ETH/USD

🔗

Chainlink BTC/USD

💎

WETH Collateral

🟠

WBTC Collateral

DSCEngine.sol - The Brain

Handles all collateral management, minting, burning, and liquidations

Key State Variables

            // Who deposited what
            mapping(address
            user => mapping(address
            token => uint256))
            private s_collateralDeposited;

            // How much DSC each user minted (their debt)
            mapping(address
            user => uint256)
            private s_DSCMinted;

            // Token → Chainlink Price Feed
            mapping(address
            token => address priceFeed)
            private s_priceFeeds;
          

Key Constants

50%

Liquidation Threshold

10%

Liquidation Bonus

1e18

Min Health Factor

1e18

Precision

Main Functions

depositCollateral()

Deposit WETH or WBTC as collateral

              function
              depositCollateral(address
              token, uint256 amount)
              public {
              s_collateralDeposited[msg.sender][token] += amount;
              // Transfer tokens from user to this contract
              IERC20(token).transferFrom(msg.sender, address(this), amount); }
            

mintDSC()

Mint DSC against your collateral

              function
              mintDSC(uint256
              amount) public {
              s_DSCMinted[msg.sender] += amount;
              _revertIfHealthFactorIsBroken(msg.sender);
              // Critical check! i_dsc.mint(msg.sender, amount); }
            

liquidate()

Liquidate unhealthy positions and earn 10% bonus

              function
              liquidate(address
              collateral, address user,
              uint256 debtToCover)
              public {
              // 1. Check user is actually liquidatable
              require(_healthFactor(user) < MIN_HEALTH_FACTOR);

              // 2. Calculate collateral to take (debt + 10% bonus)
              uint256 tokenAmount =
              getTokenAmountFromUsd(collateral,
              debtToCover); uint256 bonus =
              tokenAmount * 10 /
              100;

              // 3. Take collateral, burn DSC
              _redeemCollateral(user, msg.sender,
              collateral, tokenAmount + bonus);
              _burnDSC(debtToCover, user,
              msg.sender); }
            

DecentralizedStableCoin.sol - The Token

Simple ERC20 token that only DSCEngine can mint/burn

Why is it so simple?

The token itself doesn't need to be smart. It's just a "receipt" for your position.

All the intelligence is in DSCEngine - the token just says "DSCEngine is my boss".

            contract
            DecentralizedStableCoin
            is ERC20Burnable, Ownable {

            // Only the owner (DSCEngine) can mint new tokens
            function
            mint(address
            to, uint256 amount)
            external
            onlyOwner
            returns (bool) { _mint(to, amount);
            return
            true; }

            // Only the owner (DSCEngine) can burn tokens
            function
            burn(uint256
            amount) public
            override
            onlyOwner {
            super.burn(amount); } }
          

OracleLib.sol - The Price Guardian

Protects against stale/manipulated price data

The Newspaper Analogy

Imagine you only trust today's newspaper for stock prices. If someone gives you a 3-day old newspaper and says "buy!", you'd refuse.

OracleLib does the same - it checks if the price data is "fresh" (less than 3 hours old).

Why is this critical?

!

Stale Price Attack

Real ETH: $1000 (crashed!)

Stale Oracle: $2000 (old data)

Attacker deposits 1 ETH → Protocol thinks $2000 → Mints $1000 DSC

Protocol is now UNDERCOLLATERALIZED! 💀

            function
            staleCheckLatestRoundData(AggregatorV3Interface feed) public
            view { (,, ,
            uint256 updatedAt,) = feed.latestRoundData();

            uint256 secondsSince = block.timestamp -
            updatedAt;

            // If price is older than 3 hours, REVERT!
            if (secondsSince >
            3 hours) {
            revert OracleLib__StalePrice(); } }
          

🧪 Testing Strategy

How we ensure the protocol is secure

Testing Pyramid

Invariant

Fuzz Tests

Unit Tests (29 tests)

Invariant Testing - The Ultimate Test

The "No Matter What" Rule

An invariant is something that must ALWAYS be true, no matter what users do.

Our invariant: "Total collateral value ≥ Total DSC minted"

We let the fuzzer do THOUSANDS of random actions, then check if this rule still holds!

          function
          invariant_protocolMustHaveMoreValueThanTotalSupply() public {
          uint256 totalSupply = dsc.totalSupply(); uint256 wethValue = dscEngine.getUSDValue(weth, weth.balanceOf(address(dscEngine))); uint256 wbtcValue =
          dscEngine.getUSDValue(wbtc, wbtc.balanceOf(address(dscEngine)));

          // THE INVARIANT: Protocol must always be solvent!
          assert(wethValue + wbtcValue >=
          totalSupply); }
        

1000

Fuzz Runs

128,000

Total Calls

0

Reverts

31

Tests Passed

Handler Pattern - Making Fuzz Tests Smart

The Helpful Assistant

Without a Handler, the fuzzer calls random functions with random inputs - most calls fail!

The Handler is like a helpful assistant that:

Mints tokens before depositing
Approves spending before transfers
Bounds values to valid ranges

Without Handler vs With Handler

❌ Without Handler

Fuzzer: "deposit 1000 WETH!"

Contract: "You don't have any WETH..."

REVERT!

✅ With Handler

Handler: "Let me mint WETH first..."

Handler: "And approve spending..."

Handler: "Now deposit!"

SUCCESS!

🔢 Understanding Decimal Precision

The math behind Solidity's number system

Why 1e18? The Precision Problem

The Decimal Dilemma

Solidity doesn't have decimals! You can't write 1.5 ETH.

Solution: Use REALLY big numbers and pretend the last 18 digits are decimals.

1 ETH = 1,000,000,000,000,000,000 wei (that's 1 followed by 18 zeros = 1e18)

1e18

ETH Precision

1e8

Chainlink Price

1e10

Additional Precision

1e18

DSC Token

The Precision Ladder

1 Chainlink returns: 200000000000 (ETH = $2000, 8 decimals)

2 Multiply by 1e10: 2000000000000000000000 (now 18 decimals)

3 User has 1 ETH = 1000000000000000000 (1e18 wei)

4 USD Value = (price × amount) / 1e18 = $2000

          // PRECISION CONSTANTS
          uint256
          private constant PRECISION =
          1e18;
          // 18 decimals for math
          uint256
          private constant
          ADDITIONAL_FEED_PRECISION = 1e10;
          // 8→18 decimals
          uint256
          private constant FEED_PRECISION =
          1e8;
          // Chainlink uses 8

          // Converting ETH amount to USD value
          function
          _getUsdValue(address
          token, uint256 amount)
          private view returns (uint256) { (, int256 price,,,) = priceFeed.latestRoundData();

          // price = 200000000000 ($2000 with 8 decimals)
          // amount = 1000000000000000000 (1 ETH with 18 decimals)

          return ((uint256(price) * ADDITIONAL_FEED_PRECISION) * amount) / PRECISION;
          // ((200000000000 * 1e10) * 1e18) / 1e18
          // = 2000e18 (which represents $2000)
          }
        

Reverse Conversion: USD to Token Amount

Getting ETH from USD

If I want $500 worth of ETH and ETH is $2000, how much ETH do I get?

Simple: $500 ÷ $2000 = 0.25 ETH

In code: (500e18 × 1e18) ÷ (2000e8 × 1e10) = 0.25e18 = 250000000000000000 wei

          // USD to Token conversion (used in liquidation)
          function
          getTokenAmountFromUsd(address
          token, uint256 usdAmountInWei)
          public view returns (uint256) { (, int256 price,,,) = priceFeed.latestRoundData();

          // usdAmountInWei = 500e18 ($500)
          // price = 200000000000 ($2000)

          return (usdAmountInWei * PRECISION) /
          (uint256(price) *
          ADDITIONAL_FEED_PRECISION);
          // (500e18 * 1e18) / (200000000000 * 1e10)
          // = 500e36 / 2000e18
          // = 0.25e18 = 250000000000000000 wei = 0.25 ETH
          }
        

🚶 Complete User Journey

Follow the entire flow from start to finish

Step 1: Deposit Collateral

👤

Alice

Has 2 WETH

→ approve()

💎

WETH

ERC20

→ depositCollateral()

⚙️

DSCEngine

Holds collateral

1a

User approves DSCEngine to spend their WETH

                weth.approve(address(dscEngine), 2e18);
                // 2 WETH
              

1b

User calls depositCollateral

dscEngine.depositCollateral(address(weth), 2e18);

1c

State Changes

s_collateralDeposited[alice][weth]: 0 → 2e18

weth.balanceOf(alice): 2e18 → 0

weth.balanceOf(dscEngine): 0 → 2e18

Step 2: Mint DSC (Borrow)

👤

Alice

Has collateral

→ mintDSC()

⚙️

DSCEngine

Checks health

→ mint()

🪙

DSC Token

Creates tokens

2a

User wants to mint DSC

dscEngine.mintDSC(1500e18); // Mint $1500 DSC

2b

Engine calculates health factor

1 Collateral: 2 ETH × $2000 = $4000

2 Adjusted: $4000 × 50% = $2000

3 Health: $2000 ÷ $1500 = 1.33 ✓

2c

State Changes

s_DSCMinted[alice]: 0 → 1500e18

dsc.balanceOf(alice): 0 → 1500e18

dsc.totalSupply(): 0 → 1500e18

Step 3: Use DSC (In Real World)

What can Alice do with DSC?

💱 Trade on DEXs (Uniswap, Curve)
🏦 Lend on other protocols for yield
💰 Use as stable payment
🔄 Provide liquidity in LP pools

The DSC is REAL money on the blockchain!

Step 4: Burn DSC & Withdraw (Exit Position)

👤

Alice

Wants ETH back

→ burnDSC()

🔥

Burn DSC

Reduce debt

→ redeemCollateral()

💎

Get WETH

Back to Alice

4a

Alice approves DSCEngine to burn her DSC

dsc.approve(address(dscEngine), 1500e18);

4b

Burn DSC to reduce debt

                dscEngine.burnDSC(1500e18);
                // s_DSCMinted[alice]: 1500e18 → 0
                // DSC tokens are destroyed forever
              

4c

Redeem collateral

                dscEngine.redeemCollateral(address(weth), 2e18);
                // Alice gets her 2 WETH back!
              

The Combo Function

There's also redeemCollateralForDSC() that does burn + redeem in one transaction!

            dscEngine.redeemCollateralForDSC(weth,
            2e18,
            1500e18);
            // Burns 1500 DSC AND withdraws 2 WETH - saves gas!
          

💀 Liquidation Deep Dive

Complete flow of a liquidation event

Scenario: ETH Crashes, Bob Gets Liquidated

0

Initial State (Bob is Healthy)

Bob deposited: 1 ETH @ $2000

Bob minted: $800 DSC

Health Factor: ($2000 × 50%) ÷ $800 = 1.25 ✓

1

ETH Price Crashes! 📉

ETH drops from $2000 → $1400

Bob's collateral value: 1 ETH × $1400 = $1400

New Health Factor: ($1400 × 50%) ÷ $800 = 0.875 ✗

⚠️ Bob is now LIQUIDATABLE!

2

Alice Spots the Opportunity 🔍

Alice has $400 DSC and wants to liquidate Bob

                // Alice checks Bob's health factor
                uint256 healthFactor = dscEngine.getHealthFactor(bob);
                // Returns 0.875e18 - BELOW 1e18, can be liquidated!
              

3

The Liquidation Math

1 Alice pays: $400 DSC (debtToCover)

2 Base ETH: $400 ÷ $1400 = 0.2857 ETH

3 Bonus (10%): 0.2857 × 0.10 = 0.0286 ETH

4 Total: 0.2857 + 0.0286 = 0.3143 ETH

5 Value: 0.3143 × $1400 = $440

✓ Alice profit: $440 - $400 = $40! 🎉

4

Execute Liquidation

                // Alice approves DSCEngine to take her DSC
                dsc.approve(address(dscEngine), 400e18);

                // Alice liquidates Bob
                dscEngine.liquidate(
                address(weth),
                // collateral to take bob,
                // user to liquidate
                400e18
                // debt to cover
                );
              

5

Final State Changes

Variable	Before	After
Bob's Collateral	1 ETH	0.6857 ETH
Bob's Debt	$800 DSC	$400 DSC
Bob's Health Factor	0.875	1.2 ✓
Alice's DSC	$400	$0
Alice's ETH	0	0.3143 ETH ($440)

🚨 Error Handling

Understanding all custom errors

DSCEngine Custom Errors

Error	When It Happens	Fix
`NeedsMoreThanZero`	Trying to deposit/mint/burn 0 amount	Pass amount > 0
`TokenNotAllowed`	Using unsupported collateral token	Only use WETH or WBTC
`TransferFailed`	ERC20 transfer didn't work	Check token approval/balance
`BreaksHealthFactor`	Action would make health factor < 1	Deposit more or mint less
`MintFailed`	DSC token mint returned false	Check DSCEngine is owner
`HealthFactorOk`	Trying to liquidate healthy user	Can only liquidate HF < 1
`HealthFactorNotImproved`	Liquidation didn't help the user	Cover more debt

          // All custom errors defined at the top of DSCEngine
          error
          DSCEngine__TokenAddressesAndPriceFeedAddressesAmountsDontMatch();
          error DSCEngine__NeedsMoreThanZero();
          error DSCEngine__TokenNotAllowed(address
          token);
          error DSCEngine__TransferFailed();
          error DSCEngine__BreaksHealthFactor(uint256
          healthFactorValue);
          error DSCEngine__MintFailed();
          error DSCEngine__HealthFactorOk();
          error
          DSCEngine__HealthFactorNotImproved();
        

OracleLib Error

The Single Error That Freezes Everything

OracleLib__StalePrice()

This error is thrown when:

updatedAt == 0 - Price was never set
answeredInRound < roundId - Oracle is behind
block.timestamp - updatedAt > 3 hours - Price too old

When this happens, the ENTIRE protocol freezes. No deposits, mints, or redeems. Safety first!

⚖️ Stablecoin Comparison

How DSC compares to other stablecoins

Feature	DSC (Ours)	DAI	USDT	USDC
Type	Crypto-backed	Crypto-backed	Fiat-backed	Fiat-backed
Collateral	WETH, WBTC	ETH, WBTC, etc.	USD in bank	USD in bank
Decentralized	✅ Fully	✅ Mostly	❌ No	❌ No
Can be frozen	❌ No	❌ No	✅ Yes	✅ Yes
Overcollateralized	✅ 200%	✅ 150%+	100% (claimed)	100% (audited)
Trust Required	Code only	Code + DAO	Tether company	Circle company
Transparency	100% on-chain	100% on-chain	Quarterly reports	Monthly attestations

Why Choose DSC?

Pros: Fully trustless, censorship-resistant, transparent, overcollateralized

Cons: Capital inefficient (need $2 to get $1), volatile collateral risk

It's a trade-off: Do you trust code or companies?

🚀 Deployment Flow

How the contracts get deployed

Deployment Order Matters!

1

Deploy DecentralizedStableCoin

                DecentralizedStableCoin dsc =
                new DecentralizedStableCoin();
                // At this point, deployer is the owner
              

2

Deploy DSCEngine with DSC address

                address[]
                memory tokens = [wethAddress,
                wbtcAddress]; address[]
                memory priceFeeds = [ethUsdFeed,
                btcUsdFeed]; DSCEngine engine =
                new DSCEngine(tokens, priceFeeds,
                address(dsc));
              

3

Transfer DSC ownership to Engine

                dsc.transferOwnership(address(engine));
                // Now ONLY DSCEngine can mint/burn DSC!
              

After Deployment

🔗

ETH/USD Feed

→

⚙️

DSCEngine

OWNER of DSC

→

🪙

DSC Token

Owned by Engine

📖 Complete Function Reference

Every function in DSCEngine explained

External Functions (User Calls These)

depositCollateralAndMintDSC()

Combo: Deposit + Mint in one transaction

Gas Efficient: Saves ~21000 gas vs two separate calls

            function
            depositCollateralAndMintDSC(
            address tokenCollateralAddress,
            uint256 amountCollateral,
            uint256 amountDscToMint )
            external {
            depositCollateral(tokenCollateralAddress, amountCollateral);
            mintDSC(amountDscToMint); }
          

redeemCollateralForDSC()

Combo: Burn DSC + Withdraw collateral in one transaction

            function
            redeemCollateralForDSC(
            address tokenCollateralAddress,
            uint256 amountCollateral,
            uint256 amountDscToBurn )
            external {
            _burnDSC(amountDscToBurn, msg.sender,
            msg.sender);
            _redeemCollateral(tokenCollateralAddress, amountCollateral, msg.sender, msg.sender);
            _revertIfHealthFactorIsBroken(msg.sender);
            // Check AFTER both operations
            }
          

View Functions (Read-Only)

getAccountInformation()

Get debt + collateral value

getHealthFactor()

Get user's health factor

getUsdValue()

Convert token → USD

getTokenAmountFromUsd()

Convert USD → token

getCollateralTokens()

Get allowed tokens list

getCollateralBalanceOfUser()

Get user's collateral amount

Why are these important?

Frontend apps call these to show users their positions. Liquidation bots call these to find liquidatable users!

🔄 User Flow Diagrams

Visual step-by-step flows for every user action

Flow 1: Opening a Position (Deposit + Mint)

👤

User

Has WETH/WBTC

→ approve()

✅

Approve

Allow DSCEngine to spend tokens

→ depositCollateralAndMintDSC()

⚙️

DSCEngine

Validates & processes

→ transferFrom()

💎

WETH/WBTC

Tokens transferred

⚙️

DSCEngine

Updates state

→ mint()

🪙

DSC Token

DSC minted to user

→ Balance Updated

🎉

Position Open!

User has DSC + collateral locked

📊 State Changes

s_collateralDeposited[user]

0 → 2e18

s_DSCMinted[user]

0 → 1000e18

User DSC Balance

0 → 1000e18

Health Factor

∞ → 2.0 ✓

Flow 2: Adding Collateral Only

👤

User

Wants to add collateral

→ approve()

✅

Approve

Allow spending

→ depositCollateral()

⚙️

DSCEngine

Updates mapping

→ transferFrom()

📈

Health ↑

HF improves!

Why Add Collateral Without Minting?

Users might want to:

🛡️ Improve health factor - Make position safer
📊 Prepare for minting - Deposit now, mint later
💰 Lower liquidation risk - Buffer against price drops

Flow 3: Minting More DSC

👤

User

Has collateral deposited

→ mintDSC()

⚙️

DSCEngine

Check health factor

→ _healthFactor()

⚖️

Check

HF >= 1.0 after mint?

↓ Yes

🪙

Mint Success

DSC minted!

↓ No

❌

Revert

BreaksHealthFactor

Flow 4: Closing Position (Burn + Redeem)

👤

User

Wants ETH back

→ approve(DSC)

✅

Approve DSC

Allow burn

→ redeemCollateralForDSC()

🔥

Burn DSC

Debt reduced

→ _redeemCollateral()

💎

Get Collateral

WETH returned!

📊 State Changes (Full Exit)

s_collateralDeposited[user]

2e18 → 0

s_DSCMinted[user]

1000e18 → 0

DSC Total Supply

1000e18 → 0

Position Status

Active → Closed ✓

Flow 5: Liquidation Flow

😰

User A

HF < 1.0 (Liquidatable)

⇄ Monitored by

🤠

Liquidator

Bot or user

→ liquidate()

⚙️

DSCEngine

Verify & execute

💰

Pays DSC

Covers debt

→ +10% bonus

🎁

Receives

Collateral + bonus

→ debt reduced

😊

User A

HF improved!

💰 Liquidation Math Visualization

Debt Covered

$500 DSC

→

Base Collateral

0.333 ETH

+

10% Bonus

0.033 ETH

=

Total Received

0.366 ETH

💵 Profit: $50 (10% of $500)

🏗️ Code Architecture Deep Dive

Understanding the smart contract structure and design patterns

Contract Inheritance Diagram

📦

OpenZeppelin

External Library

↓

🔷

ERC20Burnable

Base Contract

🔷

Ownable

Base Contract

🔷

ReentrancyGuard

Base Contract

↓

🪙

DecentralizedStableCoin

DSC Token (~60 lines)

⚙️

DSCEngine

Core Engine (~700 lines)

Why This Architecture?

Separation of Concerns: The token (DSC) is simple - it just moves value. The engine (DSCEngine) is smart - it handles all the complex logic.

This is like a bank: The vault (DSC) holds the money, but the bank manager (DSCEngine) decides who can deposit/withdraw.

DSCEngine State Variables Map

🔒 Immutable (Set Once)

i_dsc DSC token contract address

📊 Mappings (User Data)

s_collateralDeposited user → token → amount

s_DSCMinted user → debt amount

s_priceFeeds token → price feed

📋 Arrays (Configuration)

s_collateralTokens List of allowed tokens [WETH, WBTC]

Function Categories

📥 Deposit Functions

depositCollateral() Deposit single token

depositCollateralAndMintDSC() Deposit + mint combo

🪙 Mint Functions

mintDSC() Mint against collateral

📤 Redeem Functions

redeemCollateral() Withdraw collateral

redeemCollateralForDSC() Burn + withdraw combo

🔥 Burn Functions

burnDSC() Reduce debt

⚡ Liquidation

liquidate() Liquidate unhealthy user

👁️ View Functions

getAccountInformation() Debt + collateral

getHealthFactor() User's health score

getUSDValue() Token → USD

getTokenAmountFromUsd() USD → token

Security Patterns Used

🛡️

ReentrancyGuard

Prevents reentrancy attacks on external calls

nonReentrant modifier

✅

Checks-Effects-Interactions

State changes before external calls

Update mapping → Transfer

🔒

Access Control

Only DSCEngine can mint/burn DSC

onlyOwner modifier

📊

Health Factor Checks

All operations validate position health

_revertIfHealthFactorIsBroken()

⏱️

Oracle Staleness

Rejects stale price data (>3 hours)

OracleLib.check()

🚫

Input Validation

Zero address, zero amount checks

moreThanZero modifier

Modifier Chain Visualization

depositCollateral()

→

✓ moreThanZero

→

✓ isZeroAddress

→

✓ isAllowedToken

→

✓ nonReentrant

→

Execute

          // Each modifier acts as a gatekeeper
          modifier
          moreThanZero(uint256
          _amount) { if (_amount <= 0) {
          revert
          DSCEngine__AmountMustBeMoreThanZero(); } _;
          // Continue to next modifier or function body
          }
        

🧠 Core Concepts Explained

Deep dives into the fundamental mechanisms

Overcollateralization Visualized

100% Collateralization (DANGEROUS)

$1000 ETH

$1000 DSC

❌ ETH drops 10% → Position underwater!

150% Collateralization (DAI Standard)

$1500 ETH

$1000 DSC

⚠️ ETH can drop 33% before liquidation

200% Collateralization (DSC Standard)

$2000 ETH

$1000 DSC

✅ ETH can drop 50% before liquidation

The Safety Buffer

Think of overcollateralization like a down payment on a house:

0% down (100% collateral): If house value drops, bank loses money
20% down (125% collateral): Small buffer for price drops
50% down (200% collateral): Huge buffer - very safe for lender

DSC requires 200% because crypto is volatile!

Health Factor Zones

🟢 Safe Zone HF ≥ 1.5

Your position is very healthy

✅ Can mint more DSC
✅ Can withdraw collateral
✅ Safe from liquidation

🟡 Caution Zone 1.0 ≤ HF < 1.5

Your position is at risk

⚠️ Cannot mint more DSC
⚠️ Cannot withdraw collateral
✅ Still safe from liquidation

🔴 Liquidation Zone HF < 1.0

Your position can be liquidated!

❌ Cannot mint or withdraw
❌ Anyone can liquidate you
💡 Add collateral or burn DSC to escape

Danger
0 - 1.0

Caution
1.0 - 1.5

Safe
1.5+

👤 You are here (HF: 1.5)

Liquidation Incentive Mechanics

👀

1. Spot Opportunity

Liquidator finds user with HF < 1.0

→

💰

2. Pay Debt

Pay $500 DSC to cover user's debt

→

🎁

3. Get Bonus

Receive $550 worth of collateral

→

📈

4. Profit!

Instant $50 profit (10%)

Liquidation Profit Table

Debt Covered	10% Bonus	Your Profit
$100 DSC	$10	$10
$500 DSC	$50	$50
$1,000 DSC	$100	$100
$5,000 DSC	$500	$500

Price Oracle Flow

⛓️

Ethereum Network

↓

🔗

Chainlink Nodes

Multiple independent nodes

↓

📊

Aggregator Contract

Aggregates prices from nodes

↓

✅

OracleLib Check

Fresh? (< 3 hours)

↓

⚙️

DSCEngine

Uses price for calculations

Why Chainlink?

Chainlink is a decentralized oracle network:

🔢 Multiple data sources - Not reliant on one exchange
🌐 Decentralized nodes - No single point of failure
🔒 On-chain verification - Prices are cryptographically signed
⏱️ Regular updates - Prices refresh every ~1 hour for ETH/USD

Token Economics

🖨️

Minting

DSC is created when users deposit collateral

Collateral × 50% = Max Mint

↔️

🔄

Circulation

DSC trades at $1 in the market

Total Supply = Σ All Minted

↔️

🔥

Burning

DSC is destroyed when debt is repaid

Burn DSC → Unlock Collateral

Supply Dynamics

📈 Supply Expansion

When ETH price rises, users can mint more DSC

More collateral value → More DSC supply

📉 Supply Contraction

When ETH price drops, users burn DSC to avoid liquidation

Less collateral value → Less DSC supply

⚖️ Equilibrium

DSC maintains $1 peg through overcollateralization

Always backed by more collateral than DSC issued

📋 Quick Reference

Everything at a glance

Key Formulas

Formula	Calculation	Example
Health Factor	(Collateral × 50%) ÷ Debt	($2000 × 50%) ÷ $500 = 2.0
Max Mintable DSC	Collateral Value × 50%	$2000 × 50% = $1000 DSC
Liquidation Bonus	Debt Covered × 10%	$500 × 10% = $50
USD to Token	USD Amount ÷ Token Price	$500 ÷ $1500 = 0.333 ETH

Contract Addresses (Testnet)

Deploy on Sepolia or Anvil local network

          // Run deployment
          forge script script/DeployDSCEngine.s.sol --rpc-url $RPC_URL
          --broadcast

          // Run tests
          forge test -vvv

          // Run invariant tests
          forge test --mt invariant -vvv
        

Decentralized Stablecoin

🪙 What is a Stablecoin?

The Piggy Bank Analogy

The Three Properties of Our Stablecoin

Why 200% Collateralization?

Why not just 100%?

❤️ Understanding Health Factor

What is Health Factor?

The Safety Score

🧮 Interactive Health Factor Calculator

📝 Step-by-Step Calculation:

⚡ How Liquidation Works

The Bounty Hunter Analogy

Bob's Position Goes Underwater

Alice Sees an Opportunity

The Math

⚡ Liquidation Profit Calculator

🏗️ Protocol Architecture

System Overview

DSCEngine.sol - The Brain

Key State Variables

Key Constants

Main Functions

depositCollateral()

mintDSC()

liquidate()

DecentralizedStableCoin.sol - The Token

Why is it so simple?

OracleLib.sol - The Price Guardian

The Newspaper Analogy

Why is this critical?

Stale Price Attack

🧪 Testing Strategy

Testing Pyramid

Invariant Testing - The Ultimate Test

The "No Matter What" Rule

Handler Pattern - Making Fuzz Tests Smart

The Helpful Assistant

Without Handler vs With Handler

❌ Without Handler

✅ With Handler

🔢 Understanding Decimal Precision

Why 1e18? The Precision Problem

The Decimal Dilemma

The Precision Ladder

Reverse Conversion: USD to Token Amount

Getting ETH from USD

🚶 Complete User Journey

Step 1: Deposit Collateral

User approves DSCEngine to spend their WETH

User calls depositCollateral

State Changes

Step 2: Mint DSC (Borrow)

User wants to mint DSC

Engine calculates health factor

State Changes

Step 3: Use DSC (In Real World)

What can Alice do with DSC?

Step 4: Burn DSC & Withdraw (Exit Position)

Alice approves DSCEngine to burn her DSC

Burn DSC to reduce debt

Redeem collateral

The Combo Function

💀 Liquidation Deep Dive

Scenario: ETH Crashes, Bob Gets Liquidated

Initial State (Bob is Healthy)

ETH Price Crashes! 📉

Alice Spots the Opportunity 🔍

The Liquidation Math

Execute Liquidation

Final State Changes

🚨 Error Handling

DSCEngine Custom Errors

OracleLib Error

The Single Error That Freezes Everything

⚖️ Stablecoin Comparison

Why Choose DSC?

🚀 Deployment Flow

Deployment Order Matters!

Deploy DecentralizedStableCoin