doc: documentation for the epoching module

proto/babylon/epoching/v1/epoching.proto

@@ -10,8 +10,11 @@ option go_package = "github.com/babylonchain/babylon/x/epoching/types";
 
 // Epoch is a structure that contains the metadata of an epoch
 message Epoch {
+  // epoch_number is the number of this epoch
   uint64 epoch_number = 1;
+  // current_epoch_interval is the epoch interval at the time of this epoch
   uint64 current_epoch_interval = 2;
+  // first_block_height is the height of the first block in this epoch
   uint64 first_block_height = 3;
   // last_block_time is the time of the last block in this epoch.
   // Babylon needs to remember the last header's time of each epoch to complete
@@ -33,7 +36,7 @@ message Epoch {
 }
 
 // QueuedMessage is a message that can change the validator set and is delayed
-// to the epoch boundary
+// to the end of an epoch
 message QueuedMessage {
   // tx_id is the ID of the tx that contains the message
   bytes tx_id = 1;

x/epoching/abci.go

@@ -29,7 +29,7 @@ func BeginBlocker(ctx context.Context, k keeper.Keeper) error {
 	defer telemetry.ModuleMeasureSince(types.ModuleName, time.Now(), telemetry.MetricKeyBeginBlocker)
 
 	sdkCtx := sdk.UnwrapSDKContext(ctx)
-	// record the current BlockHash
+	// record the current AppHash
 	k.RecordAppHash(ctx)
 
 	// if this block is the first block of the next epoch
@@ -38,7 +38,7 @@ func BeginBlocker(ctx context.Context, k keeper.Keeper) error {
 	if epoch.IsFirstBlockOfNextEpoch(ctx) {
 		// increase epoch number
 		incEpoch := k.IncEpoch(ctx)
-		// record the BlockHash referencing
+		// record the AppHash referencing
 		// the last block of the previous epoch
 		k.RecordSealerAppHashForPrevEpoch(ctx)
 		// init the msg queue of this new epoch
@@ -62,7 +62,7 @@ func BeginBlocker(ctx context.Context, k keeper.Keeper) error {
 
 	if epoch.IsLastBlock(ctx) {
 		// record the block hash of the last block
-		// of the sealing epoch
+		// of the epoch to be sealed
 		k.RecordSealerBlockHashForEpoch(ctx)
 	}
 	return nil

x/epoching/keeper/epochs.go

@@ -82,7 +82,7 @@ func (k Keeper) RecordLastHeaderAndAppHashRoot(ctx context.Context) error {
 	return nil
 }
 
-// RecordSealerAppHashForPrevEpoch records the BlockHash referencing
+// RecordSealerAppHashForPrevEpoch records the AppHash referencing
 // the last block of the previous epoch
 func (k Keeper) RecordSealerAppHashForPrevEpoch(ctx context.Context) *types.Epoch {
 	epoch := k.GetEpoch(ctx)
@@ -98,7 +98,7 @@ func (k Keeper) RecordSealerAppHashForPrevEpoch(ctx context.Context) *types.Epoc
 		panic(err)
 	}
 
-	// record the sealer header for the sealed epoch
+	// record the sealer AppHash for the sealed epoch
 	sealedEpoch.SealerAppHash = header.AppHash
 	k.setEpochInfo(ctx, sealedEpoch.EpochNumber, sealedEpoch)
 

x/finality/README.md

@@ -332,9 +332,9 @@ message MsgUpdateParams {
 
 ## EndBlocker
 
-Upon `EndBlocker`, the Finality module of each Babylon node will execute the
-following *if the BTC staking protocol is activated (i.e., there has been >=1
-active BTC delegations)*:
+Upon `EndBlocker`, the Finality module of each Babylon node will [execute the
+following](./abci.go) *if the BTC staking protocol is activated (i.e., there has
+been >=1 active BTC delegations)*:
 
 1. Index the current block, i.e., extract its height and `AppHash`, construct an
    `IndexedBlock` object, and save it to the indexed block storage.

x/zoneconcierge/README.md

@@ -31,6 +31,8 @@ There are two phases of integration for a consumer chain:
 - [Interaction with consumer chains under phase 2 integration](#interaction-with-consumer-chains-under-phase-2-integration)
 - [Queries](#queries)
 
+<!-- TODO: describe the PostHandler -->
+
 ## State
 
 The Zone Concierge module keeps handling IBC headers of consumer chains, and
@@ -126,6 +128,8 @@ message Params {
 }
 ```
 
+<!-- TODO: hooks -->
+
 ## Interaction with consumer chains under phase 1 integration
 
 <!-- TODO: mermaid flowchart for the interaction -->