diff --git a/bsip-0033.md b/bsip-0033.md index 06d5409..4fe4e4b 100644 --- a/bsip-0033.md +++ b/bsip-0033.md @@ -11,7 +11,16 @@ # Abstract -Currently, when matching taker limit orders with maker limit orders, the maker +Currently, in BitShares, under certian circumstances, a taker order may be +matched with a maker order which is not "on the top" of the order book. +This behavior is unexpected and irritating for users. + +This BSIP proposes a principle: always match taker orders with maker orders +with the best prices (aka on the top of the order book) first. + +# Motivation + +As expected, when matching taker limit orders with maker limit orders, the maker limit orders with better prices will always be matched first. For example, if trader A has a limit order selling 100 BTS at @@ -20,46 +29,62 @@ which means B's limit order has a better price for the opposite side to buy. Now if trader C placed an order that buys 10 BTS at 0.105 USD per BTS, B's limit order will take precedence, A's limit order won't be matched. -However, when there are margin call orders in the market which have met the -requirements that to be matched, they always take precedence over limit orders -on the same side, no matter whether the limit orders provided better price. +However, when there are (maker) margin call orders in the market which have met +the requirements that to be matched (able to be margin called), they always +take precedence over the (maker) limit orders on the same side, no matter +whether the limit orders provided better price. For example, if trader A's margin call order is selling 100 BTS at no less than 0.1 USD per BTS, trader B has a limit order selling 100 BTS at 0.09 USD per BTS, which means B's limit order has a better price for the opposite side to buy. Now if trader C placed an order that buys 10 BTS at 0.105 USD per BTS, A's margin call order will take precedence, B's limit order won't be matched. That -means C is forced to "buy high" when have chance to "buy low". +means C is forced to "buy high" when have chance to "buy low", which is +unexpected. -This BSIP proposes a new behavior: always match taker -orders with maker orders with better prices first. +Users have been confused by this behavior, as discussed in [bitshares-core +issue #625](https://github.com/bitshares/bitshares-core/issues/625) and other +threads. -This BSIP also sets a principle for dealing with [bitshares-core -issue #453](https://github.com/bitshares/bitshares-core/issues/453). -In that issue, it's described that sometimes a taker margin call order may be -matched with a maker limit order which is not on the top of the order book. - -# Motivation - -Make the exchange system more user-friendly. +Another scenario is described in [Bitshares-core +issue #453](https://github.com/bitshares/bitshares-core/issues/453) +that sometimes a taker margin call order may be matched with a maker limit order +which is not on the top of the order book. This can be seen as a bug. # Rationale -To attract more users, the system should be fair. +Always matching taker order (e.g. a buy) with a maker order which offered best +price (aka lowest ask), is a simpler rule which most users would understand +easily. + +There is a parameter in price feed named MSSR, which stands for "maximum short +squeeze ratio". Maker price of margin call orders is MSSP, which stands for +"maximum short squeeze price", is calculated as `feed_price / MSSR`. +Note: `feed_price` here is in terms of debt/collateral, aka "how much debt per +collateral". + +That said, the price that margin call orders are offering is MSSP. The prices +those limit orders are offering are the limit prices. + +When placing a limit (e.g. buy) order with a price beyond the lowest sell, +the order is expected to "walk the book", matching each order on the opposite +side in turn, at that order's price, until the new limit order is completely +filled, or there is no more sell order matching its price. + +To meet the expectation, +* firstly, we need to match the limit buy order with the limit sell orders + whose prices are lower than MSSP and prices can match the new order; +* then, if the new limit buy order hasn't been completely filled, match it with + the margin calls if MSSP can match the new order's price; +* then, if the new limit buy order still hasn't been completely filled, match it + with the rest sell orders until it's completely filled or no more sell order + matching its price -It's common sense that, in a continuous trading market, new orders should be -matched with the orders on the opposite side which offerred best prices first. # Specifications ## Matching a taker limit order -There is a parameter in price feed named MSSR, which stands for "maximum short -squeeze ratio". Maker price of margin call orders is MSSP, which stands for -"maximum short squeeze price", is calculated as `feed_price / ( 100% + MSSR )`. -Note: `feed_price` here is in terms of debt/collateral, aka "how much debt per -collateral". - New limit order is being processed in `apply_order(...)` function of `database` class. @@ -67,10 +92,13 @@ Currently, in the function, firstly call orders will be checked and matched. After that, limit orders on the opposite side will be checked and matched. Need to change the logic to: -* match the new limit order with limit orders on the opposite side whose price - is below MSSP first, -* if the new order is still there, match it with call orders, -* if the new order is still there, match it with rest limit orders. +1. firstly, sort the limit orders on the opposite by `price`, best price first, + end at MSSP; check them one by one, calls `match(...)` function until the + return value is not `2` which means the new order is completely filled; +2. if reach the end (MSSP), which means the new order is still unfilled, + call `check_call_orders(..)` function or an equivalent; +3. check if `new_order_object` still exist, if yes, redo step one but set the + maximum possible price of the market as end price. ## Matching taker margin call orders