SAKSHI Observational System | YAKMESH Documentation

Core Philosophy

SAKSHI represents a fundamental shift from permission-based security to observation-based verification. Instead of asking "does this node have permission?", we ask "can this node prove it computed correctly?"

Anti-Patterns (Removed)

• Permissions: "Can this tier do X?"
• Weighted voting: "Higher tiers count more"
• Denial systems: "Block nodes that fail"
• Trust hierarchies: "Some nodes are more trusted"

"Systems of denial = attack vectors"

SAKSHI Patterns

• Observation: "What can this node prove?"
• Agreement: "Do the computations match?"
• Remediation: "Why did they disagree?"
• Capability: "What hardware does it have?"

"All agreeing attestations are equal"

SAKSHI: Witness System

NodeWitness Class

Observes and records a node's capabilities without granting or denying permissions. Note: There is no hasPermission() method — by design.

import { NodeWitness, WITNESS_CAPABILITY } from 'yakmesh/security/sakshi';

// Create witness for a node
const witness = new NodeWitness(nodeId, {
  capabilities: [
    WITNESS_CAPABILITY.AES_NI,
    WITNESS_CAPABILITY.HARDWARE_RNG,
    WITNESS_CAPABILITY.GPS_AVAILABLE
  ],
  observedSince: Date.now(),
  lastProofTime: Date.now()
});

// Observe capabilities (not grant permissions!)
witness.hasCapability(WITNESS_CAPABILITY.AES_NI);  // → true

// Record attestation
witness.recordAttestation({
  type: 'time_sync',
  value: Date.now(),
  proof: cryptoProof
});

// Get reliability score (based on proof history)
witness.getReliabilityScore();  // → 0.0 to 1.0

Capability Observation

Witnesses observe hardware capabilities — they don't grant or deny based on them.

// Capability categories
const WITNESS_CAPABILITY = {
  // Cryptographic Hardware
  AES_NI: 'aes_ni',               // AES hardware acceleration
  SHA_EXTENSIONS: 'sha_ext',       // SHA hardware extensions
  HARDWARE_RNG: 'hw_rng',          // Hardware random generator
  
  // Timing/Location
  GPS_AVAILABLE: 'gps',            // GPS receiver
  HIGH_PRECISION_CLOCK: 'hpc',     // High-precision timing
  NTP_SYNCED: 'ntp',               // NTP synchronization
  
  // Compute
  MULTI_CORE: 'multi_core',        // Multiple CPU cores
  GPU_COMPUTE: 'gpu',              // GPU for compute
  
  // Network
  LOW_LATENCY: 'low_lat',          // <50ms round-trip
  HIGH_BANDWIDTH: 'high_bw',       // >100Mbps
};

Attestation Fusion (Not Voting)

Key Distinction

SAKSHI uses sensor fusion, not voting. Multiple witnesses provide measurements; we combine them using mathematical techniques (weighted average, outlier rejection) — not political consensus.

import { fuseTimeAttestations, checkMathematicalAgreement } from 'yakmesh/security/sakshi';

// Multiple witnesses attest to a timestamp
const attestations = [
  { witnessId: 'node1', value: 1704067200000, proof: proof1 },
  { witnessId: 'node2', value: 1704067200005, proof: proof2 },
  { witnessId: 'node3', value: 1704067200003, proof: proof3 },
];

// Fuse attestations (weighted average, not voting)
const fused = fuseTimeAttestations(attestations);
// → { value: 1704067200003, confidence: 0.98, spread: 5 }

// Check if nodes agree on a computation
const result = checkMathematicalAgreement({
  expected: computeLocally(data),
  attestations: [
    { nodeId: 'A', result: resultA },
    { nodeId: 'B', result: resultB },
    { nodeId: 'C', result: resultC },
  ]
});

// Possible outcomes
result.status === 'AGREE'              // All match → accept
result.status === 'RECOMPUTE_AND_VERIFY'  // Mismatch → investigate

Note: On disagreement, we don't vote or ban — we analyze WHY they disagreed (see VIVAAD below).

VIVAAD: Disagreement Analysis

"Don't vote on who's wrong — understand why they disagree."

vivāda (विवाद) — Sanskrit for "dispute/disagreement"

Disagreement Causes

Most disagreements aren't malicious — they're hardware or timing issues.

Hardware (~70%)

• TIMEOUT — Computation took too long
• FLOATING_POINT_VARIANCE — FP precision differs
• NO_AES_NI — Missing hardware acceleration
• MEMORY_EXHAUSTION — Ran out of RAM
• NO_HARDWARE_RNG — Software RNG used

Timing (~15%)

• CLOCK_DRIFT — NTP not synced
• EPOCH_BOUNDARY — Computed at epoch edge
• PROCESSING_DELAY — Queue backup

Network (~10%)

• INCOMPLETE_DATA — Partial message received
• MESSAGE_ORDERING — Race condition
• STALE_CACHE — Old data used

Byzantine (~5%)

• DELIBERATE_WRONG — Intentional lie
• SYBIL_SUSPECTED — Fake identity
• ECLIPSE_ATTACK — Isolated from network

Analyze Disagreement

import { analyzeDisagreement, createRemediationPlan } from 'yakmesh/security/sakshi';

// When two nodes disagree
const analysis = analyzeDisagreement({
  expected: ourResult,
  received: theirResult,
  witnessProfile: theirWitness,
  networkContext: { latency: 150, packetLoss: 0.01 }
});

// → {
//   likelyCause: 'TIMEOUT',
//   confidence: 0.85,
//   category: 'HARDWARE',
//   evidence: ['computation_time: 5200ms', 'deadline: 5000ms']
// }

// Get remediation (not punishment!)
const plan = createRemediationPlan(analysis);
// → {
//   action: 'RETRY_WITH_LONGER_TIMEOUT',
//   suggestedTimeout: 7000,
//   notifyOperator: false
// }

Remediation (Not Punishment)

VIVAAD provides constructive remediation, not bans or penalties. There are no permanent bans — even Byzantine behavior gets remediation.

Remediation	When Used	Duration
`RETRY_COMPUTATION`	Transient failure, timeout	Immediate
`SYNC_CLOCK`	Clock drift detected	Until synced
`REQUEST_REBROADCAST`	Incomplete data	Immediate
`WAIT_FOR_EPOCH`	Epoch boundary issue	Next epoch
`SUGGEST_HARDWARE_UPGRADE`	Consistent capability issues	Informational
`INCREASE_OBSERVATION`	Pattern suggests issues	Temporary
`QUARANTINE_FOR_ANALYSIS`	Byzantine patterns	Until resolved
`NOTIFY_OPERATOR`	Needs human attention	N/A

Even "QUARANTINE_FOR_ANALYSIS" is temporary — the goal is diagnosis, not exile.

SETU: Trust-Tier Bridge

"Bridge the old with the new without breaking compatibility."

setu (सेतु) — Sanskrit for "bridge"

Bridging Functions

SETU provides backward-compatible bridges from the old trust-tier system to SAKSHI.

import { 
  witnessFromTrustProfile,
  trustProfileFromWitness,
  checkRevocationAgreement,
  aggregateAttestations,
  assessComputationTrust
} from 'yakmesh/security/sakshi';

// Convert old TrustProfile → new NodeWitness
const witness = witnessFromTrustProfile(trustProfile);

// Convert back for compatibility
const profile = trustProfileFromWitness(witness);

// Replace WeightedRevocationCalculator
const agreement = checkRevocationAgreement({
  revocationRequests: requests,
  targetNodeId: nodeToRevoke
});
// → { agreed: true, reason: 'ALL_COMPUTATIONS_MATCH' }
// or → { agreed: false, action: 'RECOMPUTE_AND_VERIFY' }

// Replace calculateEffectiveCount (no more weighted voting!)
const aggregated = aggregateAttestations(attestations);
// All agreeing attestations count equally

// Assess trust based on verifiable math
const trust = assessComputationTrust({
  nodeId: 'abc123',
  computations: recentComputations,
  proofs: cryptoProofs
});
// → { score: 0.95, basedOn: 'VERIFIED_COMPUTATIONS', not: 'TIER_LEVEL' }

Disagreement Pattern Tracking

VIVAAD tracks disagreement patterns over time to identify recurring issues and suggest systemic fixes.

import { trackDisagreementPattern, getPatternInsights } from 'yakmesh/security/sakshi';

// Track each disagreement
trackDisagreementPattern({
  nodeId: 'abc123',
  cause: 'TIMEOUT',
  timestamp: Date.now(),
  context: { computationType: 'PROOF_VERIFICATION' }
});

// Get insights for a node
const insights = getPatternInsights('abc123');
// → {
//   mostCommonCause: 'TIMEOUT',
//   frequency: 0.15,  // 15% of computations
//   trend: 'STABLE',  // or 'IMPROVING', 'DEGRADING'
//   suggestion: 'Node may benefit from hardware upgrade or reduced load'
// }

// Get network-wide patterns
const networkInsights = getPatternInsights();
// → {
//   byCategory: { HARDWARE: 0.70, TIMING: 0.15, NETWORK: 0.10, BYZANTINE: 0.05 },
//   hotspots: ['proof_verification', 'time_sync'],
//   trend: 'STABLE'
// }

API Reference

SAKSHI

VIVAAD

SETU

Export	Description
`NodeWitness`	Observational witness class (no permissions!)
`WITNESS_CAPABILITY`	Enum of observable hardware capabilities
`fuseTimeAttestations(arr)`	Sensor fusion for time attestations
`checkMathematicalAgreement(opts)`	Check if computations agree (no voting)
`AGREEMENT_RESULT`	Enum: AGREE, RECOMPUTE_AND_VERIFY

Export	Description
`DISAGREEMENT_CAUSE`	Enum of 16 disagreement causes
`CAUSE_CATEGORY`	Enum: HARDWARE, TIMING, NETWORK, BYZANTINE
`REMEDIATION`	Enum of 11 remediation actions
`analyzeDisagreement(opts)`	Analyze why nodes disagreed
`createRemediationPlan(analysis)`	Create constructive remediation plan
`trackDisagreementPattern(event)`	Track disagreement for pattern analysis
`getPatternInsights(nodeId?)`	Get insights from tracked patterns

Export	Description
`witnessFromTrustProfile(profile)`	Convert TrustProfile → NodeWitness
`trustProfileFromWitness(witness)`	Convert NodeWitness → TrustProfile
`checkRevocationAgreement(opts)`	Replace WeightedRevocationCalculator
`aggregateAttestations(arr)`	Replace calculateEffectiveCount (no weights!)
`assessComputationTrust(opts)`	Trust based on verified math, not tiers

VEGATI — Behavior Velocity Monitor

VEGATI (वेगति — "velocity, momentum") detects sudden behavioral changes that may indicate compromised keys, reputation farming, or insider threat activation. Each node builds a behavioral fingerprint using exponential moving averages; deviations trigger sigma-based alerts.

Behavior Dimensions

Dimension	What It Measures
`message_rate`	Messages per minute
`gossip_ratio`	Gossip vs direct messages
`error_rate`	Invalid messages / signatures
`attestation_rate`	Revocation attestations filed
`connection_churn`	Connect / disconnect frequency
`response_latency`	Average response time

Alert Levels (σ thresholds)

NORMAL

< 2σ

ELEVATED

≥ 2σ

WARNING

≥ 3σ

CRITICAL

≥ 4σ

Baseline requires ≥ 50 observations. EMA smoothing factor defaults to 0.1. Alert cooldown: 60 s. Profile TTL: 7 days.

NPU Anomaly Assessment

assessNode() feeds a 12-feature input vector into the sakshi-anomaly ONNX model for multi-class attack detection. Falls back to CPU heuristic (z-score aggregation) when ONNX Runtime is unavailable.

12-Feature Input Vector

#	Feature	Source
0–5	6 behavior dimensions	VEGATI profile
6	uptimePercent	Context (0–1)
7	networkAgeDays / 365	Context
8	karmaScore	KARMA trust model
9	hasAesni	Hardware attestation
10	timeSourceQuality	MANI (0=sys, 0.5=NTP, 1=PTP)
11	observationCount / 1000	Profile depth

Output Scores

anomalyScore

General anomaly probability (NPU + CPU fallback)

sybilScore

Sybil attack probability (NPU only)

eclipseScore

Eclipse attack probability (NPU only)

floodScore

Flood attack probability (NPU only)

NPU vs CPU

The NPU path returns per-attack-type scores (sybil, eclipse, flood). The CPU fallback can only compute a general anomalyScore — the individual attack scores are zero. Both paths receive identical feature vectors.

Version History

Version	Changes
v3.0.0	VEGATI behavior velocity monitor with 6 dimensions, σ-based alerts. NPU anomaly assessment via `assessNode()` with 12-feature ONNX model (sakshi-anomaly) and CPU heuristic fallback.
v2.8.2	Added SETU bridge functions for trust-tier integration
v2.8.1	Initial SAKSHI + VIVAAD release. Removed VARNA (anti-yakmesh ethos)