ZivoeYDL.sol

YDL -> Yield Distribution Locker

Introduction

This contract manages the accounting for distributing yield across multiple contracts.

This contract has the following responsibilities:

• Escrows yield in between distribution periods.

• Manages accounting for yield distribution.

• Supports modification of certain state variables for governance purposes.

• Tracks historical values using EMA (exponential moving average) on 30-day basis.

State Variables

Type	Name	Description
Recipients	protocolRecipients	Tracks the distributions for protocol earnings.
Recipients	residualRecipients	Tracks the distributions for residual earnings.
address	GBL	The ZivoeGlobals contract.
address	distributedAsset	The "stablecoin" that will be distributed via YDL.
uint256	emaSTT	Weighted moving average for senior tranche size, a.k.a. zSTT.totalSupply().
uint256	emaJTT	Weighted moving average for junior tranche size, a.k.a. zJTT.totalSupply().
uint256	distributionCounter	Number of calls to distributeYield().
uint256	lastDistribution	Used for timelock constraint to call distributeYield().
uint256	targetAPYBIPS	The target annualized yield for senior tranche.
uint256	targetRatioBIPS	The target ratio of junior to senior tranche.
uint256	protocolEarningsRateBIPS	The protocol earnings rate.
uint256	daysBetweenDistributions	Number of days between yield distributions.
uint256	retrospectiveDistributions	Retrospective moving average period.
bool	unlocked	Prevents contract from supporting functionality until unlocked.
uint256	BIPS	Private constant, 10000
uint256	RAY	Private constant, 10**27
ZivoeMath.sol	MATH	Refers to the ZivoeMath contract,

Recipients

This struct stores information for distributions of yield (used for earnings and residual).

Type	Name	Description
address[]	recipients	An array of addresses that will benefit from protocol earnings.
uint256[]	proportion	An array of weights in BIPS for each specific recipient above.

Sections

Read Functions

• earningsTrancheuse() - Calculates the distribution of yield ("earnings") for the four primary groups.

• viewDistributions() - View distribution information for protocol and residual earnings recipients.

Write Functions

• distributeYield() - Distributes available yield within this contract to appropriate entities.

• returnAsset() - Returns an asset to DAO if not distributedAsset().

• unlock() - Unlocks this contract for distributions, initializes values.

• updateDistributedAsset() - Updates the distributed asset for this particular contract.

• updateProtocolEarningsRateBIPS() - Updates the state variable "protocolEarningsRateBIPS".

• updateRecipients() - Updates the protocolRecipients or residualRecipients.

• updateTargetAPYBIPS() - Updates the state variable "targetAPYBIPS".

• updateTargetRatioBIPS() - Updates the state variable "targetRatioBIPS".

Events

• AssetReturned()

• UpdatedDistributedAsset()

• UpdatedProtocolEarningsRateBIPS()

• UpdatedProtocolRecipients()

• UpdatedResidualRecipients()

• UpdatedTargetAPYBIPS()

• UpdatedTargetRatioBIPS()

• YieldDistributed()

• YieldDistributedSingle()

Read Functions

earningsTrancheuse()

Calculates the distribution of yield ("earnings") for the four primary groups.

function earningsTrancheuse(
    uint256 yP, 
    uint256 yD
) public view returns (
    uint256[] memory protocol, 
    uint256 senior, 
    uint256 junior, 
    uint256[] memory residual
);

Type	Name	Description
uint256	yP	Yield for the protocol.
uint256	yD	Yield for the remaining three groups.

Returns

Type	Name	Description
uint256[]	protocol	Protocol earnings.
uint256	senior	Senior tranche earnings.
uint256	junior	Junior tranche earnings.
uint256[]	residual	Residual earnings.

viewDistributions()

View distribution information for protocol and residual earnings recipients.

function viewDistributions() external view returns (
    address[] memory protocolEarningsRecipients, 
    uint256[] memory protocolEarningsProportion, 
    address[] memory residualEarningsRecipients, 
    uint256[] memory residualEarningsProportion
);

Returns

Type	Name	Description
address[]	protocolEarningsRecipients	The destinations for protocol earnings distributions.
uint256[]	protocolEarningsProportion	The proportions for protocol earnings distributions.
address[]	residualEarningsRecipients	The destinations for residual earnings distributions.
uint256[]	residualEarningsProportion	The proportions for residual earnings distributions.

Write Functions

distributeYield()

Distributes available yield within this contract to appropriate entities.

function distributeYield() external;

Emits the YieldDistributed() and YieldDistributedSingle() event(s)

returnAsset()

Returns an asset to DAO if not distributedAsset().

function returnAsset(address asset) external;

Type	Name	Description
address	asset	The asset to return.

Emits the AssetReturned() event

unlock()

Unlocks this contract for distributions, initializes values.

function unlock() external;

updateDistributedAsset()

Updates the distributed asset for this particular contract.

function updateDistributedAsset(address _distributedAsset) external nonReentrant;

Type	Name	Description
address	_distributedAsset	The new value for distributed asset.

Emits the UpdatedDistributedAsset() event

updateProtocolEarningsRateBIPS()

Updates the state variable "protocolEarningsRateBIPS".

function updateProtocolEarningsRateBIPS(uint256 _protocolEarningsRateBIPS) external;

Type	Name	Description
uint256	_protocolEarningsRateBIPS	The new value for protocolEarningsRateBIPS.

Emits the UpdatedProtocolEarningsRateBIPS() event

updateRecipients()

Updates the protocolRecipients or residualRecipients.

function updateRecipients(
    address[] memory recipients, 
    uint256[] memory proportions, 
    bool protocol
) external;

Type	Name	Description
address[]	recipients	An array of addresses to which protocol earnings will be distributed.
uint256[]	proportions	An array of ratios relative to the recipients - in BIPS. Sum should equal to 10000.
bool	protocol	Specifiy "true" to update protocol earnings, or "false" to update residual earnings.

Emits the UpdatedProtocolRecipients() and UpdatedResidualRecipients() event(s)

updateTargetAPYBIPS()

Updates the state variable "targetAPYBIPS".

function updateTargetAPYBIPS(uint256 _targetAPYBIPS) external;

Type	Name	Description
uint256	_targetAPYBIPS	The new value for targetAPYBIPS.

Emits the UpdatedTargetAPYBIPS() event

updateTargetRatioBIPS()

Updates the state variable "targetRatioBIPS".

function updateTargetRatioBIPS(uint256 _targetRatioBIPS) external;

Type	Name	Description
uint256	_targetRatioBIPS	The new value for targetRatioBIPS.

Emits the UpdatedTargetRatioBIPS() event

Events

AssetReturned()

Emitted during returnAsset()

event AssetReturned(address indexed asset, uint256 amount);

Type	Indexed	Name	Description
address	True	asset	The asset returned.
uint256	False	amount	The amount of "asset" returned to DAO.

UpdatedDistributedAsset()

Emitted during updateDistributedAsset()

event UpdatedDistributedAsset(address indexed oldAsset, address indexed newAsset);

Type	Indexed	Name	Description
address	True	oldAsset	The old value of distributedAsset.
address	True	newAsset	The new value of distributedAsset.

UpdatedProtocolEarningsRateBIPS()

Emitted during updateProtocolEarningsRateBIPS()

event UpdatedProtocolEarningsRateBIPS(uint256 oldValue, uint256 newValue);

Type	Indexed	Name	Description
uint256	False	oldValue	The old value of protocolEarningsRateBIPS.
uint256	False	newValue	The new value of protocolEarningsRateBIPS.

UpdatedProtocolRecipients()

Emitted during updateRecipients()

event UpdatedProtocolRecipients(address[] recipients, uint256[] proportion);

Type	Indexed	Name	Description
address[]	False	recipients	The new recipients to receive protocol earnings.
uint256[]	False	proportion	The proportion distributed across recipients.

UpdatedResidualRecipients()

Emitted during updateRecipients()

event UpdatedResidualRecipients(address[] recipients, uint256[] proportion);

Type	Indexed	Name	Description
address[]	False	recipients	The new recipients to receive residual earnings.
uint256[]	False	proportion	The proportion distributed across recipients.

UpdatedTargetAPYBIPS()

Emitted during updateTargetAPYBIPS()

event UpdatedTargetAPYBIPS(uint256 oldValue, uint256 newValue);

Type	Indexed	Name	Description
uint256	False	oldValue	The old value of targetAPYBIPS.
uint256	False	newValue	The new value of targetAPYBIPS.

UpdatedTargetRatioBIPS()

Emitted during UpdatedTargetRatioBIPS()

event UpdatedTargetRatioBIPS(uint256 oldValue, uint256 newValue);

Type	Indexed	Name	Description
uint256	False	oldValue	The old value of targetRatioBIPS.
uint256	False	newValue	The new value of targetRatioBIPS.

YieldDistributed()

Emitted during distributeYield()

event YieldDistributed(
    uint256[] protocol, 
    uint256 senior, 
    uint256 junior, 
    uint256[] residual
);

Type	Indexed	Name	Description
uint256[]	False	protocol	The amount of earnings distributed to protocol earnings recipients.
uint256	False	senior	The amount of earnings distributed to the senior tranche.
uint256	False	junior	The amount of earnings distributed to the junior tranche.
uint256[]	False	residual	The amount of earnings distributed to residual earnings recipients.

YieldDistributedSingle()

Emitted during distributeYield()

event YieldDistributedSingle(
    address indexed asset, 
    address indexed recipient, 
    uint256 amount
);

Type	Indexed	Name	Description
address	True	asset	The "asset" being distributed.
address	True	recipient	The recipient of the distribution.
uint256	False	amount	The amount distributed