Merge #3594

3594: Update chain-sync documentation r=coot a=coot Fixes #3443. Co-authored-by: Marcin Szamotulski <[email protected]>
IntersectMBO · Feb 4, 2022 · e35ff11 · e35ff11
2 parents a3eafb5 + 0fc21ba
commit e35ff11
Show file tree

Hide file tree

Showing 2 changed files with 16 additions and 4 deletions.
diff --git a/docs/network-spec/miniprotocols.tex b/docs/network-spec/miniprotocols.tex
@@ -639,13 +639,20 @@ \subsection{State Machine}
 \item [\MsgFindIntersect{} {\boldmath $\langle point_{head} \rangle $}]
       Ask the producer to try to find an improved intersection point between
       the consumer and producer's chains.
-      The consumer sends a sequence {\boldmath $\langle point \rangle $}
-      and it is up to the producer
-      to find the first intersection point on its chain and send it back to the consumer.
+      The consumer sends a sequence {\boldmath $\langle point \rangle $} which
+      shall be ordered by perference (e.g. points with highest slot number
+      first) and it is up to the producer to find the first intersection point
+      on its chain and send it back to the consumer.  If an empty list of
+      points is send with \MsgFindIntersect{} the server will reply with
+      \MsgIntersectNotFound{}.  
 \item [\MsgIntersectFound{} {\boldmath $(point_{intersect} ,tip)$}]
       The producer replies with the first point of the request that is on his current chain.
       The consumer can decide whether to send more points.
       The message also tells the consumer about the $tip$ of the producer.
+      Whenever the server replies with \MsgIntersectFound{} the client can
+      expect the next update (i.e. a replay to \MsgRequestNext{}) to be
+      \MsgRollBackward{} to the specified $point_{intersect}$ (which makes
+      handling state updates on the client side easier).
 \item [\MsgIntersectNotFound{} {\boldmath $(tip)$}]
       The reply to the consumer that no intersection was found: none of the
       points the consumer supplied are on the producer chain.
@@ -803,6 +810,10 @@ \subsection{Implementation of the Chain Producer}
 Maximum depth of a fork in Ouroboros is bounded and the intersection will always be found with a small number of
 iterations of this algorithm.
 
+\subparagraph{Additional remarks}
+Note that by sending \MsgFindIntersect{} the server will not modify its
+\readpointer{}.
+
 \subsection{Implementation of the Chain Consumer}
 In principle, the chain consumer has to guard against a malicious chain producer
 as much as the other way around.

diff --git a/ouroboros-network/src/Ouroboros/Network/Protocol/ChainSync/Type.hs b/ouroboros-network/src/Ouroboros/Network/Protocol/ChainSync/Type.hs
@@ -105,7 +105,8 @@ instance Protocol (ChainSync header point tip) where
     -- | Ask the producer to try to find an improved intersection point between
     -- the consumer and producer's chains. The consumer sends a sequence of
     -- points and it is up to the producer to find the first intersection point
-    -- on its chain and send it back to the consumer.
+    -- on its chain and send it back to the consumer.  The list of points should
+    -- be ordered by the preference, e.g. highest slot number to lowest.
     --
     MsgFindIntersect :: [point]
                      -> Message (ChainSync header point tip)