Protocol Math

Overview

The contracts under the Ionise protocol system uses exponential mathematics to represent fractional quantities with high precision. This logic exists in the Exponential.sol contract.

Most numbers in this system are represented by a mantissa, an unsigned integer scaled by a factor of 1 * 10^18. This scaling ensures basic mathematical operations can be performed with a high degree of accuracy.

iToken and Underlying Decimals

Prices and exchange rates are adjusted according to the unique decimal scaling of each asset. iTokens, which are ERC-20 tokens, are scaled with 8 decimal places. However, their underlying tokens may have different decimal scaling, which is indicated by a public member called 'decimals'.

For further details, please refer to the respective token contract addresses.

Deployed Contracts

Interpreting Exchange Rates

Each iToken is convertible into an ever increasing quantity of the underlying asset, as interest accrues in the market. The exchange rate between an iToken and the underlying asset is equal to:

// Formula
exchangeRate = (getCash() + totalBorrows() - totalReserves()) / totalSupply()

As ZIL lacks an underlying contract, you must set the 'underlyingDecimals' to 18 when dealing with iZIL.

Calculating Accrued Interest

Interest rates for each market are updated in any block where there is a change in the ratio of borrowed assets to supplied assets. The magnitude of this change in interest rates depends on the interest rate model smart contract in place for the market, and the degree of change in the aforementioned ratio.

The accrual of interest to suppliers and borrowers in a market occurs when any ZIL EVM address interacts with the market's iToken contract. This interaction could be any of the following functions: mint, redeem, borrow, repay or repayBorrow. A successful execution of any of these functions triggers the accrueInterest method, leading to the addition of interest to the underlying balance of every supplier and borrower in the market. Interest accrues for the current block, as well as any previous blocks where the accrueInterest method was not triggered due to lack of interaction with the iToken contract. Interest only accumulates during blocks where one of the aforementioned methods is invoked on the iToken contract.

Let's consider an example of supply interest accrual: Alice supplies 1 ZIL to the Ionise protocol. At the time of her supply, the supplyRatePerBlock is 37893605 Wei, which equates to 0.000000000037893605 ZIL per block. For 3 blocks, no interactions occur with the iZIL contract. On the subsequent 4th block, Bob borrows some ZIL. As a result, Alice’s underlying balance is updated to 1.000000000151574420 ZIL (calculated by multiplying 37893605 Wei by 4 blocks and adding the original 1 ZIL). From this point onwards, the accrued interest on Alice’s underlying ZIL balance will be based on the updated value of 1.000000000151574420 ZIL, rather than the initial 1 ZIL. It is important to note that the supplyRatePerBlock value may alter at any given time.

Calculating the APY Using Rate Per Block

The Annual Percentage Yield (APY) for either supplying or borrowing in each market can be computed using the 'supplyRatePerBlock' (for Supply APY) or 'borrowRatePerBlock' (for Borrow APY) values. These rates can be used in the following formula:

// Rate = iToken.supplyRatePerBlock(); // Integer
Rate = 37893566
ZIL Mantissa = 1 * 10 ^ 18 (ZIL has 18 decimal places)
Blocks Per Day = 20 * 60 * 24 (based on 20 blocks occurring every minute)
Days Per Year = 365

APY = ((((Rate / ZIL Mantissa * Blocks Per Day + 1) ^ Days Per Year - 1)) - 1) * 100