Add Initialize/Synchronize Claim methods (#1383)

* Add init/sync claim methods

* Add todo

* Make GetSynchronizedClaim method todo

* Remove GetSynchronizedClaim

Work moved to different task

* Update GetRewardIndexesOfClaimType method

x/incentive/keeper/rewards.go

@@ -0,0 +1,88 @@
+package keeper
+
+import (
+	"fmt"
+
+	sdk "github.com/cosmos/cosmos-sdk/types"
+	"github.com/kava-labs/kava/x/incentive/types"
+)
+
+// InitializeClaim creates a new claim with zero rewards and indexes matching
+// the global indexes. If the claim already exists it just updates the indexes.
+func (k Keeper) InitializeClaim(
+	ctx sdk.Context,
+	claimType types.ClaimType,
+	sourceID string,
+	owner sdk.AccAddress,
+) {
+	claim, found := k.GetClaim(ctx, claimType, owner)
+	if !found {
+		claim = types.NewClaim(claimType, owner, sdk.Coins{}, nil)
+	}
+
+	globalRewardIndexes, found := k.GetRewardIndexesOfClaimType(ctx, claimType, sourceID)
+	if !found {
+		globalRewardIndexes = types.RewardIndexes{}
+	}
+
+	claim.RewardIndexes = claim.RewardIndexes.With(sourceID, globalRewardIndexes)
+	k.SetClaim(ctx, claim)
+}
+
+// SynchronizeClaim updates the claim object by adding any accumulated rewards
+// and updating the reward index value.
+func (k Keeper) SynchronizeClaim(
+	ctx sdk.Context,
+	claimType types.ClaimType,
+	sourceID string,
+	owner sdk.AccAddress,
+	shares sdk.Int,
+) {
+	claim, found := k.GetClaim(ctx, claimType, owner)
+	if !found {
+		return
+	}
+
+	claim = k.synchronizeClaim(ctx, claim, sourceID, owner, shares)
+	k.SetClaim(ctx, claim)
+}
+
+// synchronizeClaim updates the reward and indexes in a claim for one sourceID.
+func (k *Keeper) synchronizeClaim(
+	ctx sdk.Context,
+	claim types.Claim,
+	sourceID string,
+	owner sdk.AccAddress,
+	shares sdk.Int,
+) types.Claim {
+	globalRewardIndexes, found := k.GetRewardIndexesOfClaimType(ctx, claim.Type, sourceID)
+	if !found {
+		// The global factor is only not found if
+		// - the pool has not started accumulating rewards yet (either there is no reward specified in params, or the reward start time hasn't been hit)
+		// - OR it was wrongly deleted from state (factors should never be removed while unsynced claims exist)
+		// If not found we could either skip this sync, or assume the global factor is zero.
+		// Skipping will avoid storing unnecessary factors in the claim for non rewarded pools.
+		// And in the event a global factor is wrongly deleted, it will avoid this function panicking when calculating rewards.
+		return claim
+	}
+
+	userRewardIndexes, found := claim.RewardIndexes.Get(sourceID)
+	if !found {
+		// Normally the reward indexes should always be found.
+		// But if a pool was not rewarded then becomes rewarded (ie a reward period is added to params), then the indexes will be missing from claims for that pool.
+		// So given the reward period was just added, assume the starting value for any global reward indexes, which is an empty slice.
+		userRewardIndexes = types.RewardIndexes{}
+	}
+
+	newRewards, err := k.CalculateRewards(userRewardIndexes, globalRewardIndexes, shares.ToDec())
+	if err != nil {
+		// Global reward factors should never decrease, as it would lead to a negative update to claim.Rewards.
+		// This panics if a global reward factor decreases or disappears between the old and new indexes.
+		panic(fmt.Sprintf("corrupted global reward indexes found: %v", err))
+	}
+
+	claim.Reward = claim.Reward.Add(newRewards...)
+	claim.RewardIndexes = claim.RewardIndexes.With(sourceID, globalRewardIndexes)
+
+	return claim
+}

x/incentive/keeper/rewards_init_test.go

@@ -0,0 +1,197 @@
+package keeper_test
+
+import (
+	"testing"
+
+	sdk "github.com/cosmos/cosmos-sdk/types"
+	"github.com/stretchr/testify/suite"
+
+	"github.com/kava-labs/kava/x/incentive/types"
+)
+
+// InitializeClaimTests runs unit tests for the keeper.InitializeClaim method
+//
+// inputs
+// - claim in store if it exists
+// - global indexes in store
+//
+// outputs
+// - sets or creates a claim
+type InitializeClaimTests struct {
+	unitTester
+}
+
+func TestInitializeRewardTests(t *testing.T) {
+	suite.Run(t, new(InitializeClaimTests))
+}
+
+func (suite *InitializeClaimTests) TestClaimAddedWhenClaimDoesNotExistAndNoRewards() {
+	// When a claim doesn't exist, and a user deposits to a non-rewarded pool;
+	// then a claim is added with no rewards and no indexes
+
+	collateralType := "usdc"
+	claimType := types.CLAIM_TYPE_SWAP
+	owner := arbitraryAddress()
+
+	// no global indexes stored as this pool is not rewarded
+
+	suite.keeper.InitializeClaim(suite.ctx, claimType, collateralType, owner)
+
+	syncedClaim, found := suite.keeper.GetClaim(suite.ctx, claimType, owner)
+	suite.True(found)
+	// A new claim should have empty indexes. It doesn't strictly need the collateralType either.
+	expectedIndexes := types.MultiRewardIndexes{{
+		CollateralType: collateralType,
+		RewardIndexes:  nil,
+	}}
+	suite.Equal(expectedIndexes, syncedClaim.RewardIndexes)
+	// a new claim should start with 0 rewards
+	suite.Equal(sdk.Coins(nil), syncedClaim.Reward)
+}
+
+func (suite *InitializeClaimTests) TestClaimAddedWhenClaimDoesNotExistAndRewardsExist() {
+	// When a claim doesn't exist, and a user deposits to a rewarded pool;
+	// then a claim is added with no rewards and indexes matching the global indexes
+
+	collateralType := "usdc"
+	claimType := types.CLAIM_TYPE_SWAP
+	owner := arbitraryAddress()
+
+	globalIndexes := types.MultiRewardIndexes{
+		{
+			CollateralType: collateralType,
+			RewardIndexes: types.RewardIndexes{
+				{
+					CollateralType: "rewarddenom",
+					RewardFactor:   d("1000.001"),
+				},
+			},
+		},
+	}
+	suite.storeGlobalIndexes(claimType, globalIndexes)
+
+	suite.keeper.InitializeClaim(suite.ctx, claimType, collateralType, owner)
+
+	syncedClaim, found := suite.keeper.GetClaim(suite.ctx, claimType, owner)
+	suite.True(found)
+	// a new claim should start with the current global indexes
+	suite.Equal(globalIndexes, syncedClaim.RewardIndexes)
+	// a new claim should start with 0 rewards
+	suite.Equal(sdk.Coins(nil), syncedClaim.Reward)
+}
+
+func (suite *InitializeClaimTests) TestClaimUpdatedWhenClaimExistsAndNoRewards() {
+	// When a claim exists, and a user deposits to a new non-rewarded pool;
+	// then the claim's rewards don't change
+
+	preexistingCollateralType := "preexisting"
+
+	preexistingIndexes := types.RewardIndexes{
+		{
+			CollateralType: "rewarddenom",
+			RewardFactor:   d("1000.001"),
+		},
+	}
+
+	newCollateralType := "usdc"
+	claimType := types.CLAIM_TYPE_SWAP
+
+	claim := types.Claim{
+		Type:   claimType,
+		Owner:  arbitraryAddress(),
+		Reward: arbitraryCoins(),
+		RewardIndexes: types.MultiRewardIndexes{
+			{
+				CollateralType: preexistingCollateralType,
+				RewardIndexes:  preexistingIndexes,
+			},
+		},
+	}
+	suite.keeper.SetClaim(suite.ctx, claim)
+
+	// no global indexes stored as the new pool is not rewarded
+
+	suite.keeper.InitializeClaim(suite.ctx, claimType, newCollateralType, claim.Owner)
+
+	syncedClaim, _ := suite.keeper.GetClaim(suite.ctx, claimType, claim.Owner)
+	// The preexisting indexes shouldn't be changed. It doesn't strictly need the new collateralType either.
+	expectedIndexes := types.MultiRewardIndexes{
+		{
+			CollateralType: preexistingCollateralType,
+			RewardIndexes:  preexistingIndexes,
+		},
+		{
+			CollateralType: newCollateralType,
+			RewardIndexes:  nil,
+		},
+	}
+	suite.Equal(expectedIndexes, syncedClaim.RewardIndexes)
+	// init should never alter the rewards
+	suite.Equal(claim.Reward, syncedClaim.Reward)
+}
+
+func (suite *InitializeClaimTests) TestClaimUpdatedWhenClaimExistsAndRewardsExist() {
+	// When a claim exists, and a user deposits to a new rewarded pool;
+	// then the claim's rewards don't change and the indexes are updated to match the global indexes
+
+	preexistingCollateralType := "preexisting"
+	preexistingIndexes := types.RewardIndexes{
+		{
+			CollateralType: "rewarddenom",
+			RewardFactor:   d("1000.001"),
+		},
+	}
+
+	newCollateralType := "btcb:usdx"
+	newIndexes := types.RewardIndexes{
+		{
+			CollateralType: "otherrewarddenom",
+			RewardFactor:   d("1000.001"),
+		},
+	}
+
+	claimType := types.CLAIM_TYPE_SWAP
+
+	claim := types.Claim{
+		Type:   claimType,
+		Owner:  arbitraryAddress(),
+		Reward: arbitraryCoins(),
+		RewardIndexes: types.MultiRewardIndexes{
+			{
+				CollateralType: preexistingCollateralType,
+				RewardIndexes:  preexistingIndexes,
+			},
+		},
+	}
+	suite.keeper.SetClaim(suite.ctx, claim)
+
+	globalIndexes := types.MultiRewardIndexes{
+		{
+			CollateralType: preexistingCollateralType,
+			RewardIndexes:  increaseRewardFactors(preexistingIndexes),
+		},
+		{
+			CollateralType: newCollateralType,
+			RewardIndexes:  newIndexes,
+		},
+	}
+	suite.storeGlobalIndexes(claimType, globalIndexes)
+
+	suite.keeper.InitializeClaim(suite.ctx, claimType, newCollateralType, claim.Owner)
+
+	syncedClaim, _ := suite.keeper.GetClaim(suite.ctx, claimType, claim.Owner)
+	// only the indexes for the new pool should be updated
+	expectedIndexes := types.MultiRewardIndexes{
+		{
+			CollateralType: preexistingCollateralType,
+			RewardIndexes:  preexistingIndexes,
+		},
+		{
+			CollateralType: newCollateralType,
+			RewardIndexes:  newIndexes,
+		},
+	}
+	suite.Equal(expectedIndexes, syncedClaim.RewardIndexes)
+	// init should never alter the rewards
+	suite.Equal(claim.Reward, syncedClaim.Reward)
+}

x/incentive/keeper/rewards_sync_test.go

@@ -0,0 +1,320 @@
+package keeper_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/suite"
+
+	"github.com/kava-labs/kava/x/incentive/types"
+)
+
+// SynchronizeClaimTests runs unit tests for the keeper.SynchronizeClaim method
+//
+// inputs
+// - claim in store (only claim.RewardIndexes, claim.Reward)
+// - global indexes in store
+// - shares function arg
+//
+// outputs
+// - sets a claim
+type SynchronizeClaimTests struct {
+	unitTester
+}
+
+func TestSynchronizeClaim(t *testing.T) {
+	suite.Run(t, new(SynchronizeClaimTests))
+}
+
+func (suite *SynchronizeClaimTests) TestClaimUpdatedWhenGlobalIndexesHaveIncreased() {
+	// This is the normal case
+	// Given some time has passed (meaning the global indexes have increased)
+	// When the claim is synced
+	// The user earns rewards for the time passed, and the claim indexes are updated
+
+	originalReward := arbitraryCoins()
+	collateralType := "base:quote"
+	claimType := types.CLAIM_TYPE_USDX_MINTING
+
+	claim := types.Claim{
+		Type:   claimType,
+		Owner:  arbitraryAddress(),
+		Reward: originalReward,
+		RewardIndexes: types.MultiRewardIndexes{
+			{
+				CollateralType: collateralType,
+				RewardIndexes: types.RewardIndexes{
+					{
+						CollateralType: "rewarddenom",
+						RewardFactor:   d("1000.001"),
+					},
+				},
+			},
+		},
+	}
+	suite.keeper.SetClaim(suite.ctx, claim)
+
+	globalIndexes := types.MultiRewardIndexes{
+		{
+			CollateralType: collateralType,
+			RewardIndexes: types.RewardIndexes{
+				{
+					CollateralType: "rewarddenom",
+					RewardFactor:   d("2000.002"),
+				},
+			},
+		},
+	}
+	suite.storeGlobalIndexes(claimType, globalIndexes)
+
+	userShares := i(1e9)
+
+	suite.keeper.SynchronizeClaim(suite.ctx, claimType, collateralType, claim.Owner, userShares)
+
+	syncedClaim, _ := suite.keeper.GetClaim(suite.ctx, claimType, claim.Owner)
+	// indexes updated from global
+	suite.Equal(globalIndexes, syncedClaim.RewardIndexes)
+	// new reward is (new index - old index) * user shares
+	suite.Equal(
+		cs(c("rewarddenom", 1_000_001_000_000)).Add(originalReward...),
+		syncedClaim.Reward,
+	)
+}
+
+func (suite *SynchronizeClaimTests) TestClaimUnchangedWhenGlobalIndexesUnchanged() {
+	// It should be safe to call SynchronizeClaim multiple times
+
+	collateralType := "base:quote"
+	claimType := types.CLAIM_TYPE_USDX_MINTING
+
+	unchangingIndexes := types.MultiRewardIndexes{
+		{
+			CollateralType: collateralType,
+			RewardIndexes: types.RewardIndexes{
+				{
+					CollateralType: "rewarddenom",
+					RewardFactor:   d("1000.001"),
+				},
+			},
+		},
+	}
+
+	claim := types.Claim{
+		Type:          claimType,
+		Owner:         arbitraryAddress(),
+		Reward:        arbitraryCoins(),
+		RewardIndexes: unchangingIndexes,
+	}
+	suite.keeper.SetClaim(suite.ctx, claim)
+
+	suite.storeGlobalIndexes(claimType, unchangingIndexes)
+
+	userShares := i(1e9)
+
+	suite.keeper.SynchronizeClaim(suite.ctx, claimType, collateralType, claim.Owner, userShares)
+
+	syncedClaim, _ := suite.keeper.GetClaim(suite.ctx, claimType, claim.Owner)
+	// claim should have the same rewards and indexes as before
+	suite.Equal(claim, syncedClaim)
+}
+
+func (suite *SynchronizeClaimTests) TestClaimUpdatedWhenNewRewardAdded() {
+	// When a new reward is added (via gov) for a pool the user has already deposited to, and the claim is synced;
+	// Then the user earns rewards for the time since the reward was added, and the indexes are added to the claim.
+
+	originalReward := arbitraryCoins()
+	newlyRewardcollateralType := "newlyRewardedPool"
+	claimType := types.CLAIM_TYPE_USDX_MINTING
+
+	claim := types.Claim{
+		Type:   claimType,
+		Owner:  arbitraryAddress(),
+		Reward: originalReward,
+		RewardIndexes: types.MultiRewardIndexes{
+			{
+				CollateralType: "currentlyRewardedPool",
+				RewardIndexes: types.RewardIndexes{
+					{
+						CollateralType: "reward",
+						RewardFactor:   d("1000.001"),
+					},
+				},
+			},
+		},
+	}
+	suite.keeper.SetClaim(suite.ctx, claim)
+
+	globalIndexes := types.MultiRewardIndexes{
+		{
+			CollateralType: "currentlyRewardedPool",
+			RewardIndexes: types.RewardIndexes{
+				{
+					CollateralType: "reward",
+					RewardFactor:   d("2000.002"),
+				},
+			},
+		},
+		{
+			CollateralType: newlyRewardcollateralType,
+			RewardIndexes: types.RewardIndexes{
+				{
+					CollateralType: "otherreward",
+					// Indexes start at 0 when the reward is added by gov,
+					// so this represents the syncing happening some time later.
+					RewardFactor: d("1000.001"),
+				},
+			},
+		},
+	}
+	suite.storeGlobalIndexes(claimType, globalIndexes)
+
+	userShares := i(1e9)
+
+	suite.keeper.SynchronizeClaim(suite.ctx, claimType, newlyRewardcollateralType, claim.Owner, userShares)
+
+	syncedClaim, _ := suite.keeper.GetClaim(suite.ctx, claimType, claim.Owner)
+	// the new indexes should be added to the claim, but the old ones should be unchanged
+	newlyRewrdedIndexes, _ := globalIndexes.Get(newlyRewardcollateralType)
+	expectedIndexes := claim.RewardIndexes.With(newlyRewardcollateralType, newlyRewrdedIndexes)
+	suite.Equal(expectedIndexes, syncedClaim.RewardIndexes)
+	// new reward is (new index - old index) * shares for the synced pool
+	// The old index for `newlyrewarded` isn't in the claim, so it's added starting at 0 for calculating the reward.
+	suite.Equal(
+		cs(c("otherreward", 1_000_001_000_000)).Add(originalReward...),
+		syncedClaim.Reward,
+	)
+}
+
+func (suite *SynchronizeClaimTests) TestClaimUnchangedWhenNoReward() {
+	// When a pool is not rewarded but the user has deposited to that pool, and the claim is synced;
+	// Then the claim should be the same.
+
+	collateralType := "nonRewardPool"
+	claimType := types.CLAIM_TYPE_USDX_MINTING
+
+	claim := types.Claim{
+		Type:          claimType,
+		Owner:         arbitraryAddress(),
+		Reward:        arbitraryCoins(),
+		RewardIndexes: nonEmptyMultiRewardIndexes,
+	}
+	suite.keeper.SetClaim(suite.ctx, claim)
+
+	// No global indexes stored as this pool is not rewarded
+
+	userShares := i(1e9)
+
+	suite.keeper.SynchronizeClaim(suite.ctx, claimType, collateralType, claim.Owner, userShares)
+
+	syncedClaim, _ := suite.keeper.GetClaim(suite.ctx, claimType, claim.Owner)
+	suite.Equal(claim, syncedClaim)
+}
+
+func (suite *SynchronizeClaimTests) TestClaimUpdatedWhenNewRewardDenomAdded() {
+	// When a new reward coin is added (via gov) to an already rewarded pool (that the user has already deposited to), and the claim is synced;
+	// Then the user earns rewards for the time since the reward was added, and the new indexes are added.
+
+	originalReward := arbitraryCoins()
+	collateralType := "base:quote"
+	claimType := types.CLAIM_TYPE_USDX_MINTING
+
+	claim := types.Claim{
+		Type:   claimType,
+		Owner:  arbitraryAddress(),
+		Reward: originalReward,
+		RewardIndexes: types.MultiRewardIndexes{
+			{
+				CollateralType: collateralType,
+				RewardIndexes: types.RewardIndexes{
+					{
+						CollateralType: "reward",
+						RewardFactor:   d("1000.001"),
+					},
+				},
+			},
+		},
+	}
+	suite.keeper.SetClaim(suite.ctx, claim)
+
+	globalIndexes := types.MultiRewardIndexes{
+		{
+			CollateralType: collateralType,
+			RewardIndexes: types.RewardIndexes{
+				{
+					CollateralType: "reward",
+					RewardFactor:   d("2000.002"),
+				},
+				{
+					CollateralType: "otherreward",
+					// Indexes start at 0 when the reward is added by gov,
+					// so this represents the syncing happening some time later.
+					RewardFactor: d("1000.001"),
+				},
+			},
+		},
+	}
+	suite.storeGlobalIndexes(claimType, globalIndexes)
+
+	userShares := i(1e9)
+
+	suite.keeper.SynchronizeClaim(suite.ctx, claimType, collateralType, claim.Owner, userShares)
+
+	syncedClaim, _ := suite.keeper.GetClaim(suite.ctx, claimType, claim.Owner)
+	// indexes should have the new reward denom added
+	suite.Equal(globalIndexes, syncedClaim.RewardIndexes)
+	// new reward is (new index - old index) * shares
+	// The old index for `otherreward` isn't in the claim, so it's added starting at 0 for calculating the reward.
+	suite.Equal(
+		cs(c("reward", 1_000_001_000_000), c("otherreward", 1_000_001_000_000)).Add(originalReward...),
+		syncedClaim.Reward,
+	)
+}
+
+func (suite *SynchronizeClaimTests) TestClaimUpdatedWhenGlobalIndexesIncreasedAndSourceIsZero() {
+	// Given some time has passed (meaning the global indexes have increased)
+	// When the claim is synced, but the user has no shares
+	// The user earns no rewards for the time passed, but the claim indexes are updated
+
+	collateralType := "base:quote"
+	claimType := types.CLAIM_TYPE_USDX_MINTING
+
+	claim := types.Claim{
+		Type:   claimType,
+		Owner:  arbitraryAddress(),
+		Reward: arbitraryCoins(),
+		RewardIndexes: types.MultiRewardIndexes{
+			{
+				CollateralType: collateralType,
+				RewardIndexes: types.RewardIndexes{
+					{
+						CollateralType: "rewarddenom",
+						RewardFactor:   d("1000.001"),
+					},
+				},
+			},
+		},
+	}
+	suite.keeper.SetClaim(suite.ctx, claim)
+
+	globalIndexes := types.MultiRewardIndexes{
+		{
+			CollateralType: collateralType,
+			RewardIndexes: types.RewardIndexes{
+				{
+					CollateralType: "rewarddenom",
+					RewardFactor:   d("2000.002"),
+				},
+			},
+		},
+	}
+	suite.storeGlobalIndexes(claimType, globalIndexes)
+
+	userShares := i(0)
+
+	suite.keeper.SynchronizeClaim(suite.ctx, claimType, collateralType, claim.Owner, userShares)
+
+	syncedClaim, _ := suite.keeper.GetClaim(suite.ctx, claimType, claim.Owner)
+	// indexes updated from global
+	suite.Equal(globalIndexes, syncedClaim.RewardIndexes)
+	// reward is unchanged
+	suite.Equal(claim.Reward, syncedClaim.Reward)
+}

x/incentive/keeper/unit_test.go

@@ -119,6 +119,12 @@ func (suite *unitTester) storeGlobalEarnIndexes(indexes types.MultiRewardIndexes
 	}
 }
 
+func (suite *unitTester) storeGlobalIndexes(claimType types.ClaimType, indexes types.MultiRewardIndexes) {
+	for _, i := range indexes {
+		suite.keeper.SetRewardIndexes(suite.ctx, claimType, i.CollateralType, i.RewardIndexes)
+	}
+}
+
 func (suite *unitTester) storeHardClaim(claim types.HardLiquidityProviderClaim) {
 	suite.keeper.SetHardLiquidityProviderClaim(suite.ctx, claim)
 }