Implement BSIP 74: Margin Call Fee Ratio

[jmjatlanta]

This issue is to track the implementation of BSIP 74.

Impacts

• API (the application programming interface)
• Build (the build process or something prior to compiled code)
• CLI (the command line wallet)
• Deployment (the deployment process after building such as Docker, Travis, etc.)
• DEX (the Decentralized EXchange, market engine, etc.)
• P2P (the peer-to-peer network for transaction/block propagation)
• Performance (system or user efficiency, etc.)
• Protocol (the blockchain logic, consensus, validation, etc.)
• Security (the security of system or user data, etc.)
• UX (the User Experience)
• Other (please add below)

Additional Context
Discussion about the BSIP itself can be found here. This issue is to discuss implementation details.

CORE TEAM TASK LIST

• Evaluate / Prioritize Feature Request
• Refine User Stories / Requirements
• Define Test Cases
• Design / Develop Solution
• Perform QA/Testing
• Update Documentation

[jmjatlanta]

It seems this is very much like the market fee. It is calculated at order execution time, and modifies the quantity of the asset sent or received. It is unlike an operation fee, that is deducted up-front at order creation time.

Prior to BSIP 74, no market fee was charged to the account that created the limit order that ended up going against the call order.

With BSIP 74, there will be a fee charged, which will go to the asset issuer. The fee amount is not based on asset_options.market_fee_percent but instead asset_options.extensions.margin_call_fee_ratio. This provides finer-grained control of fee amounts.

Note that this fee will only be charged to call orders that are matched to limit orders.

Please review and comment on my assumptions, as this will help to assure an implementation that matches the spirit of the BSIP.

[abitmore]

The spirit is "the call order gets charged" but not the limit order gets charged, although technically it's almost the same thing but with a shift on price.

[shulthz]

This fee must can be shared a part of it (e.g. like 20%) to the margin call buyer which can be set by the asset owner.
These shared fees must be continually unlocked during a vesting period like 48 hours.
This will encourage the buyer to eat the margin call, it's a very important part of this BSIP.

[jmjatlanta]

This fee must can be shared a part of it (e.g. like 20%) to the margin call buyer which can be set by the asset owner.
These shared fees must be continually unlocked during a vesting period like 48 hours.
This will encourage the buyer to eat the margin call, it's a very important part of this BSIP.

I do not see these requirements in the BSIP specifications. Was it agreed and voted upon elsewhere?

[shulthz]

This fee must can be shared a part of it (e.g. like 20%) to the margin call buyer which can be set by the asset owner.
These shared fees must be continually unlocked during a vesting period like 48 hours.
This will encourage the buyer to eat the margin call, it's a very important part of this BSIP.

I do not see these requirements in the BSIP specifications. Was it agreed and voted upon elsewhere?

I have give these requirements long times ago, but the author maybe didn't understand the spirit of this BSIP.

This BSIP have two main aims：

1. The margin call (with more lower MSSR) will not destroy the depth and price of DEX market like before;
2. The shared fees (with locked time) will encourage the buyers to eat the margin call:
   The shared fees (with locked time) will not be exploited by the leveraged market of CEX any more;
   The shared fees (with locked time) will not affect the depth and price of CEX market largely;
   It can instead of MSSR largely.

[bitcrab]

@jmjatlanta please ignore comments from @shulthz and work based on the BSIP itself.

[MichelSantos]

@dls-cipher @abitmore

The development of BSIP74 required extensive iterations because the original specifications were sometimes ambiguous, incomplete, or incompatible with all of the market situations and subtleties that are handled by the DEX mechanics. These high-level and low-level problems were identified through a series of development pushes which are documented in discussions during the first code pull request which continued during the creation of the second version of the specifications and continued further during the development towards the second version of the specifications.

A brief description of how margin calls are handled will provide some context of the encountered issues. Margin calls go through a two-step process that involves (1) matching a margin call against counter-offers on the order books, and (2) filling the margin call against the counter-offer. Both the matching process and filling process depends on such things as the "match price" and the "fill price". However those prices are highly dependent on other factors that were not addressed.

The development identified problems with the matching process in the original specifications:

• the matching process was not addressed at all

• the matching process needed to be handled differently between maker and taker margin calls because the match price is different

• the match price also depends on the new margin call fee

The development also identified problems with the filling process in the original specifications:

• the payer of the margin call fee was not identified

• the new margin call fee ratio (MCFR) may be incompatible with other parameters such as the maximum short squeeze ratio (MSSR)

• the fill price differs between maker and take margin calls due to BSIP-32: "Always Match Orders At Maker Price"

• the filling process must account for target collateral ratios, BSIP-38: "Add target collateral ratio option to short positions", which cannot naively use the match price because it must account for the new margin call fee

All of these problems have been fully defined and subsequently developed. A new pull request will be submitted later today with the code and unit tests.

A third version of the BSIP74 specifications, which summarizes the resolved requirements, will also be submitted afterwards in a new pull request.

[abitmore]

@MichelSantos thank you for the detailed info. Looking forward to the new commits.

[abitmore]

Done via #2180.