feat: lp 3.0

protocol/0056-REWA-rewards_overview.md

@@ -215,6 +215,28 @@ This flag is used to prevent any given funder from funding a creation reward in
 
 Note this reward metric **is not** available for team rewards.
 
+### Liquidity SLA Metric
+
+The Liquidity SLA metric, $m_{lq}$, rewards LPs for providing greater volumes of notional within a specified range for at least a specific proportion of the epoch.
+
+The mechanics for calculating each LPs volume of notional is the same as for the liquidity mechanics specified in [0095-LIQM](./0095-LIQM-liquidity_mechanisms.md#volume-of-notional) but instead of using the markets SLA parameters the SLA parameters specified in the transfer are used.
+
+>[!NOTE]
+> As a market can support multiple liquidity SLA rewards each specifying their own SLA parameters the network must track the [instantaneous volume of notional](./0095-LIQM-liquidity_mechanisms.md#instantaneous-volume-of-notional) supplied by each LP within each unique liquidity price range.
+
+At the end of the epoch, the average realised return metric over the last $N$ epochs is calculated as follows.
+
+Let:
+
+- $m_{lp}$ be the parties LPs  metric.
+- $v_{i}$ be the parties "volume of notional" for epoch $i$.
+- $N$ be the window length specified in the recurring transfer.
+
+$$m_{lp} = \frac{\sum_{i}^{n}{v_{i}}}{N}$$
+
+As a point of clarification, the network will only calculate a volume of notional for parties designated as an LP for that epoch, see [designating liquidity providers](./0095-LIQM-liquidity_mechanisms.md#designating-liquidity-providers) from the liquidity mechanics spec. Therefore if a party is not designated as an LP for an epoch their reward metric will be `0` regardless of whether they provided volume or not.
+
+
 ## Team reward metrics
 
 All metrics (except [market creation](#market-creation-reward-metrics)) can be used to define the distribution of both individual rewards and team rewards.

protocol/0057-TRAN-transfers.md

@@ -39,8 +39,12 @@ In order to prevent the abuse of user-initiated transfers as spam attack there w
 
 ## Minimum transfer amount
 
-This is controlled by the `transfer.minTransferQuantumMultiple` and quantum specified for the [asset](0040-ASSF-asset_framework.md).
-The minimum transfer amount is `transfer.minTransferQuantumMultiple x quantum`.
+Transfers are subject to a minimum transfer amount (expressed in quantum).
+
+- transfers to a reward pool are controlled by `transfer.minRewardTransferQuantumMultiple`.
+- all other transfers are controlled by `transfer.minTransferQuantumMultiple`.
+
+These network parameters are quantum specified for the relevant [asset](0040-ASSF-asset_framework.md) and the minimum transfer amount is the product of the relevant network parameter and the assets quantum.
 
 If a user is transferring funds from a vested account, if their balance (expressed in quantum) is less than the minimum amount, they should be able to transfer the full balance (note, transferring less than the full balance is not permitted).
 
@@ -113,6 +117,7 @@ A party should be able to configure the distribution of rewards by specifying th
 - `lock_period` - the number of epochs after distribution to delay [vesting of rewards](./0085-RVST-rewards_vesting.md#vesting-mechanics) by.
 - `cap_reward_fee_multiple` [optional] - if set, the actual amount of reward transferred to each public key during distribution for this transfer will be `min(calculated_reward_in_quantum, cap_reward_fee_multiple × feed_paid_since_last_payout)` (fees paid since last payout is akin to checking the total fees paid over the last `transfer_interval` epochs). When calculating how much of the reward each one is getting, if some is left from the applied cap, we recalculate on the remaining balance only for parties that have not reached their cap until the leftover is less than 1 reward asset unit or the maximum rounds of recalculation is 10. If all keys are capped (i.e. the total amount of the transfer cannot be be sent to eligible keys without breaching the cap) then the remaining balance must be left in the reward pool and included in the distribution in future epochs. If this occurs, and the total transferred in a given epoch, this does not affect the size of the next iteration, which proceeds as normal (including decay factors etc.) as if the full transfer has been made.
 Here, `feed_paid_since_last_payout` are the total trading fees paid by a party (arising from `infrastructure_fee` paid, `maker_fee` paid plus `liquidity_fee` paid, since the last payout and expressed in quantum units).
+- `sla_parameters` - to support the [Liquidity SLA Metric](./0056-REWA-rewards_overview.md#liquidity-sla-metric), if the distribution metric is `DISPATCH_METRIC_LIQUIDITY_SLA`, SLA parameters must be provided for the network to evaluate each LPs liquidity performance. These parameters are the same as defined in the [liquidity mechanisms specification](./0095-LIQM-liquidity_mechanisms.md#volume-of-notional).
 - `distribution_strategy` - enum defining which [distribution strategy](./0056-REWA-rewards_overview.md#distributing-rewards-between-entities) to use.
   - `DISTRIBUTION_STRATEGY_PRO_RATA` - rewards should be distributed among entities [pro-rata](./0056-REWA-rewards_overview.md#distributing-pro-rata) by reward-metric.
   - `DISTRIBUTION_STRATEGY_RANK` - rewards should be distributed among entities [based on their rank](./0056-REWA-rewards_overview.md#distributing-based-on-rank) when ordered by reward-metric.

protocol/0096-LIQM-liquidity_mechanisms.md

@@ -0,0 +1,122 @@
+# On-Chain Liquidity Mechanisms
+
+## Summary
+
+The aim of the on-chain liquidity mechanisms are to reward parties for supplying competitively priced liquidity and facilitating the growth of a market. At a high level, the liquidity mechanisms are:
+
+- parties [accrue](#accruing-els-points) ELS points over time proportional to their maker fees earned.
+- parties are [designated](#designating-liquidity-providers) as LPs on an epoch by epoch basis if they receive above a specified proportion of the markets maker fees.
+- parties [receive](#distributing-liquidity-fees) a proportion of the liquidity fees accumulated in an epoch relative to their [accrued](#accruing-els-points) ELS points and [volume of notional](#volume-of-notional) (but only when designated as an LP).
+
+With the above mechanisms the protocol incentives the following desirable behaviour.
+
+- **Early adoption** - parties accrue ELS points which never decay over time. Early adopters of a market will benefit from accrued ELS points for the entire duration of the markets life-cycle.
+- **Tight spreads** - parties are incentivised to be at the front of the book as ELS points are only accrued when a party is the non-aggressive side of a trade.
+- **Deep liquidity** - parties are incentivised to supply a larger volume of notional liquidity within a configurable range to receive a larger share of the liquidity fees.
+- **Active market making** - parties who accumulate a large number of ELS points will still need to be designated as an LP in order to receive a proportion of the liquidity fees accumulated each epoch. Therefore parties are incentivised to continue to provide competitively priced liquidity even after accruing a large number of ELS points.
+
+The mechanisms also enable the following features:
+
+- **Key rotation** - ELS points are implemented as internal assets, as such they can be transferred between keys and traded.
+
+## Network parameters
+
+### `liquidityProvider.proportionRequirement`
+
+A number in the range $[0, 1]$ which defines the minimum proportion of a markets maker fees a party must receive in order to be [designated](#designating-liquidity-providers) as an LP for the next epoch. The parameter should default to `0.1`.
+
+Updates to this parameter will be used the next time LPs are designated, i.e. updating the network parameter will not result in LPs instantly being re-designated.
+
+## Accruing ELS Points
+
+Whenever a market proposal is enacted (passes opening auction), an internal Vega asset is created to track the ELS points of that market. For a successor market, a new asset should not be created and instead the ELS asset of the parent market should be used.
+
+At the end of each epoch, each party accrues ELS points for the relevant market as follows:
+
+$$ELS_{i_j} = V_{i_j} \cdot 10^{-Q}$$
+
+Where:
+
+- $ELS_{j}$ is the ELS points accrued by party $j$ in epoch $i$
+- $V_{i_j}$ is the notional maker fees of party $j$ in epoch $i$
+- $Q$ is the quantum of the asset in which the markets prices are expressed in (settlement for future and perpetual markets, quote for spot markets)
+
+> [!NOTE]
+> the maker fees is scaled by the assets quantum such that 1 ELS point is earned for approx. every 1 USD of maker fees received.
+
+## Designating Liquidity Providers
+
+A party will only be able to receive liquidity fees or earn liquidity rewards providing they are designated as an LP for that epoch.
+
+A party will only be designated as an LP providing they received more than a specified proportion of the markets total maker fees in the previous epoch, let this requirement be $N$ (the network parameter `liquidityProvider.proportionRequirement`). Throughout the epoch the network will track each parties maker fees, $M$.  At the end of epoch $i$, a party will be designated as an LP for epoch $i+1$ providing:
+
+$$\frac{M_{i_j}}{\sum_{k}^{n}{M_{i_j}}} >= N$$
+
+Where:
+
+- $M_{i_j}$ is the maker fees of party ${j}$ in epoch ${i}$
+- $N$ the requirement specified by the network parameter `liquidityProvider.proportionRequirement`
+
+By designating parties as LPs on an epoch by epoch basis the protocol ensures:
+
+- "in-active" parties with a large number of ELS points will no longer be rewarded through liquidity mechanisms should they stop providing liquidity (or provide un-competitive liquidity).
+- "late-arriving" parties with a small number of ELS points will be rewarded through liquidity mechanisms if they provide competitive liquidity and as such comprise a larger proportion of the markets volume.
+
+## Volume of Notional
+
+The volume of notional is a measure of how much liquidity an LP provided to a market throughout the epoch.
+
+Each LPs `volume of notional` is defined as, the maximum notional volume that they supplied through orders within a specified range for at least N % of the epoch.
+
+The range and required proportion of the epoch are controlled though market configurable SLA parameters:
+
+- `lp_price_range`: a number in the range $[0, 100]$ which defines the range in which an LPs orders will contribute towards their volume of notional, refer to section [instantaneous volume-of-notional](#instantaneous volume of notional) for more details.
+- `minimum_time_fraction`: a number in the range $[0, 1]$ which defines the minimum proportion of an epoch an LP must have provided an amount of volume for in order for that amount to be set as their volume of notional, refer to section [calculating the volume of notional](#calculating-the-volume-of-notional) for more details.
+
+### Instantaneous Volume of Notional
+
+To calculate each LPs volume of notional, throughout the epoch, the network must sample and store the current volume of notional supplied by each LP at that point. Call this the instantaneous volume of notional. For now this is done once a block but could be sampled randomly to reduce the amount of data stored.
+
+>[!NOTE]
+> Whilst the SLA parameters are uniquely configurable per market, they can also be specified for a liquidity SLA reward metric. As such, for each LP, the network must also track the instantaneous volume of notional provided within each unique price range specified by a reward.
+
+Calculating the notional volume supplied at any given point in time is done as follows:
+
+Whilst in continuous trading:
+
+- If there is no mid price each LP is treated as supplying `0` volume.
+
+- If there is a mid price calculate the volume of notional that is in the range.
+
+```text
+(1.0-lp_price_range) x mid <= price levels <= (1+lp_price_range)x mid
+```
+
+Whilst in monitoring auctions:
+
+- If there is an indicative uncrossing price calculate the volume of notional that is in the range.
+
+```text
+(1.0-lp_price_range) x min(last trade price, indicative uncrossing price) <=  price levels <= (1.0+lp_price_range) x max(last trade price, indicative uncrossing price)
+```
+
+- If there is no 'indicative uncrossing price' each LP is treated as supplying `0` volume.
+
+### Calculating the Volume of Notional
+
+At the end of the epoch, before distributing fees, each LPs `volume of notional` is set to the largest volume of notional that was supplied for at least a specified proportion of the epoch, i.e. in a sorted array of supplied liquidity amounts, the commitment amount would be element $i$ where:
+
+$$i= \lceil\text{len(array)}\cdot{\text{minTimeFraction}}\rceil$$
+
+## Distributing Liquidity Fees
+
+At the end of epoch, after each party accrues ELS points for that epochs volume, the accumulated liquidity fees are distributed pro-rata amongst liquidity providers weighted by their accrued ELS points as follows.
+
+$$f_{i_j} = f_{i} \cdot \frac{ELS_j\cdot{V_j}}{\sum_{k}^{n}{ELS_k\cdot{L_k}}}$$
+
+Where:
+
+- $f_{i_j}$ is the liquidity fees distributed to party $j$ in epoch $i$
+- $f_{i}$ is the liquidity fees accumulated by the market in epoch $i$
+- $ELS_j$ is the current number of ELS points for party $j$
+- $V_j$ is the volume of notional of party $j$

spellcheck.yaml

@@ -1,6 +1,5 @@
 ---
 
-
 matrix:
 
   - name: Markdown
@@ -35,9 +34,18 @@ matrix:
             # Ignore text between inline back ticks
             - open: '`'
               close: '`'
+            # Ignore text between inline dollar signs (KaTex/LaTeX math)
+            - open: '$'
+              close: '$'
             # Ignore hugo/jinja tags
             - open: '{{'
               close: '}}'
+            # Ignore display LaTeX formulas ($$ ... $$)
+            - open: '\$\$'
+              close: '\$\$'
+            # Ignore display LaTeX formulas ($$ ... $$)
+            - open: '\$'
+              close: '\$'
       - pyspelling.filters.markdown: null
       - pyspelling.filters.html:
           comments: false