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