More proto docs

proto/osmosis/epochs/genesis.proto

@@ -9,12 +9,10 @@ option go_package = "github.com/osmosis-labs/osmosis/v7/x/epochs/types";
 
 // EpochInfo is a struct that describes the data going into
 // a timer defined by the x/epochs module.
-// Each tim
 message EpochInfo {
   // Identifier is a unique reference to this particular timer.
   string identifier = 1;
   // Start time is the time at which the timer first ever ticks.
-  // (When time 0 is measured from)
   // If start time is in the future, the epoch will not begin until the start time.
   google.protobuf.Timestamp start_time = 2 [
     (gogoproto.stdtime) = true,
@@ -33,9 +31,24 @@ message EpochInfo {
   ];
   // current_epoch is the current epoch number, or in other words,
   // how many times has the timer 'ticked'.
-  // {TODO: Detail 0 condition, when 1 starts, etc.} 
+  // The first tick (current_epoch=1) is defined as 
+  // the first block whose blocktime is greater than the EpochInfo start_time.
   int64 current_epoch = 4;
-  // {TODO: Describe}
+  // Describes the start time of the current timer interval.
+  // The interval is (current_epoch_start_time, current_epoch_start_time + duration]
+  // When the timer ticks, this is set to current_epoch_start_time = last_epoch_start_time + duration
+  // only one timer tick for a given identifier can occur per block.
+  //
+  // NOTE! The current_epoch_start_time may diverge significantly from the wall-clock time the epoch began at.
+  // Wall-clock time of epoch start may be >> current_epoch_start_time.
+  // Suppose current_epoch_start_time = 10, duration = 5. Suppose the chain goes offline at t=14, 
+  // and comes back online at t=30, and produces blocks at every successive time. (t=31, 32, etc.)
+  // * The t=30 block will start the epoch for (10, 15]
+  // * The t=31 block will start the epoch for (15, 20]
+  // * The t=32 block will start the epoch for (20, 25]
+  // * The t=33 block will start the epoch for (25, 30]
+  // * The t=34 block will start the epoch for (30, 35]
+  // * The **t=36** block will start the epoch for (35, 40]
   google.protobuf.Timestamp current_epoch_start_time = 5 [
     (gogoproto.stdtime) = true,
     (gogoproto.nullable) = false,
@@ -45,7 +58,7 @@ message EpochInfo {
   // epoch timer has began yet.
   bool epoch_counting_started = 6;
   reserved 7;
-  // {TODO: Describe}
+  // This is the block height at which the current epoch started. (The block height at which the timer last ticked)
   int64 current_epoch_start_height = 8;
 }