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. The codebase includes 1,300+ tests, custom errors and centralized validation libraries, and role-based access control.

📚 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
• Security Guide - Security practices and considerations
• 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
• Gas-Optimized Design: Custom errors, centralized validation, and consolidated error libraries

🏗️ 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-Labs/smart-contracts.git
cd smart-contracts/quantillon-protocol
npm install

Note: Some folders (scripts/) are encrypted with git-crypt for privacy concerns. If you need access to these files, you'll need the encryption key. Contact the maintainers for access.

2. Environment Configuration

# Copy an environment template for your target network
cp .env.localhost .env   # for local Anvil development

# Fill in your values (API keys, private keys, etc.)
# Other templates: .env.base-sepolia, .env.ethereum-sepolia

3. Build and Test

# Build contracts
make build

# Run tests
make test

# Run security analysis
make slither

Testing conventions: Run make test before pushing; run make ci for full checks (build, test, Slither, NatSpec, gas and size analysis). CI (GitHub Actions) runs make build && make test on push and pull requests to main. Use test_*, testFuzz_*, and invariant_* naming; avoid new assertTrue(true, ...) placeholders—convert or explicitly skip with rationale. See the test/ directory for test structure and coverage.

🚀 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 --verify

# Deploy to Ethereum Sepolia testnet
./scripts/deployment/deploy.sh ethereum-sepolia --with-mocks --verify

# Deploy to Ethereum mainnet (production)
./scripts/deployment/deploy.sh ethereum --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
• 🎭 Granular Mock Control: Choose which contracts to mock (--with-mocks, --with-mock-usdc, --with-mock-oracle)
• ✅ Contract Verification: Automatic verification on block explorers
• 🧪 Dry-Run Capability: Test deployments without broadcasting
• ⚡ Smart Caching: Compilation cache preserved by default for faster deployments (use --clean-cache to force full rebuild)
• 📝 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

# Reentrancy and security-oriented tests
forge test --match-contract ReentrancyTests

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 with centralized libraries
• Overflow Protection: Safe math operations throughout
• Flash Loan Protection: Balance checks to prevent flash loan attacks
• Custom Errors: Gas-efficient error handling with clear error messages
• Secret Handling: Environment variables loaded from .env during development
• 🔐 Encrypted Folders: Some folders (e.g., scripts/) are encrypted with git-crypt for privacy and security. These files require the encryption key to decrypt and access.

📊 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 1,300+ tests (100% passing)
• Security Analysis: Regular security audits and static analysis
• Gas Optimization: Optimized for deployment size and execution cost
• Error Handling: Custom errors for gas efficiency and better error messages
• Code Deduplication: Consolidated validation functions and error libraries
• Stack Optimization: Fixed stack too deep issues through struct-based refactoring

🤝 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 (aim for 100% coverage)
• Update documentation
• Ensure security best practices
• Protect secrets; never commit .env
• Use custom errors instead of require() strings for gas efficiency
• Consolidate duplicate code into libraries
• Follow the centralized error library pattern (CommonErrorLibrary)

📄 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