Precious time synchronization for the Yakmesh network.

v2.5.0

Overview

MANI (Metrological Anchoring for Network Integrity) provides precision time synchronization for the Yakmesh network. Quality of time determines phase tolerance for consensus operations— nodes with atomic clocks can participate in tighter consensus windows than those relying on NTP alone.

Trust Levels

MANI classifies time sources by their quality, like precious gems in a spiritual hierarchy. Higher-quality sources enable tighter consensus tolerances:

Core Components

ManiTimeDetector

Automatically detects available time sources like a pilgrim discovering MANI stones along the mountain path:

import { ManiTimeDetector, ManiTrustLevel } from 'yakmesh/oracle/time-source';

// Create and start the detector
const mani = new ManiTimeDetector({
  detectHardware: true,     // Scan for atomic clocks, GPS
  checkNtp: true,           // Check NTP status
  refreshInterval: 60000,   // Re-detect every minute
});

// Start continuous monitoring
mani.start();

// Get current detection results
const status = mani.detect();
console.log(`Trust Level: ${status.trustLevel}`);
console.log(`Phase Tolerance: ±${status.phaseTolerance}ms`);
console.log(`Primary Source: ${status.primarySource}`);

// Listen for changes
mani.on('trustLevelChanged', ({ previous, current }) => {
  console.log(`Time quality changed: ${previous} → ${current}`);
});

Phase Configuration

Generate phase tolerance settings based on detected time quality:

import { createPhaseConfig, ManiTrustLevel } from 'yakmesh/oracle/time-source';

// Get phase configuration for current trust level
const config = createPhaseConfig(ManiTrustLevel.ATOMIC);

console.log(config);
// {
//   trustLevel: 'atomic',
//   phaseTolerance: 100,
//   stratumLevel: 0,
//   capabilities: {
//     canBeTimeOracle: true,
//     canValidateTightPhase: true,
//     canParticipateInConsensus: true
//   }
// }

Hardware Detection

MANI automatically scans for precision time hardware:

Device Type	Linux Paths	Detection Method
PCIe Atomic Clock	/dev/pps0, vendor-specific	PCI device enumeration, driver detection
GPS Receiver	/dev/ttyUSB0, /dev/gps0	Serial port scan, NMEA detection
PTP Hardware	/dev/ptp0	IEEE 1588 capable NIC detection
NTP Status	chrony/ntpd sockets	Daemon status query

Configuration

const options = {
  // Hardware detection
  detectHardware: true,      // Scan for atomic clocks, GPS, PTP
  checkNtp: true,            // Check NTP daemon status
  
  // Custom device paths (override defaults)
  customDevices: {
    pps: ['/dev/my-atomic-clock'],
    gps: ['/dev/my-gps-receiver'],
  },
  
  // Monitoring
  refreshInterval: 60000,    // Re-detect interval (ms), 0 to disable
  verbose: false,            // Enable debug logging
};

Integration with Other Protocols

Backward Compatibility

For existing codebases using the original naming, legacy exports are maintained:

// Legacy imports still work
import { TimeSourceDetector, TimeTrustLevel, PhaseTolerance } from 'yakmesh/oracle/time-source';

// These map to the new MANI names
// TimeSourceDetector → ManiTimeDetector
// TimeTrustLevel → ManiTrustLevel
// PhaseTolerance → ManiPhaseTolerance