docs and CHANGELOG

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

@@ -5,7 +5,8 @@ import (
 	"github.com/cosmos/cosmos-sdk/x/staking/types"
 )
 
-// BeginBlocker will
+// 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

x/staking/keeper/historical_info.go

@@ -5,6 +5,7 @@ import (
 	"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)
@@ -19,6 +20,7 @@ func (k Keeper) GetHistoricalInfo(ctx sdk.Context, height int64) (hi types.Histo
 	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)
@@ -27,6 +29,7 @@ func (k Keeper) SetHistoricalInfo(ctx sdk.Context, height int64, hi types.Histor
 	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)

x/staking/types/historical_info.go

@@ -9,11 +9,14 @@ import (
 	sdkerrors "github.com/cosmos/cosmos-sdk/types/errors"
 )
 
+// HistoricalInfo contains the historical information that gets stored at each height
 type HistoricalInfo struct {
 	Header abci.Header
 	ValSet []Validator
 }
 
+//NewHistoricalInfo will create a historical information struct from header and valset
+// it will first sort valset before inclusion into historical info
 func NewHistoricalInfo(header abci.Header, valSet []Validator) HistoricalInfo {
 	sort.Sort(Validators(valSet))
 	return HistoricalInfo{
@@ -22,10 +25,12 @@ func NewHistoricalInfo(header abci.Header, valSet []Validator) HistoricalInfo {
 	}
 }
 
+// MustMarshalHistoricalInfo wll marshal historical info and panic on error
 func MustMarshalHistoricalInfo(cdc *codec.Codec, hi HistoricalInfo) []byte {
 	return cdc.MustMarshalBinaryLengthPrefixed(hi)
 }
 
+// MustUnmarshalHistoricalInfo wll unmarshal historical info and panic on error
 func MustUnmarshalHistoricalInfo(cdc *codec.Codec, value []byte) HistoricalInfo {
 	hi, err := UnmarshalHistoricalInfo(cdc, value)
 	if err != nil {
@@ -34,11 +39,13 @@ func MustUnmarshalHistoricalInfo(cdc *codec.Codec, value []byte) HistoricalInfo
 	return hi
 }
 
+// UnmarshalHistoricalInfo will unmarshal historical info and return any error
 func UnmarshalHistoricalInfo(cdc *codec.Codec, value []byte) (hi HistoricalInfo, err error) {
 	err = cdc.UnmarshalBinaryLengthPrefixed(value, &hi)
 	return hi, err
 }
 
+// ValidateHistoricalInfo will ensure HistoricalInfo is not nil and sorted
 func ValidateHistoricalInfo(hi HistoricalInfo) error {
 	if hi.ValSet != nil {
 		return sdkerrors.Wrap(ErrInvalidHistoricalInfo(DefaultCodespace), "ValidatorSer is nil")

x/staking/types/validator_test.go

@@ -331,7 +331,7 @@ func TestValidatorsSortDeterminism(t *testing.T) {
 			vals[j] = it
 		})
 
-		sort.Sort(Validators(vals))
+		Validators(vals).Sort()
 		require.True(t, reflect.DeepEqual(sortedVals, vals), "Validator sort returned different slices")
 	}
 }