Merge pull request #215 from nathanhourt/master

BSIP 61: Operation to update limit orders

bsip-0061.md

@@ -0,0 +1,79 @@
+    BSIP: 0061
+    Title: Operation to Update Limit Orders
+    Authors:
+      Nathan Hourt <[email protected]>
+    Status: Draft
+    Type: Protocol
+    Created: 2019-02-22
+    Discussion: https://github.com/bitshares/bsips/issues/150
+
+# Abstract
+This BSIP proposes a new operation, `limit_order_update_operation`, which will allow direct modification of a limit order. This operation will be smaller to serialize than the cancel/create operation combination presently required to achieve the same result, as it must only store new field values rather than all field values. Moreover, the update operation will require lower processing and RAM consumption. In return for this reduction in consumption, the overall fee charged for an update operation can be set lower than the equivalent cancel/create combo, thus incentivizing market makers to keep freshly updated orders at the top of the books.
+
+# Motivation
+At present, the BitShares protocol does not allow direct modification of limit orders in the markets. Instead, to modify a limit order, the order must be canceled and and a new one created in its place. This results in greater-than-necessary overhead when updating a limit order, an action which is performed by market maker robots with great frequency (hundreds of times per day, per market). Additionally, the cancel/create combination requires payment of two fees, which has led to some pressure from market makers for BitShares to provide a cheaper mechanism for maintaining fresh order walls in the markets.
+
+# Rationale
+The specification below was chosen on the following criteria:
+ - Minimal storage space for historical data (i.e. serialized operation size)
+   - Cancel/create combination requires two distinct operations, and explicit restatement of all order parameters
+   - Update operation requires only one operation, which elides all fields which are not being updated
+ - Minimal processing
+   - No deletion/construction is necessary, object is modified in place
+   - Cancel/create requires two separate modifications of balances; update requires zero or one
+   - Order matching is only triggered if order is moved past previous top of book
+ - Minimal RAM consumption for undo storage
+   - Object modification requires slightly less space than object deletion and creation
+   - Balances and account statistics are not updated unless necessary, avoiding unnecessary undo storage
+
+# Specification
+A complete implementation of this BSIP is available for review [here](https://github.com/bitshares/bitshares-core/compare/develop...nathanhourt:issue-1604).
+
+The `limit_order_update_operation` contains the following fields:
+```cpp
+       asset fee;
+       account_id_type seller;
+       limit_order_id_type order;
+       optional<price> new_price;
+       optional<share_type> delta_amount_to_sell;
+       optional<time_point_sec> new_expiration;
+
+       extensions_type extensions;
+```
+
+This operation will have the following stateless validity checks:
+ - Fee is positive 
+ - At least one of the optional update fields is not null
+ - If `new_price` is not null, run its `validate` method
+ - If `delta_amount_to_sell` is not null, check it is not zero
+
+Additionally, the following stateful checks will be applied during evaluation:
+ - `seller` matches referenced order object's owner
+ - If `new_price` is not null, check its assets match those in the referenced order
+ - If `delta_amount_to_sell` is not null and positive, check it does not exceed seller's balance
+ - If `delta_amount_to_sell` is not null and negative, check it does not exceed order's balance
+ - Check if order is too small using the logic defined in `maybe_cull_small_order()` and reject the update if so
+ - If `new_expiration` is not null, check it is in the future
+
+A single new evaluator is required, which shall check that the new field values are valid for the order being updated, and update the order and balances as necessary, then trigger order matching only if the price was modified such that the order has moved past the previous top-of-book order.
+
+No new indexes are required. No modifications to existing indexes are required. No new database objects are defined. No modifications to existing database objects are required.
+
+# Summary for Shareholders
+The changes proposed in this BSIP are easily implemented, and the only downside apparent to the author is the definition of a new operation type, which slightly increases the complexity of creating a new implementation of the BitShares protocol. Thus, the question must be considered, is the new operation of significant value to the community, and will it be used?
+
+The new operation is of greatest value to market makers, as these individuals typically run robots which must monitor the markets and maintain competitively priced orders on both sides of the market. These orders must be updated regularly, especially for BitAsset markets. The addition of an operation to modify limit orders will reduce the cost of market making, thus increasing the incentive for users to provide this service. Additionally, it reduces the requirements for processing and storing market maker activity.
+
+In conclusion, this BSIP proposes a very small modification to the protocol with minimal downside, and a meaningful upside for market makers and reduced requirements for all nodes which process the markets.
+
+# Copyright
+This document is created for the betterment of humanity and is hereby placed into the public domain.
+
+# Discussion
+A full implementation is available at:
+https://github.com/bitshares/bitshares-core/issues/1604
+
+#### Fee Calculation
+This operation is a simple object update operation; it does not allocate new resources nor command processing logic additional to that which was already expected by the pre-existing object. A limit order on the books is created with the expectation that it will either be matched, potentially several times, or canceled, and fees to cover this storage and processing are collected during order creation. Because this operation does not fundamentally change this scenario, it charges a simple, non-refundable processing fee, and does not interact with the refundable order creation fee.
+
+The limit order update operation may be used to "top up" an existing order and keep it on the books longer, possibly matching against more orders than would have been predicted when the order was created. This implies that for long-standing orders, the limit order update operation may constitute a discount over normal order creation, cancelation, and processing fees. Long-standing orders, however, are more valuable to the DEX than short-lived orders, as they promote market depth and high volume trading: market attributes which attract traders and more short-lived orders. The value added to the DEX as a whole by making it more economical for market makers to maintain long-standing orders significantly outweighs the discount the update operation affords to market makers; therefore, this proposal does not regard this discount on processing as detrimental to the blockchain as a whole.