From 7fde0a87d41c8eccd75e83e99ab410ce85749ab9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mamy=20Andr=C3=A9-Ratsimbazafy?= Date: Fri, 18 Dec 2020 13:03:39 +0100 Subject: [PATCH] Outline the block validation flow --- docs/block_validation_flow.md | 49 +++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/block_validation_flow.md diff --git a/docs/block_validation_flow.md b/docs/block_validation_flow.md new file mode 100644 index 000000000..b260bdadc --- /dev/null +++ b/docs/block_validation_flow.md @@ -0,0 +1,49 @@ +# Block Validation Flow + +This is a WIP document to explain the block validation flow. +This should be transformed into diagram that explain +the implicit block validation state machine. + +## Inputs + +Blocks can be received from the following sources: +- Gossipsub +- the NBC database +- a local validator block proposal +- Devtools: test suite, ncli, fuzzing + +The related base types are: +- BeaconBlockBody +- BeaconBlock + - BeaconBlockBody + - + metadata (slot, blockchain state before/after, proposer) +- BeaconBlockHeader + - metadata (slot, blockchain state before/after, proposer) + - merkle hash of the BeaconBlockBody +- SignedBeaconBlock + - BeaconBLock + - + BLS signature + +The base types are defined in the Eth2 specs. +On top, Nimbus builds new types to represent the level of trust and validation we have with regards to each BeaconBlock. +Those types allow the Nim compiler to help us ensure proper usage at compile-time and zero runtime cost. + +### TrustedBeaconBlocks + +A block that has been fully checked to be sound +both in regards to the blockchain protocol and its cryptographic signatures is known as a `TrustedBeaconBlock` or `TrustedSignedBeaconBlock`. +This allows skipping expensive signature checks. +Blocks are considered trusted if they come from: +- the NBC database +- produced by a local validator + +### SigVerifiedBeaconBlocks + +A block with a valid cryptographic signature is considered SigVerified. +This is a weaker guarantee than Trusted as the block might still be invalid according to the state transition function. +Such a block are produced if incoming gossip blocks' signatures are batched together for batch verification **before** being passed to state transition. + +### TransitionVerifiedBeaconBlocks + +A block that passes the state transition checks and can be successfully applied to the beacon chain is considered `TransitionVerified`. +Such a block can be produced if incoming blocks' signatures are batched together for batch verification **after** successfully passing state transition.