fe52c47570
This: * Re-organizes the docs into sections that align with what docs.filecoin.io becoming: * An installation section * A "getting started" section (lotus client focused) * A "storing" section (lotus client focused) * A "mining" section (miner focused) * A "build" section (developer focused) * An legacy "architecture" section is left in the last place. A few high-value documentation pages have been reviewed and updated with the latest recommendations: * Installation section and lotus setup * Miner setup * etc. ... Other pages have been correctly merged into the new relevant sections. Some pages have not been touched. The filesystem layout of the documentation has been changed into folders corresponding to the sections (as requested by @cw). Some pages that were not linked at all and/or where hidden, have been moved to "unclassified". This should make the porting of the Lotus documentation to docs.filecoin.io much easier, while ensuring it is more up to date than it was before. For the moment, this breaks most links as link-aliasing is not supported in lotus-docs.
138 lines
6.2 KiB
Markdown
138 lines
6.2 KiB
Markdown
# Incoming block validations
|
|
|
|
This document reviews the code flow that takes place inside the full node after receiving a new block from the GossipSub `/fil/blocks` topic and traces all of its protocol-related validation logic. We do not include validation logic *inside* the VM, the analysis stops at `(*VM).Invoke()`. The `V:` tag explicitly signals validations throughout the text.
|
|
|
|
## `modules.HandleIncomingBlocks()`
|
|
|
|
We subscribe to the `/fil/blocks` PubSub topic to receive external blocks from peers in the network and register a block validator that operates at the PubSub (`libp2p` stack) level, validating each PubSub message containing a Filecoin block header.
|
|
|
|
`V:` PubSub message is a valid CBOR `BlockMsg`.
|
|
|
|
`V:` Total messages in block are under `BlockMessageLimit`.
|
|
|
|
`V:` Aggregate message CIDs, encapsulated in the `MsgMeta` structure, serialize to the `Messages` CID in the block header (`ValidateMsgMeta()`).
|
|
|
|
`V:` Miner `Address` in block header is present and corresponds to a public-key address in the current chain state.
|
|
|
|
`V:` Block signature (`BlockSig`) is present and belongs to the public-key address retrieved for the miner (`CheckBlockSignature()`).
|
|
|
|
## `sub.HandleIncomingBlocks()`
|
|
|
|
Assemble a `FullBlock` from the received block header retrieving its Filecoin messages.
|
|
|
|
`V:` Block messages CIDs can be retrieved from the network and decode into valid CBOR `Message`/`SignedMessage`.
|
|
|
|
## `(*Syncer).InformNewHead()`
|
|
|
|
Assemble a `FullTipSet` populated with the single block received earlier.
|
|
|
|
`V:` `ValidateMsgMeta()` (already done in the topic validator).
|
|
|
|
`V:` Block's `ParentWeight` is greater than the one from the (first block of the) heaviest tipset.
|
|
|
|
## `(*Syncer).Sync()`
|
|
|
|
`(*Syncer).collectHeaders()`: we retrieve all tipsets from the received block down to our chain. Validation now is expanded to *every* block inside these tipsets.
|
|
|
|
`V`: Beacon entires are ordered by their round number.
|
|
|
|
`V:` Tipset `Parents` CIDs match the fetched parent tipset through block sync. (This check is not enforced correctly at the moment, see [issue](https://github.com/filecoin-project/lotus/issues/1918).)
|
|
|
|
## `(*Syncer).ValidateBlock()`
|
|
|
|
This function contains most of the validation logic grouped in separate closures that run asynchronously, this list does not reflect validation order then.
|
|
|
|
`V:` Block `Timestamp`:
|
|
* Is not bigger than current time plus `AllowableClockDriftSecs`.
|
|
* Is not smaller than previous block's `Timestamp` plus `BlockDelay` (including null blocks).
|
|
|
|
### Messages
|
|
|
|
We check all the messages contained in one block at a time (`(*Syncer).checkBlockMessages()`).
|
|
|
|
`V:` The block's `BLSAggregate` matches the aggregate of BLS messages digests and public keys (extracted from the messages `From`).
|
|
|
|
`V:` Each `secp256k1` message `Signature` is signed with the public key extracted from the message `From`.
|
|
|
|
`V:` Aggregate message CIDs, encapsulated in the `MsgMeta` structure, serialize to the `Messages` CID in block header (similar to `ValidateMsgMeta()` call).
|
|
|
|
`V:` For each message, in `ValidForBlockInclusion()`:
|
|
* Message fields `Version`, `To`, `From`, `Value`, `GasPrice`, and `GasLimit` are correctly defined.
|
|
* Message `GasLimit` is under the message minimum gas cost (derived from chain height and message length).
|
|
|
|
`V:` Actor associated with message `From` exists and is an account actor, its `Nonce` matches the message `Nonce`.
|
|
|
|
### Miner
|
|
|
|
`V:` Miner address is registered in the `Claims` HAMT of the Power actor.
|
|
|
|
### Compute parent tipset state
|
|
|
|
`V:` Block's `ParentStateRoot` CID matches the state CID computed from the parent tipset.
|
|
|
|
`V:` Block's `ParentMessageReceipts` CID matches receipts CID computed from the parent tipset.
|
|
|
|
### Winner
|
|
|
|
Draw randomness for current epoch with minimum ticket from previous tipset, using `ElectionProofProduction`
|
|
domain separation tag.
|
|
`V`: `ElectionProof.VRFProof` is computed correctly by checking BLS signature using miner's key.
|
|
`V`: Miner is not slashed in `StoragePowerActor`.
|
|
`V`: Check if ticket is a winning ticket:
|
|
```
|
|
h := blake2b(VRFProof)
|
|
lhs := AsInt(h) * totalNetworkPower
|
|
rhs := minerPower * 2^256
|
|
if lhs < rhs { return "Winner" } else { return "Not a winner" }
|
|
```
|
|
|
|
### Block signature
|
|
|
|
`V:` `CheckBlockSignature()` (same signature validation as the one applied to the incoming block).
|
|
|
|
### Beacon values check
|
|
|
|
`V`: Validate that all `BeaconEntries` are valid. Check that every one of them is a signature of a message: `previousSignature || round` signed using drand's public key.
|
|
`V`: All entries between `MaxBeaconRoundForEpoch` down to `prevEntry` (from previous tipset) are included.
|
|
|
|
### Verify VRF Ticket chain
|
|
|
|
Draw randomness for current epoch with minimum ticket from previous tipset, using `TicketProduction`
|
|
domain separation tag.
|
|
`V`: `VerifyVRF` using drawn randomness and miner public key.
|
|
|
|
### Winning PoSt proof
|
|
|
|
Draw randomness for current epoch with `WinningPoSt` domain separation tag.
|
|
Get list of sectors challanged in this epoch for this miner, based on the randomness drawn.
|
|
|
|
`V`: Use filecoin proofs system to verify that miner prooved access to sealed versions of these sectors.
|
|
|
|
## `(*StateManager).TipSetState()`
|
|
|
|
Called throughout the validation process for the parent of each tipset being validated. The checks here then do not apply to the received new head itself that started the validation process.
|
|
|
|
### `(*StateManager).computeTipSetState()`
|
|
|
|
`V:` Every block in the tipset should belong to different a miner.
|
|
|
|
### `(*StateManager).ApplyBlocks()`
|
|
|
|
We create a new VM with the tipset's `ParentStateRoot` (this is then the parent state of the parent of the tipset currently being validated) on which to apply all messages from all blocks in the tipset. For each message independently we apply the validations listed next.
|
|
|
|
### `(*VM).ApplyMessage()`
|
|
|
|
`V:` Basic gas and value checks in `checkMessage()`:
|
|
* Message `GasLimit` is bigger than zero.
|
|
* Message `GasPrice` and `Value` are set.
|
|
|
|
`V:` Message storage gas cost is under the message's `GasLimit`.
|
|
|
|
`V:` Message's `Nonce` matches nonce in actor retrieved from message's `From`.
|
|
|
|
`V:` Message's maximum gas cost (derived from its `GasLimit`, `GasPrice`, and `Value`) is under the balance of the actor retrieved from message's `From`.
|
|
|
|
### `(*VM).send()`
|
|
|
|
`V:` Message's transfer `Value` is under the balance in actor retrieved from message's `From`.
|