From 7925b695738b757a463fb7504756348dfa78d6a4 Mon Sep 17 00:00:00 2001
From: Steven Allen <steven@stebalien.com>
Date: Mon, 7 Jun 2021 17:52:57 -0700
Subject: [PATCH] doc(lotus-sim): document block generation logic

---
 cmd/lotus-sim/simulation/block.go | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/cmd/lotus-sim/simulation/block.go b/cmd/lotus-sim/simulation/block.go
index 677ba7a2f..3a1181c1c 100644
--- a/cmd/lotus-sim/simulation/block.go
+++ b/cmd/lotus-sim/simulation/block.go
@@ -13,6 +13,7 @@ import (
 
 const beaconPrefix = "mockbeacon:"
 
+// nextBeaconEntries returns a fake beacon entries for the next block.
 func (sim *Simulation) nextBeaconEntries() []types.BeaconEntry {
 	parentBeacons := sim.head.Blocks()[0].BeaconEntries
 	lastBeacon := parentBeacons[len(parentBeacons)-1]
@@ -28,6 +29,7 @@ func (sim *Simulation) nextBeaconEntries() []types.BeaconEntry {
 	}}
 }
 
+// nextTicket returns a fake ticket for the next block.
 func (sim *Simulation) nextTicket() *types.Ticket {
 	newProof := sha256.Sum256(sim.head.MinTicket().VRFProof)
 	return &types.Ticket{
@@ -35,6 +37,14 @@ func (sim *Simulation) nextTicket() *types.Ticket {
 	}
 }
 
+// makeTipSet generates and executes the next tipset from the given messages. This method:
+//
+// 1. Stores the given messages in the Chainstore.
+// 2. Creates and persists a single block mined by f01000.
+// 3. Creates a tipset from this block and executes it.
+// 4. Returns the resulting tipset.
+//
+// This method does _not_ mutate local state (although it does add blocks to the datastore).
 func (sim *Simulation) makeTipSet(ctx context.Context, messages []*types.Message) (*types.TipSet, error) {
 	parentTs := sim.head
 	parentState, parentRec, err := sim.sm.TipSetState(ctx, parentTs)