Quantillon Protocol Smart Contracts

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

📖 Overview

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

📚 Documentation

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

🎯 Key Features

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

🏗️ Architecture

Core Contracts

🚀 Quick Start

Prerequisites

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

1. Clone and Setup

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

2. Environment Configuration

# Copy environment template
cp .env.example .env

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

# Environment variables are ready to use

3. Build and Test

# Build contracts
make build

# Run tests
make test

# Run security analysis
make slither

🚀 Deployment

🔐 Multi-Phase Deployment Strategy

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

Key Features:

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

See Deployment Guide for complete details.

🔐 Secure Deployment

The protocol uses standard environment variable configuration:

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

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

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

📋 Deployment Options

🔧 Deployment Features

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

🛡️ Security Features

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

🧪 Testing

Run All Tests

make test

Run Specific Test Suites

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

# Integration tests
forge test --match-contract IntegrationTests

# Security tests
forge test --match-contract SecurityTests

Gas Analysis

make gas-analysis

🔍 Security

Automated Security Analysis

# Run Slither static analysis
make slither

# Run Mythril analysis
make mythril

# Validate NatSpec documentation
make validate-natspec

Security Features

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

📊 Development

Available Commands

# Build contracts
make build

# Run tests
make test

# Run security analysis
make slither

# Generate documentation
make docs

# Clean build artifacts
make clean

# Gas analysis
make gas-analysis

Code Quality

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

🤝 Contributing

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

Development Guidelines

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

📄 License

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

🔗 Links

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

🙏 Acknowledgments

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

Contents

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

Contents

• IPool
• IPoolAddressesProvider
• IRewardsController
• ReserveData
• AaveVault

IPool

Git Source

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

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

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) external 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) external 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() external 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() external view returns (uint256);

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

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);

Contents

• YieldShift

YieldShift

Git Source

Inherits: Initializable, ReentrancyGuardUpgradeable, AccessControlUpgradeable, PausableUpgradeable, SecureUpgradeable

Author: Quantillon Labs - Nicolas Bellengé - @chewbaccoin

Dynamic yield distribution system balancing rewards between users and hedgers

Main characteristics:

• Dynamic yield allocation based on pool balance ratios
• Time-weighted average price (TWAP) calculations for stability
• Multiple yield sources integration (Aave, fees, interest differentials)
• Automatic yield distribution with holding period requirements
• Emergency pause mechanism for crisis situations
• Upgradeable via UUPS pattern

Yield shift mechanics:

• Base yield shift determines default allocation (default 50/50)
• Maximum yield shift caps allocation changes (default 90/10)
• Adjustment speed controls how quickly shifts occur
• Target pool ratio defines optimal balance point
• Real-time calculations based on pool metrics

Distribution algorithm:

• Monitors user pool vs hedger pool size ratios
• Adjusts yield allocation to incentivize balance
• Higher user pool → more yield to hedgers (attract hedging)
• Higher hedger pool → more yield to users (attract deposits)
• Gradual adjustments prevent dramatic shifts
• Flash deposit protection through eligible pool size calculations
• Only deposits meeting holding period requirements count toward yield distribution

Yield sources:

• Aave yield from USDC deposits in lending protocols
• Protocol fees from minting, redemption, and trading
• Interest rate differentials from hedging operations
• External yield farming opportunities
• Authorized source validation for security

Time-weighted calculations:

• 24-hour TWAP for pool size measurements
• Historical data tracking for trend analysis
• Maximum history length prevents unbounded storage
• Drift tolerance for timestamp validation
• Automatic data cleanup and optimization

Holding period requirements:

• Minimum 7-day holding period for yield claims
• Prevents yield farming attacks and speculation
• Encourages long-term protocol participation
• Tracked per user with deposit timestamps
• Enhanced protection against flash deposit manipulation
• Eligible pool sizes exclude recent deposits from yield calculations
• Dynamic discount system based on deposit timing and activity

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
• Authorized yield source validation
• Secure yield distribution mechanisms
• Flash deposit attack prevention through holding period requirements
• Eligible pool size calculations for yield distribution
• Time-weighted protection against yield manipulation

Integration points:

• User pool for deposit and staking metrics
• Hedger pool for hedging exposure metrics
• Aave vault for yield generation and harvesting
• stQEURO token for user yield distribution
• USDC for yield payments and transfers

Note: security-contact: team@quantillon.money

State Variables

GOVERNANCE_ROLE

bytes32 public constant GOVERNANCE_ROLE = keccak256("GOVERNANCE_ROLE")

YIELD_MANAGER_ROLE

bytes32 public constant YIELD_MANAGER_ROLE = keccak256("YIELD_MANAGER_ROLE")

EMERGENCY_ROLE

bytes32 public constant EMERGENCY_ROLE = keccak256("EMERGENCY_ROLE")

usdc

IERC20 public usdc

userPool

IUserPool public userPool

hedgerPool

IHedgerPool public hedgerPool

aaveVault

IAaveVault public aaveVault

stQEURO

IstQEURO public stQEURO

TIME_PROVIDER

TimeProvider contract for centralized time management

Used to replace direct block.timestamp usage for testability and consistency

TimeProvider public immutable TIME_PROVIDER

baseYieldShift

uint256 public baseYieldShift

maxYieldShift

uint256 public maxYieldShift

adjustmentSpeed

uint256 public adjustmentSpeed

targetPoolRatio

uint256 public targetPoolRatio

MIN_HOLDING_PERIOD

uint256 public constant MIN_HOLDING_PERIOD = 7 days

TWAP_PERIOD

uint256 public constant TWAP_PERIOD = 24 hours

MAX_TIME_ELAPSED

uint256 public constant MAX_TIME_ELAPSED = 365 days

currentYieldShift

uint256 public currentYieldShift

lastUpdateTime

uint256 public lastUpdateTime

totalYieldGenerated

uint256 public totalYieldGenerated

totalYieldDistributed

uint256 public totalYieldDistributed

userYieldPool

uint256 public userYieldPool

hedgerYieldPool

uint256 public hedgerYieldPool

treasury

address public treasury

yieldSources

mapping(bytes32 => uint256) public yieldSources

yieldSourceNames

bytes32[] public yieldSourceNames

authorizedYieldSources

mapping(address => bool) public authorizedYieldSources

sourceToYieldType

mapping(address => bytes32) public sourceToYieldType

userPendingYield

mapping(address => uint256) public userPendingYield

hedgerPendingYield

mapping(address => uint256) public hedgerPendingYield

userLastClaim

mapping(address => uint256) public userLastClaim

hedgerLastClaim

mapping(address => uint256) public hedgerLastClaim

lastDepositTime

mapping(address => uint256) public lastDepositTime

userPoolHistory

PoolSnapshot[] public userPoolHistory

hedgerPoolHistory

PoolSnapshot[] public hedgerPoolHistory

MAX_HISTORY_LENGTH

uint256 public constant MAX_HISTORY_LENGTH = 1000

yieldShiftHistory

YieldShiftSnapshot[] public yieldShiftHistory

Functions

constructor

Constructor for YieldShift implementation

Sets up the time provider and disables initialization on implementation for security

Notes:

• security: Validates time provider address and disables initialization on implementation

• validation: Validates time provider is not zero address

• state-changes: Sets time provider and disables initializers

• events: No events emitted

• errors: Throws ZeroAddress if time provider is zero

• reentrancy: Not protected - constructor only

• access: Public constructor

• oracle: No oracle dependencies

constructor(TimeProvider _TIME_PROVIDER) ;

Parameters

initialize

Initialize the YieldShift 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 _userPool,
    address _hedgerPool,
    address _aaveVault,
    address _stQEURO,
    address _timelock,
    address _treasury
) public initializer;

Parameters

bootstrapDefaults

Governance bootstrap to set initial histories and source metadata after minimal init

function bootstrapDefaults() external;

updateYieldDistribution

Updates the yield distribution between users and hedgers

Recalculates and applies new yield distribution ratios based on current pool states

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 updateYieldDistribution() external nonReentrant whenNotPaused;

addYield

Add yield from authorized sources

Adds yield from authorized sources and distributes it according to current yield shift

Notes:

• security: Validates caller is authorized for the yield source

• validation: Validates yield amount is positive and matches actual received

• state-changes: Updates yield sources and total yield generated

• events: Emits YieldAdded event

• errors: Throws if caller is unauthorized or yield amount mismatch

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to authorized yield sources

• oracle: No oracle dependencies

function addYield(uint256 yieldAmount, bytes32 source) external nonReentrant;

Parameters

claimUserYield

Claim user yield

Claims yield for a user after holding period requirements are met

Notes:

• security: Validates caller is authorized and holding period is met

• validation: Validates user has pending yield and meets holding period

• state-changes: Updates user pending yield and transfers USDC

• events: Emits YieldClaimed event

• errors: Throws if caller is unauthorized or holding period not met

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to user or user pool

• oracle: No oracle dependencies

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

Parameters

Returns

claimHedgerYield

Claim hedger yield

Claims yield for a hedger

Notes:

• security: Validates caller is authorized

• validation: Validates hedger has pending yield

• state-changes: Updates hedger pending yield and transfers USDC

• events: Emits HedgerYieldClaimed event

• errors: Throws if caller is unauthorized or insufficient yield

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to hedger or hedger pool

• oracle: No oracle dependencies

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

Parameters

Returns

_calculateOptimalYieldShift

Calculate optimal yield shift based on current pool ratio

Calculates optimal yield allocation to incentivize pool balance

Notes:

• security: Uses tolerance checks to prevent excessive adjustments

• validation: No input validation required - view function

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

• events: No events emitted

• errors: No errors thrown - safe arithmetic used

• reentrancy: Not applicable - view function

• access: Internal function - no access restrictions

• oracle: No oracle dependencies

function _calculateOptimalYieldShift(uint256 poolRatio) internal view returns (uint256);

Parameters

Returns

_applyGradualAdjustment

Apply gradual adjustment to yield shift to prevent sudden changes

Gradually adjusts yield shift based on adjustmentSpeed to prevent volatility

Notes:

• security: Limits adjustment speed to prevent sudden changes

• validation: No input validation required - view function

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

• events: No events emitted

• errors: No errors thrown - safe arithmetic used

• reentrancy: Not applicable - view function

• access: Internal function - no access restrictions

• oracle: No oracle dependencies

function _applyGradualAdjustment(uint256 targetShift) internal view returns (uint256);

Parameters

Returns

_getCurrentPoolMetrics

Get current pool metrics

Returns current pool sizes and ratio for yield shift 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 _getCurrentPoolMetrics()
    internal
    view
    returns (uint256 userPoolSize, uint256 hedgerPoolSize, uint256 poolRatio);

Returns

_getEligiblePoolMetrics

Get eligible pool metrics that only count deposits meeting holding period requirements

SECURITY: Prevents flash deposit attacks by excluding recent deposits from yield 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 _getEligiblePoolMetrics()
    internal
    view
    returns (uint256 userPoolSize, uint256 hedgerPoolSize, uint256 poolRatio);

Returns

_calculateHoldingPeriodDiscount

Calculate holding period discount based on recent deposit activity

Returns a percentage (in basis points) representing eligible deposits

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 _calculateHoldingPeriodDiscount() internal view returns (uint256 discountBps);

Returns

_isWithinTolerance

Check if a value is within tolerance of a target value

Helper function for yield shift calculations

Notes:

• security: Uses safe arithmetic to prevent overflow

• validation: No input validation required - pure function

• state-changes: No state changes - pure function

• events: No events emitted

• errors: No errors thrown - safe arithmetic used

• reentrancy: Not applicable - pure function

• access: Internal function - no access restrictions

• oracle: No oracle dependencies

function _isWithinTolerance(uint256 value, uint256 target, uint256 toleranceBps) internal pure returns (bool);

Parameters

Returns

updateLastDepositTime

Updates the last deposit timestamp for a user

Called by UserPool to track user deposit timing for yield 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 updateLastDepositTime(address user) external;

Parameters

getCurrentYieldShift

Returns the current yield shift percentage

Shows how much yield is currently being shifted between pools

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 getCurrentYieldShift() external view returns (uint256);

Returns

getUserPendingYield

Returns the pending yield amount for a specific user

Calculates unclaimed yield based on user's deposits and current rates

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 getUserPendingYield(address user) external view returns (uint256);

Parameters

Returns

getHedgerPendingYield

Returns the pending yield amount for a specific hedger

Calculates unclaimed yield based on hedger's positions and current rates

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 getHedgerPendingYield(address hedger) external view returns (uint256);

Parameters

Returns

getTotalYieldGenerated

Returns the total yield generated by the protocol

Aggregates all yield generated from various sources

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 getTotalYieldGenerated() external view returns (uint256);

Returns

getYieldDistributionBreakdown

Returns detailed breakdown of yield distribution

Shows how yield is allocated between different pools and stakeholders

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 getYieldDistributionBreakdown()
    external
    view
    returns (uint256 userYieldPool_, uint256 hedgerYieldPool_, uint256 distributionRatio);

Returns

getPoolMetrics

Returns comprehensive metrics for both user and hedger pools

Provides detailed analytics about pool performance and utilization

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 getPoolMetrics()
    external
    view
    returns (uint256 userPoolSize, uint256 hedgerPoolSize, uint256 poolRatio, uint256 targetRatio);

Returns

calculateOptimalYieldShift

Calculates the optimal yield shift based on current market conditions

Uses algorithms to determine best yield distribution strategy

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 calculateOptimalYieldShift() external view returns (uint256 optimalShift, uint256 currentDeviation);

Returns

getYieldSources

Returns information about all yield sources

Provides details about different yield-generating mechanisms

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 getYieldSources()
    external
    view
    returns (uint256 aaveYield, uint256 protocolFees, uint256 interestDifferential, uint256 otherSources);

Returns

getHoldingPeriodProtectionStatus

Returns the current holding period protection status

Useful for monitoring and debugging holding period protection

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 getHoldingPeriodProtectionStatus()
    external
    view
    returns (uint256 minHoldingPeriod, uint256 baseDiscount, uint256 currentDiscount, uint256 timeSinceLastUpdate);

Returns

getHistoricalYieldShift

Returns historical yield shift data for a specified period

Provides analytics about yield shift patterns over time

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 getHistoricalYieldShift(uint256 period)
    external
    view
    returns (uint256 averageShift, uint256 maxShift, uint256 minShift, uint256 volatility);

Parameters

Returns

getYieldPerformanceMetrics

Returns comprehensive performance metrics for yield operations

Provides detailed analytics about yield performance and efficiency

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 getYieldPerformanceMetrics()
    external
    view
    returns (
        uint256 totalYieldDistributed_,
        uint256 averageUserYield,
        uint256 averageHedgerYield,
        uint256 yieldEfficiency
    );

Returns

_calculateUserAllocation

Calculate user allocation from current yield shift

Calculates how much yield should be allocated to users

Notes:

• security: Uses safe arithmetic to prevent overflow

• validation: No input validation required - view function

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

• events: No events emitted

• errors: No errors thrown - safe arithmetic used

• reentrancy: Not applicable - view function

• access: Internal function - no access restrictions

• oracle: No oracle dependencies

function _calculateUserAllocation() internal view returns (uint256);

Returns

_calculateHedgerAllocation

Calculate hedger allocation from current yield shift

Calculates how much yield should be allocated to hedgers

Notes:

• security: Uses safe arithmetic to prevent overflow

• validation: No input validation required - view function

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

• events: No events emitted

• errors: No errors thrown - safe arithmetic used

• reentrancy: Not applicable - view function

• access: Internal function - no access restrictions

• oracle: No oracle dependencies

function _calculateHedgerAllocation() internal view returns (uint256);

Returns

setYieldShiftParameters

Set yield shift parameters

Sets the base yield shift, maximum yield shift, and adjustment speed

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates yield shift ranges and adjustment speed

• state-changes: Updates yield shift parameters

• events: Emits YieldShiftParametersUpdated event

• errors: Throws if parameters are invalid

• reentrancy: Protected by reentrancy guard

• access: Restricted to governance role

• oracle: No oracle dependencies

function setYieldShiftParameters(uint256 _baseYieldShift, uint256 _maxYieldShift, uint256 _adjustmentSpeed)
    external;

Parameters

setTargetPoolRatio

Sets the target ratio between user and hedger pools

Governance function to adjust pool balance for optimal yield distribution

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 setTargetPoolRatio(uint256 _targetPoolRatio) external;

Parameters

authorizeYieldSource

Authorize a yield source for specific yield type

Authorizes a yield source to add yield of a specific type

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 authorizeYieldSource(address source, bytes32 yieldType) external;

Parameters

revokeYieldSource

Revoke authorization for a yield source

Revokes authorization for a yield source

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 revokeYieldSource(address source) external;

Parameters

updateUserPool

Governance-only setters to wire references post-initialization (phased deploy)

function updateUserPool(address _userPool) external;

updateHedgerPool

function updateHedgerPool(address _hedgerPool) external;

updateAaveVault

function updateAaveVault(address _aaveVault) external;

updateStQEURO

function updateStQEURO(address _stQEURO) external;

updateYieldAllocation

Updates yield allocation for a specific user or hedger

Called by pools to update individual yield allocations

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 updateYieldAllocation(address user, uint256 amount, bool isUser) external;

Parameters

emergencyYieldDistribution

Executes emergency yield distribution with specified amounts

Emergency function to manually distribute yield 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 emergencyYieldDistribution(uint256 userAmount, uint256 hedgerAmount) external;

Parameters

pauseYieldDistribution

Pauses all yield distribution operations

Emergency function to halt yield distribution 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 pauseYieldDistribution() external;

resumeYieldDistribution

Resumes yield distribution operations after being paused

Restarts yield distribution when 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 resumeYieldDistribution() external;

getYieldShiftConfig

Returns the current yield shift configuration

Provides access to all yield shift parameters and settings

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 getYieldShiftConfig()
    external
    view
    returns (uint256 baseShift, uint256 maxShift, uint256 adjustmentSpeed_, uint256 lastUpdate);

Returns

isYieldDistributionActive

Checks if yield distribution is currently active

Returns false if paused or in emergency mode

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 isYieldDistributionActive() external view returns (bool);

Returns

isYieldSourceAuthorized

Check if a yield source is authorized

Checks if a yield source is authorized for a specific yield type

Checks if a yield source is authorized for a specific yield type

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

• 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 isYieldSourceAuthorized(address source, bytes32 yieldType) external view returns (bool);

Parameters

Returns

checkAndUpdateYieldDistribution

Checks current conditions and updates yield distribution if needed

Automated function to maintain optimal yield distribution

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 checkAndUpdateYieldDistribution() external;

forceUpdateYieldDistribution

Forces an immediate update of yield distribution

Emergency function to bypass normal update conditions and force distribution

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 forceUpdateYieldDistribution() external;

getTimeWeightedAverage

Get time weighted average of pool history

Calculates time weighted average of pool history over a specified period

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 getTimeWeightedAverage(PoolSnapshot[] storage poolHistory, uint256 period, bool isUserPool)
    internal
    view
    returns (uint256);

Parameters

Returns

_recordPoolSnapshot

Record pool snapshot

Records current pool metrics as a snapshot for historical tracking

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 _recordPoolSnapshot() internal;

_recordPoolSnapshotWithEligibleSizes

Record pool snapshot using eligible pool sizes to prevent manipulation

SECURITY: Uses eligible pool sizes that respect holding period requirements

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 _recordPoolSnapshotWithEligibleSizes(uint256 eligibleUserPoolSize, uint256 eligibleHedgerPoolSize)
    internal;

Parameters

_addToPoolHistory

Add pool snapshot to history

Adds a pool snapshot to the history array with size management

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 _addToPoolHistory(PoolSnapshot[] storage poolHistory, uint256 poolSize, bool isUserPool) internal;

Parameters

recoverToken

Recovers accidentally sent ERC20 tokens from the contract

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 contract

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

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;

updateHoldingPeriodProtection

Update holding period protection parameters

SECURITY: Only governance can update these critical security 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 updateHoldingPeriodProtection(uint256 _minHoldingPeriod, uint256 _baseDiscount, uint256 _maxTimeFactor)
    external;

Parameters

Events

YieldDistributionUpdated

OPTIMIZED: Indexed timestamp for efficient time-based filtering

event YieldDistributionUpdated(
    uint256 newYieldShift, uint256 userYieldAllocation, uint256 hedgerYieldAllocation, uint256 indexed timestamp
);

UserYieldClaimed

event UserYieldClaimed(address indexed user, uint256 yieldAmount, uint256 timestamp);

HedgerYieldClaimed

event HedgerYieldClaimed(address indexed hedger, uint256 yieldAmount, uint256 timestamp);

YieldAdded

OPTIMIZED: Indexed source and timestamp for efficient filtering

event YieldAdded(uint256 yieldAmount, string indexed source, uint256 indexed timestamp);

YieldShiftParametersUpdated

OPTIMIZED: Indexed parameter type for efficient filtering

event YieldShiftParametersUpdated(
    string indexed parameterType, uint256 baseYieldShift, uint256 maxYieldShift, uint256 adjustmentSpeed
);

HoldingPeriodProtectionUpdated

event HoldingPeriodProtectionUpdated(uint256 minHoldingPeriod, uint256 baseDiscount, uint256 maxTimeFactor);

YieldSourceAuthorized

event YieldSourceAuthorized(address indexed source, bytes32 indexed yieldType);

YieldSourceRevoked

event YieldSourceRevoked(address indexed source);

Structs

PoolSnapshot

OPTIMIZED: Packed struct for gas efficiency in historical arrays

struct PoolSnapshot {
    uint128 userPoolSize;
    uint128 hedgerPoolSize;
    uint64 timestamp; // Timestamp (8 bytes, until year 2554)
}

YieldShiftSnapshot

OPTIMIZED: Packed struct for gas efficiency in yield shift tracking

struct YieldShiftSnapshot {
    uint128 yieldShift;
    uint64 timestamp; // Timestamp (8 bytes, until year 2554)
}

FeeCollector

Git Source

Inherits: AccessControlUpgradeable, ReentrancyGuardUpgradeable, PausableUpgradeable, UUPSUpgradeable

Author: Quantillon Protocol Team

Centralized fee collection and distribution contract for Quantillon Protocol

This contract handles all protocol fees from:

• QEURO minting fees
• QEURO redemption fees
• Hedger position fees
• Yield management fees
• Other protocol operations

Features:

• Centralized fee collection from all protocol contracts
• Governance-controlled fee distribution
• Multi-token fee support (USDC, QEURO, etc.)
• Fee analytics and tracking
• Emergency pause functionality
• Upgradeable via UUPS proxy

Note: security-contact: team@quantillon.money

State Variables

GOVERNANCE_ROLE

Governance role for fee distribution and configuration

bytes32 public constant GOVERNANCE_ROLE = keccak256("GOVERNANCE_ROLE")

TREASURY_ROLE

Treasury role for fee withdrawal

bytes32 public constant TREASURY_ROLE = keccak256("TREASURY_ROLE")

EMERGENCY_ROLE

Emergency role for pausing and emergency operations

bytes32 public constant EMERGENCY_ROLE = keccak256("EMERGENCY_ROLE")

treasury

Treasury address for fee distribution

address public treasury

devFund

Protocol development fund address

address public devFund

communityFund

Community fund address

address public communityFund

treasuryRatio

Fee distribution ratios (in basis points, 10000 = 100%)

uint256 public treasuryRatio

devFundRatio

uint256 public devFundRatio

communityRatio

uint256 public communityRatio

totalFeesCollected

Total fees collected per token

mapping(address => uint256) public totalFeesCollected

totalFeesDistributed

Total fees distributed per token

mapping(address => uint256) public totalFeesDistributed

feeCollectionCount

Fee collection events per token

mapping(address => uint256) public feeCollectionCount

Functions

onlyFeeSource

Ensures only authorized contracts can collect fees

modifier onlyFeeSource() ;

initialize

Initializes the FeeCollector contract

Sets up the initial configuration for fee collection and distribution

Sets up roles, fund addresses, and default fee distribution ratios

Notes:

• security: Protected by initializer modifier

• validation: Validates that all addresses are non-zero

• state-changes: Sets up roles, fund addresses, and default ratios

• events: Emits role grant events and FundAddressesUpdated event

• errors: Throws ZeroAddress if any address is zero

• reentrancy: No external calls, safe

• access: Can only be called once during initialization

• oracle: No oracle dependencies

function initialize(address _admin, address _treasury, address _devFund, address _communityFund)
    external
    initializer;

Parameters

collectFees

Collects fees from protocol contracts

Transfers tokens from the caller to this contract and updates tracking variables

Only authorized fee sources can call this function

Emits FeesCollected event for transparency and analytics

Notes:

• security: Protected by onlyFeeSource modifier and reentrancy guard

• validation: Validates token address and amount parameters

• state-changes: Updates totalFeesCollected and feeCollectionCount mappings

• events: Emits FeesCollected event with collection details

• errors: Throws InvalidAmount if amount is zero

• errors: Throws ZeroAddress if token address is zero

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to authorized fee sources only

• oracle: No oracle dependencies

function collectFees(address token, uint256 amount, string calldata sourceType)
    external
    onlyFeeSource
    whenNotPaused
    nonReentrant;

Parameters

collectETHFees

Collects ETH fees from protocol contracts

Accepts ETH payments and updates tracking variables for ETH (tracked as address(0))

Only authorized fee sources can call this function

Emits FeesCollected event for transparency and analytics

Notes:

• security: Protected by onlyFeeSource modifier and reentrancy guard

• validation: Validates that msg.value is greater than zero

• state-changes: Updates totalFeesCollected and feeCollectionCount for address(0)

• events: Emits FeesCollected event with ETH collection details

• errors: Throws InvalidAmount if msg.value is zero

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to authorized fee sources only

• oracle: No oracle dependencies

function collectETHFees(string calldata sourceType) external payable onlyFeeSource whenNotPaused nonReentrant;

Parameters

distributeFees

Distributes collected fees according to configured ratios

Calculates distribution amounts based on treasuryRatio, devFundRatio, and communityRatio

Handles rounding by adjusting community amount to ensure total doesn't exceed balance

Only treasury role can call this function

Emits FeesDistributed event for transparency

Notes:

• security: Protected by TREASURY_ROLE and reentrancy guard

• validation: Validates that contract has sufficient balance

• state-changes: Updates totalFeesDistributed and transfers tokens to fund addresses

• events: Emits FeesDistributed event with distribution details

• errors: Throws InsufficientBalance if contract balance is zero

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to TREASURY_ROLE only

• oracle: No oracle dependencies

function distributeFees(address token) external onlyRole(TREASURY_ROLE) whenNotPaused nonReentrant;

Parameters

_calculateDistributionAmounts

Calculate distribution amounts with rounding protection

Internal function to reduce cyclomatic complexity

Notes:

• security: No external calls, pure calculation function

• validation: Balance must be non-zero for meaningful distribution

• state-changes: No state changes, view function

• events: No events emitted

• errors: No custom errors, uses SafeMath for overflow protection

• reentrancy: No reentrancy risk, view function

• access: Internal function, no access control needed

• oracle: No oracle dependencies

function _calculateDistributionAmounts(uint256 balance)
    internal
    view
    returns (uint256 treasuryAmount, uint256 devFundAmount, uint256 communityAmount);

Parameters

Returns

_executeTransfers

Execute transfers for ETH or ERC20 tokens

Internal function to reduce cyclomatic complexity

Notes:

• security: Delegates to specific transfer functions with proper validation

• validation: Amounts must be non-zero for transfers to execute

• state-changes: Updates token balances through transfers

• events: No direct events, delegated functions emit events

• errors: May revert on transfer failures

• reentrancy: Protected by internal function design

• access: Internal function, no access control needed

• oracle: No oracle dependencies

function _executeTransfers(address token, uint256 treasuryAmount, uint256 devFundAmount, uint256 communityAmount)
    internal;

Parameters

_executeETHTransfers

Execute ETH transfers

Internal function to reduce cyclomatic complexity

Notes:

• security: Uses secure ETH transfer with address validation

• validation: Amounts must be non-zero for transfers to execute

• state-changes: Reduces contract ETH balance, increases recipient balances

• events: No direct events emitted

• errors: Reverts with ETHTransferFailed on call failure

• reentrancy: Protected by internal function design and address validation

• access: Internal function, no access control needed

• oracle: No oracle dependencies

function _executeETHTransfers(uint256 treasuryAmount, uint256 devFundAmount, uint256 communityAmount) internal;

Parameters

_secureETHTransfer

Secure ETH transfer with comprehensive validation

Validates recipient address against whitelist and performs secure ETH transfer

Notes:

• security: Multiple validation layers prevent arbitrary sends:

• Recipient must be one of three pre-authorized fund addresses

• Addresses are validated to be non-zero and non-contract

• Only GOVERNANCE_ROLE can update these addresses

• This is NOT an arbitrary send as recipient is strictly controlled

• validation: Ensures recipient is valid and amount is positive

• state-changes: Transfers ETH from contract to recipient

• events: No events emitted

• errors: Reverts with ETHTransferFailed on transfer failure

• reentrancy: Protected by address validation and call pattern

• access: Internal function, no access control needed

• oracle: No oracle dependencies

function _secureETHTransfer(address recipient, uint256 amount) internal;

Parameters

_executeERC20Transfers

Execute ERC20 token transfers

Internal function to reduce cyclomatic complexity

Notes:

• security: Uses safeTransfer for ERC20 tokens with proper error handling

• validation: Amounts must be non-zero for transfers to execute

• state-changes: Reduces contract token balance, increases recipient balances

• events: No direct events emitted

• errors: May revert on transfer failures from ERC20 contract

• reentrancy: Protected by internal function design and safeTransfer

• access: Internal function, no access control needed

• oracle: No oracle dependencies

function _executeERC20Transfers(
    address token,
    uint256 treasuryAmount,
    uint256 devFundAmount,
    uint256 communityAmount
) internal;

Parameters

updateFeeRatios

Updates fee distribution ratios

Sets new distribution ratios for treasury, dev fund, and community fund

Ratios must sum to exactly 10000 (100%) in basis points

Only governance role can call this function

Emits FeeRatiosUpdated event for transparency

Notes:

• security: Protected by GOVERNANCE_ROLE

• validation: Validates that ratios sum to exactly 10000

• state-changes: Updates treasuryRatio, devFundRatio, and communityRatio

• events: Emits FeeRatiosUpdated event with new ratios

• errors: Throws InvalidRatio if ratios don't sum to 10000

• reentrancy: No external calls, safe

• access: Restricted to GOVERNANCE_ROLE only

• oracle: No oracle dependencies

function updateFeeRatios(uint256 _treasuryRatio, uint256 _devFundRatio, uint256 _communityRatio)
    external
    onlyRole(GOVERNANCE_ROLE);

Parameters

updateFundAddresses

Updates fund addresses for fee distribution

Sets new addresses for treasury, dev fund, and community fund

All addresses must be non-zero

Only governance role can call this function

Emits FundAddressesUpdated event for transparency

Notes:

• security: Protected by GOVERNANCE_ROLE

• validation: Validates that all addresses are non-zero

• state-changes: Updates treasury, devFund, and communityFund addresses

• events: Emits FundAddressesUpdated event with new addresses

• errors: Throws ZeroAddress if any address is zero

• reentrancy: No external calls, safe

• access: Restricted to GOVERNANCE_ROLE only

• oracle: No oracle dependencies

function updateFundAddresses(address _treasury, address _devFund, address _communityFund)
    external
    onlyRole(GOVERNANCE_ROLE);

Parameters

authorizeFeeSource

Authorizes a contract to collect fees

Grants TREASURY_ROLE to the specified address, allowing it to collect fees

Only governance role can call this function

Notes:

• security: Protected by GOVERNANCE_ROLE

• validation: Validates that feeSource is not zero address

• state-changes: Grants TREASURY_ROLE to feeSource

• events: Emits RoleGranted event for TREASURY_ROLE

• errors: Throws ZeroAddress if feeSource is zero

• reentrancy: No external calls, safe

• access: Restricted to GOVERNANCE_ROLE only

• oracle: No oracle dependencies

function authorizeFeeSource(address feeSource) external onlyRole(GOVERNANCE_ROLE);

Parameters

revokeFeeSource

Revokes fee collection authorization

Revokes TREASURY_ROLE from the specified address, preventing it from collecting fees

Only governance role can call this function

Notes:

• security: Protected by GOVERNANCE_ROLE

• validation: No validation required (can revoke from any address)

• state-changes: Revokes TREASURY_ROLE from feeSource

• events: Emits RoleRevoked event for TREASURY_ROLE

• errors: No custom errors

• reentrancy: No external calls, safe

• access: Restricted to GOVERNANCE_ROLE only

• oracle: No oracle dependencies

function revokeFeeSource(address feeSource) external onlyRole(GOVERNANCE_ROLE);

Parameters

pause

Pauses fee collection and distribution

Emergency function to pause all fee operations in case of security issues

Only emergency role can call this function

Notes:

• security: Protected by EMERGENCY_ROLE

• validation: No validation required

• state-changes: Sets paused state to true

• events: Emits Paused event

• errors: No custom errors

• reentrancy: No external calls, safe

• access: Restricted to EMERGENCY_ROLE only

• oracle: No oracle dependencies

function pause() external onlyRole(EMERGENCY_ROLE);

unpause

Unpauses fee collection and distribution

Resumes all fee operations after a pause

Only emergency role can call this function

Notes:

• security: Protected by EMERGENCY_ROLE

• validation: No validation required

• state-changes: Sets paused state to false

• events: Emits Unpaused event

• errors: No custom errors

• reentrancy: No external calls, safe

• access: Restricted to EMERGENCY_ROLE only

• oracle: No oracle dependencies

function unpause() external onlyRole(EMERGENCY_ROLE);

emergencyWithdraw

Emergency withdrawal of all tokens (only in extreme circumstances)

Emergency function to withdraw all tokens to treasury in case of critical issues

Only emergency role can call this function

Notes:

• security: Protected by EMERGENCY_ROLE

• validation: Validates that contract has sufficient balance

• state-changes: Transfers all tokens to treasury address

• events: No custom events (uses standard transfer events)

• errors: Throws InsufficientBalance if contract balance is zero

• errors: Throws ETHTransferFailed if ETH transfer fails

• reentrancy: No external calls, safe

• access: Restricted to EMERGENCY_ROLE only

• oracle: No oracle dependencies

function emergencyWithdraw(address token) external onlyRole(EMERGENCY_ROLE);

Parameters

getBalance

Returns the current balance of a token

Returns the current balance of the specified token held by this contract

Notes:

• security: No security implications (view function)

• validation: No validation required

• state-changes: No state changes (view function)

• events: No events (view function)

• errors: No custom errors

• reentrancy: No external calls, safe

• access: Public (anyone can call)

• oracle: No oracle dependencies

function getBalance(address token) external view returns (uint256);

Parameters

Returns

getFeeStats

Returns fee collection statistics for a token

Returns comprehensive statistics about fee collection and distribution for a specific token

Notes:

• security: No security implications (view function)

• validation: No validation required

• state-changes: No state changes (view function)

• events: No events (view function)

• errors: No custom errors

• reentrancy: No external calls, safe

• access: Public (anyone can call)

• oracle: No oracle dependencies

function getFeeStats(address token)
    external
    view
    returns (uint256 totalCollected, uint256 totalDistributed, uint256 collectionCount, uint256 currentBalance);

Parameters

Returns

isAuthorizedFeeSource

Checks if an address is authorized to collect fees

Returns whether the specified address has permission to collect fees

Notes:

• security: No security implications (view function)

• validation: No validation required

• state-changes: No state changes (view function)

• events: No events (view function)

• errors: No custom errors

• reentrancy: No external calls, safe

• access: Public (anyone can call)

• oracle: No oracle dependencies

function isAuthorizedFeeSource(address feeSource) external view returns (bool);

Parameters

Returns

_isAuthorizedFeeSource

Internal function to check if an address is authorized to collect fees

Internal helper function to check TREASURY_ROLE for fee collection authorization

Notes:

• security: Internal function, no direct security implications

• validation: No validation required

• state-changes: No state changes (view function)

• events: No events (internal function)

• errors: No custom errors

• reentrancy: No external calls, safe

• access: Internal function only

• oracle: No oracle dependencies

function _isAuthorizedFeeSource(address feeSource) internal view returns (bool);

Parameters

Returns

_authorizeUpgrade

Authorizes upgrades (only governance)

Internal function to authorize contract upgrades via UUPS proxy pattern

Only governance role can authorize upgrades

Notes:

• security: Protected by GOVERNANCE_ROLE

• validation: No validation required (OpenZeppelin handles this)

• state-changes: No state changes (authorization only)

• events: No custom events (OpenZeppelin handles upgrade events)

• errors: No custom errors

• reentrancy: No external calls, safe

• access: Restricted to GOVERNANCE_ROLE only

• oracle: No oracle dependencies

function _authorizeUpgrade(address newImplementation) internal override onlyRole(GOVERNANCE_ROLE);

Parameters

Events

FeesCollected

Emitted when fees are collected

event FeesCollected(address indexed token, uint256 amount, address indexed source, string indexed sourceType);

FeesDistributed

Emitted when fees are distributed

event FeesDistributed(
    address indexed token,
    uint256 totalAmount,
    uint256 treasuryAmount,
    uint256 devFundAmount,
    uint256 communityAmount
);

FeeRatiosUpdated

Emitted when fee distribution ratios are updated

event FeeRatiosUpdated(uint256 treasuryRatio, uint256 devFundRatio, uint256 communityRatio);

FundAddressesUpdated

Emitted when fund addresses are updated

event FundAddressesUpdated(address treasury, address devFund, address communityFund);

HedgerPool

Git Source

Inherits: Initializable, ReentrancyGuardUpgradeable, AccessControlUpgradeable, PausableUpgradeable, SecureUpgradeable

Author: Quantillon Labs - Nicolas Bellengé - @chewbaccoin

Optimized EUR/USD hedging pool for managing currency risk and providing yield

Optimized version with reduced contract size through library extraction and code consolidation

Note: security-contact: team@quantillon.money

State Variables

GOVERNANCE_ROLE

bytes32 public constant GOVERNANCE_ROLE = keccak256("GOVERNANCE_ROLE")

LIQUIDATOR_ROLE

bytes32 public constant LIQUIDATOR_ROLE = keccak256("LIQUIDATOR_ROLE")

EMERGENCY_ROLE

bytes32 public constant EMERGENCY_ROLE = keccak256("EMERGENCY_ROLE")

HEDGER_ROLE

bytes32 public constant HEDGER_ROLE = keccak256("HEDGER_ROLE")

usdc

IERC20 public usdc

oracle

IChainlinkOracle public oracle

yieldShift

IYieldShift public yieldShift

vault

IQuantillonVault public vault

treasury

address public treasury

TIME_PROVIDER

TimeProvider public immutable TIME_PROVIDER

coreParams

CoreParams public coreParams

totalMargin

uint256 public totalMargin

totalExposure

uint256 public totalExposure

activeHedgers

uint256 public activeHedgers

nextPositionId

uint256 public nextPositionId

isWhitelistedHedger

mapping(address => bool) public isWhitelistedHedger

hedgerWhitelistEnabled

bool public hedgerWhitelistEnabled

positions

mapping(uint256 => HedgePosition) public positions

hedgers

mapping(address => HedgerInfo) public hedgers

activePositionCount

mapping(address => uint256) public activePositionCount

hedgerHasPosition

mapping(address => mapping(uint256 => bool)) public hedgerHasPosition

positionIndex

mapping(address => mapping(uint256 => uint256)) public positionIndex

liquidationCommitments

mapping(bytes32 => bool) public liquidationCommitments

liquidationCommitmentTimes

mapping(bytes32 => uint256) public liquidationCommitmentTimes

lastLiquidationAttempt

mapping(address => uint256) public lastLiquidationAttempt

hasPendingLiquidation

mapping(address => mapping(uint256 => bool)) public hasPendingLiquidation

hedgerLastRewardBlock

mapping(address => uint256) public hedgerLastRewardBlock

MAX_POSITIONS_PER_HEDGER

uint256 public constant MAX_POSITIONS_PER_HEDGER = 50

MAX_UINT96_VALUE

uint96 public constant MAX_UINT96_VALUE = type(uint96).max

MAX_POSITION_SIZE

uint256 public constant MAX_POSITION_SIZE = MAX_UINT96_VALUE

MAX_MARGIN

uint256 public constant MAX_MARGIN = MAX_UINT96_VALUE

MAX_ENTRY_PRICE

uint256 public constant MAX_ENTRY_PRICE = MAX_UINT96_VALUE

MAX_LEVERAGE

uint256 public constant MAX_LEVERAGE = type(uint16).max

MAX_MARGIN_RATIO

uint256 public constant MAX_MARGIN_RATIO = 5000

MAX_UINT128_VALUE

uint128 public constant MAX_UINT128_VALUE = type(uint128).max

MAX_TOTAL_MARGIN

uint256 public constant MAX_TOTAL_MARGIN = MAX_UINT128_VALUE

MAX_TOTAL_EXPOSURE

uint256 public constant MAX_TOTAL_EXPOSURE = MAX_UINT128_VALUE

MAX_PENDING_REWARDS

uint256 public constant MAX_PENDING_REWARDS = MAX_UINT128_VALUE

LIQUIDATION_COOLDOWN

uint256 public constant LIQUIDATION_COOLDOWN = 300

MAX_REWARD_PERIOD

uint256 public constant MAX_REWARD_PERIOD = 365 days

Functions

flashLoanProtection

modifier flashLoanProtection() ;

secureNonReentrant

modifier secureNonReentrant() ;

constructor

Initializes the HedgerPool contract with a time provider

Constructor that sets up the time provider and disables initializers for upgrade safety

Notes:

• security: Validates that the time provider is not zero address

• validation: Ensures TIME_PROVIDER is a valid contract address

• state-changes: Sets TIME_PROVIDER and disables initializers

• events: None

• errors: Throws ZeroAddress if _TIME_PROVIDER is address(0)

• reentrancy: Not applicable - constructor

• access: Public constructor

• oracle: Not applicable

constructor(TimeProvider _TIME_PROVIDER) ;

Parameters

initialize

Initializes the HedgerPool with contracts and parameters

This function configures:

1. Access roles and permissions
2. References to external contracts
3. Default protocol parameters
4. Security (pause, reentrancy, upgrades)

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: Initializes all contract state variables

• events: Emits relevant events for state changes

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by initializer modifier

• access: Restricted to initializer modifier

• oracle: No oracle dependencies

function initialize(
    address admin,
    address _usdc,
    address _oracle,
    address _yieldShift,
    address _timelock,
    address _treasury,
    address _vault
) public initializer;

Parameters

enterHedgePosition

Opens a new hedge position for a hedger

Position opening process:

1. Validates hedger whitelist status
2. Fetches current EUR/USD price from oracle
3. Calculates position size and validates parameters
4. Transfers USDC to vault for unified liquidity
5. Creates position record and updates hedger stats

Security features:

1. Flash loan protection via secureNonReentrant
2. Whitelist validation if enabled
3. Parameter validation (leverage, amounts)
4. Oracle price validation

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates amount > 0, leverage within limits, hedger whitelist

• state-changes: Creates new position, updates hedger stats, transfers USDC to vault

• events: Emits HedgePositionOpened with position details

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by secureNonReentrant modifier and proper CEI pattern

• access: Restricted to whitelisted hedgers (if whitelist enabled)

• oracle: Requires fresh oracle price data

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

Parameters

Returns

exitHedgePosition

Closes an existing hedge position

Position closing process:

1. Validates position ownership and active status
2. Checks protocol collateralization safety
3. Calculates current PnL based on price change
4. Determines net payout to hedger
5. Updates hedger stats and removes position
6. Withdraws USDC from vault for hedger payout

Security features:

1. Position ownership validation
2. Protocol collateralization safety check
3. Pause protection

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates position ownership, active status, and protocol safety

• state-changes: Closes position, updates hedger stats, withdraws USDC from vault

• events: Emits HedgePositionClosed with position details

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by whenNotPaused modifier

• access: Restricted to position owner

• oracle: Requires fresh oracle price data

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

Parameters

Returns

addMargin

Adds additional margin to an existing hedge position

Margin addition process:

1. Validates position ownership and active status
2. Validates amount is positive
3. Checks liquidation cooldown and pending liquidation status
4. Transfers USDC from hedger to vault
5. Updates position margin and hedger stats

Security features:

1. Flash loan protection
2. Position ownership validation
3. Liquidation cooldown validation

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates position ownership, active status, positive amount, liquidation cooldown

• state-changes: Updates position margin, hedger stats, transfers USDC to vault

• events: Emits MarginAdded with position details

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by flashLoanProtection modifier

• access: Restricted to position owner

• oracle: No oracle dependencies

function addMargin(uint256 positionId, uint256 amount) external flashLoanProtection;

Parameters

removeMargin

Removes margin from an existing hedge position

Margin removal process:

1. Validates position ownership and active status
2. Validates amount is positive
3. Validates margin operation maintains minimum margin ratio
4. Updates position margin and hedger stats
5. Withdraws USDC from vault to hedger

Security features:

1. Flash loan protection
2. Position ownership validation
3. Minimum margin ratio validation

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates position ownership, active status, positive amount, minimum margin ratio

• state-changes: Updates position margin, hedger stats, withdraws USDC from vault

• events: Emits MarginUpdated with position details

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by flashLoanProtection modifier

• access: Restricted to position owner

• oracle: No oracle dependencies

function removeMargin(uint256 positionId, uint256 amount) external flashLoanProtection;

Parameters

commitLiquidation

Commits to liquidating a hedger position with a salt for MEV protection

Creates a liquidation commitment that must be executed within a time window

Notes:

• security: Requires LIQUIDATOR_ROLE, validates addresses and position ID

• validation: Ensures hedger is valid address, positionId > 0, commitment doesn't exist

• state-changes: Sets liquidation commitment, timing, and pending liquidation flags

• events: None (commitment phase)

• errors: Throws InvalidRole, InvalidAddress, InvalidPosition, or CommitmentExists

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to LIQUIDATOR_ROLE

• oracle: Not applicable

function commitLiquidation(address hedger, uint256 positionId, bytes32 salt) external;

Parameters

liquidateHedger

Liquidates an undercollateralized hedge position

Liquidation process:

1. Validates liquidator role and commitment
2. Validates position ownership and active status
3. Calculates liquidation reward and remaining margin
4. Updates hedger stats and removes position
5. Withdraws USDC from vault for liquidator reward and remaining margin

Security features:

1. Role-based access control (LIQUIDATOR_ROLE)
2. Commitment validation to prevent front-running
3. Reentrancy protection

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates liquidator role, commitment, position ownership, active status

• state-changes: Liquidates position, updates hedger stats, withdraws USDC from vault

• events: Emits HedgerLiquidated with liquidation details

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to LIQUIDATOR_ROLE

• oracle: Requires fresh oracle price data

function liquidateHedger(address hedger, uint256 positionId, bytes32 salt)
    external
    nonReentrant
    returns (uint256 liquidationReward);

Parameters

Returns

claimHedgingRewards

Claims hedging rewards for a hedger

Reward claiming process:

1. Calculates interest differential based on exposure and rates
2. Calculates yield shift rewards from YieldShift contract
3. Updates hedger's last reward block
4. Transfers total rewards to hedger

Security features:

1. Reentrancy protection
2. Reward calculation validation

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates hedger has active positions and rewards available

• state-changes: Updates hedger reward tracking, transfers rewards

• events: Emits HedgingRewardsClaimed with reward details

• errors: Throws custom errors for invalid conditions

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to hedgers with active positions

• oracle: No oracle dependencies

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

Returns

getHedgerPosition

Retrieves detailed information about a specific hedger position

Returns position data including current oracle price for real-time calculations

Notes:

• security: Validates that the caller owns the position

• validation: Ensures position exists and hedger matches

• state-changes: None (view function with oracle call)

• events: None

• errors: Throws InvalidHedger if position doesn't belong to hedger

• reentrancy: Protected by nonReentrant modifier

• access: Public (anyone can query position data)

• oracle: Calls _getValidOraclePrice() for current price

function getHedgerPosition(address hedger, uint256 positionId)
    external
    view
    returns (
        uint256 positionSize,
        uint256 margin,
        uint256 entryPrice,
        uint256 currentPrice,
        uint256 leverage,
        uint256 lastUpdateTime
    );

Parameters

Returns

getHedgerMarginRatio

Calculates the current margin ratio for a hedger position

Returns margin ratio as basis points (10000 = 100%)

Notes:

• security: Validates that the caller owns the position

• validation: Ensures position exists and hedger matches

• state-changes: None (view function)

• events: None

• errors: Throws InvalidHedger if position doesn't belong to hedger

• reentrancy: Not applicable - view function

• access: Public (anyone can query margin ratio)

• oracle: Not applicable

function getHedgerMarginRatio(address hedger, uint256 positionId) external view returns (uint256);

Parameters

Returns

isHedgerLiquidatable

Checks if a hedger position is eligible for liquidation

Uses current oracle price to determine if position is undercollateralized

Notes:

• security: Validates that the caller owns the position

• validation: Ensures position exists, is active, and hedger matches

• state-changes: None (view function with oracle call)

• events: None

• errors: Throws InvalidHedger if position doesn't belong to hedger

• reentrancy: Protected by nonReentrant modifier

• access: Public (anyone can check liquidation status)

• oracle: Calls _getValidOraclePrice() for current price comparison

function isHedgerLiquidatable(address hedger, uint256 positionId) external view returns (bool);

Parameters

Returns

getTotalHedgeExposure

Returns the total hedge exposure across all active positions

Provides aggregate exposure for risk management and monitoring

Notes:

• security: No security validations required for view function

• validation: None required for view function

• state-changes: None (view function)

• events: None

• errors: None

• reentrancy: Not applicable - view function

• access: Public (anyone can query total exposure)

• oracle: Not applicable

function getTotalHedgeExposure() external view returns (uint256);

Returns

updateHedgingParameters

Updates core hedging parameters for the protocol

Allows governance to adjust risk parameters for hedge positions

Notes:

• security: Requires GOVERNANCE_ROLE, validates parameter ranges

• validation: Ensures minMarginRatio >= 500, liquidationThreshold < minMarginRatio, maxLeverage <= 20, liquidationPenalty <= 1000

• state-changes: Updates coreParams struct with new values

• events: None

• errors: Throws InvalidRole, ConfigValueTooLow, ConfigInvalid, or ConfigValueTooHigh

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to GOVERNANCE_ROLE

• oracle: Not applicable

function updateHedgingParameters(
    uint256 newMinMarginRatio,
    uint256 newLiquidationThreshold,
    uint256 newMaxLeverage,
    uint256 newLiquidationPenalty
) external;

Parameters

updateInterestRates

Updates interest rates for EUR and USD positions

Allows governance to adjust interest rates for yield calculations

Notes:

• security: Requires GOVERNANCE_ROLE, validates rate limits

• validation: Ensures both rates are <= 2000 basis points (20%)

• state-changes: Updates coreParams with new interest rates

• events: None

• errors: Throws InvalidRole or ConfigValueTooHigh

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to GOVERNANCE_ROLE

• oracle: Not applicable

function updateInterestRates(uint256 newEurRate, uint256 newUsdRate) external;

Parameters

setHedgingFees

Sets the fee structure for hedge positions

Allows governance to adjust fees for position entry, exit, and margin operations

Notes:

• security: Requires GOVERNANCE_ROLE, validates fee limits

• validation: Ensures entryFee <= 100, exitFee <= 100, marginFee <= 50

• state-changes: Updates coreParams with new fee values

• events: None

• errors: Throws InvalidRole or InvalidFee

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to GOVERNANCE_ROLE

• oracle: Not applicable

function setHedgingFees(uint256 _entryFee, uint256 _exitFee, uint256 _marginFee) external;

Parameters

emergencyClosePosition

Emergency closure of a hedge position by governance

Emergency closure process:

1. Validates emergency role and position ownership
2. Validates position is active
3. Updates hedger stats and removes position
4. Withdraws USDC from vault for hedger's margin

Security features:

1. Role-based access control (EMERGENCY_ROLE)
2. Position ownership validation

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates emergency role, position ownership, active status

• state-changes: Closes position, updates hedger stats, withdraws USDC from vault

• events: Emits EmergencyPositionClosed with position details

• errors: Throws custom errors for invalid conditions

• reentrancy: Not protected - emergency function

• access: Restricted to EMERGENCY_ROLE

• oracle: No oracle dependencies

function emergencyClosePosition(address hedger, uint256 positionId) external;

Parameters

pause

Pauses all contract operations in case of emergency

Emergency function to halt all user interactions

Notes:

• security: Requires EMERGENCY_ROLE

• validation: None required

• state-changes: Sets contract to paused state

• events: Emits Paused event

• errors: Throws InvalidRole if caller lacks EMERGENCY_ROLE

• reentrancy: Not applicable

• access: Restricted to EMERGENCY_ROLE

• oracle: Not applicable

function pause() external;

unpause

Unpauses contract operations after emergency

Resumes normal contract functionality

Notes:

• security: Requires EMERGENCY_ROLE

• validation: None required

• state-changes: Sets contract to unpaused state

• events: Emits Unpaused event

• errors: Throws InvalidRole if caller lacks EMERGENCY_ROLE

• reentrancy: Not applicable

• access: Restricted to EMERGENCY_ROLE

• oracle: Not applicable

function unpause() external;

hasPendingLiquidationCommitment

Checks if a position has a pending liquidation commitment

Returns true if a liquidation commitment exists for the position

Notes:

• security: No security validations required for view function

• validation: None required for view function

• state-changes: None (view function)

• events: None

• errors: None

• reentrancy: Not applicable - view function

• access: Public (anyone can query commitment status)

• oracle: Not applicable

function hasPendingLiquidationCommitment(address hedger, uint256 positionId) external view returns (bool);

Parameters

Returns

getHedgingConfig

Returns the current hedging configuration parameters

Provides access to all core hedging parameters for external contracts

Notes:

• security: No security validations required for view function

• validation: None required for view function

• state-changes: None (view function)

• events: None

• errors: None

• reentrancy: Not applicable - view function

• access: Public (anyone can query configuration)

• oracle: Not applicable

function getHedgingConfig()
    external
    view
    returns (
        uint256 minMarginRatio_,
        uint256 liquidationThreshold_,
        uint256 maxLeverage_,
        uint256 liquidationPenalty_,
        uint256 entryFee_,
        uint256 exitFee_
    );

Returns

marginFee

Returns the current margin fee rate

Provides the margin fee for margin operations

Notes:

• security: No security validations required for view function

• validation: None required for view function

• state-changes: None (view function)

• events: None

• errors: None

• reentrancy: Not applicable - view function

• access: Public (anyone can query margin fee)

• oracle: Not applicable

function marginFee() external view returns (uint256);

Returns

getMaxValues

Returns the maximum allowed values for various parameters

Provides hard limits for position sizes, margins, and other constraints

Notes:

• security: No security validations required for pure function

• validation: None required for pure function

• state-changes: None (pure function)

• events: None

• errors: None

• reentrancy: Not applicable - pure function

• access: Public (anyone can query max values)

• oracle: Not applicable

function getMaxValues()
    external
    pure
    returns (
        uint256 maxPositionSize,
        uint256 maxMargin,
        uint256 maxEntryPrice,
        uint256 maxLeverageValue,
        uint256 maxTotalMargin,
        uint256 maxTotalExposure,
        uint256 maxPendingRewards
    );

Returns

isHedgingActive

Checks if hedging operations are currently active

Returns true if contract is not paused, false if paused

Notes:

• security: No security validations required for view function

• validation: None required for view function

• state-changes: None (view function)

• events: None

• errors: None

• reentrancy: Not applicable - view function

• access: Public (anyone can query hedging status)

• oracle: Not applicable

function isHedgingActive() external view returns (bool);

Returns

clearExpiredLiquidationCommitment

Clears expired liquidation commitments after cooldown period

Allows liquidators to clean up expired commitments

Notes:

• security: Requires LIQUIDATOR_ROLE, checks cooldown period

• validation: Ensures cooldown period has passed

• state-changes: Clears pending liquidation flag if expired

• events: None

• errors: Throws InvalidRole if caller lacks LIQUIDATOR_ROLE

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to LIQUIDATOR_ROLE

• oracle: Not applicable

function clearExpiredLiquidationCommitment(address hedger, uint256 positionId) external;

Parameters

cancelLiquidationCommitment

Cancels a liquidation commitment before execution

Allows liquidators to cancel their own commitments

Notes:

• security: Requires LIQUIDATOR_ROLE, validates commitment exists

• validation: Ensures commitment exists and belongs to caller

• state-changes: Deletes commitment data and clears pending liquidation flag

• events: None

• errors: Throws InvalidRole or CommitmentNotFound

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to LIQUIDATOR_ROLE

• oracle: Not applicable

function cancelLiquidationCommitment(address hedger, uint256 positionId, bytes32 salt) external;

Parameters

recoverToken

Recovers accidentally sent tokens to the treasury

Emergency function to recover tokens sent to the contract

Notes:

• security: Requires DEFAULT_ADMIN_ROLE

• validation: None required

• state-changes: Transfers tokens from contract to treasury

• events: None

• errors: Throws InvalidRole if caller lacks DEFAULT_ADMIN_ROLE

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to DEFAULT_ADMIN_ROLE

• oracle: Not applicable

function recoverToken(address token, uint256 amount) external;

Parameters

recoverETH

Recovers accidentally sent ETH to the treasury

Emergency function to recover ETH sent to the contract

Notes:

• security: Requires DEFAULT_ADMIN_ROLE

• validation: None required

• state-changes: Transfers ETH from contract to treasury

• events: Emits ETHRecovered event

• errors: Throws InvalidRole if caller lacks DEFAULT_ADMIN_ROLE

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to DEFAULT_ADMIN_ROLE

• oracle: Not applicable