HedgerPool

HedgerPool: EUR/USD Hedging & Collateral Management

📋 Overview

The HedgerPool is the contract responsible for managing EUR/USD hedging positions in the Quantillon protocol. It allows the designated hedger to provide delta-neutral coverage, maintaining QEURO peg stability while generating revenue.

MVP Implementation: The MVP uses a single hedger model to simplify operations. Multi-hedger support is planned for future phases.

---

🏗️ Contract Architecture

Inheritance

contract HedgerPool is 
    Initializable,
    ReentrancyGuardUpgradeable,
    AccessControlUpgradeable,
    PausableUpgradeable,
    SecureUpgradeable

External Dependencies

Contract	Role
IERC20 usdc	Collateral token
IChainlinkOracle oracle	Real-time EUR/USD price
IYieldShift yieldShift	Yield distribution
IQuantillonVault vault	Mint/redeem synchronization
ITimeProvider TIME_PROVIDER	Time management (testability)

---

🔐 Roles & Permissions

Role	Responsibilities
DEFAULT_ADMIN_ROLE	General administration, role assignment
GOVERNANCE_ROLE	Pool parameter modification
EMERGENCY_ROLE	Emergency position closure
HEDGER_ROLE	Hedging operations (assigned to single hedger)

onlyVault Modifier

modifier onlyVault() {
    if (msg.sender != address(vault)) {
        revert CommonErrorLibrary.OnlyVault();
    }
    _;
}

Certain functions can only be called by the Vault during mint/redeem operations.

---

📊 Single Hedger Model

Configuration

address public singleHedger;  // Designated hedger address

function setSingleHedger(address _hedger) external onlyRole(GOVERNANCE_ROLE);

Assignment Flow

1. Governance calls setSingleHedger(hedgerAddress)
2. Old hedger loses HEDGER_ROLE
3. New hedger receives HEDGER_ROLE
4. Existing position must be closed before change

---

📈 Position Structure

HedgePosition

struct HedgePosition {
    address hedger;           // Hedger address
    uint96 positionSize;      // Position size (total exposure)
    uint96 filledVolume;      // Volume filled by user mints
    uint96 margin;            // USDC margin deposited
    uint96 entryPrice;        // Average entry price (EUR/USD)
    uint64 entryTime;         // Opening timestamp
    uint64 lastUpdateTime;    // Last update
    int128 unrealizedPnL;     // Unrealized P&L
    int128 realizedPnL;       // Realized P&L
    uint8 leverage;           // Leverage used
    bool isActive;            // Position active
    uint128 qeuroBacked;      // QEURO backed by this position
}

HedgerRewardState

struct HedgerRewardState {
    uint128 pendingRewards;    // Pending rewards
    uint64 lastRewardClaim;    // Last claim
}

---

💰 Position Management

Open a Position

function enterHedgePosition(
    uint96 positionSize,
    uint96 margin,
    uint8 leverage
) external onlyRole(HEDGER_ROLE) whenNotPaused nonReentrant
    returns (uint256 positionId);

Validations

1. Hedger doesn't already have an active position

2. positionSize > 0 and margin > 0

3. leverage <= maxLeverage

4. Sufficient margin ratio: margin × leverage >= positionSize × minMarginRatio

Flow

1. Hedger deposits USDC (margin)
2. Position created with entryPrice = current oracle price
3. Position marked active
4. USDC transferred to Vault for unified liquidity

Close a Position

function exitHedgePosition() 
    external onlyRole(HEDGER_ROLE) whenNotPaused nonReentrant;

Validations

1. Active position exists

2. filledVolume == 0 (no more backed QEURO)

3. Position "safe to close" (no debt to users)

Flow

1. Final P&L calculation
2. Return margin ± P&L to hedger
3. Position marked inactive
4. Residual rewards claimable

Add Margin

function addMargin(uint96 amount) 
    external onlyRole(HEDGER_ROLE) whenNotPaused nonReentrant;

Allows the hedger to improve margin ratio without closing the position.

Remove Margin

function removeMargin(uint96 amount) 
    external onlyRole(HEDGER_ROLE) whenNotPaused nonReentrant;

Condition: Margin ratio must remain above minMarginRatio after withdrawal.

---

📊 P&L Calculation

Unrealized P&L

// Simplified: P&L based on EUR/USD price variation
unrealizedPnL = filledVolume × (currentPrice - entryPrice) / entryPrice

EUR/USD Movement	Hedger Impact
EUR ↑ vs USD	Negative P&L
EUR ↓ vs USD	Positive P&L

Realized P&L

P&L is realized during QEURO redemptions:

function recordUserRedeem(uint256 qeuroAmount, uint256 usdcAmount) 
    external onlyVault;

Redemption Flow

1. User redeems QEURO via Vault
2. Vault calls recordUserRedeem
3. HedgerPool calculates portion of filled volume to close
4. Proportional P&L is realized
5. filledVolume and qeuroBacked decrease

Formula

// Closed portion
closedPortion = qeuroAmount / totalQeuroBacked

// Realized P&L on this portion  
realizedPnLPortion = closedPortion × (redemptionPrice - entryPrice) × filledVolume

---

🔄 Vault Synchronization

The HedgerPool is synchronized with Vault mint/redeem operations.

During a Mint

function recordUserMint(uint256 qeuroAmount, uint256 usdcAmount, uint256 price) 
    external onlyVault;

Actions

1. Increases filledVolume of active position

2. Updates entryPrice (weighted average)

3. Increases qeuroBacked

During a Redeem

function recordUserRedeem(uint256 qeuroAmount, uint256 usdcAmount) 
    external onlyVault;

Actions

1. Decreases filledVolume proportionally

2. Realizes P&L on closed portion

3. Decreases qeuroBacked

During a Liquidation

function recordLiquidationRedeem(uint256 qeuroAmount, uint256 usdcAmount) 
    external onlyVault;

Similar to standard redeem, but may apply special conditions.

---

💸 Reward Distribution

Hedger Revenue Sources

1. YieldShift Allocation: Share of Aave yield (10-50% depending on ratios)

2. EUR/USD Rate Differential: Compensation for FX risk

3. Position Fees: Entry/exit fees if configured

Claim Rewards

function claimHedgingRewards() 
    external onlyRole(HEDGER_ROLE) whenNotPaused nonReentrant;

Constraints

uint256 public constant MAX_REWARD_PERIOD = 365 days;
// Accumulated rewards cannot exceed 1 year of calculation

---

⚙️ Configurable Parameters

CoreParams

struct CoreParams {
    uint16 minMarginRatio;     // Minimum margin ratio (BPS)
    uint8 maxLeverage;         // Maximum allowed leverage
    uint16 entryFee;           // Entry fee (BPS)
    uint16 exitFee;            // Exit fee (BPS)
    uint16 marginFee;          // Margin fee (BPS)
    uint16 eurInterestRate;    // EUR interest rate (BPS)
    uint16 usdInterestRate;    // USD interest rate (BPS)
}

Defaults

Parameter	Default Value	Description
minMarginRatio	1000 (10%)	Minimum margin/position ratio
maxLeverage	10	Max 10x leverage
entryFee	0	No entry fee
exitFee	0	No exit fee

Configuration Functions

// General parameters
function updateHedgingParameters(uint16 minMargin, uint8 maxLev) 
    external onlyRole(GOVERNANCE_ROLE);

// Interest rates
function updateInterestRates(uint16 eurRate, uint16 usdRate) 
    external onlyRole(GOVERNANCE_ROLE);

// Fees
function setHedgingFees(uint16 entry, uint16 exit, uint16 margin) 
    external onlyRole(GOVERNANCE_ROLE);

---

🛡️ Security & Emergency Controls

Health Checks

// Checks if position can support a fill
function _isPositionHealthyForFill(HedgePosition memory pos) 
    internal view returns (bool);

// Checks if closure is safe
function _validatePositionClosureSafety(HedgePosition storage pos) 
    internal view;

Emergency Close

function emergencyClosePosition(address hedger) 
    external onlyRole(EMERGENCY_ROLE);

Allows the emergency team to close a position if:

• Hedger is non-responsive

• Position becomes dangerous for the protocol

• A vulnerability is detected

Pause

function pause() external onlyRole(EMERGENCY_ROLE);
function unpause() external onlyRole(EMERGENCY_ROLE);

Recovery

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

Recovers tokens sent by mistake (cannot recover active USDC).

---

📏 Constants & Limits

// Position limits
uint96 public constant MAX_POSITION_SIZE = type(uint96).max;
uint96 public constant MAX_MARGIN = type(uint96).max;
uint96 public constant MAX_ENTRY_PRICE = type(uint96).max;
uint8 public constant MAX_LEVERAGE = 10;
uint16 public constant MAX_MARGIN_RATIO = 10000;  // 100%

// Global limits
uint128 public constant MAX_TOTAL_MARGIN = type(uint128).max;
uint128 public constant MAX_TOTAL_EXPOSURE = type(uint128).max;

// Time limits
uint256 public constant MAX_REWARD_PERIOD = 365 days;

---

📊 View Functions

Collateral Metrics

// Total effective hedger collateral (margin + P&L)
function getTotalEffectiveHedgerCollateral() 
    external view returns (uint256);

// Is there an active hedger?
function hasActiveHedger() external view returns (bool);

Position Data

// Get a position by ID
mapping(uint256 => HedgePosition) public positions;

// Hedger's active position ID
mapping(address => uint256) public hedgerActivePositionId;

---

🔗 YieldShift Integration

The HedgerPool integrates with YieldShift for yield distribution:

IYieldShift public yieldShift;

Distribution Flow

Aave generates yield
    ↓
YieldShift calculates allocations
    ↓
HedgerPool receives its share (10-50%)
    ↓
Hedger claims via claimHedgingRewards()

---

📋 Events

event PositionOpened(address indexed hedger, uint256 positionId, uint96 size, uint96 margin);
event PositionClosed(address indexed hedger, uint256 positionId, int128 finalPnL);
event MarginAdded(address indexed hedger, uint256 positionId, uint96 amount);
event MarginRemoved(address indexed hedger, uint256 positionId, uint96 amount);
event RewardsClaimed(address indexed hedger, uint256 amount);
event SingleHedgerSet(address indexed oldHedger, address indexed newHedger);

---

⚠️ Custom Errors

error PositionAlreadyExists();
error NoActivePosition();
error InsufficientMargin();
error LeverageTooHigh();
error PositionNotSafeToClose();
error FilledVolumeNotZero();
error InvalidAmount();

---

Summary: The HedgerPool is the core of Quantillon's hedging mechanics. In the MVP, a single hedger provides EUR/USD coverage, earning revenue via YieldShift and rate differentials. The real-time P&L system and security controls ensure protocol stability.