Create an Active Participation and Engagement incentive module

[iramiller]

Summary

Create a new blockchain module that performs epoch based rewards distribution using a configurable share from the community pool to an eligible pool of addresses based on their on-chain activities during the period.

Problem Definition

One of the major challenges for a growing blockchain is the distribution of incentives to the right collection of accounts to drive interest and engagement in the platform. While a proof of stake blockchain typically has a comprehensive distribution system based on delegations, this rewards system primarily benefits passive participation. The Incentive module design targets active network participants for reward distribution by monitoring their activities and allocating distribution shares accordingly.

Proposal

Create an Incentive module that supports distribution of rewards per epoch using shares. The module should be built in a way that is extensible and flexible for different distribution strategies.

Any account can create a new incentive program by providing funding and a set of configuration that includes the epochs to fund over, eligibility criteria, and a list of activity detectors and their weights.

In addition to direct funding through creation of incentive programs a community funding program can be configured via governance control which uses the community funding pool as a source of funds to distribute.

End Block Processing

The processing pipeline of the module end block should be based on 4 stages:

1. Determine the incentive opportunity detectors to use for the current epoch
2. Identify events within the event manager history (Add support for event data injection into end block handlers #626) that represent incentive opportunities for an address, include a distribution weight factor and a source pool
3. For each incentive opportunity, filter based on eligibility criteria required for the incentive.
4. Update the epoch shares distribution for each address

At the end of a given epoch the module should determine the total funds to distribute from each funding source and split these amounts across the total number of shares allocated in the period (share-value). Using this share-value the module should send a payment to each address in the amount of ( shares-accrued * share-value ). When this is complete the epoch records should be cleared in preparation for the next period.

Basic Parameters (Governance Control)

• Epoch duration (blocks) - This is the length of the repeating epoch period measured in blocks
• Community pool accrual tax rate - This is the share of the accrued community funds to collected during the epoch to distribution (as a percentage)

Incentives

Governance proposals should be used to configure the incentive opportunities available for a given epoch. Incentive opportunities have a defined period, eligibility criteria, and funding source.

Eligibility criteria examples

• Account has transactions during period
• Account has active delegations (threshold?)
• Account maintains a balance of funds

Example 1.

The community pool funds are allocated for a perpetual incentive program. At the start of a given epoch the amount of funds within the community pool are recorded. At the end of the epoch the accrued funds during the period are computed, this amount is split based on the community pool tax rate to result in a funding amount for distribution.

• During the course of the epoch at the end of each block the events of the block are processed against a list of incentive-opportunity detectors. The list of these detectors is kept in the configuration for the community distribution (`opp1, opp2, opp5, etc).
• The results of these detections are a pairs of address, shares. These pairs are filtered by processing against a list of eligibility criteria functions, again by name min-balance, delegation-amounts, etc.
• Remaining address, share amounts after the eligibility filters have been applied are recorded, any existing share amounts are summed with the new share
• At the end of the epoch the funding will be distributed the funding equally across each share with each address being paid out according to the number of shares accrued.

Example 2.

A user with 100M in token decides to create an incentive for relaying IBC transactions. They submit a new incentive program request with their funding and include eligibility criteria of "records IBC tx". During the course of the epoch each time an address records a transaction relay they will accrue a share of the incentive pool. At the end of the epoch the total funding divided by the number of epochs the program runs will result in an allocation that is distributed to each eligible address based on their share.

In this way 100M token could be split across 100 epochs such that the relayers are paid a portion of the 1M per epoch according to their contribution as a share of the relayed transactions they recorded.

Example 3.

A validator incentive program is defined as a validator being online during a period with a minimal amount of downtime allowed. If the epoch is 1000 blocks long then a simple incentive-opportunity detector can be defined with a negative weight greater than 1000 that occurs if the downtime fault is detected. At the end of the epoch if the share count for an address is greater than zero the validator address gets paid, otherwise their reward is forfeit.

Sub-tasks

• Create Reward Module
  • CLI
    • (Dev task) Rewards Module MsgServer implementation and corresponding keeper methods #745
    • (Dev task) Rewards Module QueryServer implementation and corresponding keeper methods #746
    • (DEV Task) Rewards Module reward program tx #811
    • (DEV TASK) Create a query that can inform users about their claims. #967
    • (DEV TASK) Claim transaction at address level. #968
  • Protos
    • (Dev Task) Define initial set of proto's for Rewards module #750
  • State Management
    • (DEV Task) Reward Program Implement Time Management #851
    • (DEV Task) Reward Program Pool Balance Entity #828
    • (DEV Task) Reward Program Fund Rollover #919
    • (DEV Task) Reward Program Expiration #920
    • (Dev task) Rewards Module Grant Rewards/Shares #923
    • (DEV TASK) create a tx to end a reward program immediately after it has started #965
    • (DEV TASK) Add additional emitted events for state transitions #969
  • Event Detection
    • (DEV Task) Reward Program Implement and Integrate DelegateAction #829
    • (DEV Task) Reward Program TransferAction #921
    • Reward Program VoteAction #922
  • Other
    • (Dev task) Create Basic Keeper Export/Import Genesis for Rewards module and corresponding keeper methods #743
    • (Dev task) Rewards Module emit reward events #925
    • (Dev task) Rewards Module Documentation #926
    • (Dev task) Rewards Module Upgrade Handler #927
    • (DEV TASK) Fix proto linter errors #986
    • (DEV TASK) Investigate non-determinism of events reported on cosmos sdk #985
• Update cosmos
  • Add support for event data injection into end block handlers #626
  • (Dev Task) Create Cosmos SDK fork to get event history in End block methods #744
• Clean up
  • (DEV Task) Reward Program Cleanup Epoch Module Remnants #830
  • (Dev task) Clean up protos and rename fields #924
• Deprecated
  • (Dev task) Create epoch module to track incentive rewards  #710
  • (Dev task) Set up hooks for epoch module and rewards module, to indicate epoch starts/end #752
  • (DEV Task) Rewards Module reward program proposal #787
• Future
  • (DEV Task) Reward Program Implement Reward Program Cleanup #852
• Testing
  • (Dev task) Create bash script for Rewards Module Integration testing #943
  • (Dev task) Create sim app test for rewards module #946
  • (Dev task) Create Integration tests in Kotlin using new proto for rewards module #947
  • (DEV TASK) Create unit tests #955
• Documentation

---

For Admin Use

• Not duplicate issue
• Appropriate labels applied
• Appropriate contributors tagged
• Contributor assigned/self-assigned

[iramiller]

Given the Epoch duration will need to be adjustable to optimize the processing time and data accrued it is reasonable to presume that reward shares will need to have a lifecycle independent of the epochs...

For example if an address earn a share that share may have a lifespan of 100,000 blocks while the epochs may have a duration of 1000 blocks for performance purposes.

As a related constraint the number of shares or the total benefit rewards might be subject to limits to prevent a few addresses from claiming an outsized amount of the reward pool due to limited participation (for example early in the program) or an outsized amount of activity that might result from spamming the network with transactions.