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
• stQEUROFactory Technical Upgrade - Multi-vault staking refactor details and runbook
• 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
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) 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

🔐 Unified Deployment

All 13 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

📋 Deployment Options

🔧 Deployment Features

• 🔐 Secure Environment Variables: Manage secrets with standard .env files (never commit them)
• 🌐 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: 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

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

Quantillon Protocol API Documentation

Overview

The Quantillon Protocol is a comprehensive DeFi ecosystem built on Base, featuring a euro-pegged stablecoin (QEURO), governance token (QTI), and advanced yield management system. This document provides detailed API documentation for all public interfaces.

Table of Contents

1. Core Contracts
   • QuantillonVault
   • QEUROToken
   • QTIToken
   • FeeCollector
   • UserPool
   • HedgerPool
   • stQEUROFactory
   • stQEUROToken
2. Vault Contracts
   • AaveVault
3. Yield Management
   • YieldShift
4. Oracle System
   • OracleRouter
   • ChainlinkOracle
   • StorkOracle
5. Utilities
   • TimeProvider
6. Error Codes
7. Events
8. Integration Examples

Core Contracts

QuantillonVault

The main vault contract that manages QEURO minting and redemption against USDC.

Functions

initialize(address admin, address _qeuro, address _usdc, address _oracle, address _hedgerPool, address _userPool, address _timelock, address _feeCollector)

Initializes the vault with initial configuration.

Parameters:

• admin (address): Admin address receiving roles
• _qeuro (address): QEURO token address
• _usdc (address): USDC token address
• _oracle (address): Oracle contract address
• _hedgerPool (address): HedgerPool address (can be set later)
• _userPool (address): UserPool address (can be set later)
• _timelock (address): Timelock/treasury address
• _feeCollector (address): FeeCollector address

Access: Public (only callable once)

mintQEURO(uint256 usdcAmount, uint256 minQeuroOut)

Mints QEURO by swapping USDC.

Parameters:

• usdcAmount (uint256): Amount of USDC to swap (6 decimals)
• minQeuroOut (uint256): Minimum QEURO expected (18 decimals, slippage protection)

Access: Public

Requirements:

• Contract not paused
• Valid oracle price and initialized price cache (initializePriceCache)
• Active hedger (hedgerPool.hasActiveHedger())
• Sufficient USDC balance and allowance

redeemQEURO(uint256 qeuroAmount, uint256 minUsdcOut)

Redeems QEURO for USDC.

Parameters:

• qeuroAmount (uint256): Amount of QEURO to swap (18 decimals)
• minUsdcOut (uint256): Minimum USDC expected (6 decimals, slippage protection)

Access: Public

Requirements:

• Contract not paused
• Valid oracle price (normal mode)
• Sufficient QEURO balance and allowance
• Automatically routes to liquidation redemption when protocol CR is at or below critical threshold

calculateMintAmount(uint256 usdcAmount) → (uint256, uint256)

Calculates quoted mint output using cached price.

Parameters:

• usdcAmount (uint256): Amount of USDC (6 decimals)

Returns:

• uint256: Amount of QEURO that would be minted (18 decimals)
• uint256: Mint fee (USDC, 6 decimals)

Access: Public view

calculateRedeemAmount(uint256 qeuroAmount) → (uint256, uint256)

Calculates quoted redeem output using cached price.

Parameters:

• qeuroAmount (uint256): Amount of QEURO (18 decimals)

Returns:

• uint256: Amount of USDC that would be received (6 decimals)
• uint256: Redemption fee (USDC, 6 decimals)

Access: Public view

getVaultMetrics() → (uint256, uint256, uint256, uint256, uint256)

Retrieves comprehensive vault metrics.

Returns:

• uint256: totalUsdcHeld (USDC in vault, 6 decimals)
• uint256: totalMinted (QEURO tracked by vault, 18 decimals)
• uint256: totalDebtValue (USD value from live supply and cached EUR/USD)
• uint256: totalUsdcInExternalVaults (tracked principal across external adapters)
• uint256: totalUsdcAvailable (vault + external vault balances including accrued yield)

Access: Public view

getProtocolCollateralizationRatio() → (uint256)

Returns collateralization ratio in 18-decimal percentage format (100% = 1e20).

canMint() → (bool)

Returns whether minting is currently allowed.

getProtocolCollateralizationRatioView() → (uint256) / canMintView() → (bool)

View-safe aliases that use cached price path (no state refresh side effects).

initializePriceCache()

Seeds the cached EUR/USD price after deployment (required before first mint).

updateHedgerRewardFeeSplit(uint256 newSplit)

Updates the fee share routed to HedgerPool reserve (1e18 = 100%).

mintQEUROToVault(uint256 usdcAmount, uint256 minQeuroOut, uint256 vaultId)

Mints QEURO and routes collateral to a specific external vault adapter.

mintAndStakeQEURO(uint256 usdcAmount, uint256 minQeuroOut, uint256 vaultId, uint256 minStQEUROOut) → (uint256, uint256)

One-step flow: mint QEURO and immediately stake into stQEURO{vaultName} for the selected vaultId.

harvestVaultYield(uint256 vaultId) → (uint256)

Triggers yield harvest for a specific external vault adapter.

deployUsdcToVault(uint256 vaultId, uint256 usdcAmount)

Operator function to manually deploy vault-held USDC into a selected external vault adapter.

Events

event QEUROminted(address indexed user, uint256 usdcAmount, uint256 qeuroAmount);
event QEURORedeemed(address indexed user, uint256 qeuroAmount, uint256 usdcAmount);
event LiquidationRedeemed(address indexed user, uint256 qeuroAmount, uint256 usdcPayout, uint256 collateralizationRatioBps, bool isPremium);
event ProtocolFeeRouted(string sourceType, uint256 totalFee, uint256 hedgerReserveShare, uint256 collectorShare);
event StakingVaultConfigured(uint256 indexed vaultId, address indexed adapter, bool active);
event UsdcDeployedToExternalVault(uint256 indexed vaultId, uint256 indexed usdcAmount, uint256 principalInVault);
event UsdcWithdrawnFromExternalVault(uint256 indexed vaultId, uint256 indexed usdcAmount, uint256 principalInVault);
event ExternalVaultYieldHarvested(uint256 indexed vaultId, uint256 harvestedYield);

QEUROToken

The euro-pegged stablecoin token with compliance features.

Functions

mint(address to, uint256 amount)

Mints QEURO tokens to a specified address.

Parameters:

• to (address): Recipient address
• amount (uint256): Amount to mint (18 decimals)

Access: Vault role only

burn(uint256 amount)

Burns QEURO tokens from the caller's balance.

Parameters:

• amount (uint256): Amount to burn (18 decimals)

Access: Vault role only

whitelistAddress(address account)

Adds an address to the whitelist.

Parameters:

• account (address): Address to whitelist

Access: Compliance role only

blacklistAddress(address account)

Adds an address to the blacklist.

Parameters:

• account (address): Address to blacklist

Access: Compliance role only

updateMaxSupply(uint256 newMaxSupply)

Updates the maximum supply cap.

Parameters:

• newMaxSupply (uint256): New maximum supply (18 decimals)

Access: Admin role only

getTokenInfo() → (uint256, uint256, uint256, bool, bool)

Retrieves comprehensive token information.

Returns:

• uint256: Total supply
• uint256: Maximum supply
• uint256: Supply utilization percentage
• bool: Whitelist mode enabled
• bool: Contract paused

Access: Public view

Events

event TokensMinted(address indexed to, uint256 amount);
event TokensBurned(address indexed from, uint256 amount);
event AddressWhitelisted(address indexed account);
event AddressBlacklisted(address indexed account);
event MaxSupplyUpdated(uint256 oldMaxSupply, uint256 newMaxSupply);

QTIToken

The governance token with vote-escrow mechanics.

Functions

lock(uint256 amount, uint256 lockTime) → (uint256)

Locks QTI tokens for voting power.

Parameters:

• amount (uint256): Amount of QTI to lock (18 decimals)
• lockTime (uint256): Duration to lock (seconds)

Returns:

• uint256: Voting power received (18 decimals)

Access: Public

Requirements:

• Sufficient QTI balance
• Lock time between minimum and maximum duration

unlock() → (uint256)

Unlocks QTI tokens after lock period expires.

Returns:

• uint256: Amount of QTI unlocked

Access: Public

Requirements:

• Lock period has expired

getVotingPower(address user) → (uint256)

Gets current voting power for an address.

Parameters:

• user (address): User address

Returns:

• uint256: Current voting power (18 decimals)

Access: Public view

getLockInfo(address user) → (uint256, uint256, uint256, uint256)

Gets lock information for an address.

Parameters:

• user (address): User address

Returns:

• uint256: Locked amount
• uint256: Lock time
• uint256: Unlock time
• uint256: Current voting power

Access: Public view

createProposal(string memory description, uint256 startTime, uint256 endTime) → (uint256)

Creates a new governance proposal.

Parameters:

• description (string): Proposal description
• startTime (uint256): Voting start time
• endTime (uint256): Voting end time

Returns:

• uint256: Proposal ID

Access: Public

Requirements:

• Sufficient voting power
• Valid time parameters

vote(uint256 proposalId, bool support)

Votes on a governance proposal.

Parameters:

• proposalId (uint256): Proposal ID
• support (bool): True for yes, false for no

Access: Public

Requirements:

• Voting period active
• Sufficient voting power
• Not already voted

Events

event TokensLocked(address indexed user, uint256 amount, uint256 lockTime, uint256 votingPower);
event TokensUnlocked(address indexed user, uint256 amount);
event ProposalCreated(uint256 indexed proposalId, string description, uint256 startTime, uint256 endTime);
event VoteCast(address indexed voter, uint256 indexed proposalId, bool support, uint256 votingPower);

UserPool

Manages user deposits, staking, and yield distribution.

Functions

deposit(uint256 usdcAmount)

Deposits USDC into the user pool.

Parameters:

• usdcAmount (uint256): Amount of USDC to deposit (6 decimals)

Access: Public

Requirements:

• Contract not paused
• Sufficient USDC balance and allowance

withdraw(uint256 usdcAmount)

Withdraws USDC from the user pool.

Parameters:

• usdcAmount (uint256): Amount of USDC to withdraw (6 decimals)

Access: Public

Requirements:

• Sufficient balance
• Contract not paused

stake(uint256 qeuroAmount)

Stakes QEURO tokens for rewards.

Parameters:

• qeuroAmount (uint256): Amount of QEURO to stake (18 decimals)

Access: Public

Requirements:

• Sufficient QEURO balance and allowance
• Above minimum stake amount

unstake(uint256 qeuroAmount)

Unstakes QEURO tokens.

Parameters:

• qeuroAmount (uint256): Amount of QEURO to unstake (18 decimals)

Access: Public

Requirements:

• Sufficient staked balance
• Cooldown period completed

claimStakingRewards() → (uint256)

Claims accumulated staking rewards.

Returns:

• uint256: Amount of rewards claimed

Access: Public

getUserInfo(address user) → (uint256, uint256, uint256, uint256, uint256)

Gets comprehensive user information.

Parameters:

• user (address): User address

Returns:

• uint256: Deposited USDC amount
• uint256: Staked QEURO amount
• uint256: Last stake time
• uint256: Pending rewards
• uint256: Total rewards claimed

Access: Public view

getPoolMetrics() → (uint256, uint256, uint256, uint256)

Gets pool metrics.

Returns:

• uint256: Total users
• uint256: Total stakes
• uint256: Total deposits
• uint256: Total rewards distributed

Access: Public view

Events

event USDCDeposited(address indexed user, uint256 amount);
event USDCWithdrawn(address indexed user, uint256 amount);
event QEUROStaked(address indexed user, uint256 amount);
event QEUROUnstaked(address indexed user, uint256 amount);
event RewardsClaimed(address indexed user, uint256 amount);

HedgerPool

Manages the protocol’s single-hedger leveraged position and hedger reward settlement.

Functions

enterHedgePosition(uint256 usdcAmount, uint256 leverage) → (uint256)

Opens a new hedge position.

Parameters:

• usdcAmount (uint256): USDC margin amount (6 decimals)
• leverage (uint256): Leverage multiplier (1-10x)

Returns:

• uint256: Position ID

Access: Public

Requirements:

• Caller must be the configured singleHedger
• Valid leverage amount
• Sufficient USDC balance and allowance
• Fresh oracle price

exitHedgePosition(uint256 positionId) → (int256)

Closes the active hedge position.

Parameters:

• positionId (uint256): Position ID to close

Returns:

• int256: Profit or loss (positive = profit, negative = loss)

Access: Public

Requirements:

• Position exists and is active
• Caller owns the position

addMargin(uint256 positionId, uint256 usdcAmount)

Adds margin to an existing position.

Parameters:

• positionId (uint256): Position ID
• usdcAmount (uint256): Additional USDC margin (6 decimals)

Access: Public

Requirements:

• Position exists and is active
• Caller owns the position

removeMargin(uint256 positionId, uint256 usdcAmount)

Removes margin from a position.

Parameters:

• positionId (uint256): Position ID
• usdcAmount (uint256): USDC amount to remove (6 decimals)

Access: Public

Requirements:

• Position exists and is active
• Caller owns the position
• Maintains minimum margin ratio

claimHedgingRewards() → (uint256, uint256, uint256)

Claims hedger rewards.

Returns:

• uint256: Interest differential paid/escrowed by HedgerPool reserve
• uint256: YieldShift rewards claimed via YieldShift
• uint256: Total rewards for reporting (interest + yieldShift)

Access: Restricted to configured singleHedger

withdrawPendingRewards(address recipient)

Withdraws reward amounts escrowed after failed push-transfer in claimHedgingRewards.

hasActiveHedger() → (bool)

Returns whether a configured single hedger currently has an active position.

setSingleHedger(address hedger)

Bootstrap/rotation entrypoint for single hedger configuration (governance-only).
If no hedger is configured yet, assignment is immediate. Otherwise it creates a delayed pending rotation.

applySingleHedgerRotation()

Applies a previously proposed single-hedger rotation after delay (governance-only).

fundRewardReserve(uint256 amount)

Permissionless reserve top-up path for hedger rewards.

configureRiskAndFees((...))

Batch governance update for:

• margin ratio / leverage limits
• hold blocks / minimum margin
• EUR/USD interest rates
• entry / exit / margin fees
• rewardFeeSplit (1e18 = 100%)

configureDependencies((...))

Batch governance update for:

• treasury
• vault
• oracle
• yieldShift
• feeCollector

Events

event HedgePositionOpened(address indexed hedger, uint256 indexed positionId, bytes32 positionData);
event HedgePositionClosed(address indexed hedger, uint256 indexed positionId, bytes32 packedData);
event MarginUpdated(address indexed hedger, uint256 indexed positionId, bytes32 packedData);
event HedgingRewardsClaimed(address indexed hedger, bytes32 packedData);
event HedgerFillUpdated(uint256 indexed positionId, uint256 previousFilled, uint256 newFilled);
event RewardReserveFunded(address indexed funder, uint256 amount);
event SingleHedgerRotationProposed(address indexed currentHedger, address indexed pendingHedger, uint256 activatesAt);
event SingleHedgerRotationApplied(address indexed previousHedger, address indexed newHedger);

stQEUROFactory

Factory contract for vault-scoped staking tokens.

Functions

registerVault(uint256 vaultId, string vaultName) -> (address)

Registers the calling vault and deploys a dedicated stQEURO token proxy.

Parameters:

• vaultId (uint256): Non-zero vault id
• vaultName (string): Uppercase alphanumeric vault suffix (length 1..12)

Returns:

• address: Newly deployed stQEURO token for the vault

Access: VAULT_FACTORY_ROLE only, strict self-registration semantics (msg.sender is the vault)

getStQEUROByVaultId(uint256 vaultId) -> (address)

Resolves stQEURO token address for a given vault id.

getStQEUROByVault(address vault) -> (address)

Resolves stQEURO token address for a given vault address.

getVaultById(uint256 vaultId) -> (address)

Returns vault address for a registered vault id.

getVaultIdByStQEURO(address stQEUROToken) -> (uint256)

Returns vault id mapped to an stQEURO token address.

getVaultName(uint256 vaultId) -> (string)

Returns vault name suffix stored at registration.

updateYieldShift(address newYieldShift)

Governance setter for YieldShift dependency used for newly deployed stQEURO tokens.

updateTokenImplementation(address newImplementation)

Governance setter for stQEURO token implementation address used by future proxies.

updateTreasury(address newTreasury) / updateTokenAdmin(address newAdmin) / updateOracle(address newOracle)

Governance setters for factory-level defaults used during vault token deployment.

Events

event VaultRegistered(uint256 indexed vaultId, address indexed vault, address indexed stQEUROToken, string vaultName);
event FactoryConfigUpdated(string indexed key, address oldValue, address newValue);

stQEUROToken

Staked QEURO token with yield distribution.

Functions

stake(uint256 qeuroAmount)

Stakes QEURO tokens to receive stQEURO.

Parameters:

• qeuroAmount (uint256): Amount of QEURO to stake (18 decimals)

Access: Public

Requirements:

• Sufficient QEURO balance and allowance

unstake(uint256 stQeuroAmount)

Unstakes stQEURO tokens to receive QEURO.

Parameters:

• stQeuroAmount (uint256): Amount of stQEURO to unstake (18 decimals)

Access: Public

Requirements:

• Sufficient stQEURO balance

claimYield() → (uint256)

Claims accumulated yield.

Returns:

• uint256: Amount of yield claimed

Access: Public

getExchangeRate() → (uint256)

Gets current exchange rate between stQEURO and QEURO.

Returns:

• uint256: Exchange rate (18 decimals)

Access: Public view

getQEUROEquivalent(uint256 stQeuroAmount) → (uint256)

Calculates QEURO equivalent for stQEURO amount.

Parameters:

• stQeuroAmount (uint256): Amount of stQEURO (18 decimals)

Returns:

• uint256: Equivalent QEURO amount (18 decimals)

Access: Public view

distributeYield(uint256 qeuroAmount)

Distributes yield to stakers.

Parameters:

• qeuroAmount (uint256): Amount of QEURO to distribute (18 decimals)

Access: Yield manager role only

initialize(...) (dynamic metadata overload)

Supports per-vault metadata (tokenName, tokenSymbol, vaultName) when deployed through stQEUROFactory.

Events

event QEUROStaked(address indexed user, uint256 qeuroAmount, uint256 stQeuroAmount);
event QEUROUnstaked(address indexed user, uint256 stQeuroAmount, uint256 qeuroAmount);
event YieldClaimed(address indexed user, uint256 amount);
event YieldDistributed(uint256 totalAmount, uint256 timestamp);

Fee Management

FeeCollector

Centralized protocol fee collection and distribution.

Functions

collectFee(address token, uint256 amount)

Records a collected fee from a protocol contract.

Parameters:

• token (address): Token address (e.g. USDC)
• amount (uint256): Fee amount collected

Access: Authorized protocol contracts only

distributeFees(address token)

Distributes collected fees to treasury, dev fund, and community fund according to configured ratios.

Parameters:

• token (address): Token to distribute

Access: GOVERNANCE_ROLE

updateFeeRatios(uint256 treasury, uint256 dev, uint256 community)

Updates fee distribution ratios.

Parameters:

• treasury (uint256): Treasury ratio (basis points, default 6000 = 60%)
• dev (uint256): Dev fund ratio (basis points, default 2500 = 25%)
• community (uint256): Community fund ratio (basis points, default 1500 = 15%)

Access: GOVERNANCE_ROLE

Requirements:

• treasury + dev + community == 10000

withdrawFees(address token)

Withdraws collected fees to the caller's role-permitted address.

Access: TREASURY_ROLE

Events

event FeeCollected(address indexed token, uint256 amount);
event FeesDistributed(address indexed token, uint256 treasury, uint256 dev, uint256 community);
event FeeRatiosUpdated(uint256 treasury, uint256 dev, uint256 community);

Vault Contracts

AaveVault

Manages yield generation through Aave v3 protocol integration.

Functions

deployToAave(uint256 usdcAmount)

Deploys USDC to Aave for yield generation.

Parameters:

• usdcAmount (uint256): Amount of USDC to deploy (6 decimals)

Access: Yield manager role only

Requirements:

• Sufficient USDC balance
• Within exposure limits

withdrawFromAave(uint256 usdcAmount)

Withdraws USDC from Aave.

Parameters:

• usdcAmount (uint256): Amount of USDC to withdraw (6 decimals)

Access: Yield manager role only

harvestAaveYield() → (uint256)

Harvests accumulated yield from Aave.

Returns:

• uint256: Amount of yield harvested

Access: Yield manager role only

Notes:

• Reverts if yieldVaultId is not configured (yieldVaultId == 0)
• Routes harvested yield to YieldShift.addYield(yieldVaultId, ...)

setYieldVaultId(uint256 newYieldVaultId)

Sets the destination vault id used when routing harvested Aave yield to YieldShift.

Access: Governance role only

updateYieldShift(address newYieldShift)

Updates the YieldShift dependency used by AaveVault for yield routing.

Access: Governance role only

getAaveBalance() → (uint256)

Gets current USDC balance in Aave.

Returns:

• uint256: USDC balance in Aave (6 decimals)

Access: Public view

getAaveAPY() → (uint256)

Gets current Aave APY.

Returns:

• uint256: APY in basis points

Access: Public view

autoRebalance() → (bool, uint256, uint256)

Automatically rebalances Aave position.

Returns:

• bool: Whether rebalancing occurred
• uint256: New allocation percentage
• uint256: Expected yield

Access: Public

Events

event USDCDepositedToAave(uint256 amount);
event USDCWithdrawnFromAave(uint256 amount);
event AaveYieldHarvested(uint256 amount);
event AavePositionRebalanced(uint256 newAllocation, uint256 expectedYield);

Yield Management

YieldShift

Manages yield distribution between user and hedger pools.

Functions

addYield(uint256 vaultId, uint256 yieldAmount, bytes32 source)

Adds yield to the distribution system.

Parameters:

• vaultId (uint256): Registered staking vault id receiving user-allocation yield
• yieldAmount (uint256): Amount of USDC yield to add (6 decimals)
• source (bytes32): Source key ("aave", "fees", "interest_differential", etc.)

Access: Authorized yield sources only

updateYieldDistribution()

Refreshes and applies current distribution between user and hedger pools.

Access: Public (whenNotPaused)

claimUserYield(address user) → (uint256)

Claims yield for user pool.

Returns:

• uint256: Amount of yield claimed

Access: YIELD_MANAGER_ROLE

claimHedgerYield(address hedger) → (uint256)

Claims yield for hedger pool.

Returns:

• uint256: Amount of yield claimed

Access: YIELD_MANAGER_ROLE

configureYieldModel((...))

Batch governance update for:

• baseYieldShift
• maxYieldShift
• adjustmentSpeed
• targetPoolRatio

configureDependencies((...))

Batch governance update for:

• userPool
• hedgerPool
• aaveVault
• stQEUROFactory
• treasury

setYieldSourceAuthorization(address source, bytes32 yieldType, bool authorized)

Adds/removes an authorized yield source with explicit yield type mapping.

currentYieldShift() → (uint256)

Direct state getter for current shift (1e4 precision).

userPendingYield(address user) → (uint256) / hedgerPendingYield(address hedger) → (uint256)

Direct state getters for pending yield balances.

paused() → (bool)

Pausable state getter. Yield distribution is active when paused() == false.

getPoolMetrics() → (uint256, uint256, uint256, uint256)

Gets pool metrics for yield calculation.

Returns:

• uint256: User pool size
• uint256: Hedger pool size
• uint256: Pool ratio
• uint256: Target ratio

Access: Public view

calculateOptimalYieldShift() → (uint256, uint256)

Calculates optimal yield distribution.

Returns:

• uint256: Optimal shift
• uint256: Current deviation from optimal

Access: Public view

Events

event YieldDistributionUpdated(uint256 userPoolYield, uint256 hedgerPoolYield, uint256 currentShift);
event YieldAdded(uint256 yieldAmount, string indexed source, uint256 indexed timestamp);
event UserYieldClaimed(address indexed user, uint256 yieldAmount, uint256 timestamp);
event HedgerYieldClaimed(address indexed hedger, uint256 yieldAmount, uint256 timestamp);

Oracle System

The oracle system consists of three contracts. All protocol contracts interact only with OracleRouter via the IOracle interface — the underlying oracle source can be switched by governance without any changes to the protocol.

OracleRouter

Routes price requests to the currently active oracle (ChainlinkOracle or StorkOracle).

Functions

getLatestPrice() → (uint256, bool)

Gets the current EUR/USD price from the active oracle.

Returns:

• uint256: EUR/USD price (18 decimals)
• bool: Whether price is valid and fresh

Access: Public view

switchOracle(uint8 newOracleType)

Switches the active oracle between Chainlink (0) and Stork (1).

Parameters:

• newOracleType (uint8): 0 = Chainlink, 1 = Stork

Access: ORACLE_MANAGER_ROLE

setOracleAddresses(address chainlink, address stork)

Updates the underlying oracle contract addresses.

Parameters:

• chainlink (address): ChainlinkOracle proxy address
• stork (address): StorkOracle proxy address

Access: ORACLE_MANAGER_ROLE

Events

event OracleSwitched(uint8 oldOracle, uint8 newOracle, address caller);
event OracleAddressesUpdated(address newChainlink, address newStork);

ChainlinkOracle

EUR/USD and USDC/USD price feeds via Chainlink AggregatorV3.

Validation rules:

• Max staleness: 3600 seconds (1 hour)
• Max deviation: 500 basis points (5%)
• Timestamp drift detection: 900 seconds (15 minutes)

Functions

getLatestPrice() → (uint256, bool)

Gets current EUR/USD price from Chainlink.

Returns:

• uint256: EUR/USD price (18 decimals)
• bool: Whether price is valid and fresh

Access: Public view

updatePriceFeeds(address eurUsdFeed, address usdcUsdFeed)

Updates Chainlink price feed addresses.

Parameters:

• eurUsdFeed (address): EUR/USD Chainlink aggregator address
• usdcUsdFeed (address): USDC/USD Chainlink aggregator address

Access: ORACLE_MANAGER_ROLE

Events

event PriceFeedsUpdated(address eurUsdFeed, address usdcUsdFeed);
event CircuitBreakerTriggered(uint256 timestamp);
event CircuitBreakerReset(uint256 timestamp);

StorkOracle

EUR/USD and USDC/USD price feeds via Stork Network. Same IOracle interface as ChainlinkOracle.

Validation rules: identical to ChainlinkOracle (staleness, deviation, timestamp drift).

Functions

getLatestPrice() → (uint256, bool)

Gets current EUR/USD price from Stork Network.

Returns:

• uint256: EUR/USD price (18 decimals)
• bool: Whether price is valid and fresh

Access: Public view

updateFeedIds(bytes32 eurUsdId, bytes32 usdcUsdId)

Updates Stork feed IDs.

Parameters:

• eurUsdId (bytes32): EUR/USD Stork feed ID (default: keccak256("EURUSD"))
• usdcUsdId (bytes32): USDC/USD Stork feed ID (default: keccak256("USDCUSD"))

Access: ORACLE_MANAGER_ROLE

Events

event FeedIdsUpdated(bytes32 eurUsdId, bytes32 usdcUsdId);

Utilities

TimeProvider

Provides time utilities with offset capabilities.

Functions

currentTime() → (uint256)

Gets current time with offset.

Returns:

• uint256: Current timestamp

Access: Public view

setTimeOffset(int256 offset)

Sets time offset.

Parameters:

• offset (int256): Time offset in seconds

Access: Time manager role only

advanceTime(uint256 amount)

Advances time by specified amount.

Parameters:

• amount (uint256): Time to advance in seconds

Access: Time manager role only

isFuture(uint256 timestamp) → (bool)

Checks if timestamp is in the future.

Parameters:

• timestamp (uint256): Timestamp to check

Returns:

• bool: True if timestamp is in the future

Access: Public view

Events

event TimeOffsetSet(int256 oldOffset, int256 newOffset);
event TimeAdvanced(uint256 amount);

Error Codes

The protocol uses custom errors for gas efficiency. Common error codes include:

// Access Control
error UnauthorizedAccess();
error InsufficientRole();

// Validation
error InvalidAmount();
error InvalidAddress();
error InvalidParameter();
error InvalidTime();

// Business Logic
error InsufficientBalance();
error InsufficientAllowance();
error ExceedsLimit();
error BelowMinimum();

// Oracle
error StalePrice();
error InvalidPrice();
error CircuitBreakerActive();

// Emergency
error ContractPaused();
error EmergencyMode();

// Liquidation
error PositionHealthy();
error InsufficientMargin();

Events

All contracts emit comprehensive events for state changes. Key event categories:

Core Events

• Token transfers and approvals
• Deposits and withdrawals
• Staking and unstaking
• Yield distribution

Governance Events

• Proposal creation and execution
• Voting and delegation
• Parameter updates

Risk Management Events

• Position opening and closing
• Liquidations
• Circuit breaker activations

Emergency Events

• Pause and unpause
• Emergency withdrawals
• Recovery operations

Integration Examples

Basic QEURO Minting

// 1. Approve USDC spending
usdc.approve(vaultAddress, usdcAmount);

// 2. Mint QEURO with slippage protection
uint256 minQeuroOut = (usdcAmount * 95) / 100; // 5% slippage tolerance
vault.mintQEURO(usdcAmount, minQeuroOut);

Staking QEURO for Rewards

// 1. Approve QEURO spending
qeuro.approve(userPoolAddress, qeuroAmount);

// 2. Stake QEURO
userPool.stake(qeuroAmount);

// 3. Claim rewards later
uint256 rewards = userPool.claimStakingRewards();

Opening a Hedge Position

// 1. Approve USDC spending
usdc.approve(hedgerPoolAddress, marginAmount);

// 2. Open position with 5x leverage
uint256 positionId = hedgerPool.enterHedgePosition(marginAmount, 5);

// 3. Monitor hedger activity / claim rewards
bool hedgerActive = hedgerPool.hasActiveHedger();
(uint256 interestDiff, uint256 ysRewards, uint256 total) = hedgerPool.claimHedgingRewards();

Governance Participation

// 1. Lock QTI for voting power
qti.lock(lockAmount, lockDuration);

// 2. Create proposal
uint256 proposalId = qti.createProposal(
    "Update protocol parameters",
    block.timestamp + 1 days,
    block.timestamp + 7 days
);

// 3. Vote on proposal
qti.vote(proposalId, true); // Vote yes

Security Considerations

1. Always validate return values from view functions
2. Check contract state before making transactions
3. Use slippage protection for all swaps
4. Monitor oracle prices for freshness
5. Implement proper error handling for all interactions
6. Use events for transaction monitoring
7. Follow access control patterns for role-based operations

Support

For technical support and questions:

• Email: team@quantillon.money
• Documentation: Quantillon Protocol Docs
• GitHub: Quantillon Labs

This documentation is maintained by Quantillon Labs and updated regularly. Last updated: March 2026

Quantillon Protocol API Reference

Technical API Reference

This document provides detailed technical specifications for all Quantillon Protocol smart contract interfaces.

Contract Addresses

Note: These are example addresses for documentation. Use actual deployed addresses in production.

QuantillonVault

Contract: QuantillonVault.sol
Interface: IQuantillonVault.sol
Inherits: SecureUpgradeable, PausableUpgradeable

Function Signatures

initialize(address admin, address _qeuro, address _usdc, address _oracle, address _hedgerPool, address _userPool, address _timelock, address _feeCollector)

function initialize(
    address admin,
    address _qeuro,
    address _usdc,
    address _oracle,
    address _hedgerPool,
    address _userPool,
    address _timelock,
    address _feeCollector
) external

Modifiers: initializer
Notes:

• _hedgerPool and _userPool can be wired later through governance setters.
• _timelock is also used as treasury destination for recovery flows.

mintQEURO(uint256 usdcAmount, uint256 minQeuroOut)

function mintQEURO(
    uint256 usdcAmount,
    uint256 minQeuroOut
) external

Modifiers: whenNotPaused, nonReentrant
Events: QEUROminted(address indexed user, uint256 usdcAmount, uint256 qeuroAmount)
Requirements:

• usdcAmount > 0
• Price cache initialized (initializePriceCache)
• Active hedger configured (hedgerPool.hasActiveHedger())
• Sufficient USDC balance and allowance
• Projected post-mint collateralization ratio must remain above threshold

redeemQEURO(uint256 qeuroAmount, uint256 minUsdcOut)

function redeemQEURO(
    uint256 qeuroAmount,
    uint256 minUsdcOut
) external

Modifiers: whenNotPaused, nonReentrant
Events: QEURORedeemed(address indexed user, uint256 qeuroAmount, uint256 usdcAmount)
Requirements:

• qeuroAmount > 0
• Sufficient QEURO balance and allowance
• Automatically routes to liquidation mode when protocol CR is at or below critical threshold
• Pulls liquidity from Aave when needed (including accrued yield)

calculateMintAmount(uint256 usdcAmount) → (uint256, uint256)

function calculateMintAmount(uint256 usdcAmount) external view returns (uint256 qeuroAmount, uint256 fee)

Returns:

• qeuroAmount: Amount of QEURO that would be minted (18 decimals)
• fee: Mint fee amount (USDC, 6 decimals)

Notes:

• Uses cached EUR/USD price path (lastValidEurUsdPrice).

calculateRedeemAmount(uint256 qeuroAmount) → (uint256, uint256)

function calculateRedeemAmount(uint256 qeuroAmount) external view returns (uint256 usdcAmount, uint256 fee)

Returns:

• usdcAmount: Amount of USDC that would be received (6 decimals)
• fee: Redemption fee amount (USDC, 6 decimals)

Notes:

• Uses cached EUR/USD price path (lastValidEurUsdPrice).

getVaultMetrics() → (uint256, uint256, uint256, uint256, uint256)

function getVaultMetrics() external view returns (
    uint256 totalUsdcHeld_,
    uint256 totalMinted_,
    uint256 totalDebtValue,
    uint256 totalUsdcInExternalVaults_,
    uint256 totalUsdcAvailable_
)

Returns:

• totalUsdcHeld_: USDC held directly by vault
• totalMinted_: QEURO minted by vault tracker
• totalDebtValue: USD debt value using live token supply and cached EUR/USD
• totalUsdcInExternalVaults_: Principal tracker across all configured external vault adapters
• totalUsdcAvailable_: Total collateral available including accrued external-vault yield

getProtocolCollateralizationRatio() → (uint256)

function getProtocolCollateralizationRatio() public view returns (uint256 ratio)

Returns: Current protocol collateralization ratio in 18-decimal percentage format (100% = 1e20)

Description: Calculates CR = (TotalCollateral / BackingRequirement) * 1e20 where:

• TotalCollateral = totalUsdcHeld + currentExternalVaultCollateral (includes accrued adapter yield when queryable)
• BackingRequirement = QEUROSupply * cachedEurUsdPrice / 1e30

Note: This function uses cached price and returns 0 when required wiring/cache prerequisites are not met.

Requirements:

• Both HedgerPool and UserPool must be set
• Initialized cached price
• QEURO supply > 0

canMint() → (bool)

function canMint() public view returns (bool)

Returns: true if minting is allowed, false otherwise

Description: Checks if minting is allowed under current safeguards:

• Cached price must be initialized.
• Active hedger must exist.
• Collateralization ratio must be >= minCollateralizationRatioForMinting.

getProtocolCollateralizationRatioView() / canMintView()

View-safe aliases exposing the same logic for off-chain tooling.

initializePriceCache()

Governance-only bootstrap step required after deployment and before first user mint.

updateHedgerRewardFeeSplit(uint256 newSplit)

Governance setter for fee routing share to HedgerPool reserve (1e18 = 100%).

mintQEUROToVault(uint256 usdcAmount, uint256 minQeuroOut, uint256 vaultId)

User entrypoint for minting QEURO and routing collateral to a specific external vault adapter.

mintAndStakeQEURO(uint256 usdcAmount, uint256 minQeuroOut, uint256 vaultId, uint256 minStQEUROOut) → (uint256 qeuroMinted, uint256 stQEUROMinted)

One-step user entrypoint to mint QEURO and stake into the vault-specific stQEURO token.

deployUsdcToVault(uint256 vaultId, uint256 usdcAmount)

Vault-operator entrypoint for manual collateral deployment to a specific adapter.

harvestVaultYield(uint256 vaultId) → (uint256 harvestedYield)

Governance entrypoint that triggers yield harvest for a specific adapter.

QEUROToken

Contract: QEUROToken.sol
Interface: IQEUROToken.sol
Inherits: ERC20Upgradeable, AccessControlUpgradeable, PausableUpgradeable

Function Signatures

mint(address to, uint256 amount)

function mint(address to, uint256 amount) external

Modifiers: onlyRole(VAULT_ROLE)
Events: TokensMinted(address indexed to, uint256 amount)

burn(uint256 amount)

function burn(uint256 amount) external

Modifiers: onlyRole(VAULT_ROLE)
Events: TokensBurned(address indexed from, uint256 amount)

whitelistAddress(address account)

function whitelistAddress(address account) external

Modifiers: onlyRole(COMPLIANCE_ROLE)
Events: AddressWhitelisted(address indexed account)

blacklistAddress(address account)

function blacklistAddress(address account) external

Modifiers: onlyRole(COMPLIANCE_ROLE)
Events: AddressBlacklisted(address indexed account)

updateMaxSupply(uint256 newMaxSupply)

function updateMaxSupply(uint256 newMaxSupply) external

Modifiers: onlyRole(ADMIN_ROLE)
Events: MaxSupplyUpdated(uint256 oldMaxSupply, uint256 newMaxSupply)

getTokenInfo() → (uint256, uint256, uint256, bool, bool)

function getTokenInfo() external view returns (
    uint256 totalSupply,
    uint256 maxSupply,
    uint256 supplyUtilization,
    bool whitelistMode,
    bool isPaused
)

QTIToken

Contract: QTIToken.sol
Interface: IQTIToken.sol
Inherits: ERC20Upgradeable, AccessControlUpgradeable, PausableUpgradeable

Function Signatures

lock(uint256 amount, uint256 lockTime) → (uint256)

function lock(uint256 amount, uint256 lockTime) external returns (uint256 veQTI)

Modifiers: whenNotPaused, nonReentrant
Events: TokensLocked(address indexed user, uint256 amount, uint256 lockTime, uint256 votingPower)
Requirements:

• amount > 0
• lockTime >= MIN_LOCK_TIME && lockTime <= MAX_LOCK_TIME
• Sufficient QTI balance

unlock() → (uint256)

function unlock() external returns (uint256 amount)

Modifiers: whenNotPaused, nonReentrant
Events: TokensUnlocked(address indexed user, uint256 amount)
Requirements: Lock period has expired

getVotingPower(address user) → (uint256)

function getVotingPower(address user) external view returns (uint256 votingPower)

getLockInfo(address user) → (uint256, uint256, uint256, uint256)

function getLockInfo(address user) external view returns (
    uint256 lockedAmount,
    uint256 lockTime,
    uint256 unlockTime,
    uint256 currentVotingPower
)

createProposal(string memory description, uint256 startTime, uint256 endTime) → (uint256)

function createProposal(
    string memory description,
    uint256 startTime,
    uint256 endTime
) external returns (uint256 proposalId)

Modifiers: whenNotPaused
Events: ProposalCreated(uint256 indexed proposalId, string description, uint256 startTime, uint256 endTime)
Requirements:

• Sufficient voting power
• Valid time parameters

vote(uint256 proposalId, bool support)

function vote(uint256 proposalId, bool support) external

Modifiers: whenNotPaused
Events: VoteCast(address indexed voter, uint256 indexed proposalId, bool support, uint256 votingPower)
Requirements:

• Voting period active
• Sufficient voting power
• Not already voted

UserPool

Contract: UserPool.sol
Interface: IUserPool.sol
Inherits: SecureUpgradeable, PausableUpgradeable

Function Signatures

deposit(uint256 usdcAmount)

function deposit(uint256 usdcAmount) external

Modifiers: whenNotPaused, nonReentrant
Events: USDCDeposited(address indexed user, uint256 amount)
Requirements:

• usdcAmount > 0
• Sufficient USDC balance and allowance

withdraw(uint256 usdcAmount)

function withdraw(uint256 usdcAmount) external

Modifiers: whenNotPaused, nonReentrant
Events: USDCWithdrawn(address indexed user, uint256 amount)
Requirements:

• usdcAmount > 0
• Sufficient balance

stake(uint256 qeuroAmount)

function stake(uint256 qeuroAmount) external

Modifiers: whenNotPaused, nonReentrant
Events: QEUROStaked(address indexed user, uint256 amount)
Requirements:

• qeuroAmount >= MIN_STAKE_AMOUNT
• Sufficient QEURO balance and allowance

unstake(uint256 qeuroAmount)

function unstake(uint256 qeuroAmount) external

Modifiers: whenNotPaused, nonReentrant
Events: QEUROUnstaked(address indexed user, uint256 amount)
Requirements:

• qeuroAmount > 0
• Sufficient staked balance
• Cooldown period completed

claimStakingRewards() → (uint256)

function claimStakingRewards() external returns (uint256 rewardAmount)

Modifiers: whenNotPaused, nonReentrant
Events: RewardsClaimed(address indexed user, uint256 amount)

getUserInfo(address user) → (uint256, uint256, uint256, uint256, uint256)

function getUserInfo(address user) external view returns (
    uint256 depositedUsdc,
    uint256 stakedQeuro,
    uint256 lastStakeTime,
    uint256 pendingRewards,
    uint256 totalRewardsClaimed
)

getPoolMetrics() → (uint256, uint256, uint256, uint256)

function getPoolMetrics() external view returns (
    uint256 totalUsers,
    uint256 totalStakes,
    uint256 totalDeposits,
    uint256 totalRewards
)

HedgerPool

Contract: HedgerPool.sol
Interface: IHedgerPool.sol
Inherits: SecureUpgradeable, PausableUpgradeable

Function Signatures

enterHedgePosition(uint256 usdcAmount, uint256 leverage) → (uint256)

function enterHedgePosition(
    uint256 usdcAmount,
    uint256 leverage
) external returns (uint256 positionId)

Modifiers: whenNotPaused, nonReentrant
Events: HedgePositionOpened(address indexed hedger, uint256 indexed positionId, bytes32 positionData)
Requirements:

• usdcAmount > 0
• leverage >= 1 && leverage <= maxLeverage
• Caller must be configured singleHedger
• Fresh oracle price
• Sufficient USDC balance and allowance

exitHedgePosition(uint256 positionId) → (int256)

function exitHedgePosition(uint256 positionId) external returns (int256 pnl)

Modifiers: whenNotPaused, nonReentrant
Events: HedgePositionClosed(address indexed hedger, uint256 indexed positionId, bytes32 packedData)
Requirements:

• Position exists and is active
• Caller owns the position

addMargin(uint256 positionId, uint256 usdcAmount)

function addMargin(uint256 positionId, uint256 usdcAmount) external

Modifiers: whenNotPaused, nonReentrant
Events: MarginUpdated(address indexed hedger, uint256 indexed positionId, bytes32 packedData)
Requirements:

• Position exists and is active
• Caller owns the position
• usdcAmount > 0
• Margin fee is split between local reward reserve and FeeCollector

removeMargin(uint256 positionId, uint256 usdcAmount)

function removeMargin(uint256 positionId, uint256 usdcAmount) external

Modifiers: whenNotPaused, nonReentrant
Events: MarginUpdated(address indexed hedger, uint256 indexed positionId, bytes32 packedData)
Requirements:

• Position exists and is active
• Caller owns the position
• Maintains minimum margin ratio

claimHedgingRewards() → (uint256, uint256, uint256)

function claimHedgingRewards() external returns (uint256 interestDifferential, uint256 yieldShiftRewards, uint256 totalRewards)

Modifiers: nonReentrant
Events: HedgingRewardsClaimed(address indexed hedger, bytes32 packedData)
Requirements:

• Caller must be configured singleHedger
• YieldShift reward component is settled once through YieldShift

withdrawPendingRewards(address recipient)

function withdrawPendingRewards(address recipient) external

Pull-based fallback for pending reward escrow after failed push-transfer.

hasActiveHedger() → (bool)

function hasActiveHedger() external view returns (bool)

Returns true when the configured single hedger has an active position.

getTotalEffectiveHedgerCollateral(uint256 currentPrice) → (uint256)

function getTotalEffectiveHedgerCollateral(uint256 currentPrice) external view returns (uint256 totalEffectiveCollateral)

Returns: Total effective hedger collateral in USDC (6 decimals)
Requirements:

• currentPrice > 0

setSingleHedger(address hedger)

Governance entrypoint for bootstrap/rotation proposal.
If no hedger is currently configured, assignment is immediate. Otherwise it creates a delayed pending rotation.

applySingleHedgerRotation()

Executes a pending single-hedger rotation after delay.

fundRewardReserve(uint256 amount)

Permissionless reserve top-up path for hedger rewards.

configureRiskAndFees(HedgerRiskConfig cfg)

Batch governance setter for risk + fee parameters:

• minMarginRatio
• maxLeverage
• minPositionHoldBlocks
• minMarginAmount
• eurInterestRate
• usdInterestRate
• entryFee
• exitFee
• marginFee
• rewardFeeSplit (1e18 = 100%)

configureDependencies(HedgerDependencyConfig cfg)

Batch governance setter for:

• treasury
• vault
• oracle
• yieldShift
• feeCollector

stQEUROFactory

Contract: stQEUROFactory.sol
Interface: IStQEUROFactory.sol
Inherits: AccessControlUpgradeable, SecureUpgradeable

Function Signatures

registerVault(uint256 vaultId, string vaultName) -> (address stQEUROToken_)

function registerVault(uint256 vaultId, string calldata vaultName) external returns (address stQEUROToken_);

Modifiers: onlyRole(VAULT_FACTORY_ROLE)
Events: VaultRegistered(uint256 indexed vaultId, address indexed vault, address indexed stQEUROToken, string vaultName)
Requirements:

• vaultId > 0
• vaultName uppercase alphanumeric with length 1..12
• unique vaultId, unique caller vault, unique vaultName
• strict self-registration semantics: caller vault is inferred from msg.sender

getStQEUROByVaultId(uint256 vaultId) -> (address)

function getStQEUROByVaultId(uint256 vaultId) external view returns (address stQEUROToken_);

getStQEUROByVault(address vault) -> (address)

function getStQEUROByVault(address vault) external view returns (address stQEUROToken_);

getVaultById(uint256 vaultId) -> (address)

function getVaultById(uint256 vaultId) external view returns (address vault);

getVaultIdByStQEURO(address stQEUROToken_) -> (uint256)

function getVaultIdByStQEURO(address stQEUROToken_) external view returns (uint256 vaultId);

getVaultName(uint256 vaultId) -> (string)

function getVaultName(uint256 vaultId) external view returns (string memory vaultName);

updateYieldShift(address) / updateTokenImplementation(address) / updateOracle(address) / updateTreasury(address) / updateTokenAdmin(address)

Governance configuration setters affecting future vault token deployments and defaults.

stQEUROToken

Contract: stQEUROToken.sol
Interface: IstQEURO.sol
Inherits: ERC20Upgradeable, AccessControlUpgradeable, PausableUpgradeable

Function Signatures

stake(uint256 qeuroAmount)

function stake(uint256 qeuroAmount) external

Modifiers: whenNotPaused, nonReentrant
Events: QEUROStaked(address indexed user, uint256 qeuroAmount, uint256 stQeuroAmount)
Requirements:

• qeuroAmount > 0
• Sufficient QEURO balance and allowance

unstake(uint256 stQeuroAmount)

function unstake(uint256 stQeuroAmount) external

Modifiers: whenNotPaused, nonReentrant
Events: QEUROUnstaked(address indexed user, uint256 stQeuroAmount, uint256 qeuroAmount)
Requirements:

• stQeuroAmount > 0
• Sufficient stQEURO balance

claimYield() → (uint256)

function claimYield() external returns (uint256 yieldAmount)

Modifiers: whenNotPaused, nonReentrant
Events: YieldClaimed(address indexed user, uint256 amount)

getExchangeRate() → (uint256)

function getExchangeRate() external view returns (uint256 rate)

Returns: Exchange rate between stQEURO and QEURO (18 decimals)

getQEUROEquivalent(uint256 stQeuroAmount) → (uint256)

function getQEUROEquivalent(uint256 stQeuroAmount) external view returns (uint256 qeuroAmount)

distributeYield(uint256 qeuroAmount)

function distributeYield(uint256 qeuroAmount) external

Modifiers: onlyRole(YIELD_MANAGER_ROLE)
Events: YieldDistributed(uint256 totalAmount, uint256 timestamp)
Requirements:

• qeuroAmount > 0
• Sufficient QEURO balance

initialize(...) (metadata overload for factory)

stQEUROToken now supports an overloaded initializer that accepts:

• tokenName
• tokenSymbol
• vaultName

This overload is used by stQEUROFactory when deploying a dedicated proxy per vault.

AaveVault

Contract: AaveVault.sol
Interface: IAaveVault.sol
Inherits: SecureUpgradeable, PausableUpgradeable

Function Signatures

deployToAave(uint256 usdcAmount)

function deployToAave(uint256 usdcAmount) external

Modifiers: onlyRole(YIELD_MANAGER_ROLE), whenNotPaused, nonReentrant
Events: USDCDepositedToAave(uint256 amount)
Requirements:

• usdcAmount > 0
• Within exposure limits
• Sufficient USDC balance

withdrawFromAave(uint256 usdcAmount)

function withdrawFromAave(uint256 usdcAmount) external

Modifiers: onlyRole(YIELD_MANAGER_ROLE), whenNotPaused, nonReentrant
Events: USDCWithdrawnFromAave(uint256 amount)

harvestAaveYield() → (uint256)

function harvestAaveYield() external returns (uint256 yieldAmount)

Modifiers: onlyRole(YIELD_MANAGER_ROLE), whenNotPaused, nonReentrant
Events: AaveYieldHarvested(uint256 amount) Notes:

• Reverts if yieldVaultId == 0
• Routes harvested amount through yieldShift.addYield(yieldVaultId, netYield, bytes32("aave"))

setYieldVaultId(uint256 newYieldVaultId)

function setYieldVaultId(uint256 newYieldVaultId) external

Modifiers: onlyRole(GOVERNANCE_ROLE)
Requirements:

• newYieldVaultId > 0

updateYieldShift(address newYieldShift)

function updateYieldShift(address newYieldShift) external

Modifiers: onlyRole(GOVERNANCE_ROLE)

getAaveBalance() → (uint256)

function getAaveBalance() external view returns (uint256 balance)

getAaveAPY() → (uint256)

function getAaveAPY() external view returns (uint256 apy)

Returns: APY in basis points

autoRebalance() → (bool, uint256, uint256)

function autoRebalance() external returns (
    bool rebalanced,
    uint256 newAllocation,
    uint256 expectedYield
)

YieldShift

Contract: YieldShift.sol
Interface: IYieldShift.sol
Inherits: SecureUpgradeable, PausableUpgradeable

Function Signatures

addYield(uint256 vaultId, uint256 yieldAmount, bytes32 source)

function addYield(uint256 vaultId, uint256 yieldAmount, bytes32 source) external

Modifiers: onlyAuthorizedYieldSource, whenNotPaused, nonReentrant
Events: YieldAdded(uint256 yieldAmount, string indexed source, uint256 indexed timestamp)
Requirements:

• vaultId > 0 and vault must be registered in stQEUROFactory
• yieldAmount > 0
• Sufficient USDC balance and allowance

updateYieldDistribution()

function updateYieldDistribution() external

Modifiers: whenNotPaused, nonReentrant
Events: YieldDistributionUpdated(uint256 userPoolYield, uint256 hedgerPoolYield, uint256 currentShift)

claimUserYield(address user) → (uint256)

function claimUserYield(address user) external returns (uint256 yieldAmount)

Modifiers: whenNotPaused, nonReentrant
Events: UserYieldClaimed(address indexed user, uint256 yieldAmount, uint256 timestamp)

claimHedgerYield(address hedger) → (uint256)

function claimHedgerYield(address hedger) external returns (uint256 yieldAmount)

Modifiers: whenNotPaused, nonReentrant
Events: HedgerYieldClaimed(address indexed hedger, uint256 yieldAmount, uint256 timestamp)

getPoolMetrics() → (uint256, uint256, uint256, uint256)

function getPoolMetrics() external view returns (
    uint256 userPoolSize,
    uint256 hedgerPoolSize,
    uint256 poolRatio,
    uint256 targetRatio
)

calculateOptimalYieldShift() → (uint256, uint256)

function calculateOptimalYieldShift() external view returns (
    uint256 optimalShift,
    uint256 currentDeviation
)

configureYieldModel(YieldModelConfig cfg)

Batch governance setter for:

• baseYieldShift
• maxYieldShift
• adjustmentSpeed
• targetPoolRatio

configureDependencies(YieldDependencyConfig cfg)

Batch governance setter for:

• userPool
• hedgerPool
• aaveVault
• stQEUROFactory
• treasury

setYieldSourceAuthorization(address source, bytes32 yieldType, bool authorized)

Governance setter to authorize/revoke a yield source and bind source type.

currentYieldShift(), userPendingYield(address), hedgerPendingYield(address), paused()

Direct state getters used by integrations and indexers.

ChainlinkOracle

Contract: ChainlinkOracle.sol
Interface: IChainlinkOracle.sol
Inherits: SecureUpgradeable, PausableUpgradeable

Function Signatures

getEurUsdPrice() → (uint256, bool)

function getEurUsdPrice() external view returns (uint256 price, bool isValid)

Returns:

• price: EUR/USD price (8 decimals)
• isValid: Whether price is fresh and valid

getUsdcUsdPrice() → (uint256, bool)

function getUsdcUsdPrice() external view returns (uint256 price, bool isValid)

Returns:

• price: USDC/USD price (8 decimals)
• isValid: Whether price is fresh and valid

updatePriceFeeds(address eurUsdFeed, address usdcUsdFeed)

function updatePriceFeeds(address eurUsdFeed, address usdcUsdFeed) external

Modifiers: onlyRole(ADMIN_ROLE)
Events: PriceFeedsUpdated(address eurUsdFeed, address usdcUsdFeed)
Requirements:

• eurUsdFeed != address(0)
• usdcUsdFeed != address(0)

updatePriceBounds(uint256 minPrice, uint256 maxPrice)

function updatePriceBounds(uint256 minPrice, uint256 maxPrice) external

Modifiers: onlyRole(ADMIN_ROLE)
Events: PriceBoundsUpdated(uint256 minPrice, uint256 maxPrice)
Requirements:

• minPrice < maxPrice

triggerCircuitBreaker()

function triggerCircuitBreaker() external

Modifiers: onlyRole(EMERGENCY_ROLE)
Events: CircuitBreakerTriggered(uint256 timestamp)

resetCircuitBreaker()

function resetCircuitBreaker() external

Modifiers: onlyRole(ADMIN_ROLE)
Events: CircuitBreakerReset(uint256 timestamp)

Access Control Roles

Constants and Limits

QuantillonVault

• MAX_MINT_AMOUNT: 1,000,000 USDC
• MIN_MINT_AMOUNT: 1 USDC
• MAX_REDEEM_AMOUNT: 1,000,000 QEURO
• MIN_REDEEM_AMOUNT: 1 QEURO

QEUROToken

• MAX_SUPPLY: 1,000,000,000 QEURO (1B tokens)
• MIN_PRICE_PRECISION: 2 decimals
• MAX_PRICE_PRECISION: 8 decimals

QTIToken

• MIN_LOCK_TIME: 1 week (604,800 seconds)
• MAX_LOCK_TIME: 4 years (126,144,000 seconds)
• MIN_PROPOSAL_POWER: 1,000 veQTI
• VOTING_PERIOD: 7 days (604,800 seconds)

UserPool

• MIN_STAKE_AMOUNT: 100 QEURO
• MAX_STAKE_AMOUNT: 10,000,000 QEURO
• UNSTAKE_COOLDOWN: 7 days (604,800 seconds)

HedgerPool

• MAX_LEVERAGE: 10x
• MIN_LEVERAGE: 1x
• MIN_MARGIN_RATIO: 110% (1.1)
• LIQUIDATION_THRESHOLD: 105% (1.05)
• MAX_POSITIONS_PER_HEDGER: 50

AaveVault

• MAX_AAVE_EXPOSURE: 80% of total USDC
• MIN_AAVE_EXPOSURE: 0%
• REBALANCE_THRESHOLD: 5% deviation

Error Handling

All functions use custom errors for gas efficiency. Common error patterns:

// Revert with custom error
if (condition) revert CustomError();

// Emit event and revert
emit EventName();
revert CustomError();

Error Categories

1. Access Control Errors

   • UnauthorizedAccess()
   • InsufficientRole()
   • InvalidRole()

2. Validation Errors

   • InvalidAmount()
   • InvalidAddress()
   • InvalidParameter()
   • InvalidTime()

3. Business Logic Errors

   • InsufficientBalance()
   • InsufficientAllowance()
   • ExceedsLimit()
   • BelowMinimum()

4. Oracle Errors

   • StalePrice()
   • InvalidPrice()
   • CircuitBreakerActive()

5. Emergency Errors

   • ContractPaused()
   • EmergencyMode()

Gas Optimization

Best Practices

1. Use view functions for read-only operations
2. Batch operations when possible
3. Cache storage reads in loops
4. Use events instead of storage for logging
5. Implement proper access control to prevent unauthorized calls

Gas Estimates

Gas costs are estimates and may vary based on network conditions.

Integration Patterns

Frontend Integration

// Web3.js example
const contract = new web3.eth.Contract(abi, address);

// Call view function
const result = await contract.methods.getVaultMetrics().call();

// Send transaction
const tx = await contract.methods.mintQEURO(usdcAmount, minQeuroOut)
    .send({ from: userAddress });

Backend Integration

# Web3.py example
from web3 import Web3

w3 = Web3(Web3.HTTPProvider(rpc_url))
contract = w3.eth.contract(address=contract_address, abi=abi)

# Call view function
result = contract.functions.getVaultMetrics().call()

# Send transaction
tx_hash = contract.functions.mintQEURO(usdc_amount, min_qeuro_out).transact({
    'from': user_address
})

This technical reference is maintained by Quantillon Labs and updated with each protocol version.

Quantillon Protocol Quick Start Guide

Getting Started

This guide will help you quickly integrate with the Quantillon Protocol smart contracts.

Prerequisites

• Node.js 18+ and npm/yarn
• Web3 library (web3.js, ethers.js, or web3.py)
• Ethereum wallet (MetaMask, WalletConnect, etc.)
• USDC tokens for testing

Installation

JavaScript/TypeScript

npm install ethers
# or
yarn add ethers

Python

pip install web3

Basic Integration

1. Connect to the Protocol

import { ethers } from 'ethers';

// Contract ABIs (you'll need to import these from the compiled contracts)
import QuantillonVaultABI from './abis/QuantillonVault.json';
import QEUROTokenABI from './abis/QEUROToken.json';
import UserPoolABI from './abis/UserPool.json';

// Initialize contracts
const vault = new ethers.Contract(vaultAddress, QuantillonVaultABI, provider);
const qeuro = new ethers.Contract(qeuroAddress, QEUROTokenABI, provider);
const userPool = new ethers.Contract(userPoolAddress, UserPoolABI, provider);

2. Mint QEURO

// Approve USDC spending
await usdc.approve(vaultAddress, usdcAmount);

// Mint QEURO with slippage protection
const minQeuroOut = usdcAmount * 0.95; // 5% slippage tolerance
await vault.mintQEURO(usdcAmount, minQeuroOut);

3. Stake QEURO for Rewards

// Approve QEURO spending
await qeuro.approve(userPoolAddress, qeuroAmount);

// Stake QEURO
await userPool.stake(qeuroAmount);

// Claim rewards later
const rewards = await userPool.claimStakingRewards();

4. Participate in Governance

// Lock QTI for voting power
await qti.lock(lockAmount, lockDuration);

// Create a proposal
const proposalId = await qti.createProposal(
    "Update protocol parameters",
    startTime,
    endTime
);

// Vote on proposal
await qti.vote(proposalId, true); // Vote yes

Common Patterns

Error Handling

try {
    await vault.mintQEURO(usdcAmount, minQeuroOut);
} catch (error) {
    if (error.message.includes('InsufficientBalance')) {
        console.log('Insufficient USDC balance');
    } else if (error.message.includes('StalePrice')) {
        console.log('Oracle price is stale');
    } else {
        console.log('Transaction failed:', error.message);
    }
}

Event Listening

// Listen for mint events
vault.on('QEUROMinted', (user, usdcAmount, qeuroAmount, price) => {
    console.log(`User ${user} minted ${qeuroAmount} QEURO for ${usdcAmount} USDC`);
});

// Listen for stake events
userPool.on('QEUROStaked', (user, amount) => {
    console.log(`User ${user} staked ${amount} QEURO`);
});

Batch Operations

// Batch multiple operations
const batch = [
    usdc.approve(vaultAddress, usdcAmount),
    vault.mintQEURO(usdcAmount, minQeuroOut),
    qeuro.approve(userPoolAddress, qeuroAmount),
    userPool.stake(qeuroAmount)
];

await Promise.all(batch);

Testing

Local Development

# Clone the repository
git clone https://github.com/Quantillon-Labs/smart-contracts.git
cd smart-contracts/quantillon-protocol

# Install dependencies
forge install

# Build contracts
forge build

# Run tests
forge test

# Run specific test
forge test --match-contract QEUROToken

# Run security analysis
make security  # Runs both Slither and Mythril

Security Best Practices

1. Always Validate Inputs

// Validate amounts
if (usdcAmount <= 0) {
    throw new Error('Invalid USDC amount');
}

// Validate addresses
if (!ethers.utils.isAddress(userAddress)) {
    throw new Error('Invalid address');
}

2. Use Slippage Protection

// Calculate minimum output with slippage
const slippage = 0.05; // 5%
const minQeuroOut = expectedQeuro * (1 - slippage);

3. Check Contract State

// Check if contract is paused
const isPaused = await vault.paused();
if (isPaused) {
    throw new Error('Contract is paused');
}

// Check oracle price freshness
const [price, isValid] = await oracle.getEurUsdPrice();
if (!isValid) {
    throw new Error('Oracle price is invalid');
}

4. Implement Proper Error Handling

// Retry mechanism for failed transactions
async function retryTransaction(txFunction, maxRetries = 3) {
    for (let i = 0; i < maxRetries; i++) {
        try {
            return await txFunction();
        } catch (error) {
            if (i === maxRetries - 1) throw error;
            await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
        }
    }
}

5. Security Analysis

# Run comprehensive security analysis
make security

# Run individual tools
make slither    # Static analysis
make mythril    # Symbolic execution analysis

# Check security reports
ls scripts/results/mythril-reports/   # Mythril reports
ls scripts/results/slither/           # Slither reports
cat scripts/results/natspec-validation-report.txt
cat scripts/results/contract-sizes/contract-sizes-summary.txt

Advanced Features

Yield Optimization

// Check yield opportunities
const userPoolAPY = await userPool.getStakingAPY();
const hedgerPoolAPY = await hedgerPool.getHedgingAPY();

if (userPoolAPY > hedgerPoolAPY) {
    // Stake in user pool
    await userPool.stake(qeuroAmount);
} else {
    // Open hedge position
    await hedgerPool.enterHedgePosition(marginAmount, leverage);
}

Risk Management

// Monitor position health
const positionInfo = await hedgerPool.getPositionInfo(positionId);
const marginRatio = positionInfo.margin / positionInfo.positionSize;

if (marginRatio < 1.1) {
    console.warn('Position is near liquidation threshold');
    // Add margin or close position
}

Governance Participation

// Check voting power
const votingPower = await qti.getVotingPower(userAddress);
const minPower = await qti.MIN_PROPOSAL_POWER();

if (votingPower >= minPower) {
    // Can create proposals
    const proposalId = await qti.createProposal(description, startTime, endTime);
}

Troubleshooting

Common Issues

1. "Insufficient allowance"

   • Solution: Approve token spending before calling functions

2. "Contract paused"

   • Solution: Wait for contract to be unpaused or check with protocol team

3. "Stale oracle price"

   • Solution: Wait for oracle to update or check oracle configuration

4. "Gas estimation failed"

   • Solution: Increase gas limit or check transaction parameters

Debug Mode

// Enable debug logging
const vault = new QuantillonVault(vaultAddress, provider, { debug: true });

// Check transaction details
const tx = await vault.mintQEURO(usdcAmount, minQeuroOut);
console.log('Transaction hash:', tx.hash);
console.log('Gas used:', tx.gasUsed);

Support

Resources

• Documentation: docs.quantillon.money
• GitHub: github.com/Quantillon-Labs
• Discord: discord.gg/uk8T9GqdE5
• Email: team@quantillon.money

Community

• Telegram: t.me/quantillon
• Twitter: @QuantillonLabs
• Medium: medium.com/@quantillonlabs

Examples

Complete Integration Example

import { ethers } from 'ethers';

class QuantillonIntegration {
    constructor(provider, signer) {
        this.provider = provider;
        this.signer = signer;
        this.vault = new ethers.Contract(VAULT_ADDRESS, QuantillonVaultABI, signer);
        this.qeuro = new ethers.Contract(QEURO_ADDRESS, QEUROTokenABI, signer);
        this.userPool = new ethers.Contract(USER_POOL_ADDRESS, UserPoolABI, signer);
    }

    async mintQEURO(usdcAmount, slippage = 0.05) {
        try {
            // Check contract state
            if (await this.vault.paused()) {
                throw new Error('Contract is paused');
            }

            // Calculate minimum output
            const expectedQeuro = await this.vault.calculateMintAmount(usdcAmount);
            const minQeuroOut = expectedQeuro.mul(100 - slippage * 100).div(100);

            // Approve USDC spending
            const usdc = new ethers.Contract(USDC_ADDRESS, USDC_ABI, this.signer);
            await usdc.approve(VAULT_ADDRESS, usdcAmount);

            // Mint QEURO
            const tx = await this.vault.mintQEURO(usdcAmount, minQeuroOut);
            await tx.wait();

            console.log('QEURO minted successfully');
            return tx;
        } catch (error) {
            console.error('Minting failed:', error.message);
            throw error;
        }
    }

    async stakeQEURO(qeuroAmount) {
        try {
            // Approve QEURO spending
            await this.qeuro.approve(USER_POOL_ADDRESS, qeuroAmount);

            // Stake QEURO
            const tx = await this.userPool.stake(qeuroAmount);
            await tx.wait();

            console.log('QEURO staked successfully');
            return tx;
        } catch (error) {
            console.error('Staking failed:', error.message);
            throw error;
        }
    }

    async getPortfolio(userAddress) {
        try {
            const [vaultMetrics, userInfo, qeuroBalance] = await Promise.all([
                this.vault.getVaultMetrics(),
                this.userPool.getUserInfo(userAddress),
                this.qeuro.balanceOf(userAddress)
            ]);

            return {
                qeuroBalance: qeuroBalance.toString(),
                stakedAmount: userInfo.stakedQeuro.toString(),
                pendingRewards: userInfo.pendingRewards.toString(),
                totalDeposits: userInfo.depositedUsdc.toString(),
                vaultMetrics: {
                    totalReserves: vaultMetrics.totalUsdcReserves.toString(),
                    totalSupply: vaultMetrics.totalQeuroSupply.toString(),
                    collateralizationRatio: vaultMetrics.collateralizationRatio.toString()
                }
            };
        } catch (error) {
            console.error('Failed to get portfolio:', error.message);
            throw error;
        }
    }
}

// Usage
const integration = new QuantillonIntegration(provider, signer);
await integration.mintQEURO(ethers.utils.parseUnits('1000', 6)); // 1000 USDC
await integration.stakeQEURO(ethers.utils.parseUnits('500', 18)); // 500 QEURO
const portfolio = await integration.getPortfolio(userAddress);

This quick start guide is maintained by Quantillon Labs and updated regularly.

Quantillon Protocol Integration Examples

This document provides practical integration examples for common use cases with the Quantillon Protocol.

Table of Contents

1. Basic QEURO Operations
2. Staking and Yield Generation
3. Governance Participation
4. Hedging Operations
5. Advanced Integration Patterns
6. Error Handling and Recovery

Basic QEURO Operations

Minting QEURO from USDC

const { ethers } = require('ethers');

async function mintQEURO(usdcAmount, slippage = 0.05) {
    // Initialize contracts
    const vault = new ethers.Contract(VAULT_ADDRESS, VAULT_ABI, signer);
    const usdc = new ethers.Contract(USDC_ADDRESS, USDC_ABI, signer);
    
    try {
        // 1. Check vault state
        const isPaused = await vault.paused();
        if (isPaused) {
            throw new Error('Vault is paused');
        }
        
        // 2. Calculate expected output
        const expectedQeuro = await vault.calculateMintAmount(usdcAmount);
        const minQeuroOut = expectedQeuro.mul(100 - slippage * 100).div(100);
        
        // 3. Approve USDC spending
        const approveTx = await usdc.approve(VAULT_ADDRESS, usdcAmount);
        await approveTx.wait();
        
        // 4. Mint QEURO
        const mintTx = await vault.mintQEURO(usdcAmount, minQeuroOut);
        const receipt = await mintTx.wait();
        
        // 5. Parse events
        const mintEvent = receipt.events.find(e => e.event === 'QEUROMinted');
        console.log(`Minted ${mintEvent.args.qeuroAmount} QEURO for ${mintEvent.args.usdcAmount} USDC`);
        
        return receipt;
    } catch (error) {
        console.error('Minting failed:', error.message);
        throw error;
    }
}

// Usage
const usdcAmount = ethers.utils.parseUnits('1000', 6); // 1000 USDC
await mintQEURO(usdcAmount, 0.05); // 5% slippage tolerance

Redeeming QEURO for USDC

async function redeemQEURO(qeuroAmount, slippage = 0.05) {
    const vault = new ethers.Contract(VAULT_ADDRESS, VAULT_ABI, signer);
    const qeuro = new ethers.Contract(QEURO_ADDRESS, QEURO_ABI, signer);
    
    try {
        // 1. Calculate expected output
        const expectedUsdc = await vault.calculateRedeemAmount(qeuroAmount);
        const minUsdcOut = expectedUsdc.mul(100 - slippage * 100).div(100);
        
        // 2. Approve QEURO spending
        const approveTx = await qeuro.approve(VAULT_ADDRESS, qeuroAmount);
        await approveTx.wait();
        
        // 3. Redeem QEURO
        const redeemTx = await vault.redeemQEURO(qeuroAmount, minUsdcOut);
        const receipt = await redeemTx.wait();
        
        // 4. Parse events
        const redeemEvent = receipt.events.find(e => e.event === 'QEURORedeemed');
        console.log(`Redeemed ${redeemEvent.args.qeuroAmount} QEURO for ${redeemEvent.args.usdcAmount} USDC`);
        
        return receipt;
    } catch (error) {
        console.error('Redemption failed:', error.message);
        throw error;
    }
}

Staking and Yield Generation

Staking QEURO in User Pool

async function stakeQEURO(qeuroAmount) {
    const userPool = new ethers.Contract(USER_POOL_ADDRESS, USER_POOL_ABI, signer);
    const qeuro = new ethers.Contract(QEURO_ADDRESS, QEURO_ABI, signer);
    
    try {
        // 1. Check minimum stake amount
        const minStakeAmount = await userPool.MIN_STAKE_AMOUNT();
        if (qeuroAmount.lt(minStakeAmount)) {
            throw new Error(`Amount below minimum stake: ${minStakeAmount}`);
        }
        
        // 2. Check user's QEURO balance
        const balance = await qeuro.balanceOf(signer.address);
        if (balance.lt(qeuroAmount)) {
            throw new Error('Insufficient QEURO balance');
        }
        
        // 3. Approve QEURO spending
        const approveTx = await qeuro.approve(USER_POOL_ADDRESS, qeuroAmount);
        await approveTx.wait();
        
        // 4. Stake QEURO
        const stakeTx = await userPool.stake(qeuroAmount);
        const receipt = await stakeTx.wait();
        
        console.log(`Staked ${qeuroAmount} QEURO successfully`);
        return receipt;
    } catch (error) {
        console.error('Staking failed:', error.message);
        throw error;
    }
}

Claiming Staking Rewards

async function claimStakingRewards() {
    const userPool = new ethers.Contract(USER_POOL_ADDRESS, USER_POOL_ABI, signer);
    
    try {
        // 1. Check pending rewards
        const userInfo = await userPool.getUserInfo(signer.address);
        const pendingRewards = userInfo.pendingRewards;
        
        if (pendingRewards.eq(0)) {
            console.log('No rewards to claim');
            return null;
        }
        
        // 2. Claim rewards
        const claimTx = await userPool.claimStakingRewards();
        const receipt = await claimTx.wait();
        
        // 3. Parse events
        const claimEvent = receipt.events.find(e => e.event === 'RewardsClaimed');
        console.log(`Claimed ${claimEvent.args.amount} QEURO rewards`);
        
        return receipt;
    } catch (error) {
        console.error('Claiming rewards failed:', error.message);
        throw error;
    }
}

Staking in stQEURO Token

async function stakeInStQEURO(qeuroAmount) {
    const stQeuro = new ethers.Contract(ST_QEURO_ADDRESS, ST_QEURO_ABI, signer);
    const qeuro = new ethers.Contract(QEURO_ADDRESS, QEURO_ABI, signer);
    
    try {
        // 1. Get current exchange rate
        const exchangeRate = await stQeuro.getExchangeRate();
        const expectedStQeuro = qeuroAmount.mul(ethers.utils.parseEther('1')).div(exchangeRate);
        
        // 2. Approve QEURO spending
        const approveTx = await qeuro.approve(ST_QEURO_ADDRESS, qeuroAmount);
        await approveTx.wait();
        
        // 3. Stake QEURO
        const stakeTx = await stQeuro.stake(qeuroAmount);
        const receipt = await stakeTx.wait();
        
        console.log(`Staked ${qeuroAmount} QEURO, received ${expectedStQeuro} stQEURO`);
        return receipt;
    } catch (error) {
        console.error('stQEURO staking failed:', error.message);
        throw error;
    }
}

Governance Participation

Locking QTI for Voting Power

async function lockQTI(amount, lockDuration) {
    const qti = new ethers.Contract(QTI_ADDRESS, QTI_ABI, signer);
    
    try {
        // 1. Check lock duration limits
        const minLockTime = await qti.MIN_LOCK_TIME();
        const maxLockTime = await qti.MAX_LOCK_TIME();
        
        if (lockDuration.lt(minLockTime) || lockDuration.gt(maxLockTime)) {
            throw new Error(`Lock duration must be between ${minLockTime} and ${maxLockTime} seconds`);
        }
        
        // 2. Check QTI balance
        const balance = await qti.balanceOf(signer.address);
        if (balance.lt(amount)) {
            throw new Error('Insufficient QTI balance');
        }
        
        // 3. Lock QTI
        const lockTx = await qti.lock(amount, lockDuration);
        const receipt = await lockTx.wait();
        
        // 4. Parse events
        const lockEvent = receipt.events.find(e => e.event === 'TokensLocked');
        console.log(`Locked ${amount} QTI for ${lockDuration} seconds, received ${lockEvent.args.votingPower} veQTI`);
        
        return receipt;
    } catch (error) {
        console.error('QTI locking failed:', error.message);
        throw error;
    }
}

Creating a Governance Proposal

async function createProposal(description, startTime, endTime) {
    const qti = new ethers.Contract(QTI_ADDRESS, QTI_ABI, signer);
    
    try {
        // 1. Check voting power
        const votingPower = await qti.getVotingPower(signer.address);
        const minProposalPower = await qti.MIN_PROPOSAL_POWER();
        
        if (votingPower.lt(minProposalPower)) {
            throw new Error(`Insufficient voting power. Required: ${minProposalPower}, Current: ${votingPower}`);
        }
        
        // 2. Validate time parameters
        const currentTime = Math.floor(Date.now() / 1000);
        if (startTime <= currentTime || endTime <= startTime) {
            throw new Error('Invalid time parameters');
        }
        
        // 3. Create proposal
        const proposalTx = await qti.createProposal(description, startTime, endTime);
        const receipt = await proposalTx.wait();
        
        // 4. Parse events
        const proposalEvent = receipt.events.find(e => e.event === 'ProposalCreated');
        console.log(`Created proposal ${proposalEvent.args.proposalId}: ${description}`);
        
        return proposalEvent.args.proposalId;
    } catch (error) {
        console.error('Proposal creation failed:', error.message);
        throw error;
    }
}

Voting on Proposals

async function voteOnProposal(proposalId, support) {
    const qti = new ethers.Contract(QTI_ADDRESS, QTI_ABI, signer);
    
    try {
        // 1. Check voting power
        const votingPower = await qti.getVotingPower(signer.address);
        if (votingPower.eq(0)) {
            throw new Error('No voting power available');
        }
        
        // 2. Check if already voted
        const hasVoted = await qti.hasVoted(proposalId, signer.address);
        if (hasVoted) {
            throw new Error('Already voted on this proposal');
        }
        
        // 3. Vote
        const voteTx = await qti.vote(proposalId, support);
        const receipt = await voteTx.wait();
        
        // 4. Parse events
        const voteEvent = receipt.events.find(e => e.event === 'VoteCast');
        console.log(`Voted ${support ? 'YES' : 'NO'} on proposal ${proposalId} with ${voteEvent.args.votingPower} voting power`);
        
        return receipt;
    } catch (error) {
        console.error('Voting failed:', error.message);
        throw error;
    }
}

Hedging Operations

Opening a Hedge Position

async function openHedgePosition(marginAmount, leverage) {
    const hedgerPool = new ethers.Contract(HEDGER_POOL_ADDRESS, HEDGER_POOL_ABI, signer);
    const usdc = new ethers.Contract(USDC_ADDRESS, USDC_ABI, signer);
    
    try {
        // 1. Validate leverage
        const maxLeverage = await hedgerPool.maxLeverage();
        if (leverage.lt(1) || leverage.gt(maxLeverage)) {
            throw new Error(`Leverage must be between 1 and ${maxLeverage}`);
        }
        
        // 2. Check USDC balance
        const balance = await usdc.balanceOf(signer.address);
        if (balance.lt(marginAmount)) {
            throw new Error('Insufficient USDC balance');
        }
        
        // 3. Approve USDC spending
        const approveTx = await usdc.approve(HEDGER_POOL_ADDRESS, marginAmount);
        await approveTx.wait();
        
        // 4. Open position
        const openTx = await hedgerPool.enterHedgePosition(marginAmount, leverage);
        const receipt = await openTx.wait();
        
        // 5. Parse events
        const openEvent = receipt.events.find(e => e.event === 'HedgePositionOpened');
        console.log(`Opened position ${openEvent.args.positionId} with ${marginAmount} USDC margin and ${leverage}x leverage`);
        
        return openEvent.args.positionId;
    } catch (error) {
        console.error('Opening position failed:', error.message);
        throw error;
    }
}

Monitoring Position Health

async function monitorPosition(positionId) {
    const hedgerPool = new ethers.Contract(HEDGER_POOL_ADDRESS, HEDGER_POOL_ABI, signer);
    
    try {
        // 1. Get position info
        const positionInfo = await hedgerPool.getPositionInfo(positionId);
        
        // 2. Calculate margin ratio
        const marginRatio = positionInfo.margin.mul(10000).div(positionInfo.positionSize);
        const liquidationThreshold = await hedgerPool.liquidationThreshold();
        
        // 3. Check if position is healthy
        const isHealthy = marginRatio.gt(liquidationThreshold);
        
        console.log(`Position ${positionId}:`);
        console.log(`  Margin: ${ethers.utils.formatUnits(positionInfo.margin, 6)} USDC`);
        console.log(`  Position Size: ${ethers.utils.formatUnits(positionInfo.positionSize, 6)} USDC`);
        console.log(`  Margin Ratio: ${marginRatio.toNumber() / 100}%`);
        console.log(`  Unrealized PnL: ${ethers.utils.formatEther(positionInfo.unrealizedPnL)} QEURO`);
        console.log(`  Status: ${isHealthy ? 'HEALTHY' : 'AT RISK'}`);
        
        return {
            positionInfo,
            marginRatio,
            isHealthy
        };
    } catch (error) {
        console.error('Position monitoring failed:', error.message);
        throw error;
    }
}

Adding Margin to Position

async function addMargin(positionId, additionalMargin) {
    const hedgerPool = new ethers.Contract(HEDGER_POOL_ADDRESS, HEDGER_POOL_ABI, signer);
    const usdc = new ethers.Contract(USDC_ADDRESS, USDC_ABI, signer);
    
    try {
        // 1. Check position ownership
        const positionInfo = await hedgerPool.getPositionInfo(positionId);
        if (positionInfo.hedger !== signer.address) {
            throw new Error('Not the owner of this position');
        }
        
        // 2. Check USDC balance
        const balance = await usdc.balanceOf(signer.address);
        if (balance.lt(additionalMargin)) {
            throw new Error('Insufficient USDC balance');
        }
        
        // 3. Approve USDC spending
        const approveTx = await usdc.approve(HEDGER_POOL_ADDRESS, additionalMargin);
        await approveTx.wait();
        
        // 4. Add margin
        const addMarginTx = await hedgerPool.addMargin(positionId, additionalMargin);
        const receipt = await addMarginTx.wait();
        
        console.log(`Added ${ethers.utils.formatUnits(additionalMargin, 6)} USDC margin to position ${positionId}`);
        return receipt;
    } catch (error) {
        console.error('Adding margin failed:', error.message);
        throw error;
    }
}

Advanced Integration Patterns

Portfolio Management

class QuantillonPortfolio {
    constructor(provider, signer) {
        this.provider = provider;
        this.signer = signer;
        this.vault = new ethers.Contract(VAULT_ADDRESS, VAULT_ABI, signer);
        this.qeuro = new ethers.Contract(QEURO_ADDRESS, QEURO_ABI, signer);
        this.userPool = new ethers.Contract(USER_POOL_ADDRESS, USER_POOL_ABI, signer);
        this.hedgerPool = new ethers.Contract(HEDGER_POOL_ADDRESS, HEDGER_POOL_ABI, signer);
    }
    
    async getPortfolioOverview() {
        const address = this.signer.address;
        
        try {
            const [
                qeuroBalance,
                userInfo,
                vaultMetrics,
                positions
            ] = await Promise.all([
                this.qeuro.balanceOf(address),
                this.userPool.getUserInfo(address),
                this.vault.getVaultMetrics(),
                this.getUserPositions()
            ]);
            
            return {
                balances: {
                    qeuro: ethers.utils.formatEther(qeuroBalance),
                    staked: ethers.utils.formatEther(userInfo.stakedQeuro),
                    deposited: ethers.utils.formatUnits(userInfo.depositedUsdc, 6)
                },
                rewards: {
                    pending: ethers.utils.formatEther(userInfo.pendingRewards),
                    claimed: ethers.utils.formatEther(userInfo.totalRewardsClaimed)
                },
                positions: positions,
                vault: {
                    totalReserves: ethers.utils.formatUnits(vaultMetrics.totalUsdcReserves, 6),
                    totalSupply: ethers.utils.formatEther(vaultMetrics.totalQeuroSupply),
                    collateralizationRatio: vaultMetrics.collateralizationRatio.toNumber() / 100
                }
            };
        } catch (error) {
            console.error('Failed to get portfolio overview:', error.message);
            throw error;
        }
    }
    
    async getUserPositions() {
        // Implementation to get user's hedge positions
        // This would require tracking position IDs or using events
        return [];
    }
    
    async optimizeYield() {
        try {
            const userPoolAPY = await this.userPool.getStakingAPY();
            const hedgerPoolAPY = await this.hedgerPool.getHedgingAPY();
            
            console.log(`User Pool APY: ${userPoolAPY.toNumber() / 100}%`);
            console.log(`Hedger Pool APY: ${hedgerPoolAPY.toNumber() / 100}%`);
            
            if (userPoolAPY.gt(hedgerPoolAPY)) {
                console.log('Recommendation: Stake in User Pool for higher yield');
            } else {
                console.log('Recommendation: Consider hedging for higher yield');
            }
        } catch (error) {
            console.error('Yield optimization failed:', error.message);
            throw error;
        }
    }
}

// Usage
const portfolio = new QuantillonPortfolio(provider, signer);
const overview = await portfolio.getPortfolioOverview();
console.log('Portfolio Overview:', overview);
await portfolio.optimizeYield();

Automated Yield Management

class YieldManager {
    constructor(provider, signer) {
        this.provider = provider;
        this.signer = signer;
        this.yieldShift = new ethers.Contract(YIELD_SHIFT_ADDRESS, YIELD_SHIFT_ABI, signer);
        this.aaveVault = new ethers.Contract(AAVE_VAULT_ADDRESS, AAVE_VAULT_ABI, signer);
    }
    
    async checkAndDistributeYield() {
        try {
            // 1. Check if yield distribution is needed
            const poolMetrics = await this.yieldShift.getPoolMetrics();
            const targetRatio = await this.yieldShift.targetPoolRatio();
            
            const currentRatio = poolMetrics.userPoolSize.mul(10000).div(poolMetrics.hedgerPoolSize);
            const deviation = currentRatio.sub(targetRatio).abs();
            const threshold = await this.yieldShift.rebalanceThreshold();
            
            if (deviation.gt(threshold)) {
                console.log('Pool ratio deviation detected, distributing yield...');
                await this.yieldShift.distributeYield();
            }
        } catch (error) {
            console.error('Yield distribution failed:', error.message);
            throw error;
        }
    }
    
    async harvestAaveYield() {
        try {
            const yieldAmount = await this.aaveVault.harvestAaveYield();
            console.log(`Harvested ${ethers.utils.formatEther(yieldAmount)} QEURO from Aave`);
            return yieldAmount;
        } catch (error) {
            console.error('Aave yield harvest failed:', error.message);
            throw error;
        }
    }
    
    async autoRebalance() {
        try {
            const [rebalanced, newAllocation, expectedYield] = await this.aaveVault.autoRebalance();
            
            if (rebalanced) {
                console.log(`Rebalanced to ${newAllocation.toNumber() / 100}% allocation`);
                console.log(`Expected yield: ${ethers.utils.formatEther(expectedYield)} QEURO`);
            } else {
                console.log('No rebalancing needed');
            }
            
            return { rebalanced, newAllocation, expectedYield };
        } catch (error) {
            console.error('Auto rebalancing failed:', error.message);
            throw error;
        }
    }
}

Error Handling and Recovery

Comprehensive Error Handling

class QuantillonErrorHandler {
    static handleError(error) {
        const errorMessage = error.message.toLowerCase();
        
        if (errorMessage.includes('insufficient balance')) {
            return {
                type: 'INSUFFICIENT_BALANCE',
                message: 'Insufficient token balance for this operation',
                action: 'Check your token balance and try again'
            };
        } else if (errorMessage.includes('insufficient allowance')) {
            return {
                type: 'INSUFFICIENT_ALLOWANCE',
                message: 'Token allowance is insufficient',
                action: 'Approve token spending before calling this function'
            };
        } else if (errorMessage.includes('stale price')) {
            return {
                type: 'STALE_PRICE',
                message: 'Oracle price is stale',
                action: 'Wait for oracle to update or contact support'
            };
        } else if (errorMessage.includes('contract paused')) {
            return {
                type: 'CONTRACT_PAUSED',
                message: 'Contract is currently paused',
                action: 'Wait for contract to be unpaused'
            };
        } else if (errorMessage.includes('unauthorized')) {
            return {
                type: 'UNAUTHORIZED',
                message: 'Unauthorized access',
                action: 'Check your permissions and try again'
            };
        } else {
            return {
                type: 'UNKNOWN',
                message: error.message,
                action: 'Contact support if the issue persists'
            };
        }
    }
    
    static async retryOperation(operation, maxRetries = 3, delay = 1000) {
        for (let i = 0; i < maxRetries; i++) {
            try {
                return await operation();
            } catch (error) {
                const errorInfo = this.handleError(error);
                
                if (i === maxRetries - 1) {
                    throw new Error(`${errorInfo.type}: ${errorInfo.message}. ${errorInfo.action}`);
                }
                
                console.log(`Attempt ${i + 1} failed: ${errorInfo.message}. Retrying in ${delay}ms...`);
                await new Promise(resolve => setTimeout(resolve, delay));
                delay *= 2; // Exponential backoff
            }
        }
    }
}

// Usage
try {
    await QuantillonErrorHandler.retryOperation(async () => {
        return await vault.mintQEURO(usdcAmount, minQeuroOut);
    });
} catch (error) {
    console.error('Operation failed after retries:', error.message);
}

Transaction Monitoring

class TransactionMonitor {
    static async waitForConfirmation(tx, confirmations = 1) {
        try {
            console.log(`Transaction submitted: ${tx.hash}`);
            const receipt = await tx.wait(confirmations);
            console.log(`Transaction confirmed in block ${receipt.blockNumber}`);
            return receipt;
        } catch (error) {
            console.error(`Transaction failed: ${error.message}`);
            throw error;
        }
    }
    
    static async monitorGasPrice(provider, maxGasPrice) {
        const gasPrice = await provider.getGasPrice();
        if (gasPrice.gt(maxGasPrice)) {
            console.warn(`Gas price ${ethers.utils.formatUnits(gasPrice, 'gwei')} Gwei exceeds maximum ${ethers.utils.formatUnits(maxGasPrice, 'gwei')} Gwei`);
            return false;
        }
        return true;
    }
    
    static async estimateGasWithBuffer(contract, method, params, buffer = 1.2) {
        try {
            const gasEstimate = await contract.estimateGas[method](...params);
            return gasEstimate.mul(Math.floor(buffer * 100)).div(100);
        } catch (error) {
            console.error('Gas estimation failed:', error.message);
            throw error;
        }
    }
}

Best Practices

1. Always Check Contract State

// Check if contract is paused before any operation
const isPaused = await contract.paused();
if (isPaused) {
    throw new Error('Contract is paused');
}

2. Use Slippage Protection

// Always use slippage protection for swaps
const slippage = 0.05; // 5%
const minOutput = expectedOutput.mul(100 - slippage * 100).div(100);

3. Implement Proper Error Handling

// Use try-catch blocks and handle specific errors
try {
    await contract.function();
} catch (error) {
    const errorInfo = QuantillonErrorHandler.handleError(error);
    console.error(`${errorInfo.type}: ${errorInfo.message}`);
}

4. Monitor Events

// Listen for important events
contract.on('EventName', (param1, param2) => {
    console.log('Event received:', param1, param2);
});

5. Gas Optimization

// Estimate gas and add buffer
const gasEstimate = await contract.estimateGas.function(params);
const gasLimit = gasEstimate.mul(120).div(100); // 20% buffer

This integration examples guide is maintained by Quantillon Labs and updated regularly.

Quantillon Protocol Architecture

Overview

The Quantillon Protocol is a sophisticated DeFi ecosystem built around a euro-pegged stablecoin (QEURO) with advanced yield management and risk mitigation systems. The architecture is designed for scalability, security, and efficient capital utilization.

The staking layer now supports a multi-vault model through stQEUROFactory: each staking vault has its own non-fungible staking token instance (stQEURO{vaultName}).

System Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        SYSTEM ARCHITECTURE                      │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   User Layer    │    │ Protocol Layer  │    │  Yield Layer    │
├─────────────────┤    ├─────────────────┤    ├─────────────────┤
│ • Retail Users  │───▶│ • QuantillonVault│    │ • AaveVault     │
│ • Institutional │    │ • QEUROToken    │    │ • YieldShift    │
│ • Liquidity     │    │ • QTIToken      │    └─────────────────┘
│   Providers     │    │ • FeeCollector  │             │
└─────────────────┘    │ • UserPool      │             │
                       │ • HedgerPool    │             │
                       │ • stQEUROToken  │             │
                       └─────────────────┘             │
                                │                      │
                       ┌─────────────────┐             │
                       │Infrastructure   │             │
                       │Layer            │             │
                       ├─────────────────┤             │
                       │ • OracleRouter  │             │
                       │ • TimeProvider  │             │
                       │ • Security Libs │             │
                       └─────────────────┘             │
                                │                      │
                       ┌─────────────────┐             │
                       │External Systems │             │
                       ├─────────────────┤             │
                       │ • Aave Protocol │◀────────────┘
                       │ • Chainlink     │
                       │ • Stork Network │
                       │ • Base Network  │
                       └─────────────────┘

Core Components

1. QuantillonVault

Purpose: Central vault managing QEURO minting and redemption against USDC collateral.

Key Responsibilities:

• Overcollateralized QEURO minting
• USDC collateral management
• Oracle price validation
• Liquidation system
• Fee collection and distribution

Architecture Patterns:

• Proxy Pattern: Upgradeable implementation
• Access Control: Role-based permissions
• Reentrancy Protection: Secure external calls
• Circuit Breaker: Emergency pause mechanisms

2. QEUROToken

Purpose: Euro-pegged stablecoin with compliance and governance features.

Key Features:

• ERC-20 compliant with extensions
• Mint/burn controls via vault
• Compliance features (whitelist/blacklist)
• Rate limiting mechanisms
• Supply cap management

Architecture Patterns:

• Factory Pattern: Controlled token creation
• Observer Pattern: Event-driven compliance
• State Machine: Pause/unpause states

3. QTIToken

Purpose: Governance token with vote-escrow mechanics for protocol governance.

Key Features:

• Vote-escrow token mechanics
• Time-weighted voting power
• Governance proposal system
• Delegation capabilities
• Lock period management

Architecture Patterns:

• Escrow Pattern: Time-locked voting power
• Voting System: Proposal and execution framework
• Decay Function: Linear voting power decay

4. UserPool

Purpose: Manages user deposits, staking, and yield distribution.

Key Features:

• USDC deposit/withdrawal
• QEURO staking for rewards
• Yield distribution system
• User position tracking
• Reward calculation and claiming

Architecture Patterns:

• Pool Pattern: Centralized liquidity management
• Reward Distribution: Proportional yield allocation
• State Tracking: User position management

5. HedgerPool

Purpose: Manages leveraged hedging positions for risk management.

Key Features:

• EUR/USD hedging positions
• Margin management system
• Liquidation mechanisms
• Position tracking and PnL calculation
• Risk parameter management

Architecture Patterns:

• Position Management: Individual position tracking
• Margin System: Collateral and leverage management
• Liquidation Engine: Automated risk management
• Oracle Integration: Price feed validation

6. stQEUROToken

Purpose: Yield-bearing wrapper for QEURO with automatic yield accrual.

Key Features:

• Automatic yield distribution via exchange rate
• Exchange rate = (totalUnderlying + totalYieldEarned) / totalSupply
• No lock-up period — unstake at any time
• Virtual protection against donation attacks

Architecture Patterns:

• Wrapper Pattern: Enhanced token functionality
• Yield Distribution: Exchange rate increases as yield accrues
• Virtual Protection: Attack prevention mechanisms

6b. stQEUROFactory (Multi-Vault Extension)

Purpose: Factory/orchestrator that deploys one stQEUROToken proxy per staking vault.

Key Features:

• Per-vault token deployment using ERC1967Proxy and shared stQEUROToken implementation
• Deterministic registry and lookup mappings:
  • vaultId -> stQEURO token
  • vault -> stQEURO token
  • stQEURO token -> vaultId
• Strict vault self-registration model (msg.sender is the registered vault)
• Validation and uniqueness guarantees for vaultId and vaultName (uppercase alphanumeric)
• Governance-controlled factory config (implementation/yieldShift/treasury/token admin)

Architecture Patterns:

• Factory Pattern: Dynamic deployment of homogeneous staking-token proxies
• Registry Pattern: Bi-directional mapping between vaults and staking tokens
• Role-Gated Self-Registration: Vault onboarding constrained by governance-granted role + on-chain self-call

7. FeeCollector

Purpose: Centralized fee collection and distribution across the protocol.

Key Features:

• Collects fees from QuantillonVault (mint/redeem fees)
• Distributes to three beneficiaries: treasury (60%), dev fund (25%), community (15%)
• Governance-controlled ratio updates
• Per-token fee accounting

Architecture Patterns:

• Pull Pattern: Beneficiaries withdraw collected fees
• Split Pattern: Configurable fee ratio distribution

8. OracleRouter

Purpose: Oracle-agnostic price routing — all protocol contracts interact with OracleRouter via IOracle.

Key Features:

• Routes price requests to the active oracle (Chainlink or Stork)
• Governance can switch between oracles at runtime without changing protocol contracts
• Both oracles implement the same IOracle interface
• Event emitted on oracle switch (OracleSwitched)

9. ChainlinkOracle / StorkOracle

Purpose: EUR/USD and USDC/USD price feeds with circuit breakers.

Key Features:

• ChainlinkOracle: Uses Chainlink AggregatorV3 feeds; 1-hour staleness check; 5% deviation circuit breaker
• StorkOracle: Uses Stork Network TemporalNumericValue feeds; identical staleness/deviation validation
• Both support EUR/USD and USDC/USD feeds
• Mock versions available (MockChainlinkOracle, MockStorkOracle) for local/testnet

10. TimeProvider

Purpose: Centralized block.timestamp wrapper for consistent time management across all contracts.

Yield Management Architecture

YieldShift System

Purpose: Intelligent yield distribution between user and hedger pools.

Components:

• Yield Sources: Aave, protocol fees, interest differentials
• Distribution Engine: Dynamic allocation between pools
• Performance Metrics: Yield tracking and optimization
• Rebalancing Logic: Automatic pool rebalancing

Architecture Patterns:

• Strategy Pattern: Multiple yield source strategies
• Observer Pattern: Performance monitoring
• Factory-Routed Distribution: Yield routed by vaultId through stQEUROFactory to the correct staking token

AaveVault Integration

Purpose: Automated yield generation through Aave protocol.

Features:

• USDC deployment to Aave
• Yield harvesting and distribution
• Risk management and exposure limits
• Emergency withdrawal mechanisms
• Auto-rebalancing based on market conditions

Architecture Patterns:

• Adapter Pattern: Aave protocol integration
• Risk Management: Exposure limit enforcement
• Yield Optimization: Dynamic allocation strategies
• Vault-Aware Routing: Harvested yield is pushed to YieldShift.addYield(yieldVaultId, ...)

Security Architecture

Access Control System

Role-Based Access Control (RBAC):

• MINTER_ROLE / BURNER_ROLE: QEUROToken — vault-only mint/burn
• PAUSER_ROLE: QEUROToken emergency pause
• COMPLIANCE_ROLE: QEUROToken blacklist/whitelist management
• GOVERNANCE_ROLE: Parameter updates and contract wiring across all core contracts
• EMERGENCY_ROLE: Emergency pause and withdrawal across all core contracts
• VAULT_OPERATOR_ROLE: QuantillonVault — authorize Aave deployment
• HEDGER_ROLE: HedgerPool — open and manage hedging positions
• TREASURY_ROLE: FeeCollector — fee withdrawal
• ORACLE_MANAGER_ROLE: OracleRouter/ChainlinkOracle/StorkOracle — feed updates, oracle switching
• UPGRADER_ROLE: Oracle contracts — UUPS upgrades

Security Patterns

Reentrancy Protection:

• nonReentrant modifier on all state-changing functions
• Checks-effects-interactions pattern
• External call isolation

Oracle Security:

• Multiple price feed validation
• Staleness checks
• Circuit breaker mechanisms
• Price bound validation

Emergency Systems:

• Pause/unpause mechanisms
• Emergency withdrawal functions
• Circuit breaker activation
• Recovery procedures

Data Flow Architecture

QEURO Minting Flow

QEURO Minting Flow:
┌─────────┐    ┌──────────────┐    ┌─────────────────┐    ┌─────────────┐
│  User   │    │QuantillonVault│    │ChainlinkOracle │    │QEUROToken   │
└────┬────┘    └──────┬───────┘    └────────┬────────┘    └──────┬──────┘
     │                │                      │                    │
     │ approve()      │                      │                    │
     ├───────────────▶│                      │                    │
     │ mintQEURO()    │                      │                    │
     ├───────────────▶│                      │                    │
     │                │ getEurUsdPrice()     │                    │
     │                ├─────────────────────▶│                    │
     │                │ price, isValid       │                    │
     │                │◀─────────────────────┤                    │
     │                │ validatePrice()      │                    │
     │                │ calculateMintAmount()│                    │
     │                │ transferFrom()       │                    │
     │                │ mint()               │                    │
     │                ├─────────────────────────────────────────▶│
     │                │ emit QEUROMinted()   │                    │
     │ success        │                      │                    │
     │◀───────────────┤                      │                    │

Yield Distribution Flow

Yield Distribution Flow:
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ YieldShift  │    │ AaveVault   │    │  UserPool   │    │ HedgerPool  │
└──────┬──────┘    └──────┬──────┘    └──────┬──────┘    └──────┬──────┘
       │                  │                  │                  │
       │ harvestAaveYield()│                  │                  │
       ├─────────────────▶│                  │                  │
       │                  │ claimRewards()   │                  │
       │                  ├─────────────────▶│                  │
       │                  │ yieldAmount      │                  │
       │                  │◀─────────────────┤                  │
       │ addYield()       │                  │                  │
       │◀─────────────────┤                  │                  │
       │ calculateOptimalDistribution()      │                  │
       │ distributeUserYield()               │                  │
       ├─────────────────────────────────────▶│                  │
       │ distributeHedgerYield()             │                  │
       ├───────────────────────────────────────────────────────▶│
       │ emit YieldDistributed()             │                  │

Governance Flow

Governance Flow:
┌─────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  User   │    │  QTIToken   │    │  Timelock   │    │   Target    │
│         │    │             │    │             │    │  Contract   │
└────┬────┘    └──────┬──────┘    └──────┬──────┘    └──────┬──────┘
     │                │                  │                  │
     │ lock()         │                  │                  │
     ├───────────────▶│                  │                  │
     │                │ calculateVotingPower()              │
     │                │ emit TokensLocked()                 │
     │ createProposal()│                  │                  │
     ├───────────────▶│                  │                  │
     │                │ validateVotingPower()               │
     │                │ emit ProposalCreated()              │
     │ vote()         │                  │                  │
     ├───────────────▶│                  │                  │
     │                │ emit VoteCast()  │                  │
     │ executeProposal()│                │                  │
     ├───────────────▶│                  │                  │
     │                │ schedule()       │                  │
     │                ├─────────────────▶│                  │
     │                │                  │ execute()        │
     │                │                  ├─────────────────▶│

Scalability Architecture

Gas Optimization

Storage Optimization:

• Packed structs for efficient storage
• Batch operations for multiple updates
• Event-based logging instead of storage
• Minimal state variables

Computation Optimization:

• Cached values for repeated calculations
• Efficient algorithms for complex operations
• Minimal external calls
• Optimized loops and iterations

Upgradeability

Proxy Pattern Implementation:

• Transparent proxy for admin functions
• UUPS proxy for gas efficiency
• Storage layout compatibility
• Initialization pattern for upgrades

Upgrade Process:

1. Deploy new implementation
2. Validate compatibility
3. Schedule upgrade via governance
4. Execute upgrade after timelock
5. Verify functionality

Integration Architecture

External Integrations

Oracle System (OracleRouter + ChainlinkOracle + StorkOracle):

• OracleRouter implements IOracle — all protocol contracts use this interface
• Active oracle is switchable by governance (Chainlink ↔ Stork) without contract changes
• ChainlinkOracle: EUR/USD + USDC/USD via Chainlink AggregatorV3; 1 hr staleness check; 5% deviation circuit breaker
• StorkOracle: EUR/USD + USDC/USD via Stork Network; same staleness/deviation validation
• MockChainlinkOracle + MockStorkOracle available for local/testnet development

Aave Protocol:

• USDC lending integration via AaveVault
• Yield harvesting and distribution
• Risk management (exposure limits)
• Emergency withdrawal mechanisms

ERC-20 Standards:

• Full ERC-20 compliance
• Extended functionality
• Metadata support
• Permit functionality

API Architecture

Contract Interfaces:

• Standardized function signatures
• Consistent error handling
• Event emission patterns
• Access control integration

Integration Patterns:

• Factory pattern for contract creation
• Registry pattern for contract discovery
• Proxy pattern for upgrades
• Adapter pattern for external integrations

Monitoring and Observability

Event Architecture

Core Events:

• Token transfers and approvals
• Vault operations (mint/redeem)
• Staking and unstaking
• Yield distribution
• Governance actions

Monitoring Events:

• System health indicators
• Performance metrics
• Error conditions
• Security events

Analytics Architecture

On-Chain Analytics:

• Transaction volume tracking
• Yield performance metrics
• User behavior analysis
• Risk metrics monitoring

Off-Chain Analytics:

• Protocol health dashboards
• Performance reporting
• Risk assessment
• Compliance monitoring

Future Architecture Considerations

Layer 2 Integration

Planned Support:

• Polygon deployment
• Arbitrum integration
• Optimism support
• Base network expansion

Cross-Chain Architecture:

• Bridge integration
• Cross-chain governance
• Unified yield management
• Shared security model

Advanced Features

Planned Enhancements:

• Advanced yield strategies
• Institutional features
• MEV protection
• Enhanced governance
• Automated market making

Architecture Principles

Design Principles

1. Security First: All components designed with security as the primary concern
2. Modularity: Clear separation of concerns and modular design
3. Upgradeability: Future-proof design with upgrade capabilities
4. Gas Efficiency: Optimized for cost-effective operations
5. Transparency: Open and auditable code and processes

Development Principles

1. Test-Driven Development: Comprehensive test coverage
2. Documentation: Complete documentation for all components
3. Code Review: Rigorous review process for all changes
4. Continuous Integration: Automated testing and deployment
5. Security Audits: Regular security assessments

This architecture document is maintained by Quantillon Labs and updated with each protocol version.

Quantillon Protocol Security Guide

Overview

The Quantillon Protocol implements comprehensive security measures to protect user funds and ensure protocol integrity. This document outlines security best practices, audit reports, and risk management guidelines.

Security Architecture

Multi-Layer Security Model

graph TB
    subgraph "Application Layer"
        AC[Access Control]
        RB[Role-Based Permissions]
        EM[Emergency Mechanisms]
    end
    
    subgraph "Smart Contract Layer"
        RP[Reentrancy Protection]
        OV[Overflow Protection]
        PA[Pause Mechanisms]
    end
    
    subgraph "Oracle Layer"
        CB[Circuit Breakers]
        PV[Price Validation]
        SF[Staleness Checks]
    end
    
    subgraph "Infrastructure Layer"
        UP[Upgradeable Proxies]
        TL[Timelock Controls]
        AU[Audit Trails]
    end
    
    subgraph "External Layer"
        AE[Audit Reports]
        BB[Bug Bounty]
        MC[Monitoring & Alerting]
    end

Security Features

1. Access Control

Role-Based Access Control (RBAC):

• Hierarchical permission system
• Principle of least privilege
• Time-locked administrative functions
• Multi-signature requirements for critical operations

Key Roles per contract:

// QEUROToken
MINTER_ROLE       = keccak256("MINTER_ROLE");      // Vault: mint QEURO
BURNER_ROLE       = keccak256("BURNER_ROLE");      // Vault: burn QEURO
PAUSER_ROLE       = keccak256("PAUSER_ROLE");      // Emergency: pause token
COMPLIANCE_ROLE   = keccak256("COMPLIANCE_ROLE");  // Blacklist/whitelist management

// QuantillonVault / UserPool / HedgerPool / YieldShift / AaveVault
GOVERNANCE_ROLE         = keccak256("GOVERNANCE_ROLE");         // Parameter updates, wiring
EMERGENCY_ROLE          = keccak256("EMERGENCY_ROLE");          // Emergency pause/withdraw
VAULT_OPERATOR_ROLE     = keccak256("VAULT_OPERATOR_ROLE");     // Vault: Aave deployment
HEDGER_ROLE             = keccak256("HEDGER_ROLE");             // HedgerPool: open positions

// FeeCollector
TREASURY_ROLE     = keccak256("TREASURY_ROLE");    // Fee withdrawal

// OracleRouter / ChainlinkOracle / StorkOracle
ORACLE_MANAGER_ROLE = keccak256("ORACLE_MANAGER_ROLE"); // Feed address updates, oracle switching
UPGRADER_ROLE       = keccak256("UPGRADER_ROLE");       // UUPS upgrades

2. Reentrancy Protection

Implementation:

• nonReentrant modifier on all state-changing functions
• Checks-effects-interactions pattern
• External call isolation
• State variable protection

Example:

modifier nonReentrant() {
    require(_status != _ENTERED, "ReentrancyGuard: reentrant call");
    _status = _ENTERED;
    _;
    _status = _NOT_ENTERED;
}

3. Oracle Security

Price Feed Validation:

• Multiple price feed sources
• Staleness checks (max 1 hour)
• Price bound validation
• Circuit breaker mechanisms

Implementation:

function validateOraclePrice(bool isValid) internal pure {
    if (!isValid) revert ErrorLibrary.StalePrice();
}

function validatePriceBounds(uint256 price) internal view {
    if (price < minPrice || price > maxPrice) {
        revert ErrorLibrary.InvalidPrice();
    }
}

4. Emergency Mechanisms

Pause System:

• Global pause functionality
• Role-based pause controls
• Emergency withdrawal capabilities
• Circuit breaker activation

Implementation:

modifier whenNotPaused() {
    require(!paused(), "Pausable: paused");
    _;
}

function emergencyPause() external onlyRole(EMERGENCY_ROLE) {
    _pause();
    emit EmergencyPause(msg.sender, block.timestamp);
}

Bug Bounty Program

Program Details

Reward Structure:

• Critical: $100,000
• High: $50,000
• Medium: $10,000
• Low: $1,000
• Informational: $500

Scope:

• All smart contracts in the protocol
• Integration contracts
• Governance mechanisms
• Oracle systems

Exclusions:

• Issues in third-party dependencies
• Social engineering attacks
• Physical attacks
• Issues requiring admin privileges

Submission Process

1. Report: Submit detailed vulnerability report
2. Review: Security team reviews submission
3. Validation: Reproduce and validate issue
4. Fix: Develop and deploy fix
5. Reward: Process bounty payment

Contact: security@quantillon.money

Risk Management

Risk Categories

1. Smart Contract Risks

Oracle Manipulation:

• Risk: Price feed manipulation
• Mitigation: Multiple price sources, circuit breakers
• Monitoring: Price deviation alerts

Reentrancy Attacks:

• Risk: State manipulation during external calls
• Mitigation: Reentrancy guards, CEI pattern
• Monitoring: Function call analysis

Access Control Bypass:

• Risk: Unauthorized function execution
• Mitigation: Role-based access control, multi-sig
• Monitoring: Permission change alerts

2. Economic Risks

Liquidity Risk:

• Risk: Insufficient liquidity for operations
• Mitigation: Liquidity requirements, emergency procedures
• Monitoring: Liquidity ratio tracking

Interest Rate Risk:

• Risk: Adverse interest rate movements
• Mitigation: Hedging mechanisms, rate limits
• Monitoring: Rate change alerts

Market Risk:

• Risk: Extreme market volatility
• Mitigation: Circuit breakers, position limits
• Monitoring: Volatility tracking

3. Operational Risks

Key Management:

• Risk: Private key compromise
• Mitigation: Hardware security modules, multi-sig
• Monitoring: Access pattern analysis

Upgrade Risk:

• Risk: Malicious or faulty upgrades
• Mitigation: Timelock controls, governance
• Monitoring: Upgrade proposal tracking

Integration Risk:

• Risk: Third-party protocol failures
• Mitigation: Risk limits, emergency procedures
• Monitoring: External protocol health

Security Best Practices

For Developers

1. Code Security

Input Validation:

function deposit(uint256 amount) external {
    require(amount > 0, "Amount must be positive");
    require(amount <= MAX_DEPOSIT, "Amount exceeds limit");
    // ... function logic
}

Access Control:

modifier onlyAuthorized() {
    require(hasRole(AUTHORIZED_ROLE, msg.sender), "Unauthorized");
    _;
}

Reentrancy Protection:

function withdraw(uint256 amount) external nonReentrant {
    // ... function logic
}

2. Testing

Unit Testing:

• Test all function paths
• Test edge cases and boundary conditions
• Test access control mechanisms
• Test error conditions

Integration Testing:

• Test contract interactions
• Test external integrations
• Test upgrade scenarios
• Test emergency procedures

Fuzz Testing:

• Random input generation
• Property-based testing
• Stress testing
• Gas limit testing

3. Code Review

Review Checklist:

• Access control implementation
• Input validation
• Reentrancy protection
• Error handling
• Gas optimization
• Event emission
• Documentation

For Integrators

1. Integration Security

Contract Verification:

// Verify contract addresses
const VAULT_ADDRESS = "0x..."; // Verified on Etherscan
const QEURO_ADDRESS = "0x..."; // Verified on Etherscan

// Verify contract state
const isPaused = await vault.paused();
if (isPaused) {
    throw new Error("Contract is paused");
}

Transaction Security:

// Use slippage protection
const slippage = 0.05; // 5%
const minOutput = expectedOutput * (1 - slippage);

// Validate transaction parameters
const gasEstimate = await contract.estimateGas.function(params);
const gasLimit = gasEstimate.mul(120).div(100); // 20% buffer

Error Handling:

try {
    await contract.function();
} catch (error) {
    if (error.message.includes('InsufficientBalance')) {
        // Handle insufficient balance
    } else if (error.message.includes('StalePrice')) {
        // Handle stale price
    } else {
        // Handle other errors
    }
}

2. Monitoring

Event Monitoring:

// Monitor important events
contract.on('QEUROMinted', (user, usdcAmount, qeuroAmount) => {
    console.log(`User ${user} minted ${qeuroAmount} QEURO`);
});

contract.on('EmergencyPause', (admin, timestamp) => {
    console.log(`Contract paused by ${admin} at ${timestamp}`);
});

Health Checks:

async function healthCheck() {
    const [
        isPaused,
        oraclePrice,
        vaultMetrics
    ] = await Promise.all([
        vault.paused(),
        oracle.getEurUsdPrice(),
        vault.getVaultMetrics()
    ]);
    
    if (isPaused) {
        console.warn("Vault is paused");
    }
    
    if (!oraclePrice.isValid) {
        console.warn("Oracle price is stale");
    }
    
    if (vaultMetrics.collateralizationRatio < 11000) {
        console.warn("Low collateralization ratio");
    }
}

Incident Response

Response Procedures

1. Detection

Automated Monitoring:

• Price deviation alerts
• Liquidity threshold alerts
• Access control violation alerts
• Unusual transaction pattern alerts

Manual Monitoring:

• Community reports
• Security researcher reports
• Internal security reviews
• External audit findings

2. Assessment

Severity Classification:

• Critical: Immediate threat to user funds
• High: Significant risk to protocol integrity
• Medium: Moderate risk with workarounds
• Low: Minor issues with minimal impact

Impact Analysis:

• Affected contracts and functions
• Potential financial impact
• User impact assessment
• Recovery time estimation

3. Response

Immediate Actions:

• Activate emergency pause if necessary
• Notify security team and stakeholders
• Assess and contain the issue
• Implement temporary mitigations

Recovery Actions:

• Develop and test fixes
• Deploy fixes through governance
• Monitor system recovery
• Conduct post-incident review

4. Communication

Stakeholder Notification:

• Internal team notification
• Community announcement
• Partner notification
• Regulatory notification (if required)

Transparency:

• Incident timeline
• Root cause analysis
• Remediation steps
• Prevention measures

Security Monitoring

Real-Time Monitoring

Key Metrics:

• Contract pause status
• Oracle price staleness
• Liquidity ratios
• Access control changes
• Unusual transaction patterns

Alerting:

• Price deviation > 5%
• Liquidity ratio < 110%
• Emergency role activation
• Large transaction volumes
• Failed transaction spikes

Security Dashboards

Operational Dashboard:

• System health indicators
• Performance metrics
• Error rates
• Gas usage patterns

Security Dashboard:

• Access control events
• Emergency activations
• Oracle health status
• Risk metrics

Security Contacts

Primary Contacts

Security Team: security@quantillon.money

Security Resources

Documentation

• Smart Contract Security Best Practices
• OpenZeppelin Security Guidelines
• Ethereum Security Considerations

Tools

• Slither Static Analysis
• Mythril Symbolic Execution
• Echidna Fuzzing

Security Analysis Results

Use generated artifacts from each run instead of hardcoded snapshots:

• scripts/results/slither/slither-report.txt
• scripts/results/slither/slither-report.json
• scripts/results/mythril-reports/
• scripts/results/natspec-validation-report.txt
• scripts/results/contract-sizes/contract-sizes-summary.txt

As of March 10, 2026, the latest local validation included:

• NatSpec coverage: 1218/1218 functions documented (100.00%)
• Targeted Slither missing-zero-check pass: 0 findings
• Mock oracle initialization hardening with explicit zero-address validation for admin-derived state

Running Mythril Analysis:

# Run Mythril analysis
make mythril

# Or run directly
./scripts/run-mythril.sh

# Run Slither static analysis
make slither

# Validate NatSpec coverage
make validate-natspec

# Run EIP-170 contract size checks
make analyze-contract-sizes

# Run comprehensive security analysis (Slither + Mythril)
make security

This security guide is maintained by Quantillon Labs and updated regularly.

Quantillon Protocol — Deployment Guide

Overview

This guide covers deploying and configuring the Quantillon Protocol smart contracts using Foundry. Core contracts are deployed in a single forge script invocation via DeployQuantillon.s.sol, which writes the deployed addresses to deployments/{chainId}/addresses.json.

Prerequisites

Required Tools

• Foundry (forge, cast, anvil): curl -L https://foundry.paradigm.xyz | bash && foundryup
• jq: for post-deployment address parsing (sudo apt install jq or brew install jq)
• Node.js 18+ (for NatSpec validation and size analysis scripts)

Environment File

Copy the appropriate template and fill in your values:

# Localhost development
cp .env.localhost .env

# Base Sepolia testnet
cp .env.base-sepolia .env

# Base mainnet production
cp .env.base .env

Required variables:

Optional variables (default to deployer address if not set):

Deployment Architecture

DeployQuantillon.s.sol deploys all contracts in this dependency order within a single broadcast session:

TimeProvider
    └── ChainlinkOracle (or MockChainlinkOracle) + ERC1967Proxy
    └── StorkOracle (or MockStorkOracle) + ERC1967Proxy
    └── OracleRouter + ERC1967Proxy
            │
            ├── FeeCollector + ERC1967Proxy
            │       └── QEUROToken + ERC1967Proxy
            │               └── QuantillonVault + ERC1967Proxy
            │
            ├── QTIToken + ERC1967Proxy
            │
            ├── AaveVault + ERC1967Proxy (uses Aave V3 or mock)
            │
            ├── UserPool + ERC1967Proxy
            ├── HedgerPool + ERC1967Proxy
            ├── YieldShift + ERC1967Proxy
            ├── stQEUROToken (implementation)
            └── stQEUROFactory + ERC1967Proxy
                    └── _wireContracts() — configures dependencies/roles and enforces required post-deploy wiring (no vault registration)

After deployment, addresses are written to deployments/{chainId}/addresses.json.

Required post-deploy wiring now enforced in-script (deployment reverts if any check fails):

• quantillonVault.initializePriceCache()
• yieldShift.configureDependencies(...)
• yieldShift.setYieldSourceAuthorization(aaveVault, "aave", true)
• yieldShift.bootstrapDefaults()
• aaveVault.updateYieldShift(yieldShift)
• hedgerPool.configureDependencies(...) (includes feeCollector)
• feeCollector.authorizeFeeSource(quantillonVault)
• feeCollector.authorizeFeeSource(hedgerPool)

Vault registration is intentionally deferred: DeployQuantillon.s.sol does not register any stQEURO vault token on initialization.

Network Configuration

Localhost Deployment

Start Anvil

# Plain local node (all mocks required)
anvil --host 0.0.0.0 --port 8545 --accounts 10 --balance 10000

# Or fork Base mainnet (allows using real oracle feeds without mocks)
anvil --host 0.0.0.0 --port 8545 --fork-url https://mainnet.base.org --chain-id 31337

Deploy

# All mocks (MockUSDC + MockChainlinkOracle + MockStorkOracle)
./scripts/deployment/deploy.sh localhost --with-mocks

# Mock oracle only (real USDC from fork)
./scripts/deployment/deploy.sh localhost --with-mock-oracle

# No mocks (assumes Base mainnet fork with real contracts)
./scripts/deployment/deploy.sh localhost

Output

deployments/31337/addresses.json

Testnet Deployment (Base Sepolia)

# With mock contracts (recommended for testing)
./scripts/deployment/deploy.sh base-sepolia --with-mocks --verify

# With real Chainlink feeds + real USDC
./scripts/deployment/deploy.sh base-sepolia --verify

The script automatically:

• Sets gas price to 2 gwei
• Uses --slow to send transactions one-at-a-time (avoids nonce desync with public RPCs)
• Polls for stable nonce before broadcasting
• Falls back to mock Aave if Base Sepolia Aave addresses have no code

Output

deployments/84532/addresses.json

Mainnet Deployment (Base)

Pre-Deployment Checklist

Before deploying to Base mainnet:

• Set TREASURY, DEV_FUND, COMMUNITY_FUND to governance-controlled multisig addresses in .env.base
• Set SINGLE_HEDGER to the authorized hedger address
• Verify PRIVATE_KEY belongs to a dedicated deployment wallet with sufficient ETH
• Set ETHERSCAN_API_KEY for contract verification
• Run a dry-run first: ./scripts/deployment/deploy.sh base --dry-run
• Test on Base Sepolia with the same configuration

Deploy

# Production deployment with verification and 1M optimizer runs
./scripts/deployment/deploy.sh base --verify --production

The --production flag sets FOUNDRY_PROFILE=production which uses 1,000,000 optimizer runs (defined in foundry.toml).

Output

deployments/8453/addresses.json

Dry Run

Test the deployment without broadcasting any transactions:

./scripts/deployment/deploy.sh localhost --dry-run
./scripts/deployment/deploy.sh base-sepolia --dry-run
./scripts/deployment/deploy.sh base --dry-run

Post-Deployment

deploy.sh automatically runs these after a successful deployment:

1. Copy ABIs to Frontend

./scripts/deployment/copy-abis.sh localhost

Copies all contract JSON artifacts from out/ to the path specified in FRONTEND_ABI_DIR.

2. Update Frontend Addresses

./scripts/deployment/update-frontend-addresses.sh localhost

Reads deployments/{chainId}/addresses.json and writes the frontend addresses.json to FRONTEND_ADDRESSES_FILE.

Accessing Deployed Addresses

Programmatically (shell)

jq '.qeuroToken' deployments/31337/addresses.json
# "0x..."

Frontend format (addresses.json)

{
  "31337": {
    "name": "Anvil Localhost",
    "isTestnet": true,
    "contracts": {
      "timeProvider": "0x...",
      "chainlinkOracle": "0x...",
      "storkOracle": "0x...",
      "oracleRouter": "0x...",
      "feeCollector": "0x...",
      "qeuroToken": "0x...",
      "quantillonVault": "0x...",
      "qtiToken": "0x...",
      "aaveVault": "0x...",
      "stQEUROFactory": "0x...",
      "stQeuroToken": "0x...",
      "userPool": "0x...",
      "hedgerPool": "0x...",
      "yieldShift": "0x..."
    }
  }
}

Contract Verification

Contracts are verified automatically when --verify is passed. For manual re-verification:

# Example: re-verify QEUROToken proxy on Base Sepolia
forge verify-contract \
  <PROXY_ADDRESS> \
  lib/openzeppelin-contracts/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy \
  --chain-id 84532 \
  --etherscan-api-key $ETHERSCAN_API_KEY

Troubleshooting

Anvil not running

anvil --host 0.0.0.0 --port 8545 --accounts 10 --balance 10000

Missing environment file

cp .env.localhost .env
# or
cp .env.base-sepolia .env

Nonce desync on testnet

The deploy script polls for a stable nonce before broadcasting. If it keeps failing, try a different RPC URL (the default https://sepolia.base.org can occasionally lag). You can override by editing the NETWORKS map in deploy.sh.

Verification failed

Ensure ETHERSCAN_API_KEY is set and valid. If automatic verification fails, contracts can be re-verified using forge verify-contract after deployment.

USDC address is zero on localhost

Set USDC=<mock_address> in .env.localhost after deploying MockUSDC, or let deploy.sh handle it automatically with --with-mock-usdc.

Security Considerations

Private Key Management

• Use a dedicated deployment wallet — never your main wallet
• For production, use a hardware wallet or a cloud HSM
• Rotate deployment keys after production deployment

Production Role Configuration

• TREASURY, DEV_FUND, and COMMUNITY_FUND should be multisig wallets (e.g., Safe)
• SINGLE_HEDGER should be an audited, authorized hedger address
• After deployment, transfer admin roles to the governance multisig

Never Commit Secrets

• All .env* files are in .gitignore
• Use a secret manager (AWS Secrets Manager, HashiCorp Vault) for production CI/CD

Maintained by Quantillon Labs. See scripts/README.md for the complete deployment script reference.

Contents

• vaults
• yieldmanagement
• FeeCollector
• HedgerPool
• QEUROToken
• QTIToken
• QuantillonVault
• SecureUpgradeable
• TimelockUpgradeable
• UserPool
• stQEUROFactory
• stQEUROToken

Contents

• IPool
• IPoolAddressesProvider
• IRewardsController
• ReserveData
• AaveVault
• IMockMorphoVault
• MorphoStakingVaultAdapter

IPool

Git Source

Title: AaveVault

Author: Quantillon Labs - Nicolas Bellengé - @chewbaccoin

Note: security-contact: team@quantillon.money

Functions

supply

Supply assets to Aave protocol

Supplies assets to Aave protocol on behalf of a user

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function supply(address asset, uint256 amount, address onBehalfOf, uint16 referralCode) external;

Parameters

withdraw

Withdraw assets from Aave protocol

Withdraws assets from Aave protocol to a specified address

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function withdraw(address asset, uint256 amount, address to) external returns (uint256);

Parameters

Returns

getReserveData

Get reserve data for an asset

Returns reserve data for a specific asset in Aave protocol

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function getReserveData(address asset) external view returns (ReserveData memory);

Parameters

Returns

IPoolAddressesProvider

Git Source

Functions

getPool

Get the pool address

Returns the address of the Aave pool

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function getPool() external view returns (address);

Returns

IRewardsController

Git Source

Functions

claimRewards

Claim rewards from Aave protocol

Claims rewards for specified assets and amount

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function claimRewards(address[] calldata assets, uint256 amount, address to) external returns (uint256);

Parameters

Returns

getUserRewards

Get user rewards for specified assets

Returns the rewards for a user across specified assets

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function getUserRewards(address[] calldata assets, address user) external view returns (uint256[] memory);

Parameters

Returns

ReserveData

Git Source

struct ReserveData {
uint256 configuration;
uint128 liquidityIndex;
uint128 currentLiquidityRate;
uint128 variableBorrowIndex;
uint128 currentVariableBorrowRate;
uint128 currentStableBorrowRate;
uint40 lastUpdateTimestamp;
uint16 id;
address aTokenAddress;
address stableDebtTokenAddress;
address variableDebtTokenAddress;
address interestRateStrategyAddress;
uint128 accruedToTreasury;
uint128 unbacked;
uint128 isolationModeTotalDebt;
}

AaveVault

Git Source

Inherits: Initializable, ReentrancyGuardUpgradeable, AccessControlUpgradeable, PausableUpgradeable, SecureUpgradeable, IExternalStakingVault

Title: AaveVault

Author: Quantillon Labs - Nicolas Bellengé - @chewbaccoin

Aave integration vault for yield generation through USDC lending

Main characteristics:

• USDC deposits into Aave lending protocol for yield generation
• Automatic yield harvesting and distribution
• Risk management with exposure limits and health monitoring
• Emergency withdrawal capabilities for crisis situations
• Dynamic allocation based on market conditions
• Upgradeable via UUPS pattern

Deposit mechanics:

• USDC supplied to Aave protocol for lending
• Receives aUSDC tokens representing interest-bearing deposits
• Principal tracking for yield calculation
• Maximum exposure limits for risk management
• Health checks before deposits

Yield harvesting:

• Automatic detection of accrued interest
• Threshold-based harvesting to optimize gas costs
• Protocol fees charged on harvested yield
• Net yield distributed to yield shift mechanism
• Real-time yield tracking and reporting

Risk management:

• Maximum Aave exposure limits (default 50M USDC)
• Utilization rate monitoring for liquidity risk
• Emergency mode for immediate withdrawals
• Health monitoring of Aave protocol status
• Slippage protection on withdrawals

Allocation strategy:

• Dynamic allocation based on Aave APY
• Rebalancing thresholds for optimal yield
• Market condition adjustments
• Liquidity availability considerations
• Expected yield calculations

Fee structure:

• Yield fees charged on harvested interest (default 10%)
• Protocol fees for sustainability
• Dynamic fee adjustment based on performance
• Fee collection and distribution tracking

Security features:

• Role-based access control for all critical operations
• Reentrancy protection for all external calls
• Emergency pause mechanism for crisis situations
• Upgradeable architecture for future improvements
• Secure withdrawal validation
• Health monitoring and circuit breakers

Integration points:

• Aave lending protocol for yield generation
• USDC for deposits and withdrawals
• aUSDC tokens for interest accrual tracking
• Yield shift mechanism for yield distribution
• Rewards controller for additional incentives

Note: security-contact: team@quantillon.money

State Variables

GOVERNANCE_ROLE

bytes32 public constant GOVERNANCE_ROLE = keccak256("GOVERNANCE_ROLE")

VAULT_MANAGER_ROLE

bytes32 public constant VAULT_MANAGER_ROLE = keccak256("VAULT_MANAGER_ROLE")

EMERGENCY_ROLE

bytes32 public constant EMERGENCY_ROLE = keccak256("EMERGENCY_ROLE")

usdc

IERC20 public usdc

aUSDC

IERC20 public aUSDC

aavePool

IPool public aavePool

aaveProvider

IPoolAddressesProvider public aaveProvider

rewardsController

IRewardsController public rewardsController

yieldShift

IYieldShift public yieldShift

maxAaveExposure

uint256 public maxAaveExposure

harvestThreshold

uint256 public harvestThreshold

yieldFee

uint256 public yieldFee

rebalanceThreshold

uint256 public rebalanceThreshold

principalDeposited

uint256 public principalDeposited

lastHarvestTime

uint256 public lastHarvestTime

totalYieldHarvested

uint256 public totalYieldHarvested

totalFeesCollected

uint256 public totalFeesCollected

utilizationLimit

uint256 public utilizationLimit

emergencyExitThreshold

uint256 public emergencyExitThreshold

yieldVaultId

uint256 public yieldVaultId

emergencyMode

bool public emergencyMode

treasury

address public treasury

Functions

constructor

Constructor for AaveVault implementation

Disables initialization on implementation for security

Notes:

• security: Disables initialization on implementation for security

• validation: No input validation required

• state-changes: Disables initializers

• events: No events emitted

• errors: No errors thrown

• reentrancy: Not protected - constructor only

• access: Public constructor

• oracle: No oracle dependencies

constructor() ;

initialize

Initialize the AaveVault contract

Sets up the contract with all required addresses and roles

Notes:

• security: Validates all addresses are not zero

• validation: Validates all input addresses

• state-changes: Initializes ReentrancyGuard, AccessControl, and Pausable

• events: Emits initialization events

• errors: Throws if any address is zero

• reentrancy: Protected by initializer modifier

• access: Public initializer

• oracle: No oracle dependencies

function initialize(
    address admin,
    address _usdc,
    address _aaveProvider,
    address _rewardsController,
    address _yieldShift,
    address _timelock,
    address _treasury
) public initializer;

Parameters

deployToAave

Deploy USDC to Aave V3 pool to earn yield

Supplies USDC to Aave protocol and receives aUSDC tokens representing the deposit

Notes:

• security: Validates oracle price freshness, enforces exposure limits and health checks

• validation: Validates amount > 0, checks max exposure limits, verifies Aave pool health

• state-changes: Updates principalDeposited, transfers USDC from caller, receives aUSDC

• events: Emits DeployedToAave with operation details

• errors: Throws WouldExceedLimit if exceeds maxAaveExposure, AavePoolNotHealthy if pool unhealthy

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to VAULT_MANAGER_ROLE

• oracle: Requires fresh EUR/USD price for health validation

function deployToAave(uint256 amount) public nonReentrant whenNotPaused returns (uint256 aTokensReceived);

Parameters

Returns

withdrawFromAave

Withdraw USDC from Aave V3 pool

Withdraws USDC from Aave protocol, validates slippage and updates principal tracking

Notes:

• security: Validates withdrawal constraints, enforces minimum balance requirements

• validation: Validates amount > 0, checks sufficient aUSDC balance, validates slippage

• state-changes: Updates principalDeposited, withdraws aUSDC, receives USDC

• events: Emits WithdrawnFromAave with withdrawal details

• errors: Throws InsufficientBalance if not enough aUSDC, WouldBreachMinimum if below threshold

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to VAULT_MANAGER_ROLE

• oracle: No oracle dependency for withdrawals

function withdrawFromAave(uint256 amount) public nonReentrant returns (uint256 usdcWithdrawn);

Parameters

Returns

_validateAndCalculateWithdrawAmount

Validates and calculates the actual withdrawal amount

Internal function to validate withdrawal parameters and calculate actual amount

Notes:

• security: Validates sufficient balance and handles max withdrawal requests

• validation: Validates aaveBalance > 0, amount <= aaveBalance

• state-changes: No state changes - pure function

• events: No events emitted

• errors: Throws InsufficientBalance if balance too low

• reentrancy: Not applicable - pure function

• access: Internal function - no access restrictions

• oracle: No oracle dependencies

function _validateAndCalculateWithdrawAmount(uint256 amount, uint256 aaveBalance)
    internal
    pure
    returns (uint256 withdrawAmount);

Parameters

Returns

_validateWithdrawalConstraints

Validates withdrawal constraints (emergency mode, minimum balance)

Internal function to validate withdrawal constraints and minimum balance requirements

Notes:

• security: Enforces minimum balance requirements unless in emergency mode

• validation: Validates remaining balance >= minimum threshold

• state-changes: No state changes - view function

• events: No events emitted

• errors: Throws WouldBreachMinimum if below minimum balance threshold

• reentrancy: Not applicable - view function

• access: Internal function - no access restrictions

• oracle: No oracle dependencies

function _validateWithdrawalConstraints(uint256 withdrawAmount, uint256 aaveBalance) internal view;

Parameters

_validateExpectedWithdrawal

Validates expected withdrawal amounts before external call

Validates expected withdrawal amounts before external call

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function _validateExpectedWithdrawal(uint256 withdrawAmount) internal view;

Parameters

_executeAaveWithdrawal

Executes the Aave withdrawal with proper error handling

Executes the Aave withdrawal with proper error handling

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function _executeAaveWithdrawal(uint256 originalAmount, uint256 withdrawAmount, uint256 usdcBefore)
    internal
    returns (uint256 usdcWithdrawn);

Parameters

Returns

_validateWithdrawalResult

Validates the withdrawal result and slippage

Validates the withdrawal result and slippage

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function _validateWithdrawalResult(
    uint256 originalAmount,
    uint256 withdrawAmount,
    uint256 usdcBefore,
    uint256 usdcWithdrawn
) internal view;

Parameters

claimAaveRewards

Claim Aave rewards (if any)

Claims any available Aave protocol rewards for the vault's aUSDC position

Notes:

• security: No additional security checks required - Aave handles reward validation

• validation: No input validation required - view function checks pending rewards

• state-changes: Claims rewards to vault address, updates reward tracking

• events: Emits AaveRewardsClaimed with reward details

• errors: No errors thrown - safe to call even with no rewards

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to VAULT_MANAGER_ROLE

• oracle: No oracle dependency for reward claims

function claimAaveRewards() external nonReentrant returns (uint256 rewardsClaimed);

Returns

harvestAaveYield

Harvest Aave yield and distribute via YieldShift

Harvests available yield from Aave lending, charges protocol fees, distributes net yield

Notes:

• security: Uses CEI pattern, validates slippage, enforces harvest threshold

• validation: Validates available yield >= harvestThreshold before harvesting

• state-changes: Updates lastHarvestTime, totalFeesCollected, totalYieldHarvested

• events: Emits AaveYieldHarvested with harvest details

• errors: Throws BelowThreshold if yield < harvestThreshold, ExcessiveSlippage if slippage too high

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to VAULT_MANAGER_ROLE

• oracle: No oracle dependency for yield harvesting

function harvestAaveYield() public nonReentrant returns (uint256 yieldHarvested);

Returns

getAvailableYield

Returns the total available yield from Aave lending

Calculates yield based on current aToken balance vs principal deposited

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function getAvailableYield() public view returns (uint256);

Returns

getYieldDistribution

Returns the breakdown of yield distribution between users and protocol

Shows how yield is allocated according to current distribution parameters

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function getYieldDistribution()
    external
    view
    returns (uint256 protocolYield, uint256 userYield, uint256 hedgerYield);

Returns

getAaveBalance

Returns the current balance of aTokens held by this vault

Represents the total amount deposited in Aave plus accrued interest

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function getAaveBalance() public view returns (uint256);

Returns

depositUnderlying

Generic external vault adapter deposit entrypoint.

Delegates to deployToAave using adapter-standard semantics for QuantillonVault.

Notes:

• security: Callable by configured integration flows; underlying logic validates amount and roles.

• validation: Reverts on zero amount, invalid state, or failed Aave interaction in delegate path.

• state-changes: Updates principal tracking and deploys USDC to Aave via delegated function.

• events: Emits deployment/yield-related events from delegated function.

• errors: Propagates validation, transfer, and Aave interaction errors from delegated function.

• reentrancy: Reentrancy protections are enforced by delegated function flow.

• access: Access control is enforced by delegated function flow.

• oracle: No direct oracle dependency in this wrapper.

function depositUnderlying(uint256 usdcAmount) external override returns (uint256 sharesReceived);

Parameters

Returns

withdrawUnderlying

Generic external vault adapter withdraw entrypoint.

Delegates to withdrawFromAave and returns actual USDC withdrawn.

Notes:

• security: Callable by configured integration flows; delegated function enforces safety checks.

• validation: Reverts on invalid amount/balance or failed Aave withdrawal in delegate path.

• state-changes: Updates principal tracking and vault balances through delegated function.

• events: Emits withdrawal-related events from delegated function.

• errors: Propagates delegated function errors for validation and Aave failures.

• reentrancy: Reentrancy protections are enforced by delegated function flow.

• access: Access control is enforced by delegated function flow.

• oracle: No direct oracle dependency in this wrapper.

function withdrawUnderlying(uint256 usdcAmount) external override returns (uint256 usdcWithdrawn);

Parameters

Returns

harvestYield

Generic external vault adapter harvest entrypoint.

Delegates to harvestAaveYield to realize and route harvested yield.

Notes:

• security: Delegated function enforces configured role and dependency checks.

• validation: Reverts when harvesting preconditions fail in delegated function.

• state-changes: Realizes Aave yield and updates accounting in delegated function.

• events: Emits harvest/yield distribution events from delegated function.

• errors: Propagates delegated function errors.

• reentrancy: Reentrancy protections are enforced by delegated function flow.

• access: Access control is enforced by delegated function flow.

• oracle: No direct oracle dependency in this wrapper.

function harvestYield() external override returns (uint256 harvestedYield);

Returns

totalUnderlying

Returns total underlying balance for adapter-generic reads.

Mirrors getAaveBalance for adapter-standard interface compatibility.

Notes:

• security: Read-only accessor.

• validation: No input validation required.

• state-changes: No state changes.

• events: No events emitted.

• errors: No errors expected.

• reentrancy: Not applicable for view function.

• access: Public view.

• oracle: No oracle dependency.

function totalUnderlying() external view override returns (uint256 underlyingBalance);

Returns

getAccruedInterest

Returns the total interest accrued from Aave lending

Calculates interest as current balance minus principal deposited

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function getAccruedInterest() external view returns (uint256);

Returns

getAaveAPY

Returns the current APY offered by Aave for the deposited asset

Fetches the supply rate from Aave's reserve data

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function getAaveAPY() external view returns (uint256);

Returns

getAavePositionDetails

Returns detailed information about the Aave position

Provides comprehensive data about the vault's Aave lending position

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function getAavePositionDetails()
    external
    view
    returns (uint256 principalDeposited_, uint256 currentBalance, uint256 aTokenBalance, uint256 lastUpdateTime);

Returns

getAaveMarketData

Returns current Aave market data for the deposited asset

Fetches real-time market information from Aave protocol

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function getAaveMarketData()
    external
    view
    returns (uint256 supplyRate, uint256 utilizationRate, uint256 totalSupply, uint256 availableLiquidity);

Returns

checkAaveHealth

Performs health checks on the Aave position

Validates that the Aave position is healthy and functioning properly

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function checkAaveHealth() external view returns (bool isHealthy, bool pauseStatus, uint256 lastUpdate);

Returns

_isAaveHealthy

Check if Aave protocol is healthy

Checks if Aave protocol is functioning properly by verifying reserve data

Notes:

• security: Uses try-catch to handle potential failures gracefully

• validation: No input validation required

• state-changes: No state changes - view function only

• events: No events emitted

• errors: No errors thrown - uses try-catch

• reentrancy: Not applicable - view function

• access: Internal function - no access restrictions

• oracle: No oracle dependencies

function _isAaveHealthy() internal view returns (bool);

Returns

autoRebalance

Automatically rebalance the vault allocation

Rebalances the vault allocation based on optimal allocation calculations

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function autoRebalance() external returns (bool rebalanced, uint256 newAllocation, uint256 expectedYield);

Returns

calculateOptimalAllocation

Calculates the optimal allocation of funds to Aave

Determines best allocation strategy based on current market conditions

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function calculateOptimalAllocation() external view returns (uint256 optimalAllocation, uint256 expectedYield);

Returns

setMaxAaveExposure

Sets the maximum exposure limit for Aave deposits

Governance function to control risk by limiting Aave exposure

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function setMaxAaveExposure(uint256 _maxExposure) external;

Parameters

emergencyWithdrawFromAave

Emergency withdrawal from Aave protocol

Emergency function to withdraw all funds from Aave protocol

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function emergencyWithdrawFromAave() external nonReentrant returns (uint256 amountWithdrawn);

Returns

getRiskMetrics

Returns comprehensive risk metrics for the Aave position

Provides detailed risk analysis including concentration and volatility metrics

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function getRiskMetrics()
    external
    view
    returns (uint256 exposureRatio, uint256 concentrationRisk, uint256 liquidityRisk);

Returns

updateAaveParameters

Update Aave parameters

Updates harvest threshold, yield fee, and rebalance threshold

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function updateAaveParameters(uint256 newHarvestThreshold, uint256 newYieldFee, uint256 newRebalanceThreshold)
    external;

Parameters

updateYieldShift

Updates the YieldShift contract reference.

Governance-only setter used to rotate the YieldShift dependency for harvested-yield routing.

Notes:

• security: Restricted to governance and validates non-zero dependency address.

• validation: Reverts if newYieldShift is zero address.

• state-changes: Updates yieldShift reference.

• events: Emits AaveParameterUpdated with old/new encoded addresses.

• errors: Reverts on unauthorized access or invalid address.

• reentrancy: No token transfer side effects; single storage write after validation.

• access: Restricted to governance through AccessControlLibrary.onlyGovernance.

• oracle: No oracle dependencies.

function updateYieldShift(address newYieldShift) external;

Parameters

setYieldVaultId

Sets the vault id used when routing harvested yield via YieldShift.

Governance-only setter for destination vault id used by downstream YieldShift calls.

Notes:

• security: Restricted to governance and prevents unset/invalid id value.

• validation: Reverts if newYieldVaultId is zero.

• state-changes: Updates yieldVaultId.

• events: Emits AaveParameterUpdated with old/new vault id.

• errors: Reverts on unauthorized access or invalid vault id.

• reentrancy: No external calls after validation except event emission.

• access: Restricted to governance through AccessControlLibrary.onlyGovernance.

• oracle: No oracle dependencies.

function setYieldVaultId(uint256 newYieldVaultId) external;

Parameters

getAaveConfig

Returns the current Aave integration configuration

Provides access to all configuration parameters for Aave integration

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function getAaveConfig()
    external
    view
    returns (address aavePool_, address aUSDC_, uint256 harvestThreshold_, uint256 yieldFee_, uint256 maxExposure_);

Returns

toggleEmergencyMode

Toggles emergency mode for the Aave vault

Emergency function to enable/disable emergency mode during critical situations

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function toggleEmergencyMode(bool enabled, string calldata reason) external;

Parameters

pause

Pauses all Aave vault operations

Emergency function to halt all vault operations when needed

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function pause() external;

unpause

Unpauses Aave vault operations

Resumes normal vault operations after emergency is resolved

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function unpause() external;

recoverToken

Recovers accidentally sent ERC20 tokens from the vault

Emergency function to recover tokens that are not part of normal operations

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function recoverToken(address token, uint256 amount) external;

Parameters

recoverETH

Recovers accidentally sent ETH from the vault

Emergency function to recover ETH that shouldn't be in the vault

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Updates contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by reentrancy guard

• access: Restricted to authorized roles

• oracle: Requires fresh oracle price data

function recoverETH() external;

Events

DeployedToAave

OPTIMIZED: Indexed operation type for efficient filtering

event DeployedToAave(string indexed operationType, uint256 amount, uint256 aTokensReceived, uint256 newBalance);

WithdrawnFromAave

event WithdrawnFromAave(
    string indexed operationType, uint256 amountRequested, uint256 amountWithdrawn, uint256 newBalance
);

AaveYieldHarvested

event AaveYieldHarvested(string indexed harvestType, uint256 yieldHarvested, uint256 protocolFee, uint256 netYield);

AaveRewardsClaimed

event AaveRewardsClaimed(address indexed rewardToken, uint256 rewardAmount, address recipient);

PositionRebalanced

OPTIMIZED: Indexed reason and parameter for efficient filtering

event PositionRebalanced(string indexed reason, uint256 oldAllocation, uint256 newAllocation);

AaveParameterUpdated

event AaveParameterUpdated(string indexed parameter, uint256 oldValue, uint256 newValue);

EmergencyWithdrawal

event EmergencyWithdrawal(string indexed reason, uint256 amountWithdrawn, uint256 timestamp);

EmergencyModeToggled

event EmergencyModeToggled(string indexed reason, bool enabled);

IMockMorphoVault

Git Source

Functions

depositUnderlying

Deposits underlying assets into the mock Morpho vault.

Test-only vault interface used by the adapter in localhost simulations.

Notes:

• security: External dependency call; trust model is environment-specific.

• validation: Reverts on invalid amount or vault-side checks.

• state-changes: Updates vault share/asset accounting.

• events: Vault implementation may emit deposit events.

• errors: Reverts on vault-side failures.

• reentrancy: Interface declaration only.

• access: Access control defined by vault implementation.

• oracle: No oracle dependencies.

function depositUnderlying(uint256 assets, address onBehalfOf) external returns (uint256 shares);

Parameters

Returns

withdrawUnderlying

Withdraws underlying assets from the mock Morpho vault.

Test-only vault interface used by the adapter in localhost simulations.

Notes:

• security: External dependency call; trust model is environment-specific.

• validation: Reverts on insufficient balance or vault-side checks.

• state-changes: Updates vault share/asset accounting.

• events: Vault implementation may emit withdrawal events.

• errors: Reverts on vault-side failures.

• reentrancy: Interface declaration only.

• access: Access control defined by vault implementation.

• oracle: No oracle dependencies.

function withdrawUnderlying(uint256 assets, address to) external returns (uint256 withdrawn);

Parameters

Returns

totalUnderlyingOf

Returns underlying assets held for an account.

Read helper used by the adapter for principal/yield accounting.

Notes:

• security: Read-only helper.

• validation: No input validation required at interface level.

• state-changes: No state changes.

• events: No events emitted.

• errors: May revert if implementation cannot service read.

• reentrancy: Not applicable for view function.

• access: Public view at implementation level.

• oracle: No oracle dependencies.

function totalUnderlyingOf(address account) external view returns (uint256);

Parameters

Returns

MorphoStakingVaultAdapter

Git Source

Inherits: AccessControl, ReentrancyGuard, IExternalStakingVault

Title: MorphoStakingVaultAdapter

Generic external vault adapter for Morpho-like third-party vaults.

State Variables

GOVERNANCE_ROLE

bytes32 public constant GOVERNANCE_ROLE = keccak256("GOVERNANCE_ROLE")

VAULT_MANAGER_ROLE

bytes32 public constant VAULT_MANAGER_ROLE = keccak256("VAULT_MANAGER_ROLE")

USDC

IERC20 public immutable USDC

morphoVault

IMockMorphoVault public morphoVault

yieldShift

IYieldShift public yieldShift

yieldVaultId

uint256 public yieldVaultId

principalDeposited

uint256 public principalDeposited

Functions

constructor

Initializes Morpho adapter dependencies and roles.

Configures governance/operator roles and immutable USDC reference.

Notes:

• security: Validates non-zero dependency addresses and vault id.

• validation: Reverts on zero address or zero yieldVaultId_.

• state-changes: Initializes role assignments and adapter dependency pointers.

• events: No events emitted by constructor.

• errors: Reverts with ZeroAddress or InvalidVault on invalid inputs.

• reentrancy: Not applicable - constructor only.

• access: Public constructor.

• oracle: No oracle dependencies.

constructor(address admin, address usdc_, address morphoVault_, address yieldShift_, uint256 yieldVaultId_) ;

Parameters

depositUnderlying

Deposits USDC into the configured Morpho vault.

Pulls USDC from caller, deposits to Morpho, and increases tracked principal.

Notes:

• security: Restricted to VAULT_MANAGER_ROLE; protected by nonReentrant.

• validation: Reverts on zero amount or zero-share deposit outcome.

• state-changes: Increases principalDeposited and updates vault position.

• events: Emits downstream transfer/deposit events from dependencies.

• errors: Reverts on transfer/approval/deposit failures.

• reentrancy: Protected by nonReentrant.

• access: Restricted to vault manager role.

• oracle: No oracle dependencies.

function depositUnderlying(uint256 usdcAmount)
    external
    override
    onlyRole(VAULT_MANAGER_ROLE)
    nonReentrant
    returns (uint256 sharesReceived);

Parameters

Returns

withdrawUnderlying

Withdraws USDC principal from the configured Morpho vault.

Caps withdrawal to tracked principal, redeems from Morpho, then returns USDC to caller.

Notes:

• security: Restricted to VAULT_MANAGER_ROLE; protected by nonReentrant.

• validation: Reverts on zero amount or when no principal is tracked.

• state-changes: Decreases principalDeposited and updates vault position.

• events: Emits downstream transfer/withdrawal events from dependencies.

• errors: Reverts on withdrawal mismatch or transfer failures.

• reentrancy: Protected by nonReentrant.

• access: Restricted to vault manager role.

• oracle: No oracle dependencies.

function withdrawUnderlying(uint256 usdcAmount)
    external
    override
    onlyRole(VAULT_MANAGER_ROLE)
    nonReentrant
    returns (uint256 usdcWithdrawn);

Parameters

Returns

harvestYield

Harvests accrued yield from Morpho and routes it to YieldShift.

Withdraws only the amount above tracked principal, then forwards to YieldShift.

Notes:

• security: Restricted to VAULT_MANAGER_ROLE; protected by nonReentrant.

• validation: Reverts only on downstream failures; returns zero when no yield is available.

• state-changes: Leaves principal unchanged and routes yield through YieldShift.

• events: Emits downstream transfer/yield events from dependencies.

• errors: Reverts on downstream withdrawal, approval, or addYield failures.

• reentrancy: Protected by nonReentrant.

• access: Restricted to vault manager role.

• oracle: No oracle dependencies.

function harvestYield()
    external
    override
    onlyRole(VAULT_MANAGER_ROLE)
    nonReentrant
    returns (uint256 harvestedYield);

Returns

totalUnderlying

Returns current underlying balance controlled by this adapter.

Read helper used by QuantillonVault for exposure accounting.

Notes:

• security: Read-only helper.

• validation: No input validation required.

• state-changes: No state changes.

• events: No events emitted.

• errors: May revert if downstream vault read fails.

• reentrancy: Not applicable for view function.

• access: Public view.

• oracle: No oracle dependencies.

function totalUnderlying() external view override returns (uint256 underlyingBalance);

Returns

setMorphoVault

Updates the configured Morpho vault endpoint.

Governance maintenance hook for swapping vault implementation/address.

Notes:

• security: Restricted to GOVERNANCE_ROLE.

• validation: Reverts on zero address input.

• state-changes: Updates morphoVault pointer.

• events: Emits MorphoVaultUpdated.

• errors: Reverts with ZeroAddress for invalid input.

• reentrancy: No external calls after state change.

• access: Restricted to governance role.

• oracle: No oracle dependencies.