pool_incentives

package
v25.2.0 Latest Latest
Warning

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

 Go to latest Published: Jun 28, 2024 License: Apache-2.0 Imports: 19 Imported by: 0

README

Pool Incentives

Abstract

The pool-incentives module is separate but related to the incentives module. When a pool is created using the GAMM module, the pool-incentives module automatically creates individual gauges in the incentives module for every lock duration that exists in that pool. The pool-incentives module also takes the pool_incentives distributed from the gov module and distributes it to the various incentivized gauges.

Contents

  1. Concept
  2. State
  3. Governance
  4. Transactions
  5. Queries

Concepts

The purpose of the pool incentives module is to distribute incentives to a pool's LPs. This assumes that pool's follow the interface from the x/gamm module

Pool incentives module doesn't directly distribute the rewards to the LPs. When a pool is created, the pool incentives module creates a gauge in the incentives module for every lock duration that exists. Also, the pool incentives module takes a part of the minted inflation from the mint module, and automatically distributes it to the various selected gauges.

State

Genesis states
type GenesisState struct {
 // params defines all the parameters of the module.
 Params            Params          
 LockableDurations []time.Duration 
 DistrInfo         *DistrInfo      
}

type Params struct {
 // minted_denom is the denomination of the coin expected to be minted
 //  by the minting module.
 // Pool-incentives module doesn’t actually mint the coin itself, 
 // but rather manages the distribution of coins that matches the defined minted_denom.
 MintedDenom string 
 // allocation_ratio defines the proportion of the minted minted_denom 
 // that is to be allocated as pool incentives.
 AllocationRatio github_com_cosmos_cosmos_sdk_types.Dec 
}

Lockable durations can be set to the pool incentives module at genesis. Every time a pool is created, the pool incentives module creates the same amount of 'gauge' as there are lockable durations for the pool.

Also in regards to the Params, when the mint module mints new tokens to the fee collector at Begin Block, the pool incentives module takes the token which matches the 'minted denom' from the fee collector. Tokens are taken according to the 'allocationRatio', and are distributed to each DistrRecord of the DistrInfo. For example, if the fee collector holds 1000uatom and 2000 uosmo at Begin Block, and Params' mintedDenom is set to uosmo, and AllocationRatio is set to 0.1, 200uosmo will be taken from the fee collector and distributed to the DistrRecords.

Gov

Pool Incentives module uses the values set at genesis or values added by chain governance to distribute part of the inflation minted by the mint module to specified gauges.

type DistrInfo struct {
 TotalWeight github_com_cosmos_cosmos_sdk_types.Int 
 Records     []DistrRecord                          
}

type DistrRecord struct {
 GaugeId  uint64                                 
 Weight github_com_cosmos_cosmos_sdk_types.Int 
}

DistrInfo internally manages the DistrRecord and total weight of all DistrRecord. Governance can modify DistrInfo via UpdatePoolIncentivesProposal proposal.

UpdatePoolIncentivesProposal
type UpdatePoolIncentivesProposal struct {
 Title       string       
 Description string      
 Records     []DistrRecord 
}

UpdatePoolIncentivesProposal can be used by governance to update DistrRecords.

osmosisd tx gov submit-proposal update-pool-incentives [gaugeIds] [weights]

Proposals can be proposed in using the CLI command format above.
For example, to designate 100 weight to gauge id 2 and 200 weight to gauge id 3, the following command can be used.

osmosisd tx gov submit-proposal update-pool-incentives 2,3 100,200

Transactions

replace-pool-incentives
osmosisd tx poolincentives replace-pool-incentives [gaugeIds] [weights] [flags]

::: details Example

Fully replace records for pool incentives:

osmosisd tx poolincentives replace-pool-incentives proposal.json --from --chain-id

The proposal.json would look as follows:

{
  "title": "Pool Incentive Adjustment",
  "description": "Adjust pool incentives",
  "records": [
    {
      "gauge_id": "0",
      "weight": "100000"
    },
    {
      "gauge_id": "1",
      "weight": "1766249"
    },
    {
      "gauge_id": "XXX",
      "weight": "XXXXXXXX"
    },
    ...
  ]
}

:::

update-pool-incentives

Update the weight of specified pool gauges in regards to their share of incentives (by creating a proposal)

osmosisd tx poolincentives update-pool-incentives [gaugeIds] [weights] [flags] --from --chain-id

::: details Example

Update the pool incentives for gauge_id 0 and 1:

osmosisd tx gov submit-proposal update-pool-incentives proposal.json --from WALLET_NAME --chain-id CHAIN_ID

The proposal.json would look as follows:

{
  "title": "Pool Incentive Adjustment",
  "description": "Adjust pool incentives",
  "records": [
    {
      "gauge_id": "0",
      "weight": "100000"
    },
    {
      "gauge_id": "1",
      "weight": "1766249"
    },
  ]
}

:::

Queries

distr-info

Query distribution info for all pool gauges

osmosisd query poolincentives distr-info

::: details Example

osmosisd query poolincentives distr-info

An example output:

  - gauge_id: "1877"
    weight: "60707"
  - gauge_id: "1878"
    weight: "40471"
  - gauge_id: "1897"
    weight: "1448"
  - gauge_id: "1898"
    weight: "869"
  - gauge_id: "1899"
    weight: "579"
...

:::

external-incentivized-gauges

Query externally incentivized gauges (gauges distributing rewards on top of the normal OSMO rewards)

osmosisd query pool-incentives external-incentivized-gauges

::: details Example

osmosisd query pool-incentives external-incentivized-gauges

An example output:

- coins:
  - amount: "596400000"
    denom: ibc/0EF15DF2F02480ADE0BB6E85D9EBB5DAEA2836D3860E9F97F9AADE4F57A31AA0
  distribute_to:
    denom: gamm/pool/562
    duration: 604800s
    lock_query_type: ByDuration
    timestamp: "1970-01-01T00:00:00Z"
  distributed_coins:
  - amount: "596398318"
    denom: ibc/0EF15DF2F02480ADE0BB6E85D9EBB5DAEA2836D3860E9F97F9AADE4F57A31AA0
  filled_epochs: "28"
  id: "1791"
  is_perpetual: false
  num_epochs_paid_over: "28"
  start_time: "1970-01-01T00:00:00Z"
- coins:
  - amount: "1000000"
    denom: ibc/46B44899322F3CD854D2D46DEEF881958467CDD4B3B10086DA49296BBED94BED
  distribute_to:
    denom: gamm/pool/498
    duration: 86400s
    lock_query_type: ByDuration
    timestamp: "1970-01-01T00:00:00Z"
  distributed_coins:
  - amount: "999210"
    denom: ibc/46B44899322F3CD854D2D46DEEF881958467CDD4B3B10086DA49296BBED94BED
  filled_epochs: "2"
  id: "1660"
  is_perpetual: false
  num_epochs_paid_over: "2"
  start_time: "2021-10-14T16:00:00Z"
...

:::

gauge-ids

Query the gauge ids (by duration) by pool id

osmosisd query poolincentives gauge-ids [pool-id] [flags]

::: details Example

Find out what the gauge IDs are for pool 1:

osmosisd query poolincentives gauge-ids 1

An example output:

gauge_ids_with_duration:
- duration: 86400s
  gauge_id: "1"
- duration: 604800s
  gauge_id: "2"
- duration: 1209600s
  gauge_id: "3"

In this example, we see that gauge IDs 1,2, and 3 are for the one day, one week, and two week lockup periods respectively for the OSMO/ATOM pool. :::

incentivized-pools

Query all incentivized pools with their respective gauge IDs and lockup durations

osmosisd query poolincentives incentivized-pools [flags]

::: details Example

osmosisd query poolincentives incentivized-pools

An example output:

- gauge_id: "1897"
  lockable_duration: 86400s
  pool_id: "602"
- gauge_id: "1898"
  lockable_duration: 604800s
  pool_id: "602"
- gauge_id: "1899"
  lockable_duration: 1209600s
  pool_id: "602"
...

:::

lockable-durations

Query incentivized lockup durations

osmosisd query poolincentives lockable-durations [flags]

::: details Example

osmosisd query poolincentives lockable-durations

An example output:

lockable_durations:
- 86400s
- 604800s
- 1209600s

:::

params

Query pool-incentives module parameters

osmosisd query poolincentives params [flags]

::: details Example

osmosisd query poolincentives params

An example output:

params:
  minted_denom: uosmo

:::

Documentation

Overview

The `pool-incentives` module automatically creates individual gauges in the `incentives` module for every lock duration that exists in that pool. The `pool-incentives` module also takes the `pool_incentives` distributed from the `gov` module and distributes it to the various incentivized gauges.

  • Handles governance proposals impacting pool incentives.
  • Pool distribution and lockup infos queries.
  • Distributes incentives to LPs.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewPoolIncentivesProposalHandler 

func NewPoolIncentivesProposalHandler(k keeper.Keeper) govtypesv1.Handler

NewPoolIncentivesProposalHandler is a handler for governance proposals on new pool incentives.

Types

type AppModule 

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

func NewAppModule 

func NewAppModule(keeper keeper.Keeper) AppModule

func (AppModule) BeginBlock 

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

BeginBlock performs a no-op.

func (AppModule) ConsensusVersion 

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements AppModule/ConsensusVersion.

func (AppModule) EndBlock 

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

EndBlock returns the end blocker for the pool-incentives module. It returns no validator updates.

func (AppModule) ExportGenesis 

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

ExportGenesis returns the exported genesis state as raw bytes for the mint module.

func (AppModule) GenerateGenesisState 

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

GenerateGenesisState creates a randomized GenState of the pool-incentives module.

func (AppModule) InitGenesis 

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

InitGenesis performs genesis initialization for the pool-incentives module.

func (AppModule) ProposalContents 

func (AppModule) ProposalContents(simState module.SimulationState) []simtypes.WeightedProposalContent

ProposalContents doesn't return any content functions for governance proposals.

func (AppModule) ProposalMsgs 

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

UNFORKINGNOTE: Implement simulated gov proposal ProposalMsgs doesn't return any content functions for governance proposals

func (AppModule) QuerierRoute 

func (AppModule) QuerierRoute() string

QuerierRoute returns the pool-incentives module's querier route name.

func (AppModule) RegisterInvariants 

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

RegisterInvariants registers the pool-incentives module invariants.

func (AppModule) RegisterServices 

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

func (AppModule) RegisterStoreDecoder 

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

RegisterStoreDecoder registers a decoder for supply module's types.

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

func (AppModuleBasic) DefaultGenesis 

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

DefaultGenesis returns default genesis state as raw bytes for the pool-incentives module.

func (AppModuleBasic) GetQueryCmd 

func (b AppModuleBasic) GetQueryCmd() *cobra.Command

func (AppModuleBasic) GetTxCmd 

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

func (AppModuleBasic) Name 

func (AppModuleBasic) Name() string

Name returns the pool-incentives module's name.

func (AppModuleBasic) RegisterGRPCGatewayRoutes 

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

--------------------------------------- Interfaces.

func (AppModuleBasic) RegisterInterfaces 

func (AppModuleBasic) RegisterInterfaces(registry codectypes.InterfaceRegistry)

RegisterInterfaces registers interfaces and implementations of the pool-incentives module.

func (AppModuleBasic) RegisterLegacyAminoCodec 

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

RegisterLegacyAminoCodec registers the pool-incentives module's types on the LegacyAmino codec.

func (AppModuleBasic) ValidateGenesis 

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

ValidateGenesis performs genesis state validation for the pool-incentives module.

Source Files

View all Source files

Directories

Path Synopsis
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.