Quantillon Protocol Smart Contracts

Euro-pegged stablecoin protocol with dual-pool architecture, yield generation, and governance mechanisms

📖 Overview

Quantillon Protocol is a comprehensive DeFi ecosystem built around QEURO, a Euro-pegged stablecoin. The protocol features a dual-pool architecture that separates user deposits from hedging operations, enabling efficient yield generation while maintaining stability.

📚 Documentation

• API Documentation - Complete API reference for all smart contracts
• Technical Reference - Detailed technical specifications and implementation details
• Quick Start Guide - Get started quickly with integration examples
• Integration Examples - Comprehensive integration examples and patterns
• Deployment Guide - Complete deployment instructions and procedures
• Secure Deployment Guide - Environment and operational security practices
• Documentation Hub - Comprehensive documentation overview

🎯 Key Features

• Euro-Pegged Stablecoin: QEURO maintains 1:1 peg with Euro through sophisticated mechanisms
• Dual-Pool Architecture: Separates user deposits from hedging operations for optimal risk management
• Yield Generation: Multiple yield sources including protocol fees, interest differentials, and yield farming
• Governance Token: QTI token with vote-escrow mechanics for decentralized governance
• Advanced Hedging: EUR/USD hedging positions with margin management and liquidation systems
• Yield-Bearing Wrapper: stQEURO token that automatically accrues yield for holders
• Aave Integration: Automated yield farming through Aave protocol integration
• Comprehensive Security: Role-based access control, reentrancy protection, and emergency pause mechanisms
• 🔐 Secure Environment Variables: Enterprise-grade security with standard .env files

🏗️ Architecture

Core Contracts

🚀 Quick Start

Prerequisites

• Foundry (latest version)
• Node.js (v18 or later)
• Anvil for local development

1. Clone and Setup

git clone https://github.com/quantillon/smart-contracts.git
cd smart-contracts/quantillon-protocol
npm install

2. Environment Configuration

# Copy environment template
cp .env.example .env

# Fill in your values (API keys, private keys, etc.)
# Edit .env with your actual configuration

# Environment variables are ready to use

3. Build and Test

# Build contracts
make build

# Run tests
make test

# Run security analysis
make slither

🚀 Deployment

🔐 Multi-Phase Deployment Strategy

The protocol uses a 4-phase atomic deployment (A→B→C→D) to stay within Base Sepolia/Mainnet's 24.9M gas limit per transaction:

Key Features:

• ✅ All phases well under 24.9M limit (8-13M gas headroom)
• ✅ Automatic address passing between phases
• ✅ Minimal initialization with governance setters for post-deployment wiring
• ✅ Frontend address updater merges all phase broadcasts automatically

See Deployment Guide for complete details.

🔐 Secure Deployment

The protocol uses standard environment variable configuration:

# Deploy to localhost with mock contracts
./scripts/deployment/deploy.sh localhost --with-mocks

# Deploy to Base Sepolia testnet
./scripts/deployment/deploy.sh base-sepolia --verify

# Deploy to Base mainnet (production)
./scripts/deployment/deploy.sh base --production --verify

📋 Deployment Options

🔧 Deployment Features

• 🔐 Secure Environment Variables: Manage secrets with standard .env files (never commit them)
• 🌐 Multi-Network Support: Localhost, Base Sepolia, and Base Mainnet
• 🎭 Mock Contract Handling: Automatic mock deployment for localhost
• ✅ Contract Verification: Automatic verification on block explorers
• 🧪 Dry-Run Capability: Test deployments without broadcasting
• 📝 Post-Deployment Tasks: Automatic ABI copying and address updates

🛡️ Security Features

• Environment Variables: Use standard .env files (never commit them)
• Secret Management: Prefer a secret manager for production (e.g., AWS Secrets Manager)

🧪 Testing

Run All Tests

make test

Run Specific Test Suites

# Core protocol tests
forge test --match-contract QuantillonVault

# Integration tests
forge test --match-contract IntegrationTests

# Security tests
forge test --match-contract SecurityTests

Gas Analysis

make gas-analysis

🔍 Security

Automated Security Analysis

# Run Slither static analysis
make slither

# Run Mythril analysis
make mythril

# Validate NatSpec documentation
make validate-natspec

Security Features

• Role-Based Access Control: Granular permissions for different operations
• Reentrancy Protection: Comprehensive reentrancy guards
• Emergency Pause: Circuit breakers for critical functions
• Input Validation: Extensive parameter validation
• Overflow Protection: Safe math operations throughout
• Secret Handling: Environment variables loaded from .env during development

📊 Development

Available Commands

# Build contracts
make build

# Run tests
make test

# Run security analysis
make slither

# Generate documentation
make docs

# Clean build artifacts
make clean

# Gas analysis
make gas-analysis

Code Quality

• NatSpec Documentation: Comprehensive documentation for all functions
• Test Coverage: Extensive test suite with 678+ tests
• Security Analysis: Regular security audits and static analysis
• Gas Optimization: Optimized for deployment size and execution cost

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow Solidity style guide
• Write comprehensive tests
• Update documentation
• Ensure security best practices
• Protect secrets; never commit .env

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Website: https://quantillon.money
• Documentation: https://docs.quantillon.money
• Discord: https://discord.gg/quantillon
• Twitter: @QuantillonLabs

🙏 Acknowledgments

• OpenZeppelin for secure contract libraries
• Chainlink for reliable price feeds
• Aave for yield farming integration
• Foundry for development framework
• Standard .env files for environment variable management