wallet/docs/libraries/time.md

---
title: time
sidebar: true
notmine: false
abstract: >-
       We plan to have a network with all parties agreeing on the consensus network time,
       peers running on linux systems that claim their tai time is accurate should
       stubbornly steer the consensus time to the tai time, but not too stubbornly
       because they can have a wrong tai time.
---

# timekeeping primitives

[chrono]:https://en.cppreference.com/w/cpp/chrono {target="_blank"}

the C++ library [chrono] reports the steady time, guaranteed not to jump,
and guaranteed to pass at very very close to one second per actual second,
but not guaranteed to have any particular relationship with any other machine,
the global official time, the system time, with no guarantees
that it is not wildly wrong, and which once in a while jumps by a second,
and, on C++20, the tai time, guaranteed to not jump.

However there are linux specific calls that report the system time,
the global posix time on linux, *and uncertainty in that time*.

``` c
#include <stdio.h>
#include <sys/timex.h>

int main()
{
    struct timex timex_info = {};
    timex_info.modes = 0;         /* explicitly don't adjust any time parameters */

    int ntp_result = ntp_adjtime(&timex_info);

    printf("Max       error: %9ld (us)\n", timex_info.maxerror);
    printf("Estimated error: %9ld (us)\n", timex_info.esterror);
    printf("Clock precision: %9ld (us)\n", timex_info.precision);
    printf("Jitter:          %9ld (%s)\n", timex_info.jitter,
           (timex_info.status & STA_NANO) ? "ns" : "us");
    printf("Synchronized:    %9s\n",
           (ntp_result >= 0 && ntp_result != TIME_ERROR) ? "yes" : "no");
    return 0;
}
```

# ad hoc consensus time

Those machines that do not have an accurate global time will try to be
at the median of all the machines that they have direct connection with
while biasing the consensus towards the passage of one second per second,
plus or minus a couple of milliseconds, by being a little bit off the median,
should the consensus time seem to be moving too fast or too slow -- which is
to say if the new consensus seems to have drifted from the old,
they will stubbornly drag their heels in moving to the new consensus.

Those that do have an accurate global time will try to be nearer to the
global time, while remaining inside two thirds of the distribution.
If the network
time differs by so from the authoritative tai time, they will be as
close as they can be to the authoritative tai time, while remaining inside
the majority consensus, thus causing the consensus to drift towards
the authoritative tai time.

# Bayesian consensus

(People agree on metalog distribution of consensus time)

[gamma distribution]:../estimating_frequencies_from_small_samples.html#beta-distribution
{target="_blank"}

[delta distribution]:../estimating_frequencies_from_small_samples.html#beta-distribution
{target="_blank"}

We could be really clever and represent the consensus by a
[gamma distribution], which for a continuous quantity such as
time means a two dimensional $α$ and a two dimensional $β$,
hyper parameters, but the mathematics of conjugate distributions
gets rather scary.

Or cleverer still and accommodate leap seconds by consensus
on both the time and the rate of passage of consensus time relative
to steady time by a [delta distribution], in which case we have
a three dimensional $α$ and $β$

But both distributions suffer from the pathology that outliers will have
large effect, when they should have little effect.

So we need a metalog distribution that represents the sum of two
distributions, one narrow, and one wide and long tailed.
So outliers affect primarily the long tailed distribution