Rewrite BSIP74 Specification section

bsip-0074.md

@@ -24,13 +24,89 @@ To ensure the debt positions can always be closed with suffcient smartcoin, it i
 As the margin call fee ratio may be obvious higher than market fee, the margin call orders should be placed at the real price without margin call fee to avoid misleading the buyer.
 
 # Specification
-Add one new parameter Margin Call Fee Ratio(MCFR) for each smartcoin, which is controlled by the smartcoin owner.
 
-`Margin call order price = settlement price/(MSSR-MCFR)`.
+### Fee Parameter and Margin Call Order Price
 
-Here settlement price is a new introduced parameter which is defined in BSIP71, settlement price = feed price when there is no bad debt.
+Add one new parameter, Margin Call Fee Ratio (MCFR), for each smartcoin, which is controlled by the smartcoin owner. This fee ratio will modulate the Maximum Short Squeeze Ratio (MSSR) when determining the Margin Call Order Price (MCOP):
 
-When a margin call trading happens, the buyer sells smartcoin with quantity X and get collaterals in quantity `X*(MSSR-MCFR)/settlement price`, the margin call order owner sells collaterals in quantity `X*MSSR/settlement price` and get smartcoin in quantity X, the delta in paid and received collaterals in `quantity X*MCFR/settlement price` will be paid to the owner of the smartcoin as margin call fee.
+`margin_call_order_price = median_feed_price / (MSSR - MCFR)`.
+
+Here, `margin_call_order_price` is the price at which margin calls will enter the market order book, and `median_feed_price`<sup>(1)</sup> conveys the "even exchange" price between DEBT and COLLATERAL, as reported by the price feed publishers.  Both prices are expressed in units of DEBT / COLLATERAL.
+
+This new calculation of MCOP differs from previous behavior.  Previously, margin calls entered the book at the Maximum Short Squeeze Price (MSSP), defined as:
+
+`max_short_squeeze_price = median_feed_price / MSSR`.
+
+The MSSP is retained under this BSIP as the collateralization threshold at which global settlement can be triggered, but it no longer determines the order price.
+
+_**Note (1):** In the core source code, as of this writing, what we here call `median_feed_price` is called `settlement_price`, although it represents the median reported price feed.  Even though it would match current code, we have preferred not to use the symbol `settlement_price` as a synonym for median feed price in this document for two reasons: (1) the value is not identical with the price at which force settlements occur, due to the Force Settlement Offset (FSO), thus the symbol is confusing, and (2) [BSIP-0071](bsip-0071.md) uses the symbol `settlement_price` to refer to the price at which force settlements occur, inclusive of the FSO, and we do not wish to add ambiguity by using a different definition here._
+
+### Fee Calculation
+
+#### Review of order-matching sequence:
+
+A margin call will enter the book at the MCOP.  However, if at the time the call enters the book, (or any time thereafter in response to a price feed update), it can be matched with an existing limit order at a more favorable price, it will take that order. This means that the `match_price` will be some price no worse than (from the perspective of the callee) the MCOP:
+
+`match_price >= margin_call_order_price`.  _(when margin call is a taker)_
+
+If no immediate match is found, then the call order will wait on the books (as a maker) for a future limit order to take it.  In this case, the eventual match price is exactly the order price:
+
+`match_price = margin_call_order_price`.  _(when margin call is a maker)_
+
+#### Calculation of fee, general case:
+
+When a call order is matched to a limit order and they exchange _X_ amount of smartcoin, this BSIP proposes that two distinct quantities be calculated: the amount of collateral which the limit order receives from the call order in exchange for _X_, and the total amount of collateral that the call order relinquishes to satisfy obligations including the margin call fee.  If the MCFR parameter is zero, then these two quantities are equal, and the behavior is unchanged from before.  But if the MCFR is non-zero, then the relinquished collateral will be a greater quantity than what is payed to the limit order.  The excess is to be paid to the issuer of _X_ as the _Margin Call Fee_.
+
+<br>
+
+`limit_order_receives = X / match_price`
+
+`call_order_relinquishes = (X / match_price) * [MSSR / (MSSR - MCFR)]`
+
+`margin_call_fee = call_order_relinquishes - limit_order_receives`.
+
+<br>
+
+This calculation results in a Margin Call Fee which is proportional to the amount of collateral paid to the limit order to buy _X_ amount of smartcoin.
+
+#### Calculation of fee, maker case:
+
+Note that in the case when the margin call enters the book as a maker order (i.e., when it was not able to immediately find an existing favorable limit order), the match price will be identical to the order price, which allows the forgoing calculations to simplify as follows:
+
+<br>
+
+`limit_order_receives = X * (MSSR - MCFR) / median_feed_price`
+
+`call_order_relinquishes = X * MSSR / median_feed_price = X / max_short_squeeze_price`
+
+`margin_call_fee = X * MCFR / median_feed_price`
+
+<br>
+
+The above simplification offers two insights into the Margin Call Fee:
+
+1. The reason why Maximum Short Squeeze Price is retained as the Global Settlement threshold is because this is the price that determines the total amount of collateral a call order must relinquish under least favorable conditions, and,
+
+2. That the MCFR can be interpreted as defining a fraction of the feed price that establishes the maximum fee rate paid by the callee.  (I.e., the fee will not exceed `MCFR * X / median_feed_price`.)
+
+
+### Fee Floor
+
+Because the effect of the Margin Call Fee is to reduce the amount of collateral offered by the margin call to buy back debt, there is a danger that the margin call could offer less collateral than the "even exchange" value of the debt (as reported by the price feed publishers), making it unlikely to match the call with a buyer.  To prevent this, the implementation should include a floor wherein every place that `MSSR - MCFR` appears, it is replaced with:
+
+`(MSSR - MCFR)` —> `max((MSSR - MCFR), 1.000)`.
+
+This will ensure that the amount of collateral offered by the margin call is never valued less than the quantity of debt which the call seeks to buy.  At the same time, however, it may mean that the asset issuer receives less collateral (or even no collateral) than they are expecting in fees.  Asset issuers should be advised not to expect to collect a fee rate greater than (MSSR - 1.000).
+
+### Specification summary
+
+In summary, this BSIP proposes that the Maximum Short Squeeze Price, which previously established both the price at which margin calls offered collateral _and_ the collateralization threshold at which Global Settlement occurs, be separated into two distinct concepts:
+
+1. **Margin Call Offer Price** — The price at which margin calls offer to sell collateral in order to buy debt, and,
+
+2. **Maximum Short Squeeze Price** — The most extreme price at which a call order will be required to relinquish collateral in order to satisfy the combined obligation of buying debt and paying the margin call fee.  Because the margin call must hold at least this much collateral (per unit debt) in order to relinquish it, this also becomes the collateralization threshold at which Global Settlement can be triggered.
+
+# Shareholder Summary
 
 # Copyright
 This document is placed in the public domain.