ADR 17 Implementation: Historical Module

CHANGELOG.md

@@ -139,6 +139,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.
+
 
 ### Improvements
 

x/staking/abci.go

@@ -0,0 +1,32 @@
+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)
+	types.Validators(lastVals).Sort()
+	historicalEntry := types.HistoricalInfo{
+		Header: ctx.BlockHeader(),
+		ValSet: lastVals,
+	}
+
+	// Set latest HistoricalInfo at current height
+	k.SetHistoricalInfo(ctx, ctx.BlockHeight(), historicalEntry)
+
+	// prune store to ensure we only have parameter-defined historical entries
+	if ctx.BlockHeight() > int64(entryNum) {
+		k.DeleteHistoricalInfo(ctx, ctx.BlockHeight()-int64(entryNum))
+	}
+}

x/staking/abci_test.go

@@ -0,0 +1,70 @@
+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 which should be pruned
+	header := 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{}),
+	}
+	hi5 := types.NewHistoricalInfo(header, valSet)
+	k.SetHistoricalInfo(ctx, 5, hi5)
+	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 is pruned
+	recv, found = k.GetHistoricalInfo(ctx, 5)
+	require.False(t, found, "GetHistoricalInfo did not prune")
+	require.Equal(t, types.HistoricalInfo{}, recv, "GetHistoricalInfo is not empty after prune")
+}

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) (hi types.HistoricalInfo, found 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)
+	var validators []types.Validator
+
+	for i, valAddr := range addrVals {
+		validators = append(validators, 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)

x/staking/keeper/querier_test.go

@@ -31,6 +31,13 @@ func TestNewQuerier(t *testing.T) {
 		keeper.SetValidatorByPowerIndex(ctx, validators[i])
 	}
 
+	header := abci.Header{
+		ChainID: "HelloChain",
+		Height:  5,
+	}
+	hi := types.NewHistoricalInfo(header, validators[:])
+	keeper.SetHistoricalInfo(ctx, 5, hi)
+
 	query := abci.RequestQuery{
 		Path: "",
 		Data: []byte{},
@@ -86,6 +93,16 @@ func TestNewQuerier(t *testing.T) {
 
 	_, err = querier(ctx, []string{"redelegations"}, query)
 	require.Nil(t, err)
+
+	queryHisParams := types.NewQueryHistoricalInfoParams(5)
+	bz, errRes = cdc.MarshalJSON(queryHisParams)
+	require.Nil(t, errRes)
+
+	query.Path = "/custom/staking/historicalInfo"
+	query.Data = bz
+
+	_, err = querier(ctx, []string{"historicalInfo"}, query)
+	require.Nil(t, err)
 }
 
 func TestQueryParametersPool(t *testing.T) {
@@ -551,3 +568,45 @@ func TestQueryUnbondingDelegation(t *testing.T) {
 	require.NoError(t, cdc.UnmarshalJSON(res, &ubDels))
 	require.Equal(t, 0, len(ubDels))
 }
+
+func TestQueryHistoricalInfo(t *testing.T) {
+	cdc := codec.New()
+	ctx, _, keeper, _ := CreateTestInput(t, false, 10000)
+
+	// Create Validators and Delegation
+	val1 := types.NewValidator(addrVal1, pk1, types.Description{})
+	val2 := types.NewValidator(addrVal2, pk2, types.Description{})
+	vals := []types.Validator{val1, val2}
+	keeper.SetValidator(ctx, val1)
+	keeper.SetValidator(ctx, val2)
+
+	header := abci.Header{
+		ChainID: "HelloChain",
+		Height:  5,
+	}
+	hi := types.NewHistoricalInfo(header, vals)
+	keeper.SetHistoricalInfo(ctx, 5, hi)
+
+	queryHistoricalParams := types.NewQueryHistoricalInfoParams(4)
+	bz, errRes := cdc.MarshalJSON(queryHistoricalParams)
+	require.Nil(t, errRes)
+	query := abci.RequestQuery{
+		Path: "/custom/staking/historicalInfo",
+		Data: bz,
+	}
+	res, err := queryHistoricalInfo(ctx, query, keeper)
+	require.NotNil(t, err, "Invalid query passed")
+	require.Nil(t, res, "Invalid query returned non-nil result")
+
+	queryHistoricalParams = types.NewQueryHistoricalInfoParams(5)
+	bz, errRes = cdc.MarshalJSON(queryHistoricalParams)
+	require.Nil(t, errRes)
+	query.Data = bz
+	res, err = queryHistoricalInfo(ctx, query, keeper)
+	require.Nil(t, err, "Valid query passed")
+	require.NotNil(t, res, "Valid query returned nil result")
+
+	var recv types.HistoricalInfo
+	require.NoError(t, cdc.UnmarshalJSON(res, &recv))
+	require.Equal(t, hi, recv, "HistoricalInfo query returned wrong result")
+}

x/staking/module.go

@@ -165,7 +165,9 @@ func (am AppModule) ExportGenesis(ctx sdk.Context) json.RawMessage {
 }
 
 // BeginBlock returns the begin blocker for the staking module.
-func (AppModule) BeginBlock(_ sdk.Context, _ abci.RequestBeginBlock) {}
+func (am AppModule) BeginBlock(ctx sdk.Context, _ abci.RequestBeginBlock) {
+	BeginBlocker(ctx, am.keeper)
+}
 
 // EndBlock returns the end blocker for the staking module. It returns no validator
 // updates.

x/staking/simulation/genesis.go

@@ -50,7 +50,7 @@ func RandomizedGenState(simState *module.SimulationState) {
 	// NewSimulationManager constructor for this to work
 	simState.UnbondTime = unbondTime
 
-	params := types.NewParams(simState.UnbondTime, maxValidators, 7, sdk.DefaultBondDenom)
+	params := types.NewParams(simState.UnbondTime, maxValidators, 7, 3, sdk.DefaultBondDenom)
 
 	// validators & delegations
 	var (

x/staking/types/errors.go

@@ -14,14 +14,15 @@ type CodeType = sdk.CodeType
 const (
 	DefaultCodespace sdk.CodespaceType = ModuleName
 
-	CodeInvalidValidator  CodeType = 101
-	CodeInvalidDelegation CodeType = 102
-	CodeInvalidInput      CodeType = 103
-	CodeValidatorJailed   CodeType = 104
-	CodeInvalidAddress    CodeType = sdk.CodeInvalidAddress
-	CodeUnauthorized      CodeType = sdk.CodeUnauthorized
-	CodeInternal          CodeType = sdk.CodeInternal
-	CodeUnknownRequest    CodeType = sdk.CodeUnknownRequest
+	CodeInvalidValidator      CodeType = 101
+	CodeInvalidDelegation     CodeType = 102
+	CodeInvalidInput          CodeType = 103
+	CodeValidatorJailed       CodeType = 104
+	CodeInvalidHistoricalInfo CodeType = 105
+	CodeInvalidAddress        CodeType = sdk.CodeInvalidAddress
+	CodeUnauthorized          CodeType = sdk.CodeUnauthorized
+	CodeInternal              CodeType = sdk.CodeInternal
+	CodeUnknownRequest        CodeType = sdk.CodeUnknownRequest
 )
 
 //validator
@@ -212,3 +213,11 @@ func ErrNeitherShareMsgsGiven(codespace sdk.CodespaceType) sdk.Error {
 func ErrMissingSignature(codespace sdk.CodespaceType) sdk.Error {
 	return sdk.NewError(codespace, CodeInvalidValidator, "missing signature")
 }
+
+func ErrInvalidHistoricalInfo(codespace sdk.CodespaceType) sdk.Error {
+	return sdk.NewError(codespace, CodeInvalidHistoricalInfo, "invalid historical info")
+}
+
+func ErrNoHistoricalInfo(codespace sdk.CodespaceType) sdk.Error {
+	return sdk.NewError(codespace, CodeInvalidHistoricalInfo, "no historical info found")
+}