Bullet points for reactor and poolRoutine

blockchain/reactor.go

@@ -49,12 +49,13 @@ type BlockchainReactor struct {
 	// immutable
 	initialState sm.State
 
-	blockExec  *sm.BlockExecutor
-	store      *BlockStore
-	pool       *BlockPool
-	fastSync   bool
-	requestsCh chan BlockRequest
-	timeoutsCh chan p2p.ID
+	blockExec *sm.BlockExecutor
+	store     *BlockStore
+	pool      *BlockPool
+	fastSync  bool
+
+	requestsCh <-chan BlockRequest
+	timeoutsCh <-chan p2p.ID
 }
 
 // NewBlockchainReactor returns new reactor instance.
@@ -127,7 +128,8 @@ func (bcR *BlockchainReactor) GetChannels() []*p2p.ChannelDescriptor {
 
 // AddPeer implements Reactor by sending our state to peer.
 func (bcR *BlockchainReactor) AddPeer(peer p2p.Peer) {
-	if !peer.Send(BlockchainChannel, struct{ BlockchainMessage }{&bcStatusResponseMessage{bcR.store.Height()}}) {
+	if !peer.Send(BlockchainChannel,
+		struct{ BlockchainMessage }{&bcStatusResponseMessage{bcR.store.Height()}}) {
 		// doing nothing, will try later in `poolRoutine`
 	}
 	// peer is added to the pool once we receive the first

docs/specification/new-spec/blockchain_reactor.md

@@ -6,7 +6,21 @@ the blocks to disk and play blocks to the ABCI app.
 
 ## Block Reactor
 
-* coordinates synching with other peers
+* coordinates the pool for synching
+* coordinates the store for persistence
+* coordinates the playing of blocks towards the app using a sm.BlockExecutor
+* handles switching between fastsync and consensus
+* it is a p2p.BaseReactor
+* starts the pool.Start() and its poolRoutine()
+* registers all the concrete types and interfaces for serialisation
+
+### poolRoutine
+
+* requests blocks from a specific peer based on the pool
+* periodically asks for status updates
+* tries to switch to consensus
+* tries to sync the app by taking downloaded blocks from the pool, gives them to the app and stores
+  them on disk
 
 ## Block Pool