BitShares-Core  5.0.0
BitShares blockchain implementation and command-line interface software
Public Member Functions | List of all members
graphene::protocol::price_feed Class Reference

defines market parameters for margin positions More...

#include <asset.hpp>

Inheritance diagram for graphene::protocol::price_feed:
graphene::chain::price_feed_with_icr

Public Member Functions

void validate () const
 
bool is_for (asset_id_type asset_id) const
 
price settlement_price
 
price core_exchange_rate
 Price at which automatically exchanging this asset for CORE from fee pool occurs (used for paying fees) More...
 
uint16_t maintenance_collateral_ratio = GRAPHENE_DEFAULT_MAINTENANCE_COLLATERAL_RATIO
 
uint16_t maximum_short_squeeze_ratio = GRAPHENE_DEFAULT_MAX_SHORT_SQUEEZE_RATIO
 
price max_short_squeeze_price () const
 
price max_short_squeeze_price_before_hf_1270 () const
 
price margin_call_order_price (const fc::optional< uint16_t > margin_call_fee_ratio) const
 
ratio_type margin_call_pays_ratio (const fc::optional< uint16_t > margin_call_fee_ratio) const
 
price maintenance_collateralization () const
 
bool margin_call_params_equal (const price_feed &b) const
 

Detailed Description

defines market parameters for margin positions

Definition at line 164 of file asset.hpp.

Member Function Documentation

bool graphene::protocol::price_feed::is_for ( asset_id_type  asset_id) const

Definition at line 253 of file asset.cpp.

price graphene::protocol::price_feed::maintenance_collateralization ( ) const

Call orders with collateralization (aka collateral/debt) not greater than this value are in margin call territory. Calculation: ~settlement_price * maintenance_collateral_ratio / GRAPHENE_COLLATERAL_RATIO_DENOM

Definition at line 321 of file asset.cpp.

price graphene::protocol::price_feed::margin_call_order_price ( const fc::optional< uint16_t >  margin_call_fee_ratio) const

Compute price at which margin calls offer to sell collateral.

Margin calls offer a greater amount of COLLATERAL asset to the market to buy back DEBT asset than would otherwise be required in a fair exchange at the settlement_price. (I.e. they sell collateral "cheaper" than its price feed value.) This is done to attract a quick buyer of the call in order to preserve healthy collateralization of the DEBT asset overall. The price at which the call is offered, in comparison to the settlement price, is determined by the Maximum Short Squeeze Ratio (MSSR) and the Margin Call Fee Ratio (MCFR) as follows, in units of DEBT per COLLATERAL:

MCOP = settlement_price / (MSSR - MCFR);

Compare with Maximum Short Squeeze Price (MSSP), which is computed as follows:

MSSP = settlement_price / MSSR;

Since BSIP-74, we distinguish between Maximum Short Squeeze Price (MSSP) and Margin Call Order Price (MCOP). Margin calls previously offered collateral at the MSSP, but now they offer slightly less collateral per debt if Margin Call Fee Ratio (MCFR) is set, because the call order must reserve some collateral to pay the fee. We must still retain the concept of MSSP, as it communicates the minimum collateralization before black swan may be triggered, but we add this new method to calculate MCOP.

Note that when we calculate the MCOP, we enact a price floor to ensure the margin call never offers LESS collateral than the DEBT is worth. As such, it's important to calculate the realized fee, when trading at the offer price, as a delta between total relinquished collateral (DEBT*MSSP) and collateral sold to the buyer (DEBT*MCOP). If you instead try to calculate the fee by direct multiplication of MCFR, you will get the wrong answer if the price was floored. (Fee is truncated when price is floored.)

Parameters
margin_call_fee_ratioMCFR value currently in effect. If zero or unset, returns same result as max_short_squeeze_price().
Returns
The MCOP in units of DEBT per COLLATERAL.

Definition at line 295 of file asset.cpp.

bool graphene::protocol::price_feed::margin_call_params_equal ( const price_feed b) const
inline

Whether the parameters that affect margin calls in this price feed object are the same as the parameters in the passed-in object

Definition at line 291 of file asset.hpp.

ratio_type graphene::protocol::price_feed::margin_call_pays_ratio ( const fc::optional< uint16_t >  margin_call_fee_ratio) const

Ratio between max_short_squeeze_price and margin_call_order_price.

This ratio, if it multiplied margin_call_order_price (expressed in DEBT/COLLATERAL), would yield the max_short_squeeze_price, apart perhaps for truncation (rounding) error.

When a margin call is taker, matching an existing order on the books, it is possible the call gets a better realized price than the order price that it offered at. In this case, the margin call fee is proportionaly reduced. This ratio is used to calculate the price at which the call relinquishes collateral (to meet both trade and fee obligations) based on actual realized match price.

This function enacts the same flooring as margin_call_order_price() (MSSR - MCFR is floored at 1.00). This ensures we apply the same fee truncation in the taker case as the maker case.

Returns
(MSSR - MCFR) / MSSR

Definition at line 307 of file asset.cpp.

price graphene::protocol::price_feed::max_short_squeeze_price ( ) const

This is the price at which a call order will relinquish COLLATERAL when margin called. It is also the price that establishes the minimum amount of collateral per debt that call orders must maintain to avoid possibility of black swan. A call order maintaining less collateral per debt than this price is unable to meet the combined obligation to sell collateral at the Margin Call Offer Price (MCOP) AND to pay the margin call fee. The MSSP is related to the MCOP, but the MSSP accounts for the need to reserve extra collateral to pay the margin call fee, whereas the MCOP only accounts for the collateral to be traded to the call buyer. Prior to the introduction of the Margin Call Fee Ratio (MCFR) with BSIP-74, the two prices (MSSP and MCOP) were identical, and MSSP could be thought of as "the price at which you are forced to sell collateral if margin called," but this latter concept is now embodied by the MCOP.

The Maximum Short Squeeze Price is computed as follows, in units of DEBT per COLLATERAL:

MSSP = settlement_price / MSSR;

Returns
The MSSP in units of DEBT per COLLATERAL.

Definition at line 287 of file asset.cpp.

price graphene::protocol::price_feed::max_short_squeeze_price_before_hf_1270 ( ) const

Older implementation of max_short_squeeze_price() due to hardfork changes. It came with the following commentary:

When selling collateral to pay off debt, the least amount of debt to receive should be min_usd = max_short_squeeze_price() * collateral

This is provided to ensure that a black swan cannot be trigged due to poor liquidity alone, it must be confirmed by having the max_short_squeeze_price() move below the black swan price.

Returns
the Maximum Short Squeeze price for this asset

Definition at line 269 of file asset.cpp.

void graphene::protocol::price_feed::validate ( ) const

Definition at line 238 of file asset.cpp.

Member Data Documentation

price graphene::protocol::price_feed::core_exchange_rate

Price at which automatically exchanging this asset for CORE from fee pool occurs (used for paying fees)

Definition at line 187 of file asset.hpp.

uint16_t graphene::protocol::price_feed::maintenance_collateral_ratio = GRAPHENE_DEFAULT_MAINTENANCE_COLLATERAL_RATIO

Fixed point between 1.000 and 10.000, implied fixed point denominator is GRAPHENE_COLLATERAL_RATIO_DENOM

Definition at line 190 of file asset.hpp.

uint16_t graphene::protocol::price_feed::maximum_short_squeeze_ratio = GRAPHENE_DEFAULT_MAX_SHORT_SQUEEZE_RATIO

Fixed point between 1.000 and 10.000, implied fixed point denominator is GRAPHENE_COLLATERAL_RATIO_DENOM

Definition at line 193 of file asset.hpp.

price graphene::protocol::price_feed::settlement_price

Required maintenance collateral is defined as a fixed point number with a maximum value of 10.000 and a minimum value of 1.000. (denominated in GRAPHENE_COLLATERAL_RATIO_DENOM)

A black swan event occurs when value_of_collateral equals value_of_debt * MSSR. To avoid a black swan a margin call is executed when value_of_debt * required_maintenance_collateral equals value_of_collateral using rate.

Default requirement is $1.75 of collateral per $1 of debt

BlackSwan —> SQR —> MCR -—> SP Forced settlements will evaluate using this price, defined as BITASSET / COLLATERAL

Definition at line 184 of file asset.hpp.


The documentation for this class was generated from the following files: