Comment on page

# Introduction

Getting Started

These docs are a comprehensive guide to the Source Market, based on the Source Whitepaper. The protocol codebase is hosted on Github, and will be maintained by the team and the community.

The Source One Market 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.

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

sToken | sToken Decimals | Underlying | Underlying Decimals |
---|---|---|---|

sBNB | 8 | BNB | 18 |

sBUSD | 8 | BUSD | 18 |

sUSDC | 8 | USDC | 18 |

sUSDT | 8 | USDT | 18 |

sSRCX | 8 | SRCX | 9 |

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

onesTokenInUnderlying = exchangeRateCurrent / (1 * 10 ^ (18 + underlyingDecimals - sTokenDecimals)

Here is an example of finding the value of 1 sBUSD in BUSD with Web3.js JavaScript.

const sTokenDecimals = 8; // all sTokens have 8 decimal places

const underlying = new web3.eth.Contract(bep20Abi, busdAddress);

const sToken = new web3.eth.Contract(sTokenAbi, sBusdAddress);

const underlyingDecimals = await underlying.methods.decimals().call();

const exchangeRateCurrent = await sToken.methods.exchangeRateCurrent().call();

const mantissa = 18 + parseInt(underlyingDecimals) - sTokenDecimals;

const onesTokenInUnderlying = exchangeRateCurrent / Math.pow(10, mantissa);

console.log('1 sBUSD can be redeemed for', oneSTokenInUnderlying, 'BUSD');

There is no underlying contract for BNB, so to do this with sBNB, set underlyingDecimals to 18.

To find the number of underlying tokens that can be redeemed for sTokens, divide the number of sTokens by the above value oneSTokenInUnderlying.

underlyingTokens = sTokenAmount * oneSTokenInUnderlying

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.

Historical interest rates can be retrieved from the MarketHistoryServiceAPI.

Interest accrues to all suppliers and borrowers in a market when any BSC address interacts with the market’s sToken contract, calling one of these functions: mint, redeem, borrow, or repay. Successful execution of one of these functions triggers the accrueInterest 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 accrueInterest method was not triggered (no user interacted with the sToken contract). Interest Source One only during blocks in which the sToken contract has one of the aforementioned methods invoked.

Here is an example of supply interest accrual:

Alice supplies 1 BNB to the Source One Market At the time of supply, the supplyRatePerBlock is 37893605 Wei, or 0.000000000037893605 BNB per block. No one interacts with the sBNB 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.

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 = sToken.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;

const blocksPerDay = 20 * 60 * 24;

const daysPerYear = 365;

const sToken = new web3.eth.Contract(sBnbAbi, sBnbAddress);

const supplyRatePerBlock = await sToken.methods.supplyRatePerBlock().call();

const borrowRatePerBlock = await sToken.methods.borrowRatePerBlock().call();

const supplyApy = (((Math.pow((supplyRatePerBlock / bnbMantissa * blocksPerDay) + 1,

const borrowApy = (((Math.pow((borrowRatePerBlock / bnbMantissa * blocksPerDay) + 1,

console.log(`Supply APY for BNB ${supplyApy} %`);

console.log(`Borrow APY for BNB ${borrowApy} %`);

The gas usage of the protocol functions may fluctuate by market and user. External calls, such as to underlying BEP-20 tokens, may use an arbitrary amount of gas. Any calculations that involve checking account liquidity , have gas costs that increase with the number of entered markets. Thus, while it can be difficult to provide any guarantees about costs, we provide the table below for guidance:

Function | Typical Gas Cost |
---|---|

Mint | < 200K, sDAI < 300k |

Redeem, Transfer | < 200K if borrowing, otherwise < 90K |

Borrow | < 300K |

Repay Borrow | < 90K |

Liquidate Borrow | < 400K |