feat(x/evmstaking): recovery for lost delegations (#484)

more detail in the [forum
post](https://forum.story.foundation/t/recovery-mechanism-for-lost-delegation-funds-due-to-user-mistakes/36879)

issue: none

Author: jdubpark

client/proto/story/evmstaking/v1/types/params.proto

@@ -2,6 +2,7 @@ syntax = "proto3";
 package story.evmstaking.v1.types;
 
 import "gogoproto/gogo.proto";
+import "google/protobuf/duration.proto";
 
 option go_package = "github.com/piplabs/story/client/x/evmstaking/types";
 
@@ -19,4 +20,11 @@ message Params {
   string ubi_withdraw_address = 4 [
     (gogoproto.moretags) = "yaml:\"ubi_withdraw_address\""
   ];
+  uint32 refund_fee_bps = 5 [
+    (gogoproto.moretags) = "yaml:\"refund_fee_bps\""
+  ];
+  google.protobuf.Duration refund_period = 6 [
+    (gogoproto.nullable) = false, (gogoproto.stdduration) = true,
+    (gogoproto.moretags) = "yaml:\"refund_period\""
+  ];
 }

client/x/evmstaking/keeper/deposit.go

@@ -6,6 +6,9 @@ import (
 	"encoding/hex"
 	"fmt"
 	"strconv"
+	"time"
+
+	"cosmossdk.io/math"
 
 	sdk "github.com/cosmos/cosmos-sdk/types"
 	skeeper "github.com/cosmos/cosmos-sdk/x/staking/keeper"
@@ -23,6 +26,10 @@ func (k Keeper) ProcessDeposit(ctx context.Context, ev *bindings.IPTokenStakingD
 	sdkCtx := sdk.UnwrapSDKContext(ctx)
 	cachedCtx, writeCache := sdkCtx.CacheContext()
 
+	var isRefund bool
+	var refundAmount math.Int
+	var completionTime time.Time
+
 	defer func() {
 		if r := recover(); r != nil {
 			err = errors.WrapErrWithCode(errors.UnexpectedCondition, fmt.Errorf("panic caused by %v", r))
@@ -41,18 +48,27 @@ func (k Keeper) ProcessDeposit(ctx context.Context, ev *bindings.IPTokenStakingD
 			)
 		}
 
-		sdkCtx.EventManager().EmitEvents(sdk.Events{
-			e.AppendAttributes(
-				sdk.NewAttribute(types.AttributeKeyAmount, ev.StakeAmount.String()),
-				sdk.NewAttribute(types.AttributeKeyBlockHeight, strconv.FormatInt(sdkCtx.BlockHeight(), 10)),
-				sdk.NewAttribute(types.AttributeKeyDelegatorAddress, ev.Delegator.String()),
-				sdk.NewAttribute(types.AttributeKeyValidatorCmpPubKey, hex.EncodeToString(ev.ValidatorCmpPubkey)),
-				sdk.NewAttribute(types.AttributeKeyDelegateID, ev.DelegationId.String()),
-				sdk.NewAttribute(types.AttributeKeyPeriodType, strconv.FormatInt(ev.StakingPeriod.Int64(), 10)),
-				sdk.NewAttribute(types.AttributeKeySenderAddress, ev.OperatorAddress.Hex()),
-				sdk.NewAttribute(types.AttributeKeyTxHash, hex.EncodeToString(ev.Raw.TxHash.Bytes())),
-			),
-		})
+		e = e.AppendAttributes(
+			sdk.NewAttribute(types.AttributeKeyAmount, ev.StakeAmount.String()),
+			sdk.NewAttribute(types.AttributeKeyBlockHeight, strconv.FormatInt(sdkCtx.BlockHeight(), 10)),
+			sdk.NewAttribute(types.AttributeKeyDelegatorAddress, ev.Delegator.String()),
+			sdk.NewAttribute(types.AttributeKeyValidatorCmpPubKey, hex.EncodeToString(ev.ValidatorCmpPubkey)),
+			sdk.NewAttribute(types.AttributeKeyDelegateID, ev.DelegationId.String()),
+			sdk.NewAttribute(types.AttributeKeyPeriodType, strconv.FormatInt(ev.StakingPeriod.Int64(), 10)),
+			sdk.NewAttribute(types.AttributeKeySenderAddress, ev.OperatorAddress.Hex()),
+			sdk.NewAttribute(types.AttributeKeyTxHash, hex.EncodeToString(ev.Raw.TxHash.Bytes())),
+			sdk.NewAttribute(types.AttributeKeyIsRefund, strconv.FormatBool(isRefund)),
+		)
+
+		// if it's a refund, add refund attributes
+		if isRefund {
+			e = e.AppendAttributes(
+				sdk.NewAttribute(types.AttributeKeyRefundAmount, refundAmount.String()),
+				sdk.NewAttribute(types.AttributeKeyRefundCompletionTime, completionTime.String()),
+			)
+		}
+
+		sdkCtx.EventManager().EmitEvents(sdk.Events{e})
 	}()
 
 	validatorPubkey, err := k1util.PubKeyBytesToCosmos(ev.ValidatorCmpPubkey)
@@ -96,8 +112,19 @@ func (k Keeper) ProcessDeposit(ctx context.Context, ev *bindings.IPTokenStakingD
 	}
 
 	val, err := k.stakingKeeper.GetValidator(cachedCtx, validatorAddr)
+
 	if errors.Is(err, stypes.ErrNoValidatorFound) {
-		return errors.WrapErrWithCode(errors.ValidatorNotFound, err)
+		isRefund = true
+		log.Info(cachedCtx, "Validator not found, refunding deposit minus the refund fee",
+			"val_addr", validatorAddr,
+			"val_evm_addr", valEvmAddr.String(),
+			"del_addr", depositorAddr.String(),
+			"del_evm_addr", ev.Delegator.String(),
+		)
+
+		refundAmount, completionTime, err = k.RefundDelegation(ctx, depositorAddr, validatorAddr, amountCoin)
+
+		return err // skip delegation logic
 	} else if err != nil {
 		return errors.Wrap(err, "get validator failed")
 	}
@@ -115,11 +142,6 @@ func (k Keeper) ProcessDeposit(ctx context.Context, ev *bindings.IPTokenStakingD
 		delID = stypes.FlexiblePeriodDelegationID
 	}
 
-	evmstakingSKeeper, ok := k.stakingKeeper.(*skeeper.Keeper)
-	if !ok {
-		return errors.New("type assertion failed")
-	}
-
 	// Note that, after minting, we save the mapping between delegator bech32 address and evm address, which will be used in the withdrawal queue.
 	// The saving is done regardless of any error below, as the money is already minted and sent to the delegator, who can withdraw the minted amount.
 	// NOTE: Do not overwrite the existing withdraw/reward address set by the delegator.
@@ -146,13 +168,25 @@ func (k Keeper) ProcessDeposit(ctx context.Context, ev *bindings.IPTokenStakingD
 		return errors.Wrap(err, "create stake coin for depositor: send coins")
 	}
 
+	return k.CreateDelegation(cachedCtx, validatorAddr.String(), depositorAddr.String(), amountCoin, delID, periodType)
+}
+
+func (k Keeper) CreateDelegation(
+	cachedCtx context.Context, validatorAddr, depositorAddr string, amountCoin sdk.Coin, periodDelegationID string,
+	periodType int32,
+) error {
+	evmstakingSKeeper, ok := k.stakingKeeper.(*skeeper.Keeper)
+	if !ok {
+		return errors.New("type assertion failed")
+	}
+
 	skeeperMsgServer := skeeper.NewMsgServerImpl(evmstakingSKeeper)
 	// Delegation by the depositor on the validator (validator existence is checked in msgServer.Delegate)
 	msg := stypes.NewMsgDelegate(
-		depositorAddr.String(), validatorAddr.String(), amountCoin,
-		delID, periodType,
+		depositorAddr, validatorAddr, amountCoin,
+		periodDelegationID, periodType,
 	)
-	if _, err = skeeperMsgServer.Delegate(cachedCtx, msg); errors.Is(err, stypes.ErrDelegationBelowMinimum) {
+	if _, err := skeeperMsgServer.Delegate(cachedCtx, msg); errors.Is(err, stypes.ErrDelegationBelowMinimum) {
 		return errors.WrapErrWithCode(errors.InvalidDelegationAmount, err)
 	} else if errors.Is(err, stypes.ErrNoPeriodTypeFound) {
 		return errors.WrapErrWithCode(errors.InvalidPeriodType, err)
@@ -166,3 +200,52 @@ func (k Keeper) ProcessDeposit(ctx context.Context, ev *bindings.IPTokenStakingD
 func (k Keeper) ParseDepositLog(ethlog ethtypes.Log) (*bindings.IPTokenStakingDeposit, error) {
 	return k.ipTokenStakingContract.ParseDeposit(ethlog)
 }
+
+func (k Keeper) RefundDelegation(
+	ctx context.Context, delegatorAddr sdk.AccAddress, validatorAddr sdk.ValAddress, rawRefundAmountCoin sdk.Coin,
+) (refundAmount math.Int, completionTime time.Time, err error) {
+	sdkCtx := sdk.UnwrapSDKContext(ctx)
+
+	// the min refund fee amount will be `refundFeeBps * minDelegationAmount (1024) / 10_000bps`
+	refundFeeBps, err := k.RefundFeeBps(ctx)
+	if err != nil {
+		return math.Int{}, time.Time{}, errors.Wrap(err, "get refund fee")
+	}
+	refundFeeAmount := rawRefundAmountCoin.Amount.Mul(math.NewInt(int64(refundFeeBps))).Quo(math.NewInt(10_000))
+	refundAmount = rawRefundAmountCoin.Amount.Sub(refundFeeAmount)
+
+	refundPeriod, err := k.RefundPeriod(ctx)
+	if err != nil {
+		return math.Int{}, time.Time{}, errors.Wrap(err, "get refund period")
+	}
+
+	completionTime = sdkCtx.BlockTime().Add(refundPeriod)
+
+	// set ubd index in mapping (needed before inserting to ubd queue)
+	ubd, err := k.stakingKeeper.SetUnbondingDelegationEntry(
+		ctx,
+		delegatorAddr,
+		validatorAddr,
+		sdkCtx.BlockHeight(),
+		completionTime,
+		refundAmount,
+	)
+	if err != nil {
+		return math.Int{}, time.Time{}, errors.Wrap(err, "set unbonding delegation entry")
+	}
+
+	// push the refund to the unbonding queue
+	err = k.stakingKeeper.InsertUBDQueue(ctx, ubd, completionTime)
+	if err != nil {
+		return math.Int{}, time.Time{}, errors.Wrap(err, "insert unbonding delegation queue")
+	}
+
+	log.Debug(ctx, "Added refund to unbonding queue",
+		"del_addr", delegatorAddr.String(),
+		"val_addr", validatorAddr.String(),
+		"amount", refundAmount.String(),
+		"completion_time", completionTime,
+	)
+
+	return refundAmount, completionTime, nil
+}

client/x/evmstaking/keeper/deposit_test.go

@@ -39,18 +39,27 @@ func (s *TestSuite) createValidator(ctx context.Context, valPubKey crypto.PubKey
 	_ = skeeper.TestingUpdateValidator(stakingKeeper, sdkCtx, validator, true)
 }
 
+type expectedResultDeposit struct {
+	validatorAddr sdk.ValAddress
+	delegatorAddr sdk.AccAddress
+	delegation    stypes.Delegation
+}
+
 func (s *TestSuite) TestProcessDeposit() {
 	require := s.Require()
 	ctx, keeper, stakingKeeper := s.Ctx, s.EVMStakingKeeper, s.StakingKeeper
 
-	pubKeys, accAddrs, valAddrs := createAddresses(2)
+	pubKeys, accAddrs, valAddrs := createAddresses(3)
 	// delegator
 	delPubKey := pubKeys[0]
 	delAddr := accAddrs[0]
 	// validator
 	valPubKey := pubKeys[1]
 	valAddr := valAddrs[1]
 	s.createValidator(ctx, valPubKey, valAddr)
+	// non-existing validator
+	val2Pubkey := pubKeys[2]
+	val2Addr := valAddrs[2]
 
 	createDeposit := func(delPubKey, valPubKey []byte, amount *big.Int) *bindings.IPTokenStakingDeposit {
 		return &bindings.IPTokenStakingDeposit{
@@ -63,13 +72,25 @@ func (s *TestSuite) TestProcessDeposit() {
 		}
 	}
 
+	refundFeeBps, err := keeper.RefundFeeBps(ctx)
+	require.NoError(err)
+	refundPeriod, err := keeper.RefundPeriod(ctx)
+	require.NoError(err)
+
 	tcs := []struct {
 		name           string
 		settingMock    func()
 		deposit        *bindings.IPTokenStakingDeposit
-		expectedResult stypes.Delegation
-		expectedErr    string
+		expectedResult []expectedResultDeposit
+		expectedRefund struct {
+			DelegatorAddress sdk.AccAddress
+			ValidatorAddress sdk.ValAddress
+			RefundAmount     sdkmath.Int
+			// NOTE: CompletionTime is calculated during the test if RefundAmount is greater than 0
+		}
+		expectedErr string
 	}{
+		// TODO: corrupted delegator and validator pubkey
 		{
 			name: "fail: invalid validator pubkey",
 			deposit: &bindings.IPTokenStakingDeposit{
@@ -82,25 +103,54 @@ func (s *TestSuite) TestProcessDeposit() {
 			},
 			expectedErr: "validator pubkey to cosmos: invalid pubkey length",
 		},
-		// TODO: corrupted delegator and validator pubkey
+		{
+			name: "pass: validator not found, refund deposit",
+			deposit: &bindings.IPTokenStakingDeposit{
+				Delegator:          common.Address(delAddr),
+				ValidatorCmpPubkey: val2Pubkey.Bytes(),
+				StakeAmount:        new(big.Int).SetUint64(1024),
+				StakingPeriod:      big.NewInt(0),
+			},
+			expectedRefund: struct {
+				DelegatorAddress sdk.AccAddress
+				ValidatorAddress sdk.ValAddress
+				RefundAmount     sdkmath.Int
+			}{
+				DelegatorAddress: delAddr,
+				ValidatorAddress: val2Addr,
+				RefundAmount:     sdkmath.NewInt(1024).Sub(sdkmath.NewInt(1024).Mul(sdkmath.NewInt(int64(refundFeeBps))).Quo(sdkmath.NewInt(10_000))),
+			},
+		},
 		{
 			name:    "pass: existing delegator",
 			deposit: createDeposit(delPubKey.Bytes(), valPubKey.Bytes(), new(big.Int).SetUint64(1)),
-			expectedResult: stypes.Delegation{
-				DelegatorAddress: delAddr.String(),
-				ValidatorAddress: valAddr.String(),
-				Shares:           sdkmath.LegacyNewDecFromInt(sdkmath.NewInt(1)),
-				RewardsShares:    sdkmath.LegacyNewDecFromInt(sdkmath.NewInt(1)).Quo(sdkmath.LegacyNewDecFromInt(sdkmath.NewInt(2))),
+			expectedResult: []expectedResultDeposit{
+				{
+					validatorAddr: valAddr,
+					delegatorAddr: delAddr,
+					delegation: stypes.Delegation{
+						DelegatorAddress: delAddr.String(),
+						ValidatorAddress: valAddr.String(),
+						Shares:           sdkmath.LegacyNewDecFromInt(sdkmath.NewInt(1)),
+						RewardsShares:    sdkmath.LegacyNewDecFromInt(sdkmath.NewInt(1)).Quo(sdkmath.LegacyNewDecFromInt(sdkmath.NewInt(2))),
+					},
+				},
 			},
 		},
 		{
 			name:    "pass: new delegator",
 			deposit: createDeposit(delPubKey.Bytes(), valPubKey.Bytes(), new(big.Int).SetUint64(1)),
-			expectedResult: stypes.Delegation{
-				DelegatorAddress: delAddr.String(),
-				ValidatorAddress: valAddr.String(),
-				Shares:           sdkmath.LegacyNewDecFromInt(sdkmath.NewInt(1)),
-				RewardsShares:    sdkmath.LegacyNewDecFromInt(sdkmath.NewInt(1)).Quo(sdkmath.LegacyNewDecFromInt(sdkmath.NewInt(2))),
+			expectedResult: []expectedResultDeposit{
+				{
+					validatorAddr: valAddr,
+					delegatorAddr: delAddr,
+					delegation: stypes.Delegation{
+						DelegatorAddress: delAddr.String(),
+						ValidatorAddress: valAddr.String(),
+						Shares:           sdkmath.LegacyNewDecFromInt(sdkmath.NewInt(1)),
+						RewardsShares:    sdkmath.LegacyNewDecFromInt(sdkmath.NewInt(1)).Quo(sdkmath.LegacyNewDecFromInt(sdkmath.NewInt(2))),
+					},
+				},
 			},
 		},
 	}
@@ -117,9 +167,27 @@ func (s *TestSuite) TestProcessDeposit() {
 			} else {
 				require.NoError(err)
 				// check delegation
-				delegation, err := stakingKeeper.GetDelegation(cachedCtx, delAddr, valAddr)
-				require.NoError(err)
-				require.Equal(tc.expectedResult, delegation)
+				if len(tc.expectedResult) > 0 {
+					for _, tc := range tc.expectedResult {
+						delegation, err := stakingKeeper.GetDelegation(cachedCtx, tc.delegatorAddr, tc.validatorAddr)
+						require.NoError(err)
+						require.Equal(tc.delegation, delegation)
+					}
+				}
+
+				// check refund in unbonding queue
+				if tc.expectedRefund.DelegatorAddress != nil {
+					ubd, err := stakingKeeper.GetUnbondingDelegation(cachedCtx, tc.expectedRefund.DelegatorAddress, tc.expectedRefund.ValidatorAddress)
+					require.NoError(err)
+					require.Equal(tc.expectedRefund.ValidatorAddress.String(), ubd.ValidatorAddress)
+					require.Equal(tc.expectedRefund.DelegatorAddress.String(), ubd.DelegatorAddress)
+
+					completionTime := ctx.BlockTime().Add(refundPeriod)
+					for _, entry := range ubd.Entries {
+						require.True(tc.expectedRefund.RefundAmount.Equal(sdkmath.NewIntFromBigInt(entry.Balance.BigInt())))
+						require.Equal(completionTime, entry.CompletionTime)
+					}
+				}
 			}
 		})
 	}

client/x/evmstaking/keeper/params.go

@@ -2,6 +2,7 @@ package keeper
 
 import (
 	"context"
+	"time"
 
 	sdk "github.com/cosmos/cosmos-sdk/types"
 
@@ -36,6 +37,24 @@ func (k Keeper) MinPartialWithdrawalAmount(ctx context.Context) (uint64, error)
 	return params.MinPartialWithdrawalAmount, nil
 }
 
+func (k Keeper) RefundFeeBps(ctx context.Context) (uint32, error) {
+	params, err := k.GetParams(ctx)
+	if err != nil {
+		return 0, err
+	}
+
+	return params.RefundFeeBps, nil
+}
+
+func (k Keeper) RefundPeriod(ctx context.Context) (time.Duration, error) {
+	params, err := k.GetParams(ctx)
+	if err != nil {
+		return 0, err
+	}
+
+	return params.RefundPeriod, nil
+}
+
 // This method performs no validation of the parameters.
 func (k Keeper) SetParams(ctx context.Context, params types.Params) error {
 	store := k.storeService.OpenKVStore(ctx)