From 555937cf2fd4b49588ce42747cf0babef9599596 Mon Sep 17 00:00:00 2001
From: abitmore <abitmore@users.noreply.github.com>
Date: Tue, 10 Apr 2018 15:08:35 -0400
Subject: [PATCH] bsip38: more description about rounding and mcr

---
 bsip-0038.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 54 insertions(+), 2 deletions(-)

diff --git a/bsip-0038.md b/bsip-0038.md
index 764203c..c3150f4 100644
--- a/bsip-0038.md
+++ b/bsip-0038.md
@@ -90,6 +90,56 @@ max_debt_to_cover = max_amount_to_sell * match_price
 
 It need to be rounded up to an integer as well.
 
+Then adjust `max_amount_to_sell` to be more precise by:
+
+```
+max_amount_to_sell = round_down(max_debt_to_cover / match_price)
+```
+
+## Rounding and Edge Cases
+
+Without `target_CR` option set, when a call order is partially filled, its
+paid collateral will be rounded down, so its collateral ratio will increase.
+
+With `target_CR` option set, when a call order is partially filled, it's
+possible that its paid collateral will be rounded up. If the call order's
+collateral ratio is not too low, partially filling will likely leads to an
+increase in collateral ratio.
+
+However, there are edge cases: if the call order's collateral ratio is already
+low, or its debt or collateral amount is tiny, rounding up paid collateral on
+partially filling will probably lead to a decrease in collateral ratio,
+in extreme cases it may even lead to a black swan event. This is against the
+intention of this BSIP. To solve this issue, when detected a decrease in
+collateral ratio when matching, ignore the `target_CR` option of corresponding
+call order, and re-evaluate the match.
+
+## When and How To Use the Option
+
+The `target_collateral_ratio` option can to be set, updated or cleared when
+creating or updating a short position. When doing so, other rules still apply,
+E.G. can't update a short position to have too small collateral ratio.
+
+For one account, different short positions (for different assets) can be set
+with different `target_collateral_ratio`.
+
+For one short position,
+
+* if want to close it completely to cut losses when being margin called,
+  * don't set or clear `target_collateral_ratio` option, because the option is
+   **optional** so can be unset or cleared;
+
+* if want to sell as little collateral as possible when being margin called,
+  to keep the remaining short position as large as possible,
+  * set `target_collateral_ratio` to `MCR` or less;
+
+* if want to sell more than minimum required collateral when being margin
+  called, to reduce the possibility of being margin called again in the near
+  future, but don't want to completely close the short position,
+  * set `target_collateral_ratio` to a value higher than `MCR`, E.G. `300%`.
+   The higher the value is, the more collateral will be listed for sale when
+   it's margin called.
+
 
 # Specifications
 
@@ -138,8 +188,10 @@ The `proposal_create_evaluator` is used to evaluate and apply the
 
 After a call order get matched with a limit order and about to fill,
 * if `target_collateral_ratio` is not set, process as before;
-* if `target_collateral_ratio` is set, calculate maximum amount of collateral
-  for sale according to the equation described above, then process as before.
+* if `target_collateral_ratio` is set, compare it to `MCR`, use the bigger
+  one (aka `max(target_collateral_ratio,MCR)`) to calculate maximum amount of
+  collateral for sale and maximum amount of debt to cover according to the
+  equation described above, then process as before.
 
 ### Rounding