package octez-shell-libs

  1. Overview
  2. Docs
Legend:
Library
Module
Module type
Parameter
Class
Class type

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).
type status = Tezos_shell_services.Chain_validator_worker_state.synchronisation_status =
  1. | Synchronised of {
    1. is_chain_stuck : bool;
    }
  2. | Not_synchronised

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.
module Core : sig ... end
module Bootstrapping : sig ... end
OCaml

Innovation. Community. Security.