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, CAPABILITY_LEVEL } from 'yakmesh/security/sakshi';

// Create witness from observed facts about a node
const witness = new NodeWitness({
  nodeId: 'node-abc123',
  timeSource: 'gps',        // best available time source
  hasAESNI: true,           // hardware attestation result
  networkAgeDays: 45,
  uptimePercent: 0.98,
  karmaScore: 0.7,
});

// Observe derived capability level (not grant permissions!)
witness.capabilityLevel;        // → CAPABILITY_LEVEL.PRECISION_NODE, etc.
witness.capabilityInfo.name;    // → 'Precision Node'
witness.qualityScore;           // → composite quality (0-1)
witness.canProvideHighPrecisionTime;  // → true
witness.isHardwareAttested;     // → true
witness.reliabilityCoefficient; // → derived from observed uptime

Capability Observation

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

// Observed capability tiers — derived from facts, never granted
import { CAPABILITY_LEVEL, CAPABILITY_INFO } from 'yakmesh/security/sakshi';

const CAPABILITY_LEVEL = {
  ATOMIC_VETERAN: 'atomic_veteran',   // Atomic time + attested HW + history
  PRECISION_NODE: 'precision_node',   // Precision time + attested HW
  RELIABLE_NODE:  'reliable_node',    // Good time source + hardware
  STANDARD_NODE:  'standard_node',    // Standard time + hardware
  BASIC_NODE:     'basic_node',       // Basic participation
  NEW_NODE:       'new_node',         // New/unverified
};
// CAPABILITY_INFO[level] → { name, nepali, description, color }

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, analyzeDisagreement } from 'yakmesh/security/sakshi';

// The caller owns the history — a Map of nodeId → disagreement records
const history = new Map();

// Track each disagreement; returns the updated pattern assessment
const analysis = analyzeDisagreement(observation, expected, actual);
const pattern = trackDisagreementPattern(history, 'abc123', analysis);
// → {
//   nodeId: 'abc123',
//   totalDisagreements: 7,
//   benignRatio: 0.86,
//   dominantCause: 'TIME_DRIFT',
//   assessment: 'NORMAL'   // or 'NEEDS_OBSERVATION'
// }

// history.get('abc123') holds the full record:
// { disagreements: [...], causeCounts: Map, firstSeen: ts }
// Patterns are observational — no punishment is applied.

API Reference

SAKSHI

VIVAAD

SETU

Export	Description
`NodeWitness`	Observational witness class (no permissions!)
`CAPABILITY_LEVEL` / `CAPABILITY_INFO`	Observed capability tiers + metadata (witness, not permission)
`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(history, nodeId, analysis)`	Record a disagreement; returns pattern assessment
`analyzeDisagreement(observation, expected, actual)`	Classify a disagreement's likely cause

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.

Provenance full version history →

Introduced in v2.8.1 — SETU bridge functions for trust-tier integration.

v2.9.0 — Initial SAKSHI + VIVAAD release; VARNA removed (anti-yakmesh ethos). VEGATI behavior velocity monitor with 6 dimensions, σ-based alerts. NPU anomaly assessment via assessNode() with ONNX model (sakshi-anomaly) and CPU heuristic fallback (wired v3.0.0)