feat: add liquidity SLA reward metric (#2309)

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/0095-LIQM-liquidity_mechanisms.md

@@ -73,11 +73,13 @@ The range and required proportion of the epoch are controlled though market conf
 - `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: