quorum/docs/new-block-code-walkthrough.md

How a block gets added to the chain in quorum

A code walkthrough showing the making of a new block and how nodes receive and vote for it.

Pre-requisites for all nodes:

The BlockVoting service has been started with a block maker strategy in place

On the block maker

1. BlockMaker reaches its deadline waiting for a new block from others and fires an event to trigger the creation of a new one itself
2. The event is picked up by the BlockVoting loop
3. A new block is constructed, inserted into the chain
4. A ChainHeadEvent is published on BlockChain.chainEvents
5. A NewMinedBlockEvent is published
6. The NewMinedBlockEvent will eventually cause the ProtocolManager to broadcast the new block
7. Finally, the ChainHeadEvent will cause the node to reset its pending state and vote for its own block

On other nodes

1. Node receives a message notifying about new block
2. Enqueues it for import
3. The fetcher detects a new import has been queued
4. And imports it by calling ProtocolManager.insertChain()
5. Which in turn calls BlockChain.InsertChain(), which checks that the block was created by a block maker (via BlockValidator.ValidateBlock() -> ValidateHeader() -> ValidateExtraData()), and call BlockValidator.ValidateState() to check that its parent is the current head
6. It will then send a ChainHeadEvent on BlockChain.chainEvents
7. Which is processed in BlockVoting.run(), causing the Node's pending state to be reset and the node to vote for the new block