From 63733223fd61d3fdabbdf1a95e2894ff98bffa3c Mon Sep 17 00:00:00 2001 From: Neil Booth Date: Fri, 9 Feb 2018 18:43:08 +0800 Subject: [PATCH] Update docs for blockchain.headers.subscribe --- docs/PROTOCOL.rst | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/PROTOCOL.rst b/docs/PROTOCOL.rst index a8bf596..c84a076 100644 --- a/docs/PROTOCOL.rst +++ b/docs/PROTOCOL.rst @@ -434,14 +434,25 @@ Subscribe to receive block headers when a new block is found. **Response** - The *deserialized header* [2]_ of the current block. + The *deserialized header* [2]_ of the current block chain tip. **Notification Parameters** As this is a subcription, the client will receive a notification when a new block is found. The parameters are: - [**header**] + [**deserialized_header**] + + **NOTE**: if a new block comes in quickly so the server has not + finished processing the prior block(s), it may skip them and only + notify of the new tip. The protocol does not guarantee + notifications of all intermediate blocks. + + In a similar vein, the client also needs to be able to handle chain + reorganisations; in case of a re-org the new tip will not connect + directly onto the prior chain tip. The client needs to be able to + figure out where the connection point and request any missing block + headers. blockchain.numblocks.subscribe