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

YieldShiftOptimizationLibrary

Git Source

Author: Quantillon Labs

Library for YieldShift pool metrics, historical data, and utility functions

Extracts utility functions from YieldShift to reduce contract size

State Variables

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

MAX_HISTORY_LENGTH

uint256 public constant MAX_HISTORY_LENGTH = 100

Functions

getCurrentPoolMetrics

Get current pool metrics

Returns current pool sizes and ratio for yield shift calculations

Notes:

  • security: No security implications - view function

  • validation: Input validation handled by calling contract

  • state-changes: No state changes - view function

  • events: No events emitted

  • errors: No errors thrown - view function

  • reentrancy: Not applicable - view function

  • access: Public function

  • oracle: No oracle dependencies

function getCurrentPoolMetrics(address userPoolAddress, address hedgerPoolAddress)
    external
    view
    returns (uint256 userPoolSize, uint256 hedgerPoolSize, uint256 poolRatio);

Parameters

NameTypeDescription
userPoolAddressaddressAddress of the user pool contract
hedgerPoolAddressaddressAddress of the hedger pool contract

Returns

NameTypeDescription
userPoolSizeuint256Current user pool size
hedgerPoolSizeuint256Current hedger pool size
poolRatiouint256Ratio of user to hedger pool sizes

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: Prevents flash deposit attacks by excluding recent deposits

  • validation: Input validation handled by calling contract

  • state-changes: No state changes - view function

  • events: No events emitted

  • errors: No errors thrown - view function

  • reentrancy: Not applicable - view function

  • access: Public function

  • oracle: No oracle dependencies

function getEligiblePoolMetrics(
    address userPoolAddress,
    address hedgerPoolAddress,
    uint256 currentTime,
    uint256 lastUpdateTime
) external view returns (uint256 userPoolSize, uint256 hedgerPoolSize, uint256 poolRatio);

Parameters

NameTypeDescription
userPoolAddressaddressAddress of the user pool contract
hedgerPoolAddressaddressAddress of the hedger pool contract
currentTimeuint256Current timestamp
lastUpdateTimeuint256Last update timestamp

Returns

NameTypeDescription
userPoolSizeuint256Eligible user pool size (deposits older than MIN_HOLDING_PERIOD)
hedgerPoolSizeuint256Eligible hedger pool size (deposits older than MIN_HOLDING_PERIOD)
poolRatiouint256Ratio of eligible pool sizes

calculateEligibleUserPoolSize

Calculate eligible user pool size excluding recent deposits

Only counts deposits older than MIN_HOLDING_PERIOD

Notes:

  • security: Prevents flash deposit attacks by excluding recent deposits

  • 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 calculateEligibleUserPoolSize(uint256 totalUserPoolSize, uint256 currentTime, uint256 lastUpdateTime)
    external
    pure
    returns (uint256 eligibleSize);

Parameters

NameTypeDescription
totalUserPoolSizeuint256Current total user pool size
currentTimeuint256Current timestamp
lastUpdateTimeuint256Last update timestamp

Returns

NameTypeDescription
eligibleSizeuint256Eligible pool size for yield calculations

_calculateEligibleUserPoolSize

Internal function to calculate eligible user pool size

Only counts deposits older than MIN_HOLDING_PERIOD

Notes:

  • security: Prevents flash deposit attacks by excluding recent deposits

  • validation: Input validation handled by calling function

  • state-changes: No state changes - pure function

  • events: No events emitted

  • errors: No errors thrown - pure function

  • reentrancy: Not applicable - pure function

  • access: Internal function

  • oracle: No oracle dependencies

function _calculateEligibleUserPoolSize(uint256 totalUserPoolSize, uint256 currentTime, uint256 lastUpdateTime)
    internal
    pure
    returns (uint256 eligibleSize);

Parameters

NameTypeDescription
totalUserPoolSizeuint256Current total user pool size
currentTimeuint256Current timestamp
lastUpdateTimeuint256Last update timestamp

Returns

NameTypeDescription
eligibleSizeuint256Eligible pool size for yield calculations

calculateEligibleHedgerPoolSize

Calculate eligible hedger pool size excluding recent deposits

Only counts deposits older than MIN_HOLDING_PERIOD

Notes:

  • security: Prevents flash deposit attacks by excluding recent deposits

  • 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 calculateEligibleHedgerPoolSize(uint256 totalHedgerPoolSize, uint256 currentTime, uint256 lastUpdateTime)
    external
    pure
    returns (uint256 eligibleSize);

Parameters

NameTypeDescription
totalHedgerPoolSizeuint256Current total hedger pool size
currentTimeuint256Current timestamp
lastUpdateTimeuint256Last update timestamp

Returns

NameTypeDescription
eligibleSizeuint256Eligible pool size for yield calculations

_calculateEligibleHedgerPoolSize

Internal function to calculate eligible hedger pool size

Only counts deposits older than MIN_HOLDING_PERIOD

Notes:

  • security: Prevents flash deposit attacks by excluding recent deposits

  • validation: Input validation handled by calling function

  • state-changes: No state changes - pure function

  • events: No events emitted

  • errors: No errors thrown - pure function

  • reentrancy: Not applicable - pure function

  • access: Internal function

  • oracle: No oracle dependencies

function _calculateEligibleHedgerPoolSize(uint256 totalHedgerPoolSize, uint256 currentTime, uint256 lastUpdateTime)
    internal
    pure
    returns (uint256 eligibleSize);

Parameters

NameTypeDescription
totalHedgerPoolSizeuint256Current total hedger pool size
currentTimeuint256Current timestamp
lastUpdateTimeuint256Last update timestamp

Returns

NameTypeDescription
eligibleSizeuint256Eligible pool size for yield calculations

calculateHoldingPeriodDiscount

Calculate holding period discount based on recent deposit activity

Returns a percentage (in basis points) representing eligible deposits

Notes:

  • security: No security implications - pure calculation 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 calculateHoldingPeriodDiscount(uint256 currentTime, uint256 lastUpdateTime)
    external
    pure
    returns (uint256 discountBps);

Parameters

NameTypeDescription
currentTimeuint256Current timestamp
lastUpdateTimeuint256Last update timestamp

Returns

NameTypeDescription
discountBpsuint256Discount in basis points (10000 = 100%)

_calculateHoldingPeriodDiscount

Internal function to calculate holding period discount

Returns a percentage (in basis points) representing eligible deposits

Notes:

  • security: No security implications - pure calculation function

  • validation: Input validation handled by calling function

  • state-changes: No state changes - pure function

  • events: No events emitted

  • errors: No errors thrown - pure function

  • reentrancy: Not applicable - pure function

  • access: Internal function

  • oracle: No oracle dependencies

function _calculateHoldingPeriodDiscount(uint256 currentTime, uint256 lastUpdateTime)
    internal
    pure
    returns (uint256 discountBps);

Parameters

NameTypeDescription
currentTimeuint256Current timestamp
lastUpdateTimeuint256Last update timestamp

Returns

NameTypeDescription
discountBpsuint256Discount in basis points (10000 = 100%)

getTimeWeightedAverage

Get time weighted average of pool history

Calculates time weighted average of pool history over a specified period

Notes:

  • security: No security implications - pure calculation 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 getTimeWeightedAverage(
    PoolSnapshot[] memory poolHistory,
    uint256 period,
    bool isUserPool,
    uint256 currentTime
) external pure returns (uint256);

Parameters

NameTypeDescription
poolHistoryPoolSnapshot[]Array of pool snapshots
perioduint256Time period for calculation
isUserPoolboolWhether this is for user pool or hedger pool
currentTimeuint256Current timestamp

Returns

NameTypeDescription
<none>uint256Time weighted average value

addToPoolHistory

Add pool snapshot to history

Adds a pool snapshot to the history array with size management

Notes:

  • security: No security implications - pure 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 addToPoolHistory(
    PoolSnapshot[] memory poolHistory,
    uint256 poolSize,
    bool isUserPool,
    uint256 currentTime
) external pure returns (PoolSnapshot[] memory newHistory);

Parameters

NameTypeDescription
poolHistoryPoolSnapshot[]Array of pool snapshots to add to
poolSizeuint256Size of the pool to record
isUserPoolboolWhether this is for user pool or hedger pool
currentTimeuint256Current timestamp

Returns

NameTypeDescription
newHistoryPoolSnapshot[]Updated pool history array

calculateUserAllocation

Calculate user allocation from current yield shift

Calculates user allocation based on current yield shift percentage

Notes:

  • security: No security implications - pure calculation 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 calculateUserAllocation(uint256 userYieldPool, uint256 hedgerYieldPool, uint256 currentYieldShift)
    external
    pure
    returns (uint256);

Parameters

NameTypeDescription
userYieldPooluint256Current user yield pool amount
hedgerYieldPooluint256Current hedger yield pool amount
currentYieldShiftuint256Current yield shift percentage

Returns

NameTypeDescription
<none>uint256User allocation amount based on current yield shift percentage

calculateHedgerAllocation

Calculate hedger allocation from current yield shift

Calculates hedger allocation based on current yield shift percentage

Notes:

  • security: No security implications - pure calculation 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 calculateHedgerAllocation(uint256 userYieldPool, uint256 hedgerYieldPool, uint256 currentYieldShift)
    external
    pure
    returns (uint256);

Parameters

NameTypeDescription
userYieldPooluint256Current user yield pool amount
hedgerYieldPooluint256Current hedger yield pool amount
currentYieldShiftuint256Current yield shift percentage

Returns

NameTypeDescription
<none>uint256Hedger allocation amount based on current yield shift percentage

isWithinTolerance

Check if a value is within tolerance of a target value

Checks if a value is within the specified tolerance of a target

Notes:

  • security: No security implications - pure calculation 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 isWithinTolerance(uint256 value, uint256 target, uint256 toleranceBps) external pure returns (bool);

Parameters

NameTypeDescription
valueuint256The value to check
targetuint256The target value
toleranceBpsuint256Tolerance in basis points (e.g., 1000 = 10%)

Returns

NameTypeDescription
<none>boolTrue if value is within tolerance, false otherwise

calculateHistoricalYieldShift

Calculate historical yield shift metrics

Calculates statistical metrics for yield shift history

Notes:

  • security: No security implications - pure calculation 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 calculateHistoricalYieldShift(
    YieldShiftSnapshot[] memory yieldShiftHistory,
    uint256 period,
    uint256 currentTime
) external pure returns (uint256 averageShift, uint256 maxShift, uint256 minShift, uint256 volatility);

Parameters

NameTypeDescription
yieldShiftHistoryYieldShiftSnapshot[]Array of yield shift snapshots
perioduint256Time period to analyze
currentTimeuint256Current timestamp

Returns

NameTypeDescription
averageShiftuint256Average yield shift during the period
maxShiftuint256Maximum yield shift during the period
minShiftuint256Minimum yield shift during the period
volatilityuint256Volatility measure of yield shifts

Structs

PoolSnapshot

struct PoolSnapshot {
    uint64 timestamp;
    uint128 userPoolSize;
    uint128 hedgerPoolSize;
}

YieldShiftSnapshot

struct YieldShiftSnapshot {
    uint128 yieldShift;
    uint64 timestamp;
}