IEEE 1588 PTP

IEEE 1588 PTP

IEEE 1588 Precision Time Protocol (PTP) is one of the time-source paths a Roko validator can use to discipline its local clock. It is not a chain-wide synchronization guarantee: validator-to-validator agreement happens in Roko's own time mesh, and PTP (typically via a Timebeat daemon) is one of the recognized ways to feed that mesh a high-quality local clock.

This page explains where PTP sits in the architecture and gives working configuration for operators who run it.

Where PTP fits

Two distinct layers are easy to conflate:

1. Local clock discipline (PTP's job). PTP, chrony/NTP, or a directly-attached GNSS/PPS receiver keeps your machine's clock close to UTC. The node's time-source detector recognizes a Timebeat PTP daemon, chrony, GNSS/PPS hardware, and NIC hardware timestamping, and announces your measured root distance to the network.

2. Inter-validator agreement (the time mesh's job). Validators converge on a shared mesh consensus time using PTP Squared — a native Rust time-sync layer running over the libp2p protocol `/roko/timesync/1`, with lucky-packet offset estimation, Welch's t-test reputation scoring, convergence detection, and path-cost source selection.

The PTP Squared algorithms credit Lasse Limkilde Johnsen's September 2021 Technical Preview — the "squared" name reflects PTP-style offset exchange applied pairwise across the whole validator mesh rather than against a single grandmaster.

Mesh results reach the chain as a block inherent consumed by the timesync pallet, which stores per-block, per-validator time quality on-chain (fixed-point 0–10,000) and records health checkpoints every 100 blocks.

Running PTP under a validator

If you operate PTP infrastructure, the node will pick it up automatically in `Auto` mode. The config below is the team's production-vintage `ptp4l` setup (engineering reference from earlier hardware deployments — adapt to your network):

# /etc/linuxptp/ptp4l.conf
[global]
domainNumber            44     # ROKO domain
slaveOnly               1      # Validators are slaves to grandmaster
priority1               128
priority2               128
clockClass              248
free_running            0
dscp_event              46     # High-priority DSCP
dscp_general            34
network_transport       L2     # Layer 2 for lowest latency
delay_mechanism         E2E    # End-to-end
time_stamping           hardware
tx_timestamp_timeout    10

Then sync the system clock to the NIC's PTP hardware clock (PHC):

ptp4l -i eth0 -f /etc/linuxptp/ptp4l.conf -m
phc2sys -s /dev/ptp0 -c CLOCK_REALTIME -O 0 -m

Two field lessons baked into that config:

  • E2E, not P2P. The peer-to-peer delay mechanism doesn't work through non-PTP switches; end-to-end does.
  • Hardware timestamping, not software. Software timestamps showed 10–100 µs of jitter in trials — unusable for sub-microsecond discipline. Verify support with `ethtool -T eth0` before relying on a NIC.

The PHC drift trap

A PHC that is phase-locked to GPS PPS but has no continuous UTC anchor drifts unboundedly in whole seconds. The live Raspberry Pi testnet validator hit exactly this: its PHC drifted 2–7 seconds per afternoon, so the `--timesync-phc-path` flag was removed and the node reads the NTP-disciplined `CLOCK_REALTIME` instead. Never point the node at a PHC unless something (NMEA, disciplined NTP-to-PHC sync) keeps it anchored to UTC seconds.

What PTP is not, on Roko

  • Not a compliance requirement. No validator is required to run IEEE 1588. NTP-only validators classify as Standard tier and participate fully.
  • Not a shipped chain-wide sync guarantee. What the chain enforces is structural: every transaction gets an ECDSA-signed temporal receipt at pool admission, and block import rejects blocks that omit a receipted transaction past its 15-second inclusion deadline. Time-quality offences are defined (with slash fractions up to 5%) but enforcement is currently disabled in both compiled runtimes.

Operationally, you can watch your node's view of mesh agreement at any time via `temporal_getConsensusTime`, which returns the nanosecond consensus time, a time-quality score, convergence state, and peer count.

See also