Lend and Borrow fCash
How to integrate with Notional fCash markets for fixed rate lending and borrowing
Notional fCash markets enable fixed rate lending and borrowing. There are three ways to lend and borrow fCash:
Batch Trades: a flexible set of methods that allows developers to implement complex, gas efficient sets of trades.
ERC20 Wrapped fCash: a simplified way to lend at fixed rates via an ERC20 and ERC4626 compatible wrapper contract
ERC1155 Transfers: an advanced way to execute OTC (over the counter) fCash trades to make markets in idiosyncratic fCash.
Key Concepts
Account Portfolio: unlike minting cTokens or trading on Uniswap, fCash is not a standalone asset. Every address will hold fCash positions in its portfolio and there is a maximum number of fCash assets a portfolio can hold. The reason for this is that fCash matures at a given date and Notional automatically converts that fCash to cash on that date. In order to do this effectively, it must keep track of fCash assets in an array structure. Read more in Manage Account Assets.
Implied Interest Rate: interest rates reported by the fCash markets are annualized (APY, compounded continuously). They are useful to compare rates across fCash markets. However, note that if the 6 month and the 1 year fCash markets both show a 10% APY, the 6 month market will earn half the absolute amount of interest since the time to maturity is half the 1 year.
Exchange Rate: trading fCash is done based on a calculated exchange rate from cash to fCash. This exchange rate takes into account the current implied interest rate, slippage, fees, and the time to maturity to determine the ratio between fCash and cash. Exchange rates are not comparable across time or markets but they most accurately represent the trade that will take place.
Slippage: the implied interest rate is given at the mid point of the market. Similar to any AMM, the larger the size of the lending or borrowing, the market will slip further away from that mid point. Larger lending will decrease the traded interest rate, larger borrowing will increase the traded interest rate.
Signed Cash and fCash Balances: Unlike most DeFi systems, cash and fCash balances are signed (positive or negative) in Notional. Negative cash or fCash represents a debt owed to the system. Debts can be offset by lending at the same maturity and this is an important concept to understand. A -100 fCash debt can be repaid early by lending 100 fCash at the same maturity. The cash required to lend 100 fCash may be more or less than the original amount borrowed depending on interest rates, if rates have increased then it will cost less. If rates have decreased then it will cost more. Remember: you want to borrow when rates are low and lend when rates are high.
Buying and Selling fCash: Lending and borrowing fCash are colloquial terms for buying (lending) and selling (borrowing). Thinking of lending and borrowing in terms of buying and selling fCash can be useful when thinking about how to repay a borrow early or exit a lending position before maturity.
Market Utilization (Proportion): Trading in fCash markets are limited by two boundaries. The upper limit is 99% utilization which means that only 1% of the market is cash. In this case interest rates will be very high and only lending will be possible. The lower limit is a 0% interest rate. This means that the most you will pay for a unit of fCash is the same amount of cash (i.e. you earn no interest). Notional does not allow negative interest rates.
Calculating Trade Size
Notional only accepts trades denominated in fCash due to how the liquidity curve is shaped (it is not possible to analytically calculate the amount of cash required to trade fCash). There are tools on chain and off chain available to calculate the exchange rate between cash and fCash given either input. The decision was made to make trades specified in fCash so that portfolio balances can be cleared to reduce the size of an account's portfolio (see: Manage Account Assets).
Lending vs Borrowing
Lending will revert if there is insufficient cash in the account, therefore calculating lending trades tends to be less forgiving of dust amounts than borrowing. When lending, be sure to either slightly increase the deposit amount or slightly decrease the fCash amount to account for slippage. If borrowing to take another action and dust amounts will cause problems, check the balance of the address after borrowing to get the exact cash borrowed.
On Chain Calculations (Solidity)
There are multiple trade helper methods on chain that can be used to calculate cash and fCash amount. Since they do add to overall gas costs, it's recommended to call them via RPC off chain and supply the corresponding amounts. However, the Typescript SDK provides much more flexibility for calculating trade amounts.
Off Chain Calculations (Typescript)
The Typescript SDK also exposes getCashAmountGivenfCashAmount and getfCashAmountGivenCashAmount on the Market object which function similar to the solidity methods.
The Market object also has a getSlippageRate function to help calculate the minLendRate or maxBorrowRate when submitting a transaction.
Formulas
NOTE: Notional uses 360 day years.
SECONDS_IN_YEAR = 360 * 86400
Market Utilization
Exchange Rate from Interest Rate (no slippage)
Interest Rate from Exchange Rate
Cash to fCash via Exchange Rate
Last updated