rewards

x/rewards

Abstract

This document specifies the rewards module of Lava Protocol.

The rewards module is responsible for distributing rewards to validators and providers. Rewards are collected from the validators' and providers' pools, respectively. The pools' funds originate from the treasury account - a module account that holds all the pre-allocated Lava tokens of the network. It is important to note that the pre-allocated amount is constant, and there will be no minting of new Lava tokens in the future.

The rewards module also operates the Incentivized Providers RPC program (IPRPC). This program distributes bonus rewards to providers servicing specific chains. The IPRPC rewards are funded by the chains' DAO and other contributors.

Please note that this module replaces Cosmos SDK's mint module, which is typically responsible for minting rewards for validators.

Contents

• Concepts
  • The Treasury
  • Rewards Pools
    • Validators Rewards Pool
    • Providers Rewards Pool
  • IPRPC
• Parameters
  • MinBondedTarget
  • MaxBondedTarget
  • LowFactor
  • LeftOverBurnRate
• Queries
• Transactions
• Proposals

Concepts

The Treasury

As per Lava's vision, there is a constant supply of Lava tokens from the chain's genesis. There will be no minting of new tokens in the future like other Cosmos-SDK based chains. The treasury account holds all of Lava's pre-allocated tokens. The total amount of coins will be $10^9 * 10^6$ ulava.

Rewards Pools

The rewards module is responsible on distributing rewards for validators that create new blocks, and providers that provide RPC service for their consumers.

To manage the rewards, the module uses two rewards pools: allocation pools and distribution pools. Note that there are two allocation pools and two distribution pools to manage the validators and providers rewards independently.

The allocation pools get some of the treasury account's tokens and hold onto it. Once a month, the allocation pools transfer a fixed amount of funds to the distribution pools. This monthly transfer will last for 4 years, after which the alocation pools' funds will be depleted (the allocation pools lifetime (4 years) is a pre-defined constant in the module's code). Note that before the allocation pools transfer the funds, the distribution pools' tokens are burned according to the LeftOverBurnRate parameter (see below).

The distribution pools use the monthly quota of funds to distribute rewards for validators and providers.

Validators Rewards Pool

In Cosmos-SDK chains, validators get rewards for creating blocks by the Cosmos' distribution module. For each new block, new tokens are minted and distributed to all the accounts that contributed to the new block creation.

In Lava, the Cosmos validators reward distribution mechanism remains as is, but the source of the tokens comes from the rewards module (and not the mint module). As stated above, the rewards are managed using two pools: an allocation pool and a distribution pool.

The allocation pool of validators, validators_rewards_allocation_pool, gets 3% of the tokens of the treasury account.

The distribution pool of validators, validators_rewards_distribution_pool, uses its funds to reward validators for proposing new blocks. Same as Cosmos' mint module, the validators_rewards_distribution_pool transfers the block rewards to the fee collection account which is used by Cosmos' distribution module to reward the validators.

The validators block reward is calculated using the following formula:

Reward = \frac{{\text{{validators\_distribution\_pool\_balance}}} \cdot {\text{bonded\_target\_factor}}}{\text{{remaining\_blocks\_until\_next\_emission}}}

Where:

• $\text{validators\_distribution\_pool\_balance}$ - The remaining balance in the validators_rewards_distribution_pool.
• $\text{bonded\_target\_factor}$ - A factor calculated with the module's params (see below).
• $\text{remaining\_blocks\_until\_next\_emission}$ - The amount of blocks until the next monthly refill of the validators_rewards_distribution_pool.

Providers Rewards Pool

Providers get rewards for their services from the funds used to buy subscriptions (see subscription module readme).

Besides these rewards, the provider also get monthly bonus rewards from a pre-allocated rewards pools. To manage this, like the validators, the providers have an allocation and distribution rewards pools. The bonus rewards exist to provide additional rewards when there is no much demand (few subscriptions).

The total monthly bonus rewards ("total spec payout") are calculated per spec by the following formula:

\text{Total spec payout}=\\\min\{MaxRewardsBoost\cdot\text{Total Base Payouts}, \\ \text{Spec Payout Cap}, \\ \max\{0,1.5(\text{Spec Payout Cap})-0.5(\text{Total Base Payouts})\}\}

Where:

• $\text{MaxRewardsBoost}$ - A module's parameter (see below).
• $\text{Total Base Payouts}$ - The sum of all base payouts the providers for this spec collected = $\sum_{provider_1.._n} (\text{{provider base rewards}}_i)$
• $\text{Spec Payout Cap}$ - The max value for this spec bonus rewards = $\frac{specStake\cdot specShares}{\sum_i{specStake \cdot specShares}_i}$.
• SpecStake = Total effective stake of providers in this spec.
• SpecShares = Weight factor for the spec (determined in each spec)

The total spec payout is distributed between providers proportional to the rewards they collected from subscriptions throughtout the month. Each provider will get bonus rewards according to the following formula:

Provider Bonus Rewards = Total Spec Payout \cdot \frac{\sum_{\text{payment} \; i} (\text{{provider base rewards}}_{i,j} \times \text{{adjustment}}_{i,j})}{\sum_{\text{provider}\;j'}\sum_{\text{payment} \; i}  (\text{{provider base rewards}}_{i,j'}  )}

Note that some of the providers rewards are sent to the community pool (according to the CommunityTax parameter, determined by the distribution module) and to the validators block rewards (according to the ValidatorsSubscriptionParticipation parameter, see below). For more details about the adjustment, see below.

The participation fees are calculated according to the following formulas:

\text{Validators Participation Fee} = \frac{ValidatorsSubscriptionParticipation}{1-CommunityTax}

\text{Community Participation Fee} = ValidatorsSubscriptionParticipation + CommunityTax\\ - \text{Validators Participation Fee}

Adjustment

Adjustment is a security mechanism that prevents collusion and abuse of rewards boost. It calculates the distribution of usage across multiple providers for each consumer. The more scattered a consumer's usage is across providers, the higher the bonus rewards they can receive. The adjustment value is always smaller or equal to one and can reduce the bonus rewards by up to $\frac{1}{MaxRewardsBoost}$.

The adjustment is calculated per epoch using a weighted average based on usage. It considers the consumer's CU (compute units) used with a specific provider relative to the total CU the consumer used. The formula is as follows:

\text{epochAdjustment}_\text{consumet i, provider j}=\\\min\{1,\;\;\;minAdjustment\cdot(\frac{\sum_{\text{provider }k}{CU_\text{i,k}}}{CU _\text{i,j}})\}

\text{monthlyAdjustment}_{i,k} = \frac{\sum_{\text{epoch}\; t }\left(CU_\text{i}(t)\cdot \text{epochAdjustment}_{i,k}(t)\right)}{\sum_{\text{epoch}\; t}CU_{i}(t)}

IPRPC

IPRPC (Incentivized Providers RPC) is a program designed to motivate providers to offer services for specific chains using Lava. Providers supplying RPC data for chain X will receive additional rewards from the IPRPC pool each month. This pool is funded by chain X's DAO and other contributors.

The IPRPC pools will hold both Lava's native tokens and IBC wrapped tokens. Providers' rewards will be based on the amount of CU they serviced during the month relative to other providers' serviced CU. Only the CU from eligible subscriptions will be counted. IPRPC eligible subscriptions are determined via a government proposal.

Users have the freedom to fund the pool with any token of their choice, for any supported chain and set the emission schedule for their funds. For instance, a user can fund the IPRPC pool for the Osmosis chain with 300ulava, which will be dispersed over a period of three months. It's important to note that the IPRPC pool will start receiving funds from the beginning of the upcoming month.

In order to fund the IPRPC pool, the user's funds must cover the monthly minimum IPRPC cost, a parameter determined by governance. This minimum IPRPC cost will be subtracted from the monthly emission.

Parameters

The rewards module contains the following parameters:

MinBondedTarget

MinBondedTarget is used to calculate the BondedTargetFactor. This is the percentage of stake vs token supply that above it, reduction in validators block rewards is done.

MaxBondedTarget

MaxBondedTarget is used to calculate the BondedTargetFactor. This is the percentage in which the validators block rewards reduction is capped and reaches LowFactor.

LowFactor

LowFactor is used to calculate the BondedTargetFactor. This is the linear reduction rate/slope of the validators block rewards.

LeftOverBurnRate

LeftOverBurnRate determines the percentage of tokens to burn before refilling the distribution rewards pool with the monthly quota (from the allocation pool). LeftOverBurnRate = 0 means there is no burn.

BondedTargetFactor

In Lava we wanted to make validator rewards decrease linearly with the increase in stake. The BondedTargetFactor encapsulates this behaviour.

To calculate the BondedTargetFactor see the following formula (note that the staking module's BondedRatio parameter is used, which is the fraction of the staking tokens which are currently bonded):

\text{BondedTargetFactor}= \\\begin{cases}
1 & \text{$\text{BondRatio} < \text{MinBonded}$}\\
\frac{\text{MaxBonded}-\text{BondRatio}}{\text{MaxBonded}-\text{MinBonded}} + (\text{LowFactor})\frac{\text{BondRatio}-\text{MinBonded}}{\text{MaxBonded}-\text{MinBonded}}  & \text{$\text{MinBonded} < \text{BondRatio} < \text{MaxBonded}$}\\
\text{LowFactor} & \text{$\text{BondRatio} > \text{MaxBonded}$}\\
\end{cases}

MaxRewardsBoost

MaxRewardsBoost is a multiplier that determines the maximum bonus for provider rewards from subscriptions.

ValidatorsSubscriptionParticipation

ValidatorsSubscriptionParticipation is used to calculate the providers rewards participation fees.

Queries

The rewards module supports the following queries:

Transactions

All the transactions below require setting the --from flag and gas related flags.

The rewards module supports the following transactions:

Please note that the coins specified in the fund-iprpc transaction is the monthly emission fund. For instance, if you specify a fund of 100ulava for a duration of three months, providers will receive 100ulava each month, not 33ulava.

Also, the coins must include duration*min_iprpc_cost of ulava tokens (min_iprpc_cost is shown with the show-iprpc-data query).

Proposals

The rewards module supports the set-iprpc-data proposal which set the minimum IPRPC cost and the IPRPC eligible subscriptions.

To send a proposal and vote use the following commands:

lavad tx gov submit-legacy-proposal set-iprpc-data <deposit> --min-cost 0ulava --add-subscriptions addr1,addr2 --remove-subscriptions addr3,addr4 --from alice <gas-flags>

lavad tx gov vote <latest_proposal_id> yes --from alice <gas-flags>

Events

The rewards module has the following events: