diff --git a/protocol/0042-LIQF-setting_fees_and_rewarding_lps.md b/protocol/0042-LIQF-setting_fees_and_rewarding_lps.md deleted file mode 100644 index 051c1dbe5..000000000 --- a/protocol/0042-LIQF-setting_fees_and_rewarding_lps.md +++ /dev/null @@ -1,508 +0,0 @@ -# Setting fees and rewarding liquidity providers - -## Summary - -The aim of this specification is to set out how fees on Vega are set based on committed liquidity provider stake and prevailing open interest on the market leading to [target stake](../protocol/0041-TSTK-target_stake.md). Let us recall that liquidity providers can commit and withdraw stake by submitting / amending a special [liquidity commitment transaction](./0044-LIME-lp_mechanics.md). - -## Definitions / Glossary of terms used - -- **`market.value.windowLength`**: sets the length of the window over which we estimate the market growth. This is a network parameter. -- **Target stake**: as defined in [target stake spec](./0041-TSTK-target_stake.md). The ideal amount of stake LPs would commit to a market. -- `market.liquidityProvision.minLpStakeQuantumMultiple`: There is a network wide parameter specifying the minimum LP stake as the `quantum` specified per asset, see [asset framework spec](../protocol/0040-ASSF-asset_framework.md). - -## Calculating the Liquidity Fee Factor - -There are three methods for setting the liquidity fee factor, with the default method being the 'Marginal Cost method.' The liquidity fee setting mechanism is configured per market as part of the market proposal. - -### Marginal Cost method - -The [liquidity fee factor](./0029-FEES-fees.md) is an input to the total taker fee that a price taker of a trade pays: - -`total_fee = infrastructure_fee + maker_fee + liquidity_fee` - -`liquidity_fee = fee_factor[liquidity] x trade_value_for_fee_purposes` - -As part of the [commit liquidity network transaction](./0044-LIME-lp_mechanics.md#commit-liquidity-network-transaction), the liquidity provider submits their desired level for the [liquidity fee factor](./0042-LIQF-setting_fees_and_rewarding_lps.md) for the market. Here we describe how this fee factor is set from the values submitted by all liquidity providers for a given market. -First, we produce a list of pairs which capture committed liquidity of each LP together with their desired liquidity fee factor and arrange this list in an increasing order by fee amount. Thus we have - -```text -[LP-1-stake, LP-1-liquidity-fee-factor] -[LP-2-stake, LP-2-liquidity-fee-factor] -... -[LP-N-stake, LP-N-liquidity-fee-factor] -``` - -where `N` is the number of liquidity providers who have committed to supply liquidity to this market. Note that `LP-1-liquidity-fee-factor <= LP-2-liquidity-fee-factor <= ... <= LP-N-liquidity-fee-factor` because we demand this list of pairs to be sorted in this way. - -We now find the smallest integer `k` such that `[target stake] < sum from i=1 to k of [LP-i-stake]`. In other words we want in this ordered list to find the liquidity providers that supply the liquidity that's required. If no such `k` exists we set `k=N`. - -Finally, we set the liquidity-fee-factor for this market to be the fee `LP-k-liquidity-fee-factor`. - -#### Example for fee setting mechanism using the marginal cost method - -In the example below there are 3 liquidity providers all bidding for their chosen fee level. The LP orders they submit are sorted into increasing fee order so that the lowest fee bid is at the top and the highest is at the bottom. The fee level chosen for the market is derived from the liquidity commitment of the market (`target stake`) and the amount of stake committed from each bidder. Vega processes the LP orders from top to bottom by adding up the commitment stake as it goes until it reaches a level greater than or equal to the `target stake`. When that point is reached the fee used is the fee of the last liquidity order processed. - -```text -[LP 1 stake = 120 ETH, LP 1 liquidity-fee-factor = 0.5%] -[LP 2 stake = 20 ETH, LP 2 liquidity-fee-factor = 0.75%] -[LP 3 stake = 60 ETH, LP 3 liquidity-fee-factor = 3.75%] -``` - -1. If the `target stake = 119` then the needed liquidity is given by LP 1, thus `k=1` and so the market's liquidity-fee-factor is `LP 1 fee = 0.5%`. -1. If the `target stake = 123` then the needed liquidity is given by LP 1 and LP 2, thus `k=2` and so the market's liquidity-fee-factor is `LP 2 fee = 0.75%`. -1. If the `target stake = 240` then even putting all the liquidity supplied above does not meet the estimated market liquidity demand and thus we set `k=N` and so the market's liquidity-fee-factor is `LP N fee = LP 3 fee = 3.75%`. -1. Initially (before market opened) the `[target stake]` is by definition zero (it's not possible to have a position on a market that's not opened yet). Hence by default the market's initial liquidity-fee-factor is the lowest liquidity-fee-factor. - - -### Stake-weighted-average method for setting the liquidity fee factor - -The liquidity fee factor is set as the weighted average of the liquidity fee factors, with weights assigned based on the supplied stake from each liquidity provider. - -#### Example for fee setting mechanism using the Stake-weighted-average method - -In the example below there are 3 liquidity providers all bidding for their chosen fee level. The overall liquidity fee factor is the weight-average of their nominations: - -```text -[LP 1 stake = 120 ETH, LP 1 liquidity-fee-factor = 0.5%] -[LP 2 stake = 20 ETH, LP 2 liquidity-fee-factor = 0.75%] -[LP 3 stake = 60 ETH, LP 3 liquidity-fee-factor = 3.75%] - -then - -liquidity-fee-factor = ((120 * 0.5%) + (20 * 0.75%) + (60 * 3.75%)) / (120 + 20 + 60) = 1.5% -``` - -### "Constant Liquidity Fee" Method - -The liquidity fee factor is set to a constant directly as part of the market proposal. - -#### Example for fee setting mechanism using the constant method - -In the example below there are 3 liquidity providers all bidding for their chosen fee level and the overall liquidity fee factor is: - -```text -[LP 1 stake = 120 ETH, LP 1 liquidity-fee-factor = 0.5%] -[LP 2 stake = 20 ETH, LP 2 liquidity-fee-factor = 0.75%] -[LP 3 stake = 60 ETH, LP 3 liquidity-fee-factor = 3.75%] -``` - -but the market was proposed with a constant fee of 0.8% so that is what the liquidity-fee-factor will be. - -### Timing market's liquidity-fee-factor changes - -Once the market opens (opening auction starts) a clock starts ticking. We calculate the `[target stake]` using [target stake](./0041-TSTK-target_stake.md). The fee is re-evaluated using the mechanism above at the start of each epoch using LPs commitments at start of epoch. - -### APIs for fee factor calculations - what should core be exposing? - -At time of call: - -- The `liquidity-fee-factor` for the market, and the method used to calculate it. -- Current liquidity provider commitments and their individually nominated fee factors -- [Target stake](./0041-TSTK-target_stake.md) - -## Splitting Fees Between Liquidity Providers - -The guiding principle of this section is that by committing stake a liquidity provider gets virtual stake that depends on how trading has grown on the market. The virtual stake then determines equity-like share as will be set out below. Equity-like share is then used to split fee revenue between LPs. - -### Calculating liquidity provider equity-like share - -The parameter which determines the period over which growth is estimated is `market.value.windowLength` which could be e.g. a week. -From the end of the opening auction, which we will refer to as `t0` until `t0+market.value.windowLength` is the `0th` or "bootstrap period". Then from `t0+market.value.windowLength` until `t0 + 2 x market.value.windowLength` is the `1st` period and so on. -For each LP we track the stake they have and also their virtual stake. -For markets that have no "parent" market, see [governance](./0028-GOVE-governance.md) we postulate that before and during the 0th (bootstrap) any stake commitment or removal is mirrored in the virtual stake. - -For any period `n >= 1` LP can add stake or remove stake but virtual stake is treated differently for markets with "parent market": - -If the market has a "parent market" then each LP which commits liquidity (to this market) gets the virtual stake copied from the parent market as the 1st step of the process and the stake they are committing here minus the stake on parent market is treated as the `delta` here. - -Say an `LP i` wants increases their commitment by `delta > market.liquidityProvision.minLpStakeQuantumMultiple x quantum` (this could also be the initial commitment). Then we update - -```text -LP i virtual stake <- LP i virtual stake + delta. -``` - -Say an `LP i` wants to decrease their commitment by `delta < 0`. Then we update - -```text -LP i virtual stake <- LP i virtual stake x (LP i stake + delta)/(LP i stake). -``` - -Independently of the above we also update all virtual stakes at start of each new period. -To that end "total value for fee purposes" is cumulated over the period set by `market.value.windowLength`. For a period `n` call this `T(n)`. -We let the `0`th period start the moment the opening auction ends and last for `market.value.windowLength`. -We include the volume of the trades that resolved the opening auction in `T(0)` for markets with no parent market. -For markets with a parent market we take `T(0)` to be the most recent `T_{parent}(latest)`. -From this we calculate the running average trade value for fee purposes: - -```text -A(0) <- T(0), -A(n) <- A(n-1) x n/(n+1) + T(n)/(n+1), for `n=1,2,... -``` - -For `n = 0` set `r=0` and for `n = 1,2,...` the `g"r"owth` of the market is then - -```go -r = 0 -if A(n) > 0 and A(n-1) > 0 - r = (A(n)-A(n-1))/A(n-1), -``` - -Thus at the end of period `n` update - -```go -if n = 0 or n = 1 or A(n) = 0 or A(n-1) = 0 - LP i virtual stake <- LP i physical stake -else - LP i virtual stake <- max(LP i physical stake, (1 + r) x (LP i virtual stake)). -``` - -Thus the virtual stake of an LP will always be at least their physical stake. -Moreover, in situations when trading volume was zero in the previous period or if it is zero in the current period then we don't define the growth `r` and so in such extreme situations the virtual stake reverts to the physical stake. - -The equity-like share for each LP is then - -```text -(LP i equity-like share) = (LP i virtual stake) / (sum over j from 1 to N of (LP j virtual stake)). -``` - -**Check** the sum from over `i` from `1` to `N` of `LP i equity-like share` is equal to `1`. -**Warning** the above will be decimal calculations so the above checks will only be true up to a rounding errors. - -The average entry valuation (which should be reported by the APIs and could be calculated only by the data node as it doesn't itself impact core state) is defined, at the time of change of an LP commitment as follows: - -1. There already is `average entry valuation` for the LP in question (and `average entry valuation = 0` for a new LP). The LP has existing physical stake `S` (and `S=0` for new LP) and wishes to add / remove stake `Delta S`. If `Delta S < 0` then `average entry valuation` is unchanged by the transaction. If `S + Delta S = 0` then the LP is exiting their LP commitment and we do not calculate the `average entry valuation` for them in this case. -So `Delta S > 0` (and so `S+Delta S > 0`) in what follows. -2. Calculate the entry valuation at the time stake `Delta S` is added / removed as - -```text -(entry valuation) = sum over j from 1 to N of (LP j virtual stake) -``` - -Note, the `virtual stake` used in the calculation of `entry valuation` is after the change of the LP commitment is applied. -This in particular means that if this is the first LP commitment on the market then the `(entry valuation) = Delta S`. -3. Update the average entry valuation to - -```text -(average entry valuation) <- (average entry valuation) x S / (S + Delta S) + (entry valuation) x (Delta S) / (S + Delta S) -``` - -Example 1: -Currently the sum of all virtual stakes is `900`. A new LP has `0` stake and add stake `Delta S = 100`. The sum of all virtual stakes is now `1000`. The average entry valuation is - -```text -(average entry valuation) <- 0 + 1000 x 100 / (0 + 100) = 1000 -``` - -Example 2: -A new LP1 has `0` stake and they wish to add `Delta S = 8000` and a new LP2 has `0` stake and they wish to add `Delta S = 2000`. Currently the sum of all virtual stakes is `10000` after the LP commitments added. The average entry valuations are: - -```text -(average entry valuation LP1) <- 0 + 8000 x 8000 / (0 + 8000) = 8000 -(average entry valuation LP2) <- 0 + (8000 + 2000) x 2000 / (0 + 2000) = 10000 -``` - -Example 3: -An existing LP has `average entry valuation 1000` and `S=100`. Currently the sum of all virtual stakes is `2000`. They wish to add `10` to their stake. - -```text -(average entry valuation) <- 1000 x 100 / (100 + 10) + 2000 x 10 / (100 + 10) = 1090.9.... -``` - -Example 4: -An existing LP has `average entry valuation 1090.9` and `S=110`. Currently the sum of all virtual stakes is `3000`. They wish to remove `20` from their stake. Their average entry valuation stays the same - -```text -(average entry valuation) = 1090.9 -``` - - -### Calculating the liquidity score - -At every vega time change calculate the liquidity score for each committed LP. -This is done by taking into account all orders they have deployed within the `[min_lp_price,max_lp_price]` [range](./0044-LIME-lp_mechanics.md) and then calculating the volume-weighted instantaneous liquidity score. - -It can be based either on [probability of trading](./0034-PROB-prob_weighted_liquidity_measure.ipynb) at each price level or an [explicit scoring function](./0091-ILSF-instantaneous_liquidity_scoring_funcion.md). The purpose of it is to decide on the relative value of volume placed close to the mid price versus that further away from it. - -For orders outside the tightest price monitoring bounds set probability of trading to 0. For orders which have less than 10% [probability of trading], we set the probability to 0 when calculating liquidity score. -Note that parked [pegged orders](./0037-OPEG-pegged_orders.md) and not-yet-triggered [stop orders](./0014-ORDT-order_types.md) are not included. - -Now calculate the total of the instantaneous liquidity scores obtained for each committed LP: - -`total = the sum of instantaneous liquidity scores for all LPs that have an active liquidity commitment` - -Now, if the `total` comes out as `0` then set `fractional instantaneous liquidity score` to `1.0/n`, where `n` is the number of committed LPs. -Otherwise calculate fractional instantaneous liquidity score for each committed LP. - -`fractional instantaneous liquidity score = instantaneous liquidity score / total` - -Whenever a new LP fee distribution period starts set a counter `n=1`. -Then on every Vega time change, after `fractional instantaneous liquidity score` has been obtained for all the committed LPs, update: - -`liquidity score <- ((n-1)/n) x liquidity score + (1/n) x fractional instantaneous liquidity score` - -The liquidity score should always be rounded to 10 decimal places to prevent spurious accuracy and overly long string representation of a number. - -### Distributing fees into LP-per-market fee account - -On every trade, liquidity fee should be collected immediately into the market's aggregate LP fee account. -The account is under control of the network and funds from this account will be transferred to the owning LP party according to the mechanism below. - -A network parameter `market.liquidity.providersFeeCalculationTimeStep` will control how often fees are distributed from the market's aggregate LP fee account. -Starting with the end of the opening auction the clock starts ticking and then rings every time `market.liquidity.providersFeeCalculationTimeStep` has passed. Every time this happens the balance in this account is transferred to the liquidity provider's general account for the market settlement asset. - -The liquidity fees are transferred from the market's aggregate LP fee account into the LP-per-market fee account from two different configurable size buckets, defined by the network parameter `market.liquidity.equityLikeShareFeeFraction`. The first bucket, a proportion equal to `market.liquidity.equityLikeShareFeeFraction` of the fee, is divided pro-rata depending on the `LP i equity-like share` multiplied by `LP i liquidity score` scaled back to `1` across all LPs at a given time. The other bucket, `1 - market.liquidity.equityLikeShareFeeFraction`, is divided purely by each LP's in-epoch liquidity score `LP i liquidity score`, scaled again across the value of all LPs at that time. - -The LP parties don't control the LP-per-market fee account; the fees from there are then transferred to the LPs' general account at the end epoch as described below. - -### Calculating SLA performance - -#### Measuring time spent meeting their commitment in a single epoch - -During the epoch, the amount of time in nanoseconds (of Vega time) that each LP spends meeting the SLA is recorded. This can be done by maintaining a counter `s_i` as shown below: - -- At the start of a new epoch, `s_i = 0` - - - If the LP is meeting their commitment, store the Vega time of the start of the epoch as the time the LP began meeting their commitment, otherwise store `nothing`. - -- At start of block, for LP `i`, first reset the running minimum valid volume an LP is providing and across the block and then keep updating the minimum volume that the LP is providing that is [within the valid range](./0044-LIME-lp_mechanics.md) (section "Meeting the committed volume of notional"). -- Note that the volume check must only happen _after_ iceberg orders, that need refreshing as a result of a transaction are refreshed. This means that while an iceberg order has sufficient `remaining` quantity, it will **never** be considered to be contributing less than its `minimum peak size`. - -- At the end of each block: - - If an LP has started meeting their [committed volume of notional based on the minimum volume recorded during the block](./0044-LIME-lp_mechanics.md) (section "Calculating liquidity from commitment") after previously not doing so (i.e. `nothing` is stored as the time the LP began meeting their commitment): - - Store the current Vega time attached to the block being processed as the time the LP began meeting their commitment. - - - If an LP has stopped meeting their committed volume of notional after previously doing so: - - Add the difference in nanoseconds between the current Vega time attached to the block being processed and the time the LP began meeting their commitment (stored in the step above) to `s_i`. - - Store `nothing` as the time the LP began meeting their commitment, to signify the LP not meeting their commitment. - -- At the end of the epoch, calculate the actual observed epoch length `observed_epoch_length` = the difference in nanoseconds between the Vega time at the start of the epoch and the Vega time at the end of the epoch. - -Note that because vega time won't be progressing inside a block the above mechanism should ensure that `s_i` gets incremented only if the LP was meeting their commitment at every point this was checked within the block. - -#### Calculating the SLA performance penalty for a single epoch - -Calculate the fraction of the time the LP spent on the book: - -```text -fraction_of_time_on_book = s_i / observed_epoch_length -``` - -For any LP where `fraction_of_time_on_book < market.liquidity.commitmentMinTimeFraction` the SLA penalty fraction `p_i = 1` (that is, the penalty is 100% of their fees). - -For each LP where `fraction_of_time_on_book ≥ market.liquidity.commitmentMinTimeFraction`, the SLA penalty fraction `p_i` is calculated as follows: - -Let $t$ be `fraction_of_time_on_book` - -Let $s$ be `market.liquidity.commitmentMinTimeFraction`. - -Let $c$ be `market.liquidity.slaCompetitionFactor`. - -$$p_i = \begin{cases} - (1 - \frac{t - s}{1 - s}) \cdot c &\text{if } s < 1 \\ - 0 &\text{if } s = 1 -\end{cases}$$ - -#### Calculating the SLA performance penalty for over hysteresis period - -Now, for each LP $i$ take the $p_i$ values calculated over the last `market.liqudity.performanceHysteresisEpochs - 1`, call these $p_i^1, p_i^2, ..., p_i^{n-1}$ (if all the historical ones are not yet available, take as many as there are - i.e. expanding window till you get to the full length). - -Now calculate $p_i^n$ to be the arithmetic average of $p_i^k$ for $k = 1,2,...,n-1$. -Finally set - -$$ -p_i^n \leftarrow \max(p_i,p_i^n). -$$ - -i.e. your penalty is the bigger of current epoch and average over the hysteresis period - -### Applying LP SLA performance penalties to accrued fees - -As defined above, for each LP for each epoch you have "penalty fraction" $p_i^n$ which is between `[0,1]` with `0` indicating LP has met commitment 100% of the time and `1` indicating that LP was below `market.liquidity.commitmentMinTimeFraction` of the time. All vAMM LPs should also receive a $p_i^n$ value, however this will always be `0`, as they are defined as always meeting their commitment. - -If for all $i$ (all the LPs) have $p_i^n = 1$ then all the fees go into the market insurance pool and we stop. - -Calculate - -$$ -w_i = \frac{\text{LP-per-market fee account } i}{\sum_k \text{LP-per-market fee account } k}. -$$ - -For each LP transfer $(1-p_i^n) \times \text{ amount in LP-per-market fee account}$ to their general account with a transfer type that marks this as the "LP net liquidity fee distribution". - -Transfer the remaining amount from each LP-per-market fee account back into the market's aggregate LP fee account. Record the total inflow as a result of that operation as $B$. -Let $b_i := (1-p_i^n) \times w_i$ and renormalise $b_i$s so that they sum up to $1$ i.e. - -$$ -b_i \leftarrow \frac{b_i}{\sum_k b_k}\,. -$$ - -Each LP further gets a performance bonus: $b_i \times B$ with a transfer type that marks this as the "LP relative SLA performance bonus distribution". - -### APIs for fee splits and payments - -- Each liquidity provider's equity-like share -- Each liquidity provider's average entry valuation - -## Acceptance Criteria - -### CALCULATING LIQUIDITY FEE FACTOR TESTS - -- The examples provided result in the given outcomes (0042-LIQF-001) -- The resulting liquidity-fee-factor is always equal to one of the liquidity provider's individually nominated fee factors (0042-LIQF-002) For product spot: (0042-LIQF-063). -- The resulting liquidity-fee-factor is never less than zero (0042-LIQF-003) -- Liquidity fee factors are recalculated every time a liquidity provider nominates a new fee factor (using the commit liquidity network transaction). (0042-LIQF-004) -- Liquidity fee factors are recalculated every time the liquidity demand estimate changes. (0042-LIQF-005). For product spot: (0042-LIQF-064). -- If a change in the open interest causes the liquidity demand estimate to change, then fee factor is correctly recalculated. (0042-LIQF-006) -- If passage of time causes the liquidity demand estimate to change, the fee factor is correctly recalculated. (0042-LIQF-007). For product spot: (0042-LIQF-065). -- A market can be proposed with a choice of liquidity fee settings. These settings can be updated by a subsequent market update proposal. Moreover, the correct fee value and liquidity fee setting method can be read from the data node APIs. Upon proposal enactment the new liquidity method is applied to recalculate the liquidity fee. The tests should be carried out with the following methods: - - Weighted average (0042-LIQF-056). For product spot: (0042-LIQF-066). - - Constant fee (0042-LIQF-061). For product spot: (0042-LIQF-067). - - Marginal cost (0042-LIQF-062). For product spot: (0042-LIQF-068). -- The above example for the liquidity fee when the method is weighted-average results in a fee-factor of 1.5% (0042-LIQF-057). For product spot: (0042-LIQF-069). -- The above example for the liquidity fee when the method is constant-fee results in a fee-factor of 0.8% (0042-LIQF-058). For product spot: (0042-LIQF-070). -- The above example for the liquidity fee when the method is marginal cost results in a fee-factor of `3.75%` (0042-LIQF-059). For product spot: (0042-LIQF-071). -- For the constant-fee method validate that the fee factor can only be between 0 and 1 inclusive (0042-LIQF-060). For product spot: (0042-LIQF-072). - - -### CHANGE OF NETWORK PARAMETERS TESTS - -- Change of network parameter `market.liquidityProvision.minLpStakeQuantumMultiple` will change the multiplier of the asset quantum that sets the minimum LP commitment amount. If `market.liquidityProvision.minLpStakeQuantumMultiple` is changed then no LP orders that have already been submitted are affected. However any new submissions or amendments must respect the new amount and those not meeting the new minimum will be rejected. (0042-LIQF-021) -- Change of network parameter `market.value.windowLength` will affect equity-like share calculations from the next block. Decreasing it so that the current period is already longer then the new parameter value will end it immediately and the next period will have the length specified by the updated parameter. Increasing it will lengthen the current period up to the the length specified by the updated parameter. (0042-LIQF-022) - - -### SPLITTING FEES BETWEEN liquidity providers - -- The examples provided result in the given outcomes. (0042-LIQF-008) -- The total amount of liquidity fee distributed is equal to the most recent `liquidity-fee-factor` x `notional-value-of-all-trades` (0042-LIQF-011) -- Liquidity providers with a commitment of 0 will not receive a share of the fees (0042-LIQF-012) -- When a market settles any fees from any intermediate fee accounts are distributed as if the epoch ended as part of the settlement process, see [market lifecycle](./0043-MKTL-market_lifecycle.md). Any settled market has zero balances in all the LP fee accounts. (0042-LIQF-014) -- All liquidity providers with `average fraction of liquidity provided by committed LP > 0` in the market receive a greater than zero amount of liquidity fee. The only exception is if a non-zero amount is rounded to zero due to integer representation. (0042-LIQF-015) -- After fee distribution, if there is a remainder in the liquidity fee account and the market is not being settled, it should be left in the liquidity fee account and carried over to the next distribution window. (0042-LIQF-032) - - -### LP JOINING AND LEAVING MARKETS - -- An LP joining a market that is below the target stake with a higher fee bid than the current fee: their fee is used (0042-LIQF-019) -- Given the fee setting method is marginal cost. An LP joining a spot market that is below the target stake with a higher fee bid than the current fee: their fee is used when the fee is next recalculated (0042-LIQF-073) -- An LP joining a market that is below the target stake with a lower fee bid than the current fee: fee doesn't change (0042-LIQF-020) -- Given the fee setting method is marginal cost. An LP joining a market that is below the target stake with a lower fee bid than the current fee: fee doesn't change (0042-LIQF-074) -- An LP joining a market that is above the target stake with a sufficiently large commitment to push ALL higher bids above the target stake and a lower fee bid than the current fee: their fee is used (0042-LIQF-029) -- Given the fee setting method is marginal cost. An LP joining a spot market that is above the target stake with a sufficiently large commitment to push ALL higher bids above the target stake and a lower fee bid than the current fee: their fee is used when the fee is next recalculated (0042-LIQF-075) -- An LP joining a market that is above the target stake with a commitment not large enough to push any higher bids above the target stake, and a lower fee bid than the current fee: the fee doesn't change (0042-LIQF-030) -- Given the fee setting method is marginal cost. An LP joining a spot market that is above the target stake with a commitment not large enough to push any higher bids above the target stake, and a lower fee bid than the current fee: the fee doesn't change when the fee is next recalculated (0042-LIQF-076) -- An LP joining a market that is above the target stake with a commitment large enough to push one of two higher bids above the target stake, and a lower fee bid than the current fee: the fee changes to the other lower bid (0042-LIQF-023) -- Given the fee setting method is marginal cost. An LP joining a spot market that is above the target stake with a commitment large enough to push one of two higher bids above the target stake, and a lower fee bid than the current fee: the fee changes to the other lower bid when the fee is next recalculated (0042-LIQF-077) -- An LP joining a market that is above the target stake with a commitment large enough to push one of two higher bids above the target stake, and a higher fee bid than the current fee: the fee doesn't change (0042-LIQF-024) -- Given the fee setting method is marginal cost. An LP joining a spot market that is above the target stake with a commitment large enough to push one of two higher bids above the target stake, and a higher fee bid than the current fee: the fee doesn't change when the fee is next recalculated (0042-LIQF-078) -- An LP leaves a market that is above target stake when their fee bid is currently being used: fee changes to fee bid by the LP who takes their place in the bidding order (0042-LIQF-025) -- Given the fee setting method is marginal cost. An LP leaves a market that is above target stake when their fee bid is currently being used: fee changes to fee bid by the LP who takes their place in the bidding order when the fee is next recalculated (0042-LIQF-079) -- An LP leaves a market that is above target stake when their fee bid is lower than the one currently being used and their commitment size changes the LP that meets the target stake: fee changes to fee bid by the LP that is now at the place in the bid order to provide the target stake (0042-LIQF-026) -- Given the fee setting method is marginal cost. An LP leaves a market that is above target stake when their fee bid is lower than the one currently being used and their commitment size changes the LP that meets the target stake: fee changes to fee bid by the LP that is now at the place in the bid order to provide the target stake when the fee is next recalculated (0042-LIQF-080) -- An LP leaves a market that is above target stake when their fee bid is lower than the one currently being used. The loss of their commitment doesn't change which LP meets the target stake: fee doesn't change (0042-LIQF-027) -- Given the fee setting method is marginal cost. An LP leaves a spot market that is above target stake when their fee bid is lower than the one currently being used. The loss of their commitment doesn't change which LP meets the target stake: fee doesn't change when the fee is next recalculated (0042-LIQF-081) -- An LP leaves a market that is above target stake when their fee bid is higher than the one currently being used: fee doesn't change (0042-LIQF-028) -- Given the fee setting method is marginal cost. An LP leaves a spot market that is above target stake when their fee bid is higher than the one currently being used: fee doesn't change (0042-LIQF-106) - -### API - -- Equity-like share of each active LP can be obtained via the API (0042-LIQF-016) -- Liquidity score of each active LP can be obtained via the API (0042-LIQF-017) -- Through the `LiquidityProviders` API, liquidity score, average entry valuation and equity-like share of each active LP can be obtained - - GRPC (0042-LIQF-050) - - GRAPHQL (0042-LIQF-051) - - REST (0042-LIQF-052) - - -### Successor markets - -- If an LP has virtual stake of `11000` and stake of `10000` on a parent marketID=`m1` and a new market is proposed and enacted as `m2` with `m1` as its parent market and the LP submits a commitment of `10000` to `m2` during the "Pending" period, see [lifecycle](./0043-MKTL-market_lifecycle.md) then for the duration of the first `market.value.windowLength` after the opening auction ends the LP has virtual stake of `11000` and stake of `10000` on `m2`. (0042-LIQF-031) -- If an LP has virtual stake of `11000` and stake of `10000` on a parent `marketID`=`m1` and a new market is proposed and enacted as `m2` with `m1` as its parent market and the LP submits a commitment of `20000` to `m2` during the "Pending" period, see [lifecycle](./0043-MKTL-market_lifecycle.md) then for the duration of the first `market.value.windowLength` after the opening auction ends the LP has virtual stake which must be result of the virtual stake obtained from `m1` with the `delta=10000` added on, so virtual stake of `21000`, assuming all other LPs committed exactly the stake they had on `m1`. (0042-LIQF-048) -- If an LP has virtual stake of `11000` and stake of `10000` on a parent `marketID`=`m1` and a new market is proposed and enacted as `m2` with `m1` as its parent market and the LP submits a commitment of `5000` to `m2` during the "Pending" period, see [lifecycle](./0043-MKTL-market_lifecycle.md) then for the duration of the first `market.value.windowLength` after the opening auction ends the LP has virtual stake obtained from `m1` with the `delta=-5000` added on (i.e. 5000 removed). (0042-LIQF-033) -- If `market.liquidity.providersFeeCalculationTimeStep > 0` for a given market and an LP submits a new liquidity commitment halfway through the time interval then they receive roughly 1/2 the fee income from that market compared with the next time interval when they maintain their commitment (and the traded value is the same in both time intervals). (0042-LIQF-034) - - -### Calculating SLA Performance - -- If an LP has an active liquidity provision at the start of an epoch, `market.liquidity.slaCompetitionFactor = 1`, `market.liquidity.commitmentMinTimeFraction = 0.5` and throughout the epoch meets their liquidity provision requirements such that the `fraction_of_time_on_book = 0.75` then their penalty from that epoch will be `0.5`. This will be true whether: - - - Their liquidity is all provided at the start of the epoch and then none is provided for the second half (0042-LIQF-037). For spot (0042-LIQF-082) - - Their liquidity is provided scattered throughout the epoch (0042-LIQF-038). For spot (0042-LIQF-083) - -- If an LP has an active liquidity provision at the start of an epoch, `market.liquidity.slaCompetitionFactor = 0`, `market.liquidity.commitmentMinTimeFraction = 0.5` and throughout the epoch meets their liquidity provision requirements such that the `fraction_of_time_on_book = 0.75` then their penalty from that epoch will be `0`. (0042-LIQF-041). For spot (0042-LIQF-084) -- If an LP has an active liquidity provision at the start of an epoch, `market.liquidity.slaCompetitionFactor = 0.5`, `market.liquidity.commitmentMinTimeFraction = 0.5` and throughout the epoch meets their liquidity provision requirements such that the `fraction_of_time_on_book = 0.75` then their penalty from that epoch will be `0.25`. (0042-LIQF-042). For spot (0042-LIQF-085) - -- When `market.liquidity.performanceHysteresisEpochs = 1`: - - - If an LP has an active liquidity provision at the start of an epoch and throughout the epoch always meets their liquidity provision requirements then they will have a `fraction_of_time_on_book == 1` and no penalty will be applied to their liquidity fee payments at the end of the epoch (0042-LIQF-035). For spot (0042-LIQF-086) - - If an LP has an active liquidity provision at the start of an epoch and throughout the epoch meets their liquidity provision requirements less than `market.liquidity.commitmentMinTimeFraction` fraction of the time then they will have a full penalty and will receive `0` liquidity fee payments at the end of the epoch (0042-LIQF-049). For spot (0042-LIQF-087) - - An LP has an active liquidity provision at the start of an epoch. The penalty rate for said LP over the previous `2` epochs is `0.75`. During the epoch `market.liquidity.performanceHysteresisEpochs` is set to `3`. Throughout the current epoch the LP meets their liquidity provision requirements so they will have `fraction_of_time_on_book == 1`. The penalty applied to fee distribution at epoch end will be `0` and will not consider the previous epochs. (0042-LIQF-053). For spot (0042-LIQF-088) - -- When `market.liquidity.performanceHysteresisEpochs > 1`: - - - If an LP has an active liquidity provision at the start of an epoch, the average `penalty rate` over the previous `n-1` epochs is `0.75` and throughout the epoch they always meet their liquidity provision requirements then they will have a `fraction_of_time_on_book == 1` for the latest epoch a penalty rate of `0.75` will be applied to liquidity fee payments at the end of the epoch (0042-LIQF-047). For spot (0042-LIQF-089) - - If an LP has an active liquidity provision at the start of an epoch, the average `penalty rate` over the previous `n-1` epochs is `0.5` and throughout the epoch they always meet their liquidity provision requirements then they will have a `fraction_of_time_on_book == 1` for the latest epoch a penalty rate of `0.5` will be applied to liquidity fee payments at the end of the epoch (0042-LIQF-039). For spot (0042-LIQF-090) - - If an LP has an active liquidity provision at the start of an epoch, the average `penalty rate` over the previous `n-1` epochs is `0.5` and throughout the epoch they never meet their liquidity provision requirements then they will have a `fraction_of_time_on_book == 0` for the latest epoch a penalty rate of `1` will be applied to liquidity fee payments at the end of the epoch (0042-LIQF-040). For spot (0042-LIQF-091) - - If an LP has an active liquidity provision at the start of an epoch and no previous performance penalties and throughout the epoch always meets their liquidity provision requirements then they will have a `fraction_of_time_on_book == 1` then no penalty will be applied to their liquidity fee payments at the end of the epoch. (0042-LIQF-054). For spot (0042-LIQF-100) - - -### SLA Performance bonus transfers - -- The net inflow and outflow into and out of the market's aggregate LP fee account should be zero as a result of penalty collection and bonus distribution. (0042-LIQF-043). For spot (0042-LIQF-101) -- With two liquidity providers, one with an effective penalty rate of `0.5` and earned fees of `n`, and the other with an effective rate of `0.75` and earned fees of `m`, `50% * n` and `25% * m` of the second provider's should be transferred back into market's aggregate LP fee account. Then the total provider bonus score should be `b = (m / (n + m)) * 0.25 + (n / (n + m)) * 0.5` and provider 1 should receive `(0.5 * n + 0.25 * m) * (n / (n + m)) * 0.5 / b` and provider 2 should receive `(0.5 * n + 0.25 * m) * (m / (n + m)) * 0.25 / b` as an additional bonus payment (0042-LIQF-044). For spot (0042-LIQF-102) -- With two liquidity providers, one with an effective penalty rate of `1` and earned fees of `n`, and the other with an effective rate of `0` and earned fees of `m`, the entirety of `n` should be transferred to the second liquidity provider as a bonus payment (0042-LIQF-045). For spot (0042-LIQF-103) -- With only one liquidity provider, with an effective penalty rate of `0.5`, `50%` of their initially earned fees will be taken initially but will be entirely paid back to them as a bonus payment (0042-LIQF-046). For spot (0042-LIQF-104) - -### Transfers example - -Example 1, generated with [supplementary worksheet](https://docs.google.com/spreadsheets/d/1PQC2WYv9qRlyjbvvCYpVWCzO5MzwkcEGOR5aS9rWGEY) [internal only]. Values should match up to rounding used by `core` (0042-LIQF-055). For spot (0042-LIQF-105): -| LP | penalty fraction | LP-per-market fee accounts balance | 1st transfer amt | 2nd (bonus) transfer amt | -| --- | -------------- | -------------- | -------------- | -------------- | -| LP1 | 0 | 1000 | 1000 | 24673.94095 | -| LP2 | 0.05 | 100 | 95 | 2344.02439 | -| LP3 | 0.6 | 7000 | 2800 | 69087.03466 | -| LP4 | 1 | 91900 | 0 | 0 | - - -### vAMM behaviour - -- All vAMMs active on a market at the end of an epoch receive SLA bonus rebalancing payments with `0` penalty fraction. (0042-LIQF-092) -- A vAMM active on a market during an epoch, which was cancelled prior to the end of an epoch, receives SLA bonus rebalancing payments with `0` penalty fraction. (0042-LIQF-093) -- A vAMMs cancelled in a previous epoch does not receive anything and is not considered during SLA rebalancing at the end of an epoch(0042-LIQF-094) - -- a vAMM which was active on the market throughout the epoch but with an active range which never overlapped with the SLA range is counted with an implied commitment of `0`. (0042-LIQF-107) -- A vAMM which was active on the market with an average of `10000` liquidity units (`price * volume`) provided across the epoch, and where the `market.liquidity.stakeToCcyVolume` value is `100`, will have an implied commitment of `100`. (0042-LIQF-108) -- A vAMM which was active on the market with an average of `10000` liquidity units (`price * volume`) provided for half the epoch, and then `0` for the second half of the epoch (as the price was out of the vAMM's configured range), and where the `market.liquidity.stakeToCcyVolume` value is `100`, will have an implied commitment of `50`. (0042-LIQF-109) -- A vAMM which was active on the market with an average of `10000` liquidity units (`price * volume`) provided for half the epoch, and then is cancelled for the second half of the epoch, and where the `market.liquidity.stakeToCcyVolume` value is `100`, will have an implied commitment of `50`. (0042-LIQF-110) -- A vAMM which was active on the market with an average of `10000` liquidity units (`price * volume`) provided for half the epoch, and then `5000` for the second half of the epoch (as the price was out of the vAMM's configured range), and where the `market.liquidity.stakeToCcyVolume` value is `100`, will have an implied commitment of `75`. (0042-LIQF-111) -- If a vAMM was active during the market's opening auction if the opening auction ended and if trades were placed before the end of an epoch the vAMM should receive liquidity fee at epoch boundary (just like a normal LP that submitted bond during opening auction and then met the SLA) (0042-LIQF-112) - - -### Explicit instantaneous liquidity scoring function - -When market is setup with [explicit instantaneous liquidity scoring function](./0091-ILSF-instantaneous_liquidity_scoring_funcion.md) as follows: - -- buy-side: - - reference: BEST_BID - - points: [(0,0.25),(1,0)] - - interpolation strategy: FLAT - -- sell-side: - - reference: BEST_ASK - - points: [(0,0.35),(1,0)] - - interpolation strategy: FLAT - -then all the buy orders deployed at `BEST_BID` get an instantaneous liquidity score of `0.25`, all sell orders deployed at `BEST_ASK` get a score of `0.35` and all other orders get a score of `0`. Updating the risk model has no effect on those scores. (0042-LIQF-095) - -When market is setup with [explicit instantaneous liquidity scoring function](./0091-ILSF-instantaneous_liquidity_scoring_funcion.md) as follows: - -- buy-side: - - reference: MID - - points: [(0,0.4),(200,0.2)] - - interpolation strategy: FLAT - -- sell-side: - - reference: MID - - points: [(0,0.5),(300,0.3)] - - interpolation strategy: FLAT - -the decimal places for the asset are, the decimal places for the market are and tick size is. Then buy orders pegged to MID with an offset of `100` get a score of `0.3`, orders with offset of `200` get a score of `0.2` and orders with and offset of `300` also get a score of `0.2`. Sell orders pegged to MID with an offset of `150` get a score of `0.4`, orders with an offset of `300` get a score of `0.3` and orders with an offset of `400` also get a score of `0.3`. Updating the risk model has no effect on those scores. (0042-LIQF-096) diff --git a/protocol/0044-LIME-lp_mechanics.md b/protocol/0044-LIME-lp_mechanics.md deleted file mode 100644 index c15e37753..000000000 --- a/protocol/0044-LIME-lp_mechanics.md +++ /dev/null @@ -1,424 +0,0 @@ -# Liquidity provision mechanics - -The point of liquidity provision on Vega is to incentivise people to place orders on the market that maintain liquidity on the book. -This is done via a financial commitment and reward + penalty mechanics, and through the LP commitment transaction that announces that a party is entering the liquidity provision (LP) service level agreement (SLA). - - -Important note on wording: - -- liquidity provision / liquidity COMMITMENTs are the amount of stake a liquidity provider places as a bond on the market to earn rewards. -- the COMMITMENT is converted via a multiplicative network parameter `market.liquidity.stakeToCcyVolume` to a liquidity OBLIGATION, measured in price level x volume i.e. settlement currency of the market. - -## Network and market parameters - -### Network parameters - -- `market.liquidity.bondPenaltyParameter` - used to calculate the penalty to liquidity providers when they fail to support their open position through sufficient `general+margin` balance. -Valid values: any decimal number `>= 0` with a default value of `0.1`. -- `market.liquidity.sla.nonPerformanceBondPenaltySlope` - used to calculate how much is the LP bond slashed if they fail to reach the minimum SLA. Valid values: any decimal number `>= 0` with a default value of `2.0`. -- `market.liquidity.sla.nonPerformanceBondPenaltyMax` - used to calculate how much is the LP bond slashed if they fail to reach the minimum SLA. Valid values: any decimal number `>= 0` and `<=1.0` with a default value of `0.5`. -- `market.liquidity.maximumLiquidityFeeFactorLevel` - used in validating fee amounts that are submitted as part of the LP commitment transaction. Note that a value of `0.05 = 5%`. Valid values are: any decimal number `>=0` and `<=1`. Default value `1`. -- `market.liquidity.stakeToCcyVolume` - used to translate a commitment to an obligation. Any decimal number `>0` with default value `1.0`. -- `validators.epoch.length` - LP rewards from liquidity fees are paid out once per epoch according to whether they met the "SLA" (implied by `market.liquidity.commitmentMinTimeFraction`) and their previous performance (for the last n epochs defined by `market.liquidity.performanceHysteresisEpochs`), see [epoch spec](./0050-EPOC-epochs.md). -- `market.liquidity.earlyExitPenalty` (decimal ≥0), sets how much LP forfeits of their bond in case the market is below target stake and they wish to reduce their commitment. If set to `0` there is no penalty for early exit, if set to `1` their entire bond is forfeited if they exit their entire commitment, if set >1, their entire bond will be forfeited for exiting `1/earlyExitPenalty` of their commitment amount. -- `market.liquidity.probabilityOfTrading.tau.scaling` sets how the probability of trading is calculated from the risk model; this is used to [measure the relative competitiveness of LPs supplied volume](0042-LIQF-setting_fees_and_rewarding_lps.md). -- `market.liquidity.minimum.probabilityOfTrading.lpOrders` sets a lower bound on the result of the probability of trading calculation. -- `market.liquidity.feeCalculationTimeStep` (time period e.g. `1m`) controls how often the quality of liquidity supplied by the LPs is evaluated and fees arising from that period are earmarked for specific parties. Minimum valid value is anything more than or equal `1s`. Maximum valid value `validators.epoch.length`. - -### Market parameters - -All following market parameters can be set / modified as part of [market proposal](0028-GOVE-governance.md) / market change proposal and the new value take effect at the first new epoch after enactment. - -- `market.liquidity.priceRange` (decimal) - this is a percentage price move (e.g. `0.05 = 5%`) from `mid_price` during continuous trading or indicative uncrossing price during auctions. - -- `market.liquidity.commitmentMinTimeFraction` (decimal) — minimum fraction of time LPs must spend "on the book" providing their committed liquidity. This is a decimal number in the interval $[0,1]$ i.e. both limits included. When set to $0$ the SLA mechanics are switched off for the market entirely. - -- `market.liquidity.performanceHysteresisEpochs` (uint) - number of liquidity epochs over which past performance will continue to affect rewards. - -- `market.liquidity.slaCompetitionFactor` - the maximum fraction of their accrued fees an LP that meets the SLA implied by `market.liquidity.commitmentMinTimeFraction` will lose to LPs that achieved a higher SLA performance than them. - -For LP reward calculations based on the SLA see the [0042-LIQF spec](./0042-LIQF-setting_fees_and_rewarding_lps.md). - - -## Mechanism overview - -At a high level, the liquidity mechanism in Vega allows Liquidity Providers (LPs) to commit liquidity to a market and "bid" to set the liquidity fee on the market. LPs that meet this commitment are rewarded from the fee revenue. This is done by: - -- Requiring LPs to meet an SLA (i.e. % of time spent providing liquidity within the defined range) in order to be rewarded. - -- Rewarding LPs more for better performance against the SLA vs other LPs, ensuring there is an incentive to do more than the bare minimum and more than other LPs, if market conditions allow. - -- Penalising LPs that commit and do not meet the SLA, to reduce the attractiveness of opportunistically going after rewards with no intention to meet the SLA in more challenging conditions, and of leeching style attacks on the rewards. - -Once committed LPs attempt to meet their commitment by placing and maintaining normal orders on the market. They may use pegged or priced limit orders, along with features like post only and iceberg (or more accurately, transparent iceberg) to control their risk. Non-persistent orders, parked pegged orders, and stop-loss orders do not count towards an LP's supplied liquidity and therefore cannot be used to meet the SLA. - - -## Commit liquidity network transaction - -Any Vega participant can apply to become a liquidity provider (LP) on a market by submitting a transaction to the network which includes the following - -1. Market ID -1. COMMITMENT AMOUNT: liquidity commitment amount (specified as a unitless number that represents the amount of settlement asset of the market) -1. FEES: nominated [liquidity fee factor](./0029-FEES-fees.md), which is an input to the calculation of taker fees on the market, as per [setting fees and rewarding lps](./0042-LIQF-setting_fees_and_rewarding_lps.md) - -Accepted if all of the following are true: - -- The transaction is valid: the submitting party has sufficient collateral in their general account to meet the size of their nominated commitment amount. -- The market is in a state that accepts new liquidity provision [market lifecycle spec](./0043-MKTL-market_lifecycle.md). - - -## Commitment amount - -### Processing the commitment - -When a commitment is made the liquidity commitment amount is assumed to be specified in terms of the settlement currency of the market. -There is an minimum LP stake which is `market.liquidityProvision.minLpStakeQuantumMultiple x quantum` where `quantum` is specified per asset, see [asset framework spec](./0040-ASSF-asset_framework.md). - -If the participant has sufficient collateral to cover their commitment, the commitment amount (stake) is transferred from the participant's general account to their (maybe newly created) [liquidity provision bond account](./0013-ACCT-accounts.md#liquidity-provider-bond-accounts) (new account type, 1 per liquidity provider per market and asset where they are committing liquidity, created as needed). -For clarity, liquidity providers will have a separate [margin account](./0013-ACCT-accounts.md#trader-margin-accounts) and [bond account](./0013-ACCT-accounts.md#liquidity-provider-bond-accounts). - -A new or increased commitment will get activated in two stages.(*) First the commitment amount (increase) will get transferred from general to bond account. -Their obligation for providing liquidity under SLA is determined by their commitment from the beginning of the current epoch (so, in particular, for a new LP, it's 0). -Second, at the beginning of the next epoch (after the rewards/penalties for present LPs have been evaluated), the commitment amount is noted, and the LP is expected to provide sufficient liquidity for the epoch. - -(*) The exception is the end of the opening auction of the market. The LPs that submit a commitment during the opening auction become the market LPs as soon as the opening auction ends. - -The fee for the market is only [updated at the epoch boundary using the "auction" mechanism set here](0042-LIQF-setting_fees_and_rewarding_lps.md). - -Liquidity provider bond account: - -- Each active market has one bond account per liquidity provider, per settlement asset for that market. -- When a liquidity provider transaction is approved, the size of their staked bond is immediately transferred from their general account to this bond account. -- A liquidity provider can only prompt a transfer of funds to or from this account by (re)submitting the LP commitment transaction: a valid transaction to create, increase, or decrease their commitment to the market. - - Transfers to/from this account also occur when it is used for settlement or margin shortfall, when penalties are applied, and if the account is under-collateralised because of these uses and is subsequently topped up to the commitment amount during collateral search (see below) -- Collateral withdrawn from this account may only be transferred to either: - - The insurance pool of the market for markets trading on margin or the network treasury for the asset (for spot markets) (in event of penalties/slashing) - - The liquidity provider's margin account or the network's settlement account/other participant's margin accounts (during a margin search and mark to market settlement) in the event that they have zero balance in their general account. - - The liquidity provider's general account (in event of liquidity provider reducing their commitment) - -### Liquidity provider proposes to amend commitment amount - -The commitment transaction is also used to amend any aspect of their liquidity provision obligations. -A participant may apply to amend their commitment amount by submitting a transaction for the market with a revised commitment amount. - -`proposed-commitment-variation = new-proposed-commitment-amount - old-commitment-amount` - -An increase in amendment is actioned immediately but only has implications for rewards / penalties at start of the next epoch. - -1) the amount is immediately transferred from the party's general account to their bond account. However we keep track of commitment at start of epoch and this is used for penalties / rewards. -2) at the beginning of the next epoch, the rewards / penalties for present LPs - including the party that's amending - are evaluated based on balance of bond account at start of epoch. - -A decrease in commitment is noted but the transfer out of the bond account is only actioned at the end of the current epoch. - -For each party only the most recent amendment should be considered. All the amendments get processed simultaneously, hence the relative arrival of amendments made by different LPs within the previous epoch is irrelevant (as far as commitment reduction is concerned, it still has implications for other aspects of the mechanism). - -#### Increasing commitment - -_Case:_ `proposed-commitment-variation >= 0` - -A liquidity provider can always increase their commitment amount as long as they have sufficient collateral in the settlement asset of the market to meet the new commitment amount. - -If they do not have sufficient collateral the transaction is rejected in entirety. This means that any change in fee bid is not applied and that the `old-commitment-amount` is retained. - -#### Decreasing commitment - -_Case:_ `proposed-commitment-variation < 0` - -At the beginning of each epoch, calculate actual commitment variation for each LP wishing to reduce their commitment as: - -$$ -\text{commitment-variation}_i=\min(-\text{proposed-commitment-variation}_i, \text{bond account balance}_i). -$$ - -Next, calculate how much the overall commitment within the market can be decreased by without incurring a penalty. -To do this we first evaluate the maximum amount that the `total_stake` can reduce by without penalty given the current liquidity demand in the market. - -`maximum-penalty-free-reduction-amount = max(0,total_stake - target_stake)` - -where: - -- `total_stake` is the sum of all stake of all liquidity providers bonded to this market including the amendments with positive commitment variation submitted in the previous epoch. -- `target_stake` is a measure of the market's current stake requirements, as per the calculation in the [target stake](./0041-TSTK-target_stake.md). - -Then, for each $LP_i$ we calculate the pro rata penalty-free reduction amount: - -```math -\text{maximum-penalty-free-reduction-amount}_i=\frac{\text{commitment-variation}_i}{\sum_{j}\text{commitment-variation}_j} \cdot \text{maximum-penalty-free-reduction-amount}. -``` - -If $\text{commitment-variation}_i <= \text{maximum-penalty-free-reduction-amount}_i$ then we're done, the LP reduced commitment, the entire amount by which they decreased their commitment is transferred to their general account, their ELS got updated as per the [ELS calculation](0042-LIQF-setting_fees_and_rewarding_lps.md). - -If $\text{commitment-variation}_i > \text{maximum-penalty-free-reduction-amount}_i$ then first establish - -$$ -\text{penalty-incurring-reduction-amount}_i = \text{commitment-variation}_i - \text{maximum-penalty-free-reduction-amount}_i -$$ - -Transfer $\text{maximum-penalty-free-reduction-amount}_i$ to their general account. - -Now transfer $(1-\text{market.liquidity.earlyExitPenalty}) \cdot \text{penalty-incurring-reduction-amount}_i$ to their general account and transfer $\text{market.liquidity.earlyExitPenalty} \cdot \text{penalty-incurring-reduction-amount}_i$ to the market insurance pool. -Note that in the case of spot market or any market that isn't running an insurance pool the transfer should go into the network treasury for the asset. - -Finally update the ELS as per the [ELS calculation](0042-LIQF-setting_fees_and_rewarding_lps.md) using the entire $\text{commitment-variation}_i$ as the `delta`. - - -## Fees - -### Nominating and amending fee amounts - -The network transaction is used by liquidity providers to nominate a fee amount which is used by the network to calculate the [liquidity_fee](./0042-LIQF-setting_fees_and_rewarding_lps.md) of the market. Liquidity providers may amend their nominated fee amount by submitting a liquidity provider transaction to the network with a new fee amount. If the fee amount is valid, this new amount is used. Otherwise, the entire transaction is considered invalid. - -### How fee amounts are used - -The [liquidity_fee](./0029-FEES-fees.md) of a market on Vega takes as an input, a [`fee factor[liquidity]`](./0029-FEES-fees.md) which is calculated by the network, taking as an input the data submitted by the liquidity providers in their liquidity provision network transactions (see [this spec](./0042-LIQF-setting_fees_and_rewarding_lps.md) for more information on the specific calculation). - -### Distributing fees between liquidity providers - -When calculating fees for a trade, the size of a liquidity provider’s commitment at the start of the epoch along with when they committed and the market size are inputs that will be used to calculate how the liquidity fee is distributed between liquidity providers. See [setting fees and rewarding lps](./0042-LIQF-setting_fees_and_rewarding_lps.md) for the calculation of the split. - - -## Liquidity provision and penalties - -### Calculating liquidity from commitment - -Committed Liquidity Providers are required to provide a multiple of their stake, at the start of the epoch, (supplied in the settlement currency of the market) in notional volume of orders within the range defined below on both sides of the order book. - -The multiple is controlled by a network parameter `market.liquidity.stakeToCcyVolume`: - -```text -liquidity_required = stake_amount ✖️ market.liquidity.stakeToCcyVolume -``` - -### Meeting the committed volume of notional - -#### During continuous trading - -If there is no mid price then no LP is meeting their committed volume of notional. -If there is mid price then we calculate the volume of notional that is in the range - -```text -(1.0-market.liquidity.priceRange) x mid <= price levels <= (1+market.liquidity.priceRange)x mid. -``` - -If this is greater than or equal to `liquidity_required` then the LP is meeting the committed volume of notional. - -#### During auctions - -We calculate the volume of notional that is in the range - -```text -(1.0-market.liquidity.priceRange) x min(last trade price, indicative uncrossing price) <= price levels <= (1.0+market.liquidity.priceRange) x max(last trade price, indicative uncrossing price). -``` - -If there is no 'indicative uncrossing price' then volume placed at any price should count towards the LP's commitment i.e the price range is interpreted as - -```text --infinity <= price levels <= infinity -``` - -If this is greater than or equal to `liquidity_required` then the LP is meeting the committed volume of notional. - - -Note: we don't evaluate whether LPs meet the SLA during opening auctions so there will always be a mark price. - - -### Penalty for not meeting the SLA - -See the [Calculating the SLA performance penalty for a single epoch section in 0042-LIQF](./0042-LIQF-setting_fees_and_rewarding_lps.md) for how `fraction_of_time_on_book` is calculated. -This is available at the end of each epoch. -If, at the end of the epoch, `fraction_of_time_on_book >= market.liquidity.commitmentMinTimeFraction` then let $f=0$. -Otherwise we calculate a penalty to be applied to the bond as follows. - -Let $t$ be `fraction_of_time_on_book` - -Let $s$ be `market.liquidity.commitmentMinTimeFraction`. - -Let $p$ be `market.liquidity.sla.nonPerformanceBondPenaltySlope`. - -Let $m$ be `market.liquidity.sla.nonPerformanceBondPenaltyMax`. - -Let - -$$ -f = \max\left[0,\min\left(m, p \cdot (1 - \frac{t}{s})\right)\right]\,. -$$ - -Once you have $f$ transfer $f \times B$ into the insurance pool of the market, where $B$ is the LP bond account balance. -For spot markets, the transfer is to go into the network treasury account for the asset. -Moreover, as this reduced the LP stake, update the ELS as per [Calculating liquidity provider equity-like share section in 0042-LIQF](./0042-LIQF-setting_fees_and_rewarding_lps.md). - -In the case of if a liquidity provider has `fraction_of_time_on_book = 0`, and `market.liquidity.commitmentMinTimeFraction = 0`, then `f = max[0,min(m,p)]` - -In the case of spot markets the transfer goes into the network treasury account for the asset. - -### Penalty for not supporting open positions - -If at any point in time, a liquidity provider has insufficient capital to make the transfers for their mark to market or other settlement movements, and/or margin requirements arising from their orders and open positions, the network will utilise their liquidity provision commitment, held in the _liquidity provider bond account_ to cover the shortfall. -The protocol will also apply a penalty proportional to the size of the shortfall, which will be transferred to the market's insurance pool. - -Calculating the penalty: - -`bondPenalty = market.liquidity.bondPenaltyParameter ⨉ shortfall` - -The above simple formula defines the amount by which the bond account will be 'slashed', where: - -- `market.liquidity.bondPenaltyParameter` is a network parameter -- `shortfall` refers to the absolute value of the funds that the liquidity provider was unable to cover through their margin and general accounts, that are needed for settlement (mark to market or [product](./0051-PROD-product.md) driven) or to meet their margin requirements. - -_Auctions:_ if this occurs at the transition from auction mode to continuous trading, the `market.liquidity.bondPenaltyParameter` will not be applied / will always be set to zero. - -The network will: - -1. _As part of the normal collateral "search" process:_ Access first the liquidity provider's bond account to make up the shortfall. If there is insufficient funds to cover this amount, the full balance of both bond accounts will be used. Note that this means that the transfer request should include the liquidity provider's bond account in the list of accounts to search, and that these accounts would always be emptied before any market insurance pool funds are used or loss socialisation occurs. - -1. _If there was a shortfall and the bond account was accessed:_ Transfer an amount equal to the `market.liquidity.bondPenaltyParameter` calculated above from the liquidity provider's bond account to the market's insurance pool. If there are insufficient funds in the bond account and the bond account, the full amount will be used and the remainder of the penalty (or as much as possible) should be transferred from the liquidity provider's margin account. - -1. Initiate closeout of the LPs order and/or positions as normal if their margin does not meet the minimum maintenance margin level required. (NB: this should involve no change) - -1. _The liquidity provider's bond account balance is always their current commitment level:_ This is strictly their "true" bond account. - -Note: - -- As mentioned above, closeout should happen as per regular trader account (with the addition of cancelling the liquidity provision and the associated LP rewards & fees consequences). So, if after cancelling all open orders the party can afford to keep the open positions sufficiently collateralised they should be left open, otherwise the positions should get liquidated. - - -## What data do we keep relating to liquidity provision? - -1. List of all liquidity providers and their commitment sizes (bond account balance), the commitment at the start of epoch, their “equity-like share” and "liquidity score" for each market [see 0042-setting-fees-and-rewarding-lps](./0042-LIQF-setting_fees_and_rewarding_lps.md) -1. New bond account per LP per market -1. Actual amount of liquidity supplied (can be calculated from order book, [see 0034-prob-weighted-liquidity-measure](./0034-PROB-prob_weighted_liquidity_measure.ipynb)) - - -## APIs - -- Transfers to and from the bond account, new or changed commitments, and any penalties applied should all be published on the event stream -- It should be possible to query all details of liquidity providers via an API - -## Acceptance Criteria - -- Through the `LiquidityProvisions` API, I can list all active liquidity providers for a market (0044-LIME-001) -- Through the `LiquidityProviders` API, I can list all active liquidity providers fee share information - - GRPC (0044-LIME-057) - - GRAPHQL (0044-LIME-058) - - REST (0044-LIME-059) -- When a LP commits liquidity on market 1, on market 2 this LP has no liquidity commitment when I request for all LP provisions through `ListLiquidityProvisions` api for this party, then only LP provisions for market 1 is returned. (0044-LIME-087) -- The [bond slashing](https://github.com/vegaprotocol/vega/blob/develop/core/integration/features/verified/liquidity-provision-bond-account.feature) works as the feature test claims. (0044-LIME-002). -- Change of network parameter `market.liquidity.bondPenaltyParameter` will, as soon as the current epoch ends, change the amount by which the bond account will be 'slashed' when a liquidity provider has insufficient capital for Vega to make the transfers for their mark to market or other settlement movements, and/or margin requirements arising from their orders and open positions. (0044-LIME-003) -- Change of `market.liquidity.maximumLiquidityFeeFactorLevel` will change the maximum liquidity fee factor. Any new submission or amendments must respect the new maximum (those that don't get rejected). (0044-LIME-006) -- Check that bond slashing works with non-default asset decimals, market decimals, position decimals. This can be done by following a similar story to [bond slashing feature test](https://github.com/vegaprotocol/vega/blob/develop/core/integration/features/verified/liquidity-provision-bond-account.feature). Should test at least three different combinations, each decimal settings different to each other. (0044-LIME-009) -- If `market.liquidity.stakeToCcyVolume` is set to `0.0`, there is [target stake](./0041-TSTK-target_stake.md) of `1000` and there are 3 LPs on the market with stake / fee bid submissions of `100, 0.01`, `1000, 0.02` and `200, 0.03` then the liquidity fee is `0.02`. (0044-LIME-012) - -- If a liquidity provider has `fraction_of_time_on_book` >= `market.liquidity.commitmentMinTimeFraction`, no penalty will be taken from their bond account (0044-LIME-013). For product spot (0044-LIME-102) -- If a liquidity provider has `fraction_of_time_on_book` = `0.3`, `market.liquidity.commitmentMinTimeFraction = 0.6`, `market.liquidity.sla.nonPerformanceBondPenaltySlope = 0.7`, `market.liquidity.sla.nonPerformanceBondPenaltyMax = 0.6` at the end of an epoch then they will forfeit `35%` of their bond stake, which will be transferred into the market's insurance pool (0044-LIME-014) -and in the case of spot markets into the network treasury for the asset (0044-LIME-048) -- If a liquidity provider has `fraction_of_time_on_book` = `0.3`, `market.liquidity.commitmentMinTimeFraction = 0.6`, `market.liquidity.sla.nonPerformanceBondPenaltySlope = 0.7`, `market.liquidity.sla.nonPerformanceBondPenaltyMax = 0.6`and the market parameter change `market.liquidity.commitmentMinTimeFraction = 0.3` is enacted during the epoch then at the end of the current epoch LP will have their bond slashed. If the LP has `fraction_of_time_on_book` = `0.3` at the end of the next epoch, they are meeting their commitment and will not forfeit any of their bond stake. (0044-LIME-088). For product spot (0044-LIME-103) -- If a liquidity provider has `fraction_of_time_on_book` = `0.3`, `market.liquidity.commitmentMinTimeFraction = 0.0`, `market.liquidity.sla.nonPerformanceBondPenaltySlope = 0.7`, `market.liquidity.sla.nonPerformanceBondPenaltyMax = 0.6`and the market parameter change `market.liquidity.commitmentMinTimeFraction = 0.6` is enacted during the epoch then at the end of the current epoch LP will not forfeit any of their bond stake. If the LP has `fraction_of_time_on_book` = `0.3` at the end of the next epoch at the end of the next epoch, the LP will have their bond slashed. (0044-LIME-089). For product spot (0044-LIME-104) -- If a liquidity provider has `fraction_of_time_on_book` = `0`, `market.liquidity.commitmentMinTimeFraction = 0.6`, `market.liquidity.sla.nonPerformanceBondPenaltySlope = 0.7`, `market.liquidity.sla.nonPerformanceBondPenaltyMax = 0.6` at the end of an epoch then they will forfeit `60%` of their bond stake, which will be transferred into the market's insurance pool (0044-LIME-015) -and in the case of spot markets into the network treasury for the asset (0044-LIME-046) -- If a liquidity provider has `fraction_of_time_on_book` = `0`, `market.liquidity.commitmentMinTimeFraction = 0.6`, `market.liquidity.sla.nonPerformanceBondPenaltySlope = 0.2`, `market.liquidity.sla.nonPerformanceBondPenaltyMax = 0.6` at the end of an epoch then they will forfeit `20%` of their bond stake, which will be transferred into the market's insurance pool (0044-LIME-016) -and in the case of spot markets into the network treasury for the asset (0044-LIME-047) - -- If a liquidity provider with an active liquidity provision at the start of an epoch reduces their liquidity provision staked commitment during the epoch the initial committed level at the start of the epoch will remain in effect until the end of the epoch, at which point the protocol will attempt to reduce the bond to the new level. (0044-LIME-018). For product spot (0044-LIME-105) -- If a liquidity provider with an active liquidity provision at the start of an epoch reduces their liquidity provision staked commitment during the epoch the initial committed level at the start of the epoch will remain in effect until the end of the epoch, at which point the protocol will attempt to reduce the bond to the new level. If the reduced level has been changed several times during an epoch, only the latest value will take effect (0044-LIME-019). For product spot (0044-LIME-106) -- If a liquidity provider with an active liquidity provision at the start of an epoch reduces their liquidity provision staked commitment during the epoch the initial committed level at the start of the epoch will remain in effect until the end of the epoch, at which point the protocol will attempt to reduce the bond to the new level. If the bond stake has been slashed to a level lower than the amendment, this slashed level will be retained (i.e. the protocol will not attempt to now increase the commitment) (0044-LIME-020). For product spot (0044-LIME-107) -- If a liquidity provider with an active liquidity provision at the start of an epoch amends the fee level associated to this commitment during the epoch, this change will only take effect at the end of the epoch. (0044-LIME-021). For product spot (0044-LIME-108) -- If a liquidity provider with an active liquidity provision at the start of an epoch increases their liquidity provision staked commitment during the epoch, the amended committed level will take affect immediately and the protocol will attempt to increase the bond to the new level, if they do not have sufficient collateral in the settlement asset of the market to meet new commitment amount then the amendment will be rejected and old commitment amount is retained (0044-LIME-030). For product spot (0044-LIME-109) -- If a liquidity provider with an active liquidity provision at the start of an epoch increases their liquidity provision staked commitment during the epoch, the amended committed level will take affect immediately and - - the protocol will increase the bond to the new level if they have sufficient collateral in the settlement asset of the market to meet new commitment amount (0044-LIME-031). For product spot (0044-LIME-110) - - at the end of the current epoch rewards / penalties are evaluated based on the balance of the bond account at start of epoch (0044-LIME-049). For product spot (0044-LIME-111) - -- A liquidity provider who reduces their liquidity provision such that the total stake on the market is still above the target stake after reduction will have no penalty applied and will receive their full reduction in stake back at the end of the epoch. (0044-LIME-022). For product spot (0044-LIME-112) -- For a market with `market.liquidity.earlyExitPenalty = 0.25` and `target stake > total stake` already, a liquidity provider who reduces their commitment by `100` will only receive `75` back into their general account with `25` transferred into the market's insurance account. (0044-LIME-023) -In the case of spot markets it will be transferred into the network treasury for the asset (0044-LIME-045) -- For a market with `market.liquidity.earlyExitPenalty = 0.25` and `total stake = target stake + 40` already, a liquidity provider who reduces their commitment by `100` will receive a total of `85` back into their general account with `15` transferred into the market's insurance account (`40` received without penalty, then the remaining `60` receiving a `25%` penalty). (0044-LIME-024). In the case of spot markets it will be transferred into the network treasury for the asset (0044-LIME-044) - -- For a market with `market.liquidity.earlyExitPenalty = 0.25` and `total stake = target stake + 140` already, if one liquidity provider places a transaction to reduce their stake by `100` followed by a second liquidity provider who reduces their commitment by `100`, the first liquidity provider will receive a full `100` stake back whilst the second will receive a total of `85` back into their general account with `15` transferred into the market's insurance account (`40` received without penalty, then the remaining `60` receiving a `25%` penalty). (0044-LIME-025) - -In the case of spot markets it will be transferred into the network treasury for the asset (0044-LIME-043) - - -- For a futures market with `market.liquidity.earlyExitPenalty = 0.25` and `total stake = target stake + 140` already, if the following transactions occur: - - - `LP1` places a transaction to reduce their stake by `30` - - `LP2` places a transaction to reduce their stake by `100`, and then wait until end of the epoch, - - `LP1` places a transaction to update their reduction to `100` - `LP2` will receive a full `100` stake back whilst `LP1` will receive a total of `85` back into their general account with `15` transferred into the market's insurance account (0044-LIME-026) -- When LP is committed they are obliged to provide liquidity equal to their commitment size on both sides of the order book (0044-LIME-027) -- For a market that is in opening auction and LP has committed liquidity: - - When a LP increases their commitment then: - - It takes effect immediately for the purposes of LP stake supplied to the market - - In terms of the liquidity they are expected to supply: this only takes effect from the start of the next epoch - (0044-LIME-050). For spot (0044-LIME-054) - - LP can decrease or cancel their commitment and it will take effect immediately without incurring penalties (0044-LIME-051). For spot (0044-LIME-055) - - If target stake is 0 then any LP can cancel their commitment without incurring penalties (0044-LIME-053) - -- For a market that is in continuous trading and a single LP has committed liquidity: - - The LP can cancel their commitment at any time (though this may involve incurring a penalty) (0044-LIME-060). For spot (0044-LIME-056) -- During continuous trading an LP can submit a transaction to decrease commitment but it will only happen at the end of current epoch. (0044-LIME-101) - -- For a market that is in continuous trading and LP has committed liquidity - - if `market.liquidity.providersFeeCalculationTimeStep` is set to `10s` and `validators.epoch.length` is set to `15s`, during the first `10` seconds of the current epoch parameter change `market.liquidity.providersFeeCalculationTimeStep = 3s` is enacted, at the end of the epoch any funds that are in `ACCOUNT_TYPE_FEES_LIQUIDITY` account will be distributed to `ACCOUNT_TYPE_LP_LIQUIDITY_FEES` on the next block. For the next epoch the distribution will take place at `3` second intervals (0044-LIME-062) -- For a market that is in continuous trading if a new LP has active buy and sell orders on the market then makes a liquidity commitment to that market, at the start of the next epoch the active orders will count towards the LPs liquidity commitment. (0044-LIME-090) -- If an LP with a liquidity provision and active orders on a market cancels their liquidity provision (orders remain active), after the cancellation penalty (if it applies at end of epoch) at the end of the next epoch the LP will not accrue any rewards for trades on the market. (0044-LIME-097) -- Consider a market where `market.liquidity.priceRange = 0.05 (5%)` and which is in continuous trading with a mid price of 5. There is an LP who's committed to provide liquidity. They place a buy order at a price of 4.75 and a sell order at a price of 5.25 (with sufficient volume). As the epoch progresses, if the market parameter is altered to `market.liquidity.priceRange = 0.01` (1%), then upon the culmination of the current epoch, the LP will still have fulfilled their committed notional volume, rendering them exempt from a bond penalty. (0044-LIME-091) - -- Consider a market, where `market.liquidity.priceRange = 0.05`, and which is in continuous trading with a mid price set at 5. There is an LP who's committed to provide liquidity. They place a buy order at a price of 4.74 and a sell order at a price of 5.25 (with sufficient volume). As the epoch progresses, if the market parameter is altered to `market.liquidity.priceRange = 0.01` (1%), then upon the culmination of the ongoing epoch, the LP will not have met their committed notional volume, resulting in the imposition of a bond penalty. (0044-LIME-093). For product spot (0044-LIME-113) - -- Consider a market, where `market.liquidity.priceRange = 0.05`, and which is in monitoring auction with the last trade price set at 5, the indicative uncrossing price is set at 4. There is an LP who's committed to provide liquidity. They place a buy order at a price of 3.79 (which is less than `5%` of `1-0.05 x min(5, 4) = 3.80`), and a sell order at a price of 5.25 (with sufficient volume). At the end of the epoch, the LP has not fulfilled their committed notional volume, resulting in the imposition of a bond penalty. (0044-LIME-094). For product spot (0044-LIME-114) - -- Consider a market, where `market.liquidity.priceRange = 0.05`, and which is in monitoring auction with `last trade price` set to `5`, `indicative uncrossing price` is set to `4`. There is a LP who's committed to provide liquidity. They place a buy order at price `3.8` and a sell order at price `5.25` (with sufficient volume). At the end of the epoch, the LP is meeting their committed volume of notional rendering them exempt from a bond penalty. (0044-LIME-095). For product spot (0044-LIME-115) - -- Consider a market, where `market.liquidity.priceRange = 0.05`, and which is in monitoring auction with `last trade price` set to `5`, `indicative uncrossing price` is set to `6`. There is a LP who's committed to provide liquidity. They place a buy orders at price `4.75` and sell order at price `6.31` (which is larger than `5%` of `1+ 0.05 x max (5, 6) = 6.30`). At the end of the epoch, the LP is not meeting their committed volume of notional, resulting in the imposition of a bond penalty. (0044-LIME-096). For product spot (0044-LIME-116) - -- Consider a market, where `market.liquidity.priceRange = 0.05`, and which is in monitoring auction with `last trade price` set to `5` and we do not have `indicative uncrossing price`. There is a LP who's committed to provide liquidity. They place a buy orders at price `4.74` (which is less than `5%` of `1-0.05 x min(5, n/a) = 4.75`) and sell order at price `5.25`. At the end of the epoch, the LP is not meeting their committed volume of notional, resulting in the imposition of a bond penalty. (0044-LIME-098). For product spot (0044-LIME-117) - -- Consider a market, where `market.liquidity.priceRange = 0.05`, and which is in monitoring auction with `last trade price` set to `5` and we do not have `indicative uncrossing price`. There is a LP who's committed to provide liquidity. They place a buy orders at price `4.75` and sell order at price `5.26` (which is is more than `5%` of `1+ 0.05 x max (5, n/a) = 5.25`). At the end of the epoch, the LP is not meeting their committed volume of notional, resulting in the imposition of a bond penalty. (0044-LIME-099). For product spot (0044-LIME-118) - -- Consider a market, where `market.liquidity.priceRange = 0.05`, and which is in monitoring auction with `last trade price` set to `5` and we do not have `indicative uncrossing price`. There is a LP who's committed to provide liquidity. They place a buy orders at price `4.75` and sell order at price `5.25`. At the end of the epoch, the LP is meeting their committed volume of notional rendering them exempt from a bond penalty. (0044-LIME-092). For product spot (0044-LIME-119) - -- When the LP increases its commitment and the increment is higher than its general account balance, the increments are rejected, and the old provision persists. (0044-LIME-063). For spot (0044-LIME-064) -- When LP decreases its commitment so that $\text{commitment-variation}_i <= \text{maximum-penalty-free-reduction-amount}_i$, then the entire amount by which they decreased their commitment is transferred to their general account, their ELS got updated as per the [ELS calculation](0042-LIQF-setting_fees_and_rewarding_lps.md)(0044-LIME-065). For spot (0044-LIME-066) -- When LP decreases its commitment so that $\text{commitment-variation}_i > \text{maximum-penalty-free-reduction-amount}_i$ , $(1-\text{market.liquidity.earlyExitPenalty}) \cdot \text{penalty-incurring-reduction-amount}_i$ should be transferred into its general account and $\text{market.liquidity.earlyExitPenalty} \cdot \text{penalty-incurring-reduction-amount}_i$ should be transferred into market insurance pool (0044-LIME-067). For spot $\text{market.liquidity.earlyExitPenalty} \cdot \text{penalty-incurring-reduction-amount}_i$ should be transferred into the network treasury for the asset (0044-LIME-068) -- When an LP creates a new provision with zero commitment, it should be rejected with an error message stating that the commitment amount is zero. (0044-LIME-069). For spot (0044-LIME-070) -- When an LP amends the Fee Factor to a value greater than `market.liquidity.maximumLiquidityFeeFactorLevel`, the amendments are rejected (0044-LIME-071). For spot (0044-LIME-072) -- A distressed LP (when `bond account == 0 && general account == 0 && margin account < maintenance margin`) will have their orders cancelled. If the LP remains distressed, the network takes over any positions the LP may hold and zeroes them out (closes them out) (0044-LIME-073). -- If a party submits LP provisions in multiple markets then multiple bond accounts are created and managed by Vega.(0044-LIME-075). For spot (0044-LIME-076) - - -### Qualifying Order Types - -- Once liquidity is committed, LPs can meet their commitment by placing limit orders, pegged limit orders, and iceberg orders. For iceberg orders, all the volume (including displayed and remaining volume) counts towards the commitment. (0044-LIME-028). For spot (0044-LIME-029) -- Parked pegged limit orders and stop-loss orders do not count towards an LPs liquidity commitment. (0044-LIME-077). For spot (0044-LIME-078) -- GFA orders during auction from LP count towards LPs liquidity commitment (0044-LIME-079). For spot (0044-LIME-080) -- GFA orders during continuous trading mode from LP do not count towards the LP's liquidity commitment (0044-LIME-081). For spot (0044-LIME-082) - -### Snapshot - -- A snapshot must include the aggregate LP fee accounts and their balances so that after a node is started using the snapshot it can retain the aggregate LP fee accounts and their balances for each market. (0044-LIME-032) - -### Protocol upgrade - -- After a protocol upgrade each market's aggregate LP fee accounts and their balances are retained (0044-LIME-033) - -#### Network History - Data node restored from network history segments - -- A datanode restored from network history will contain each market's aggregate LP fee accounts which were created prior to the restore and these can be retrieved via APIs on the new datanode. (0044-LIME-036) - -#### Network parameters validation - -- Boundary values are respected for the network parameters - - `market.liquidityV2.bondPenaltyParameter` valid values: `>=0`, `<=1000` default value of `0.1` (0044-LIME-037) - - `market.liquidityV2.earlyExitPenalty` valid values: `>=0`, `<=1000` default value of `0.1` (0044-LIME-038) - - `market.liquidityV2.maximumLiquidityFeeFactorLevel` valid values: `>=0`, `<=1` default value of `1` (0044-LIME-039) - - `market.liquidityV2.sla.nonPerformanceBondPenaltySlope` valid values: `>=0`, `<=1000` default value of `2` (0044-LIME-040) - - `market.liquidityV2.sla.nonPerformanceBondPenaltyMax` valid values: `>=0`, `<=1` default value of `0.5` (0044-LIME-041) - - `market.liquidityV2.stakeToCcyVolume` valid values: `>=0`, `<=100` default value of `1` (0044-LIME-042) - - `market.liquidity.providersFeeCalculationTimeStep` valid values: `>0`, `<= validators.epoch.length` default value of `60m` (0044-LIME-100) - -#### Market parameters validation - -- Boundary values are respected for the market parameters - - `market.liquidity.commitmentMinTimeFraction` valid values: `>=0`, `<=1` (0044-LIME-083) - - `market.liquidity.priceRange` valid values: `>0`, `<=20` (0044-LIME-084) - - `market.liquidity.slaCompetitionFactor` valid values: `>=0`, `<=1` (0044-LIME-085) - - `market.liquidity.performanceHysteresisEpochs` valid values: `>=0`, `<=366` (0044-LIME-086)