# ZivoeMath.sol

## Introduction

This contract facilitates mathematics, intended solely for the YDL.

*Note: This contract is deployed and tracked via ZivoeYDL, see* [zivoeydl.sol](https://docs.zivoe.com/developer-docs/core-contracts/zivoeydl.sol "mention") and for further information on the derivation of the equations, see [Broken link](https://docs.zivoe.com/developer-docs/core-contracts/broken-reference "mention")

#### State Variables

<table><thead><tr><th width="144.33333333333331">Type</th><th width="150">Name</th><th>Description</th></tr></thead><tbody><tr><td>uint256</td><td>BIPS</td><td>Private constant, <code>10000</code></td></tr><tr><td>uint256</td><td>WAD</td><td>Private constant, <code>10**18</code></td></tr><tr><td>uint256</td><td>RAY</td><td>Private constant, <code>10**27</code></td></tr></tbody></table>

## **Sections**

[#read-functions](#read-functions "mention")

* [#ema](#ema "mention") - Calculates the current EMA (exponential moving average).
* [#juniorproportion](#juniorproportion "mention") - Calculates proportion of yield attributable to junior tranche.
* [#seniorproportion](#seniorproportion "mention") - Calculates proportion of yield distributble which is attributable to the senior tranche.
* [#seniorproportionbase](#seniorproportionbase "mention") - Calculates proportion of yield attributed to senior tranche (no extenuating circumstances).
* [#seniorproportionshortfall](#seniorproportionshortfall "mention") - Calculates proportion of yield attributed to senior tranche (shortfall occurence).
* [#yieldtarget](#yieldtarget "mention") - Calculates amount of annual yield required to meet target rate for both tranches.

## Read Functions

#### `ema()`

Calculates the current EMA (exponential moving average).

```solidity
function ema(
    uint256 bV, 
    uint256 cV, 
    uint256 N
) external pure returns (uint256 eV);
```

<table><thead><tr><th width="143.33333333333331">Type</th><th width="120">Name</th><th>Description</th></tr></thead><tbody><tr><td>uint256</td><td>bV</td><td>The base value (typically an EMA from prior calculations).</td></tr><tr><td>uint256</td><td>cV</td><td>The current value, which is factored into bV.</td></tr><tr><td>uint256</td><td>N</td><td>Number of steps to average over.</td></tr></tbody></table>

*Returns*

<table><thead><tr><th width="148.33333333333331">Type</th><th width="121">Name</th><th>Description</th></tr></thead><tbody><tr><td>uint256</td><td>eV</td><td>EMA-based value given prior and current conditions.</td></tr></tbody></table>

#### `juniorProportion()`

Calculates proportion of yield attributable to junior tranche.

```solidity
function juniorProportion(
    uint256 eSTT,
    uint256 eJTT, 
    uint256 sP,
    uint256 Q
) external pure returns (uint256 jP);
```

<table><thead><tr><th width="143.33333333333331">Type</th><th width="120">Name</th><th>Description</th></tr></thead><tbody><tr><td>uint256</td><td>eSTT</td><td>ema-based supply of zSTT (units = WEI)</td></tr><tr><td>uint256</td><td>eJTT</td><td>ema-based supply of zJTT (units = WEI)</td></tr><tr><td>uint256</td><td>sP</td><td>Proportion of yield attributable to seniors (units = RAY)</td></tr><tr><td>uint256</td><td>Q</td><td>senior to junior tranche target ratio (units = BIPS)</td></tr></tbody></table>

*Returns*

<table><thead><tr><th width="148.33333333333331">Type</th><th width="121">Name</th><th>Description</th></tr></thead><tbody><tr><td>uint256</td><td>jP</td><td>Yield attributable to junior tranche in RAY.</td></tr></tbody></table>

#### `seniorProportion()`

Calculates proportion of yield distributable which is attributable to the senior tranche.

```solidity
function seniorProportion(
    uint256 yD,
    uint256 yT,
    uint256 eSTT, 
    uint256 eJTT, 
    uint256 Y, 
    uint256 Q, 
    uint256 T
) external pure returns (uint256 sP);
```

<table><thead><tr><th width="143.33333333333331">Type</th><th width="120">Name</th><th>Description</th></tr></thead><tbody><tr><td>uint256</td><td>yD</td><td>yield distributable (units = WEI)</td></tr><tr><td>uint256</td><td>yT</td><td>ema-based yield target (units = WEI)</td></tr><tr><td>uint256</td><td>eSTT</td><td>ema-based supply of zSTT (units = WEI)</td></tr><tr><td>uint256</td><td>eJTT</td><td>ema-based supply of zJTT (units = WEI)</td></tr><tr><td>uint256</td><td>Y</td><td>target annual yield for senior tranche (units = BIPS)</td></tr><tr><td>uint256</td><td>Q</td><td>multiple of Y (units = BIPS)</td></tr><tr><td>uint256</td><td>T</td><td># of days between distributions (units = integer)</td></tr></tbody></table>

*Returns*

<table><thead><tr><th width="148.33333333333331">Type</th><th width="121">Name</th><th>Description</th></tr></thead><tbody><tr><td>uint256</td><td>sP</td><td>Proportion of yD attributable to senior tranche.</td></tr></tbody></table>

#### `seniorProportionBase()`

Calculates proportion of yield attributed to senior tranche (no extenuating circumstances).

```solidity
function seniorProportionBase(
    uint256 yD, 
    uint256 eSTT, 
    uint256 Y, 
    uint256 T
) public pure returns (uint256 sPB);
```

<table><thead><tr><th width="143.33333333333331">Type</th><th width="120">Name</th><th>Description</th></tr></thead><tbody><tr><td>uint256</td><td>yD</td><td>yield distributable (units = WEI)</td></tr><tr><td>uint256</td><td>eSTT</td><td>ema-based supply of zSTT (units = WEI)</td></tr><tr><td>uint256</td><td>Y</td><td>target annual yield for senior tranche (units = BIPS)</td></tr><tr><td>uint256</td><td>T</td><td># of days between distributions (units = integer)</td></tr></tbody></table>

*Returns*

<table><thead><tr><th width="148.33333333333331">Type</th><th width="121">Name</th><th>Description</th></tr></thead><tbody><tr><td>uint256</td><td>sPB</td><td>Proportion of yield attributed to senior tranche in RAY.</td></tr></tbody></table>

#### `seniorProportionShortfall()`

Calculates proportion of yield attributed to senior tranche (shortfall occurence).

```solidity
function seniorProportionShortfall(
    uint256 eSTT, 
    uint256 eJTT, 
    uint256 Q
) public pure returns (uint256 sPS);
```

<table><thead><tr><th width="143.33333333333331">Type</th><th width="120">Name</th><th>Description</th></tr></thead><tbody><tr><td>uint256</td><td>eSTT</td><td>ema-based supply of zSTT (units = WEI)</td></tr><tr><td>uint256</td><td>eJTT</td><td>ema-based supply of zJTT (units = WEI)</td></tr><tr><td>uint256</td><td>Q</td><td>multiple of Y (units = BIPS)</td></tr></tbody></table>

*Returns*

<table><thead><tr><th width="148.33333333333331">Type</th><th width="121">Name</th><th>Description</th></tr></thead><tbody><tr><td>uint256</td><td>sPS</td><td>Proportion of yield attributed to senior tranche in RAY.</td></tr></tbody></table>

#### `yieldTarget()`

Calculates amount of annual yield required to meet target rate for both tranches.

```solidity
function yieldTarget(
    uint256 eSTT,
    uint256 eJTT, 
    uint256 Y, 
    uint256 Q, 
    uint256 T
) public pure returns (uint256 yT);
```

<table><thead><tr><th width="143.33333333333331">Type</th><th width="120">Name</th><th>Description</th></tr></thead><tbody><tr><td>uint256</td><td>eSTT</td><td>ema-based supply of zSTT (units = WEI)</td></tr><tr><td>uint256</td><td>eJTT</td><td>ema-based supply of zJTT (units = WEI)</td></tr><tr><td>uint256</td><td>Y</td><td>target annual yield for senior tranche (units = BIPS)</td></tr><tr><td>uint256</td><td>Q</td><td>multiple of Y (units = BIPS)</td></tr><tr><td>uint256</td><td>T</td><td># of days between distributions (units = integer)</td></tr></tbody></table>

*Returns*

<table><thead><tr><th width="148.33333333333331">Type</th><th width="121">Name</th><th>Description</th></tr></thead><tbody><tr><td>uint256</td><td>yT</td><td>yield target for the senior and junior tranche combined.</td></tr></tbody></table>