From 57af99d901fccd7078a4da910b665842321ac4cd Mon Sep 17 00:00:00 2001
From: Ethan Buchman <ethan@coinculture.info>
Date: Fri, 25 Jan 2019 15:01:39 -0500
Subject: [PATCH] types: comments on user vs internal events

Distinguish between user events and internal consensus events
---
 types/events.go | 31 ++++++++++++++++++++-----------
 1 file changed, 20 insertions(+), 11 deletions(-)

diff --git a/types/events.go b/types/events.go
index 9b3b158d8..b70bc9dc5 100644
--- a/types/events.go
+++ b/types/events.go
@@ -11,21 +11,30 @@ import (
 
 // Reserved event types (alphabetically sorted).
 const (
-	EventCompleteProposal    = "CompleteProposal"
-	EventLock                = "Lock"
+	// Block level events for mass consumption by users.
+	// These events are triggered from the state package,
+	// after a block has been committed.
+	// These are also used by the tx indexer for async indexing.
+	// All of this data can be fetched through the rpc.
 	EventNewBlock            = "NewBlock"
 	EventNewBlockHeader      = "NewBlockHeader"
-	EventNewRound            = "NewRound"
-	EventNewRoundStep        = "NewRoundStep"
-	EventPolka               = "Polka"
-	EventRelock              = "Relock"
-	EventTimeoutPropose      = "TimeoutPropose"
-	EventTimeoutWait         = "TimeoutWait"
 	EventTx                  = "Tx"
-	EventUnlock              = "Unlock"
-	EventValidBlock          = "ValidBlock"
 	EventValidatorSetUpdates = "ValidatorSetUpdates"
-	EventVote                = "Vote"
+
+	// Internal consensus events.
+	// These are used for testing the consensus state machine.
+	// They can also be used to build real-time consensus visualizers.
+	EventCompleteProposal = "CompleteProposal"
+	EventLock             = "Lock"
+	EventNewRound         = "NewRound"
+	EventNewRoundStep     = "NewRoundStep"
+	EventPolka            = "Polka"
+	EventRelock           = "Relock"
+	EventTimeoutPropose   = "TimeoutPropose"
+	EventTimeoutWait      = "TimeoutWait"
+	EventUnlock           = "Unlock"
+	EventValidBlock       = "ValidBlock"
+	EventVote             = "Vote"
 )
 
 ///////////////////////////////////////////////////////////////////////////////