A DeFi protocol implementing an algorithmic stablecoin system designed to maintain a 1:1 peg with the US Dollar through overcollateralization and algorithmic stability mechanisms.
The DSC protocol is built on Ethereum using Solidity smart contracts and follows the principles of:
- Relative Stability: Anchored/pegged to $1.00 USD
- Exogenous Collateral: Backed by crypto assets (wETH, wBTC)
- Algorithmic Minting: Decentralized minting mechanism
- Overcollateralization: Always maintains collateral value > minted DSC value
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ DSC Token │ │ DSC Engine │ │ Oracle Lib │
│ (ERC20) │◄──►│ (Core Logic) │◄──►│ (Price Feeds) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ User Wallets │ │ Collateral │ │ Chainlink │
│ │ │ (wETH/wBTC) │ │ Price Feeds │
└─────────────────┘ └─────────────────┘ └─────────────────┘
DecentralizedStableCoin.sol: ERC20 stablecoin token with mint/burn capabilitiesDSCEngine.sol: Core protocol logic handling collateral, minting, and liquidationOracleLib.sol: Price feed validation and stale data protection
- Overcollateralization: 50% liquidation threshold
- Liquidation System: 10% bonus for liquidators
- Price Feed Integration: Chainlink with stale data protection
- CEI Pattern: Check-Effects-Interactions for security
This project implements a comprehensive multi-layered testing approach:
forge test --match-contract DSCEngineTest- Tests individual functions and edge cases
- AAA pattern (Arrange, Act, Assert)
- Covers all core functionality
forge test --match-contract Invariants- Handler-based testing for complex state interactions
- Bounded random inputs with realistic constraints
- State tracking across operations
Core protocol invariants that must always hold:
- Protocol Solvency: Total collateral value ≥ Total DSC supply
- Getter Stability: View functions never revert
- Health Factor Bounds: Users maintain minimum health factors
- Unrestricted random input generation
- Discovery of unexpected edge cases
- Validation of core protocol properties
- Foundry
- Node.js (for dependencies)
# Clone the repository
git clone <repository-url>
cd foundry-defi-stablecoin
# Install dependencies
forge install
# Build contracts
forge build# Run all tests
forge test
# Run with verbose output
forge test -vvv
# Run specific test file
forge test --match-contract DSCEngineTest
# Run fuzz tests
forge test --match-contract Invariants
# Generate gas report
forge test --gas-report# Deploy to local network
forge script script/DeployDSC.s.sol --rpc-url <rpc-url> --private-key <private-key> --broadcast- Reentrancy Protection: All external calls use
nonReentrantmodifier - Price Feed Security: 3-hour timeout for stale data detection
- Access Control: Owner-only minting/burning with proper ownership transfer
- Health Factor Protection: Automatic reversion on health factor violations
- Input Validation: Comprehensive checks for amounts, addresses, and allowances
| Parameter | Value | Description |
|---|---|---|
| Liquidation Threshold | 50% | Minimum collateralization ratio |
| Liquidation Bonus | 10% | Bonus for liquidators |
| Min Health Factor | 1.0 | Minimum health factor before liquidation |
| Price Feed Timeout | 3 hours | Stale data detection window |
- Ethereum Mainnet
- Ethereum Testnets (Goerli, Sepolia)
- Local development (Anvil)
For detailed technical documentation, see PROJECT_DOCUMENTATION.md
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
This project is licensed under the MIT License.
This is experimental software. Use at your own risk. The authors are not responsible for any financial losses incurred through the use of this protocol.
- Additional collateral types
- Governance integration
- Flash loan support
- Advanced liquidation mechanisms
- Cross-chain deployment