Protocol Math

Eco DeFi protocol contracts use a system of exponential math, Exponential.sol in order to represent fractional quantities with sufficient precision.

Most numbers are represented as a mantissa, an unsigned integer scaled by 1 * 10 ^ 18, in order to perform basic math at a high level of precision.

eToken and Underlying Decimals

Prices and exchange rates are scaled by the decimals unique to each asset; eTokens are BEP-20 tokens with 8 decimals, while their underlying tokens vary, and have a public member named decimals.

eToken	eToken Decimals	Underlying	Underlying Decimals
eUSDT	8	USDT	18
eUSDC	8	USDC	18
eBUSD	8	BUSD	18
eVAI	8	VAI	18
eETH	8	ETH	18
eBTC	8	BTC	18
eWBNB	8	WBNB	18
eZIL	8	ZIL	12
eBABY	8	BABY	18
eWING	8	WING	9
eONT	8	ONT	18
eONG	8	ONG	9

Interpreting Exchange Rates

The eToken Exchange Rate is scaled by the difference in decimals between the eToken and the underlying asset.

oneETokenInUnderlying = exchangeRateCurrent / (1 * 10 \^ (18 +
underlyingDecimals - eTokenDecimals))

Here is an example of finding the value of 1 cBAT in BAT with Web3.js JavaScript.

const eTokenDecimals = 8; // all eTokens have 8 decimal places
const underlying = new web3.eth.Contract(erc20Abi, batAddress);
const eToken = new web3.eth.Contract(eTokenAbi, cBatAddress);
const underlyingDecimals = await underlying.methods.decimals().call();
const exchangeRateCurrent = await eToken.methods.exchangeRateCurrent().call();
const mantissa = 18 + parseInt(underlyingDecimals) - eTokenDecimals;
const oneETokenInUnderlying = exchangeRateCurrent / Math.pow(10, mantissa);
console.log('1 cBAT can be redeemed for', oneETokenInUnderlying, 'BAT');

There is no underlying contract for BNB, so to do this with eBNB, set underlying Decimals to 18. To find the number of underlying tokens that can be redeemed for eTokens, multiply the number of eTokens by the above value oneETokenInUnderlying.

underlyingTokens = eTokenAmount * oneETokenInUnderlying

Calculating Accrued Interest

Interest rates for each market is updated in each block where the ratio of borrowed assets to supplied assets in the market has changed. The total interest rates are changing depending on the interest rate model being implemented in smart contract, and the amount of change in the ratio of borrowed assets to supplied assets in the market.

See the interest rate data visualization notebook on Observable to visualize which interest rate model is currently applied to each market.

Historical interest rates can be retrieved from the MarketHistoryService API

Interest accrues to all suppliers and borrowers in a market when any BNB address interacts with the market’s eToken contract, calling one of these functions: mint, redeem, borrow, or repay. Successful execution of one of these functions triggers the accrue Interest method, which causes interest to be added to the underlying balance of every supplier and borrower in the market. Interest accrues for the current block, as well as each prior block in which the accrue Interest method was not triggered (no user interacted with the eToken contract). Interest accrues for the current block, as well as each prior block in which the accrue Interest method invoked.

Here is an example of supply interest accrual:

Alice supplies 1 BNB to the Eco DeFi protocol. At the time of supply, the supply Rate Per Block is 37893605 Wei, or 0.000000000037893605 BNB per block. No one interacts with the BSC contract for 3 BNB blocks. On the subsequent 4th block, Bob borrows some BNB. Alice’s underlying balance is now 1.000000000151574420 BNB (which is 37893605 Wei times 4 blocks, plus the original 1 BNB). Alice’s underlying BNB balance in subsequent blocks will have interest accrued based on the new value of 1.000000000151574420 BNB instead of the initial 1 BNB. Note that the supply Rate Per Block value may change at any time.

Calculating the APY Using Rate Per Block

The Annual Percentage Yield (APY) for supplying or borrowing in each market can be calculated using the value of supply Rate Per Block (for supply APY) or borrow Rate Per Block (for borrow APY) in this formula:

Rate = eToken.supplyRatePerBlock(); // Integer
Rate = 37893566
BNB Mantissa = 1 * 10 ^ 18 (BNB has 18 decimal places)
Blocks Per Day = 6570 (13.15 seconds per block)
Days Per Year = 365

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

Here is an example of calculating the supply and borrow APY with Web3.js JavaScript:

const BNBMantissa = 1e18;
const blocksPerDay = 6570; // 13.15 seconds per block
const daysPerYear = 365;

const eToken = new web3.eth.Contract(eBNBAbi, eBNBAddress);
const supplyRatePerBlock = await eToken.methods.supplyRatePerBlock().call();
const borrowRatePerBlock = await eToken.methods.borrowRatePerBlock().call();
const supplyApy = (((Math.pow((supplyRatePerBlock / BNBMantissa * blocksPerDay) + 1, daysPerYear))) - 1) * 100;
const borrowApy = (((Math.pow((borrowRatePerBlock / BNBMantissa * blocksPerDay) + 1, daysPerYear))) - 1) * 100;
console.log(`Supply APY for BNB ${supplyApy} %`);
console.log(`Borrow APY for BNB ${borrowApy} %`);