Recipe

TrueTime Primer

TrueTime is Meridian's bounded-uncertainty clock. Instead of returning a single instant, it returns an interval [earliest, latest] within which the true wall-clock time provably lies. This primer walks you through reading a TrueTime stamp, waiting out uncertainty, and ordering distributed writes safely.

01.Reading a TrueTime stamp

A call to tt.now()returns a pair of timestamps. The midpoint is your best estimate; the half-width is the epsilon. In a healthy region epsilon stays under 7 ms. If you see epsilon climb past 50 ms, the local time master has likely lost GPS or atomic sync.

02.Commit-wait, explained

To guarantee external consistency, a writer picks a commit timestamp s = tt.now().latestand then sleeps until tt.now().earliest > s. That sleep is the commit-wait. Once it elapses, every observer in the universe agrees the write happened before any subsequent transaction.

03.Putting it together

The snippet below shows the canonical write path. Note we never read a single clock value — we always read the interval, commit at the latest edge, and wait out the uncertainty before acknowledging the client.

import { tt } from "@meridian/truetime";

async function commit(tx) {
  const interval = tt.now();
  const s = interval.latest;

  await tx.prepare(s);

  // commit-wait: block until s is in the past for everyone
  while (tt.now().earliest <= s) {
    await sleep(1);
  }

  await tx.apply(s);
  return s;
}