QuantillonVault

Git Source

Inherits: Initializable, ReentrancyGuardUpgradeable, AccessControlUpgradeable, PausableUpgradeable, SecureUpgradeable

Author: Quantillon Labs - Nicolas Bellengé - @chewbaccoin

Main vault managing QEURO minting against USDC collateral

Main characteristics:

• Simple USDC to QEURO swap mechanism
• USDC as input for QEURO minting
• Real-time EUR/USD price oracle integration
• Dynamic fee structure for protocol sustainability
• Emergency pause mechanism for crisis situations
• Upgradeable via UUPS pattern

Minting mechanics:

• Users swap USDC for QEURO
• QEURO is minted based on EUR/USD exchange rate
• Minting fees charged for protocol revenue
• Simple 1:1 exchange with price conversion
• Price deviation protection prevents flash loan manipulation
• Block-based validation ensures price freshness

Redemption mechanics:

• Users can redeem QEURO back to USDC
• Redemption based on current EUR/USD exchange rate
• Protocol fees charged on redemptions
• USDC returned to user after fee deduction
• Same price deviation protection as minting
• Consistent security across all operations

Risk management:

• Real-time price monitoring
• Emergency pause capabilities
• Slippage protection on swaps
• Flash loan attack prevention via price deviation checks
• Block-based price manipulation detection
• Comprehensive oracle validation and fallback mechanisms

Fee structure:

• Minting fees for creating QEURO
• Redemption fees for converting QEURO back to USDC
• Dynamic fee adjustment based on market conditions

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 collateral management
• Oracle price validation
• Flash loan protection through price deviation checks
• Block-based price update validation
• Comprehensive price manipulation attack prevention

Integration points:

• QEURO token for minting and burning
• USDC for collateral deposits and withdrawals
• Chainlink oracle for EUR/USD price feeds
• Vault math library for precise calculations

Note: security-contact: team@quantillon.money

State Variables

GOVERNANCE_ROLE

Role for governance operations (parameter updates, emergency actions)

keccak256 hash avoids role collisions with other contracts

Should be assigned to governance multisig or DAO

bytes32 public constant GOVERNANCE_ROLE = keccak256("GOVERNANCE_ROLE")

EMERGENCY_ROLE

Role for emergency operations (pause)

keccak256 hash avoids role collisions with other contracts

Should be assigned to emergency multisig

bytes32 public constant EMERGENCY_ROLE = keccak256("EMERGENCY_ROLE")

MAX_PRICE_DEVIATION

Maximum allowed price deviation between consecutive price updates (in basis points)

Prevents flash loan price manipulation attacks

200 basis points = 2% maximum deviation

uint256 private constant MAX_PRICE_DEVIATION = 200

MIN_BLOCKS_BETWEEN_UPDATES

Minimum number of blocks required between price updates for deviation checks

Prevents manipulation within the same block

uint256 private constant MIN_BLOCKS_BETWEEN_UPDATES = 1

qeuro

QEURO token contract for minting and burning

Used for all QEURO minting and burning operations

Should be the official QEURO token contract

IQEUROToken public qeuro

usdc

USDC token used as collateral

Used for all collateral deposits, withdrawals, and fee payments

Should be the official USDC contract on the target network

IERC20 public usdc

oracle

Chainlink oracle contract for EUR/USD price feeds

Provides real-time EUR/USD exchange rates for minting and redemption

Used for price calculations in swap operations

IChainlinkOracle public oracle

hedgerPool

HedgerPool contract for collateralization checks

Used to verify protocol has sufficient hedging positions before minting QEURO

Ensures protocol is properly collateralized by hedgers

IHedgerPool public hedgerPool

userPool

UserPool contract for user deposit tracking

Used to get total user deposits for collateralization ratio calculations

Required for accurate protocol collateralization assessment

IUserPool public userPool

treasury

Treasury address for ETH recovery

SECURITY: Only this address can receive ETH from recoverETH function

address public treasury

feeCollector

Fee collector contract for protocol fees

Centralized fee collection and distribution

address public feeCollector

mintFee

Protocol fee charged on minting QEURO (in basis points)

Example: 10 = 0.1% minting fee

Revenue source for the protocol

uint256 public mintFee

redemptionFee

Protocol fee charged on redeeming QEURO (in basis points)

Example: 10 = 0.1% redemption fee

Revenue source for the protocol

uint256 public redemptionFee

minCollateralizationRatioForMinting

Minimum collateralization ratio required for minting QEURO (in basis points)

Example: 10500 = 105% collateralization ratio required for minting

When protocol collateralization >= this threshold, minting is allowed

When protocol collateralization < this threshold, minting is halted

Can be updated by governance to adjust protocol risk parameters

uint256 public minCollateralizationRatioForMinting

criticalCollateralizationRatio

Critical collateralization ratio that triggers liquidation (in basis points)

Example: 10100 = 101% collateralization ratio triggers liquidation

When protocol collateralization < this threshold, hedgers start being liquidated

Emergency threshold to protect protocol solvency

Can be updated by governance to adjust liquidation triggers

uint256 public criticalCollateralizationRatio

totalUsdcHeld

Total USDC held in the vault

Used for vault analytics and risk management

uint256 public totalUsdcHeld

totalMinted

Total QEURO in circulation (minted by this vault)

uint256 public totalMinted

lastValidEurUsdPrice

Last valid EUR/USD price used in operations

Used for price deviation checks to prevent manipulation

uint256 private lastValidEurUsdPrice

lastPriceUpdateBlock

Block number of the last price update

Used to ensure minimum blocks between updates for deviation checks

uint256 private lastPriceUpdateBlock

lastPriceUpdateTime

Variable to store the timestamp of the last valid price update

uint256 private lastPriceUpdateTime

Functions

flashLoanProtection

Modifier to protect against flash loan attacks

Uses the FlashLoanProtectionLibrary to check USDC balance consistency

modifier flashLoanProtection() ;

constructor

Constructor for QuantillonVault contract

Disables initializers for security

Notes:

• security: Disables initializers for security

• validation: No validation needed

• state-changes: Disables initializers

• events: No events emitted

• errors: No errors thrown

• reentrancy: No reentrancy protection needed

• access: No access restrictions

• oracle: No oracle dependencies

• oz-upgrades-unsafe-allow: constructor

constructor() ;

initialize

Initializes the vault with contracts and parameters

This function configures:

1. Access roles
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 reentrancy guard

• access: Restricted to initializer modifier

• oracle: No oracle dependencies

function initialize(
    address admin,
    address _qeuro,
    address _usdc,
    address _oracle,
    address _hedgerPool,
    address _userPool,
    address _timelock,
    address _feeCollector
) public initializer;

Parameters

mintQEURO

Mints QEURO tokens by swapping USDC

Minting process:

1. Fetch EUR/USD price from oracle
2. Calculate amount of QEURO to mint
3. Transfer USDC from user
4. Update vault balances
5. Mint QEURO to user

Example: 1100 USDC → ~1000 QEURO (if EUR/USD = 1.10) Simple swap with protocol fee applied

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: No access restrictions

• oracle: Requires fresh oracle price data

function mintQEURO(uint256 usdcAmount, uint256 minQeuroOut)
    external
    nonReentrant
    whenNotPaused
    flashLoanProtection;

Parameters

redeemQEURO

Redeems QEURO for USDC

Redeem process:

1. Calculate USDC to return based on EUR/USD price
2. Apply protocol fees
3. Burn QEURO
4. Update vault balances
5. Transfer USDC to 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: No access restrictions

• oracle: Requires fresh oracle price data

• security: No flash loan protection needed - legitimate redemption operation

function redeemQEURO(uint256 qeuroAmount, uint256 minUsdcOut) external nonReentrant whenNotPaused;

Parameters

getVaultMetrics

Retrieves the vault's global metrics

Returns comprehensive vault metrics for monitoring and analytics

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: No state changes

• events: No events emitted

• errors: No errors thrown

• reentrancy: No reentrancy protection needed

• access: No access restrictions

• oracle: No oracle dependencies

function getVaultMetrics() external returns (uint256 totalUsdcHeld_, uint256 totalMinted_, uint256 totalDebtValue);

Returns

calculateMintAmount

Calculates the amount of QEURO that can be minted for a given USDC amount

Calculates mint amount based on current oracle price and protocol fees

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: No state changes

• events: No events emitted

• errors: No errors thrown

• reentrancy: No reentrancy protection needed

• access: No access restrictions

• oracle: Requires fresh oracle price data

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

Parameters

Returns

calculateRedeemAmount

Calculates the amount of USDC received for a QEURO redemption

Calculates redeem amount based on current oracle price and protocol fees

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: No state changes

• events: No events emitted

• errors: No errors thrown

• reentrancy: No reentrancy protection needed

• access: No access restrictions

• oracle: Requires fresh oracle price data

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

Parameters

Returns

isProtocolCollateralized

Checks if the protocol is properly collateralized by hedgers

Public view function to check collateralization status

Notes:

• security: No security validations required - view function

• validation: No input validation required - view function

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

• events: No events emitted

• errors: No errors thrown - safe view function

• reentrancy: Not applicable - view function

• access: Public - anyone can check collateralization status

• oracle: No oracle dependencies

function isProtocolCollateralized() external view returns (bool isCollateralized, uint256 totalMargin);

Returns

updateParameters

Updates the vault parameters (governance only)

Safety constraints:

• Fees <= 5% (user 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 GOVERNANCE_ROLE

• oracle: No oracle dependencies

function updateParameters(uint256 _mintFee, uint256 _redemptionFee) external onlyRole(GOVERNANCE_ROLE);

Parameters

updateCollateralizationThresholds

Updates the collateralization thresholds (governance only)

Safety constraints:

• minCollateralizationRatioForMinting >= 10100 (101% minimum)
• criticalCollateralizationRatio <= minCollateralizationRatioForMinting
• criticalCollateralizationRatio >= 10000 (100% minimum)

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 GOVERNANCE_ROLE

• oracle: No oracle dependencies

function updateCollateralizationThresholds(
    uint256 _minCollateralizationRatioForMinting,
    uint256 _criticalCollateralizationRatio
) external onlyRole(GOVERNANCE_ROLE);

Parameters

updateOracle

Updates the oracle address

Updates the oracle contract address for price feeds

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 updateOracle(address _oracle) external onlyRole(GOVERNANCE_ROLE);

Parameters

updateHedgerPool

Updates the HedgerPool address

Updates the HedgerPool contract address for collateralization checks

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 GOVERNANCE_ROLE

• oracle: No oracle dependencies

function updateHedgerPool(address _hedgerPool) external onlyRole(GOVERNANCE_ROLE);

Parameters

updateUserPool

Updates the UserPool address

Updates the UserPool contract address for user deposit 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 GOVERNANCE_ROLE

• oracle: No oracle dependencies

function updateUserPool(address _userPool) external onlyRole(GOVERNANCE_ROLE);

Parameters

updateFeeCollector

Updates the fee collector address

Only governance role can update the fee collector address

Notes:

• security: Validates address is not zero before updating

• validation: Ensures _feeCollector is not address(0)

• state-changes: Updates feeCollector state variable

• events: Emits ParametersUpdated event

• errors: Reverts if _feeCollector is address(0)

• reentrancy: No reentrancy risk, simple state update

• access: Restricted to GOVERNANCE_ROLE

• oracle: No oracle dependencies

function updateFeeCollector(address _feeCollector) external onlyRole(GOVERNANCE_ROLE);

Parameters

updatePriceProtectionParams

Updates price deviation protection parameters

Only governance can update these security parameters

Note: This function requires converting constants to state variables for full implementation. Currently a placeholder for future governance control.

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 GOVERNANCE_ROLE

• oracle: No oracle dependencies

function updatePriceProtectionParams(uint256 _maxPriceDeviation, uint256 _minBlocksBetweenUpdates)
    external
    onlyRole(GOVERNANCE_ROLE);

Parameters

withdrawProtocolFees

Withdraws accumulated protocol fees

Fees accumulate during minting and redemptions

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 withdrawProtocolFees(address to) external onlyRole(GOVERNANCE_ROLE);

Parameters

addHedgerDeposit

Adds hedger USDC deposit to vault's total USDC reserves

Called by HedgerPool when hedgers open positions to unify USDC liquidity

Notes:

• security: Validates caller is HedgerPool contract and amount is positive

• validation: Validates amount > 0 and caller is authorized HedgerPool

• state-changes: Updates totalUsdcHeld with hedger deposit amount

• events: Emits HedgerDepositAdded with deposit details

• errors: Throws "Vault: Only HedgerPool can call" if caller is not HedgerPool

• errors: Throws "Vault: Amount must be positive" if amount is zero

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to HedgerPool contract only

• oracle: No oracle dependencies

function addHedgerDeposit(uint256 usdcAmount) external nonReentrant;

Parameters

withdrawHedgerDeposit

Withdraws hedger USDC deposit from vault's reserves

Called by HedgerPool when hedgers close positions to return their deposits

Notes:

• security: Validates caller is HedgerPool, amount is positive, and sufficient reserves

• validation: Validates amount > 0, caller is authorized, and totalUsdcHeld >= amount

• state-changes: Updates totalUsdcHeld and transfers USDC to hedger

• events: Emits HedgerDepositWithdrawn with withdrawal details

• errors: Throws "Vault: Only HedgerPool can call" if caller is not HedgerPool

• errors: Throws "Vault: Amount must be positive" if amount is zero

• errors: Throws "Vault: Insufficient USDC reserves" if not enough USDC available

• reentrancy: Protected by nonReentrant modifier

• access: Restricted to HedgerPool contract only

• oracle: No oracle dependencies

function withdrawHedgerDeposit(address hedger, uint256 usdcAmount) external nonReentrant;

Parameters

getTotalUsdcAvailable

Gets the total USDC available for hedger deposits

Returns the current total USDC held in the vault for transparency

Notes:

• security: No security validations required - view function

• validation: No input validation required - view function

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

• events: No events emitted

• errors: No errors thrown

• reentrancy: Not applicable - view function

• access: Public access - anyone can query total USDC held

• oracle: No oracle dependencies

function getTotalUsdcAvailable() external view returns (uint256);

Returns

_updatePriceTimestamp

Updates the last valid price timestamp when a valid price is fetched

Internal function to track price update timing for monitoring

Notes:

• security: Updates timestamp only for valid price fetches

• validation: No input validation required

• state-changes: Updates lastPriceUpdateTime if price is valid

• events: No events emitted

• errors: No errors thrown

• reentrancy: Not protected - internal function only

• access: Internal function - no access restrictions

• oracle: No oracle dependencies

function _updatePriceTimestamp(bool isValid) internal;

Parameters

getProtocolCollateralizationRatio

Calculates the current protocol collateralization ratio

Formula: ((A + B) / A) * 100 where A = user deposits, B = hedger deposits

Returns ratio in basis points (e.g., 10500 = 105%)

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: No state changes - view function

• events: No events emitted - view function

• errors: No errors thrown - safe view function

• reentrancy: Not applicable - view function

• access: Public - anyone can check collateralization ratio

• oracle: No oracle dependencies

function getProtocolCollateralizationRatio() public returns (uint256 ratio);

Returns

canMint

Checks if minting is allowed based on current collateralization ratio

Returns true if collateralization ratio >= minCollateralizationRatioForMinting

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: No state changes - view function

• events: No events emitted - view function

• errors: No errors thrown - safe view function

• reentrancy: Not applicable - view function

• access: Public - anyone can check minting status

• oracle: No oracle dependencies

function canMint() public returns (bool);

Returns

shouldTriggerLiquidation

Checks if liquidation should be triggered based on current collateralization ratio

Returns true if collateralization ratio < criticalCollateralizationRatio

Notes:

• security: Validates input parameters and enforces security checks

• validation: Validates input parameters and business logic constraints

• state-changes: No state changes - view function

• events: No events emitted - view function

• errors: No errors thrown - safe view function

• reentrancy: Not applicable - view function

• access: Public - anyone can check liquidation status

• oracle: No oracle dependencies

function shouldTriggerLiquidation() public returns (bool shouldLiquidate);

Returns

getPriceProtectionStatus

Returns the current price protection status

Useful for monitoring and debugging price 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 getPriceProtectionStatus()
    external
    view
    returns (uint256 lastValidPrice, uint256 lastUpdateBlock, uint256 maxDeviation, uint256 minBlocks);

Returns

pause

Pauses all vault operations

When paused:

• No mint/redeem possible
• Read functions still active

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 onlyRole(EMERGENCY_ROLE);

unpause

Unpauses and resumes operations

Resumes all vault operations after emergency pause

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 onlyRole(EMERGENCY_ROLE);

recoverToken

Recovers tokens accidentally sent to the vault to treasury only

Protections:

• Cannot recover own vault tokens
• Tokens are sent to treasury address only
• Only third-party tokens can be recovered

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 DEFAULT_ADMIN_ROLE

• oracle: No oracle dependencies

function recoverToken(address token, uint256 amount) external onlyRole(DEFAULT_ADMIN_ROLE);

Parameters

recoverETH

Recover ETH to treasury address only

SECURITY: Restricted to treasury to prevent arbitrary ETH transfers

Security considerations:

• Only DEFAULT_ADMIN_ROLE can recover
• Prevents sending to zero address
• Validates balance before attempting transfer
• Uses call() for reliable ETH transfers to any 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 onlyRole(DEFAULT_ADMIN_ROLE);

Events

QEUROminted

Emitted when QEURO is minted

event QEUROminted(address indexed user, uint256 usdcAmount, uint256 qeuroAmount);

QEURORedeemed

Emitted when QEURO is redeemed

event QEURORedeemed(address indexed user, uint256 qeuroAmount, uint256 usdcAmount);

HedgerDepositAdded

Emitted when hedger deposits USDC to vault for unified liquidity

event HedgerDepositAdded(address indexed hedgerPool, uint256 usdcAmount, uint256 totalUsdcHeld);

Parameters

HedgerDepositWithdrawn

Emitted when hedger withdraws USDC from vault

event HedgerDepositWithdrawn(address indexed hedger, uint256 usdcAmount, uint256 totalUsdcHeld);

Parameters

ParametersUpdated

Emitted when parameters are changed

OPTIMIZED: Indexed parameter type for efficient filtering

event ParametersUpdated(string indexed parameterType, uint256 mintFee, uint256 redemptionFee);

CollateralizationThresholdsUpdated

Emitted when price deviation protection is triggered

Emitted when collateralization thresholds are updated by governance

Helps monitor potential flash loan attacks

event CollateralizationThresholdsUpdated(
    uint256 indexed minCollateralizationRatioForMinting,
    uint256 indexed criticalCollateralizationRatio,
    address indexed caller
);

Parameters

CollateralizationStatusChanged

Emitted when protocol collateralization status changes

event CollateralizationStatusChanged(
    uint256 indexed currentRatio, bool indexed canMint, bool indexed shouldLiquidate
);

Parameters

PriceDeviationDetected

event PriceDeviationDetected(
    uint256 currentPrice, uint256 lastValidPrice, uint256 deviationBps, uint256 blockNumber
);