Version: v0.19

Incentives Module

Module Overview

The Incentives module enables the incentivization of token holders who participate in specific aspects of the system. It allows governance to configure incentive pools for tokens. Token holders can bond their tokens to these pools to earn incentives, which may come from multiple sources, such as minted native tokens or external incentives. The module provides flexibility in determining the types of tokens that can be used as rewards for each pool, facilitating dual incentives.

Concepts

Incentive Pool

An "incentive pool" is a mechanism for encouraging token holders to participate in a protocol. Governance can establish a pool for a particular token, enabling users to bond their tokens and receive incentives. Each pool caters to a single bond token but can receive incentives from multiple denominations. Governance can specify a list of reward tokens when creating the pool, and additional reward tokens can be appended later. The pools are structured as follows:

message Pool {
  cosmos.base.v1beta1.Coin bonded_token = 1 [(gogoproto.nullable) = false];
  repeated PoolRewardToken rewards = 2 [(gogoproto.nullable) = false];
}

message PoolRewardToken {
  string denom = 1;
  string amount = 2 [
    (cosmos_proto.scalar) = "cosmos.Int",
    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
    (gogoproto.nullable) = false
  ];
  string global_index = 3 [
    (cosmos_proto.scalar) = "cosmos.Dec",
    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
    (gogoproto.nullable) = false
  ];
  string weight = 4 [
    (cosmos_proto.scalar) = "cosmos.Dec",
    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
    (gogoproto.nullable) = false
  ];
}

Here, bonded_token represents the denomination and total bonded amount of the bond token, while rewards is a list of permitted reward denominations with the following properties:

denom represents the denomination of the reward token.
amount represents the accumulated yet unpaid reward.
global_index is an index tracking accumulated rewards, used for calculating each user's share.
weight signifies the token's weight, currently used only for distributing mint module incentives. The weight of each reward token can be updated through governance proposals.

Rewards can be sent to any pool, provided the sent denominations are listed as reward tokens for that pool. The mint module's mint denom, the chain's primary native coin, can also be used to pay incentives to pools at the end of each mint epoch, based on their weight. Pools with a non-zero weight of the minted denomination and a non-zero bonded amount receive a portion of the mint incentives proportional to their weight. The total incentives sent to the Incentives module are controlled in the Mint module.

This dual incentivization strategy can incentivize LP holders of AMM pools. The incentive pool concept promotes the targeted incentivization of specific user behaviors, aligning token holders' interests with the protocol's success, and stimulating adoption and engagement.

When a reward is paid to a pool, the corresponding reward token is updated to reflect the new rewards. Specifically, the global_index and amount of the reward token are adjusted as follows:

The global_index is updated using the formula:

I^g_n = I^g_o + \frac{R}{B},

$I_o^g$ represents the global index prior to the operation, B refers to the total bonded amount of the pool, and $R$ is the newly accrued reward added to the pool. The resultant $I_n^g$ is the updated global index of the token.

The amount is refreshed by adding the newly accrued reward to the existing value.

In essence, these updates ensure that the reward token mirrors the rewards accrued by the pool, which can then be distributed to the rightful users. Notably, when a reward token is instantiated for the first time, its global index is set at $1$ and the amount at $0$ .

Bond

As noted earlier, a system may contain multiple incentive pools. When a user binds tokens to a pool, a bond object is generated with the following structure:

message Bond {
  string address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
  cosmos.base.v1beta1.Coin token = 2 [(gogoproto.nullable) = false];
  repeated BondRewardToken rewards = 3 [(gogoproto.nullable) = false];
}

message BondRewardToken {
  string denom = 1;
  string pending_amount = 2 [
    (cosmos_proto.scalar) = "cosmos.Int",
    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
    (gogoproto.nullable) = false
  ];
  string user_index = 3 [
    (cosmos_proto.scalar) = "cosmos.Dec",
    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
    (gogoproto.nullable) = false
  ];
}

The address field stores the user's address, while the token field records the bonded amount and its denomination. The rewards property maintains the user's state for each reward denomination of the pool. The pending_amount indicates the quantity of pending rewards, and the user_index is employed to calculate the user's share of the reward for the bond.

Whenever a user bonds or unbonds tokens, or claims rewards, the reward tokens are adjusted accordingly. For each reward token, the properties are updated as follows:

The pending_amount is modified using the formula:

P_{n} = P_{o} + (I^g - I^u_{o})\times B_o,

Here, $P_o$ , $I^u_o$ , and $B_o$ represent the pending_amount, user_index, and the user's bonded amount prior to the operation, respectively. The resultant $P_n$ is the refreshed pending_amount. This formula incorporates the global_index $I^g$ of the reward token in the pool, ensuring that the user's rewards are proportional to their stake in the pool.

The user_index is updated to the global_index of the reward token in the pool.

Following these updates, for unbond and claimReward operations, the pending_amount is disbursed to the user and then reset to zero. It's key to note that distributing the reward also reduces the reward quantity in the pool data.

It's crucial to remember that if a new reward token is added to a pool, all bonds established prior to the addition would not immediately have the new reward token in their data. In such scenarios, $I_o^u = 1$ and $P_o = 0$ are used in the computations, as the user was in the pool when the new token was added and therefore receives the initial index.

Unbonding

As outlined in the previous section, when a user opts to unbond an amount from a pool, the amount is deducted from their bonded sum and the rewards are updated and paid accordingly. However, the unbonded amount may not be immediately accessible to the user due to an UnbondingPeriod, during which the user must wait before claiming the unbonded amount. It's important to note that even though the amount isn't instantly transferred to the user, it is indeed withdrawn from the pool and is no longer eligible for rewards during the unbonding period. The unbonding period length, a parameter adjustable via governance, can also be set to zero. In this scenario, users can either choose to automatically receive the unbonded amount in the same message execution, or defer the claim to a separate message. Regardless of the unbonding period length, an unbonding request may create a record with the following properties:

message Unbonding {
  uint64 id = 1;
  google.protobuf.Timestamp completion_time = 2 [
    (gogoproto.nullable) = false,
    (gogoproto.stdtime) = true
  ];
  string address = 3;
  string treasury_address = 4;
  cosmos.base.v1beta1.Coin amount = 5 [(gogoproto.nullable) = false];
  bool auto_claim = 6;
}

id: Auto-generated identifier for the unbonding instance.
completion_time: The sum of the unbonding period and the block time of the unbond request.
address: User address of the bond.
treasury_address: Address for the amount to be paid after the unbonding period ends and the unbonding is claimed.
amount: Unbonding amount to be claimed.
auto_claim: Determines whether this unbonding should be automatically claimed when the unbonding period ends, or if it should be manually claimed by the user.

Auto-claim instances are added to a queue (sorted by completion-time) for automatic claiming once the unbonding period completes.

Users can also cancel unbondings at any time. This feature allows users to re-bond the entire amount or a portion of it back to the pool without waiting for the unbonding period to end. Any remaining amount in the unbonding will be claimable at the completion time.

Transitions

End Block

Users may not have immediate access to unbonded amounts at the unbond time. They must wait for the unbonding period to claim their tokens. However, users can opt for the auto-claim feature that automatically transfers tokens to the designated address upon the completion of the unbonding period.

To implement the auto-claim feature, a queue of unbondings (sorted by completion time) is maintained. At the end of each block, unbondings with a completion time less than the block time are iterated over and claimed, transferring the tokens to the selected address.

Message

MsgUpdateParams

This message can be used to update module parameters through governance.

message MsgUpdateParams {
  string authority = 1;
  Params params = 2 [(gogoproto.nullable) = false];
}
message MsgUpdateParamsResponse {}

MsgCreatePool

A new pool for a bond denomination can be created using this message, with a list of reward tokens. The reward tokens can have a weight, which is currently used for mint distribution.

message MsgCreatePool {
  string authority = 1;
  string bond_denom = 2;
  repeated WeightedRewardToken reward_tokens = 3 [(gogoproto.nullable) = false];
}
message WeightedRewardToken {
  string denom = 1;
  // weight is used for reward portion for each pool, when a reward is
  // accrued from dist module, it will be distributed to each pool according to the weights
  string weight = 2 [
    (cosmos_proto.scalar) = "cosmos.Dec",
    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
    (gogoproto.nullable) = false
  ];
}
message MsgCreatePoolResponse {}

MsgUpdateRewardTokenWeight

This message enables the governance to adjust a reward token's weight in a pool.

message MsgUpdateRewardTokenWeight {
  string authority = 1;
  string bond_denom = 2;
  WeightedRewardToken reward_token = 3 [(gogoproto.nullable) = false];
}

message MsgUpdateRewardTokenWeightResponse {}

MsgAddRewardTokenToPool

This message permits the addition of a new reward token to a pool via governance.

message MsgAddRewardTokenToPool {
  string authority = 1;
  string bond_denom = 2;
  WeightedRewardToken reward_token = 3 [(gogoproto.nullable) = false];
}

message MsgAddRewardTokenToPoolResponse {}

MsgBond

This message allows users to bond tokens to a pool. The response includes the actual bond object. If a bond for the given denomination already exists, it's updated and the revised instance, containing the total bond and rewards, is returned.

message MsgBond {
  string creator = 1;
  cosmos.base.v1beta1.Coin amount = 2 [(gogoproto.nullable) = false];
}

message MsgBondResponse {
  Bond bond = 1 [(gogoproto.nullable) = false];
}

CLI command:

pryzmd tx incentives bond [amount]

MsgClaimReward

This message enables users to claim their accumulated rewards for a specific bond denomination. The rewards are sent to the provided treasury address. The response includes the claimed reward coins.

message MsgClaimReward {
  string creator = 1;
  string bond_denom = 2;
  string treasury = 3;
}

message MsgClaimRewardResponse {
  repeated cosmos.base.v1beta1.Coin rewards = 1 [(gogoproto.nullable) = false];
}

CLI command:

pryzmd tx incentives claim-reward [bond-denom] [treasury]

MsgUnbond

This message allows users to unbond tokens from a pool. The unbonded amount is sent to the unbond_treasury and the accumulated rewards are sent to the reward_treasury. Setting auto_claim to true enables automatic claiming of the unbonded amount after the unbonding period. The response includes the unbonding instance, if applicable. If the unbonding period is zero and auto_claim is true, no unbonding is created and the amount is sent instantly. The rewards are also included in the response.

message MsgUnbond {
  string creator = 1;
  cosmos.base.v1beta1.Coin amount = 2 [(gogoproto.nullable) = false];
  string unbond_treasury = 3;
  string reward_treasury = 4;
  bool auto_claim = 5;
}

message MsgUnbondResponse {
  Unbonding unbonding = 1;
  repeated cosmos.base.v1beta1.Coin rewards = 2 [
    (gogoproto.nullable) = false,
    (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"
  ];
}