YAKMESH integrates with quantum, atomic, GPS, PTP, and NTP time sources to enable precision-grade phase synchronization across the mesh network.

Trust Levels

Time sources are classified into trust levels based on their precision and reliability. Higher trust levels enable tighter phase tolerances for consensus operations.

Quick Reference Table

TimeSourceDetector Class

The TimeSourceDetector class automatically detects available time sources and selects the highest-quality option.

Basic Usage

import { 
  TimeSourceDetector, 
  TimeTrustLevel, 
  PhaseTolerance 
} from './oracle/time-source.js';

// Create detector with hardware detection enabled
const detector = new TimeSourceDetector({ 
  detectHardware: true,
  checkNtp: true,
  refreshInterval: 60000, // Re-check every minute
  verbose: true
});

// Start continuous monitoring
detector.start();

// Get detection results
const results = detector.detect();
console.log('Primary source:', results.primarySource);
console.log('Trust level:', results.trustLevel);
console.log('Phase tolerance:', results.phaseTolerance, 'ms');

Constructor Options

Key Methods

// Start continuous monitoring
detector.start();

// Stop monitoring
detector.stop();

// Manual detection
const results = detector.detect();

// Get current trust level
const trust = detector.getTrustLevel(); // 'atomic', 'gps', 'ntp', etc.

// Get phase tolerance in milliseconds
const tolerance = detector.getPhaseTolerance(); // e.g., 100

// Get NTP stratum equivalent
const stratum = detector.getStratum(); // e.g., 0, 1, 2, 16

// Check if atomic-tier time is available
if (detector.hasAtomicTime()) {
  console.log('Node can serve as time oracle');
}

// Check if high-precision time is available (atomic, GPS, or PTP)
if (detector.hasHighPrecisionTime()) {
  console.log('Node can validate tight phase windows');
}

// Get full status object for API responses
const status = detector.getStatus();

Event Handling

// Listen for detection events
detector.on('detected', (results) => {
  console.log('Time sources detected:', results);
  console.log('Primary:', results.primarySource);
  console.log('Trust:', results.trustLevel);
  console.log('Tolerance:', results.phaseTolerance, 'ms');
});

Device Paths

The detector checks platform-specific device paths for hardware time sources.

Linux

Windows

macOS (Darwin)

Detection Methods

Atomic Clock Detection

The detector identifies atomic clocks through multiple methods:

• Chrony sources reporting PPS or ATOM references
• PPS device names containing: atomic, csac, rubidium, caesium, sa.45
• PCIe devices via lspci matching time/clock/atomic keywords
• Windows: Jackson Labs CSAC driver processes

GPS Detection

GPS receivers are detected via:

• gpsd service status and gpspipe output
• Serial devices at standard GPS paths
• Associated PPS devices for high-precision timing
• Chrony sources with GPS references

PTP Detection

IEEE 1588 PTP synchronization is detected through:

• PTP hardware devices at /dev/ptpN
• ptp4l service with pmc queries for offset
• phc2sys process for PTP-to-system clock sync
• Meinberg PTP hardware (PTP270PEX) via lspci and mbgstatus

NTP Detection

NTP status is checked via:

• Chrony: chronyc tracking for stratum, offset, and server
• systemd-timesyncd: timedatectl show
• ntpd: ntpq -p for selected source
• Windows: w32tm /query /status
• macOS: sntp queries

Phase Configuration

Use createPhaseConfig() to generate phase epoch configuration based on detected time source quality.

import { 
  TimeSourceDetector, 
  createPhaseConfig 
} from './oracle/time-source.js';

const detector = new TimeSourceDetector({ detectHardware: true });
detector.detect();

const phaseConfig = createPhaseConfig(detector);

console.log(phaseConfig);
// {
//   trustLevel: 'atomic',
//   toleranceMs: 100,
//   epochDurationHours: 1,
//   gracePeriodMinutes: 1,
//   capabilities: {
//     canBeTimeOracle: true,
//     canValidateTightPhase: true,
//     canParticipateInConsensus: true
//   }
// }

Capabilities by Trust Level

Exported Constants

TimeTrustLevel

export const TimeTrustLevel = {
  QUANTUM: 'quantum',   // Quantum optical network (WR-PTP, optical atomic)
  ATOMIC: 'atomic',     // PCIe atomic clock (CSAC, Rubidium)
  GPS: 'gps',           // GPS with PPS signal
  PTP: 'ptp',           // IEEE 1588 PTP synchronized
  NTP: 'ntp',           // Standard NTP
  UNSYNC: 'unsync',     // No reliable time source
};

PhaseTolerance

export const PhaseTolerance = {
  [TimeTrustLevel.QUANTUM]: 1,       // ±1ms for quantum (sub-nanosecond capable)
  [TimeTrustLevel.ATOMIC]: 100,      // ±100ms for atomic
  [TimeTrustLevel.GPS]: 500,         // ±500ms for GPS
  [TimeTrustLevel.PTP]: 500,         // ±500ms for PTP
  [TimeTrustLevel.NTP]: 5000,        // ±5 seconds for NTP
  [TimeTrustLevel.UNSYNC]: 30000,    // ±30 seconds for unsync (degraded mode)
};

StratumLevel

export const StratumLevel = {
  [TimeTrustLevel.QUANTUM]: 0, // Quantum reference (highest)
  [TimeTrustLevel.ATOMIC]: 0,  // Reference clock
  [TimeTrustLevel.GPS]: 1,     // Primary server
  [TimeTrustLevel.PTP]: 1,     // Primary server
  [TimeTrustLevel.NTP]: 2,     // Secondary server
  [TimeTrustLevel.UNSYNC]: 16, // Unsynchronized
};

Helper Functions

Quick Detection

import { detectTimeSources } from './oracle/time-source.js';

// One-shot detection without continuous monitoring
const results = detectTimeSources();
console.log('Detected:', results.primarySource, 'at', results.trustLevel);

Singleton Instance

import { getTimeSourceDetector } from './oracle/time-source.js';

// Get or create the global detector instance
const detector = getTimeSourceDetector({ verbose: true });
detector.start();

// Subsequent calls return the same instance
const sameDetector = getTimeSourceDetector();
console.log(detector === sameDetector); // true