From 5b43bb55ebf73d70dd7b0a49f18553ebc03a1427 Mon Sep 17 00:00:00 2001 From: Charlie Date: Thu, 3 Aug 2023 19:28:13 +0100 Subject: [PATCH 01/27] feat: add vesting spec --- protocol/0085-RVST-rewards_vesting.md | 50 +++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 protocol/0085-RVST-rewards_vesting.md diff --git a/protocol/0085-RVST-rewards_vesting.md b/protocol/0085-RVST-rewards_vesting.md new file mode 100644 index 000000000..4d9f6f417 --- /dev/null +++ b/protocol/0085-RVST-rewards_vesting.md @@ -0,0 +1,50 @@ +# Rewards Vesting Specification + +## Summary + +The aim of the rewards vesting mechanics is to prevent farming rewards by delaying the payout of rewards through vesting. To encourage longer term behaviour parties can accelerate their rewards vesting rate through the [activity streak program](./0086-ASPR-activity_streak_program.md). + +## Network Parameters + +- `rewards.vesting.baseRate`: the proportion of rewards in a vesting account which are vested each epoch +- `rewards.vesting.minimumTransfer`: the minimum amount (expressed in quantum) which can be vested each epoch + +## Vesting mechanics + +As detailed in [distributing rewards](), each party has their rewards paid into vesting rewards accounts (one for each asset). + +At the end of each epoch, a proportion of the rewards accumulated in each "vesting" account should be released and transferred to the respective "vested" account. The percentage released can be scaled by the account owner increasing their [activity streak](./0086-ASPR-activity_streak_program.md) and a minimum transfer amount will be applied to ensure the account is eventually emptied. The proportion released and minimum applied are controlled for parameters for the asset. + +Now, let: + +- $T$ be the amount to be "vested" (transferred from the vesting account to the vested account) +- $B_{vested}$ be the total quantum amount in the vesting account +- $r_{bvr}$ be the network parameter `rewards.vesting.baseRate` +- $a$ be the account owners current [`activity_streak_vesting_multiplier`](./0086-ASPR-activity_streak_program.md#setting-activity-benefits) +- $m_{mva}$ be the network parameter `rewards.vesting.minimumTransfer` + +The quantum amount to be transferred from each "vesting" account to the relevant "vested" account is defined as: +$$ +T = min(B_{vested} * r * a, m) +$$ + +When transferring funds from the vesting account to the vested account, a new transfer type should be used, `TRANSFER_TYPE_REWARDS_VESTED`. + +## APIs + +### Accounts API + +Must expose the following: + +- every account with `ACCOUNT_TYPE_VESTING_REWARDS` for each party +- every account with `ACCOUNT_TYPE_VESTED_REWARDS` for each party + +### Ledger Entries API + +Must expose the following: + +- every transfer with `TRANSFER_TYPE_REWARDS_VESTED` for each party + +## Acceptance Criteria + +TBD \ No newline at end of file From ab6a30283a1874e16c33c74c84716060b091b0c5 Mon Sep 17 00:00:00 2001 From: Charlie Date: Thu, 3 Aug 2023 19:28:34 +0100 Subject: [PATCH 02/27] feat: add activity spec --- protocol/0086-ASPR-activity_streak_program.md | 125 ++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 protocol/0086-ASPR-activity_streak_program.md diff --git a/protocol/0086-ASPR-activity_streak_program.md b/protocol/0086-ASPR-activity_streak_program.md new file mode 100644 index 000000000..ddaa370dd --- /dev/null +++ b/protocol/0086-ASPR-activity_streak_program.md @@ -0,0 +1,125 @@ +# Activity Streak Program + +The purpose of the activity streak program is to reward loyal, active traders with the following tiered benefits: + +- a greater share of rewards schemes +- an accelerated vesting rate on locked rewards + +Parties access higher tiers and greater benefits by maintaining an activity streak. The length of a streak is measured in epochs and a party is considered active if they made a trade or held an open position during the epoch. If a party is inactive for more than a specified number of epochs they lose their streak. + +## Network parameters + +- `rewards.activityStreak.benefitTiers`: is an ordered list of dictionaries defining the requirements and benefits for each tier. +- `rewards.activityStreak.inactivityLimit`: the maximum number of epochs a trader can be inactive before loosing their streak. +- `rewards.activityStreak.minQuantumOpenVolume`: the minimum open notional volume (expressed in quantum) for a trader to be considered active in an epoch +- `rewards.activityStreak.minQuantumTradeVolume`: the minimum trade volume (expressed in quantum) for a trader to be considered active in an epoch + + +## Governance proposals + +The network parameter [`rewards.activityStreak.benefitTiers`](#network-parameters) can be updated via a `UpdateNetworkParameter` governance proposal. Each tier in the ordered list must have the following fields: + +- `minimum_activity_streak`: int greater or equal to `0` defining the minimum activity streak a party must have to access this tier +- `reward_multiplier`: float greater or equal to `1` defining the factor to scale a parties [reward shares]() by +- `vesting_multiplier`: float greater or equal to `1` defining the factor to scale a parties [base vesting rate]() by + +*Example:* +```proto +message UpdateNetworkParameter{ + changes: NetworkParameter{ + key: "rewards.activityStreak.benefitTiers", + value: [ + {"minimum_activity_streak": 1, "reward_multiplier": 1.0, "vesting_multiplier": 1.05}, + {"minimum_activity_streak": 7, "reward_multiplier": 5.0, "vesting_multiplier": 1.25}, + {"minimum_activity_streak": 31, "reward_multiplier": 10.0, "vesting_multiplier": 1.50}, + {"minimum_activity_streak": 365, "reward_multiplier": 20.0, "vesting_multiplier": 2.00}, + + ], + } +} +``` + +## Activity streak mechanics + +The following steps should occur **before** rewards are [distributed] and [vested]. + +### Setting activity / inactivity streak + +For the feature, the network must track each parties "activity streak". At the end of an epoch: + +- if a party was "active" in the epoch + + - increment their `activity_streak` by `1` + - reset their `inactivity_streak` to `0`. + +- if a party was "inactive" in the epoch + + - increment their `inactivity_streak` streak by `1` + - if their `inactivity_streak` is greater than or equal to the `rewards.activityStreak.streakLength`, reset their `activity_streak` to `0`. + +A party is defined as active if they fulfil **either** of the following criteria: + +- their open interest was strictly greater than `rewards.activityStreak.minQuantumOpenVolume` at any point in the epoch +- their total trade volume was strictly greater than `rewards.activityStreak.minQuantumTradeVolume` at the end of the epoch + +### Setting activity benefits + +After determining a parties "activity streak" there `reward_distribution_activity_multiplier` and `reward_vesting_activity_multiplier` should be set according to the highest tier they qualify for. + +```pseudo +Given: + rewards.activityStreak.benefitTiers: [ + [ + {"minimum_activity_streak": 1, "reward_multiplier": 1.0, "vesting_multiplier": 1.05}, + {"minimum_activity_streak": 7, "reward_multiplier": 5.0, "vesting_multiplier": 1.25}, + {"minimum_activity_streak": 31, "reward_multiplier": 10.0, "vesting_multiplier": 1.50}, + {"minimum_activity_streak": 365, "reward_multiplier": 20.0, "vesting_multiplier": 2.00}, + + ], + ] + +And: + activity_streak=48 + inactivity_streak=3 + +Then: + reward_distribution_activity_multiplier=10.0 + reward_vesting_activity_multiplier=1.50 +``` + +### Applying activity benefits + +#### Applying the activity reward multiplier + +The `activity_streak_reward_multiplier` scales the parties [reward share]() for all rewards they are eligible for. + +#### Applying the activity vesting multiplier + +The `activity_streak_vesting_multiplier` scales the parties [vesting rate]() of all funds locked in the parties vesting accounts. + + +## APIs + +### Parties API + +Must expose the following: + +- a parties `activity_streak` +- a parties `inactivity_streak` +- whether a party has been considered "active" in the current epoch +- a parties current `reward_distribution_activity_multiplier` +- a parties current `reward_vesting_activity_multiplier` + +## Acceptance Criteria + +### Governance proposals + +TBD + +### Setting activity / inactivity streak + +TBD + +### Setting activity benefits + +TBD \ No newline at end of file From da05d5afbd764b0473046705ed11a90eb5091755 Mon Sep 17 00:00:00 2001 From: Charlie Date: Mon, 7 Aug 2023 02:37:14 +0100 Subject: [PATCH 03/27] feat: update reward distribution --- protocol/0056-REWA-rewards_overview.md | 119 +++++++++++++++++++------ 1 file changed, 94 insertions(+), 25 deletions(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index edc794678..83976a171 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -1,6 +1,6 @@ # Reward framework -The reward framework provides a mechanism for measuring and rewarding a number of key activities on the Vega network. +The reward framework provides a mechanism for measuring and rewarding individuals or [teams](./0083-RFPR-on_chain_referral_program.md#glossary) (collectively referred to within this spec as entities) for a number of key activities on the Vega network. These rewards operate in addition to the main protocol economic incentives which come from [fees](0029-FEES-fees.md) on every trade. These fees are the fundamental income stream for [liquidity providers LPs](0042-LIQF-setting_fees_and_rewarding_lps.md) and [validators](./0061-REWP-pos_rewards.md). @@ -9,7 +9,6 @@ The additional rewards described here can be funded arbitrarily by users of the Note that transfers via governance, including to fund rewards, is a post-Oregon Trail feature. Note that validator rewards (and the reward account for those) is covered in [validator rewards](./0061-REWP-pos_rewards.md) and is separate from the trading reward framework described here. - ## New network parameter for market creation threshold The parameter `rewards.marketCreationQuantumMultiple` will be used together with [quantum](0040-ASSF-asset_framework.md) to asses market size when deciding whether a market qualifies for the payment of market creation rewards. @@ -20,17 +19,18 @@ Therefore, for example, to reward futures markets when they reach a lifetime tra At a high level, rewards work as follows: -- Reward metrics are calculated for each combination of [reward type, party, market]. - - The calculation used for the reward metric is specific to each reward type. +- Individual reward metrics are calculated for each combination of [reward type, party, market] and team reward metrics for each combination of [reward type, team, market]. At the end of the epoch: 1. Recurring reward transfers (set up by the parties funding the rewards) are made to the reward account(s) for a specific reward type, for one or more markets in scope where the total reward metric is `>0`. See [transfers](./0057-TRAN-transfers.md#recurring-transfers-to-reward-accounts). -1. Then the entire balance of each reward account is distributed to the parties with a non-zero reward metric for that reward type and market, pro-rata by their reward metric. +1. Then the entire balance of each reward account is distributed amongst entities with a non-zero reward metric for that reward type and market using the mechanism specified in the recurring transfer. +1. Distributed rewards are transferred to a [vesting account](./0085-RVST-rewards_vesting.md). + +## Individual reward metrics -## Reward metrics +Individual reward metrics are scoped by [`reward type`, `market`, `party`] (this triplet can be thought of as a primary key for fee-based reward metrics). -Fee-based reward metrics are scoped by [`reward type`, `market`, `party`] (this triplet can be thought of as a primary key for fee-based reward metrics). Therefore a party may be in scope for the same reward type multiple times but no more than once per market per epoch. Metrics will be calculated at the end of every epoch, for every eligible party, in each market for each reward type. Metrics only need to be calculated where the [market, reward type] reward account has a non-zero balance of at least one asset. @@ -38,10 +38,9 @@ Metrics only need to be calculated where the [market, reward type] reward accoun Reward metrics will be calculated once for each party/market combination in the reward metric asset which is the [settlement asset](0070-MKTD-market-decimal-places.md) of the market. This is the original precision for the metric source data. -### Market activity (fee based) reward metrics +### Fee-based reward metrics -There will be three market activity reward metrics calculated based on fees (as a proxy for activity). -Each of these represents a reward type with its own segregated reward accounts for each market. +There will be three reward metrics calculated based on fees. 1. Sum of maker fees paid by the party on the market this epoch 1. Sum of maker fees received by the party on the market this epoch @@ -51,7 +50,15 @@ These metrics apply only to the sum of fees for the epoch in question. That is, the metrics are reset to zero for all parties at the end of the epoch. If the reward account balance is 0 at the end of the epoch for a given market, any parties with non-zero metrics will not be rewarded for that epoch and their metric scores do not roll over (they are still zeroed). -Market activity (fee based) reward metrics (the total fees paid/received by each party as defined above) are stored in [LNL checkpoints](./0073-LIMN-limited_network_life.md) and are restored after a checkpoint restart to ensure rewards are not lost. +Fee-based reward metrics (the total fees paid/received by each party as defined above) are stored in [LNL checkpoints](./0073-LIMN-limited_network_life.md) and are restored after a checkpoint restart to ensure rewards are not lost. + +### Open interest metrics + + +### Pnl metrics + + +### Volatility metrics ### Market creation reward metrics @@ -82,6 +89,13 @@ This flag is used to prevent any given funder from funding a creation reward in Market creation reward metrics (both each market's `cumulative volume` and the payout record flags to identify [funder, market scope, reward asset] combinations that have already been rewarded) are stored in [LNL checkpoints](./0073-LIMN-limited_network_life.md) and will be restored after a checkpoint restart. +## 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. + +A team’s reward metric is the weighted average metric score of the top performing `n` % of team members by number where `n` is specified when creating the recurring transfer (i.e. for a team of 100 parties with `n=0.1`, the 10 members with the highest metric score). + + ## Reward accounts Trading reward accounts are defined by the reward asset (the asset in which the reward is paid out), the market, and the reward type (metric). @@ -98,26 +112,81 @@ Reward accounts and balances must be saved in [LNL checkpoints](./0073-LIMN-limi ## Reward distribution -All rewards are paid out at the end of each epoch *after* [recurring transfers](0057-TRAN-transfers.md) have been executed. -The entire reward account balance is paid out every epoch unless the total value of the metric over all parties is zero, in which case the balance will also be zero anyway (there are no fractional payouts). -There are no payout delays, rewards are paid out instantly at epoch end. +All rewards are distributed to [vesting accounts](./0085-RVST-rewards_vesting.md) at the end of each epoch *after* [recurring transfers](0057-TRAN-transfers.md) have been executed. -Rewards will be distributed pro-rata by the party's reward metric value to all parties that have metric values `>0`. Note that for the market creation reward, the metric is defined to either be `0` or `1`, which will lead to equal payments for each eligible market under the pro-rata calculation. If we have reward account balance `R` and parties `p_1 – p_n` with non-zero metrics `m_1 – m_n` on the market in question: +The entire reward account balance is paid out every epoch unless the total value of the metric over all entities is zero, in which case the balance will also be zero anyway (there are no fractional payouts). -```math -[p_1, m_1] -[p_2, m_2] -... -[p_n, m_n] -``` +Rewards are first [distributed amongst entities](#distributing-rewards-amongst-entities) (individuals or teams) and then any rewards distributed to teams are [distributed amongst team members](#distributing-rewards-amongst-team-members). + +### Distributing rewards amongst entities + +Rewards are distributed amongst entities based on the distribution method defined in the recurring transfer. + +The protocol currently supports the following distribution strategies: + +- [pro-rata](#distributing-pro-rata) by reward metric +- [exponential-decay](#distributing-with-exponential-decay) by reward metric + +#### Distributing pro-rata + +Rewards funded using the pro-rata strategy should be distributed pro-rata by each entities reward metric scaled by any active multipliers that party has, i.e. + +Let: +- $d_{i}$ be the payout factor for entity $i$ +- $r_{i}$ be the reward metric value for entity $i$ +- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ +- $s_{i}$ be the share of the rewards for entity $i$ + +$$d_{i}=r_{i} M_{i}$$ + +Note if the entity is a team, $M_{i}$ is set to zero as reward payout multipliers are considered later when distributing rewards [amongst the team members](#distributing-rewards-amongst-team-members). + +Calculate each entities share of the rewards, $s_{i}$ pro-rata based on $d_{i}$, i.e. + +$$s_{i} = \frac{d_{i}}{\sum_{i=1}^{n}d_{i}}$$ + +#### Distributing with exponential decay + +Rewards funded using the exponential-decay strategy should be distributed as follows. + +1. Calculate each entities reward metric +2. Order each entity in a descending list by their reward metric value and determine their "rank" in the list +3. Calculate each entities share of the rewards using the below formula. + +Let: +- $d_{i}$ be the payout factor for entity $i$ +- $s_{i}$ be the share of the rewards for entity $i$ +- $k$ be the decay factor specified in the recurring transfer funding the reward +- $R_{i}$ be the rank of entity $i$ +- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ + +$$d_{i}=e^{-k R_{i}} M_{i}$$ + +Note if the entity is a team, $M_{i}$ is set to zero as reward payout multipliers are considered later when distributing rewards [amongst the team members](#distributing-rewards-amongst-team-members). + +Calculate each entities share of the rewards, $s_{i}$ pro-rata based on $d_{i}$, i.e. + +$$s_{i} = \frac{d_{i}}{\sum_{i=1}^{n}d_{i}}$$ +### Distributing rewards amongst team members + +If rewards are distributed to a team, rewards must then be distributed between team members. -Then calculate `M := m_1 + m_2 + … + m_n` and transfer `R ✖️ m_i / M` to party `p_i` (for each `p_i`) at the end of the epoch. +Let: +- $d_{i}$ be the payout for team member $i$ +- $s_{i}$ be the share of the rewards for team member $i$ +- $B_{i}$ be the total balance in all of the team members accounts (expressed in quantum) +- $F$ be the network parameter `rewards.teamDistribution.minimumAccountQuantum` +- $C$ be the network parameter `rewards.teamDistribution.maximumAccountQuantum` +- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ -If `M=0` (no-one incurred or received fees as specified by the metric type for the given market) then no transfer will have been made to the reward account and therefore there are no rewards to pay out. -The transfer will be retried the next epoch if it is still active. +$$d_{i} = \begin{cases} + 0 &\text{if } B_{i} < F \\ + M_{i}\log(\min(B_{i}+1, C+1)) &\text{if } B_{i} \geq F +\end{cases}$$ -Reward payouts will be calculated using the decimal precision of the reward payout asset. If this allows less precision than the reward metric asset (the market's settlement asset) then the ratios between reward payouts may not match exactly the ratio between the reward metrics for any two parties. All funds will always be paid out. +Calculate each parties share of the rewards, $s_{i}$ pro-rata based on $d_{i}$, i.e. +$$s_{i} = \frac{d_{i}}{\sum_{i=1}^{n}d_{i}}$$ ## Acceptance criteria ### Funding reward accounts (0056-REWA-001) From 80229e16369123adac3d706f49d824170a3bc8d2 Mon Sep 17 00:00:00 2001 From: Charlie Date: Mon, 7 Aug 2023 08:58:19 +0100 Subject: [PATCH 04/27] feat: address vesting feedback --- protocol/0085-RVST-rewards_vesting.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/protocol/0085-RVST-rewards_vesting.md b/protocol/0085-RVST-rewards_vesting.md index 4d9f6f417..800793a5b 100644 --- a/protocol/0085-RVST-rewards_vesting.md +++ b/protocol/0085-RVST-rewards_vesting.md @@ -6,8 +6,8 @@ The aim of the rewards vesting mechanics is to prevent farming rewards by delayi ## Network Parameters -- `rewards.vesting.baseRate`: the proportion of rewards in a vesting account which are vested each epoch -- `rewards.vesting.minimumTransfer`: the minimum amount (expressed in quantum) which can be vested each epoch +- `rewards.vesting.baseRate`: the proportion of rewards in a vesting account which are vested each epoch, value defaults to `0.1` and must be a float strictly greater than 0. +- `rewards.vesting.minimumTransfer`: the minimum amount (expressed in quantum) which can be vested each epoch, value defaults to 100 and must be an integer greater or equal than `0`. ## Vesting mechanics @@ -24,9 +24,8 @@ Now, let: - $m_{mva}$ be the network parameter `rewards.vesting.minimumTransfer` The quantum amount to be transferred from each "vesting" account to the relevant "vested" account is defined as: -$$ -T = min(B_{vested} * r * a, m) -$$ + +$$T = max(B_{vesting} * r * a, m)$$ When transferring funds from the vesting account to the vested account, a new transfer type should be used, `TRANSFER_TYPE_REWARDS_VESTED`. From 7ae6bc5c4d3556bff12521179b754737705a638e Mon Sep 17 00:00:00 2001 From: Charlie Date: Mon, 7 Aug 2023 13:53:04 +0100 Subject: [PATCH 05/27] feat: update reward metrics --- protocol/0056-REWA-rewards_overview.md | 63 ++++++++++++++++++++++++-- 1 file changed, 60 insertions(+), 3 deletions(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index 83976a171..8b95cc5f5 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -52,13 +52,70 @@ If the reward account balance is 0 at the end of the epoch for a given market, a Fee-based reward metrics (the total fees paid/received by each party as defined above) are stored in [LNL checkpoints](./0073-LIMN-limited_network_life.md) and are restored after a checkpoint restart to ensure rewards are not lost. -### Open interest metrics +### Open interest metric +The open interest metric, ($m_{oi}$, measures each parties time-weighted average open interest over a number of epochs. -### Pnl metrics +At the start of each epoch, the network must reset each parties time weighted average open interest for the epoch ($\bar{OI}$) to `0`. Whenever a parties position changes during an epoch, **and** at the end of the epoch, this value should be updated as follows. +Let: + +- $\bar{OI}$ be the parties time weighted average open interest in the epoch so far +- $OI_{n}$ be the parties open interest before their open interest changed +- $t_{n}$ be the time the party held the previous position in seconds +- $t$ be the amount of time elapsed in the current epoch so far + + +$$\bar{OI} = \bar{OI} \cdot \left(1 - \frac{t_{n}}{t}\right) + \frac{OI_{n} \cdot t_{n}}{t}$$ + +At the end of the epoch, the network must store the parties time weighted average open interest and then calculate their open interest reward metric as follows. + +Let: + +- $m_{oi}$ be the parties open interest reward metric +- $\bar{OI_{i}}$ be the parties time weighted average open interest in the ith epoch +- $N$ be the network parameter `rewards.metrics.openInterestWindow` + +$$m_{oi} = \frac{\sum_{i}^{n}\bar{OI_{i}}}{N}$$ + +### Relative return metric + +The relative return metric, $m_{rr}$, measures each parties average relative return, weighted by their [time-weighted average open-interest](#open-interest-metric), over a number of epochs. + +At the start of the epoch, the network must store the parties current pnl. + +$$p_{0} = p_{realised} + p_{unrealised}$$ + +At the end of each epoch, the network must calculate and store the parties change in pnl: + +Let: +- $\Delta{p}$ be the parties change in pnl +- $p_{realised}$ be the parties realised pnl at the end of the epoch +- $p_{unrealised}$ be the parties unrealised pnl at the end of the epoch + +$$\Delta{p} = p_{realised} + p_{unrealised} - p_{0}$$ + +And calculate their average relative return, weighted by the log of their [time weighted average open interest](#open-interest-metrics), over the last $N$ epochs as follows. + +Let: +- $m_{rr}$ be the parties relative return reward metric +- $\bar{OI_{i}}$ be the parties time weighted average open interest in the ith epoch +- $\Delta{p}$ be the parties change in pnl in the ith epoch +- $N$ be the network parameter `rewards.metrics.relativeReturnsWindow` + +$$m_{rr} = \frac{\sum_{i}^{n}{p_{i}\cdot\log(1 + \bar{OI_{i}})}}{N}$$ + +### Returns volatility metric + +The return volatility metric, $m_{rv}$, measures the volatility of a parties returns across a number of epochs. + +At the end of an epoch, if a party has had net returns less than or equal to `0` over the last $N$ epochs (where $N$ is the network parameter `rewards.metrics.returnsVolatilityWindow`), their reward metric $m_{rv}$ is set to `0`. Otherwise, the network should calculate the standard deviation of the set of each parties returns weighted by the log of their [time weighted average open interest](#open-interest-metrics) over the last $N$ epochs. + +Given the set: + +$$R = \{r_i \cdot \log(1 +\bar{OI_{i}}) \mid i = 1, 2, \ldots, N\}$$ -### Volatility metrics +The reward metric $m_{rv}$ is the standard deviation of the set $R$. ### Market creation reward metrics From 6f75ebce0d55149658baf1955130d1dce01790ba Mon Sep 17 00:00:00 2001 From: Charlie Date: Tue, 8 Aug 2023 10:22:07 +0100 Subject: [PATCH 06/27] feat: add validator power metric --- protocol/0056-REWA-rewards_overview.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index 8b95cc5f5..d26ac4c77 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -117,6 +117,18 @@ $$R = \{r_i \cdot \log(1 +\bar{OI_{i}}) \mid i = 1, 2, \ldots, N\}$$ The reward metric $m_{rv}$ is the standard deviation of the set $R$. +### Validator power metric + +The validator power metric, $m_{vp}$, measures the voting power of validators. + +At the end of each epoch, for each party who is a validator set their reward metric as follows. + +$$m_{vp} = validatorScore$$ + +Note the `validatorScore` is the score **after** any [penalties](./0061-REWP-pos_rewards.md#for-each-validator-we-then-do) have been applied. +If a party is not a validator, their reward metric is simply: + +$$m_{vp} = 0$$ ### Market creation reward metrics There will be a single market creation reward metric and reward type. @@ -146,6 +158,8 @@ This flag is used to prevent any given funder from funding a creation reward in Market creation reward metrics (both each market's `cumulative volume` and the payout record flags to identify [funder, market scope, reward asset] combinations that have already been rewarded) are stored in [LNL checkpoints](./0073-LIMN-limited_network_life.md) and will be restored after a checkpoint restart. +Note this reward metric **is not** available for team rewards. + ## 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. From 05a7c962ad6e2d39b297a43c270ed1309cef95bc Mon Sep 17 00:00:00 2001 From: Charlie Date: Tue, 8 Aug 2023 10:23:31 +0100 Subject: [PATCH 07/27] feat: add new entity scoping --- protocol/0057-TRAN-transfers.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/protocol/0057-TRAN-transfers.md b/protocol/0057-TRAN-transfers.md index 49c9e0db2..b92eeb954 100644 --- a/protocol/0057-TRAN-transfers.md +++ b/protocol/0057-TRAN-transfers.md @@ -87,6 +87,20 @@ To be able to dispatch rewards to reward pools of multiple markets pro rata to t - `reward metric asset` — (the settlement asset of all markets that will be in scope for the transfer) - `market scope` — a subset of markets in which parties are eligible to be rewarded from this transfer. - If the market scope is not defined / an empty list, it is taken as all the markets that settle in the reward metric asset. + +A party can further control their recurring transfer funding the reward pool by defining the entities which are within scope. Entities within scope can be either individual parties or [teams](./0083-RFPR-on_chain_referral_program.md#glossary). When scoping individuals, a subset of keys can be detailed, and when scoping teams a specific set of team ids can be detailed. + +To support entity scoping, the transaction include the following fields: + +- `entity scope` - mandatory enum which defines the entities within scope. + - `ENTITY_SCOPE_INDIVIDUALS` - the rewards must be distributed directly amongst eligible parties + - `ENTITY_SCOPE_TEAMS` - the rewards must be distributed amongst directly eligible teams (and then amongst team members) +- `individual scope` - optional enum if the entity scope is `ENTITY_SCOPE_INDIVIDUALS` which defines the subset of individuals which are eligible to be rewarded. + - `INDIVIDUAL_SCOPE_ALL` - all parties on the network are within the scope of this reward + - `INDIVIDUAL_SCOPE_IN_TEAM` - all parties which are part of a team are within the scope of this reward + - `INDIVIDUAL_SCOPE_NOT_IN_TEAM` - all parties which are not part of a team are within the scope of this reward +- `team scope` - optional list if the reward type is `ENTITY_SCOPE_TEAMS`, field allows the funder to define a list of team ids which are eligible to be rewarded from this transfer + - At the end of the epoch when the transfer is about to be distributed, it first calculates the contribution of each market to the sum total reward metric for all markets in the `market scope` and then distributes the transfer amount to the corresponding accounts of the markets pro-rata by their contribution to the total. Where the reward metric type is "market creation rewards", it is important that no market creator will receive more than one market creation reward paid in the same asset from the same source account (reward funder). From 1ff1e3f13799cba345d10cc65be2cafd44eef6f6 Mon Sep 17 00:00:00 2001 From: Charlie Date: Tue, 8 Aug 2023 10:41:04 +0100 Subject: [PATCH 08/27] refactor: linting and spellcheck fixes --- protocol/0056-REWA-rewards_overview.md | 17 ++++++++++---- protocol/0057-TRAN-transfers.md | 10 ++++---- protocol/0085-RVST-rewards_vesting.md | 8 +++---- protocol/0086-ASPR-activity_streak_program.md | 23 ++++++++++--------- 4 files changed, 34 insertions(+), 24 deletions(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index d26ac4c77..941919849 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -9,6 +9,7 @@ The additional rewards described here can be funded arbitrarily by users of the Note that transfers via governance, including to fund rewards, is a post-Oregon Trail feature. Note that validator rewards (and the reward account for those) is covered in [validator rewards](./0061-REWP-pos_rewards.md) and is separate from the trading reward framework described here. + ## New network parameter for market creation threshold The parameter `rewards.marketCreationQuantumMultiple` will be used together with [quantum](0040-ASSF-asset_framework.md) to asses market size when deciding whether a market qualifies for the payment of market creation rewards. @@ -54,7 +55,7 @@ Fee-based reward metrics (the total fees paid/received by each party as defined ### Open interest metric -The open interest metric, ($m_{oi}$, measures each parties time-weighted average open interest over a number of epochs. +The open interest metric, $m_{oi}$, measures each parties time-weighted average open interest over a number of epochs. At the start of each epoch, the network must reset each parties time weighted average open interest for the epoch ($\bar{OI}$) to `0`. Whenever a parties position changes during an epoch, **and** at the end of the epoch, this value should be updated as follows. @@ -89,27 +90,29 @@ $$p_{0} = p_{realised} + p_{unrealised}$$ At the end of each epoch, the network must calculate and store the parties change in pnl: Let: + - $\Delta{p}$ be the parties change in pnl - $p_{realised}$ be the parties realised pnl at the end of the epoch - $p_{unrealised}$ be the parties unrealised pnl at the end of the epoch $$\Delta{p} = p_{realised} + p_{unrealised} - p_{0}$$ -And calculate their average relative return, weighted by the log of their [time weighted average open interest](#open-interest-metrics), over the last $N$ epochs as follows. +And calculate their average relative return, weighted by the log of their [time weighted average open interest](#open-interest-metric), over the last $N$ epochs as follows. Let: + - $m_{rr}$ be the parties relative return reward metric - $\bar{OI_{i}}$ be the parties time weighted average open interest in the ith epoch - $\Delta{p}$ be the parties change in pnl in the ith epoch - $N$ be the network parameter `rewards.metrics.relativeReturnsWindow` -$$m_{rr} = \frac{\sum_{i}^{n}{p_{i}\cdot\log(1 + \bar{OI_{i}})}}{N}$$ +$$m_{rr} = \frac{\sum_{i}^{n}{$\Delta{p}$\cdot\log(1 + \bar{OI_{i}})}}{N}$$ ### Returns volatility metric The return volatility metric, $m_{rv}$, measures the volatility of a parties returns across a number of epochs. -At the end of an epoch, if a party has had net returns less than or equal to `0` over the last $N$ epochs (where $N$ is the network parameter `rewards.metrics.returnsVolatilityWindow`), their reward metric $m_{rv}$ is set to `0`. Otherwise, the network should calculate the standard deviation of the set of each parties returns weighted by the log of their [time weighted average open interest](#open-interest-metrics) over the last $N$ epochs. +At the end of an epoch, if a party has had net returns less than or equal to `0` over the last $N$ epochs (where $N$ is the network parameter `rewards.metrics.returnsVolatilityWindow`), their reward metric $m_{rv}$ is set to `0`. Otherwise, the network should calculate the standard deviation of the set of each parties returns weighted by the log of their [time weighted average open interest](#open-interest-metric) over the last $N$ epochs. Given the set: @@ -129,6 +132,7 @@ Note the `validatorScore` is the score **after** any [penalties](./0061-REWP-pos If a party is not a validator, their reward metric is simply: $$m_{vp} = 0$$ + ### Market creation reward metrics There will be a single market creation reward metric and reward type. @@ -203,6 +207,7 @@ The protocol currently supports the following distribution strategies: Rewards funded using the pro-rata strategy should be distributed pro-rata by each entities reward metric scaled by any active multipliers that party has, i.e. Let: + - $d_{i}$ be the payout factor for entity $i$ - $r_{i}$ be the reward metric value for entity $i$ - $M_{i}$ be the sum of all reward payout multipliers for entity $i$ @@ -225,6 +230,7 @@ Rewards funded using the exponential-decay strategy should be distributed as fol 3. Calculate each entities share of the rewards using the below formula. Let: + - $d_{i}$ be the payout factor for entity $i$ - $s_{i}$ be the share of the rewards for entity $i$ - $k$ be the decay factor specified in the recurring transfer funding the reward @@ -238,11 +244,13 @@ Note if the entity is a team, $M_{i}$ is set to zero as reward payout multiplier Calculate each entities share of the rewards, $s_{i}$ pro-rata based on $d_{i}$, i.e. $$s_{i} = \frac{d_{i}}{\sum_{i=1}^{n}d_{i}}$$ + ### Distributing rewards amongst team members If rewards are distributed to a team, rewards must then be distributed between team members. Let: + - $d_{i}$ be the payout for team member $i$ - $s_{i}$ be the share of the rewards for team member $i$ - $B_{i}$ be the total balance in all of the team members accounts (expressed in quantum) @@ -258,6 +266,7 @@ $$d_{i} = \begin{cases} Calculate each parties share of the rewards, $s_{i}$ pro-rata based on $d_{i}$, i.e. $$s_{i} = \frac{d_{i}}{\sum_{i=1}^{n}d_{i}}$$ + ## Acceptance criteria ### Funding reward accounts (0056-REWA-001) diff --git a/protocol/0057-TRAN-transfers.md b/protocol/0057-TRAN-transfers.md index b92eeb954..4258374b0 100644 --- a/protocol/0057-TRAN-transfers.md +++ b/protocol/0057-TRAN-transfers.md @@ -93,12 +93,12 @@ A party can further control their recurring transfer funding the reward pool by To support entity scoping, the transaction include the following fields: - `entity scope` - mandatory enum which defines the entities within scope. - - `ENTITY_SCOPE_INDIVIDUALS` - the rewards must be distributed directly amongst eligible parties - - `ENTITY_SCOPE_TEAMS` - the rewards must be distributed amongst directly eligible teams (and then amongst team members) + - `ENTITY_SCOPE_INDIVIDUALS` - the rewards must be distributed directly amongst eligible parties + - `ENTITY_SCOPE_TEAMS` - the rewards must be distributed amongst directly eligible teams (and then amongst team members) - `individual scope` - optional enum if the entity scope is `ENTITY_SCOPE_INDIVIDUALS` which defines the subset of individuals which are eligible to be rewarded. - - `INDIVIDUAL_SCOPE_ALL` - all parties on the network are within the scope of this reward - - `INDIVIDUAL_SCOPE_IN_TEAM` - all parties which are part of a team are within the scope of this reward - - `INDIVIDUAL_SCOPE_NOT_IN_TEAM` - all parties which are not part of a team are within the scope of this reward + - `INDIVIDUAL_SCOPE_ALL` - all parties on the network are within the scope of this reward + - `INDIVIDUAL_SCOPE_IN_TEAM` - all parties which are part of a team are within the scope of this reward + - `INDIVIDUAL_SCOPE_NOT_IN_TEAM` - all parties which are not part of a team are within the scope of this reward - `team scope` - optional list if the reward type is `ENTITY_SCOPE_TEAMS`, field allows the funder to define a list of team ids which are eligible to be rewarded from this transfer - At the end of the epoch when the transfer is about to be distributed, it first calculates the contribution of each market to the sum total reward metric for all markets in the `market scope` and then distributes the transfer amount to the corresponding accounts of the markets pro-rata by their contribution to the total. diff --git a/protocol/0085-RVST-rewards_vesting.md b/protocol/0085-RVST-rewards_vesting.md index 800793a5b..293715ed3 100644 --- a/protocol/0085-RVST-rewards_vesting.md +++ b/protocol/0085-RVST-rewards_vesting.md @@ -11,7 +11,7 @@ The aim of the rewards vesting mechanics is to prevent farming rewards by delayi ## Vesting mechanics -As detailed in [distributing rewards](), each party has their rewards paid into vesting rewards accounts (one for each asset). +As detailed in [distributing rewards](./0056-REWA-rewards_overview.md#distributing-rewards-amongst-entities), each party has their rewards paid into vesting rewards accounts (one for each asset). At the end of each epoch, a proportion of the rewards accumulated in each "vesting" account should be released and transferred to the respective "vested" account. The percentage released can be scaled by the account owner increasing their [activity streak](./0086-ASPR-activity_streak_program.md) and a minimum transfer amount will be applied to ensure the account is eventually emptied. The proportion released and minimum applied are controlled for parameters for the asset. @@ -19,9 +19,9 @@ Now, let: - $T$ be the amount to be "vested" (transferred from the vesting account to the vested account) - $B_{vested}$ be the total quantum amount in the vesting account -- $r_{bvr}$ be the network parameter `rewards.vesting.baseRate` +- $r$ be the network parameter `rewards.vesting.baseRate` - $a$ be the account owners current [`activity_streak_vesting_multiplier`](./0086-ASPR-activity_streak_program.md#setting-activity-benefits) -- $m_{mva}$ be the network parameter `rewards.vesting.minimumTransfer` +- $m$ be the network parameter `rewards.vesting.minimumTransfer` The quantum amount to be transferred from each "vesting" account to the relevant "vested" account is defined as: @@ -46,4 +46,4 @@ Must expose the following: ## Acceptance Criteria -TBD \ No newline at end of file +WIP diff --git a/protocol/0086-ASPR-activity_streak_program.md b/protocol/0086-ASPR-activity_streak_program.md index ddaa370dd..da18df0bb 100644 --- a/protocol/0086-ASPR-activity_streak_program.md +++ b/protocol/0086-ASPR-activity_streak_program.md @@ -20,10 +20,11 @@ Parties access higher tiers and greater benefits by maintaining an activity stre The network parameter [`rewards.activityStreak.benefitTiers`](#network-parameters) can be updated via a `UpdateNetworkParameter` governance proposal. Each tier in the ordered list must have the following fields: - `minimum_activity_streak`: int greater or equal to `0` defining the minimum activity streak a party must have to access this tier -- `reward_multiplier`: float greater or equal to `1` defining the factor to scale a parties [reward shares]() by -- `vesting_multiplier`: float greater or equal to `1` defining the factor to scale a parties [base vesting rate]() by +- `reward_multiplier`: float greater or equal to `1` defining the factor to scale a parties [reward shares](./0056-REWA-rewards_overview.md#distributing-rewards-amongst-entities) by +- `vesting_multiplier`: float greater or equal to `1` defining the factor to scale a parties [base vesting rate](./0085-RVST-rewards_vesting.md#vesting-mechanics) by *Example:* + ```proto message UpdateNetworkParameter{ changes: NetworkParameter{ @@ -49,13 +50,13 @@ For the feature, the network must track each parties "activity streak". At the e - if a party was "active" in the epoch - - increment their `activity_streak` by `1` - - reset their `inactivity_streak` to `0`. + - increment their `activity_streak` by `1` + - reset their `inactivity_streak` to `0`. - if a party was "inactive" in the epoch - - increment their `inactivity_streak` streak by `1` - - if their `inactivity_streak` is greater than or equal to the `rewards.activityStreak.streakLength`, reset their `activity_streak` to `0`. + - increment their `inactivity_streak` streak by `1` + - if their `inactivity_streak` is greater than or equal to the `rewards.activityStreak.streakLength`, reset their `activity_streak` to `0`. A party is defined as active if they fulfil **either** of the following criteria: @@ -91,11 +92,11 @@ Then: #### Applying the activity reward multiplier -The `activity_streak_reward_multiplier` scales the parties [reward share]() for all rewards they are eligible for. +The `activity_streak_reward_multiplier` scales the parties [reward share](./0056-REWA-rewards_overview.md#distributing-rewards-amongs-entities) for all rewards they are eligible for. #### Applying the activity vesting multiplier -The `activity_streak_vesting_multiplier` scales the parties [vesting rate]() of all funds locked in the parties vesting accounts. +The `activity_streak_vesting_multiplier` scales the parties [vesting rate](./0085-RVST-rewards_vesting.md#vesting-mechanics) of all funds locked in the parties vesting accounts. ## APIs @@ -114,12 +115,12 @@ Must expose the following: ### Governance proposals -TBD +WIP ### Setting activity / inactivity streak -TBD +WIP ### Setting activity benefits -TBD \ No newline at end of file +WIP From 11dd0ba58385fc4a8fdb69a0b0880537c2934959 Mon Sep 17 00:00:00 2001 From: Charlie Date: Tue, 8 Aug 2023 19:23:49 +0100 Subject: [PATCH 09/27] refactor: address network param feedback --- protocol/0086-ASPR-activity_streak_program.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/protocol/0086-ASPR-activity_streak_program.md b/protocol/0086-ASPR-activity_streak_program.md index da18df0bb..1a7fdbf22 100644 --- a/protocol/0086-ASPR-activity_streak_program.md +++ b/protocol/0086-ASPR-activity_streak_program.md @@ -11,7 +11,7 @@ Parties access higher tiers and greater benefits by maintaining an activity stre - `rewards.activityStreak.benefitTiers`: is an ordered list of dictionaries defining the requirements and benefits for each tier. - `rewards.activityStreak.inactivityLimit`: the maximum number of epochs a trader can be inactive before loosing their streak. -- `rewards.activityStreak.minQuantumOpenVolume`: the minimum open notional volume (expressed in quantum) for a trader to be considered active in an epoch +- `rewards.activityStreak.minQuantumOpenNotionalVolume`: the minimum open notional volume (expressed in quantum) for a trader to be considered active in an epoch - `rewards.activityStreak.minQuantumTradeVolume`: the minimum trade volume (expressed in quantum) for a trader to be considered active in an epoch @@ -56,11 +56,11 @@ For the feature, the network must track each parties "activity streak". At the e - if a party was "inactive" in the epoch - increment their `inactivity_streak` streak by `1` - - if their `inactivity_streak` is greater than or equal to the `rewards.activityStreak.streakLength`, reset their `activity_streak` to `0`. + - if their `inactivity_streak` is greater than or equal to the `rewards.activityStreak.inactivityLimit`, reset their `activity_streak` to `0`. A party is defined as active if they fulfil **either** of the following criteria: -- their open interest was strictly greater than `rewards.activityStreak.minQuantumOpenVolume` at any point in the epoch +- their open interest was strictly greater than `rewards.activityStreak.minQuantumOpenNotionalVolume` at any point in the epoch - their total trade volume was strictly greater than `rewards.activityStreak.minQuantumTradeVolume` at the end of the epoch ### Setting activity benefits From b75b4f1ff223ef7032465dcbf7f886736f846d3a Mon Sep 17 00:00:00 2001 From: Charlie Date: Tue, 8 Aug 2023 19:26:31 +0100 Subject: [PATCH 10/27] refactor: fix formatting --- protocol/0083-RFPR-on_chain_referral_program.md | 1 + 1 file changed, 1 insertion(+) diff --git a/protocol/0083-RFPR-on_chain_referral_program.md b/protocol/0083-RFPR-on_chain_referral_program.md index 8282e06a5..68e67385e 100644 --- a/protocol/0083-RFPR-on_chain_referral_program.md +++ b/protocol/0083-RFPR-on_chain_referral_program.md @@ -141,6 +141,7 @@ message CreateReferralSet{ team_url: "https://discord.com/channels/vegarocks", avatar_url: "https://vega-rocks/logo-360x360.jpg", closed: False, + } } ``` From 37554b5a30deb411eb3c1a25900be113accf09ee Mon Sep 17 00:00:00 2001 From: Charlie Date: Tue, 8 Aug 2023 19:29:06 +0100 Subject: [PATCH 11/27] feat: update the validator ranking metric --- protocol/0056-REWA-rewards_overview.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index 941919849..94173633e 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -120,18 +120,17 @@ $$R = \{r_i \cdot \log(1 +\bar{OI_{i}}) \mid i = 1, 2, \ldots, N\}$$ The reward metric $m_{rv}$ is the standard deviation of the set $R$. -### Validator power metric +### Validator ranking metric -The validator power metric, $m_{vp}$, measures the voting power of validators. +The validator ranking metric, $m_{vr}$, measures the ranking score of consensus and standby validators. -At the end of each epoch, for each party who is a validator set their reward metric as follows. +At the end of each epoch, for each party who **is** a consensus or standby validator set their reward metric as follows. -$$m_{vp} = validatorScore$$ +$$m_{vr} = rankingScore$$ -Note the `validatorScore` is the score **after** any [penalties](./0061-REWP-pos_rewards.md#for-each-validator-we-then-do) have been applied. -If a party is not a validator, their reward metric is simply: +If a party **is not** a consensus or standby validator, their reward metric is simply: -$$m_{vp} = 0$$ +$$m_{vr} = 0$$ ### Market creation reward metrics From 771f14cee53b08473c8ee775c64ef9341ab46458 Mon Sep 17 00:00:00 2001 From: Charlie Date: Thu, 10 Aug 2023 09:13:58 +0100 Subject: [PATCH 12/27] fix: correct variable name --- protocol/0056-REWA-rewards_overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index 94173633e..97448f6b2 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -116,7 +116,7 @@ At the end of an epoch, if a party has had net returns less than or equal to `0` Given the set: -$$R = \{r_i \cdot \log(1 +\bar{OI_{i}}) \mid i = 1, 2, \ldots, N\}$$ +$$R = \{\Delta{p} \cdot \log(1 +\bar{OI_{i}}) \mid i = 1, 2, \ldots, N\}$$ The reward metric $m_{rv}$ is the standard deviation of the set $R$. From cefc4990cfcdac6bae276cec1635282708a99bf0 Mon Sep 17 00:00:00 2001 From: Charlie Date: Mon, 14 Aug 2023 13:18:40 +0100 Subject: [PATCH 13/27] feat: add vested multiplier --- protocol/0056-REWA-rewards_overview.md | 6 +++--- protocol/0085-RVST-rewards_vesting.md | 30 ++++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 3 deletions(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index 97448f6b2..51de18c56 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -209,7 +209,7 @@ Let: - $d_{i}$ be the payout factor for entity $i$ - $r_{i}$ be the reward metric value for entity $i$ -- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ +- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [vested rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-vested-bonus-multiplier)). - $s_{i}$ be the share of the rewards for entity $i$ $$d_{i}=r_{i} M_{i}$$ @@ -234,7 +234,7 @@ Let: - $s_{i}$ be the share of the rewards for entity $i$ - $k$ be the decay factor specified in the recurring transfer funding the reward - $R_{i}$ be the rank of entity $i$ -- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ +- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [vested rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-vested-bonus-multiplier)). $$d_{i}=e^{-k R_{i}} M_{i}$$ @@ -255,7 +255,7 @@ Let: - $B_{i}$ be the total balance in all of the team members accounts (expressed in quantum) - $F$ be the network parameter `rewards.teamDistribution.minimumAccountQuantum` - $C$ be the network parameter `rewards.teamDistribution.maximumAccountQuantum` -- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ +- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [vested rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-vested-bonus-multiplier)). $$d_{i} = \begin{cases} 0 &\text{if } B_{i} < F \\ diff --git a/protocol/0085-RVST-rewards_vesting.md b/protocol/0085-RVST-rewards_vesting.md index 293715ed3..12d77b3e9 100644 --- a/protocol/0085-RVST-rewards_vesting.md +++ b/protocol/0085-RVST-rewards_vesting.md @@ -8,6 +8,7 @@ The aim of the rewards vesting mechanics is to prevent farming rewards by delayi - `rewards.vesting.baseRate`: the proportion of rewards in a vesting account which are vested each epoch, value defaults to `0.1` and must be a float strictly greater than 0. - `rewards.vesting.minimumTransfer`: the minimum amount (expressed in quantum) which can be vested each epoch, value defaults to 100 and must be an integer greater or equal than `0`. +- `rewards.vesting.rewardPayoutMultipliers`: is an ordered list of dictionaries defining the requirements and multipliers for each tier. ## Vesting mechanics @@ -29,6 +30,35 @@ $$T = max(B_{vesting} * r * a, m)$$ When transferring funds from the vesting account to the vested account, a new transfer type should be used, `TRANSFER_TYPE_REWARDS_VESTED`. +## Vested bonus + +Once vested rewards are transferred to the vested account, the party will be able to transfer funds to their general account using a normal transfer. + +Alternatively, they can leave their rewards in the vested account to receive a multiplier on their reward payout share. The size of this multiplier is dependent on the balance (expressed in quantum) in the vested account before rewards are distributed. + +Note, a party will be unable to transfer funds in to the vested account. + +### Determining the vested bonus multiplier + +Before [distributing rewards](./0056-REWA-rewards_overview.md#distributing-rewards-amongst-entities), each parties `reward_distribution_vested_multiplier` should be set according to the highest tier they qualify for. + +```pseudo +Given: + rewards.vesting.benefitTiers: [ + [ + {"minimum_quantum_balance": 10000, "reward_multiplier": 1.0}, + {"minimum_quantum_balance": 100000, "reward_multiplier": 5.0}, + {"minimum_quantum_balance": 1000000, "reward_multiplier": 10.0}, + ], + ] + +And: + vested_quantum_balance=145231 + +Then: + reward_distribution_vested_multiplier=5.0 +``` + ## APIs ### Accounts API From ff72db22a6b266c984d5dc279819540776fa21aa Mon Sep 17 00:00:00 2001 From: Charlie Date: Mon, 14 Aug 2023 13:48:10 +0100 Subject: [PATCH 14/27] feat: change total rewards calc as per feedback --- protocol/0056-REWA-rewards_overview.md | 6 +++--- protocol/0085-RVST-rewards_vesting.md | 16 +++++++++------- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index 51de18c56..274b75b5f 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -209,7 +209,7 @@ Let: - $d_{i}$ be the payout factor for entity $i$ - $r_{i}$ be the reward metric value for entity $i$ -- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [vested rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-vested-bonus-multiplier)). +- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [bonus rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-rewards-bonus-multiplier)). - $s_{i}$ be the share of the rewards for entity $i$ $$d_{i}=r_{i} M_{i}$$ @@ -234,7 +234,7 @@ Let: - $s_{i}$ be the share of the rewards for entity $i$ - $k$ be the decay factor specified in the recurring transfer funding the reward - $R_{i}$ be the rank of entity $i$ -- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [vested rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-vested-bonus-multiplier)). +- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [bonus rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-rewards-bonus-multiplier)). $$d_{i}=e^{-k R_{i}} M_{i}$$ @@ -255,7 +255,7 @@ Let: - $B_{i}$ be the total balance in all of the team members accounts (expressed in quantum) - $F$ be the network parameter `rewards.teamDistribution.minimumAccountQuantum` - $C$ be the network parameter `rewards.teamDistribution.maximumAccountQuantum` -- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [vested rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-vested-bonus-multiplier)). +- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [bonus rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-rewards-bonus-multiplier)). $$d_{i} = \begin{cases} 0 &\text{if } B_{i} < F \\ diff --git a/protocol/0085-RVST-rewards_vesting.md b/protocol/0085-RVST-rewards_vesting.md index 12d77b3e9..f91ab894b 100644 --- a/protocol/0085-RVST-rewards_vesting.md +++ b/protocol/0085-RVST-rewards_vesting.md @@ -8,7 +8,7 @@ The aim of the rewards vesting mechanics is to prevent farming rewards by delayi - `rewards.vesting.baseRate`: the proportion of rewards in a vesting account which are vested each epoch, value defaults to `0.1` and must be a float strictly greater than 0. - `rewards.vesting.minimumTransfer`: the minimum amount (expressed in quantum) which can be vested each epoch, value defaults to 100 and must be an integer greater or equal than `0`. -- `rewards.vesting.rewardPayoutMultipliers`: is an ordered list of dictionaries defining the requirements and multipliers for each tier. +- `rewards.vesting.rewardPayoutTiers`: is an ordered list of dictionaries defining the requirements and multipliers for each tier. ## Vesting mechanics @@ -30,17 +30,17 @@ $$T = max(B_{vesting} * r * a, m)$$ When transferring funds from the vesting account to the vested account, a new transfer type should be used, `TRANSFER_TYPE_REWARDS_VESTED`. -## Vested bonus +## Rewards bonus multiplier Once vested rewards are transferred to the vested account, the party will be able to transfer funds to their general account using a normal transfer. -Alternatively, they can leave their rewards in the vested account to receive a multiplier on their reward payout share. The size of this multiplier is dependent on the balance (expressed in quantum) in the vested account before rewards are distributed. +Alternatively, they can leave their rewards in the vested account to increase their total rewards balance and receive a multiplier on their reward payout share. The size of this multiplier is dependent on their total rewards balance, i.e. the sum of the parties locked rewards, vesting rewards and vested rewards. Note, funds removed from the vested account are not included in this total. Note, a party will be unable to transfer funds in to the vested account. -### Determining the vested bonus multiplier +### Determining the rewards bonus multiplier -Before [distributing rewards](./0056-REWA-rewards_overview.md#distributing-rewards-amongst-entities), each parties `reward_distribution_vested_multiplier` should be set according to the highest tier they qualify for. +Before [distributing rewards](./0056-REWA-rewards_overview.md#distributing-rewards-amongst-entities), each parties `reward_distribution_bonus_multiplier` should be set according to the highest tier they qualify for. ```pseudo Given: @@ -53,10 +53,12 @@ Given: ] And: - vested_quantum_balance=145231 + locked_quantum_amount=2 + vesting_quantum_amount=999 + vested_quantum_amount=99000 Then: - reward_distribution_vested_multiplier=5.0 + reward_distribution_bonus_multiplier=5.0 ``` ## APIs From 29c50f8cbdaaf26c2f883e9b6a44d4df55f6e484 Mon Sep 17 00:00:00 2001 From: Charlie Date: Mon, 14 Aug 2023 18:51:01 +0100 Subject: [PATCH 15/27] feat: remove logarithmic functions --- protocol/0056-REWA-rewards_overview.md | 65 +++++++++++++------------- protocol/0057-TRAN-transfers.md | 7 +++ 2 files changed, 40 insertions(+), 32 deletions(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index 274b75b5f..d3f3d7857 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -30,15 +30,17 @@ At the end of the epoch: ## Individual reward metrics -Individual reward metrics are scoped by [`reward type`, `market`, `party`] (this triplet can be thought of as a primary key for fee-based reward metrics). +Individual reward metrics are scoped by [`recurring transfer`, `market`, `party`] (this triplet can be thought of as a primary key for fee-based reward metrics). -Therefore a party may be in scope for the same reward type multiple times but no more than once per market per epoch. -Metrics will be calculated at the end of every epoch, for every eligible party, in each market for each reward type. +Therefore a party may be in scope for the same reward type multiple times per epoch. +Metrics will be calculated at the end of every epoch, for every eligible party, in each market, for each recurring transfer. Metrics only need to be calculated where the [market, reward type] reward account has a non-zero balance of at least one asset. Reward metrics will be calculated once for each party/market combination in the reward metric asset which is the [settlement asset](0070-MKTD-market-decimal-places.md) of the market. This is the original precision for the metric source data. +For each reward metric an individual must meet the [staking requirement](./0057-TRAN-transfers.md#recurring-transfers-to-reward-accounts) **AND** [notional time-weighted average position requirement](./0057-TRAN-transfers.md#recurring-transfers-to-reward-accounts)) set in the recurring transfer. If they do not then their reward metric is set to `0`. + ### Fee-based reward metrics There will be three reward metrics calculated based on fees. @@ -81,42 +83,38 @@ $$m_{oi} = \frac{\sum_{i}^{n}\bar{OI_{i}}}{N}$$ ### Relative return metric -The relative return metric, $m_{rr}$, measures each parties average relative return, weighted by their [time-weighted average open-interest](#open-interest-metric), over a number of epochs. - -At the start of the epoch, the network must store the parties current pnl. - -$$p_{0} = p_{realised} + p_{unrealised}$$ +The relative return metric, $m_{rr}$, measures each parties average relative return, weighted by their [time-weighted average position](#average-position-metric), over a number of epochs. -At the end of each epoch, the network must calculate and store the parties change in pnl: +At the end of each epoch, the network must calculate and store the parties relative returns as follows. Let: -- $\Delta{p}$ be the parties change in pnl -- $p_{realised}$ be the parties realised pnl at the end of the epoch -- $p_{unrealised}$ be the parties unrealised pnl at the end of the epoch +- $r_i$ be the parties relative returns in the epoch +- $m2m_{wins}$ be the sum of all mark-to-market win transfers in the epoch +- $m2m_{losses}$ be the sum of all mark-to-market loss transfers in the epoch +- $TWAP$ be the parties time-weighted average position in the epoch. -$$\Delta{p} = p_{realised} + p_{unrealised} - p_{0}$$ +$$r = \frac{m2m_{wins} + m2m_{losses}}{TWAP}$$ -And calculate their average relative return, weighted by the log of their [time weighted average open interest](#open-interest-metric), over the last $N$ epochs as follows. +And calculate their average relative returns over the last $N$ epochs as follows. Let: - $m_{rr}$ be the parties relative return reward metric -- $\bar{OI_{i}}$ be the parties time weighted average open interest in the ith epoch -- $\Delta{p}$ be the parties change in pnl in the ith epoch -- $N$ be the network parameter `rewards.metrics.relativeReturnsWindow` +- $r_i$ be the parties change in pnl in the i th epoch +- $N$ be the window length specified in the recurring transfer. -$$m_{rr} = \frac{\sum_{i}^{n}{$\Delta{p}$\cdot\log(1 + \bar{OI_{i}})}}{N}$$ +$$m_{rr} = \max(\frac{\sum_{i}^{n}{r_{i}}}{N}, 0)$$ ### Returns volatility metric The return volatility metric, $m_{rv}$, measures the volatility of a parties returns across a number of epochs. -At the end of an epoch, if a party has had net returns less than or equal to `0` over the last $N$ epochs (where $N$ is the network parameter `rewards.metrics.returnsVolatilityWindow`), their reward metric $m_{rv}$ is set to `0`. Otherwise, the network should calculate the standard deviation of the set of each parties returns weighted by the log of their [time weighted average open interest](#open-interest-metric) over the last $N$ epochs. +At the end of an epoch, if a party has had net returns less than or equal to `0` over the last $N$ epochs (where $N$ is the window length specified in the recurring transfer), their reward metric $m_{rv}$ is set to `0`. Otherwise, the network should calculate the standard deviation of the set of each parties returns over the last $N$ epochs. Given the set: -$$R = \{\Delta{p} \cdot \log(1 +\bar{OI_{i}}) \mid i = 1, 2, \ldots, N\}$$ +$$R = \{r_i \mid i = 1, 2, \ldots, N\}$$ The reward metric $m_{rv}$ is the standard deviation of the set $R$. @@ -214,7 +212,7 @@ Let: $$d_{i}=r_{i} M_{i}$$ -Note if the entity is a team, $M_{i}$ is set to zero as reward payout multipliers are considered later when distributing rewards [amongst the team members](#distributing-rewards-amongst-team-members). +Note if the entity is a team, $M_{i}$ is set to `1` as reward payout multipliers are considered later when distributing rewards [amongst the team members](#distributing-rewards-amongst-team-members). Calculate each entities share of the rewards, $s_{i}$ pro-rata based on $d_{i}$, i.e. @@ -226,19 +224,24 @@ Rewards funded using the exponential-decay strategy should be distributed as fol 1. Calculate each entities reward metric 2. Order each entity in a descending list by their reward metric value and determine their "rank" in the list -3. Calculate each entities share of the rewards using the below formula. +3. Normalize the rank of each party within a range of 0 to 1, using the highest rank as the upper limit for normalization. +4. Calculate each entities share of the rewards using the below formula. Let: - $d_{i}$ be the payout factor for entity $i$ - $s_{i}$ be the share of the rewards for entity $i$ -- $k$ be the decay factor specified in the recurring transfer funding the reward -- $R_{i}$ be the rank of entity $i$ +- $k$ be the decay factor specified in the recurring transfer funding the reward. +- $R_{i}$ be the normalised rank of entity $i$ - $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [bonus rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-rewards-bonus-multiplier)). -$$d_{i}=e^{-k R_{i}} M_{i}$$ +$$d_{i}=M_{i} e^{-k R_{i}}$$ + +Note if the entity is a team, $M_{i}$ is set to 1 as reward payout multipliers are considered later when distributing rewards [amongst the team members](#distributing-rewards-amongst-team-members). + +To avoid exponential formulas in the core implementation, the above exponential equation can be approximated using the following 7th order Taylor expansion. An odd number of terms has intentionally been chosen so the expansion diverges to $-\infty$ rather than $+\infty$. -Note if the entity is a team, $M_{i}$ is set to zero as reward payout multipliers are considered later when distributing rewards [amongst the team members](#distributing-rewards-amongst-team-members). +$$d_{i} = M_{i} e^{-k R_i} \approx M_{i} \min(1- \sum_{j=0}^{7} \frac{(-k R_i)^j}{j!}, 0)$$ Calculate each entities share of the rewards, $s_{i}$ pro-rata based on $d_{i}$, i.e. @@ -246,20 +249,18 @@ $$s_{i} = \frac{d_{i}}{\sum_{i=1}^{n}d_{i}}$$ ### Distributing rewards amongst team members -If rewards are distributed to a team, rewards must then be distributed between team members. +If rewards are distributed to a team, rewards must then be distributed between team members who had a reward metric, $m$, greater than `0` based on their payout multipliers. Let: - $d_{i}$ be the payout for team member $i$ - $s_{i}$ be the share of the rewards for team member $i$ -- $B_{i}$ be the total balance in all of the team members accounts (expressed in quantum) -- $F$ be the network parameter `rewards.teamDistribution.minimumAccountQuantum` -- $C$ be the network parameter `rewards.teamDistribution.maximumAccountQuantum` +- $m$ be the reward metric of the team member - $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [bonus rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-rewards-bonus-multiplier)). $$d_{i} = \begin{cases} - 0 &\text{if } B_{i} < F \\ - M_{i}\log(\min(B_{i}+1, C+1)) &\text{if } B_{i} \geq F + 0 &\text{if } m = 0 \\ + M_{i} &\text{if } m > 0 \end{cases}$$ Calculate each parties share of the rewards, $s_{i}$ pro-rata based on $d_{i}$, i.e. diff --git a/protocol/0057-TRAN-transfers.md b/protocol/0057-TRAN-transfers.md index 4258374b0..7db780a4b 100644 --- a/protocol/0057-TRAN-transfers.md +++ b/protocol/0057-TRAN-transfers.md @@ -100,6 +100,13 @@ To support entity scoping, the transaction include the following fields: - `INDIVIDUAL_SCOPE_IN_TEAM` - all parties which are part of a team are within the scope of this reward - `INDIVIDUAL_SCOPE_NOT_IN_TEAM` - all parties which are not part of a team are within the scope of this reward - `team scope` - optional list if the reward type is `ENTITY_SCOPE_TEAMS`, field allows the funder to define a list of team ids which are eligible to be rewarded from this transfer +- `staking_requirement` - the required minimum number of tokens staked for a party to be considered eligible. Defaults to `0`. +- `notional_time_weighted_average_position_requirement` - the required minimum notional time-weighted averaged position required for a party to be considered eligible. Defaults to `0`. + +A party should be able to configure the distribution of rewards by specifying a number of epochs to evaluate the reward metric over and specify a number of epochs to delay vesting by. The transaction should now include the following fields. + +- `window_length` - the number of epochs over which to evaluate the reward metric. +- `lock_period` - the number of epochs after distribution to delay [vesting of rewards](./0085-RVST-rewards_vesting.md#vesting-mechanics) by. - At the end of the epoch when the transfer is about to be distributed, it first calculates the contribution of each market to the sum total reward metric for all markets in the `market scope` and then distributes the transfer amount to the corresponding accounts of the markets pro-rata by their contribution to the total. From 9fac4b2badfa328c9488bbc0aff8e2011c613204 Mon Sep 17 00:00:00 2001 From: Charlie Date: Mon, 14 Aug 2023 18:52:38 +0100 Subject: [PATCH 16/27] refactor: rename open-interest metric to position metric --- protocol/0056-REWA-rewards_overview.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index d3f3d7857..47b05c58d 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -55,31 +55,31 @@ If the reward account balance is 0 at the end of the epoch for a given market, a Fee-based reward metrics (the total fees paid/received by each party as defined above) are stored in [LNL checkpoints](./0073-LIMN-limited_network_life.md) and are restored after a checkpoint restart to ensure rewards are not lost. -### Open interest metric +### Average position metric -The open interest metric, $m_{oi}$, measures each parties time-weighted average open interest over a number of epochs. +The average position metric, $m_{ap}$, measures each parties time-weighted average position over a number of epochs. -At the start of each epoch, the network must reset each parties time weighted average open interest for the epoch ($\bar{OI}$) to `0`. Whenever a parties position changes during an epoch, **and** at the end of the epoch, this value should be updated as follows. +At the start of each epoch, the network must reset each parties time weighted average position for the epoch ($\bar{P}$) to `0`. Whenever a parties position changes during an epoch, **and** at the end of the epoch, this value should be updated as follows. Let: -- $\bar{OI}$ be the parties time weighted average open interest in the epoch so far -- $OI_{n}$ be the parties open interest before their open interest changed +- $\bar{P}$ be the parties time weighted average position in the epoch so far +- $P_{n}$ be the parties position before their position changed - $t_{n}$ be the time the party held the previous position in seconds - $t$ be the amount of time elapsed in the current epoch so far -$$\bar{OI} = \bar{OI} \cdot \left(1 - \frac{t_{n}}{t}\right) + \frac{OI_{n} \cdot t_{n}}{t}$$ +$$\bar{P} = \bar{P} \cdot \left(1 - \frac{t_{n}}{t}\right) + \frac{|P_{n}| \cdot t_{n}}{t}$$ -At the end of the epoch, the network must store the parties time weighted average open interest and then calculate their open interest reward metric as follows. +At the end of the epoch, the network must store the parties time weighted average position and then calculate their average position reward metric as follows. Let: -- $m_{oi}$ be the parties open interest reward metric -- $\bar{OI_{i}}$ be the parties time weighted average open interest in the ith epoch -- $N$ be the network parameter `rewards.metrics.openInterestWindow` +- $m_{ap}$ be the parties average position reward metric +- $\bar{P_{i}}$ be the parties time weighted average position in the i th epoch +- $N$ be the window length specified in the recurring transfer. -$$m_{oi} = \frac{\sum_{i}^{n}\bar{OI_{i}}}{N}$$ +$$m_{ap} = \frac{\sum_{i}^{n}\bar{P_{i}}}{N}$$ ### Relative return metric From 3855351817fcfcd623446f345dbc836d621df69f Mon Sep 17 00:00:00 2001 From: Charlie Date: Mon, 14 Aug 2023 19:00:09 +0100 Subject: [PATCH 17/27] fix: fix linting and spellcheck --- protocol/0056-REWA-rewards_overview.md | 8 ++++---- protocol/0085-RVST-rewards_vesting.md | 2 +- protocol/0086-ASPR-activity_streak_program.md | 6 +++--- wordlist.txt | 3 +++ 4 files changed, 11 insertions(+), 8 deletions(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index 47b05c58d..09bc93c65 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -120,15 +120,15 @@ The reward metric $m_{rv}$ is the standard deviation of the set $R$. ### Validator ranking metric -The validator ranking metric, $m_{vr}$, measures the ranking score of consensus and standby validators. +The validator ranking metric, $m_v$, measures the ranking score of consensus and standby validators. At the end of each epoch, for each party who **is** a consensus or standby validator set their reward metric as follows. -$$m_{vr} = rankingScore$$ +$$m_v = ranking_score$$ If a party **is not** a consensus or standby validator, their reward metric is simply: -$$m_{vr} = 0$$ +$$m_v = 0$$ ### Market creation reward metrics @@ -224,7 +224,7 @@ Rewards funded using the exponential-decay strategy should be distributed as fol 1. Calculate each entities reward metric 2. Order each entity in a descending list by their reward metric value and determine their "rank" in the list -3. Normalize the rank of each party within a range of 0 to 1, using the highest rank as the upper limit for normalization. +3. Normalise the rank of each party within a range of 0 to 1, using the highest rank as the upper limit for normalisation. 4. Calculate each entities share of the rewards using the below formula. Let: diff --git a/protocol/0085-RVST-rewards_vesting.md b/protocol/0085-RVST-rewards_vesting.md index f91ab894b..eb3073b4c 100644 --- a/protocol/0085-RVST-rewards_vesting.md +++ b/protocol/0085-RVST-rewards_vesting.md @@ -78,4 +78,4 @@ Must expose the following: ## Acceptance Criteria -WIP +Too be added diff --git a/protocol/0086-ASPR-activity_streak_program.md b/protocol/0086-ASPR-activity_streak_program.md index 1a7fdbf22..5c7721959 100644 --- a/protocol/0086-ASPR-activity_streak_program.md +++ b/protocol/0086-ASPR-activity_streak_program.md @@ -115,12 +115,12 @@ Must expose the following: ### Governance proposals -WIP +Too be added ### Setting activity / inactivity streak -WIP +Too be added ### Setting activity benefits -WIP +Too be added diff --git a/wordlist.txt b/wordlist.txt index be1231188..8c5869ec7 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -315,3 +315,6 @@ dApp leaderboards ReferralSet CreateReferralSet +enum +ldots +infty From bbe8e929009775ec8f840ae7998c9867aa2aa097 Mon Sep 17 00:00:00 2001 From: Charlie Date: Tue, 15 Aug 2023 09:29:38 +0100 Subject: [PATCH 18/27] feat: add validation for k --- protocol/0056-REWA-rewards_overview.md | 4 ++-- wordlist.txt | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index 09bc93c65..148d8e839 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -231,7 +231,7 @@ Let: - $d_{i}$ be the payout factor for entity $i$ - $s_{i}$ be the share of the rewards for entity $i$ -- $k$ be the decay factor specified in the recurring transfer funding the reward. +- $k$ be the decay factor specified in the recurring transfer funding the reward. This must be a float in the range $0\leq k \leq 2$. - $R_{i}$ be the normalised rank of entity $i$ - $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [bonus rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-rewards-bonus-multiplier)). @@ -241,7 +241,7 @@ Note if the entity is a team, $M_{i}$ is set to 1 as reward payout multipliers a To avoid exponential formulas in the core implementation, the above exponential equation can be approximated using the following 7th order Taylor expansion. An odd number of terms has intentionally been chosen so the expansion diverges to $-\infty$ rather than $+\infty$. -$$d_{i} = M_{i} e^{-k R_i} \approx M_{i} \min(1- \sum_{j=0}^{7} \frac{(-k R_i)^j}{j!}, 0)$$ +$$d_{i} = M_{i} e^{-k R_i} \approx M_{i} \min(\sum_{j=0}^{7} \frac{(-k R_i)^j}{j!}, 0)$$ Calculate each entities share of the rewards, $s_{i}$ pro-rata based on $d_{i}$, i.e. diff --git a/wordlist.txt b/wordlist.txt index 8c5869ec7..7ca46810b 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -318,3 +318,4 @@ CreateReferralSet enum ldots infty +leq From 2f18f45c19991a5cb6bc1bf82215476a3bd5635d Mon Sep 17 00:00:00 2001 From: Charlie <99198652+cdummett@users.noreply.github.com> Date: Tue, 15 Aug 2023 10:55:54 +0100 Subject: [PATCH 19/27] feat: address feedback Co-authored-by: David Siska <62546419+davidsiska-vega@users.noreply.github.com> --- protocol/0056-REWA-rewards_overview.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index 148d8e839..fd13bb13a 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -69,14 +69,14 @@ Let: - $t$ be the amount of time elapsed in the current epoch so far -$$\bar{P} = \bar{P} \cdot \left(1 - \frac{t_{n}}{t}\right) + \frac{|P_{n}| \cdot t_{n}}{t}$$ +$$\bar{P} \leftarrow \bar{P} \cdot \left(1 - \frac{t_{n}}{t}\right) + \frac{|P_{n}| \cdot t_{n}}{t}$$ At the end of the epoch, the network must store the parties time weighted average position and then calculate their average position reward metric as follows. Let: - $m_{ap}$ be the parties average position reward metric -- $\bar{P_{i}}$ be the parties time weighted average position in the i th epoch +- $\bar{P_{i}}$ be the parties time weighted average position in the $i$-th epoch - $N$ be the window length specified in the recurring transfer. $$m_{ap} = \frac{\sum_{i}^{n}\bar{P_{i}}}{N}$$ @@ -92,9 +92,9 @@ Let: - $r_i$ be the parties relative returns in the epoch - $m2m_{wins}$ be the sum of all mark-to-market win transfers in the epoch - $m2m_{losses}$ be the sum of all mark-to-market loss transfers in the epoch -- $TWAP$ be the parties time-weighted average position in the epoch. +- $\bar{P}$ be the parties time-weighted average position in the epoch. -$$r = \frac{m2m_{wins} + m2m_{losses}}{TWAP}$$ +$$r = \frac{|m2m_{wins}| - |m2m_{losses}|}{\bar{P}}$$ And calculate their average relative returns over the last $N$ epochs as follows. From 28249770a2f0ae7e32558198aa97bbbae36dea4f Mon Sep 17 00:00:00 2001 From: Charlie <99198652+cdummett@users.noreply.github.com> Date: Tue, 15 Aug 2023 11:17:00 +0100 Subject: [PATCH 20/27] feat: address exponential feedback Co-authored-by: David Siska <62546419+davidsiska-vega@users.noreply.github.com> --- protocol/0056-REWA-rewards_overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index fd13bb13a..e6231f20e 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -231,7 +231,7 @@ Let: - $d_{i}$ be the payout factor for entity $i$ - $s_{i}$ be the share of the rewards for entity $i$ -- $k$ be the decay factor specified in the recurring transfer funding the reward. This must be a float in the range $0\leq k \leq 2$. +- $k$ be the decay factor specified in the recurring transfer funding the reward. This must be a decimal in the range $0\leq k \leq 2$. - $R_{i}$ be the normalised rank of entity $i$ - $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [bonus rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-rewards-bonus-multiplier)). @@ -239,7 +239,7 @@ $$d_{i}=M_{i} e^{-k R_{i}}$$ Note if the entity is a team, $M_{i}$ is set to 1 as reward payout multipliers are considered later when distributing rewards [amongst the team members](#distributing-rewards-amongst-team-members). -To avoid exponential formulas in the core implementation, the above exponential equation can be approximated using the following 7th order Taylor expansion. An odd number of terms has intentionally been chosen so the expansion diverges to $-\infty$ rather than $+\infty$. +To avoid exponential formulas in the core implementation, the above exponential function can be approximated using the following 7th order Taylor expansion. An odd number of terms has intentionally been chosen so the expansion diverges to $-\infty$ rather than $+\infty$. $$d_{i} = M_{i} e^{-k R_i} \approx M_{i} \min(\sum_{j=0}^{7} \frac{(-k R_i)^j}{j!}, 0)$$ From 4154bcb70a8851fb631a19051e467d0d9b4de8a1 Mon Sep 17 00:00:00 2001 From: Charlie Date: Tue, 15 Aug 2023 18:18:17 +0100 Subject: [PATCH 21/27] feat: switch rank exponential distribution to table --- protocol/0056-REWA-rewards_overview.md | 39 ++++++++++++++++++-------- protocol/0057-TRAN-transfers.md | 16 ++++++++++- 2 files changed, 43 insertions(+), 12 deletions(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index e6231f20e..fb35f8bdb 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -196,8 +196,8 @@ Rewards are distributed amongst entities based on the distribution method define The protocol currently supports the following distribution strategies: -- [pro-rata](#distributing-pro-rata) by reward metric -- [exponential-decay](#distributing-with-exponential-decay) by reward metric +- [pro-rata]:(#distributing-pro-rata) distributed pro-rata by reward metric +- [rank]:(#distributing-based-on-rank) distributed by entities rank when ordered by reward metric #### Distributing pro-rata @@ -218,28 +218,45 @@ Calculate each entities share of the rewards, $s_{i}$ pro-rata based on $d_{i}$, $$s_{i} = \frac{d_{i}}{\sum_{i=1}^{n}d_{i}}$$ -#### Distributing with exponential decay +#### Distributing based on rank -Rewards funded using the exponential-decay strategy should be distributed as follows. +Rewards funded using the rank-distribution strategy should be distributed as follows. -1. Calculate each entities reward metric -2. Order each entity in a descending list by their reward metric value and determine their "rank" in the list -3. Normalise the rank of each party within a range of 0 to 1, using the highest rank as the upper limit for normalisation. -4. Calculate each entities share of the rewards using the below formula. +1. Calculate each entity's reward metric. +2. Arrange all entities in a list in descending order based on their reward metric values and determine their rank. If multiple entities share the same reward metric value, they should be assigned the same rank. The next entity's rank should be adjusted to account for the shared rank among the previous entities. For instance, if two entities share rank 2, the next entity should be assigned rank 4 (since there are two entities with rank 2). +3. Set the entities `share_ratio` based on their position in the `rank_table` specified in the recurring transfer. +4. Calculate each entities share of the rewards. + +```pseudo +Given: + rank_table = [ + {"start_rank": 1, "share_ratio": 10}, + {"start_rank": 2, "share_ratio": 5}, + {"start_rank": 4, "share_ratio": 2}, + {"start_rank": 10, "share_ratio": 1}, + {"start_rank": 20, "share_ratio": 0}, + ] + rank=6 + +Then: + share_ratio=2 +``` + +Calculate each entities share of the rewards as follows. Let: - $d_{i}$ be the payout factor for entity $i$ - $s_{i}$ be the share of the rewards for entity $i$ -- $k$ be the decay factor specified in the recurring transfer funding the reward. This must be a decimal in the range $0\leq k \leq 2$. +- $k$ be the decay factor specified in the recurring transfer funding the reward. This must be a float in the range $0\leq k \leq 2$. - $R_{i}$ be the normalised rank of entity $i$ - $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [bonus rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-rewards-bonus-multiplier)). -$$d_{i}=M_{i} e^{-k R_{i}}$$ +$$d_{i}=M_{i} * r_{i}$$ Note if the entity is a team, $M_{i}$ is set to 1 as reward payout multipliers are considered later when distributing rewards [amongst the team members](#distributing-rewards-amongst-team-members). -To avoid exponential formulas in the core implementation, the above exponential function can be approximated using the following 7th order Taylor expansion. An odd number of terms has intentionally been chosen so the expansion diverges to $-\infty$ rather than $+\infty$. +To avoid exponential formulas in the core implementation, the above exponential equation can be approximated using the following 7th order Taylor expansion. An odd number of terms has intentionally been chosen so the expansion diverges to $-\infty$ rather than $+\infty$. $$d_{i} = M_{i} e^{-k R_i} \approx M_{i} \min(\sum_{j=0}^{7} \frac{(-k R_i)^j}{j!}, 0)$$ diff --git a/protocol/0057-TRAN-transfers.md b/protocol/0057-TRAN-transfers.md index 7db780a4b..774dd01e5 100644 --- a/protocol/0057-TRAN-transfers.md +++ b/protocol/0057-TRAN-transfers.md @@ -103,10 +103,24 @@ To support entity scoping, the transaction include the following fields: - `staking_requirement` - the required minimum number of tokens staked for a party to be considered eligible. Defaults to `0`. - `notional_time_weighted_average_position_requirement` - the required minimum notional time-weighted averaged position required for a party to be considered eligible. Defaults to `0`. -A party should be able to configure the distribution of rewards by specifying a number of epochs to evaluate the reward metric over and specify a number of epochs to delay vesting by. The transaction should now include the following fields. +A party should be able to configure the distribution of rewards by specifying the following fields: - `window_length` - the number of epochs over which to evaluate the reward metric. - `lock_period` - the number of epochs after distribution to delay [vesting of rewards](./0085-RVST-rewards_vesting.md#vesting-mechanics) by. +- `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. +- `rank_table` - if the distribution strategy is `DISTRIBUTION_STRATEGY_RANK`, an ordered list dictionaries defining the rank bands and share ratio for each band should be specified. Note, the `start_rank` values must be integers and in an ascending order. + + ```pseudo + rank_table = [ + {"start_rank": 1, "share_ratio": 10}, + {"start_rank": 2, "share_ratio": 5}, + {"start_rank": 4, "share_ratio": 2}, + {"start_rank": 10, "share_ratio": 1}, + {"start_rank": 20, "share_ratio": 0}, + ] + ``` - At the end of the epoch when the transfer is about to be distributed, it first calculates the contribution of each market to the sum total reward metric for all markets in the `market scope` and then distributes the transfer amount to the corresponding accounts of the markets pro-rata by their contribution to the total. From a6e14e836ca04c52f6fb78f01f79dc3fa351292d Mon Sep 17 00:00:00 2001 From: Charlie Date: Tue, 15 Aug 2023 18:30:39 +0100 Subject: [PATCH 22/27] feat: address feedback --- protocol/0056-REWA-rewards_overview.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index fb35f8bdb..1529dbcff 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -248,18 +248,13 @@ Let: - $d_{i}$ be the payout factor for entity $i$ - $s_{i}$ be the share of the rewards for entity $i$ -- $k$ be the decay factor specified in the recurring transfer funding the reward. This must be a float in the range $0\leq k \leq 2$. -- $R_{i}$ be the normalised rank of entity $i$ +- $r_{i}$ be the share ratio of entity $i$ as determined from the rank table - $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [bonus rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-rewards-bonus-multiplier)). $$d_{i}=M_{i} * r_{i}$$ Note if the entity is a team, $M_{i}$ is set to 1 as reward payout multipliers are considered later when distributing rewards [amongst the team members](#distributing-rewards-amongst-team-members). -To avoid exponential formulas in the core implementation, the above exponential equation can be approximated using the following 7th order Taylor expansion. An odd number of terms has intentionally been chosen so the expansion diverges to $-\infty$ rather than $+\infty$. - -$$d_{i} = M_{i} e^{-k R_i} \approx M_{i} \min(\sum_{j=0}^{7} \frac{(-k R_i)^j}{j!}, 0)$$ - Calculate each entities share of the rewards, $s_{i}$ pro-rata based on $d_{i}$, i.e. $$s_{i} = \frac{d_{i}}{\sum_{i=1}^{n}d_{i}}$$ From f83d1cdddd75506dbefb0e43f9ae5232bb670b41 Mon Sep 17 00:00:00 2001 From: Charlie <99198652+cdummett@users.noreply.github.com> Date: Wed, 16 Aug 2023 08:56:29 +0100 Subject: [PATCH 23/27] feat: apply suggestion Co-authored-by: Barnaby M --- protocol/0057-TRAN-transfers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protocol/0057-TRAN-transfers.md b/protocol/0057-TRAN-transfers.md index 774dd01e5..0242aeb62 100644 --- a/protocol/0057-TRAN-transfers.md +++ b/protocol/0057-TRAN-transfers.md @@ -100,7 +100,7 @@ To support entity scoping, the transaction include the following fields: - `INDIVIDUAL_SCOPE_IN_TEAM` - all parties which are part of a team are within the scope of this reward - `INDIVIDUAL_SCOPE_NOT_IN_TEAM` - all parties which are not part of a team are within the scope of this reward - `team scope` - optional list if the reward type is `ENTITY_SCOPE_TEAMS`, field allows the funder to define a list of team ids which are eligible to be rewarded from this transfer -- `staking_requirement` - the required minimum number of tokens staked for a party to be considered eligible. Defaults to `0`. +- `staking_requirement` - the required minimum number of governance (e.g. VEGA) tokens staked for a party to be considered eligible. Defaults to `0`. - `notional_time_weighted_average_position_requirement` - the required minimum notional time-weighted averaged position required for a party to be considered eligible. Defaults to `0`. A party should be able to configure the distribution of rewards by specifying the following fields: From 1a29685a886928918d3a2b6b04e4a3302f6d3d7f Mon Sep 17 00:00:00 2001 From: Charlie Date: Wed, 16 Aug 2023 12:51:11 +0100 Subject: [PATCH 24/27] feat: add limits --- protocol/0057-TRAN-transfers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/protocol/0057-TRAN-transfers.md b/protocol/0057-TRAN-transfers.md index 0242aeb62..576d1c4cf 100644 --- a/protocol/0057-TRAN-transfers.md +++ b/protocol/0057-TRAN-transfers.md @@ -105,12 +105,12 @@ To support entity scoping, the transaction include the following fields: A party should be able to configure the distribution of rewards by specifying the following fields: -- `window_length` - the number of epochs over which to evaluate the reward metric. +- `window_length` - the number of epochs over which to evaluate the reward metric. The value should be limited to 100 epochs. - `lock_period` - the number of epochs after distribution to delay [vesting of rewards](./0085-RVST-rewards_vesting.md#vesting-mechanics) by. - `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. -- `rank_table` - if the distribution strategy is `DISTRIBUTION_STRATEGY_RANK`, an ordered list dictionaries defining the rank bands and share ratio for each band should be specified. Note, the `start_rank` values must be integers and in an ascending order. +- `rank_table` - if the distribution strategy is `DISTRIBUTION_STRATEGY_RANK`, an ordered list dictionaries defining the rank bands and share ratio for each band should be specified. Note, the `start_rank` values must be integers in an ascending order and the table can have strictly no more than 500 rows. ```pseudo rank_table = [ From 99c66bdab101620e41d15158bf55612a86eb8755 Mon Sep 17 00:00:00 2001 From: Charlie Date: Wed, 16 Aug 2023 13:03:08 +0100 Subject: [PATCH 25/27] feat: clarify requirements not applied for certain metrics --- protocol/0056-REWA-rewards_overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index 1529dbcff..0113b1151 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -39,7 +39,7 @@ Metrics only need to be calculated where the [market, reward type] reward accoun Reward metrics will be calculated once for each party/market combination in the reward metric asset which is the [settlement asset](0070-MKTD-market-decimal-places.md) of the market. This is the original precision for the metric source data. -For each reward metric an individual must meet the [staking requirement](./0057-TRAN-transfers.md#recurring-transfers-to-reward-accounts) **AND** [notional time-weighted average position requirement](./0057-TRAN-transfers.md#recurring-transfers-to-reward-accounts)) set in the recurring transfer. If they do not then their reward metric is set to `0`. +For reward metrics relating to trading, an individual must meet the [staking requirement](./0057-TRAN-transfers.md#recurring-transfers-to-reward-accounts) **AND** [notional time-weighted average position requirement](./0057-TRAN-transfers.md#recurring-transfers-to-reward-accounts)) set in the recurring transfer. If they do not then their reward metric is set to `0`. Note, these requirements do not apply to the [validator ranking metric](#returns-volatility-metric) or the [market creation reward metric](#market-creation-reward-metrics). ### Fee-based reward metrics From 1c35a929240b304d4121ace769e0cd5d71d5800d Mon Sep 17 00:00:00 2001 From: Charlie Date: Tue, 22 Aug 2023 21:07:11 +0100 Subject: [PATCH 26/27] feat: switch reward accounts to per unique transfer --- protocol/0056-REWA-rewards_overview.md | 15 ++++++++------- protocol/0057-TRAN-transfers.md | 4 ++-- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index 0113b1151..b62c71944 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -41,6 +41,8 @@ This is the original precision for the metric source data. For reward metrics relating to trading, an individual must meet the [staking requirement](./0057-TRAN-transfers.md#recurring-transfers-to-reward-accounts) **AND** [notional time-weighted average position requirement](./0057-TRAN-transfers.md#recurring-transfers-to-reward-accounts)) set in the recurring transfer. If they do not then their reward metric is set to `0`. Note, these requirements do not apply to the [validator ranking metric](#returns-volatility-metric) or the [market creation reward metric](#market-creation-reward-metrics). +For reward transfers where the [scope](./0057-TRAN-transfers.md#recurring-transfers-to-reward-accounts) is set to teams, each party must meet the minimum time in team requirement. That is, given a party has been in a team for $N$ epochs, if $N$ is strictly less than the network parameter `rewards.minimumEpochsInTeam` (an integer defaulting to `0`) their reward metric is set to `0`. + ### Fee-based reward metrics There will be three reward metrics calculated based on fees. @@ -51,7 +53,7 @@ There will be three reward metrics calculated based on fees. These metrics apply only to the sum of fees for the epoch in question. That is, the metrics are reset to zero for all parties at the end of the epoch. -If the reward account balance is 0 at the end of the epoch for a given market, any parties with non-zero metrics will not be rewarded for that epoch and their metric scores do not roll over (they are still zeroed). +If the reward account balance is `0` at the end of the epoch for a given recurring transfer, any parties with non-zero metrics will not be rewarded for that epoch and their metric scores do not roll over (they are still zeroed). Fee-based reward metrics (the total fees paid/received by each party as defined above) are stored in [LNL checkpoints](./0073-LIMN-limited_network_life.md) and are restored after a checkpoint restart to ensure rewards are not lost. @@ -170,15 +172,14 @@ A team’s reward metric is the weighted average metric score of the top perform ## Reward accounts -Trading reward accounts are defined by the reward asset (the asset in which the reward is paid out), the market, and the reward type (metric). -That is, there can be multiple rewards with the same type paid in different assets for the same market. +Trading reward accounts are defined by a hash of the fields specified in the recurring transfer funding the reward account (see the [transfers](./0057-TRAN-transfers.md#recurring-transfers-to-reward-accounts) spec for relevant details about each field). This allows multiple recurring transfers to fund the same reward pool. + +Note as part of the recurring transfer a user specifies a settlement asset. The market settlement asset has nothing to do in in particular with the asset used to pay out a reward. -Note that the market settlement asset has nothing to do in particular with the asset used to pay out a reward for a market. That is, a participant might receive rewards in the settlement asset of the market, in VEGA governance tokens, and in any number of other unrelated tokens (perhaps governance of "loyalty"/reward tokens issued by LPs or market creators, or stablecoins like DAI). -Reward accounts are funded by setting up recurring transfers, which may be set to occur only once for a one off reward. -These allow a reward type to be automatically funded on an ongoing basis from a pool of assets. -Recurring transfers can target groups of markets, or all markets for a settlement asset, in which case the amount paid to each market is determined pro-rata by the markets' relative total reward metrics for the given reward type. See [transfers](./0057-TRAN-transfers.md) for more detail. +Reward accounts are funded by setting up recurring transfers, which may be set to occur only once for a one off reward. These allow a reward type to be automatically funded on an ongoing basis from a pool of assets. +Recurring transfers can target groups of markets, or all markets for a settlement asset. See [transfers](./0057-TRAN-transfers.md) for more detail. Reward accounts and balances must be saved in [LNL checkpoints](./0073-LIMN-limited_network_life.md) to ensure all funds remain accounted for across a restart. diff --git a/protocol/0057-TRAN-transfers.md b/protocol/0057-TRAN-transfers.md index 576d1c4cf..2082e4b2c 100644 --- a/protocol/0057-TRAN-transfers.md +++ b/protocol/0057-TRAN-transfers.md @@ -79,9 +79,9 @@ If the `amount` is less than `transfer.minTransferQuantumMultiple x quantum` the Read this section alongside the [rewards](./0056-REWA-rewards_overview.md) specification. -To be able to dispatch rewards to reward pools of multiple markets pro rata to the contribution of the reward metric (e.g. received maker fees) in the market vs the total of the measured metric across all in scope markets, recurring transfers support auto dispatch in the following way: +When funding a reward account with a recurring transfer, the reward account funded is the hash of the fields in the recurring transfer specific to funding reward accounts (listed below). -- When transferring to a reward account, the transaction must also include the following: +When transferring to a reward account, the transaction must include the following: - `reward metric` — the type of reward (see [rewards](./0056-REWA-rewards_overview.md)) - `reward metric asset` — (the settlement asset of all markets that will be in scope for the transfer) From 4e8202bb8c36df94429dbcc3bae7a48156269adf Mon Sep 17 00:00:00 2001 From: Charlie Date: Wed, 23 Aug 2023 15:06:46 +0100 Subject: [PATCH 27/27] refactor: clarification of lock period --- protocol/0056-REWA-rewards_overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protocol/0056-REWA-rewards_overview.md b/protocol/0056-REWA-rewards_overview.md index b62c71944..6828f9537 100644 --- a/protocol/0056-REWA-rewards_overview.md +++ b/protocol/0056-REWA-rewards_overview.md @@ -185,7 +185,7 @@ Reward accounts and balances must be saved in [LNL checkpoints](./0073-LIMN-limi ## Reward distribution -All rewards are distributed to [vesting accounts](./0085-RVST-rewards_vesting.md) at the end of each epoch *after* [recurring transfers](0057-TRAN-transfers.md) have been executed. +All rewards are distributed to [vesting accounts](./0085-RVST-rewards_vesting.md) at the end of each epoch *after* [recurring transfers](0057-TRAN-transfers.md) have been executed. Funds distributed to the vesting account will not start vesting until the [`lock period`](./0057-TRAN-transfers.md#recurring-transfers-to-reward-accounts) defined in the recurring transfer has expired. The entire reward account balance is paid out every epoch unless the total value of the metric over all entities is zero, in which case the balance will also be zero anyway (there are no fractional payouts).