ChainSync jumping (CSJ) is an optimization for the ChainSync protocol that allows nodes to sync without downloading headers from all of the honest peers. This load is undesirable as it slows down all the peers involved.

The idea is to download the headers of a chain from a single peer (the dynamo) and then ask periodically to the other peers (the jumpers) whether they agree with the dynamo's chain.

When the jumpers disagree with the dynamo, the jumper with the oldest intersection is asked to compete with the dynamo in the GDD logic (becoming an objector). If the dynamo is disconnected, a new dynamo is elected and the objector is demoted to a jumper.

If the objector is disconnected, the syncing process continues with the dynamo and the remaining jumpers.

The main property of the algorithm is that it never downloads headers from more than two plausibly honest peers at a time (a dynamo and an objector). All other peers are either waiting their turn to compete with the dynamo, or are in agreement with it, or are disengaged (see next section).

The algorithm might still download headers redundantly from peers that do historical rollbacks. These rollbacks, however, constitute dishonest behavior, and CSJ does not concern itself with avoiding load to dishonest peers. Avoiding the load induced by dishonest peers on the syncing node would require additionally to disconnect peers that do historical rollbacks. This is not done by CSJ.

Interactions with the Genesis Density Disconnection logic ---------------------------------------------------------

It is possible that neither the dynamo nor the objector are disconnected. This could happen if: 1. They both serve the same chain, or 2. They both claim to have no more headers.

To avoid (1) CSJ checks that the objector disagrees with the dynamo at the point it claimed to disagree as a jumper. If the objector agrees with the dynamo, it is disengaged. A disengaged peer is not asked to jump or act as dynamo or objector. Instead, it continues to offer headers for the rest of the syncing. When the objector is disengaged, a new objector is elected among the dissenting jumpers. If there are no dissenting jumpers left, the syncing continues with the dynamo and the remaining jumpers.

To prevent the dynamo from agreeing with the objector instead, the dynamo is not allowed to rollback before the last jump it requested. If the dynamo tries to rollback before the last jump, it is disengaged and a new dynamo is elected.

To avoid (2) CSJ disengages a peer as soon as it claims to have no more headers. Syncing continues with a new elected dynamo or objector depending on the disengaged peer's role.

CSJ finishes and is turned off when all peers have been disengaged.

Interactions with the ChainSync client --------------------------------------

The ChainSync client interacts with CSJ through some callbacks that determine when the client should pause, download headers, or ask about agreement with a given point (jumping). See the Jumping type for more details.

CSJ depends on the ChainSync client to disconnect dynamos that have an empty genesis window after their intersection with the selection. This is necessary because otherwise there are no points to jump to, and CSJ could would get stuck when the dynamo blocks on the forecast horizon. See Note [Candidate comparing beyond the forecast horizon] in Ouroboros.Consensus.MiniProtocol.ChainSync.Client.

Interactions with the BlockFetch logic --------------------------------------

When syncing, the BlockFetch logic might request to change the dynamo with a call to rotateDynamo. This is because the choice of dynamo influences which peer is selected to download blocks. See the note "Interactions with ChainSync Jumping" in Ouroboros.Network.BlockFetch.Decision.BulkSync.

Interactions with the Limit on Patience ---------------------------------------

Jumpers don't leak the Limit on Patience (LoP) bucket until they are promoted to dynamos or objectors. And the leaking is stopped as soon as they are demoted.

If a jumper refrains from answering to jumps, they will be disconnected with the intersectTimeout (in ChainSyncTimeout).

A jumper answering just before the timeout will not delay the syncing process by a large amount. If they agree with the dynamo, the dynamo will be busy downloading headers and validating blocks while the jumper answers. If the jumper disagrees with the dynamo, CSJ will look for the precise intersection with the dynamo's chain. This could take a few minutes, but it is a path that will end up in one of the dynamo and the jumper being disconnected or disengaged.

Overview of the state transitions ---------------------------------

See ChainSyncJumpingState for the implementation of the states.

               j       ╔════════╗
           ╭────────── ║ Dynamo ║ ◀─────────╮
           │        ╭─ ╚════════╝           │f
           ▼        │         ▲             │
   ┌────────────┐   │         │     k     ┌──────────┐
   │ Disengaged │ ◀─│─────────│────────── │ Objector │
   └────────────┘   │   ╭─────│────────── └──────────┘
                    │   │     │             ▲    ▲ │
                   l│  g│     │e         b  │    │ │
                    │   │     │       ╭─────╯   i│ │c
                ╭╌╌╌▼╌╌╌▼╌╌╌╌╌╌╌╌╌╌╌╌╌│╌╌╌╌╌╌╌╌╌╌│╌▼╌╌╌╮
                ┆ ╔═══════╗  a   ┌──────┐  d   ┌─────┐ ┆
                ┆ ║ Happy ║ ───▶ │ LFI* │ ───▶ │ FI* │ ┆
                ┆ ╚═══════╝ ◀─╮  └──────┘      └─────┘ ┆
                ┆ Jumper      ╰─────┴────────────╯h    ┆
                ╰╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╯

• : LookingForIntersection and FoundIntersection, abbreviated for this drawing only; this abbreviation will not be used elsewhere.

In the following walk-through, we will point to transitions in the drawing between parentheses, like so: (a) (b+c) (e|f). We will use + to express that both transitions happen simultaneously (for different peers) and `|` to express a choice.

A new peer starts as the dynamo if there is no other peer or as a Happy jumper otherwise. The dynamo periodically requests jumps from happy jumpers who, in the ideal case, accept them and remain happy jumpers.

In the event that a jumper rejects a jump, it goes from Happy to LFI* (a). From there starts a back-and-forth of intersection search messages until the exact point of disagreement with the dynamo is found.

Once the exact point of disagreement is found, and if there is no objector yet, the jumper becomes the objector (b). If there is an objector, then we compare the intersection of the objector with the dynamo and the intersection of the jumper with the dynamo. If the jumper's intersection is strictly older, then the jumper replaces the objector, who is marked as FI* (b+c). Otherwise, the jumper is marked as FI* (d).

If the dynamo disconnects or is disengaged, one peer is elected as the new dynamo (e|f) and all the other peers revert to being happy jumpers (g+h).

If the objector disconnects or is disengaged, and there are FI* jumpers, then the one with the oldest intersection with the dynamo gets elected (i). Otherwise, we are left with no objector.

If the dynamo rolls back to a point older than the last jump it requested, it is disengaged (j), a new dynamo is elected (e|f), and all the other peers revert to being happy jumpers (g+h).

If the objector agrees with the dynamo, it is disengaged (k). If there are FI* jumpers, then one of them gets elected as the new objector (i). Otherwise, we are left with no objector.

If the dynamo or the objector claim to have no more headers, they are disengaged (j|k), triggering the same chain of effect as described in the two previous points.

The BlockFetch logic can ask to change the dynamo if it is not serving blocks fast enough. If there are other non-disengaged peers, all peers are demoted to happy jumpers (l+g+h) and a new dynamo is elected (e).