feat: add acs for program update behaviour

protocol/0083-RFPR-on_chain_referral_program.md

@@ -512,6 +512,9 @@ The Estimate Fees API should now calculate the following additional information:
     - `referralProgram.maxReferralRewardFactor` (<a name="0083-RFPR-042" href="#0083-RFPR-042">0083-RFPR-042</a>)
     - `referralProgram.maxReferralDiscountFactor` (<a name="0083-RFPR-043" href="#0083-RFPR-043">0083-RFPR-043</a>)
 
+1. Given a referral program is not active, if an `UpdateReferralProgram` is enacted in epoch `k`. The program should be active in `k+1` **AND** all parties that qualify for a tier in the new program should receive the relevant factors from the new programs tier. (<a name="0083-RFPR-056" href="#0083-RFPR-056">0083-RFPR-056</a>).
+1. Given a referral program is active, if an `UpdateReferralProgram` is enacted in epoch `k`. The program should be updated in `k+1` **AND** all parties that qualify for a tier in the updated program should receive the relevant factors from the updated programs tier. (<a name="0083-RFPR-057" href="#0083-RFPR-057">0083-RFPR-057</a>).
+
 ### Referral set mechanics
 
 #### Creating a referral set

protocol/0084-VDPR-volume_discount_program.md

@@ -170,6 +170,9 @@ The Trades API should now also expose the following additional information for e
     - `volumeDiscountProgram.maxBenefitTiers` (<a name="0084-VDPR-015" href="#0084-VDPR-015">0084-VDPR-015</a>).
     - `volumeDiscountProgram.maxVolumeDiscountFactor` (<a name="0084-VDPR-016" href="#0084-VDPR-016">0084-VDPR-016</a>).
 
+1. Given a volume discount program program is not active, if an `UpdateVolumeDiscountProgram` is enacted in epoch `k`. The program should be active in `k+1` **AND** all parties that qualify for a tier in the new program should receive the relevant factors from the new programs tier. (<a name="0083-RFPR-019" href="#0083-RFPR-019">0083-RFPR-019</a>).
+1. Given a volume discount program program is active, if an `UpdateVolumeDiscountProgram` is enacted in epoch `k`. The program should be updated in `k+1` **AND** all parties that qualify for a tier in the updated program should receive the relevant factors from the updated programs tier. (<a name="0083-RFPR-020" href="#0083-RFPR-020">0083-RFPR-020</a>).
+
 ### Setting benefit factors
 
 1. At the start of an epoch, each parties `volume_discount_factors` are reevaluated and fixed for the epoch (<a name="0084-VDPR-012" href="#0084-VDPR-012">0084-VDPR-012</a>).

protocol/0095-HVMR-high_volume_maker_rebate.md

@@ -65,6 +65,81 @@ As variable fees for the taker depending upon with whom they are trading would n
    1. `treasury_fee = treasury_fee * (1 - high_volume_maker_fee / (treasury_fee + buyback_fee))`
    1. `buyback_fee = treasury_fee * (1 - buyback_fee / (treasury_fee + buyback_fee))`
 
-## Governance Requirements
+As the rebate is funded through the buyback and treasure fee, the effective rebate is capped to a maximum rebate factor which is the sum of the treasury and buy back factors, i.e.
 
-As the rebate possible level interacts with other fee settings there must be a restriction on it's possible values in governance change proposals. However, as both the rebate and the relevant fees could be changed at once the failure should occur at enactment of the proposal rather than initial validation. The criterion `max(additional_maker_rebate) <= market.fee.factors.treasuryFee + market.fee.factors.buybackFee` should be checked at changes of both the maker rebate program and the two fee factor values to ensure this constraint remains true.
+$$\text{effectiveAdditionalMakerRebate} = \min{(\text{additionalMakerRebate}, \text{market.fee.factors.treasuryFee} + \text{market.fee.factors.buybackFee})}$$
+
+As a party's $effectiveAdditionalMakerRebate$ is dependent on the network parameters defining the factors, if the fee factors are updated through governance during an epoch, calculation of the effective rebate should be re-triggered a party's current $additionalMakerRebate$ and the updated factors. Note in this case, the network should not recalculate which tier and $additionalMakerRebate$ a party qualifies for as this is only done on epoch boundaries.
+
+Any APIs which report a party's rebate factor should adhere to this cap and return the $effectiveAdditionalMakerRebate$.
+
+## Acceptance Criteria
+
+### Governance Proposals
+
+1. If an `UpdateVolumeRebateProgram` proposal does not fulfil one or more of the following conditions, the proposal should be `STATUS_REJECTED`:
+    - the `end_of_program_timestamp` must be less than or equal to the proposals `enactment_time` (<a name="0095-HVMR-001" href="#0095-HVMR-001">0095-HVMR-001</a>).
+    - the number of tiers in `benefit_tiers` must be less than or equal to the network parameter `volumeRebateProgram.maxBenefitTiers` (<a name="0095-HVMR-002" href="#0095-HVMR-002">0095-HVMR-002</a>).
+    - all `minimum_party_maker_volume_fraction` values must be a float strictly greater than 0 (<a name="0095-HVMR-003" href="#0095-HVMR-003">0095-HVMR-003</a>).
+    - the `window_length` must be an integer strictly greater than zero (<a name="0095-HVMR-004" href="#0095-HVMR-004">0095-HVMR-004</a>).
+1. A volume rebate program should be started the first epoch change after the `enactment_datetime` is reached (<a name="0095-HVMR-005" href="#0095-HVMR-005">0095-HVMR-005</a>).
+1. A volume rebate program should be closed the first epoch change after the `end_of_program_timestamp` is reached (<a name="0095-HVMR-006" href="#0095-HVMR-006">0095-HVMR-006</a>).
+1. If a volume rebate program is already active and a proposal `enactment_datetime` is reached, the volume rebate program is updated at the next epoch change.
+    - Propose program A with `enactment_timestamp` ET1 and `end_of_program_timestamp` CT1 (<a name="0095-HVMR-007" href="#0095-HVMR-007">0095-HVMR-007</a>).
+    - Proposal for program A accepted and begins first epoch after ET1 (<a name="0095-HVMR-008" href="#0095-HVMR-008">0095-HVMR-008</a>).
+    - Propose program B with `enactment_timestamp` ET2 (ET2 > ET1 && ET2 < CT1) and `end_of_program_timestamp` CT1 (CT1 < CT2) (<a name="0095-HVMR-009" href="#0095-HVMR-009">0095-HVMR-009</a>).
+    - Proposal for program B accepted and overrides program A the first epoch after ET2 (<a name="0095-HVMR-010" href="#0095-HVMR-010">0095-HVMR-010</a>).
+    - Program is closed first epoch after CT2, there should be no active proposals (<a name="0095-HVMR-011" href="#0095-HVMR-011">0095-HVMR-011</a>).
+1. Updating any of the following network parameters whilst there is an active volume rebate program will not modify or cancel the active program in any way. The updated parameters will however be used to validate future volume rebate program proposals.
+    - `volumeRebateProgram.maxBenefitTiers` (<a name="0095-HVMR-012" href="#0095-HVMR-012">0095-HVMR-012</a>).
+
+1. Given a volume discount program program is not active, if an `UpdateVolumeRebateProgram` is enacted in epoch `k`. The program should be active in `k+1` **AND** all parties that qualify for a tier in the new program should receive the relevant factors from the new programs tier. (<a name="0095-HVMR-040" href="#0095-HVMR-040">0095-HVMR-040</a>).
+1. Given a volume discount program program is active, if an `UpdateVolumeRebateProgram` is enacted in epoch `k`. The program should be updated in `k+1` **AND** all parties that qualify for a tier in the updated program should receive the relevant factors from the updated programs tier. (<a name="0095-HVMR-041" href="#0095-HVMR-041">0095-HVMR-041</a>).
+
+### Maker volume fraction
+
+#### Contributing trades
+
+1. Each trade in which a party is the "maker" **should** contribute towards the party's maker volume fraction (<a name="0095-HVMR-013" href="#0095-HVMR-013">0095-HVMR-013</a>). For product spot (<a name="0095-HVMR-014" href="#0095-HVMR-014">0095-HVMR-014</a>).
+1. Each trade in which a party is the "taker" **should not** contribute towards the party's maker volume fraction (<a name="0095-HVMR-015" href="#0095-HVMR-015">0095-HVMR-015</a>). For product spot (<a name="0095-HVMR-016" href="#0095-HVMR-016">0095-HVMR-016</a>).
+1. A trade generated during auction uncrossing should not contribute to either party's maker volume fraction (<a name="0095-HVMR-017" href="#0095-HVMR-017">0095-HVMR-017</a>). For product spot (<a name="0095-HVMR-018" href="#0095-HVMR-018">0095-HVMR-018</a>).
+
+#### Evaluating contributions across windows
+
+1. Given a rebate program with a window length greater than zero. If a party generated an equal amount of volume in the current epoch to a party who created volume in a previous epoch in the window, then they should both have a maker volume fraction of `0.5`. (<a name="0095-HVMR-019" href="#0095-HVMR-019">0095-HVMR-019</a>). For product spot (<a name="0095-HVMR-020" href="#0095-HVMR-020">0095-HVMR-020</a>).
+1. Given a rebate program with a window length greater than zero. If a party generated an equal amount of volume in the current epoch to a party who created volume in a previous epoch which is no longer in the window, they the party should have a maker volume fraction of `1` (and the other party will have a fraction of `0`). (<a name="0095-HVMR-021" href="#0095-HVMR-021">0095-HVMR-021</a>). For product spot (<a name="0095-HVMR-022" href="#0095-HVMR-022">0095-HVMR-022</a>).
+
+#### Evaluating contributions across markets
+
+1. Given two parties' making markets in two separate derivative markets using settlement assets with different quantum values, if the party's generated equal volume (e.g. 10,000 USD) then they should both have a maker volume fraction of `0.5`. (<a name="0095-HVMR-023" href="#0095-HVMR-023">0095-HVMR-023</a>).
+1. Given two parties' making markets in two separate spot markets using quote assets with different quantum values, if the party's generated equal volume (e.g. 10,000 USD) then they should both have a maker volume fraction of `0.5`. (<a name="0095-HVMR-024" href="#0095-HVMR-024">0095-HVMR-024</a>).
+1. Given two parties' making markets in a separate derivative and spot market using a settlement and quote asset with different quantum values respectively, if the party's generated equal volume (e.g. 10,000 USD) then they should both have a maker volume fraction of `0.5`. (<a name="0095-HVMR-025" href="#0095-HVMR-025">0095-HVMR-025</a>).
+
+### Setting rebate factors
+
+1. At the start of an epoch, each party's `additional_rebate_factor` is reevaluated and fixed for the epoch (<a name="0095-HVMR-026" href="#0095-HVMR-026">0095-HVMR-026</a>).
+1. A party's `additional_rebate_factor`  is set equal to the factors in the highest benefit tier they qualify for (<a name="0095-HVMR-027" href="#0095-HVMR-027">0095-HVMR-027</a>).
+1. If a party does not qualify for the lowest tier, their `additional_rebate_factor`is set to `0` (<a name="0095-HVMR-028" href="#0095-HVMR-028">0095-HVMR-028</a>).
+
+#### Capping the effective rebate factor
+
+#### General behaviour
+
+1. Given the `treasury_fee_factor` is `0` If a party qualifies for a tier where the `additional_rebate_factor` is greater than `buyback_fee_factor`, their `effective_additional_rebate_factor` should be capped to a maximum and set to (`buyback_fee_factor` + `treasury_fee_factor`). In this case no treasury or buyback fees should be collected by the network for trades involving this party. (<a name="0095-HVMR-029" href="#0095-HVMR-029">0095-HVMR-029</a>).
+1. Given the `buyback_fee_factor` is `0`. If a party qualifies for a tier where the `additional_rebate_factor` is greater than `treasury_fee_factor`, their `effective_additional_rebate_factor` should be capped to a maximum and set to (`buyback_fee_factor` + `treasury_fee_factor`). In this case no treasury or buyback fees should be collected by the network for trades involving this party. (<a name="0095-HVMR-030" href="#0095-HVMR-030">0095-HVMR-030</a>).
+1. If a party qualifies for a tier where the `additional_rebate_factor` is greater than (`buyback_fee_factor` + `treasury_fee_factor`), their `effective_additional_rebate_factor` should be capped to a maximum and set to (`buyback_fee_factor` + `treasury_fee_factor`). In this case no treasury or buyback fees should be collected by the network for trades involving this party. (<a name="0095-HVMR-031" href="#0095-HVMR-031">0095-HVMR-031</a>).
+
+##### Program updates
+
+1. If the rebate program is updated such that the `additional_rebate_factor` in the tier the party currently qualifies for is reduced so that the party's new `additional_rebate_factor` is greater than (`buyback_fee_factor` + `treasury_fee_factor`), their `effective_additional_rebate_factor` should be capped to a maximum and set to (`buyback_fee_factor` + `treasury_fee_factor`). (<a name="0095-HVMR-032" href="#0095-HVMR-032">0095-HVMR-032</a>).
+1. If the rebate program is updated such that the `additional_rebate_factor` in the tier the party currently qualifies for is increased so that the party's new `additional_rebate_factor` is less than (`buyback_fee_factor` + `treasury_fee_factor`), their `effective_additional_rebate_factor` should be set to their current `additional_rebate_factor`. (<a name="0095-HVMR-033" href="#0095-HVMR-033">0095-HVMR-033</a>).
+
+#### Network parameter updates
+
+1. If the `buyback_fee_factor` is increased through a proposal in the middle of an epoch such that a party's `additional_rebate_factor` is greater than (`buyback_fee_factor` + `treasury_fee_factor`), their `effective_additional_rebate_factor` should be set to the new maximum (`buyback_fee_factor` + `treasury_fee_factor`). (<a name="0095-HVMR-034" href="#0095-HVMR-034">0095-HVMR-034</a>).
+1. If the `treasury_fee_factor` is increased through a proposal in the middle of an epoch such that a party's `additional_rebate_factor` is greater than (`buyback_fee_factor` + `treasury_fee_factor`), their `effective_additional_rebate_factor` should be set to the new maximum (`buyback_fee_factor` + `treasury_fee_factor`). (<a name="0095-HVMR-035" href="#0095-HVMR-035">0095-HVMR-035</a>).
+1. If the `buyback_fee_factor` and `treasury_fee_factor` are both increased through a batch proposal in the middle of an epoch such that a party's `additional_rebate_factor` is greater than (`buyback_fee_factor` + `treasury_fee_factor`), their `effective_additional_rebate_factor` should be set to the new maximum (`buyback_fee_factor` + `treasury_fee_factor`). (<a name="0095-HVMR-036" href="#0095-HVMR-036">0095-HVMR-036</a>).
+
+1. If the `buyback_fee_factor` is reduced through a proposal in the middle of an epoch such that a party's `additional_rebate_factor` is less than (`buyback_fee_factor` + `treasury_fee_factor`), their `effective_additional_rebate_factor` should be set to their current `additional_rebate_factor`. (<a name="0095-HVMR-037" href="#0095-HVMR-037">0095-HVMR-037</a>).
+1. If the `treasury_fee_factor` is reduced through a proposal in the middle of an epoch such that a party's `additional_rebate_factor` is less than (`buyback_fee_factor` + `treasury_fee_factor`), their `effective_additional_rebate_factor` should be set to their current `additional_rebate_factor`. (<a name="0095-HVMR-038" href="#0095-HVMR-038">0095-HVMR-038</a>).
+1. If the `buyback_fee_factor` and `treasury_fee_factor` are both reduced through a batch proposal in the middle of an epoch such that a party's current `additional_rebate_factor` is less than (`buyback_fee_factor` + `treasury_fee_factor`), their `effective_additional_rebate_factor` should be set to their current `additional_rebate_factor`. (<a name="0095-HVMR-039" href="#0095-HVMR-039">0095-HVMR-039</a>).

protocol/features.json

@@ -107,6 +107,17 @@
       "0016-PFUT-031"
     ]
   },
+  "Program enactment fixes": {
+  "milestone": "genbutemple",
+    "acs": [
+      "0083-RFPR-056",
+      "0083-RFPR-057",
+      "0084-VDPR-019",
+      "0084-VDPR-020",
+      "0095-HVMR-040",
+      "0095-HVMR-041"
+    ]
+  },
   "Unknown": {
     "milestone": "unknown",
     "acs": []