Tags Cleanup & Docs (#3137)

PENDING.md

@@ -48,6 +48,9 @@ IMPROVEMENTS
   * [\#3158](https://github.com/cosmos/cosmos-sdk/pull/3158) Validate slashing genesis
 
 * SDK
+  * [\#3137](https://github.com/cosmos/cosmos-sdk/pull/3137) Add tag documentation
+    for each module along with cleaning up a few existing tags in the governance,
+    slashing, and staking modules.
   * [\#3093](https://github.com/cosmos/cosmos-sdk/issues/3093) Ante handler does no longer read all accounts in one go when processing signatures as signature
     verification may fail before last signature is checked.
 

cmd/gaia/app/app.go

@@ -193,7 +193,6 @@ func MakeCodec() *codec.Codec {
 
 // application updates every end block
 func (app *GaiaApp) BeginBlocker(ctx sdk.Context, req abci.RequestBeginBlock) abci.ResponseBeginBlock {
-
 	// mint new tokens for the previous block
 	mint.BeginBlocker(ctx, app.mintKeeper)
 
@@ -215,7 +214,6 @@ func (app *GaiaApp) BeginBlocker(ctx sdk.Context, req abci.RequestBeginBlock) ab
 // application updates every end block
 // nolint: unparam
 func (app *GaiaApp) EndBlocker(ctx sdk.Context, req abci.RequestEndBlock) abci.ResponseEndBlock {
-
 	tags := gov.EndBlocker(ctx, app.govKeeper)
 	validatorUpdates, endBlockerTags := stake.EndBlocker(ctx, app.stakeKeeper)
 	tags = append(tags, endBlockerTags...)

docs/spec/bank/tags.md

@@ -0,0 +1,12 @@
+# Tags
+
+The bank module emits the following events/tags:
+
+## Handlers
+
+### MsgSend
+
+| Key       | Value                     |
+|-----------|---------------------------|
+| sender    | {senderAccountAddress}    |
+| recipient | {recipientAccountAddress} |

docs/spec/distribution/tags.md

@@ -0,0 +1,30 @@
+# Tags
+
+The distribution module emits the following events/tags:
+
+## Handlers
+
+### MsgSetWithdrawAddress
+
+| Key       | Value                     |
+|-----------|---------------------------|
+| delegator | {delegatorAccountAddress} |
+
+### MsgWithdrawDelegatorRewardsAll
+
+| Key       | Value                     |
+|-----------|---------------------------|
+| delegator | {delegatorAccountAddress} |
+
+### MsgWithdrawDelegatorReward
+
+| Key              | Value                     |
+|------------------|---------------------------|
+| delegator        | {delegatorAccountAddress} |
+| source-validator | {srcOperatorAddress}      |
+
+### MsgWithdrawValidatorRewardsAll
+
+| Key              | Value                |
+|------------------|----------------------|
+| source-validator | {srcOperatorAddress} |

docs/spec/governance/tags.md

@@ -0,0 +1,38 @@
+# Tags
+
+The governance module emits the following events/tags:
+
+## EndBlocker
+
+| Key             | Value                                                |
+|-----------------|------------------------------------------------------|
+| proposal-result | proposal-passed\|proposal-rejected\|proposal-dropped |
+
+## Handlers
+
+### MsgSubmitProposal
+
+| Key                     | Value                    |
+|-------------------------|--------------------------|
+| action                  | proposal-vote            |
+| proposer                | {proposerAccountAddress} |
+| proposal-id             | {proposalID}             |
+| voting-period-start [0] | {proposalID}             |
+
+* [0] Tag only emitted if the voting period starts during the submission.
+
+### MsgVote
+
+| Key         | Value                 |
+|-------------|-----------------------|
+| action      | proposal-vote         |
+| voter       | {voterAccountAddress} |
+| proposal-id | {proposalID}          |
+
+### MsgDeposit
+
+| Key         | Value                     |
+|-------------|---------------------------|
+| action      | proposal-vote             |
+| depositor   | {depositorAccountAddress} |
+| proposal-id | {proposalID}              |

docs/spec/slashing/tags.md

@@ -0,0 +1,12 @@
+# Tags
+
+The slashing module emits the following events/tags:
+
+## Handlers
+
+### MsgUnjail
+
+| Key       | Value                      |
+|-----------|----------------------------|
+| action    | validator-unjailed         |
+| validator | {validatorOperatorAddress} |

docs/spec/staking/tags.md

@@ -0,0 +1,58 @@
+# Tags
+
+The staking module emits the following events/tags:
+
+## EndBlocker
+
+| Key                   | Value                                     |
+|-----------------------|-------------------------------------------|
+| action                | complete-unbonding\|complete-redelegation |
+| delegator             | {delegatorAccountAddress}                 |
+| source-validator      | {srcOperatorAddress}                      |
+| destination-validator | {dstOperatorAddress}                      |
+
+## Handlers
+
+### MsgCreateValidator
+
+| Key                   | Value                |
+|-----------------------|----------------------|
+| destination-validator | {dstOperatorAddress} |
+| moniker               | {validatorMoniker}   |
+| identity              | {validatorIdentity}  |
+
+### MsgEditValidator
+
+| Key                   | Value                |
+|-----------------------|----------------------|
+| destination-validator | {dstOperatorAddress} |
+| moniker               | {validatorMoniker}   |
+| identity              | {validatorIdentity}  |
+
+### MsgDelegate
+
+| Key                   | Value                                     |
+|-----------------------|-------------------------------------------|
+| delegator             | {delegatorAccountAddress}                 |
+| destination-validator | {dstOperatorAddress}                      |
+
+### MsgBeginRedelegate
+
+| Key                   | Value                                     |
+|-----------------------|-------------------------------------------|
+| delegator             | {delegatorAccountAddress}                 |
+| source-validator      | {srcOperatorAddress}                      |
+| destination-validator | {dstOperatorAddress}                      |
+| end-time [0]          | {delegationFinishTime}                    |
+
+* [0] Time is formatted in the RFC3339 standard
+
+### MsgBeginUnbonding
+
+| Key              | Value                     |
+|------------------|---------------------------|
+| delegator        | {delegatorAccountAddress} |
+| source-validator | {srcOperatorAddress}      |
+| end-time [0]     | {delegationFinishTime}    |
+
+* [0] Time is formatted in the RFC3339 standard

x/bank/handler.go

@@ -20,7 +20,6 @@ func NewHandler(k Keeper) sdk.Handler {
 // Handle MsgSend.
 func handleMsgSend(ctx sdk.Context, k Keeper, msg MsgSend) sdk.Result {
 	// NOTE: totalIn == totalOut should already have been checked
-
 	tags, err := k.InputOutputCoins(ctx, msg.Inputs, msg.Outputs)
 	if err != nil {
 		return err.Result()

x/distribution/handler.go

@@ -31,7 +31,6 @@ func NewHandler(k keeper.Keeper) sdk.Handler {
 // now we just perform action and save
 
 func handleMsgModifyWithdrawAddress(ctx sdk.Context, msg types.MsgSetWithdrawAddress, k keeper.Keeper) sdk.Result {
-
 	k.SetDelegatorWithdrawAddr(ctx, msg.DelegatorAddr, msg.WithdrawAddr)
 
 	tags := sdk.NewTags(
@@ -43,7 +42,6 @@ func handleMsgModifyWithdrawAddress(ctx sdk.Context, msg types.MsgSetWithdrawAdd
 }
 
 func handleMsgWithdrawDelegatorRewardsAll(ctx sdk.Context, msg types.MsgWithdrawDelegatorRewardsAll, k keeper.Keeper) sdk.Result {
-
 	k.WithdrawDelegationRewardsAll(ctx, msg.DelegatorAddr)
 
 	tags := sdk.NewTags(
@@ -55,7 +53,6 @@ func handleMsgWithdrawDelegatorRewardsAll(ctx sdk.Context, msg types.MsgWithdraw
 }
 
 func handleMsgWithdrawDelegatorReward(ctx sdk.Context, msg types.MsgWithdrawDelegatorReward, k keeper.Keeper) sdk.Result {
-
 	err := k.WithdrawDelegationReward(ctx, msg.DelegatorAddr, msg.ValidatorAddr)
 	if err != nil {
 		return err.Result()
@@ -71,7 +68,6 @@ func handleMsgWithdrawDelegatorReward(ctx sdk.Context, msg types.MsgWithdrawDele
 }
 
 func handleMsgWithdrawValidatorRewardsAll(ctx sdk.Context, msg types.MsgWithdrawValidatorRewardsAll, k keeper.Keeper) sdk.Result {
-
 	err := k.WithdrawValidatorRewardsAll(ctx, msg.ValidatorAddr)
 	if err != nil {
 		return err.Result()

x/gov/handler.go

@@ -88,21 +88,22 @@ func handleMsgVote(ctx sdk.Context, keeper Keeper, msg MsgVote) sdk.Result {
 }
 
 // Called every block, process inflation, update validator set
-func EndBlocker(ctx sdk.Context, keeper Keeper) (resTags sdk.Tags) {
+func EndBlocker(ctx sdk.Context, keeper Keeper) sdk.Tags {
 	logger := ctx.Logger().With("module", "x/gov")
-	resTags = sdk.NewTags()
+	resTags := sdk.NewTags()
 
 	inactiveIterator := keeper.InactiveProposalQueueIterator(ctx, ctx.BlockHeader().Time)
 	for ; inactiveIterator.Valid(); inactiveIterator.Next() {
 		var proposalID uint64
 
 		keeper.cdc.MustUnmarshalBinaryLengthPrefixed(inactiveIterator.Value(), &proposalID)
 		inactiveProposal := keeper.GetProposal(ctx, proposalID)
+
 		keeper.DeleteProposal(ctx, proposalID)
 		keeper.DeleteDeposits(ctx, proposalID) // delete any associated deposits (burned)
 
-		resTags = resTags.AppendTag(tags.Action, tags.ActionProposalDropped)
-		resTags = resTags.AppendTag(tags.ProposalID, []byte(string(proposalID)))
+		resTags = resTags.AppendTag(tags.ProposalID, []byte(fmt.Sprintf("%d", proposalID)))
+		resTags = resTags.AppendTag(tags.ProposalResult, tags.ActionProposalDropped)
 
 		logger.Info(
 			fmt.Sprintf("proposal %d (%s) didn't meet minimum deposit of %s (had only %s); deleted",
@@ -124,26 +125,30 @@ func EndBlocker(ctx sdk.Context, keeper Keeper) (resTags sdk.Tags) {
 		activeProposal := keeper.GetProposal(ctx, proposalID)
 		passes, tallyResults := tally(ctx, keeper, activeProposal)
 
-		var action []byte
+		var tagValue []byte
 		if passes {
 			keeper.RefundDeposits(ctx, activeProposal.GetProposalID())
 			activeProposal.SetStatus(StatusPassed)
-			action = tags.ActionProposalPassed
+			tagValue = tags.ActionProposalPassed
 		} else {
 			keeper.DeleteDeposits(ctx, activeProposal.GetProposalID())
 			activeProposal.SetStatus(StatusRejected)
-			action = tags.ActionProposalRejected
+			tagValue = tags.ActionProposalRejected
 		}
 
 		activeProposal.SetTallyResult(tallyResults)
 		keeper.SetProposal(ctx, activeProposal)
 		keeper.RemoveFromActiveProposalQueue(ctx, activeProposal.GetVotingEndTime(), activeProposal.GetProposalID())
 
-		logger.Info(fmt.Sprintf("proposal %d (%s) tallied; passed: %v",
-			activeProposal.GetProposalID(), activeProposal.GetTitle(), passes))
+		logger.Info(
+			fmt.Sprintf(
+				"proposal %d (%s) tallied; passed: %v",
+				activeProposal.GetProposalID(), activeProposal.GetTitle(), passes,
+			),
+		)
 
-		resTags = resTags.AppendTag(tags.Action, action)
-		resTags = resTags.AppendTag(tags.ProposalID, []byte(string(proposalID)))
+		resTags = resTags.AppendTag(tags.ProposalID, []byte(fmt.Sprintf("%d", proposalID)))
+		resTags = resTags.AppendTag(tags.ProposalResult, tagValue)
 	}
 
 	activeIterator.Close()

x/gov/tags/tags.go

@@ -19,4 +19,5 @@ var (
 	VotingPeriodStart = "voting-period-start"
 	Depositor         = "depositor"
 	Voter             = "voter"
+	ProposalResult    = "proposal-result"
 )

x/slashing/handler.go

@@ -2,6 +2,7 @@ package slashing
 
 import (
 	sdk "github.com/cosmos/cosmos-sdk/types"
+	"github.com/cosmos/cosmos-sdk/x/slashing/tags"
 )
 
 func NewHandler(k Keeper) sdk.Handler {
@@ -49,7 +50,10 @@ func handleMsgUnjail(ctx sdk.Context, msg MsgUnjail, k Keeper) sdk.Result {
 	// unjail the validator
 	k.validatorSet.Unjail(ctx, consAddr)
 
-	tags := sdk.NewTags("validator", []byte(msg.ValidatorAddr.String()))
+	tags := sdk.NewTags(
+		tags.Action, tags.ActionValidatorUnjailed,
+		tags.Validator, []byte(msg.ValidatorAddr.String()),
+	)
 
 	return sdk.Result{
 		Tags: tags,

x/slashing/tags/tags.go

@@ -0,0 +1,13 @@
+package tags
+
+import (
+	sdk "github.com/cosmos/cosmos-sdk/types"
+)
+
+// Slashing tags
+var (
+	ActionValidatorUnjailed = []byte("validator-unjailed")
+
+	Action    = sdk.TagAction
+	Validator = "validator"
+)

x/slashing/tick.go

@@ -1,7 +1,6 @@
 package slashing
 
 import (
-	"encoding/binary"
 	"fmt"
 
 	abci "github.com/tendermint/tendermint/abci/types"
@@ -11,13 +10,7 @@ import (
 )
 
 // slashing begin block functionality
-func BeginBlocker(ctx sdk.Context, req abci.RequestBeginBlock, sk Keeper) (tags sdk.Tags) {
-
-	// Tag the height
-	heightBytes := make([]byte, 8)
-	binary.LittleEndian.PutUint64(heightBytes, uint64(req.Header.Height))
-	tags = sdk.NewTags("height", heightBytes)
-
+func BeginBlocker(ctx sdk.Context, req abci.RequestBeginBlock, sk Keeper) sdk.Tags {
 	// Iterate over all the validators  which *should* have signed this block
 	// store whether or not they have actually signed it and slash/unbond any
 	// which have missed too many blocks in a row (downtime slashing)
@@ -37,5 +30,5 @@ func BeginBlocker(ctx sdk.Context, req abci.RequestBeginBlock, sk Keeper) (tags
 		}
 	}
 
-	return
+	return sdk.EmptyTags()
 }