Update 0064-VALP-validator_performance_based_rewards.md

.github/workflows/config/markdownlint.json

@@ -1,9 +1,14 @@
-
 {
     "default": true,
     "line-length": false,
     "commands-show-output": false,
     "no-bare-urls": true,
     "no-inline-html": false,
-    "no-hard-tabs": false
+    "no-hard-tabs": false,
+    "MD012": {
+        "maximum": 2
+    },
+    "MD024": {
+        "siblings_only": true
+    }
 }

0000-TEMP-template-notes.md

@@ -0,0 +1,52 @@
+# 0000-TEMP decision notes
+
+## Context / Problem Statement 1
+
+|   Opened   | Last updated |    Status    |
+|:----------:|:------------:|:------------:|
+| DD/MM/YYYY |  DD/MM/YYYY  | open/resoved |
+
+Describe the context and problem statement...
+
+### Considered Options
+
+* Option 1...
+* Option 2...
+
+### Decision Outcome
+
+Chosen option: Option X, because... (include why paramemters are chosen, any dependancies and / or assumptions this decision is based upon)
+
+### Open risks
+
+* Risk 1 - details any risks or gaps that are not yet resolved
+
+### Limitations
+
+Are there any issues we wanted to address but could not e.g., A core rewrite or CometBFT limtitaion
+
+
+## Context / Problem Statement 2
+
+|   Opened   | Last updated |    Status    |
+|:----------:|:------------:|:------------:|
+| DD/MM/YYYY |  DD/MM/YYYY  | open/resoved |
+
+Describe the context and problem statement...
+
+### Considered Options
+
+* Option 1...
+* Option 2...
+
+### Decision Outcome
+
+Chosen option: Option X, because... (include why paramemters are chosen, any dependancies and / or assumptions this decision is based upon)
+
+### Open risks
+
+* Risk 1 - details any risks or gaps that are not yet resolved
+
+### Limitations
+
+Are there any issues we wanted to address but could not e.g., A core rewrite or CometBFT limtitaion

README.md

@@ -7,7 +7,7 @@ This repository contains specifications and RFCs for future changes to the syste
 In order to ensure that there is a clear view on the specification of the protocol, both at the version in mainnet and the version being developed in testnet, the following branching is used:
 
 - `master` branch details the specification of the protocol in mainnet (from Alpha Mainnet onwards)
-- `cosmicelevator` branch is the milestone grouping of features being developed AFTER Alpha Mainnet
+- `cosmicelevator` branch is the milestone grouping of features being developed AFTER Alpha Mainnet. As features are deployed to mainnet by the validators the relevant spec changes will be merged into the `master` branch.
 - Further milestone branches will be created as development progresses and will be updated in this `README.md`
 
 To find out more see the [The specification lifecycle](WORKFLOW.md#the-specification-lifecycle)

non-protocol-specs/0012-NP-LIPE-liquidation-price-estimate.md

@@ -0,0 +1,60 @@
+# Liquidation price estimate
+
+## Summary
+
+Provide an estimate of the price range at which the liquidation of a specified position is likely to occur.
+
+## Overview
+
+Provide a range of liquidation price, where the lower bound assumes no slippage in the [margin level calculation](../protocol/0019-MCAL-margin_calculator.md) and the upper bound assumes that the slippage cap is applied.
+
+This amounts to carrying out the same computation twice, once with both linear and quadratic slippage factor set to `0` and once with the actual values used by the market for which the specified position is being considered.
+
+The system carries out [position resolution](../protocol/0012-POSR-position_resolution.md) when the available collateral (amount in margin account for the market along with amount in the general account denominated in the same asset) is less than the maintenance margin level for the position. The first step is to cancel any open orders that a distressed party may have. After that the margin requirement is re-evaluated to see if the position is still distressed. Therefore we provide three sets of estimates of a liquidation price range: current open volume only, current open volume with active buy orders, current open volume with active sell orders.
+
+## Calculation
+
+### Position only
+
+We start with the case which estimates the liquidation price given the current open volume and ignoring any orders a party may have. We need to keep in mind that as the mark price moves the maintenance margin changes and the collateral available a party has changes due to [mark to market](../protocol/0003-MTMK-mark_to_market_settlement.md) gains/losses. Therefore, to estimate the liquidation price we need to find $S^{\text{liquidation}}$ such that:
+
+$$
+\text{collateral available} + V(S^{\text{liquidation}}-S^{\text{current}}) = \text{maintenance margin}(S^{\text{liquidation}}),
+$$
+
+where $V$ is the open volume (negative for a short position) and $S^\text{current}$ is the current mark price.
+
+We assume margin is calculated as per continuous trading formula (as there are no closeouts in auctions) and that the slippage cap always applies, therefore we get:
+
+$$
+\text{collateral available} + V(S^{\text{liquidation}}-S^\text{current}) = S^{\text{liquidation}} (V \cdot \text{linear slippage factor}+V^2 \cdot \text{quadratic slippage factor}+V \cdot \text{risk factor}),
+$$
+
+where $\text{risk factor}$ is the long risk factor when $V>0$ and the short risk factor otherwise. Solving for $S^{\text{liquidation}}$ we get:
+
+$$
+S^{\text{liquidation}} = \frac{\text{collateral available}-V \cdot S^\text{current}}{V \cdot \text{linear slippage factor}+V^2 \cdot \text{quadratic slippage factor}+V \cdot \text{risk factor}-V}
+$$
+
+if the denominator in the above expression evaluates to $0$ the liquidation price is undefined and we return an error, otherwise we return the result floored at $0$ (as the negative price is not attainable for any of the currently supported products).
+
+### Including orders
+
+When including orders we sort the orders in the order they will get filled in (descending for buy orders, ascending for sell orders) and assume any market orders get filled instantaneously at the current mark price. Then separately for each side:
+
+- Calculate open volume with including the remaining volume of all the market orders for a given side ($V$) and calculate the liquidation price ($S^{\text{liquidation}}$) using the formula outlined above and the current mark price or indicative uncrossing price if market is in auction ($S^{\text{current}}$).
+- For each limit order:
+  - if the order price ($S^{\text{order}}$) is above (buy side) / below (sell side) the liquidation price ($S^{\text{liquidation}}$):
+    - recalculate $V$ to include the order's remaining volume (assumes order gets filled as soon as its price level is filled),
+    - update $\text{collateral available}$ to include the MTM gains/losses:  $V(S^{\text{order}}-S^{\text{current}})$,
+    - update $S^{\text{current}}$ to equal $S^{\text{order}}$,
+  - otherwise return last calculated $S^{\text{liquidation}}$ (assumes other orders will get cancelled and the remaining position will be liquidated).
+
+### Acceptance criteria
+
+1. An estimate is obtained for a long position with no open orders, mark price keeps going down in small increments and the actual liquidation takes place within the estimated range. (<a name="0012-NP-LIPE-001" href="#0012-NP-LIPE-001">0012-NP-LIPE-001</a>)
+1. An estimate is obtained for a short position with no open orders, mark price keeps going up in small increments and the actual liquidation takes place within the estimated range.  (<a name="0012-NP-LIPE-002" href="#0012-NP-LIPE-002">0012-NP-LIPE-002</a>)
+1. An estimate is obtained for a position with no open volume and a single limit buy order, after the order fills the mark price keeps going down in small increments and the actual liquidation takes place within the obtained estimated range.  (<a name="0012-NP-LIPE-003" href="#0012-NP-LIPE-003">0012-NP-LIPE-003</a>)
+1. An estimate is obtained for a long position with multiple limit sell order with the absolute value of the total remaining size of the orders less than the open volume. The estimated liquidation price with sell orders is lower than that for the open volume only. As the limit orders get filled the estimated liquidation price for the (updated) open volume converges to the estimate originally obtained with open sell orders. (<a name="0012-NP-LIPE-004" href="#0012-NP-LIPE-004">0012-NP-LIPE-004</a>)
+1. An estimate is obtained for a short position with multiple limit sell order with the absolute value of the total remaining size of the orders less than the open volume. The estimated liquidation price with sell orders is lower than that for the open volume only. As the limit orders get filled the estimated liquidation price for the (updated) open volume converges to the estimate originally obtained with open sell orders. As the price keeps moving in small increments the liquidation happens within the originally estimated range (with sell orders) (<a name="0012-NP-LIPE-005" href="#0012-NP-LIPE-005">0012-NP-LIPE-005</a>)
+1. There's no difference in the estimate for an open volume and that with `0` open volume and market order of the same size. (<a name="0012-NP-LIPE-006" href="#0012-NP-LIPE-006">0012-NP-LIPE-006</a>)

protocol/0010-MARG-margin_orchestration.md

@@ -77,6 +77,11 @@ The protocol compares these levels to the balance in the trader's margin account
 | greater than  _collateral release level_       | Collateral release      | Collateral release
 | greater than _collateral search level_ and less than  _initial margin_  | no action     | No financial risk to network
 
+When posting a new order the initial margin for the overall position including the new order is calculated and order is only allowed to go ahead if party has enough funds to bring their margin account balance to that figure. An exception to this is when a party has an open position and tries to reduce it, but cannot afford the new margin. Then orders from the opposite side (short orders for a long position, long orders for a short position) are accepted as follows:
+
+- limit order: accept order when sum sizes of all the party's order's for that side of the book including the one being posted is less than or equal to the absolute open volume that a party has,
+- market order: accept order as long as its size is less than or equal to the absolute open volume that a party has.
+
 #### Collateral search
 
 When a trader's balance in their margin account (for a market) is less than their position’s collateral search level the protocol will attempt to transfer sufficient collateral from the trader’s main collateral account to top up their margin account to the level of the _initial margin_.

protocol/0014-ORDT-order_types.md

@@ -42,11 +42,11 @@ Notes on scope of current version of this spec:
 **Market-state:**
 
 1. **Good For Auction (GFA):** This order will only be accepted by the system if it arrives during an auction period, otherwise it will be rejected. The order can act like either a GTC or GTT order depending on whether the `expiresAt` field is set.
-1. **Good For Normal (GFN):** This order will only be accepted by the system if it arrived during normal trading, otherwise it will be rejected. Normal trading is defined as either continuous trading on a normal market or auction trading in a frequent batch auction market. The order can act like either a GTC or GTT order depending on whether the `expiresAt` field is set.
+2. **Good For Normal (GFN):** This order will only be accepted by the system if it arrived during normal trading, otherwise it will be rejected. Normal trading is defined as either continuous trading on a normal market or auction trading in a frequent batch auction market. The order can act like either a GTC or GTT order depending on whether the `expiresAt` field is set.
 
 ### Execution flags
 
-1. **Post-Only (True/False):** Only valid for Limit orders. Cannot be True at the same time as Reduce-Only. If set to true, once order reaches the orderbook, this order acts identically to a limit order set at the same price. However, prior to being placed a check is run to ensure that the order will not (neither totally nor in any part) immediately cross with anything already on the book. If the order would immediately trade, it is instead immediately `Stopped` with a reason informing the trader that the order was stopped to avoid a trade occurring. As a result, placing a Post-Only order will never incur taker fees.
+1. **Post-Only (True/False):** Only valid for Limit orders. Cannot be True at the same time as Reduce-Only. If set to true, once order reaches the orderbook, this order acts identically to a limit order set at the same price. However, prior to being placed a check is run to ensure that the order will not (neither totally nor in any part) immediately cross with anything already on the book. If the order would immediately trade, it is instead immediately `Stopped` with a reason informing the trader that the order was stopped to avoid a trade occurring. As a result, placing a Post-Only order will never incur taker fees, and will not incur fees in general if executed in continuous trading. It is possible for some liquidity and infrastructure fees to be paid if the resultant limit order trades at the uncrossing of an auction, as specified in [0029-FEES](https://github.com/vegaprotocol/specs/blob/master/protocol/0029-FEES-fees.md#normal-auctions-including-market-protection-and-opening-auctions).
 1. **Reduce-Only (True/False):** Only valid for Non-Persistent orders. Cannot be True at the same time as Post-Only. If set, order will only be executed if the outcome of the trade moves the trader's position closer to 0. In addition, a Reduce-Only order will not move a position to the opposite side to the trader's current position (e.g. if short, a Reduce-Only order cannot make the trader long as a result). If submitted as IOC, where the full volume would switch sides, only the amount required to move the position to 0 will be executed.
 
 ### Valid order entry combinations

protocol/0019-MCAL-margin_calculator.md

@@ -103,20 +103,14 @@ If `riskiest long == 0` then `maintenance_margin_long = 0`.
 
 In this simple methodology, a linearised margin formula is used to return the maintenance margin, using risk factors returned by the [quantitative model](./0018-RSKM-quant_risk_models.ipynb).
 
-`maintenance_margin_long = maintenance_margin_long_open_position + maintenance_margin_long_open_orders`
-
 with
 
 ```formula
-maintenance_margin_long_open_position 
-    = max(min(slippage_volume * slippage_per_unit, mark_price * (slippage_volume * market.maxSlippageFraction[1] + slippage_volume^2 * market.maxSlippageFraction[2])), 0) 
-    + slippage_volume * [ quantitative_model.risk_factors_long ] . [ Product.value(market_observable) ]
+maintenance_margin_long 
+    = max(min(riskiest_long * slippage_per_unit, product.value(market_observable)  * (riskiest_long * market.maxSlippageFraction[1] + riskiest_long^2 * market.maxSlippageFraction[2])), 0) 
+    +  max(open_volume, 0) * [ quantitative_model.risk_factors_long ] . [ Product.value(market_observable) ] + buy_orders * [ quantitative_model.risk_factors_long ] . [ Product.value(market_observable) ]`,
 ```
 
-and
-
-`maintenance_margin_long_open_orders = buy_orders * [ quantitative_model.risk_factors_long ] . [ Product.value(market_observable) ]`,
-
 where
 
 `slippage_volume =  max( open_volume, 0 )`,
@@ -125,7 +119,7 @@ and
 
 if `open_volume > 0` then
 
-`slippage_per_unit = Product.value(market_observable) - Product.value(exit_price)`,
+`slippage_per_unit = max(0, Product.value(market_observable) - Product.value(exit_price))`,
 
 else `slippage_per_unit = 0`.
 
@@ -149,25 +143,17 @@ If `riskiest short == 0` then `maintenance_margin_short = 0`.
 
 Else
 
-`maintenance_margin_short = maintenance_margin_short_open_position + maintenance_margin_short_open_orders`
-
-with
-
 ```formula
-maintenance_margin_short_open_position 
-    = max(min(abs(slippage_volume) * slippage_per_unit, mark_price * (abs(slippage_volume) *  market.maxSlippageFraction[1] + abs(slippage_volume)^2 * market.maxSlippageFraction[2])),  0) 
-    + abs(slippage_volume) * [ quantitative_model.risk_factors_short ] . [ Product.value(market_observable) ]
+maintenance_margin_short 
+    = max(min(abs(riskiest short) * slippage_per_unit, mark_price * (abs(riskiest short) *  market.maxSlippageFraction[1] + abs(slippage_volume)^2 * market.maxSlippageFraction[2])),  0) 
+    + abs(min( open_volume, 0 )) * [ quantitative_model.risk_factors_short ] . [ Product.value(market_observable) ] + abs(sell_orders) * [ quantitative_model.risk_factors_short ] . [ Product.value(market_observable) ]`
 ```
 
-and
-
-`maintenance_margin_short_open_orders = abs(sell_orders) * [ quantitative_model.risk_factors_short ] . [ Product.value(market_observable) ]`,
-
 where meanings of terms in Step 1 apply except for:
 
 `slippage_volume = min( open_volume, 0 )`,
 
-`slippage_per_unit = -1 * (Product.value(market_observable) - Product.value(exit_price) )`
+`slippage_per_unit = max(0, Product.value(exit_price)-Product.value(market_observable))`
 
 ### **Step 3**
 
@@ -224,10 +210,13 @@ bids: [
     {volume: 7, price: $108}
 ]
 
+market.maxSlippageFraction[1] = 0.25
+market.maxSlippageFraction[2] = 0.001
+
 risk_factor_short = 0.11
 risk_factor_long = 0.1
 
-last_trade = $144
+mark_price = $144
 
 search_level_scaling_factor = 1.1
 initial_margin_scaling_factor = 1.2
@@ -244,29 +233,28 @@ riskiest_short = min( open_volume + sell_orders, 0 ) =  min( 10 - 8, 0 ) = 0
 
 ## exit price considers what selling the open position (10) on the order book would achieve.
 
-slippage_per_unit =  Product.value(previous_mark_price) - Product.value(exit_price) = Product.value($144) - Product.value((1*120 + 4*110 + 5*108)/10) = 144 - 110  = 34
+slippage_per_unit =  max(0, Product.value(previous_mark_price) - Product.value(exit_price)) = max(0, Product.value($144) - Product.value((1*120 + 4*110 + 5*108)/10)) = max(0, 144 - 110)  = 34
 
-slippage_volume =  max( open_volume, 0 ) = max ( 10, 0 ) = 10
 
+maintenance_margin_long =max(min(riskiest_long * slippage_per_unit, product.value(market_observable)  * (riskiest_long * market.maxSlippageFraction[1] + riskiest_long^2 * market.maxSlippageFraction[2])), 0) 
+ + max(open_volume, 0 ) * [ quantitative_model.risk_factors_long ] . [ Product.value(market_observable) ] + buy_orders * [ quantitative_model.risk_factors_long ] . [ Product.value(market_observable) ]
 
-maintenance_margin_long = max(slippage_volume * slippage_per_unit, 0) + slippage_volume * [ quantitative_model.risk_factors_long ] . [ Product.value(market_observable) ] + buy_orders * [ quantitative_model.risk_factors_long ] . [ Product.value(market_observable) ]
 
-= max(10 * 34, 0) +  10 * 0.1 * 144 + 4 * 0.1 * 144 =  541.6
+=  max(min(14 * 34, 144*(14 * 0.25 + 14 * 14 * 0.001), 0) + 10 * 0.1 * 144 + 4 * 0.1 * 144 = max(min(476, 532.224), 0) + 10 * 0.1 * 144 + 4 * 0.1 * 144 = 677.6
 
 # Step 2
 
 Since riskiest short == 0 then maintenance_margin_short = 0
 
 # Step 3
 
-maintenance_margin = max ( 541.6, 0) = 541.6
+maintenance_margin = max ( 677.6, 0) = 677.6
 
 # Step 4
 
-collateral_release_level = 541.6 * collateral_release_scaling_factor = 541.6 * 1.1
-initial_margin = 541.6 * initial_margin_scaling_factor = 541.6 * 1.2
-search_level = 541.6 * search_level_scaling_factor = 541.6 * 1.3
-
+collateral_release_level = 677.6 * collateral_release_scaling_factor = 677.6 * 1.1
+initial_margin = 677.6 * initial_margin_scaling_factor = 677.6 * 1.2
+search_level = 677.6 * search_level_scaling_factor = 677.6 * 1.3
 
 ```
 
@@ -286,30 +274,18 @@ riskiest long: 2
 
 riskiest short: -1
 
-slippage volume long: 1
-
-slippage volume short: 0
-
 #### *case-2*
 
 riskiest long: 1
 
 riskiest short: -1
 
-slippage volume long: 0
-
-slippage volume short: -1
-
 #### *case-3*
 
 riskiest long: 1
 
 riskiest short: -1
 
-slippage volume long: 1
-
-slippage volume short: 0
-
 ## SCENARIOS
 
 Scenarios found [here](https://docs.google.com/spreadsheets/d/1VXMdpgyyA9jp0hoWcIQTUFrhOdtu-fak/edit#gid=1586131462)