diff --git a/content/algorithms/crypto/randomness.md b/content/algorithms/crypto/randomness.md index d680b4798..5b17e8b7a 100644 --- a/content/algorithms/crypto/randomness.md +++ b/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): ``` -{{}} - ## 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: -{{}} ## Entropy to be used with randomness diff --git a/content/systems/filecoin_blockchain/struct/_index.md b/content/systems/filecoin_blockchain/struct/_index.md index ef95484ce..94dbd90e8 100644 --- a/content/systems/filecoin_blockchain/struct/_index.md +++ b/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 --- diff --git a/content/systems/filecoin_blockchain/struct/block_producer/_index.md b/content/systems/filecoin_blockchain/struct/block_producer/_index.md index 2511630b6..b5a3f3ac2 100644 --- a/content/systems/filecoin_blockchain/struct/block_producer/_index.md +++ b/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. -{{}} -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). -{{}} +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. diff --git a/content/systems/filecoin_blockchain/struct/chain/_index.md b/content/systems/filecoin_blockchain/struct/chain/_index.md deleted file mode 100644 index 39017296c..000000000 --- a/content/systems/filecoin_blockchain/struct/chain/_index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Chain -weight: 3 -dashboardWeight: 1.5 -dashboardState: incorrect -dashboardAudit: missing -dashboardTests: 0 ---- - -# Chain - -A Chain is a sequence of tipsets, linked together. It is a single history of execution in the Filecoin blockchain. - -{{}} - diff --git a/content/systems/filecoin_blockchain/struct/chain/chain.go b/content/systems/filecoin_blockchain/struct/chain/chain.go deleted file mode 100644 index 23b521f01..000000000 --- a/content/systems/filecoin_blockchain/struct/chain/chain.go +++ /dev/null @@ -1,44 +0,0 @@ -package chain - -import ( - abi "github.com/filecoin-project/specs-actors/actors/abi" - builtin "github.com/filecoin-project/specs-actors/actors/builtin" - node_base "github.com/filecoin-project/specs/systems/filecoin_nodes/node_base" -) - -// Returns the tipset at or immediately prior to `epoch`. -// For negative epochs, it should return a tipset composed of the genesis block. -func (chain *Chain_I) TipsetAtEpoch(epoch abi.ChainEpoch) Tipset { - current := chain.HeadTipset() - genesisEpoch := abi.ChainEpoch(0) - for current.Epoch() > epoch && epoch >= genesisEpoch { - // for epoch <= genesisEpoch, this should return a single-block tipset that includes the genesis block - current = current.Parents() - } - - return current -} - -// Draws randomness from the tipset at or immediately prior to `epoch`. -func (chain *Chain_I) GetRandomnessFromVRFChain(epoch abi.ChainEpoch) abi.RandomnessSeed { - - ts := chain.TipsetAtEpoch(epoch) - // return ts.MinTicket().Digest() - return ts.MinTicket().DrawRandomness(epoch) -} - -func (chain *Chain_I) GetTicketProductionRandSeed(epoch abi.ChainEpoch) abi.RandomnessSeed { - return chain.RandomnessSeedAtEpoch(epoch - node_base.SPC_LOOKBACK_TICKET) -} - -func (chain *Chain_I) GetSealRandSeed(epoch abi.ChainEpoch) abi.RandomnessSeed { - return chain.RandomnessSeedAtEpoch(epoch - builtin.SPC_LOOKBACK_SEAL) -} - -func (chain *Chain_I) GetPoStChallengeRandSeed(epoch abi.ChainEpoch) abi.RandomnessSeed { - return chain.RandomnessSeedAtEpoch(epoch - builtin.SPC_LOOKBACK_POST) -} - -func (chain *Chain_I) RandomnessSeedAtEpoch(epoch abi.ChainEpoch) abi.RandomnessSeed { - panic("not implemented") -} diff --git a/content/systems/filecoin_blockchain/struct/chain/chain.id b/content/systems/filecoin_blockchain/struct/chain/chain.id deleted file mode 100644 index e9b1ca241..000000000 --- a/content/systems/filecoin_blockchain/struct/chain/chain.id +++ /dev/null @@ -1,46 +0,0 @@ -import abi "github.com/filecoin-project/specs-actors/actors/abi" -import block "github.com/filecoin-project/specs/systems/filecoin_blockchain/struct/block" - -type Chain struct { - HeadTipset Tipset - - TipsetAtEpoch(epoch abi.ChainEpoch) Tipset - RandomnessSeedAtEpoch(epoch abi.ChainEpoch) abi.RandomnessSeed - - // call by StorageMiningSubsystem during block production - GetTicketProductionRandSeed(epoch abi.ChainEpoch) abi.RandomnessSeed - - // call by StorageMiningSubsystem in sealing sector - GetSealRandSeed(epoch abi.ChainEpoch) abi.RandomnessSeed - - // call by StorageMiningSubsystem after sealing - GetPoStChallengeRandSeed(epoch abi.ChainEpoch) abi.RandomnessSeed -} - -// Checkpoint represents a particular block to use as a trust anchor -// in Consensus and ChainSync -// -// Note: a Block uniquely identifies a tipset (the parents) -// from here, we may consider many tipsets that _include_ Block -// but we must indeed include t and not consider tipsets that -// fork from Block.Parents, but do not include Block. -type Checkpoint &block.BlockHeader - -// SoftCheckpoint is a checkpoint that Filecoin nodes may use as they -// gain confidence in the blockchain. It is a unilateral checkpoint, -// and derived algorithmically from notions of probabilistic consensus -// and finality. -type SoftCheckpoint Checkpoint - -// TrustedCheckpoint is a Checkpoint that is trusted by the broader -// Filecoin Network. These TrustedCheckpoints are arrived at through -// the higher level economic consensus that surrounds Filecoin. -// TrustedCheckpoints: -// - MUST be at least 200,000 blocks old (>1mo) -// - MUST be at least -// - MUST be widely known and accepted -// - MAY ship with Filecoin software implementations -// - MAY be propagated through other side-channel systems -// For more, see the Checkpoints section. -// TODO: consider renaming as EconomicCheckpoint -type TrustedCheckpoint Checkpoint diff --git a/content/systems/filecoin_blockchain/struct/chain/tipset.id b/content/systems/filecoin_blockchain/struct/chain/tipset.id deleted file mode 100644 index 9b872ad05..000000000 --- a/content/systems/filecoin_blockchain/struct/chain/tipset.id +++ /dev/null @@ -1,20 +0,0 @@ -import abi "github.com/filecoin-project/specs-actors/actors/abi" -import block "github.com/filecoin-project/specs/systems/filecoin_blockchain/struct/block" -import clock "github.com/filecoin-project/specs/systems/filecoin_nodes/clock" -import st "github.com/filecoin-project/specs/systems/filecoin_vm/state_tree" - -type Tipset struct { - BlockCIDs [&block.BlockHeader] - Blocks [block.BlockHeader] - - Has(b block.Block) bool @(cached) - Parents Tipset @(cached) - StateTree st.StateTree @(cached) - Weight block.ChainWeight @(cached) - Epoch abi.ChainEpoch @(cached) - - // Returns the largest timestamp fom the tipset's blocks. - LatestTimestamp() clock.UnixTime @(cached) - // Returns the lexicographically smallest ticket from the tipset's blocks. - MinTicket() block.Ticket @(cached) -} diff --git a/content/systems/filecoin_blockchain/struct/chain_manager/_index.md b/content/systems/filecoin_blockchain/struct/chain_manager/_index.md index d4c907518..7ca83973d 100644 --- a/content/systems/filecoin_blockchain/struct/chain_manager/_index.md +++ b/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' diff --git a/content/systems/filecoin_blockchain/struct/tipset/_index.md b/content/systems/filecoin_blockchain/struct/tipset/_index.md index 2527dab04..7ce192d69 100644 --- a/content/systems/filecoin_blockchain/struct/tipset/_index.md +++ b/content/systems/filecoin_blockchain/struct/tipset/_index.md @@ -32,11 +32,8 @@ The main Tipset structure in the Lotus implementation includes the following: {{}} -Semantic validation of a Tipset is performed in: +Semantic validation of a Tipset includes the following checks. {{}} -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. +