package octez-shell-libs

  1. Overview
  2. Docs
package octez-shell-libs
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.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct