Trade Helpers

getPresentfCashValue

Returns the present value of the given fCash amount using Notional internal oracle rates. If riskAdjusted is set to true then the will return the buffered or haircut value of fCash used in the Notional free collateral calculation.

fCashAmount must be specified in 8 decimal precision, present value will be returned in 8 decimal precision.

function getPresentfCashValue(
    uint16 currencyId,
    uint256 maturity,
    int256 notional,
    uint256 blockTime,
    bool riskAdjusted
) external view returns (int256 presentValue);

getMarketIndex

Returns an integer between 0 and 7 that represents the corresponding market index (i.e. tenor) of the market. 0 represents no corresponding market. Market indexes reference fCash tenors as follows:

• 1: 3 Month

• 2: 6 Month

• 3: 1 Year

• 4: 2 Year

• 5: 5 Year

• 6: 10 Year

• 7: 20 Year

Each currency will be listed with a max markets index that it cannot trade past.

function getMarketIndex(
    uint256 maturity,
    uint256 blockTime
) external pure returns (uint8 marketIndex);

getfCashLendFromDeposit

Returns an amount of fCash that would be received if lending the depositAmountExternal amount. currencyId refers to the currency that is being lent on Notional, depositAmountExternal is denominated in the token's native decimal precision (i.e. 6 decimals for USDC, 18 for DAI). useUnderlying can be set to true when referring to underlying tokens (i.e. DAI, USDC) and false when referring to asset tokens (i.e. cDAI, cUSDC, aFRAX). minLendRate is the minimum annualized interest rate that will be encoded in encodedTrade, this is specified in 9 decimal precision where 1e9 is 100% interest. If 0 is specified for minLendRate then no slippage limit will be applied.

Returns the fCashAmount to be received at maturity, the market index that corresponds to the maturity, and an encodedTrade object that can be passed directly into batchLend or batchBalanceAndTradeAction.

function getfCashLendFromDeposit(
    uint16 currencyId,
    uint256 depositAmountExternal,
    uint256 maturity,
    uint32 minLendRate,
    uint256 blockTime,
    bool useUnderlying
) external view returns (
    uint88 fCashAmount,
    uint8 marketIndex,
    bytes32 encodedTrade
);

getfCashBorrowFromPrincipal

Returns an amount of fCash that would be owed if borrowing the depositAmountExternal amount. currencyId refers to the currency that is being borrowed on Notional, depositAmountExternal is denominated in the token's native decimal precision (i.e. 6 decimals for USDC, 18 for DAI). useUnderlying can be set to true when referring to underlying tokens (i.e. DAI, USDC) and false when referring to asset tokens (i.e. cDAI, cUSDC, aFRAX). maxBorrowRate is the maximum annualized interest rate that will be encoded in encodedTrade, this is specified in 9 decimal precision where 1e9 is 100% interest. If 0 is specified for maxBorrowRate then no slippage limit will be applied.

Returns the fCashAmount to be repaid at maturity, the market index that corresponds to the maturity, and an encodedTrade object that can be passed directly into batchBalanceAndTradeAction.

function getfCashBorrowFromPrincipal(
    uint16 currencyId,
    uint256 borrowedAmountExternal,
    uint256 maturity,
    uint32 maxBorrowRate,
    uint256 blockTime,
    bool useUnderlying
) external view returns (
    uint88 fCashDebt,
    uint8 marketIndex,
    bytes32 encodedTrade
);

getDepositFromfCashLend

Returns an amount of cash (both underlying and asset denominated) that is required in order to lend a given fCash amount. currencyId refers to the currency that is being lent on Notional. minLendRate is the minimum annualized interest rate that will be encoded in encodedTrade, this is specified in 9 decimal precision where 1e9 is 100% interest. If 0 is specified for minLendRate then no slippage limit will be applied.

Returns depositAmountUnderlying and depositAmountAsset which correspond to the amount of tokens (in their native decimal precision) that is required to lend, the market index that corresponds to the maturity, and an encodedTrade object that can be passed directly into batchLend or batchBalanceAndTradeAction.

function getDepositFromfCashLend(
    uint16 currencyId,
    uint256 fCashAmount,
    uint256 maturity,
    uint32 minLendRate,
    uint256 blockTime
) external view returns (
    uint256 depositAmountUnderlying,
    uint256 depositAmountAsset,
    uint8 marketIndex,
    bytes32 encodedTrade
);

getPrincipalFromfCashBorrow

Returns an amount of cash (both underlying and asset denominated) that will be received when borrowing a given fCash amount. currencyId refers to the currency that is being borrowed on Notional. maxBorrowRate is the maximum annualized interest rate that will be encoded in encodedTrade, this is specified in 9 decimal precision where 1e9 is 100% interest. If 0 is specified for maxBorrowRate then no slippage limit will be applied.

Returns depositAmountUnderlying and depositAmountAsset which correspond to the amount of tokens (in their native decimal precision) that will be received when borrowing, the market index that corresponds to the maturity, and an encodedTrade object that can be passed directly batchBalanceAndTradeAction.

function getPrincipalFromfCashBorrow(
    uint16 currencyId,
    uint256 fCashBorrow,
    uint256 maturity,
    uint32 maxBorrowRate,
    uint256 blockTime
) external view returns (
    uint256 borrowAmountUnderlying,
    uint256 borrowAmountAsset,
    uint8 marketIndex,
    bytes32 encodedTrade
);

convertCashBalanceToExternal

Converts a Notional internal cash balance to a native token precision value. cashBalanceInternal is a cash balance value returned by Notional, if convertToUnderlying is true then it will return the amount in underlying token denomination (i.e. USDC, DAI). If false, then it will return the amount in asset token denomination (i.e. cDAI, aFRAX, etc).

Note that cash balances can be positive or negative. Negative signifies that an amount is owed to the protocol.

function convertCashBalanceToExternal(
    uint16 currencyId,
    int256 cashBalanceInternal,
    bool useUnderlying
) external view returns (int256);

Deprecated Calculation Methods

These calculation methods are still available and accurate but are deprecated because they are not as easy to use as the newer methods above. They only return values in 8 decimal precision, rather than the token's native precision and they require users to encode trade objects manually.

getCashAmountGivenfCashAmount

Given an amount of fCash to lend (positive) or borrow (negative) at the given market index, returns the resulting netAssetCash. netAssetCash will be negative when lending (lender must pay this amount) and positive when borrowing (borrower will receive this amount). netUnderlyingCash is the converted netAssetCash value (i.e. netAssetCash refers to cDAI whereas netUnderlyingCash refers to DAI).

fCashAmount must be specified in 8 decimal precision, netAssetCash and netUnderlyingCash will be returned in 8 decimal precision.

function getfCashAmountGivenCashAmount(
    uint16 currencyId,
    int88 netCashToAccount,
    uint256 marketIndex,
    uint256 blockTime
) external view returns (int256);

getfCashAmountGivenCashAmount

Given an amount of net cash to an account (lend will be negative because the lender will pay this amount, borrowing is positive because the borrower will receive) at the given market index, returns the resulting netfCash. netfCash will be positive when lending (lender will receive this amount) and negative when borrowing (borrower must pay this amount).

netCashToAccount must be specified in 8 decimal precision, netfCash will be returned in 8 decimal precision.

function getCashAmountGivenfCashAmount(
    uint16 currencyId,
    int88 fCashAmount,
    uint256 marketIndex,
    uint256 blockTime
) external view returns (int256, int256);