ADR 17 Implementation: Historical Module

CHANGELOG.md

@@ -145,6 +145,9 @@ that allows for arbitrary vesting periods.
     * `ValidateSigCountDecorator`: Validate the number of signatures in tx based on app-parameters.
     * `IncrementSequenceDecorator`: Increments the account sequence for each signer to prevent replay attacks.
 * (cli) [\#5223](https://github.com/cosmos/cosmos-sdk/issues/5223) Cosmos Ledger App v2.0.0 is now supported. The changes are backwards compatible and App v1.5.x is still supported.
+* (x/staking) [\#5380](https://github.com/cosmos/cosmos-sdk/pull/5380) Introduced ability to store historical info entries in staking keeper, allows applications to introspect specified number of past headers and validator sets
+* (x/staking) [\#5380](https://github.com/cosmos/cosmos-sdk/pull/5380) Introduces new parameter `HistoricalEntries` which allows applications to determine how many recent historical info entries they want to persist in store. Default value is 0.
+* (x/staking) [\#5380](https://github.com/cosmos/cosmos-sdk/pull/5380) Introduces cli commands and rest routes to query historical information at a given height
 * (modules) [\#5249](https://github.com/cosmos/cosmos-sdk/pull/5249) Funds are now allowed to be directly sent to the community pool (via the distribution module account).
 
 ### Improvements

x/staking/abci.go

@@ -0,0 +1,42 @@
+package staking
+
+import (
+	sdk "github.com/cosmos/cosmos-sdk/types"
+	"github.com/cosmos/cosmos-sdk/x/staking/types"
+)
+
+// BeginBlocker will persist the current header and validator set as a historical entry
+// and prune the oldest entry based on the HistoricalEntries parameter
+func BeginBlocker(ctx sdk.Context, k Keeper) {
+	entryNum := k.HistoricalEntries(ctx)
+	// if there is no need to persist historicalInfo, return
+	if entryNum == 0 {
+		return
+	}
+
+	// Create HistoricalInfo struct
+	lastVals := k.GetLastValidators(ctx)
+	historicalEntry := types.NewHistoricalInfo(
+		ctx.BlockHeader(),
+		lastVals,
+	)
+
+	// Set latest HistoricalInfo at current height
+	k.SetHistoricalInfo(ctx, ctx.BlockHeight(), historicalEntry)
+
+	// prune store to ensure we only have parameter-defined historical entries
+	// in most cases, this will involve removing a single historical entry
+	// In the rare scenario when the historical entries gets reduced to a lower value k'
+	// from the original value k. k - k' entries must be deleted from the store
+	// Since the entries to be deleted are always in a continuous range, we can iterate
+	// over the historical entries starting from the most recent version to be pruned
+	// and then return at the first empty entry
+	for i := ctx.BlockHeight() - int64(entryNum); i >= 0; i-- {
+		_, found := k.GetHistoricalInfo(ctx, i)
+		if found {
+			k.DeleteHistoricalInfo(ctx, i)
+		} else {
+			return
+		}
+	}
+}

x/staking/abci_test.go

@@ -0,0 +1,83 @@
+package staking
+
+import (
+	"sort"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	sdk "github.com/cosmos/cosmos-sdk/types"
+	"github.com/cosmos/cosmos-sdk/x/staking/keeper"
+	"github.com/cosmos/cosmos-sdk/x/staking/types"
+	abci "github.com/tendermint/tendermint/abci/types"
+)
+
+func TestBeginBlocker(t *testing.T) {
+	ctx, _, k, _ := keeper.CreateTestInput(t, false, 10)
+
+	// set historical entries in params to 5
+	params := types.DefaultParams()
+	params.HistoricalEntries = 5
+	k.SetParams(ctx, params)
+
+	// set historical info at 5, 4 which should be pruned
+	// and check that it has been stored
+	h4 := abci.Header{
+		ChainID: "HelloChain",
+		Height:  4,
+	}
+	h5 := abci.Header{
+		ChainID: "HelloChain",
+		Height:  5,
+	}
+	valSet := []Validator{
+		types.NewValidator(sdk.ValAddress(keeper.Addrs[0]), keeper.PKs[0], types.Description{}),
+		types.NewValidator(sdk.ValAddress(keeper.Addrs[1]), keeper.PKs[1], types.Description{}),
+	}
+	hi4 := types.NewHistoricalInfo(h4, valSet)
+	hi5 := types.NewHistoricalInfo(h5, valSet)
+	k.SetHistoricalInfo(ctx, 4, hi4)
+	k.SetHistoricalInfo(ctx, 5, hi5)
+	recv, found := k.GetHistoricalInfo(ctx, 4)
+	require.True(t, found)
+	require.Equal(t, hi4, recv)
+	recv, found = k.GetHistoricalInfo(ctx, 5)
+	require.True(t, found)
+	require.Equal(t, hi5, recv)
+
+	// Set last validators in keeper
+	val1 := types.NewValidator(sdk.ValAddress(keeper.Addrs[2]), keeper.PKs[2], types.Description{})
+	k.SetValidator(ctx, val1)
+	k.SetLastValidatorPower(ctx, val1.OperatorAddress, 10)
+	val2 := types.NewValidator(sdk.ValAddress(keeper.Addrs[3]), keeper.PKs[3], types.Description{})
+	vals := []types.Validator{val1, val2}
+	sort.Sort(types.Validators(vals))
+	k.SetValidator(ctx, val2)
+	k.SetLastValidatorPower(ctx, val2.OperatorAddress, 8)
+
+	// Set Header for BeginBlock context
+	header := abci.Header{
+		ChainID: "HelloChain",
+		Height:  10,
+	}
+	ctx = ctx.WithBlockHeader(header)
+
+	BeginBlocker(ctx, k)
+
+	// Check HistoricalInfo at height 10 is persisted
+	expected := types.HistoricalInfo{
+		Header: header,
+		ValSet: vals,
+	}
+	recv, found = k.GetHistoricalInfo(ctx, 10)
+	require.True(t, found, "GetHistoricalInfo failed after BeginBlock")
+	require.Equal(t, expected, recv, "GetHistoricalInfo returned eunexpected result")
+
+	// Check HistoricalInfo at height 5, 4 is pruned
+	recv, found = k.GetHistoricalInfo(ctx, 4)
+	require.False(t, found, "GetHistoricalInfo did not prune earlier height")
+	require.Equal(t, types.HistoricalInfo{}, recv, "GetHistoricalInfo at height 4 is not empty after prune")
+	recv, found = k.GetHistoricalInfo(ctx, 5)
+	require.False(t, found, "GetHistoricalInfo did not prune first prune height")
+	require.Equal(t, types.HistoricalInfo{}, recv, "GetHistoricalInfo at height 5 is not empty after prune")
+}

x/staking/client/cli/query.go

@@ -2,6 +2,7 @@ package cli
 
 import (
 	"fmt"
+	"strconv"
 	"strings"
 
 	"github.com/spf13/cobra"
@@ -35,6 +36,7 @@ func GetQueryCmd(queryRoute string, cdc *codec.Codec) *cobra.Command {
 		GetCmdQueryValidatorDelegations(queryRoute, cdc),
 		GetCmdQueryValidatorUnbondingDelegations(queryRoute, cdc),
 		GetCmdQueryValidatorRedelegations(queryRoute, cdc),
+		GetCmdQueryHistoricalInfo(queryRoute, cdc),
 		GetCmdQueryParams(queryRoute, cdc),
 		GetCmdQueryPool(queryRoute, cdc))...)
 
@@ -527,6 +529,50 @@ $ %s query staking redelegation cosmos1gghjut3ccd8ay0zduzj64hwre2fxs9ld75ru9p
 	}
 }
 
+// GetCmdQueryHistoricalInfo implements the historical info query command
+func GetCmdQueryHistoricalInfo(queryRoute string, cdc *codec.Codec) *cobra.Command {
+	return &cobra.Command{
+		Use:   "historical-info [height]",
+		Args:  cobra.ExactArgs(1),
+		Short: "Query historical info at given height",
+		Long: strings.TrimSpace(
+			fmt.Sprintf(`Query historical info at given height.
+
+Example:
+$ %s query staking historical-info 5
+`,
+				version.ClientName,
+			),
+		),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cliCtx := context.NewCLIContext().WithCodec(cdc)
+
+			height, err := strconv.ParseInt(args[0], 10, 64)
+			if err != nil || height < 0 {
+				return fmt.Errorf("Height argument provided must be a non-negative-integer: %v", err)
+			}
+
+			bz, err := cdc.MarshalJSON(types.QueryHistoricalInfoParams{Height: height})
+			if err != nil {
+				return err
+			}
+
+			route := fmt.Sprintf("custom/%s/%s", queryRoute, types.QueryHistoricalInfo)
+			res, _, err := cliCtx.QueryWithData(route, bz)
+			if err != nil {
+				return err
+			}
+
+			var resp types.HistoricalInfo
+			if err := cdc.UnmarshalJSON(res, &resp); err != nil {
+				return err
+			}
+
+			return cliCtx.PrintOutput(resp)
+		},
+	}
+}
+
 // GetCmdQueryPool implements the pool query command.
 func GetCmdQueryPool(storeName string, cdc *codec.Codec) *cobra.Command {
 	return &cobra.Command{

x/staking/client/rest/query.go

@@ -3,6 +3,7 @@ package rest
 import (
 	"fmt"
 	"net/http"
+	"strconv"
 	"strings"
 
 	"github.com/gorilla/mux"
@@ -86,6 +87,12 @@ func registerQueryRoutes(cliCtx context.CLIContext, r *mux.Router) {
 		validatorUnbondingDelegationsHandlerFn(cliCtx),
 	).Methods("GET")
 
+	// Get HistoricalInfo at a given height
+	r.HandleFunc(
+		"/staking/historical_info/{height}",
+		historicalInfoHandlerFn(cliCtx),
+	).Methods("GET")
+
 	// Get the current state of the staking pool
 	r.HandleFunc(
 		"/staking/pool",
@@ -313,6 +320,36 @@ func validatorUnbondingDelegationsHandlerFn(cliCtx context.CLIContext) http.Hand
 	return queryValidator(cliCtx, "custom/staking/validatorUnbondingDelegations")
 }
 
+// HTTP request handler to query historical info at a given height
+func historicalInfoHandlerFn(cliCtx context.CLIContext) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		vars := mux.Vars(r)
+		heightStr := vars["height"]
+		height, err := strconv.ParseInt(heightStr, 10, 64)
+		if err != nil || height < 0 {
+			rest.WriteErrorResponse(w, http.StatusBadRequest, fmt.Sprintf("Must provide non-negative integer for height: %v", err))
+			return
+		}
+
+		params := types.NewQueryHistoricalInfoParams(height)
+		bz, err := cliCtx.Codec.MarshalJSON(params)
+		if err != nil {
+			rest.WriteErrorResponse(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+
+		route := fmt.Sprintf("custom/%s/%s", types.QuerierRoute, types.QueryHistoricalInfo)
+		res, height, err := cliCtx.QueryWithData(route, bz)
+		if err != nil {
+			rest.WriteErrorResponse(w, http.StatusBadRequest, err.Error())
+			return
+		}
+
+		cliCtx = cliCtx.WithHeight(height)
+		rest.PostProcessResponse(w, cliCtx, res)
+	}
+}
+
 // HTTP request handler to query the pool information
 func poolHandlerFn(cliCtx context.CLIContext) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {

x/staking/keeper/historical_info.go

@@ -0,0 +1,38 @@
+package keeper
+
+import (
+	sdk "github.com/cosmos/cosmos-sdk/types"
+	"github.com/cosmos/cosmos-sdk/x/staking/types"
+)
+
+// GetHistoricalInfo gets the historical info at a given height
+func (k Keeper) GetHistoricalInfo(ctx sdk.Context, height int64) (types.HistoricalInfo, bool) {
+	store := ctx.KVStore(k.storeKey)
+	key := types.GetHistoricalInfoKey(height)
+
+	value := store.Get(key)
+
+	if value == nil {
+		return types.HistoricalInfo{}, false
+	}
+
+	hi := types.MustUnmarshalHistoricalInfo(k.cdc, value)
+	return hi, true
+}
+
+// SetHistoricalInfo sets the historical info at a given height
+func (k Keeper) SetHistoricalInfo(ctx sdk.Context, height int64, hi types.HistoricalInfo) {
+	store := ctx.KVStore(k.storeKey)
+	key := types.GetHistoricalInfoKey(height)
+
+	value := types.MustMarshalHistoricalInfo(k.cdc, hi)
+	store.Set(key, value)
+}
+
+// DeleteHistoricalInfo deletes the historical info at a given height
+func (k Keeper) DeleteHistoricalInfo(ctx sdk.Context, height int64) {
+	store := ctx.KVStore(k.storeKey)
+	key := types.GetHistoricalInfoKey(height)
+
+	store.Delete(key)
+}

x/staking/keeper/historical_info_test.go

@@ -0,0 +1,34 @@
+package keeper
+
+import (
+	"sort"
+	"testing"
+
+	"github.com/cosmos/cosmos-sdk/x/staking/types"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestHistoricalInfo(t *testing.T) {
+	ctx, _, keeper, _ := CreateTestInput(t, false, 10)
+	validators := make([]types.Validator, len(addrVals))
+
+	for i, valAddr := range addrVals {
+		validators[i] = types.NewValidator(valAddr, PKs[i], types.Description{})
+	}
+
+	hi := types.NewHistoricalInfo(ctx.BlockHeader(), validators)
+
+	keeper.SetHistoricalInfo(ctx, 2, hi)
+
+	recv, found := keeper.GetHistoricalInfo(ctx, 2)
+	require.True(t, found, "HistoricalInfo not found after set")
+	require.Equal(t, hi, recv, "HistoricalInfo not equal")
+	require.True(t, sort.IsSorted(types.Validators(recv.ValSet)), "HistoricalInfo validators is not sorted")
+
+	keeper.DeleteHistoricalInfo(ctx, 2)
+
+	recv, found = keeper.GetHistoricalInfo(ctx, 2)
+	require.False(t, found, "HistoricalInfo found after delete")
+	require.Equal(t, types.HistoricalInfo{}, recv, "HistoricalInfo is not empty")
+}

x/staking/keeper/params.go

@@ -37,6 +37,13 @@ func (k Keeper) MaxEntries(ctx sdk.Context) (res uint16) {
 	return
 }
 
+// HistoricalEntries = number of historical info entries
+// to persist in store
+func (k Keeper) HistoricalEntries(ctx sdk.Context) (res uint16) {
+	k.paramstore.Get(ctx, types.KeyHistoricalEntries, &res)
+	return
+}
+
 // BondDenom - Bondable coin denomination
 func (k Keeper) BondDenom(ctx sdk.Context) (res string) {
 	k.paramstore.Get(ctx, types.KeyBondDenom, &res)
@@ -49,6 +56,7 @@ func (k Keeper) GetParams(ctx sdk.Context) types.Params {
 		k.UnbondingTime(ctx),
 		k.MaxValidators(ctx),
 		k.MaxEntries(ctx),
+		k.HistoricalEntries(ctx),
 		k.BondDenom(ctx),
 	)
 }

x/staking/keeper/querier.go

@@ -38,6 +38,8 @@ func NewQuerier(k Keeper) sdk.Querier {
 			return queryDelegatorValidators(ctx, req, k)
 		case types.QueryDelegatorValidator:
 			return queryDelegatorValidator(ctx, req, k)
+		case types.QueryHistoricalInfo:
+			return queryHistoricalInfo(ctx, req, k)
 		case types.QueryPool:
 			return queryPool(ctx, k)
 		case types.QueryParameters:
@@ -327,6 +329,27 @@ func queryRedelegations(ctx sdk.Context, req abci.RequestQuery, k Keeper) ([]byt
 	return res, nil
 }
 
+func queryHistoricalInfo(ctx sdk.Context, req abci.RequestQuery, k Keeper) ([]byte, sdk.Error) {
+	var params types.QueryHistoricalInfoParams
+
+	err := types.ModuleCdc.UnmarshalJSON(req.Data, &params)
+	if err != nil {
+		return nil, sdk.ErrUnknownRequest(string(req.Data))
+	}
+
+	hi, found := k.GetHistoricalInfo(ctx, params.Height)
+	if !found {
+		return nil, types.ErrNoHistoricalInfo(types.DefaultCodespace)
+	}
+
+	res, err := codec.MarshalJSONIndent(types.ModuleCdc, hi)
+	if err != nil {
+		return nil, sdk.ErrInternal(sdk.AppendMsgToErr("could not marshal result to JSON", err.Error()))
+	}
+
+	return res, nil
+}
+
 func queryPool(ctx sdk.Context, k Keeper) ([]byte, sdk.Error) {
 	bondDenom := k.BondDenom(ctx)
 	bondedPool := k.GetBondedPool(ctx)