EURxy Stablecoin Experiment

A decentralized Euro-pegged stablecoin implementation inspired by MakerDAO's DAI system. This project implements a fully collateralized stablecoin with dynamic stability mechanisms, liquidation protocols, and multi-collateral support, maintaining a stable 1:1 peg with the Euro.

Project Status

✅ Smart Contract Implementation: Core contracts completed
✅ Docker Environment: Testing infrastructure ready
✅ Documentation: Comprehensive system documentation
⚠️ Connectivity Warning: Environment requires internet access for Solidity compiler
⏳ Testing: Unit tests need network access to run

System Implementation Summary

The EURxy stablecoin system is built on four core pillars:

1. Over-collateralization: All EURxy tokens are backed by cryptocurrency collateral worth at least 150% of the minted value in EUR.
2. Price Stability: EUR peg is maintained through multiple mechanisms including liquidations, stability fees, and active collateral management.
3. Decentralized Governance: Access control and system parameters can be adjusted through role-based management.
4. Risk Management: Tiered collateral types, liquidation penalties, and dynamic stability fees protect the system against market volatility.

Overview

EURxy maintains its Euro peg through over-collateralization, liquidation mechanisms, and stability fees. Users can:

• Deposit collateral (ETH initially)
• Mint EURxy stablecoins against their collateral
• Manage their positions
• Participate in liquidations
• Interact with the price oracle system (using EUR price feeds)

Quick Verification

If you're unable to run the full test suite due to connectivity limitations, you can quickly verify the codebase structure with our verification script:

./verify-code.sh

This will check:

• Contract structure and interfaces
• Core functionality implementation
• Solidity version compatibility
• Docker setup completeness

Architecture

The system consists of four main components:

1. StableCoin.sol

   • ERC20-compliant Euro stablecoin token (EURxy)
   • Minting and burning mechanisms
   • Access control for system components

2. Vault.sol

   • Collateral management
   • Debt position tracking in EUR
   • Liquidation mechanisms
   • Stability fee collection

3. IVault.sol

   • Interface defining vault operations
   • Standardized position management
   • Event definitions

4. IPriceOracle.sol

   • Decentralized EUR/Collateral price feed interface
   • Multi-oracle support
   • Price validity checks

Key Features

• Multi-collateral support with EUR valuation
• 150% minimum collateralization ratio
• Dynamic stability fees in EUR terms
• Decentralized EUR price feeds
• Emergency pause functionality
• Role-based access control
• Liquidation incentives
• Reentrancy protection

System Parameters

• Minimum Collateral Ratio: 150%
• Liquidation Penalty: Configurable per collateral type
• Stability Fee: Accumulates based on time and base rate
• Price Feed Validity Period: Configurable
• Target Currency: Euro (EUR)

Usage

1. Deployment

Deployment

Deploy the contracts in the following order:

// 1. Deploy EURxy Stablecoin
const stablecoin = await StableCoin.deploy(
  "Euro Stable", 
  "EURxy",
  eurPriceFeed.address,
  3600 // 1 hour price validity period
)

// 2. Deploy Vault with stablecoin address
const vault = await Vault.deploy(stablecoin.address)

// 3. Configure roles
await stablecoin.grantRole(MINTER_ROLE, vault.address)

2. Opening a Position

// Deposit collateral
await vault.deposit(ETH_ADDRESS, { value: ethers.utils.parseEther("1") })

// Mint EURxy (amount in 18 decimals)
await vault.borrow(ethers.utils.parseUnits("100", 18))

3. Managing Positions

// Check position health
const position = await vault.getPosition(userAddress)

// Repay debt
await vault.repay(ethers.utils.parseUnits("50", 18))

// Withdraw collateral
await vault.withdraw(ETH_ADDRESS, ethers.utils.parseEther("0.5"))

4. Liquidations

// Check if position is liquidatable
const isUnderwater = await vault.isUnderCollateralized(userAddress)

// Perform liquidation
if (isUnderwater) {
    await vault.liquidate(userAddress)
}

Security Features

• ReentrancyGuard for all critical functions
• Pausable functionality for emergencies
• Comprehensive access control
• Input validation and bounds checking
• Price feed validity checks
• EUR/Collateral price sanity checks

Roles and Permissions

• DEFAULT_ADMIN_ROLE: System configuration
• MINTER_ROLE: EURxy minting rights
• BURNER_ROLE: EURxy burning rights
• ORACLE_ROLE: EUR price feed updates
• PAUSER_ROLE: Emergency system pause

Events

The system emits events for all important operations:

• CollateralDeposited
• CollateralWithdrawn
• EURxyMinted
• EURxyRepaid
• PositionLiquidated
• StabilityFeeCollected
• EURPriceUpdated

Development

Prerequisites

• Node.js 14+
• Hardhat
• Ethers.js
• Access to EUR price feeds
• Docker and Docker Compose (for isolated testing)

Installation

npm install

Testing

npx hardhat test

Deployment

npx hardhat run scripts/deploy.js --network <network>

Docker Setup

For isolated testing in a consistent environment, we provide a Docker-based setup:

# Start the Docker environment
./run-docker.sh up

# Run tests in Docker
./run-docker.sh test

# Deploy contracts to local Ganache inside Docker
./run-docker.sh deploy

# Open Hardhat console connected to Ganache
./run-docker.sh console

# Compile smart contracts (requires internet access)
./run-docker.sh compile 

# Open a shell in the development container
./run-docker.sh shell

# Show Docker logs
./run-docker.sh logs

# Stop the Docker environment
./run-docker.sh down

# Verify code structure without compilation
./verify-code.sh

The Docker setup includes:

• Ganache for a local Ethereum blockchain
• Hardhat development environment
• Isolated test runner
• All dependencies pre-installed

Note: Internet access is required for downloading the Solidity compiler. If your environment has firewall restrictions, use the verify-code.sh script to validate the codebase structure without compilation.

For more details, see Docker Documentation.

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request

License

MIT

Technical Implementation Details

The EURxy system consists of three primary contracts:

1. EURxy.sol - The ERC20 token implementation with:

   • Minting and burning controls
   • Role-based access for managing the system
   • Connection to EUR price oracles
   • Decentralized governance capabilities

2. Vault.sol - Manages collateral positions with:

   • Support for multiple collateral types
   • Customizable liquidation parameters
   • Stability fee mechanisms
   • Price feed integrations for EUR valuation

3. Price Oracle - Provides EUR price data with:

   • Validity time windows
   • Multiple data source aggregation
   • Sanity checking for price updates

Security Features

• ReentrancyGuard on all state-changing functions
• Role-based permissions for critical operations
• Circuit breakers (pause/unpause) for emergencies
• Over-collateralization with liquidation incentives

Disclaimer

This is an experimental implementation and should not be used in production without proper auditing and testing. The stability of the EUR peg depends on various market conditions and the effectiveness of the implemented mechanisms.