package tezos-shell

Synchronisation heuristic

The synchronisation heuristic module handles a heuristic to decide whether a node is synchronized with respect to its peers. This heuristic is parameterized by two variables:

• threshold is the number of peers to take into account for the heuristic

• latency is the timestamp drift (in seconds) expected for the threshold best candidates (see below).

A node is either Not_synchronised or Synchronised. If the node is Synchronised the chain may be stuck (last block validated was a while ago). The heuristic needs to be updated every time a block is validated or if a peer sends a block which is already known as valid. In the following, we denote such a block as a `candidate`. The heuristic maintains a set of candidates such that there is at most one candidate per peer. Given a peer, the heuristic always keeps the most recent candidate.

The heuristic works as follows:

If t.threshold is negative then get_state t always returns Not_synchronised.

If t.threshold is 0 then get_state t always returns Synchronised {is_chain_stuck=false}.

Otherwise:

• The state is Synchronised {is_chain_stuck = false} if the set of candidates that are more recent than ``latency`` seconds from now has a cardinal equal or greater to ``threshold``.

• The state is Synchronised {is_chain_stuck = true} if all the following statements are respected:

1. threshold > 1

2. The ``threshold`` most recent candidates have the same timestamp.

3. There is no candidate more than ``latency`` seconds from now

• The state is Not_synchronised otherwise.

Notice that if threshold is 1, the state is either Synchronised {is_chain_stuck=false} or Not_synchronised.

This heuristic should be used with a small threshold: Between 2 and 10. Other values should be used with care and are mostly here for testing or debugging purpose.

Following the separation of concerns principle, the heuristic exports two modules:

• The Core module contains all the logic behind the heuristic described above and can be used as such.

• The Bootstrapping module provides facility to register callbacks when the status of the heuristic changes, and in particular defines a bootstrapped flag which is set to true if the heuristic was synchronised at least once.