Risk Metrics
Describes risk metrics that are calculated via the SDK
Free Collateral
Free collateral represents the absolute amount of collateral in excess of the minimum amount required by the system. If free collateral is negative, an account is subject to liquidation. Free collateral is the core metric used to determine the health of an account. The rest of the risk metrics are useful derived metrics that affect a user's free collateral.
getFreeCollateral
Returns components of the free collateral figure which is always denominated in ETH. Aggregate free collateral can be calculated using these components. If aggregateFreeCollateral is negative, then an account is eligible for liquidation.
aggregateFreeCollateral = netETHCollateralWithHaircut - netETHDebtWithBuffer
@param account an accountData object representing a potential account
@param blockTime used for calculating present values
Return Values:
netETHCollateralWithHaircut: aggregate amount of collateral converted to ETH with haircuts applied
netETHCollateral: aggregate amount of collateral converted to ETH without haircuts
netETHDebt: aggregate amount of debt converted to ETH without buffers applied
netETHDebtWithBuffer: aggregate amount of debt converted to ETH with buffers applied
netUnderlyingAvailable: net amount of debt or collateral in each currency without exchange rate haircuts or buffers applied. Calculated as:
cashBalance + nTokenHaircutPresentValue + fCashRiskAdjustedPV + liquidityTokenRiskAdjustedPVand expressed in terms of asset cash.
getCurrencyComponents
Returns components of the netUnderlyingAvailable figure in a single currency. Both return values are risk adjusted, meaning that their present values are haircut (reduced when positively valued) or buffered (increased when negatively valued) within the local currency. nTokens, fCash and liquidity tokens have valuations that change relative to cash balances and that is why they must have these risk adjustments.
@param currencyId
@param assetCashBalanceInternal
@param nTokenBalance
@param portfolio an array of fCash and liquidity token assets
@param blockTime
Return Values:
nTokenValue: nToken present value with the nToken haircut applied
cashGroupPV: risk adjusted present value of fCash and liquidity token assets held in the portfolio
Risk Ratios
getFreeCollateral returns the absolute valued components of the collateralization calculation, but it is also useful to measure an account's health in terms of ratios between assets and debts.
calculateCollateralRatio
Calculates a collateral ratio (collateral assets / debts) as a percentage scaled by 100, always denominated in ETH underlying, 8 decimals of precision. Parameters can be either: netETHCollateralWithHaircut and netETHDebtWithBuffer or netETHCollateral or netETHDebt. The first pair of inputs will have a value of 100 at the liquidation threshold (they are scaled based on risk adjustments). The second pair of inputs may be at the liquidation threshold at any range of values and is not used within the system to determine liquidation eligibility -- it can be used as a user friendly measure of the collateralization ratio.
Convenience methods are available on the AccountData object, bufferedCollateralRatio and collateralRatio, respectively.
@param netETHCollateral
@param netETHDebt
Return Value:
Collateral ratio scaled by 100
loanToValueRatio
A loan to value ratio is the inverse of the collateral ratio (debts / collateral). This metric is a user facing representation of an account's debt load. The advantage of this metric is that it is bounded between 0% and 100% (whereas collateral ratios are unbounded). The disadvantage of this metric, however, is that it is hyperbolic due to the bounds applied, meaning that a 1% increase or decrease in the loan to value ratio is not the same through the 0% to 100% range.
Additionally, the Notional version of loan to value does not use net local currency values (i.e. netting off positive DAI cash and negative fDAI debt in the same currency prior to ETH exchange rate conversion). Rather, it uses the total value of debts and collateral denominated in ETH.
Return Values:
totalETHDebts: total value of all debts denominated in ETH, without any risk adjustments applied
totalETHValue: total value of all collateral denominated in ETH, without any risk adjustments applied
loanToValue:
totalETHDebts/ totalETHValuescaled to 100haircutLoanToValue:
totalETHDebtsWithRiskAdjustments / totalETHValueWithRiskAdjustmentsscaled to 100maxLoanToValue: the maximum allowed loan to value ratio, calculated as
loanToValue / haircutLoanToValuescaled to 100
Risk Thresholds
Risk thresholds give specific price levels or interest rate levels for when an account is eligible for liquidation. More complex portfolios with multiple collateral assets or debts DO NOT have constant risk thresholds. See descriptions below for more details.
getLiquidationPrice
Returns the ETH denominated price of the collateral currency at which the debt denominated in the debt currency will be liquidated. This liquidation price is not constant and may change significantly for accounts with multiple collateral assets or debts.
For example, an account with both WBTC and ETH collateral against USDC debts will face a changing liquidation price as WBTC and ETH prices move in relation to each other. An account with only ETH collateral against USDC debt will have a more constant liquidation price (although it will still drift in relation to USDC interest rates and time to maturity).
Similar logic applies to an account with USDC collateral against WBTC and ETH debts.
@param collateralId currency id of the collateral to calculate against
@param debtCurrencyId currency id of the debt to calculate against
calculateInterestRateRisk
nTokens and fCash present values are are subject to change as market interest rates change. It stands to reason that there are interest rates where where an account is eligible for liquidation. Because interest rate changes have a smaller effect on valuations relative to price movements, only highly leveraged accounts will be exposed to interest rate risk.
Interest rate risk is reported per currency relative to the weighted average interest rate across current fCash markets. This is an approximation of where overall market interest rates can move such that an account becomes eligible for liquidation. The exact set of interest rates where an account is eligible for liquidation is a multivariate space and not easily digestible.
Liquidation interest rates are potentially as both upper and lower bounds against the current average interest rate.
Return Values:
A mapping between a currency id with interest rate risk and:
currentWeightedAvgInterestRate: the current liquidity weighted average interest across a set of fCash markets
upperLiquidationInterestRate: the upper bound of the weighted average interest rate where an account is eligible for liquidation (null if there is no upper bound)
lowerLiquidationInterestRate: the lower bound of the weighted average interest rate where an account is eligible for liquidation (null if there is no lower bound)
getMaxInterestRate
Each fCash market is configured with an upper bound interest rate at which it cannot trade past. This is a function of its liquidity curve and time to maturity. This method will return the maximum interest rate across all fCash markets in a single currency. This can be used as a measure against the upperLiquidationInterestRate to determine the relative likelihood that a market reaches an account's liquidation point.
Borrow Requirement
These methods calculate how much additional collateral is required in order for an account to meet a given collateral ratio.
calculateBorrowRequirement
Calculates borrow requirements for a given account and a target collateral ratio
@param collateralCurrencyId currency to collateralize the account
@param bufferedRatio the target post haircut / buffer collateral ratio
@param accountData account data object with borrow amounts applied
@param mintNTokenCollateral true if collateral should be minted as nTokens
@param blockTime
Return Values:
minCollateral: minimum amount of collateral required for the borrow
targetCollateral: amount of collateral to reach the bufferedRatio
minCollateralRatio: minimum collateral ratio
minBufferedRatio: minimum risk adjusted collateral ratio
targetCollateralRatio: target collateral ratio
targetBufferedRatio: the target risk adjusted collateral ratio
minCollateralCopy: a copy of the accountData object with the minimum collateral amounts applied
targetCollateralCopy: copy of the accountData object with target collateral amounts applied
Last updated