Skip to content

Commit

Permalink
feat(palazzo): Merge palazzo into master (#2183)
Browse files Browse the repository at this point in the history
* feat: remove redundant AC 013

* feat: address comments

* feat: remove duplicated ACs

* feat: remove duplicated ACs

* feat: rename network parameter FeeDiscountDecay

* feat: add governance proposal change market name

* chore: typo

* feat: address comments

* feat: typo

* chore: add ACs to features file for overnance proposal market name

* Insurance pools of closed / settled markets to go to on - chain treasury (#2065)

* feat: insurance pool redistribution

* feat: add more updates

* chore: markdown

* chore: remove old AC

* feat: address comments

Co-authored-by: David Siska <62546419+davidsiska-vega@users.noreply.github.com>

* feat: address comments

Co-authored-by: David Siska <62546419+davidsiska-vega@users.noreply.github.com>

* feat: address comments

* feat: update spec 0015

* chore: markdown

* chore: typo

---------

Co-authored-by: David Siska <62546419+davidsiska-vega@users.noreply.github.com>

* feat: add more ACs to isolated margin

* chore: markdown

* chore: markdown

* feat: add more ACs

* chore: markdown

* chore: markdown

* chore: typo

* feat: address comments

* chore: typo

* Remove a duplicate AC (#2073)

* fix: Removed duplicate AC

* fix: Removed duplicate AC

* fix: formula in ac

* fix: diff twap if auct was included

* feat: tidy up and add more ACS

* chore: reorder

* chore: format

* fix: MD and spelling checks

* feat: add ACs for switch margin modes

* feat: update closeout

* feat: update closeout

* chore: remove mystery AC

* feat: address commments from Tom

* chore: typo

* fix: AC 0053-PERP-030 now flexes the boundary

* fix: formatting

* Update protocol/0053-PERP-product_builtin_perpetual_future.md

Co-authored-by: Gordsport <83510148+gordsport@users.noreply.github.com>

* fix: another formatting issue

* feat: A couple more ACs, API clarifications and Removing excessive margin check (#2076)

* feat: add alias to public keys

* feat: add allow list to teams

* feat: align spec with core change adding JoinTeam

* chore: assign ac codes

* chore: remove mentions of alias

* feat: stop order position linked (#2043)

* feat: Stop order changes

* fix: correct expected behaviour

* chore: duplicate ac

* fix: address comments

* feat: update for pegged order in isolated margin

* feat: update json

* chore: markdown

* feat: more margin pegged order acs

* fix: typo marging > margin

* fix: duplicate ac code

* fix: more marging typo

* refactor: remove two acs

* chore: add 165 back in

* chore: position of ac corrected for diff

* feat: update AC

* feat: add back pegged order AC

* chore: markdown

* chore: typo

* feat: update market state duing name changing

* feat: address comment

* chore: typo

* feat: mark price updates ACs

* fix: replace withdrawal limit > maximumLifetimeDeposit

* fix: spellcheck

* feat: update meaning of closed and allow_list team fields (#2090)

* feat: change meaning of closed and allow_list

* chore: reassign AC codes

* fix: update wordlist

* feat: add two system-test acs

* feat: clarify market has no pm params

* fix: update ac numbers

* fix: still dup ac numbers

* feat: update AC and add more AC

* chore: tidy up

* chore: markdown

* feat: address comments

* chore: markdown

* chore: add timing

* chore: typo

* chore: Add AC code to the featurtes.json

Also sneaking in a categories tidy up

* fix: duplicated AC codes in features.json

* feat: address comment

* feat: EthL2s

* fix: better name

* fix: clarity on what is meant by L2

* chore: add initial AC codes and fix linting

* fix: codeblock formatting

* fix: milestone name

* chore: Add ACs from the Eth spec to the L2 spec

* fix: review comment

* fix: MD linting

* fix: approbation linting

* fix: clarity on what is meant by L2

* feat: few acs for stop orders in auction

* fix: updated ac numbers

* fix: still dup acs

* fix: removed AC codes and add L2 clarification

* feat: added one more ac

* feat: add acs for network profit and loss

* fix: update for markdownlint

* fix: update for spellcheck

* fix: clarity on what is meant by L2

* fix: MD linting and add AC code to file

* fix: MD linting and spellings

* fix: spelling linting

* chore: add AC code to existing AC (#2102)

Adds an AC code to an AC that had one missing.

* feat: add more acs

* feat: add ac for first mark price

* chore: markdown

* feat: add more ac

* feat: update AC 001

* chore: address comments

Co-authored-by: David Siska <62546419+davidsiska-vega@users.noreply.github.com>

* chore: address comment

* chore: typo

* feat: add more AC for validation

* chore: typo

* chore: markdown

* chore: address comment

* feat: add validation ac for mark price

* fix: post-research call edits

* refactor: scale funding payment down (auction)

* refactor: apply suggestions from code review

Co-authored-by: David Siska <62546419+davidsiska-vega@users.noreply.github.com>

* feat: add liquidation acs

* fix: correct typo in features

* chore: update AC codes for rebase

* fix: markdown

* feat: add AC 126

* chore: Add more perps funding ACs (#2110)

* chore: Add more perps funding ACs

Adds more perps funding ACs from the AC review meeting

Note the ACs mentioned for:
- vegaprotocol/vega#10254
- vegaprotocol/vega#10255

Have NOT yet been added as the core side work has not been scheduled. A note has been added to the core issue

* chore: Add AC code to the features.json file

* fix: spelling

* fix: spelling

* fix: more spelling

* fix: AC wording

Co-authored-by: David Siska <62546419+davidsiska-vega@users.noreply.github.com>

---------

Co-authored-by: David Siska <62546419+davidsiska-vega@users.noreply.github.com>

* fix: add missing AC codes to the featurews.json file

Adds in the missing margin, markprice and perp AC codes

* chore: Add ACs from the LP fee setting AC review meeting (#2115)

* chore: Add ACs from the LP fee setting AC review meeting

This PR adds new ACs from the LP fee setting AC review meeting.

* fix: add codes to features.json

* fix: add AC clarification

* fix: wording from review comment

Co-authored-by: David Siska <62546419+davidsiska-vega@users.noreply.github.com>

* fix: fill in value

---------

Co-authored-by: David Siska <62546419+davidsiska-vega@users.noreply.github.com>

* fix: liq fee setting method market update

* chore: comment out the cosmic-carryover (#2120)

* chore: comment out the cosmic-carryover

This comments out the cosmic carry over ACs so that the approbation stats reflect just the palazzo ACs

* fix: syntax error

* feat: more validation acs

* fix: correct the AC requirement to match the correct behaviour (#2111)

* fix: correct the AC requirement to match the correct behaviour

* feat: corrected ac and added 2 more

* fix: duplicated AC codes

* fix: json syntax error

* fix: Extra AC codes

---------

Co-authored-by: Sohill-Patel <85170301+Sohill-Patel@users.noreply.github.com>

* chore: update features.json (#2123)

In order to have the correct reporting on palazzo AC coverage I have remove some ACs that will NOT be done:

insurance pool re-dist:


0073-LIMN-115
0073-LIMN-116
0073-LIMN-117

perps/sucessor markets:
0015-INSR-005
0081-SUCM-036

We do not support sucessor and perps and we are not supporting LNL

* chore: split AC code 056 into 3 (#2126)

Splits the AC code 056 into 3 parts and adds one new AC.

All to be done as system tests

* chore: adds AC from the isolated margin AC review (#2125)

* chore: adds AC from the isolated margin AC review

Adds in protocol upgrade AC coverage for isolated margin as per the isolated margin AC review meeting

* chore: Update AC to be more clear

Co-authored-by: Sohill-Patel <85170301+Sohill-Patel@users.noreply.github.com>

---------

Co-authored-by: Sohill-Patel <85170301+Sohill-Patel@users.noreply.github.com>

* chore Update features.json to add missing AC code (#2127)

* chore Update features.json to add missing AC code

Adds the following missing AC to the features file:

"0087-EVMD-043"

* fix: remove "0053-PERP-036", as its a nebula AC

* chore: add more position stop order AC codes (#2109)

* chore: add more position stop order AC codes

Adds in ACs from the position stop orders feature AC review

* fix: linting checks

* fix: review comment

* fix: reduce ethereum rpc data source flexibility

* fix: reduce ethereum rpc data source flexibility

* fix: AC code approbation check fail

* feat: add AC 003 for mark price

* chore: update json file

* feat: update ac 027

* chore: grammar

* feat: update initial margin level in isolated margin

* chore: grammar

Co-authored-by: candida-d <62548908+candida-d@users.noreply.github.com>

* chore: typo

Co-authored-by: candida-d <62548908+candida-d@users.noreply.github.com>

* feat: change tau scaling bound

* feat: update bound

* feat: update probability of trading in LP score

* chore: address comment

Co-authored-by: David Siska <62546419+davidsiska-vega@users.noreply.github.com>

* chore: markdown

* chore: descope AC 0053-PERP-035 from Palazzo (#2135)

based on a research / protocol design discussion this PR descopes AC 0053-PERP-035 from Palazzo

* fix: Updating AC to cover wrong side stop orders being rejected

* feat: add party profile feature

* feat: add anti alias squatting feature

* Revert "feat: add anti alias squatting feature"

This reverts commit 6c3f548.

* chore: correct restriction typos

* feat: add validation and defaults for new network parameters

* feat: add ac for price via data node

* feat: update json file

* chore: remove ACs from palazzo (#2140)

0009-MRKP-133 and 0053-PERP-043 will be moved to Nebula in a new PR

* refactor: update liquidation price estimate

* chore: add feature file for 0012-NP-LIPE ACs

* refactor: add spec for position estimate

* chore: Update features.json

* chore: renove dupe AC from features file (#2151)

* chore: add deatails about the max proposals in a batch

This updates the spec to details the max number of proposals that can be submitted in a single batch proposal

* chore: add teams spam protection (#2157)

Copies the changes made to the Colosseo branch here:

- #2156

* feat: add ac to 0019

* chore: add features.json entries

* fix: dupe ACs

* chore: add update team spam ACs (#2159)

* chore: add update team spam ACs

Adds in ACs for also updating referral sets / teams and spam protection

* fix: spelling

* chore: Update protocol/0062-SPAM-spam_protection.md

Co-authored-by: Jiajia-Cui <92106936+Jiajia-Cui@users.noreply.github.com>

* chore: Update protocol/features.json

Co-authored-by: Jiajia-Cui <92106936+Jiajia-Cui@users.noreply.github.com>

* fix: net param name

---------

Co-authored-by: Jiajia-Cui <92106936+Jiajia-Cui@users.noreply.github.com>

* feat: add more ACs

* chore: typo

* feat: market update ACs for mark price and perps price (#2171)

* feat: market update ACs for mark price and perps price

* feat: market update ACs for mark price and perps price

* feat: market update ACs for mark price and perps price

* feat: market update ACs for mark price and perps price

* feat: market update ACs for mark price and perps price

* feat: market update ACs for mark price and perps price

* chore: add ACs to feature.json file

---------

Co-authored-by: gordsport <gordon@vegaprotocol.io>

* refactor: AC clarifications

* refactor: amend 0012-NP-LIPE-005

* refactor: clarify and extend liquidation ACs

* refactor: additional clarifications

* feat: Add extra validator ranking reward metric AC (#2174)

* feat: Add extra validator ranking reward metric AC

Adds an extra validator ranking reward metric AC:

For reward metrics relating to trading, an individual must meet the staking requirement AND notional time-weighted average position requirement) set in the recurring transfer. If they do not then their reward metric is set to 0. Note, these requirements do not apply to the validator ranking metric or the market creation reward metric.

e.g. For a party that is a consensus or standby validator, the staking requirement and notional time-weighted average position requirement do not apply to their validator ranking metric

* chore: split AC into 3

* fix: remove old AC

* refactor: amend a few perp ACs

* chore: remove dup ac

* refactor: modify AC

* feat: clarify and add ac for gov suspend and resume

* fix: duplicate ac code

* fix: dup ac codes

* fix: conflicts and spell / md lint checks

* fix: missed dupe ACs

* chore: remove spot

---------

Co-authored-by: Jiajia-Cui <jiajia@vega.xyz>
Co-authored-by: Jiajia-Cui <92106936+Jiajia-Cui@users.noreply.github.com>
Co-authored-by: David Siska <62546419+davidsiska-vega@users.noreply.github.com>
Co-authored-by: Pete Barrow <62435083+peterbarrow@users.noreply.github.com>
Co-authored-by: Sohill-Patel <85170301+Sohill-Patel@users.noreply.github.com>
Co-authored-by: Witold <witold@vega.xyz>
Co-authored-by: wwestgarth <william@vega.xyz>
Co-authored-by: wwestgarth <westgarth.w@gmail.com>
Co-authored-by: Tom <tom@vegaprotocol.io>
Co-authored-by: Charlie <charlie@vegaprotocol.io>
Co-authored-by: Charlie <99198652+cdummett@users.noreply.github.com>
Co-authored-by: Witold <gawlikowicz@gmail.com>
Co-authored-by: candida-d <62548908+candida-d@users.noreply.github.com>
Co-authored-by: Pete Barrow <pete@vega.xyz>
Co-authored-by: Jeremy Letang <me@jeremyletang.com>
  • Loading branch information
16 people committed Feb 22, 2024
1 parent e3e9539 commit ce97ac0
Show file tree
Hide file tree
Showing 52 changed files with 3,118 additions and 1,178 deletions.
3 changes: 2 additions & 1 deletion .github/workflows/quality_check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ name: "Quality checks"
branches:
- master
- cosmicelevator
- palazzomistero
- palazzo
- colosseo

env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
There are parameters within Vega that influence the behaviour of the system:

- some are set in genesis block but fixed once network is running,
- while others are changeable by on-chain [governance](../protocol/0028-GOVE-governance.md) but initialised to genesis values during network launch. For more info see [network paramters](../protocol/0054-NETP-network_parameters.md)
- while others are changeable by on-chain [governance](../protocol/0028-GOVE-governance.md) but initialised to genesis values during network launch. For more info see [network parameters](../protocol/0054-NETP-network_parameters.md)

On [Sweetwater (Restricted Mainnet) Release](https://github.com/orgs/vegaprotocol/projects/114) Vega Team wishes to control how certain parameters are initialised while letting validators change others as they see fit.
As the process of decentralisation progresses Vega Team the number of such parameters will be reduced.
Expand All @@ -22,8 +22,8 @@ The values to be specified as a PR against ??? repo.

| Name | Comment | Suggested value (optional) |
|-------------------------------------------------------------|:------------------------------------------------------------------:| :-------------------------:|
| `min number of validators` (not in sweetwater) | Not in [network paramters](../protocol/0054-NETP-network_parameters.md) | |
| `validator min balance` | Not in [network paramters](../protocol/0054-NETP-network_parameters.md) | 3000 VEGA |
| `min number of validators` (not in sweetwater) | Not in [network parameters](../protocol/0054-NETP-network_parameters.md) | |
| `validator min balance` | Not in [network parameters](../protocol/0054-NETP-network_parameters.md) | 3000 VEGA |
| `governance.proposal.updateNetParam.requiredMajority` | So that what is set in genesis cannot be changed too easily | 0.5 |
| `governance.proposal.updateNetParam.requiredParticipation` | So that what is set in genesis cannot be changed too easily | 0.5 |
| `validators.epoch.length` | Rewards currently make an assumption on epoch length, best fix it. | 1 day |
Expand Down
21 changes: 12 additions & 9 deletions non-protocol-specs/0012-NP-LIPE-liquidation-price-estimate.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Provide an estimate of the price range at which the liquidation of a specified p

Provide an estimated liquidation price range, 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.
This amounts to carrying out the same computation twice, once with slippage factor set to `0` and once with the actual value 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.

Expand All @@ -27,13 +27,13 @@ where $V$ is the open volume (negative for a short position) and $S^\text{curren
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}) + V \cdot \text{constant},
\text{collateral available} + V(S^{\text{liquidation}}-S^\text{current}) = S^{\text{liquidation}} (\abs{V} \cdot \text{linear slippage factor}+\abs{V} \cdot \text{risk factor}) + V \cdot \text{constant},
$$

where $\text{risk factor}$ is the long risk factor when $V>0$ and the short risk factor otherwise. The $\text{constant}$ is an optional arbitrary constant scaling with open volume added to the maintenance margin, e.g. the funding payment portion of the margin for [perpetual futures](../protocol/0053-PERP-product_builtin_perpetual_future.md#5-margin-considerations). Solving for $S^{\text{liquidation}}$ we get:

$$
S^{\text{liquidation}} = \frac{\text{collateral available}-V \cdot S^\text{current} - V \cdot \text{constant}}{V \cdot \text{linear slippage factor}+V^2 \cdot \text{quadratic slippage factor}+V \cdot \text{risk factor}-V}
S^{\text{liquidation}} = \frac{\text{collateral available}-V \cdot S^\text{current} - V \cdot \text{constant}}{\abs{V} \cdot \text{linear slippage factor}+\abs{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).
Expand All @@ -46,15 +46,18 @@ When including orders we sort the orders in the order they will get filled in (d
- 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 $\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>)
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 for cross-margin mode with `include_collateral_increase_in_available_collateral` set to `true` is obtained for a long position with multiple limit sell orders with the absolute value of the total remaining size of the orders less than the open volume. The general account balance should be set to `0` in the query and the margin account balance should be set to the maintenance margin for the chosen position. Orders should be chosen so that the liquidation price estimate with sell orders is non-zero (otherwise the party is collateralised up to a point that it will never get liquidated if these orders fill). 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 for cross-margin mode with `include_collateral_increase_in_available_collateral` set to `true` is obtained for a short position with multiple limit buy orders with the absolute value of the total remaining size of the orders less than the open volume. The general account balance should be set to `0` in the query and the margin account balance should be set to the maintenance margin for the chosen position. The estimated liquidation price with buy orders is higher 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 buy orders. As the price keeps moving in small increments the liquidation happens within the originally estimated range (with buy 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 (use `open_volume_only` field) and that with `0` open volume and market order of the same size (use `including_buy_orders` or `including_sell_orders` depending on the order side). (<a name="0012-NP-LIPE-006" href="#0012-NP-LIPE-006">0012-NP-LIPE-006</a>)
1. When margining mode gets successfully changed to isolated margin mode and party has non-zero general account balance afterwards than its liquidation price estimate for all cases (position only, with buy orders, with sell orders) moves closer to the current mark price (compared to cross-margin figure). (<a name="0012-NP-LIPE-007" href="#0012-NP-LIPE-007">0012-NP-LIPE-007</a>)
1. An estimate for isolated margin mode with `include_collateral_increase_in_available_collateral` set to `true` is obtained for a short position with open sell orders. As the price keeps moving in small increments the liquidation happens within the originally estimated range (`open_volume_only` estimate). The sell orders and order margin account balance remain unchanged. (<a name="0012-NP-LIPE-008" href="#0012-NP-LIPE-008">0012-NP-LIPE-008</a>)
1. An estimate for isolated margin mode with `include_collateral_increase_in_available_collateral` set to `true` is obtained for a long position with open buy orders. As the price keeps moving in small increments the liquidation happens within the originally estimated range (`open_volume_only` estimate). The buy orders and order margin account balance remain unchanged. (<a name="0012-NP-LIPE-009" href="#0012-NP-LIPE-009">0012-NP-LIPE-009</a>)
58 changes: 58 additions & 0 deletions non-protocol-specs/0013-NP-POSE-position-estimate.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Position estimate

## Summary

Protocol provides an API endpoint which can estimate the following aspects of a theoretical position (open volume and open orders):

- margin levels,
- expected collateral increase required to support the position,
- liquidation price.

Each estimate is a range between a relevant figure obtained with the assumption of no slippage and maximum slippage configured for the market.

## Details

The endpoint does not access information related to any of the existing positions, it's based entirely on the information specified in the request.
The endpoint only distinguishes between market orders (these are assumed to fill instantly and in full at a current mark price) and limit orders (these are assumed to fill in full once mark price reaches their limit price).

### Margin level

Margin level estimate contains the levels specified in [0019-MCAL-margin_calculator](./../protocol/0019-MCAL-margin_calculator.md#reference-level-explanation) spec as well margin mode and margin factor (0 in cross margin mode).

### Collateral increase estimate

Collateral increase estimate provides an approximate difference between the current collateral and the resulting collateral for the specified theoretical position.

In isolated margin mode it's the difference between collateral required to support the specified position and orders with the margin factor provided and the balance of margin and order margin accounts specified in the request.

In cross-margin mode:

- if the collateral required for the specified position is higher than the combined margin and order margin account balances then it's the difference between the initial margin level for the specified position and the sum of those account balances.
- if the collateral required for the specified position is lower than the combined margin and order margin account balances then:
- if the combined account balances are above the margin release level for the specified position: it's the difference between the initial margin level for the specified position and the sum of those account balances,
- otherwise it's `0`.

### Liquidation price estimate

Liquidation price estimate as specified in [0012-NP-LIPE-liquidation-price-estimate](./0012-NP-LIPE-liquidation-price-estimate.md).

Depending on the [margining mode](../protocol/0019-MCAL-margin_calculator.md#margining-modes) selected by the party for the market on which its position is being considered the $\text{collateral available}$ will differ.

Cross-margin mode: $\text{collateral available} = \text{margin account balance} + \text{general account balance} + \text{order margin account balance}$.

Isolated margin mode: $\text{collateral available} = \text{margin account balance}$.

The position estimate request has an additional `include_collateral_increase_in_available_collateral` argument. It's relevant for the isolated margin mode: when set to `false` the collateral available used in liquidation price estimate will be the margin account balance only. When set to `true` the portion of the collateral increase estimated for the specified position only (not for the additional orders) will also be included in the available collateral.

The endpoint request contains additional optional argument `scale_liquidation_price_to_market_decimals`. When set to `false` the liquidation price estimates are scaled to asset decimal places, when set to `true` these estimates are scaled to market decimal places.

## Acceptance criteria

1. In isolated margin mode the request with `0` open volume and one or more limit orders specified results in a non-zero order margin in the margin level estimate and margin mode correctly representing isolated margin mode. (<a name="0013-NP-POSE-001" href="#0013-NP-POSE-001">0013-NP-POSE-001</a>)
1. When account balances are set to `0` and market has slippage factors set to `0`, the collateral increase figure per specified theoretical position correctly approximates (absolute relative difference of less than $10^{-6}$) the actual margin and order margin account balances for a party which opens such a position. (<a name="0013-NP-POSE-002" href="#0013-NP-POSE-002">0013-NP-POSE-002</a>)
1. For a market with slippage cap factor set to `0`, when the response for a given request contains figure `x` as the collateral increase (best and worst case should be the same) then resubmitting the request with margin account balance increased by `x` should result in `0` collateral increase estimate. When increasing the margin account balance in the request further the collateral increase should get negative by the amount of the increase when in isolated margin mode. In cross margin mode it should remain at `0` until the combined margin and order balances are above the margin release level for the theoretical position. Then the collateral increase amount should be negative and equal to: `initial margin level for the specified position - margin account balance - order account balance`. (<a name="0013-NP-POSE-009" href="#0013-NP-POSE-009">0013-NP-POSE-009</a>)
1. In isolated margin mode increasing general account balance specified in the request has no impact on the collateral increase estimate and the liquidation price estimate. (<a name="0013-NP-POSE-004" href="#0013-NP-POSE-004">0013-NP-POSE-004</a>)
1. In isolated margin mode the liquidation price estimate for a position with non-zero additional margin requirement with `include_collateral_increase_in_available_collateral` argument set to `true` results in liquidation price which is closer to the current mark price than the result obtained with argument set to `false`. (<a name="0013-NP-POSE-005" href="#0013-NP-POSE-005">0013-NP-POSE-005</a>)
1. When market is set with different number of decimal places then its settlement asset then setting `scale_liquidation_price_to_market_decimals` to `false` results in liquidation price estimates scaled to asset decimal places, when set to `true` these estimates get scaled to market decimal places. (<a name="0013-NP-POSE-006" href="#0013-NP-POSE-006">0013-NP-POSE-006</a>)
1. The estimates for open volume of `1` and no orders are the same as those for open volume of `0` and a single buy market order of size `1`. (<a name="0013-NP-POSE-007" href="#0013-NP-POSE-007">0013-NP-POSE-007</a>)
1. The estimates for open volume of `-1` and no orders are the same as those for open volume of `0` and a single sell market order of size `1`. (<a name="0013-NP-POSE-008" href="#0013-NP-POSE-008">0013-NP-POSE-008</a>)
Loading

0 comments on commit ce97ac0

Please sign in to comment.