feat: add staking discount spec

protocol/0029-FEES-fees.md

@@ -23,7 +23,7 @@ Note that maker_fee = 0 if there is no maker, taker relationship between the tra
 
 ## Applying benefit factors
 
-Before fees are transferred, if there is an [active referral program](./0083-RFPR-on_chain_referral_program.md) or [volume discount program](./0085-VDPR-volume_discount_program.md), each parties fee components must be modified as follows.
+Before fees are transferred, if there is an active [referral program](./0083-RFPR-on_chain_referral_program.md), [volume discount program](./0085-VDPR-volume_discount_program.md), or [staking discount program](./0087-SDPR-staking_discount_program.md). Each parties fee components must be modified as follows.
 
 Note, it is important discounts are calculated and applied **before** rewards are calculated and applied.
 
@@ -43,12 +43,20 @@ Note, it is important discounts are calculated and applied **before** rewards ar
     maker_fee_volume_discount = floor(maker_fee * volume_discount_factor)
     ```
 
+1. Calculate any staking discounts due to the party.
+
+    ```pseudo
+    infrastructure_fee_staking_discount = floor(infrastructure_fee * staking_discount_factor)
+    liquidity_fee_staking_discount = floor(liquidity_fee * staking_discount_factor)
+    maker_fee_staking_discount = floor(maker_fee * staking_discount_factor)
+    ```
+
 1. Update the fee components by applying the discounts.
 
     ```pseudo
-    infrastructure_fee = infrastructure_fee - infrastructure_fee_referral_discount - infrastructure_fee_volume_discount
-    liquidity_fee = liquidity_fee - liquidity_fee_referral_discount - liquidity_fee_volume_discount
-    maker_fee = maker_fee - maker_fee_referral_discount - maker_fee_volume_discount
+    infrastructure_fee = infrastructure_fee - infrastructure_fee_referral_discount - infrastructure_fee_volume_discount - infrastructure_fee_staking_discount
+    liquidity_fee = liquidity_fee - liquidity_fee_referral_discount - liquidity_fee_volume_discount - liquidity_fee_staking_discount
+    maker_fee = maker_fee - maker_fee_referral_discount - maker_fee_volume_discount - maker_fee_staking_discount
     ```
 
 1. Calculate any referral rewards due to the parties referrer (Note we are using the updated fee components from step 3 and the `referralProgram.maxReferralRewardProportion` is the network parameter described in the [referral program spec](./0083-RFPR-on_chain_referral_program.md#network-parameters))
@@ -180,3 +188,10 @@ For example, Ether is 18 decimals (wei). The smallest unit, non divisible is 1 w
 1. Volume discount rewards are correctly calculated and transferred for each fee component when exiting an auction. (<a name="0029-FEES-028" href="#0029-FEES-028">0029-FEES-028</a>)
     - `infrastructure_fee_volume_discount`
     - `liquidity_fee_volume_discount`
+1. Staking discounts are correctly calculated and applied for each fee component during continuous trading. (<a name="0029-FEES-029" href="#0029-FEES-029">0029-FEES-029</a>)
+    - `infrastructure_fee_volume_discount`
+    - `liquidity_fee_volume_discount`
+    - `maker_fee_volume_discount`
+1. Staking discounts are correctly calculated and applied for each fee component when exiting an auction. (<a name="0029-FEES-030" href="#0029-FEES-030">0029-FEES-030</a>)
+    - `infrastructure_fee_volume_discount`
+    - `liquidity_fee_volume_discount`

protocol/0087-SDPR-staking_discount_program.md

@@ -0,0 +1,74 @@
+# Staking Discount Program
+
+The staking discount program provides tiered discounts on taker fees to traders. A trader accesses greater discounts by increasing the average number of $VEGA governance tokens staked over a specified number of epochs.
+
+## Network parameters
+
+- `stakingDiscountProgram.benefitTiers`: is an ordered list of dictionaries defining the requirements and benefits for each tier.
+- `stakingDiscountProgram.windowLength`: is an integer defining the number of previous epochs over which to average a parties staked tokens. This value must be an integer strictly greater than 0 and less than 100. It should default to 1.
+
+## Benefit Mechanics
+
+### Setting benefit factors
+
+At the start of an epoch the network should calculate each parties `party_average_staked_tokens` by averaging the number of tokens a party has staked over the last n epochs where n is the network parameter `stakingDiscountProgram.windowLength`.
+
+Each parties `staking_discount_factor` is then fixed to the value in the highest benefit tier they qualify for. A parties benefit tier is defined as the highest tier for which their `party_average_staked_tokens` is greater or equal to the tiers `minimum_average_staked_tokens`. If a party does not qualify for any tier, their `staking_discount_factor` is set to `0`.
+
+```pseudo
+Given:
+    stakingDiscountProgram.benefitTiers=[
+        {
+            "minimum_average_staked_tokens": 1000,
+            "staking_discount_factor": 0.001,
+        },
+        {
+            "minimum_average_staked_tokens": 5000,
+            "staking_discount_factor": 0.005,
+        },
+        {
+            "minimum_average_staked_tokens": 20000,
+            "staking_discount_factor": 0.010,
+        },
+    ]
+
+And:
+    party_average_staked_tokens=2432
+
+Then:
+    staking_discount_factor=0.005
+```
+
+This benefit factor is then fixed for the duration of the next epoch.
+
+### Applying benefit factors
+
+Staking discount program benefit factors are applied by modifying [the fees](./0029-FEES-fees.md) paid by a party (either during continuous trading or on auction exit).
+
+## APIs
+
+The Parties API should expose the following information:
+
+- a list of all **parties** (by `id`) and the following metrics:
+  - current `party_average_staked_tokens` (value at the start of the epoch)
+  - current `staking_discount_factor` applied to fees
+
+The Trades API should now also expose the following additional information for every trade:
+
+- Volume discount program discounts
+  - `infrastructure_fee_staking_discount`
+  - `liquidity_fee_staking_discount`
+  - `maker_fee_staking_discount`
+
+## Acceptance Criteria
+
+### Setting benefit factors
+
+1. At the start of an epoch, each parties `staking_discount_factor` is reevaluated and fixed for the epoch (<a name="0087-SDPR-001" href="#0087-SDPR-001">0087-SDPR-001</a>).
+1. A parties `staking_discount_factor`  is set equal to the factors in the highest benefit tier they qualify for (<a name="0087-SDPR-002" href="#0087-SDPR-002">0087-SDPR-002</a>).
+1. If a party does not qualify for the lowest tier, their `staking_discount_factor`is set to `0` (<a name="0087-SDPR-003" href="#0087-SDPR-003">0087-SDPR-003</a>).
+
+### Updating network parameters
+
+1. If `stakingDiscountProgram.benefitTiers` is updated in the middle of an epoch, each parties `staking_discount_factor` value will not change un till the next epoch when they are reevaluated (<a name="0087-SDPR-004" href="#0087-SDPR-004">0087-SDPR-004</a>).
+1. If `stakingDiscountProgram.windowLength` is updated in the middle of an epoch, each parties `staking_discount_factor` value will not change un till the next epoch when they are reevaluated (<a name="0087-SDPR-005" href="#0087-SDPR-005">0087-SDPR-005</a>).

protocol/features.json

@@ -450,6 +450,18 @@
       "0029-FEES-028"
     ]
   },
+"Staking discounts": {
+    "milestone": "deployment-3",
+    "acs": [
+      "0087-SDPR-001",
+      "0087-SDPR-002",
+      "0087-SDPR-003",
+      "0087-SDPR-004",
+      "0087-SDPR-005",
+      "0029-FEES-029",
+      "0029-FEES-030"
+    ]
+  },
   "Market governance": {
     "milestone": "deployment-2",
     "acs": [