From 561840fa260eb3ba757f83d37fe54091713b1f98 Mon Sep 17 00:00:00 2001
From: Aaron Craelius <aaronc@users.noreply.github.com>
Date: Mon, 9 Sep 2024 03:31:44 -0400
Subject: [PATCH] feat(schema): update event index definitions (#21565)

---
 schema/appdata/data.go | 41 +++++++++++++++++++++++++++++++++--------
 1 file changed, 33 insertions(+), 8 deletions(-)

diff --git a/schema/appdata/data.go b/schema/appdata/data.go
index 1ef3f012c1..a051af8f46 100644
--- a/schema/appdata/data.go
+++ b/schema/appdata/data.go
@@ -49,18 +49,23 @@ type EventData struct {
 
 // Event represents the data for a single event.
 type Event struct {
-	// TxIndex is the index of the transaction in the block to which this event is associated.
-	// It should be set to a negative number if the event is not associated with a transaction.
-	// Canonically -1 should be used to represent begin block processing and -2 should be used to
-	// represent end block processing.
+	// BlockStage represents the stage of the block at which this event is associated.
+	// If the block stage is unknown, it should be set to UnknownBlockStage.
+	BlockStage BlockStage
+
+	// TxIndex is the 1-based index of the transaction in the block to which this event is associated.
+	// If TxIndex is zero, it means that we do not know the transaction index.
+	// Otherwise, the index should start with 1.
 	TxIndex int32
 
-	// MsgIndex is the index of the message in the transaction to which this event is associated.
-	// If TxIndex is negative, this index could correspond to the index of the message in
-	// begin or end block processing if such indexes exist, or it can be set to zero.
+	// MsgIndex is the 1-based index of the message in the transaction to which this event is associated.
+	// If MsgIndex is zero, it means that we do not know the message index.
+	// Otherwise, the index should start with 1.
 	MsgIndex int32
 
-	// EventIndex is the index of the event in the message to which this event is associated.
+	// EventIndex is the 1-based index of the event in the message to which this event is associated.
+	// If EventIndex is zero, it means that we do not know the event index.
+	// Otherwise, the index should start with 1.
 	EventIndex int32
 
 	// Type is the type of the event.
@@ -73,6 +78,26 @@ type Event struct {
 	Attributes ToEventAttributes
 }
 
+// BlockStage represents the stage of block processsing for an event.
+type BlockStage int32
+
+const (
+	// UnknownBlockStage indicates that we do not know the block stage.
+	UnknownBlockStage BlockStage = iota
+
+	// PreBlockStage indicates that the event is associated with the pre-block stage.
+	PreBlockStage
+
+	// BeginBlockStage indicates that the event is associated with the begin-block stage.
+	BeginBlockStage
+
+	// TxProcessingStage indicates that the event is associated with the transaction processing stage.
+	TxProcessingStage
+
+	// EndBlockStage indicates that the event is associated with the end-block stage.
+	EndBlockStage
+)
+
 type EventAttribute = struct {
 	Key, Value string
 }