Outline the block validation flow

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.