Quantillon Protocol

Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

HedgerPoolOptimizationLibrary

Git Source

Author: Quantillon Labs

Library for HedgerPool data packing, validation, and utility functions

Extracts utility functions from HedgerPool to reduce contract size

Functions

packPositionOpenData

Packs position open data into a single bytes32 for gas efficiency

Encodes position size, margin, leverage, and entry price into a compact format

Notes:

  • security: No security implications - pure data packing function

  • validation: Input validation handled by calling contract

  • state-changes: No state changes - pure function

  • events: No events emitted

  • errors: No errors thrown - pure function

  • reentrancy: Not applicable - pure function

  • access: Public function

  • oracle: No oracle dependencies

function packPositionOpenData(uint256 positionSize, uint256 margin, uint256 leverage, uint256 entryPrice)
    external
    pure
    returns (bytes32);

Parameters

NameTypeDescription
positionSizeuint256Size of the position in USDC
marginuint256Margin amount for the position
leverageuint256Leverage multiplier for the position
entryPriceuint256Price at which the position was opened

Returns

NameTypeDescription
<none>bytes32Packed data as bytes32

packPositionCloseData

Packs position close data into a single bytes32 for gas efficiency

Encodes exit price, PnL, and timestamp into a compact format

Notes:

  • security: No security implications - pure data packing function

  • validation: Input validation handled by calling contract

  • state-changes: No state changes - pure function

  • events: No events emitted

  • errors: No errors thrown - pure function

  • reentrancy: Not applicable - pure function

  • access: Public function

  • oracle: No oracle dependencies

function packPositionCloseData(uint256 exitPrice, int256 pnl, uint256 timestamp) external pure returns (bytes32);

Parameters

NameTypeDescription
exitPriceuint256Price at which the position was closed
pnlint256Profit or loss from the position (can be negative)
timestampuint256Timestamp when the position was closed

Returns

NameTypeDescription
<none>bytes32Packed data as bytes32

packMarginData

Packs margin data into a single bytes32 for gas efficiency

Encodes margin amount, new margin ratio, and operation type

Notes:

  • security: No security implications - pure data packing function

  • validation: Input validation handled by calling contract

  • state-changes: No state changes - pure function

  • events: No events emitted

  • errors: No errors thrown - pure function

  • reentrancy: Not applicable - pure function

  • access: Public function

  • oracle: No oracle dependencies

function packMarginData(uint256 marginAmount, uint256 newMarginRatio, bool isAdded)
    external
    pure
    returns (bytes32);

Parameters

NameTypeDescription
marginAmountuint256Amount of margin added or removed
newMarginRatiouint256New margin ratio after the operation
isAddedboolTrue if margin was added, false if removed

Returns

NameTypeDescription
<none>bytes32Packed data as bytes32

packLiquidationData

Packs liquidation data into a single bytes32 for gas efficiency

Encodes liquidation reward and remaining margin

Notes:

  • security: No security implications - pure data packing function

  • validation: Input validation handled by calling contract

  • state-changes: No state changes - pure function

  • events: No events emitted

  • errors: No errors thrown - pure function

  • reentrancy: Not applicable - pure function

  • access: Public function

  • oracle: No oracle dependencies

function packLiquidationData(uint256 liquidationReward, uint256 remainingMargin) external pure returns (bytes32);

Parameters

NameTypeDescription
liquidationRewarduint256Reward paid to the liquidator
remainingMarginuint256Margin remaining after liquidation

Returns

NameTypeDescription
<none>bytes32Packed data as bytes32

packRewardData

Packs reward data into a single bytes32 for gas efficiency

Encodes interest differential, yield shift rewards, and total rewards

Notes:

  • security: No security implications - pure data packing function

  • validation: Input validation handled by calling contract

  • state-changes: No state changes - pure function

  • events: No events emitted

  • errors: No errors thrown - pure function

  • reentrancy: Not applicable - pure function

  • access: Public function

  • oracle: No oracle dependencies

function packRewardData(uint256 interestDifferential, uint256 yieldShiftRewards, uint256 totalRewards)
    external
    pure
    returns (bytes32);

Parameters

NameTypeDescription
interestDifferentialuint256Interest rate differential between EUR and USD
yieldShiftRewardsuint256Rewards from yield shifting operations
totalRewardsuint256Total rewards accumulated

Returns

NameTypeDescription
<none>bytes32Packed data as bytes32

validateRole

Validates that the caller has the required role

Internal function to check role-based access control

Notes:

  • security: Prevents unauthorized access to protected functions

  • validation: Ensures proper role-based access control

  • state-changes: No state changes - view function

  • events: No events emitted

  • errors: Throws NotAuthorized if caller lacks required role

  • reentrancy: Not applicable - view function

  • access: External function with role validation

  • oracle: No oracle dependencies

function validateRole(bytes32 role, address contractInstance) external view;

Parameters

NameTypeDescription
rolebytes32The role to validate against
contractInstanceaddressThe contract instance to check roles on

validatePositionClosureSafety

Validates that closing a position won't cause protocol undercollateralization

Checks if closing the position would make the protocol undercollateralized for QEURO minting

Notes:

  • security: Prevents protocol undercollateralization from position closures

  • validation: Ensures protocol remains properly collateralized

  • state-changes: No state changes - view function

  • events: No events emitted

  • errors: No errors thrown - returns boolean result

  • reentrancy: Not applicable - view function

  • access: External function

  • oracle: No oracle dependencies

function validatePositionClosureSafety(uint256 positionMargin, address vaultAddress)
    external
    view
    returns (bool isValid);

Parameters

NameTypeDescription
positionMarginuint256The margin amount of the position being closed
vaultAddressaddressAddress of the vault contract

Returns

NameTypeDescription
isValidboolTrue if position can be safely closed

_getProtocolData

Gets protocol collateralization data

Internal function to reduce stack depth

Notes:

  • security: Uses staticcall for safe external contract interaction

  • validation: Validates call success and data length before decoding

  • state-changes: No state changes, view function

  • events: No events emitted

  • errors: Returns default values on call failures

  • reentrancy: No reentrancy risk, view function

  • access: Internal function, no access control needed

  • oracle: No oracle dependencies

function _getProtocolData(address vaultAddress)
    internal
    view
    returns (bool isCollateralized, uint256 currentTotalMargin, uint256 minCollateralizationRatio);

Parameters

NameTypeDescription
vaultAddressaddressAddress of the vault contract

Returns

NameTypeDescription
isCollateralizedboolWhether protocol is currently collateralized
currentTotalMarginuint256Current total margin in the protocol
minCollateralizationRatiouint256Minimum collateralization ratio for minting

_hasQEUROMinted

Checks if QEURO has been minted

Internal function to reduce stack depth

Notes:

  • security: Uses staticcall for safe external contract interaction

  • validation: Validates call success and data length before decoding

  • state-changes: No state changes, view function

  • events: No events emitted

  • errors: Returns false on call failures

  • reentrancy: No reentrancy risk, view function

  • access: Internal function, no access control needed

  • oracle: No oracle dependencies

function _hasQEUROMinted(address vaultAddress) internal view returns (bool hasMinted);

Parameters

NameTypeDescription
vaultAddressaddressAddress of the vault contract

Returns

NameTypeDescription
hasMintedboolWhether QEURO has been minted (totalSupply > 0)

_validateClosureWithUserDeposits

Validates closure with user deposits

Internal function to reduce stack depth

Notes:

  • security: Validates protocol remains collateralized after closure

  • validation: Ensures closure doesn't violate collateralization requirements

  • state-changes: No state changes, view function

  • events: No events emitted

  • errors: No custom errors, returns boolean result

  • reentrancy: No reentrancy risk, view function

  • access: Internal function, no access control needed

  • oracle: No oracle dependencies

function _validateClosureWithUserDeposits(
    address vaultAddress,
    uint256 positionMargin,
    uint256 currentTotalMargin,
    uint256 minCollateralizationRatio
) internal view returns (bool isValid);

Parameters

NameTypeDescription
vaultAddressaddressAddress of the vault contract
positionMarginuint256Margin for the position being closed
currentTotalMarginuint256Current total margin in the protocol
minCollateralizationRatiouint256Minimum collateralization ratio for minting

Returns

NameTypeDescription
isValidboolWhether the position can be safely closed

removePositionFromArrays

Removes a position from the hedger's position arrays

Internal function to maintain position tracking arrays

Notes:

  • security: Maintains data integrity of position tracking arrays

  • validation: Ensures position exists before removal

  • state-changes: Modifies storage mappings and arrays

  • events: No events emitted

  • errors: No errors thrown - returns boolean result

  • reentrancy: Not applicable - no external calls

  • access: External function

  • oracle: No oracle dependencies

function removePositionFromArrays(
    address hedger,
    uint256 positionId,
    mapping(address => mapping(uint256 => bool)) storage hedgerHasPosition,
    mapping(address => mapping(uint256 => uint256)) storage positionIndex,
    uint256[] storage positionIds
) external returns (bool success);

Parameters

NameTypeDescription
hedgeraddressAddress of the hedger whose position to remove
positionIduint256ID of the position to remove
hedgerHasPositionmapping(address => mapping(uint256 => bool))Mapping of hedger to position existence
positionIndexmapping(address => mapping(uint256 => uint256))Mapping of hedger to position index
positionIdsuint256[]Array of position IDs for the hedger

Returns

NameTypeDescription
successboolTrue if position was successfully removed

getValidOraclePrice

Gets a valid EUR/USD price from the oracle

Retrieves and validates price data from the oracle contract

Notes:

  • security: Ensures oracle price data is valid before use

  • validation: Validates oracle response format and data

  • state-changes: No state changes - view function

  • events: No events emitted

  • errors: No errors thrown - returns boolean result

  • reentrancy: Not applicable - view function

  • access: External function

  • oracle: Depends on oracle contract for price data

function getValidOraclePrice(address oracleAddress) external view returns (uint256 price, bool isValid);

Parameters

NameTypeDescription
oracleAddressaddressAddress of the oracle contract

Returns

NameTypeDescription
priceuint256Valid EUR/USD price from oracle
isValidboolTrue if price is valid