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 ships an extensive Foundry test suite (unit, fuzz, integration, invariants), custom errors and centralized validation libraries, and role-based access control.

📚 Documentation

• API Reference - Complete API reference for all smart contracts
• Architecture Overview - Components, flows, roles and the upgrade model
• Oracle Architecture - Hedge-aligned EUR/USD pricing (Hyperliquid active, Chainlink fallback)
• 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
• stQEUROFactory Technical Upgrade - Multi-vault staking refactor details and runbook
• Multi-Vault Staking Runtime Flow - Contract-level mint/redeem/hedger routing behavior after the vaultId refactor
• Staking Yield Distribution - How yield reaches stQEURO stakers (hedger-first three-way split)
• External Vault Onboarding Runbook - Operator guide for setup-external-vaults.sh
• 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 (not yet activated — token supply not minted, governance dormant until launch)
• Advanced Hedging: EUR/USD hedging positions with margin management and liquidation systems
• Yield-Bearing Wrapper: stQEURO token that automatically accrues yield for holders
• External Adapter Integration: Multi-vault adapter model with post-deploy onboarding
• 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: scripts/deployment/ (deployment and upgrade scripts), the .env* templates and CLAUDE.private.md are git-crypt encrypted; the rest of scripts/ is plaintext so CI can run it. Building and testing does not need the key — contact the maintainers only if you need the deployment tooling.

2. Environment Configuration

# Copy an environment template for your target network
cp .env.localhost .env        # for local Anvil development
cp .env.base-sepolia .env     # for Base Sepolia testnet
cp .env.base .env             # for Base mainnet

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, .github/workflows/quantillon-protocol-tests.yml at the repository root) runs make build && make test on push and pull requests to main, the upgrade-safety gate (make analyze-contract-sizes check-storage-layout check-abi check-version-bump) on every PR, and a nightly heavy suite. 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

🔐 Unified Deployment

Core contracts are deployed in a single forge script invocation via DeployQuantillon.s.sol. Deployed addresses are written to deployments/{chainId}/addresses.json.

# 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 --production

# Then onboard external vault adapters (post-core step)
./scripts/deployment/setup-external-vaults.sh --help

📋 Deployment Options

🔧 Deployment Features

• 🔐 Secure Environment Variables: .env* templates are tracked git-crypt encrypted — never commit them in plaintext
• 🌐 Multi-Network Support: Localhost (31337), Base Sepolia (84532), Base Mainnet (8453)
• 🎭 Granular Mock Control: Choose which contracts to mock (--with-mocks, --with-mock-usdc, --with-mock-oracle)
• ✅ Contract Verification: Automatic verification on block explorers via --verify
• 🧪 Dry-Run Capability: Test deployments without broadcasting via --dry-run
• ⚡ 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: .env* templates are tracked git-crypt encrypted — never commit them in plaintext, never disable the filter
• 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

# Check contract bytecode size limits (EIP-170)
make analyze-contract-sizes

# Enforce a personal EIP-170 budget (example: 97%)
EIP170_PERSONAL_LIMIT_PERCENT=97 make analyze-contract-sizes

Security And Quality Reports

Analysis outputs are written under scripts/results/:

• scripts/results/slither/slither-report.txt - Slither executive summary and unresolved/suppressed/excluded sections
• scripts/results/mythril-reports/ - Mythril per-contract JSON and timestamped text summaries
• scripts/results/natspec-validation-report.txt - NatSpec validation coverage report
• scripts/results/contract-sizes/contract-sizes-summary.txt - EIP-170 size compliance summary
• scripts/results/gas-analysis/ - Gas analysis outputs

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 Paths: scripts/deployment/, .env* and CLAUDE.private.md are git-crypt encrypted (see .gitattributes); everything else is plaintext

📊 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 (unit, fuzz, integration, invariants) — make test
• 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: .env* files are tracked but git-crypt encrypted — never commit them in plaintext, never disable the filter
• 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: discord.gg/uk8T9GqdE5
• X (Twitter): @QuantillonLabs
• Telegram: @QuantillonLabs

🙏 Acknowledgments

• OpenZeppelin for secure contract libraries
• Chainlink for reliable price feeds
• Morpho (MetaMorpho vaults) for the live external yield venue and Hyperliquid for the hedge venue and EUR/USD market price
• Foundry for development framework
• Standard .env files for environment variable management