🏁 Getting Start

Welnance Lending

The Welnance Lending is an unprecedented technological advancement in the history of finance: one can borrow money and earn interest with no humans, governments, or credit involved.

Rates vary frequently, though, and it is important to understand how the protocol determines interest rates.

Networks

The Welnance Protocol is currently deployed on the following networks:

wlBNB - Contract Address: 0x38e22c429e62530cbB59B90bF14a71346C727752

wlWEL - Contract Address: 0x723dCA315dCEAEf99510E0BA4947335eCb8d7ED6

wlBTC - Contract Address: 0xaDBBcad6D68A5714c2e49C5b8CBdd999A7F39762

wlUSDT - Contract Address: 0x781d0d50AE3683322090C54C25858bF76Ec9f922

wlETH - Contract Address: 0x3e18d5d225C2525aD9A7c83681258baA2B32ad39

wlUSCD - Contract Address: 0xd11c5b89fDEC48a13CaaA2c99430c02Ca01C7D8a

wlLINK - Contract Address: 0x8Fd3d759A445A42a093ce42A52FC57BB91BB392a

wlBUSD - Contract Address: 0xbDb0EbEB95cE3Bb6042b79737A274aB513442f94

wlXRP- Contract Address: 0x4c1Ab2Afa88a20F48cAB1cAe5AcCf7A626919411

wlDOT - Contract Address: 0xFeA4c8A3A46AB33E30c96F5e94DF66D1aEc7e213

wlDAI - Contract Address: 0xAc7fD7475188f59eb4Ab7D88Ce64b8Beee6eb1AB

wlADA - Contract Address: 0x028383b3D5e86fbf36Ea995B96E503925C177A4E

wlMATIC - Contract Address: 0xe1d02e15Eb236Dd28DB1fe2b7Fc9d5DD20e2Edf1

wlLTC - Contract Address: 0xE2E6f3F3CcC2B5B87C8028Ce9CdE94Caf9d81823

wlTRX - Contract Address: 0xb281962fE7fB145Df22A9110990abD599997D647

wlBCH - Contract Address: 0x0eCa218D6b9E84DF489C037522567E46E06987cF

Protocol Math

The Welnance 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.

wlToken and Underlying Decimals

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

wlToken	wlToken Decimals	Underlying	Underlying Decimals
wlBNB	8	BNB	18
wlWEL	8	WEL	18
wlBTC	8	BTC	18
wlUSDT	8	USDT	18
wlETH	8	ETH	18
wlUSCD	8	USCD	18
wlLINK	8	LINK	18
wlBUSD	8	BUSD	18
wlXRP	8	XRP	18
wlDOT	8	DOT	18
wlDAI	8	DAI	18
wlADA	8	ADA	18
wlMATIC	8	MATIC	18
wlLTC	8	LTC	18
wlTRX	8	TRX	18
wlBCH	8	BCH	18

Interpreting Exchange Rates

The wlToken Exchange Rates is scaled by the difference in decimals between the vToken and the underlying asset.

onevTokenInUnderlying = exchangeRateCurrent / (1  *  10  ^  (18  + underlyingDecimals - wlTokenDecimals)

Here is an example of finding the value of 1 wlUSDT in USDT with Web3.js JavaScript.

const wlTokenDecimals = 8; // all wlTokens have 8 decimal places
const underlying = new web3.eth.Contract(bep20Abi, usdtAddress);
const wlToken = new web3.eth.Contract(vTokenAbi, wlUSDTAddress);
const underlyingDecimals = await underlying.methods.decimals().call();
const exchangeRateCurrent = await wlToken.methods.exchangeRateCurrent().call();
const mantissa = 18 + parseInt(underlyingDecimals) - wlTokenDecimals;
const onevTokenInUnderlying = exchangeRateCurrent / Math.pow(10, mantissa);
console.log('1 wlUSDT can be redeemed for', onewlTokenInUnderlying, 'USDT');

There is no underlying contract for BNB, so to do this with wlBNB, set underlyingDecimals to 18. To find the number of underlying tokens that can be redeemed for wlTokens, divide the number of wlTokens by the above value onewlTokenInUnderlying.

underlyingTokens = wlTokenAmount * onewlTokenInUnderlying

Calculating Accrued Interest

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, 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.

Interest accrues to all suppliers and borrowers in a market when any BSC address interacts with the market’s wlToken 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 accrueId nterest method was not triggered (no user interacted with the wlToken contract). Interest Welnance only during blocks in which the wlToken contract has one of the aforementioned methods invoked.

Here is an example of supply interest accrual:

Alice supplies 1 BNB to the Welnance protocol. At the time of supply, the supplyRatePerBlock is 37893605 Wei, or 0.000000000037893605 BNB per block. No one interacts with the wlBNB contract for 3 BSC 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 supplyRatePerBlock 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 supplyRatePerBlock (for supply APY) or borrowRatePerBlock (for borrow APY) in this formula:

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

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

const ethMantissa = 1e18;
2const blocksPerDay = 20 * 60 * 24;
3const daysPerYear = 365;
4
5const wlToken = new web3.eth.Contract(vBnbAbi, vBnbAddress);
6const supplyRatePerBlock = await wlToken.methods.supplyRatePerBlock().call();
7const borrowRatePerBlock = await wlToken.methods.borrowRatePerBlock().call();
8const supplyApy = (((Math.pow((supplyRatePerBlock / bnbMantissa * blocksPerDay) + 1,
9const borrowApy = (((Math.pow((borrowRatePerBlock / bnbMantissa * blocksPerDay) + 1,
10console.log(`Supply APY for BNB ${supplyApy} %`);
11console.log(`Borrow APY for BNB ${borrowApy} %`);

Understanding the utilization rate

All interest rates in Welnance are determined as a function of a metric known as the utilization rate. The utilization rate $U_a$ for a money market $a$ is defined 1 as:

$U_a = Borrows_a / (Cash_a + Borrows_a - Reserves_a)Ua​=Borrowsa​/(Casha​+Borrowsa​−Reservesa​)$

• $Borrows_a$ refers to the amount of $a$ borrowed.
• $Cash_a$ refers to the amount of $a$ left in the system.
• $Reserves_a$ refers to the amount of $a$ that Compound keeps as profit.

Intuitively speaking, this is the percentage of money borrowed out of the total money supplied.

For example: given that reserves are 0, if Alice supplies $500 USDC and Bob supplies $500 USDC, but Charles borrows $100 USDC, the total borrows is $100 and the total cash is $500+500−100=900$, so the utilization rate is $100/(900+100)=10$%.

A high ratio signifies that a lot of borrowing is taking place, so interest rates go up to get more people to inject cash into the system. A low ratio signifies that demand for borrowing is low, so interest rates go down to encourage more people to borrow cash from the system. This follows economic theory's idea of price (the "price" of money is its interest rate) relative to supply and demand.

Borrow and supply rates

Borrow and supply rates are calculated using the utilization rate and several arbitrary constants.

The supply rate is calculated as follows:

$\text{Supply Interest Rate}_a = \text{Borrowing Interest Rate}_a * U_a * (1 - \text{Reserve Factor}_a)$

where

• $U_a$ is the utilization rate of $a$
• $\text{Reserve Factor}_a$ is the percentage of the spread between the supply and borrow rates that the protocol keeps as profit2
• $\text{Borrowing Interest Rate}_aBorrowing Interest Ratea​$ is the interest rate that borrowers should pay for $a$.

The Welnance 's Standard Interest Jump Rate Model

Some markets follow what is known as the "Jump Rate" model. This model has the standard parameters:

• Base rate per year, the minimum borrowing rate

• Multiplier per year, the rate of increase in interest rate with respect to utilization

but it also introduces two new parameters:

• Kink, the point in the model in which the model follows the jump multiplier

• Jump Multiplier per year, the rate of increase in interest rate with respect to utilization after the "kink"

The borrow rate of the jump rate model is defined as follows:

$$\begin{aligned} \text{Borrow Interest Rate} &= \text{Multiplier} * min(U_a, \text{Kink}) \\ &+ \text{Jump Multiplier} * max(0, U_a - \text{Kink}) \\ &+ \text{Base Rate} \end{aligned}$$

Example: USDC rate model

The USDC rate model is a jump rate model with the following parameters:

• Base rate: 0%/yr

• Multiplier: 5%/yr

• Kink: 80%

• Jump multiplier: 52%/yr

The USDC market also has a reserve factor of 7%.

Let's say that the market has the following status:

• Total borrows: $150

• Total Supply: $289

What is the borrow rate and supply rate?

Doing the math:

$U_a = \$150/(\$150 + \$289) = 34\%$

$\text{Borrow Interest Rate} = 5\% * 80\% + 52\% * (34\% - 80\%) + 0\% = 10\% (10.24\%)$

$\text{Supply Interest Rate}_a = 10\% * 34\% * (1 - 7\%) = 3\% (3.47\%)$

Interest rate spikes

In Welnance, the interest rate is not locked at the price of borrowing: it continuously fluctuates based on changes in the utilization rate.

Another way interest rates could spike is if the Chief Economist decides that the interest rates should go up. This has already happened in the case of MakerDAO, where the stability fee has ranged between 0% and 8%. Fortunately, both Compound and MakerDAO have transparent processes when changing interest rates with beautiful governance dashboards and decisions voted on by governance token holders.

This is in stark contrast to the current quarterly speculation on the Fed/FOMC's decisions. Compound's decision-making process on the other hand is transparent and decentralized, protecting the interests of financiers (pun intended).

Predicting accrued interest

One can compute the total interest they will pay on a principal balance $PP$ for a duration in days $tt$ with the following equation:

$\text{Total Interest} = P(1 + \frac{r}{B_y})^{B_y / 365 * t}$

where

• $B_y = 2102400By​=2102400$, the number of blocks in the year, and
• $rr$ is the expected value of the APR of the interest over the given period.

The number 2,102,400 assumes 15 second blocks.

Closing thoughts

Welnance is a very powerful building block of the Binance Smart Chain DeFi ecosystem. Understanding the ways rates change is important in evaluating the potential performance of any leveraged position.