rewards

package
v0.34.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 9, 2024 License: Apache-2.0 Imports: 23 Imported by: 0

README

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.

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

Contents

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)}

Parameters

The rewards module contains the following parameters:

Key Type Default Value
MinBondedTarget math.LegacyDec 0.6
MaxBondedTarget math.LegacyDec 0.8
LowFactor math.LegacyDec 0.5
LeftOverBurnRate math.LegacyDec 1
MaxRewardsBoost uint64 5
ValidatorsSubscriptionParticipation math.LegacyDec 0.05
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:

Query Arguments What it does
block-reward none show the block reward for validators
pools none show the info of the distribution pools
params none shows the module's parameters

Transactions

The rewards module does not support any transactions.

Proposals

The rewards module does not support any proposals.

Events

The rewards module has the following events:

Event When it happens
distribution_pools_refill a successful distribution rewards pools refill
provider_bonus_rewards a successful distribution of provider bonus rewards

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BeginBlocker 

func BeginBlocker(ctx sdk.Context, k keeper.Keeper)

BeginBlocker calculates the validators block rewards and transfers them to the fee collector

func ExportGenesis 

func ExportGenesis(ctx sdk.Context, k keeper.Keeper) *types.GenesisState

ExportGenesis returns the capability module's exported genesis.

func InitGenesis 

func InitGenesis(ctx sdk.Context, k keeper.Keeper, genState types.GenesisState)

InitGenesis initializes the capability module's state from a provided genesis state.

func NewHandler 

func NewHandler(k keeper.Keeper) sdk.Handler

NewHandler ...

Types

type AppModule 

type AppModule struct {
	AppModuleBasic
	// contains filtered or unexported fields
}

AppModule implements the AppModule interface for the capability module.

func NewAppModule 

func NewAppModule(
	cdc codec.Codec,
	keeper keeper.Keeper,
	accountKeeper types.AccountKeeper,
	bankKeeper types.BankKeeper,
) AppModule

func (AppModule) BeginBlock 

func (am AppModule) BeginBlock(ctx sdk.Context, _ abci.RequestBeginBlock)

BeginBlock executes all ABCI BeginBlock logic respective to the capability module.

func (AppModule) ConsensusVersion 

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements ConsensusVersion.

func (AppModule) EndBlock 

func (am AppModule) EndBlock(_ sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate

EndBlock executes all ABCI EndBlock logic respective to the capability module. It returns no validator updates.

func (AppModule) ExportGenesis 

func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage

ExportGenesis returns the capability module's exported genesis state as raw JSON bytes.

func (AppModule) GenerateGenesisState 

func (AppModule) GenerateGenesisState(simState *module.SimulationState)

GenerateGenesisState creates a randomized GenState of the module

func (AppModule) InitGenesis 

func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, gs json.RawMessage) []abci.ValidatorUpdate

InitGenesis performs the capability module's genesis initialization It returns no validator updates.

func (AppModule) Name 

func (am AppModule) Name() string

Name returns the capability module's name.

func (AppModule) ProposalContents 

func (AppModule) ProposalContents(_ module.SimulationState) []simtypes.WeightedProposalMsg

ProposalContents doesn't return any content functions for governance proposals

func (AppModule) RegisterInvariants 

func (am AppModule) RegisterInvariants(_ sdk.InvariantRegistry)

RegisterInvariants registers the capability module's invariants.

func (AppModule) RegisterServices 

func (am AppModule) RegisterServices(cfg module.Configurator)

RegisterServices registers a GRPC query service to respond to the module-specific GRPC queries.

func (AppModule) RegisterStoreDecoder 

func (am AppModule) RegisterStoreDecoder(_ sdk.StoreDecoderRegistry)

RegisterStoreDecoder registers a decoder

func (AppModule) WeightedOperations 

func (am AppModule) WeightedOperations(simState module.SimulationState) []simtypes.WeightedOperation

WeightedOperations returns the all the gov module operations with their respective weights.

type AppModuleBasic 

type AppModuleBasic struct {
	// contains filtered or unexported fields
}

AppModuleBasic implements the AppModuleBasic interface for the capability module.

func NewAppModuleBasic 

func NewAppModuleBasic(cdc codec.BinaryCodec) AppModuleBasic

func (AppModuleBasic) DefaultGenesis 

func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage

DefaultGenesis returns the capability module's default genesis state.

func (AppModuleBasic) GetQueryCmd 

func (AppModuleBasic) GetQueryCmd() *cobra.Command

GetQueryCmd returns the capability module's root query command.

func (AppModuleBasic) GetTxCmd 

func (a AppModuleBasic) GetTxCmd() *cobra.Command

GetTxCmd returns the capability module's root tx command.

func (AppModuleBasic) Name 

func (AppModuleBasic) Name() string

Name returns the capability module's name.

func (AppModuleBasic) RegisterCodec 

func (AppModuleBasic) RegisterCodec(cdc *codec.LegacyAmino)

func (AppModuleBasic) RegisterGRPCGatewayRoutes 

func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux)

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the module.

func (AppModuleBasic) RegisterInterfaces 

func (a AppModuleBasic) RegisterInterfaces(reg cdctypes.InterfaceRegistry)

RegisterInterfaces registers the module's interface types

func (AppModuleBasic) RegisterLegacyAminoCodec 

func (AppModuleBasic) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)

func (AppModuleBasic) RegisterRESTRoutes 

func (AppModuleBasic) RegisterRESTRoutes(clientCtx client.Context, rtr *mux.Router)

RegisterRESTRoutes registers the capability module's REST service handlers.

func (AppModuleBasic) ValidateGenesis 

func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, config client.TxEncodingConfig, bz json.RawMessage) error

ValidateGenesis performs genesis state validation for the capability module.

Source Files

View all Source files

Directories

Path Synopsis
client
cli
Package types is a reverse proxy.
 Package types is a reverse proxy.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.