Shares

Shares

Typedef on uint256 to represent user shares in vault contracts. Allows type checking to prevent errors where shares and collateral intermix

PerShare

User-defined type: an X-per-share rate (really a FPUnsigned). Because Shares values are multiples of 1E18 on top of however many decimals the collateral token has, "seconds per share" is a very small number. To avoid precision loss, we store them inverted (shares per second) and expose methods that allow us to treat this as the sensible quantity of seconds per share.

isLessThanOrEqual

Whether a is less than or equal to b.

function isLessThanOrEqual(Shares a, Shares b) internal pure returns (bool)

Return Values

Name	Type	Description
[0]	bool	True if a <= b, or False if not.

isLessThan

Whether a is less than b.

function isLessThan(Shares a, Shares b) internal pure returns (bool)

isGreaterThanOrEqual

Whether a is greater than or equal to b.

function isGreaterThanOrEqual(Shares a, Shares b) internal pure returns (bool)

isGreaterThan

Whether a is greater than b.

function isGreaterThan(Shares a, Shares b) internal pure returns (bool)

isEqualTo

Whether a is equal to b.

function isEqualTo(Shares a, Shares b) internal pure returns (bool)

minus

Difference between a and b shares. Reverts if b > a

function minus(Shares a, Shares b) internal pure returns (Shares)

plus

Sum of a and b shares.

function plus(Shares a, Shares b) internal pure returns (Shares)

div

Ratio of a and b shares

function div(Shares a, Shares b) internal pure returns (FPUnsigned)

Return Values

Name	Type	Description
[0]	FPUnsigned	FPUnsigned ratio of $\frac{a}{b}$. This is not a Shares quantity

divScale

a shares divided by uint b

function divScale(Shares a, uint256 b) internal pure returns (Shares)

Return Values

Name	Type	Description
[0]	Shares	Shares a/b

mul

Shares a times some scaling factor b

function mul(Shares a, FPUnsigned b) internal pure returns (Shares product)

Parameters

Name	Type	Description
a	Shares	Shares quantity
b	FPUnsigned	FPUnsigned factor

Return Values

Name	Type	Description
product	Shares	product of a*b

SharesLib

Addresses

Chain	Address

Functions

rate

Ratio of a per b shares

function rate(uint256 a, Shares b) internal pure returns (PerShare rate_)

Return Values

Name	Type	Description
rate_	PerShare	$\frac{a}{b}$ (represented as $\frac{b}{a}$)

rateMul

Multiply a PerShare rate by a Shares to obtain a FPUnsigned numerator

function rateMul(PerShare a, Shares b) internal pure returns (FPUnsigned qty)

Parameters

Name	Type	Description
a	PerShare	a PerShares rate
b	Shares	a number of shares

Return Values

Name	Type	Description
qty	FPUnsigned	a * b; numerator units of a

divRate

Divide a FPUnsigned numerator by a PerShare rate to obtain a Shares quantity

function divRate(PerShare a, uint256 b) internal pure returns (Shares shares)

Parameters

Name	Type	Description
a	PerShare	a PerShares rate
b	uint256	a quantity (same units as a's numerator)

Return Values

Name	Type	Description
shares	Shares	b / a

Errors

ZeroRateDiv

x / rate is undefined for rates of 0

error ZeroRateDiv(uint256 b)

perShareEq

Whether a is equal to b.

function perShareEq(PerShare a, PerShare b) internal pure returns (bool)

perShareNeq

Whether a is not equal to b.

function perShareNeq(PerShare a, PerShare b) internal pure returns (bool)

perShareAdd

Add two PerShare rates.

function perShareAdd(PerShare a, PerShare b) internal pure returns (PerShare)

Dev note

Possible precision loss here, because we must invert the stored ratios in order to add them and the intermediate $\frac{a}{b}$ values may be small:

$\cfrac{1}{\cfrac{1}{\frac{b_1}{a_1}} + \cfrac{1}{\frac{b_2}{a_2}}}$

However, this method is only called when a user lets two requests expire in a row, so it's better than incurring precision loss from small $\frac{a}{b}$ ratios every time we create or apply a penalty rate.