Skip to main content

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 poolincentives external-incentivized-gauges

::: details Example

osmosisd query poolincentives 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

:::