UMT

Exchange timestamps with a peaq master clock using Universal Machine Time. Covers PTP subscriptions, network delay estimates, and callback values.

Universal Machine Time (UMT) gives machines a shared time reference: a master clock takes its time from the peaq chain, and devices exchange Precision Time Protocol (PTP) timestamps with it. The SDK’s subscribeToPtp returns the mean one-way network delay of each exchange; it does not adjust the local clock.

PTP on peaq

Block timestamps alone are too coarse for machines that have to agree on when something happened. UMT adds:

• Network delay estimates and timestamps expressed in nanoseconds
• A master clock whose time comes from chain state, so any party can check it
• A delay estimate computed from two timestamp exchanges

Architecture

Usage

This runs in any JavaScript project, server or client. Install the SDK first, see Install the peaq SDK.

subscribeToPtp(options, callback)

Parameter	Type	Required	Description
options.masterUrl	string	Yes	URL of the master clock server. peaq runs one at https://ptp.peaq.xyz, which reads the timestamp from the network as new blocks arrive.
options.interval	number	No	How often to exchange timestamps, in milliseconds. Defaults to 1000.
callback	function	Yes	Called with { offset, synchronizedTime } on every successful round.

subscribeToPtp returns a function that stops the subscription.

import { Sdk } from '@peaq-network/sdk';

const MASTER_URL = 'https://ptp.peaq.xyz';
// Subscribe to PTP updates
const unsubscribe = Sdk.subscribeToPtp(
 { masterUrl: MASTER_URL },
 ({ offset, synchronizedTime }) => {
   console.log(`Mean Network Delay: ${offset} nanoseconds`);
   console.log(`Local Time Plus Delay: ${synchronizedTime} nanoseconds`);
 }
);
// Stop receiving updates after 10 seconds
setTimeout(unsubscribe, 10_000);

With the default interval, the callback runs once per second until you unsubscribe.

Sample output

Mean Network Delay: 1849833 nanoseconds
Local Time Plus Delay: 1740669653296849833 nanoseconds

Both values are bigint nanoseconds, and synchronizedTime is a Unix timestamp.

• offset: the mean one-way network delay between the two exchanges. Clock skew between the local and master clocks cancels out of the formula and is not corrected.
• synchronizedTime: the local receive timestamp T1' plus offset. This value retains the local clock’s skew and does not represent the master clock time.

Timestamp exchange process

Each round does four things:

1. Sync message: GET {masterUrl}/sync returns the master timestamp T1. The local timestamp is recorded straight after the response as T1'.
2. Delay request: the local timestamp T2 is recorded, then POST {masterUrl}/delay_req returns the master timestamp T2'.
3. Mean network delay: offset = ((T1' - T1) - (T2 - T2')) / 2
4. Local time plus delay: synchronizedTime = T1' + offset

To correct the local clock against the master, call GET {masterUrl}/sync and POST {masterUrl}/delay_req yourself and compute the PTP offset of the local clock from the same four timestamps: ((T1' - T1) - (T2' - T2)) / 2. Subtract it from the local time to get master-clock time.

Error handling

If a round fails, for example on a network or server error, the SDK logs the error and skips the callback for that round. The subscription stays active and tries again on the next interval.