feat: finish incentive module

app/app.go

@@ -118,6 +118,9 @@ import (
 	appparams "github.com/umee-network/umee/v4/app/params"
 	"github.com/umee-network/umee/v4/swagger"
 	"github.com/umee-network/umee/v4/util/genmap"
+	"github.com/umee-network/umee/v4/x/incentive"
+	incentivekeeper "github.com/umee-network/umee/v4/x/incentive/keeper"
+	incentivemodule "github.com/umee-network/umee/v4/x/incentive/module"
 	"github.com/umee-network/umee/v4/x/leverage"
 	leveragekeeper "github.com/umee-network/umee/v4/x/leverage/keeper"
 	leveragetypes "github.com/umee-network/umee/v4/x/leverage/types"
@@ -175,6 +178,7 @@ func init() {
 		ibctransfer.AppModuleBasic{},
 		gravity.AppModuleBasic{},
 		leverage.AppModuleBasic{},
+		incentivemodule.AppModuleBasic{},
 		oracle.AppModuleBasic{},
 		bech32ibc.AppModuleBasic{},
 		uibcmodule.AppModuleBasic{},
@@ -198,6 +202,7 @@ func init() {
 		ibctransfertypes.ModuleName: {authtypes.Minter, authtypes.Burner},
 		gravitytypes.ModuleName:     {authtypes.Minter, authtypes.Burner},
 		leveragetypes.ModuleName:    {authtypes.Minter, authtypes.Burner},
+		incentive.ModuleName:        nil,
 		oracletypes.ModuleName:      nil,
 		uibc.ModuleName:             nil,
 	}
@@ -247,6 +252,7 @@ type UmeeApp struct {
 	IBCKeeper          *ibckeeper.Keeper // IBC Keeper must be a pointer in the app, so we can SetRouter on it correctly
 	GravityKeeper      gravitykeeper.Keeper
 	LeverageKeeper     leveragekeeper.Keeper
+	IncentiveKeeper    incentivekeeper.Keeper
 	OracleKeeper       oraclekeeper.Keeper
 	bech32IbcKeeper    bech32ibckeeper.Keeper
 	UIbcQuotaKeeper    uibcquotakeeper.Keeper
@@ -310,8 +316,8 @@ func New(
 		evidencetypes.StoreKey, capabilitytypes.StoreKey,
 		authzkeeper.StoreKey, nftkeeper.StoreKey, group.StoreKey,
 		ibchost.StoreKey, ibctransfertypes.StoreKey, gravitytypes.StoreKey,
-		leveragetypes.StoreKey, oracletypes.StoreKey, bech32ibctypes.StoreKey,
-		uibc.StoreKey,
+		leveragetypes.StoreKey, incentive.StoreKey, oracletypes.StoreKey,
+		bech32ibctypes.StoreKey, uibc.StoreKey,
 	}
 	if Experimental {
 		storeKeys = append(storeKeys, wasm.StoreKey)
@@ -454,6 +460,12 @@ func New(
 			app.OracleKeeper.Hooks(),
 		),
 	)
+	app.IncentiveKeeper = incentivekeeper.NewKeeper(
+		appCodec,
+		keys[incentive.StoreKey],
+		app.BankKeeper,
+		app.LeverageKeeper,
+	)
 
 	app.GravityKeeper = gravitykeeper.NewKeeper(
 		keys[gravitytypes.StoreKey],
@@ -626,6 +638,7 @@ func New(
 		ibctransfer.NewAppModule(ibcTransferKeeper),
 		gravity.NewAppModule(app.GravityKeeper, app.BankKeeper),
 		leverage.NewAppModule(appCodec, app.LeverageKeeper, app.AccountKeeper, app.BankKeeper),
+		incentivemodule.NewAppModule(appCodec, app.IncentiveKeeper, app.BankKeeper, app.LeverageKeeper),
 		oracle.NewAppModule(appCodec, app.OracleKeeper, app.AccountKeeper, app.BankKeeper),
 		bech32ibc.NewAppModule(appCodec, app.bech32IbcKeeper),
 		uibcmodule.NewAppModule(appCodec, app.UIbcQuotaKeeper),
@@ -655,6 +668,7 @@ func New(
 		paramstypes.ModuleName, vestingtypes.ModuleName,
 		// icatypes.ModuleName,  ibcfeetypes.ModuleName,
 		leveragetypes.ModuleName,
+		incentive.ModuleName,
 		oracletypes.ModuleName,
 		gravitytypes.ModuleName,
 		bech32ibctypes.ModuleName,
@@ -673,6 +687,7 @@ func New(
 		paramstypes.ModuleName, upgradetypes.ModuleName, vestingtypes.ModuleName,
 		// icatypes.ModuleName,
 		leveragetypes.ModuleName,
+		incentive.ModuleName,
 		gravitytypes.ModuleName,
 		bech32ibctypes.ModuleName,
 		uibc.ModuleName,
@@ -694,6 +709,7 @@ func New(
 
 		oracletypes.ModuleName,
 		leveragetypes.ModuleName,
+		incentive.ModuleName,
 		gravitytypes.ModuleName,
 		bech32ibctypes.ModuleName,
 		uibc.ModuleName,
@@ -709,6 +725,7 @@ func New(
 
 		oracletypes.ModuleName,
 		leveragetypes.ModuleName,
+		incentive.ModuleName,
 		gravitytypes.ModuleName,
 		bech32ibctypes.ModuleName,
 		uibc.ModuleName,
@@ -748,6 +765,7 @@ func New(
 		[]string{stakingtypes.ModuleName, authtypes.ModuleName, oracletypes.ModuleName},
 	)
 	// TODO: Ensure x/leverage implements simulator and add it here:
+	// TODO: same for incentive
 	simTestModules := genmap.Pick(simStateModules, []string{oracletypes.ModuleName})
 
 	app.StateSimulationManager = module.NewSimulationManagerFromAppModules(simStateModules, overrideModules)

proto/umee/incentive/v1/genesis.proto

@@ -42,25 +42,28 @@ message Bond {
 // RewardAccumulator for a tier and the last value at which the user updated bonds or claimed
 // tokens. Their pending rewards increase by only the rewards accrued in that time period.
 message RewardTracker {
-  string   account                                    = 1;
-  uint32   tier                                       = 2;
-  string   denom                                      = 3;
-  repeated cosmos.base.v1beta1.DecCoin reward_tracker = 4 [
+  string   account                             = 1;
+  uint32   tier                                = 2;
+  string   denom                               = 3;
+  repeated cosmos.base.v1beta1.DecCoin rewards = 4 [
     (gogoproto.nullable)     = false,
     (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.DecCoins"
   ];
 }
 
 // RewardAccumulator is a global reward tracking struct that indicates the amount
-// of rewards that a single unit of denom would have accumulated if it was bonded
-// at a given tier since genesis.
+// of rewards that a reference amount of a bonded uToken denom would have accumulated
+// if it was bonded at a given tier since genesis. To prevent rounding issues, the
+// reference amount is 10^exponent of the uToken's smallest possible amount, generally
+// matching the exponent of the associated base token registered with the leverage module.
 message RewardAccumulator {
-  uint32   tier                                       = 1;
-  string   denom                                      = 2;
-  repeated cosmos.base.v1beta1.DecCoin reward_tracker = 3 [
+  uint32   tier                                = 1;
+  string   denom                               = 2;
+  repeated cosmos.base.v1beta1.DecCoin rewards = 3 [
     (gogoproto.nullable)     = false,
     (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.DecCoins"
   ];
+  uint32 exponent = 4;
 }
 
 // Unbonding is a structure that tracks an in-progress token unbonding.
@@ -76,4 +79,4 @@ message AccountUnbondings {
   string             denom      = 2;
   uint32             tier       = 3;
   repeated Unbonding unbondings = 4 [(gogoproto.nullable) = false];
-}
+}

x/incentive/README.md

@@ -0,0 +1,9 @@
+# Incentive Module
+
+## Abstract
+
+This document specifies the `x/incentive` module of the Umee chain.
+
+The incentive module allows users to `Bond` collateral `uTokens` from the `x/leverage` module, and governance to create and fund `Incentive Programs` which distribute rewards to users with bonded uTokens over time. Users can `Unbond` tokens over a period of time, after which they can be withdrawn. Unbonding time (and reward amounts) depend on which of the three `Unbonding Tiers` uTokens were bonded to.
+
+The incentive module depends on the `x/leverage` module for information about users' bonded collateral, and also requires that the leverage module prevent bonded or currently unbonding collateral from being withdrawn. There are also a few more advanced interactions, such as instantly unbonding collateral when it is liquidated, and registering an `exponent` when a uToken denom is incentivized for the first time.

x/incentive/errors.go

@@ -34,6 +34,7 @@ var (
 	ErrInsufficientCollateral = errors.Register(ModuleName, 404, "insufficient collateral to create bond")
 
 	// 5XX = Misc
-	ErrDecreaseNextProgramID  = errors.Register(ModuleName, 500, "cannot decrease NextProgramID")
-	ErrDecreaseLastRewardTime = errors.Register(ModuleName, 501, "cannot decrease LastRewardTime")
+	ErrDecreaseNextProgramID     = errors.Register(ModuleName, 500, "cannot decrease NextProgramID")
+	ErrDecreaseLastRewardTime    = errors.Register(ModuleName, 501, "cannot decrease LastRewardTime")
+	ErrChangeAccumulatorExponent = errors.Register(ModuleName, 502, "cannot change RewardAccumulator.Exponent once set")
 )

x/incentive/expected_keepers.go

@@ -17,8 +17,6 @@ type BankKeeper interface {
 
 // LeverageKeeper defines the expected x/leverage keeper interface.
 type LeverageKeeper interface {
-	GetCollateralAmount(ctx sdk.Context, borrowerAddr sdk.AccAddress, denom string) sdk.Coin
-	IsAcceptedUToken(ctx sdk.Context, uTokenDenom string) bool
-	AssertNotBlacklisted(ctx sdk.Context, denom string) error
+	GetCollateral(ctx sdk.Context, borrowerAddr sdk.AccAddress, denom string) sdk.Coin
 	// TODO: hooks
 }

x/incentive/genesis.go

@@ -34,17 +34,17 @@ func NewGenesisState(
 	}
 }
 
-// DefaultGenesisState returns the default genesis state
-func DefaultGenesisState() *GenesisState {
+// DefaultGenesis returns the default genesis state
+func DefaultGenesis() *GenesisState {
 	return &GenesisState{
 		Params:          DefaultParams(),
 		NextProgramId:   1,
 		LastRewardsTime: 0,
 	}
 }
 
-// ValidateGenesis checks a genesis state for basic issues
-func ValidateGenesis(_ GenesisState) error {
+// Validate checks a genesis state for basic issues
+func (gs GenesisState) Validate() error {
 	// TODO #1749
 	return nil
 }
@@ -101,19 +101,20 @@ func NewTotalBond(tier uint32, coin sdk.Coin) Bond {
 // NewRewardTracker creates the RewardTracker struct used in GenesisState
 func NewRewardTracker(addr, denom string, tier uint32, coins sdk.DecCoins) RewardTracker {
 	return RewardTracker{
-		Account:       addr,
-		Denom:         denom,
-		Tier:          tier,
-		RewardTracker: coins,
+		Account: addr,
+		Denom:   denom,
+		Tier:    tier,
+		Rewards: coins,
 	}
 }
 
 // NewRewardAccumulator creates the RewardAccumulator struct used in GenesisState
-func NewRewardAccumulator(denom string, tier uint32, coins sdk.DecCoins) RewardAccumulator {
+func NewRewardAccumulator(denom string, tier, exponent uint32, coins sdk.DecCoins) RewardAccumulator {
 	return RewardAccumulator{
-		Denom:         denom,
-		Tier:          tier,
-		RewardTracker: coins,
+		Denom:    denom,
+		Tier:     tier,
+		Exponent: exponent,
+		Rewards:  coins,
 	}
 }