fix(content): chain manager and block producer updates (#1181)

* updates chain manager and block producer sections

* excluding thin "chain" subsection and updating WinningPoSt text

* fixing broken references

* restructures block reception description

Co-authored-by: Hugo Dias <[email protected]>

content/algorithms/crypto/randomness.md

@@ -9,8 +9,6 @@ dashboardTests: 0
 
 # Randomness
 
-TODO: clean up stale .id/.go files
-
 Randomness is used throughout the protocol in order to generate values and extend the blockchain.
 Random values are drawn from a [drand](drand) beacon and appropriately formatted for usage.
 We describe this formatting below.
@@ -69,8 +67,6 @@ GetRandomness(dst, l, s):
 ```
 
 
-{{<embed src="/systems/filecoin_blockchain/struct/chain/chain.go" lang="go">}}
-
 ## Drawing tickets from the VRF-chain for proof inclusion
 
 In some places, the protocol needs randomness drawn from the Filecoin blockchain's VRF-chain (which generates [tickets](storage_power_consensus#tickets) with each new block) rather than from the random beacon, in order to tie certain proofs to a particular set of Filecoin blocks (i.e. a given chain or fork).
@@ -99,8 +95,6 @@ In plain language, this means:
 
 This ticket is then combined with a Domain Separation Tag, the round number sought and appropriate entropy to form randomness for various uses in the protocol.
 
-See the `GetRandomnessFromVRFChain` method below:
-{{<embed src="/systems/filecoin_blockchain/struct/chain/chain.go" lang="go">}}
 
 ## Entropy to be used with randomness
 

content/systems/filecoin_blockchain/struct/_index.md

@@ -3,7 +3,7 @@ title: Blocks
 bookCollapseSection: true
 weight: 1
 dashboardWeight: 1.5
-dashboardState: wip
+dashboardState: reliable
 dashboardAudit: missing
 dashboardTests: 0
 ---

content/systems/filecoin_blockchain/struct/block_producer/_index.md

@@ -1,8 +1,8 @@
 ---
 title: Block Producer
-weight: 5
+weight: 4
 dashboardWeight: 1.5
-dashboardState: incorrect
+dashboardState: reliable
 dashboardAudit: missing
 dashboardTests: 0
 ---
@@ -11,19 +11,15 @@ dashboardTests: 0
 
 ## Mining Blocks
 
-A miner registered with the storage power actor may begin generating and checking election tickets if it has proven storage meeting the [Minimum Miner Size](storage_power_consensus#minimum-miner-size) threshold requirement. 
+A miner registered with the storage power actor may begin generating and checking election tickets if it has proven storage that meets the [Minimum Miner Size](storage_power_consensus#minimum-miner-size) threshold requirement. 
 
 In order to do so, the miner must be running chain validation, and be keeping track of the most recent blocks received. A miner's new block will be based on parents from the previous epoch.
 
 ### Block Creation
 
-Producing a block for epoch `H` requires computing a tipset for epoch `H-1` (or possibly a prior epoch,
-if no blocks were received for that epoch). Using the state produced by this tipset, a miner can
-scratch winning ElectionPoSt ticket(s). 
-Armed with the requisite `ElectionPoStOutput`, as well as a new randomness ticket generated in this epoch, a miner can produce a new block.
+Producing a block for epoch `H` requires waiting for the beacon entry for that epoch and using it to run `GenerateElectionProof`. If `WinCount` ≥ 1 (i.e., when the miner is elected), the same beacon entry is used to run `WinningPoSt`. Armed by the `ElectionProof` ticket (output of `GenerateElectionProof`) and the `WinningPoSt` proof, the miner can produce an new block.
 
-See [VM Interpreter](interpreter) for details of parent tipset evaluation, and [Block](block) for constraints 
-on valid block header values. 
+See [VM Interpreter](interpreter) for details of parent tipset evaluation, and [Block](block) for constraints on valid block header values. 
 
 To create a block, the eligible miner must compute a few fields:
 
@@ -57,20 +53,12 @@ a winning ticket is found independently of block generation.
 
 ### Block Broadcast
 
-An eligible miner broadcasts the completed block to the network and, assuming everything was done correctly, 
-the network will accept it and other miners will mine on top of it, earning the miner a block reward!
+An eligible miner propagates the completed block to the network using the [GossipSub](gossip_sub) `/fil/blocks` topic and, assuming everything was done correctly, 
+the network will accept it and other miners will mine on top of it, earning the miner a block reward.
 
-Miners should output their valid block as soon as it is produced, otherwise they risk other miners receiving the block after the EPOCH_CUTOFF and not including them.
+Miners should output their valid block as soon as it is produced, otherwise they risk other miners receiving the block after the EPOCH_CUTOFF and not including them in the current epoch.
 
 ## Block Rewards
 
-{{< hint warning >}}
-TODO: Rework this.
-{{</ hint >}}
-Over the entire lifetime of the protocol, 1,400,000,000 FIL (`TotalIssuance`) will be given out to miners. Each of the miners who produced a block in a tipset will receive a block reward. 
-
-Note: Due to jitter in EC, and the gregorian calendar, there may be some error in the issuance schedule over time. This is expected to be small enough that it's not worth correcting for. Additionally, since the payout mechanism is transferring from the network account to the miner, there is no risk of minting *too much* FIL.
-
-{{< hint warning >}}
-TODO: Ensure that if a miner earns a block reward while undercollateralized, then `min(blockReward, requiredCollateral-availableBalance)` is garnished (transfered to the miner actor instead of the owner).
-{{</ hint >}}
+Block rewards are handled by the [Reward Actor](sysactors#rewardactor).
+Further details on the Block Reward are discussed in the [Filecoin Token](filecoin_token) section and details about the Block Reward Collateral are discussed in the [Miner Collaterals](miner_collaterals) section.

content/systems/filecoin_blockchain/struct/chain_manager/_index.md

@@ -1,8 +1,8 @@
 ---
 title: Chain Manager
-weight: 4
+weight: 3
 dashboardWeight: 1.5
-dashboardState: incorrect
+dashboardState: reliable
 dashboardAudit: missing
 dashboardTests: 0
 ---
@@ -13,32 +13,27 @@ The _Chain Manager_ is a central component in the blockchain system. It tracks a
 
 In so doing, the _chain manager_ is the central subsystem that handles bookkeeping for numerous other systems in a Filecoin node and exposes convenience methods for use by those systems, enabling systems to sample randomness from the chain for instance, or to see which block has been finalized most recently.
 
-The chain manager interfaces and functions are included here, but we expand on important details below for clarity.
 
-
-## Chain Expansion
+## Chain Extension
 
 ### Incoming block reception
 
-Once a block has been received and passes syntactic and semantic validation it must be added to the local datastore, regardless whether it is understood as the best tip at this point. Future blocks from other miners may be mined on top of it and in that case we will want to have it around to avoid refetching.
-
-> **NOTE:** To make certain validation checks simpler, blocks should be indexed by height and by parent set. That way sets of blocks with a given height and common parents may be quickly queried. It may also be useful to compute and cache the resultant aggregate state of blocks in these sets, this saves extra state computation when checking which state root to start a block at when it has multiple parents.
+For every incoming block, even if the incoming block is not added to the current heaviest tipset, the chain manager should add it to the appropriate subchain it is tracking, or keep track of it independently until either:
+- it is able to add to the current heaviest subchain, through the reception of another block in that subchain, or
+- it is able to discard it, as the block was mined before finality.
 
-Chain selection is a crucial component of how the Filecoin blockchain works. Every chain has an associated weight accounting for the number of blocks mined on it and so the power (storage) they track. It is always preferable to mine atop a heavier Tipset rather than a lighter one. While a miner may be foregoing block rewards earned in the past, this lighter chain is likely to be abandoned by other miners forfeiting any block reward earned as miners converge on a final chain. For more on this, see [chain selection](expected_consensus#chain-selection) in the Expected Consensus spec.
+It is important to note that ahead of finality, a given subchain may be abandoned for another, heavier one mined in a given round. In order to rapidly adapt to this, the chain manager must maintain and update all subchains being considered up to finality.
 
-However, ahead of finality, a given subchain may be abandoned in order of another, heavier one mined in a given round. In order to rapidly adapt to this, the chain manager must maintain and update all subchains being considered up to finality.
+Chain selection is a crucial component of how the Filecoin blockchain works. In brief, every chain has an associated weight accounting for the number of blocks mined on it and so the power (storage) they track. The full details of how selection works are provided in the [Chain Selection](expected_consensus#chain-selection) section.
 
-That is, for every incoming block, even if the incoming block is not added to the current heaviest tipset, the chain manager should add it to the appropriate subchain it is tracking, or keep track of it independently until either:
-- it is able to do so, through the reception of another block in that subchain
-- it is able to discard it, as that block was mined before finality
-
-We give an example of how this could work in the block reception algorithm.
+**Notes/Recommendations:**
+1. In order to make certain validation checks simpler, blocks should be indexed by height and by parent set. That way sets of blocks with a given height and common parents may be quickly queried.
+2. It may also be useful to compute and cache the resultant aggregate state of blocks in these sets, this saves extra state computation when checking which state root to start a block at when it has multiple parents.
+3. It is recommended that blocks are kept in the local datastore regardless of whether they are understood as the best tip at this point - this is to avoid having to refetch the same blocks in the future.
 
 ### ChainTipsManager
 
-The Chain Tips Manager is a subcomponent of Filecoin consensus that is technically up to the implementer, but since the pseudocode in previous sections reference it, it is documented here for clarity.
-
-The Chain Tips Manager is responsible for tracking all live tips of the Filecoin blockchain, and tracking what the current 'best' tipset is.
+The Chain Tips Manager is a subcomponent of Filecoin consensus that is responsible for tracking all live tips of the Filecoin blockchain, and tracking what the current 'best' tipset is.
 
 ```go
 // Returns the ticket that is at round 'r' in the chain behind 'head'

content/systems/filecoin_blockchain/struct/tipset/_index.md

@@ -32,11 +32,8 @@ The main Tipset structure in the Lotus implementation includes the following:
 {{<embed src="https://github.com/filecoin-project/lotus/blob/master/chain/types/tipset.go"  lang="go" symbol="TipSet">}}
 
 
-Semantic validation of a Tipset is performed in:
+Semantic validation of a Tipset includes the following checks.
 
 {{<embed src="https://github.com/filecoin-project/lotus/blob/master/chain/types/tipset.go"  lang="go" symbol="NewTipSet">}}
 
-Semantic validation includes the following checks:
-- The tipset should be composed of at least one block
-- All blocks within a tipset should have the same height
-- All blocks within a tipset have the same parents, both in terms of number of parents and in terms of CIDs.
+