ETKLib

Library with different datatypes and utils used by the eToken contract

Types

Scale

ScaledAmount

struct ScaledAmount {
  uint128 amount;
  ETKLib.Scale scale;
  uint32 lastUpdate;
}

Scr

struct Scr {
  uint128 scr;
  uint128 interestRate;
}

Variables

WAD

uint256 WAD

SWAD

int256 SWAD

Errors

ScaleTooSmall

error ScaleTooSmall(uint256 rejectedScale)

Private Functions

_mulDiv

function _mulDiv(uint256 a, uint256 b, uint256 c) internal pure returns (uint256)

unchecked version of Math.mulDiv that returns the result of a * b / c.

Assumes a * b < 2**256

_mulDiv

function _mulDiv(int256 a, int256 b, int256 c) internal pure returns (int256)

unchecked version of Math.mulDiv that returns the result of a * b / c. (signed version)

Assumes a * b < 2**256

_mulDivCeil

function _mulDivCeil(uint256 a, uint256 b, uint256 c) internal pure returns (uint256)

unchecked version of Math.mulDiv that returns the result of a * b / c, rounding up when there is non-zero remainder.

Assumes a * b < 2**256

toCurrent

function toCurrent(ETKLib.Scale scale, uint256 scaledAmount) internal pure returns (uint256)

Converts a "scaled amount" (raw value, without applying earnings) to the current value after after applying the scale.

Parameters

Name	Type	Description
scale	ETKLib.Scale	The scale to apply.
scaledAmount	uint256	The `scaled amount` as the ones stored in `$._balances`

Return Values

Name	Type	Description
[0]	uint256	The current amount, that results of `scaledAmount * scale`

toCurrentCeil

function toCurrentCeil(ETKLib.Scale scale, uint256 scaledAmount) internal pure returns (uint256)

Converts a "scaled amount" (raw value, without applying earnings) to the current value after after applying the scale, rounding to the ceil

Parameters

Name	Type	Description
scale	ETKLib.Scale	The scale to apply.
scaledAmount	uint256	The `scaled amount` as the ones stored in `$._balances`

Return Values

Name	Type	Description
[0]	uint256	The current amount, that results of `scaledAmount * scale`

toScaled

function toScaled(ETKLib.Scale scale, uint256 currentAmount) internal pure returns (uint256)

Converts a "current amount" (user-facing value, after applying earnings/scale) into a scaled amount (raw value).

Un-applies the scale (in WAD): scaled = currentAmount * WAD / scale.

Parameters

Name	Type	Description
scale	ETKLib.Scale	The scale (WAD) to un-apply.
currentAmount	uint256	The current amount as obtained from balanceOf() or totalSupply().

Return Values

Name	Type	Description
[0]	uint256	scaledAmount The scaled amount (raw value).

toScaledCeil

function toScaledCeil(ETKLib.Scale scale, uint256 currentAmount) internal pure returns (uint256)

Same as {toScaled}, but rounds up when there is a non-zero remainder.

scaled = ceil(currentAmount * WAD / scale).

Parameters

Name	Type	Description
scale	ETKLib.Scale	The scale (WAD) to un-apply.
currentAmount	uint256	The current amount as obtained from balanceOf() or totalSupply().

Return Values

Name	Type	Description
[0]	uint256	scaledAmount The scaled amount (raw value), rounded up.

grow

function grow(ETKLib.Scale scale, uint256 factor) internal pure returns (ETKLib.Scale newScale)

Returns a newScale = scale * (1 + factor)

Parameters

Name	Type	Description
scale	ETKLib.Scale	The base scale.
factor	uint256	The multiplicative increment, in WAD.

Return Values

Name	Type	Description
newScale	ETKLib.Scale	The updated scale.

add

function add(ETKLib.Scale scale, uint256 factor) internal pure returns (ETKLib.Scale newScale)

Returns a newScale = scale + factor.

Parameters

Name	Type	Description
scale	ETKLib.Scale	The base scale.
factor	uint256	The additive increment (same units as `scale`).

Return Values

Name	Type	Description
newScale	ETKLib.Scale	The updated scale.

add

function add(ETKLib.Scale scale, int256 factor) internal pure returns (ETKLib.Scale newScale)

Returns a newScale = scale + factor, allowing it to increase or decrease. Reverts if the resulting scale would be below MIN_SCALE.

Parameters

Name	Type	Description
scale	ETKLib.Scale	The base scale.
factor	int256	The signed additive increment (same units as `scale`).

Return Values

Name	Type	Description
newScale	ETKLib.Scale	The updated scale.

toUint256

function toUint256(ETKLib.Scale scale) internal pure returns (uint256)

Unwraps {Scale} into uint256.

projectScale

function projectScale(struct ETKLib.ScaledAmount scaledAmount, uint256 interestRate) internal view returns (ETKLib.Scale)

Computes the scale of the scaledAmount projecting the last recorded value to the future asumming linear rate

projectScale

function projectScale(struct ETKLib.ScaledAmount scaledAmount, struct ETKLib.Scr scr) internal view returns (ETKLib.Scale ret)

Computes the scale of the scaledAmount projecting the last recorded value to the future asumming linear rate

init

function init(struct ETKLib.ScaledAmount scaledAmount) internal

_add

function _add(struct ETKLib.ScaledAmount scaledAmount, uint256 amount, ETKLib.Scale scale) internal view returns (struct ETKLib.ScaledAmount newScaledAmount, uint256 scaledAdd)

Internal helper to add amount (current units) to a {ScaledAmount} using a given scale.

Return Values

Name	Type	Description
newScaledAmount	struct ETKLib.ScaledAmount	Updated in-memory struct (caller is expected to store it).
scaledAdd	uint256	Amount converted to scaled units (rounded down).

Pre-conditions

uint256(scale) != 0
uint256(scaledAmount.amount) + scale.toScaled(amount) fits in uint128

_sub

function _sub(struct ETKLib.ScaledAmount scaledAmount, uint256 amount, ETKLib.Scale scale) internal view returns (struct ETKLib.ScaledAmount newScaledAmount, uint256 scaledSub)

Subtracts amount (current units) from a {ScaledAmount} using the provided scale.

It uses toScaledCeil (round up) to avoid leaving dust due to rounding. If the ceil conversion would underflow by 1 unit, it retries with toScaled (round down).

Parameters

Name	Type	Description
scaledAmount	struct ETKLib.ScaledAmount	The storage record to update.
amount	uint256	Amount expressed in current units.
scale	ETKLib.Scale	Scale (wad) to use to convert `amount` into scaled units.

Return Values

Name	Type	Description
newScaledAmount	struct ETKLib.ScaledAmount	Updated in-memory struct (caller is expected to store it).
scaledSub	uint256	The subtracted value expressed in scaled units (ceil, or floor in the retry path).

Pre-conditions

uint256(scale) != 0
scale.toScaledCeil(amount) <= scaledAmount.amount OR scale.toScaled(amount) <= scaledAmount.amount

add

function add(struct ETKLib.ScaledAmount scaledAmount, uint256 amount, uint256 interestRate) internal view returns (struct ETKLib.ScaledAmount newScaledAmount, uint256 scaledAdd)

Adds amount (current units) projecting the scale forward using a linear interestRate.

sub

function sub(struct ETKLib.ScaledAmount scaledAmount, uint256 amount, uint256 interestRate) internal view returns (struct ETKLib.ScaledAmount newScaledAmount, uint256 scaledSub)

Subtracts amount (current units) projecting the scale forward using a linear interestRate.

add

function add(struct ETKLib.ScaledAmount scaledAmount, uint256 amount, struct ETKLib.Scr scr) internal view returns (struct ETKLib.ScaledAmount newScaledAmount, uint256 scaledAdd)

Adds amount (current units) projecting the scale forward using SCR earnings.

sub

function sub(struct ETKLib.ScaledAmount scaledAmount, uint256 amount, struct ETKLib.Scr scr) internal view returns (struct ETKLib.ScaledAmount newScaledAmount, uint256 scaledSub)

Subtracts amount (current units) projecting the scale forward using SCR earnings.

discreteChange

function discreteChange(struct ETKLib.ScaledAmount scaledAmount, int256 amount, struct ETKLib.Scr scr) internal view returns (struct ETKLib.ScaledAmount newScaledAmount)

Applies a discrete signed change (in current units) to the scale, and also accounts for SCR earnings accrued since scaledAmount.lastUpdate.

Parameters

Name	Type	Description
scaledAmount	struct ETKLib.ScaledAmount
amount	int256	Signed discrete change in current units.
scr	struct ETKLib.Scr

Return Values

Name	Type	Description
newScaledAmount	struct ETKLib.ScaledAmount	Updated in-memory struct with the same stored `amount`, but an adjusted `scale`.

Pre-conditions

scaledAmount.amount != 0 (required to compute proportional scale change)

minValue

function minValue(struct ETKLib.ScaledAmount scaledAmount) internal view returns (uint256)

Returns the minimum current value representable by scaledAmount.amount under the minimum scale.

add

function add(struct ETKLib.Scr scr, uint256 scrAmount_, uint256 policyInterestRate) internal view returns (struct ETKLib.Scr modifiedScr)

Adds SCR and updates the weighted-average interestRate.

Parameters

Name	Type	Description
scr	struct ETKLib.Scr
scrAmount_	uint256	Amount of SCR to add.
policyInterestRate	uint256	Annualized rate (wad) associated with `scrAmount_`.

Return Values

Name	Type	Description
modifiedScr	struct ETKLib.Scr	New in-memory SCR struct reflecting the addition.

Pre-conditions

If scr.scr != 0, then uint256(scr.scr) + scrAmount_ fits in uint256
policyInterestRate is expressed in wad

sub

function sub(struct ETKLib.Scr scr, uint256 scrAmount_, uint256 policyInterestRate) internal view returns (struct ETKLib.Scr modifiedScr)

Subtracts SCR and updates the weighted-average interestRate.

Parameters

Name	Type	Description
scr	struct ETKLib.Scr
scrAmount_	uint256	Amount of SCR to remove.
policyInterestRate	uint256	Annualized rate (wad) associated with `scrAmount_`.

Return Values

Name	Type	Description
modifiedScr	struct ETKLib.Scr	New in-memory SCR struct reflecting the subtraction.

Pre-conditions

scrAmount_ <= scr.scr

earnings

function earnings(struct ETKLib.Scr scr, uint32 since) internal view returns (uint256)

Returns the earnings of the SCR since a given date

fundsAvailable

function fundsAvailable(struct ETKLib.Scr scr, uint256 totalSupply) internal view returns (uint256)

Returns liquid funds available given totalSupply, excluding locked SCR.

Parameters

Name	Type	Description
scr	struct ETKLib.Scr
totalSupply	uint256	Total supply expressed in current units.

Return Values

Name	Type	Description
[0]	uint256	available `max(totalSupply - scr.scr, 0)`.

scrAmount

function scrAmount(struct ETKLib.Scr scr) internal view returns (uint256)

Returns the SCR amount (locked capital) in current units.