Protocol Math

Understanding the mathematical foundations of the CapyFi protocol, including interest calculations, exchange rates, and APY formulas.

Exponential Math

High-precision calculations

The CapyFi protocol contracts use a system of exponential math, ExponentialNoError.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.

Exchange Rate Calculations

How caToken exchange rates work

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

oneCaTokenInUnderlying = exchangeRateCurrent / (1 * 10 ^ (18 + underlyingDecimals - caTokenDecimals))

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

const caTokenDecimals = 8; // all caTokens have 8 decimal places
const underlying = new web3.eth.Contract(erc20Abi, batAddress);
const caToken = new web3.eth.Contract(caTokenAbi, caBatAddress);
const underlyingDecimals = await underlying.methods.decimals().call();
const exchangeRateCurrent = await caToken.methods.exchangeRateCurrent().call();
const mantissa = 18 + parseInt(underlyingDecimals) - caTokenDecimals;
const oneCaTokenInUnderlying = exchangeRateCurrent / Math.pow(10, mantissa);
console.log('1 caBAT can be redeemed for', oneCaTokenInUnderlying, 'BAT');

Interest Accrual

How interest is calculated and distributed

Interest rates for each market update on any block in which the ratio of borrowed assets to supplied assets in the market has changed. The amount interest rates are changed depends on the interest rate model smart contract implemented for the market.

Interest accrues to all suppliers and borrowers in a market when any Ethereum address interacts with the market's caToken contract, calling one of these functions: mint, redeem, borrow, or repay.

Example: Interest Accrual

Alice supplies 1 ETH to the CapyFi protocol. At the time of supply, the supplyRatePerBlock is 37893605 Wei, or 0.000000000037893605 ETH per block. No one interacts with the caEther contract for 3 Ethereum blocks. On the subsequent 4th block, Bob borrows some ETH. Alice's underlying balance is now 1.000000000151574420 ETH (which is 37893605 Wei times 4 blocks, plus the original 1 ETH).

APY Calculations

Calculating Annual Percentage Yield

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

Rate = caToken.supplyRatePerBlock(); // Integer
Rate = 37893566
ETH Mantissa = 1 * 10 ^ 18 (ETH has 18 decimal places)
Blocks Per Day = 7200 (12 seconds per block)
Days Per Year = 365

APY = ((((Rate / ETH 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 ethMantissa = 1e18;
const blocksPerDay = 7200; // 12 seconds per block
const daysPerYear = 365;

const caToken = new web3.eth.Contract(caEthAbi, caEthAddress);
const supplyRatePerBlock = await caToken.methods.supplyRatePerBlock().call();
const borrowRatePerBlock = await caToken.methods.borrowRatePerBlock().call();
const supplyApy = (((Math.pow((supplyRatePerBlock / ethMantissa * blocksPerDay) + 1, daysPerYear))) - 1) * 100;
const borrowApy = (((Math.pow((borrowRatePerBlock / ethMantissa * blocksPerDay) + 1, daysPerYear))) - 1) * 100;
console.log(`Supply APY for ETH ${supplyApy} %`);
console.log(`Borrow APY for ETH ${borrowApy} %`);

APR Calculations

Calculating Annual Percentage Rate

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

const ethMantissa = 1e18;
const blocksPerYear = 5 * 60 * 24 * 365; // 12 seconds per block
const daysPerYear = 365;

const caToken = new web3.eth.Contract(caZrxAbi, caZrxAddress);
const supplyRatePerBlock = await caToken.methods.supplyRatePerBlock().call();
const borrowRatePerBlock = await caToken.methods.borrowRatePerBlock().call();
const supplyApr = supplyRatePerBlock / ethMantissa * blocksPerYear * 100;
const borrowApr = borrowRatePerBlock / ethMantissa * blocksPerYear * 100;
console.log(`Supply APR ${(supplyApr).toFixed(3)} %`);
console.log(`Borrow APR ${(borrowApr).toFixed(3)} %`);

Interest Rate Models

How interest rates are determined

Interest rates are determined by interest rate models that adjust rates based on the utilization rate of each market. The utilization rate is the ratio of borrowed assets to supplied assets.

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

Key Concepts:

Utilization Rate = Total Borrows / Total Supply
Higher utilization leads to higher interest rates
Interest rate models are set by protocol administrators
Rates update on every block with activity