From e993e856452996fdab492508da30a18a8a4356bf Mon Sep 17 00:00:00 2001
From: mona-i <josephenemona300@gmail.com>
Date: Sun, 19 Jul 2026 15:16:34 +0100
Subject: [PATCH 1/2] feat: voluntary exit message builder with offline cold
 storage signing #521
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements the full voluntary validator exit workflow per issue #521.

## What was changed

### New files
- src/utils/exitMessageBuilder.ts: SSZ-encodes VoluntaryExit{epoch, validator_index} (16 bytes, little-endian uint64), computes SHA-256 hash for audit log, validates BLS signature hex format, and fetches current epoch from /eth/v1/beacon/genesis with local fallback.
- src/utils/qrEncoder.ts: Wraps qrcode in binary/byte mode (Version 40, Medium ECC) to generate 512px PNG QR codes for the unsigned hex blob; enforces 2,953-byte Version-40 capacity limit.
- src/utils/sszSerialization.ts: Single stable import surface re-exporting all SSZ/serialization helpers from exitMessageBuilder.
- src/store/exitSlice.ts: Zustand store tracking 3-step wizard state, 60-second cooldown timer, per-epoch rate limiter (max 4 exits), signed blob, and IndexedDB audit entry ID. Adds advanceToSign() action for correct step 1→2 transition.
- src/hooks/useVoluntaryExit.ts: Drives the complete workflow: fetch epoch, rate-limit check, SSZ encode, IndexedDB audit log, 60s countdown, BLS hex validation, and beacon node broadcast via postVoluntaryExit.
- src/services/exitAuditStore.ts: IndexedDB (exit_audit_db v1) audit trail storing unsigned_msg_hash, timestamp, validator_index, and broadcast_status (pending/broadcast/failed/aborted) with SHA-256 tamper evidence.
- src/services/beaconChainService.ts: Extended with postVoluntaryExit(baseUrl, payload) that POSTs to /eth/v1/beacon/pool/voluntary_exits and throws on non-2xx responses.
- src/components/validators/ExitWorkflowWizard.tsx: 3-step wizard UI — Step 1: validator index input + QR code display + hex blob + cooldown timer; Step 2: signed blob paste/camera input with BLS format validation; Step 3: irreversibility warning + confirmation checkbox + broadcast button (enabled only after cooldown).

### Modified files
- src/store/exitSlice.ts: Added advanceToSign() action (step 1→2 transition without setting a signed blob) and updated setSignedBlob() to advance to broadcast-review step on success.
- src/components/validators/ExitWorkflowWizard.tsx: Fixed misplaced import (useExitStore was imported at the bottom of file — now at the top). Fixed I-have-signed-it button to call advanceToSign() instead of setSignedBlob('') which was invalid. Fixed step-3 render condition to show correctly after signature validation. Fixed broadcast button disabled logic to use loading flag instead of step value.
- src/components/validators/ValidatorDetail.tsx: Added Voluntary Exit button in the actions toolbar that opens ExitWorkflowWizard in an accessible modal overlay.

### New test
- src/__tests__/exitMessageBuilder.test.ts: Unit tests for SSZ encoding, hex utilities, SHA-256 hashing, BLS signature validation, domain constants, and QR payload bounds.
---
 src/__tests__/exitMessageBuilder.test.ts      | 145 +++++
 .../validators/ExitWorkflowWizard.tsx         | 586 ++++++++++++++++++
 src/components/validators/ValidatorDetail.tsx |  36 ++
 src/hooks/useVoluntaryExit.ts                 | 277 +++++++++
 src/services/exitAuditStore.ts                | 127 ++++
 src/store/exitSlice.ts                        | 175 ++++++
 src/utils/exitMessageBuilder.ts               | 139 +++++
 src/utils/qrEncoder.ts                        |  61 ++
 src/utils/sszSerialization.ts                 |  29 +
 9 files changed, 1575 insertions(+)
 create mode 100644 src/__tests__/exitMessageBuilder.test.ts
 create mode 100644 src/components/validators/ExitWorkflowWizard.tsx
 create mode 100644 src/hooks/useVoluntaryExit.ts
 create mode 100644 src/services/exitAuditStore.ts
 create mode 100644 src/store/exitSlice.ts
 create mode 100644 src/utils/exitMessageBuilder.ts
 create mode 100644 src/utils/qrEncoder.ts
 create mode 100644 src/utils/sszSerialization.ts

diff --git a/src/__tests__/exitMessageBuilder.test.ts b/src/__tests__/exitMessageBuilder.test.ts
new file mode 100644
index 0000000..3453b21
--- /dev/null
+++ b/src/__tests__/exitMessageBuilder.test.ts
@@ -0,0 +1,145 @@
+import { describe, expect, it } from 'vitest';
+import {
+  encodeVoluntaryExitSSZ,
+  bytesToHex,
+  hexToBytes,
+  buildUnsignedExitMessage,
+  isValidSignatureHex,
+  getVoluntaryExitDomain,
+  DOMAIN_VOLUNTARY_EXIT,
+  QR_MAX_PAYLOAD_BYTES,
+} from '../utils/exitMessageBuilder';
+
+describe('exitMessageBuilder', () => {
+  describe('encodeVoluntaryExitSSZ', () => {
+    it('produces a 16-byte buffer', () => {
+      const result = encodeVoluntaryExitSSZ({ epoch: 100, validatorIndex: 42 });
+      expect(result).toBeInstanceOf(Uint8Array);
+      expect(result.byteLength).toBe(16);
+    });
+
+    it('encodes epoch in the first 8 bytes as little-endian uint64', () => {
+      const result = encodeVoluntaryExitSSZ({ epoch: 1, validatorIndex: 0 });
+      const view = new DataView(result.buffer);
+      expect(view.getBigUint64(0, true)).toBe(1n);
+    });
+
+    it('encodes validator_index in bytes 8–15 as little-endian uint64', () => {
+      const result = encodeVoluntaryExitSSZ({ epoch: 0, validatorIndex: 999 });
+      const view = new DataView(result.buffer);
+      expect(view.getBigUint64(8, true)).toBe(999n);
+    });
+
+    it('encodes epoch=0 and validatorIndex=0 as all-zero bytes', () => {
+      const result = encodeVoluntaryExitSSZ({ epoch: 0, validatorIndex: 0 });
+      expect(result.every((b) => b === 0)).toBe(true);
+    });
+
+    it('handles large validator indices correctly', () => {
+      const validatorIndex = 500_000;
+      const result = encodeVoluntaryExitSSZ({ epoch: 12345, validatorIndex });
+      const view = new DataView(result.buffer);
+      expect(view.getBigUint64(8, true)).toBe(BigInt(validatorIndex));
+    });
+  });
+
+  describe('bytesToHex / hexToBytes roundtrip', () => {
+    it('converts bytes to hex string', () => {
+      const bytes = new Uint8Array([0x00, 0x01, 0xff, 0xab]);
+      expect(bytesToHex(bytes)).toBe('0001ffab');
+    });
+
+    it('roundtrips hex → bytes → hex', () => {
+      const original = new Uint8Array([0x04, 0x00, 0x00, 0x00, 0xde, 0xad, 0xbe, 0xef]);
+      const hex = bytesToHex(original);
+      const recovered = hexToBytes(hex);
+      expect(Array.from(recovered)).toEqual(Array.from(original));
+    });
+
+    it('hexToBytes handles 0x prefix', () => {
+      const hex = '0xdeadbeef';
+      const bytes = hexToBytes(hex);
+      expect(bytesToHex(bytes)).toBe('deadbeef');
+    });
+
+    it('hexToBytes throws on odd-length hex string', () => {
+      expect(() => hexToBytes('abc')).toThrow();
+    });
+  });
+
+  describe('buildUnsignedExitMessage', () => {
+    it('returns hexBlob, messageHash and sszBytes of correct lengths', async () => {
+      const result = await buildUnsignedExitMessage({ epoch: 42, validatorIndex: 100 });
+      // 16-byte SSZ → 32-char hex
+      expect(result.hexBlob).toHaveLength(32);
+      // SHA-256 → 64-char hex
+      expect(result.messageHash).toHaveLength(64);
+      expect(result.sszBytes.byteLength).toBe(16);
+    });
+
+    it('hexBlob matches bytesToHex of sszBytes', async () => {
+      const result = await buildUnsignedExitMessage({ epoch: 1, validatorIndex: 2 });
+      expect(result.hexBlob).toBe(bytesToHex(result.sszBytes));
+    });
+
+    it('produces deterministic output for the same input', async () => {
+      const a = await buildUnsignedExitMessage({ epoch: 100, validatorIndex: 9999 });
+      const b = await buildUnsignedExitMessage({ epoch: 100, validatorIndex: 9999 });
+      expect(a.hexBlob).toBe(b.hexBlob);
+      expect(a.messageHash).toBe(b.messageHash);
+    });
+
+    it('produces distinct output for different validator indices', async () => {
+      const a = await buildUnsignedExitMessage({ epoch: 100, validatorIndex: 1 });
+      const b = await buildUnsignedExitMessage({ epoch: 100, validatorIndex: 2 });
+      expect(a.hexBlob).not.toBe(b.hexBlob);
+      expect(a.messageHash).not.toBe(b.messageHash);
+    });
+  });
+
+  describe('isValidSignatureHex', () => {
+    const validSig = 'a'.repeat(192);
+    const validSigWithPrefix = '0x' + 'b'.repeat(192);
+
+    it('accepts a 192-char hex string without prefix', () => {
+      expect(isValidSignatureHex(validSig)).toBe(true);
+    });
+
+    it('accepts a 194-char hex string with 0x prefix', () => {
+      expect(isValidSignatureHex(validSigWithPrefix)).toBe(true);
+    });
+
+    it('rejects a signature that is too short', () => {
+      expect(isValidSignatureHex('a'.repeat(191))).toBe(false);
+    });
+
+    it('rejects a signature that is too long', () => {
+      expect(isValidSignatureHex('a'.repeat(193))).toBe(false);
+    });
+
+    it('rejects a signature with non-hex characters', () => {
+      expect(isValidSignatureHex('z'.repeat(192))).toBe(false);
+    });
+
+    it('rejects an empty string', () => {
+      expect(isValidSignatureHex('')).toBe(false);
+    });
+  });
+
+  describe('getVoluntaryExitDomain', () => {
+    it('returns the correct 4-byte domain', () => {
+      const domain = getVoluntaryExitDomain();
+      expect(domain).toEqual(new Uint8Array([0x04, 0x00, 0x00, 0x00]));
+    });
+
+    it('is consistent with the DOMAIN_VOLUNTARY_EXIT constant', () => {
+      expect(DOMAIN_VOLUNTARY_EXIT).toBe('0x04000000');
+    });
+  });
+
+  describe('QR_MAX_PAYLOAD_BYTES', () => {
+    it('is 2953 (Version-40 Medium ECC byte-mode capacity)', () => {
+      expect(QR_MAX_PAYLOAD_BYTES).toBe(2_953);
+    });
+  });
+});
diff --git a/src/components/validators/ExitWorkflowWizard.tsx b/src/components/validators/ExitWorkflowWizard.tsx
new file mode 100644
index 0000000..325a5bc
--- /dev/null
+++ b/src/components/validators/ExitWorkflowWizard.tsx
@@ -0,0 +1,586 @@
+'use client';
+
+/**
+ * ExitWorkflowWizard – 3-step guided UI for voluntary validator exits.
+ *
+ * Step 1 – Initiate: validator selection, unsigned message display (QR + hex),
+ *           cooldown timer starts.
+ * Step 2 – Sign:     accepts signed blob from air-gapped cold-storage device
+ *           (paste hex or QR scan via camera input).
+ * Step 3 – Broadcast: final confirmation with irreversibility warning,
+ *           rate-limit badge, broadcasts to beacon node.
+ */
+
+import { useState, useRef, useEffect, useCallback } from 'react';
+import { useVoluntaryExit } from '@/src/hooks/useVoluntaryExit';
+import { useExitStore } from '@/src/store/exitSlice';
+import { encodeExitQR } from '@/src/utils/qrEncoder';
+
+interface ExitWorkflowWizardProps {
+  /** Pre-fill a specific validator index (from the validator detail toolbar). */
+  defaultValidatorIndex?: number;
+  /** Beacon node URL for epoch fetching and broadcasting. */
+  beaconNodeUrl?: string;
+  /** Operator identifier written to the audit log. */
+  operatorId?: string;
+  onComplete?: () => void;
+  onClose?: () => void;
+}
+
+// ── Internal step helpers ────────────────────────────────────────────────────
+
+function StepIndicator({ current }: { current: 1 | 2 | 3 }) {
+  const steps = ['1. Initiate', '2. Sign', '3. Broadcast'] as const;
+  return (
+    <div className="mb-6 flex items-center gap-2">
+      {steps.map((label, i) => {
+        const n = (i + 1) as 1 | 2 | 3;
+        const active = n === current;
+        const done = n < current;
+        return (
+          <div key={n} className="flex items-center gap-2">
+            <div
+              className={`flex h-7 w-7 items-center justify-center rounded-full text-xs font-bold ${
+                done
+                  ? 'bg-emerald-500 text-white'
+                  : active
+                    ? 'bg-sky-500 text-white ring-2 ring-sky-400/40'
+                    : 'bg-slate-700 text-slate-400'
+              }`}
+            >
+              {done ? '✓' : n}
+            </div>
+            <span
+              className={`text-sm font-medium ${active ? 'text-white' : done ? 'text-emerald-400' : 'text-slate-500'}`}
+            >
+              {label}
+            </span>
+            {i < 2 && <span className="text-slate-600">→</span>}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+function CooldownBadge({ seconds }: { seconds: number }) {
+  const done = seconds === 0;
+  return (
+    <div
+      className={`flex items-center gap-2 rounded-xl border px-4 py-2 text-sm font-semibold ${
+        done
+          ? 'border-emerald-500/40 bg-emerald-500/10 text-emerald-300'
+          : 'border-amber-500/40 bg-amber-500/10 text-amber-300'
+      }`}
+      role="status"
+      aria-live="polite"
+      aria-label={done ? 'Cooldown complete' : `Cooldown: ${seconds} seconds remaining`}
+    >
+      <span>{done ? '✓' : '⏱'}</span>
+      <span>{done ? 'Cooldown complete — broadcast enabled' : `Cooldown: ${seconds}s remaining`}</span>
+    </div>
+  );
+}
+
+// ── Main component ──────────────────────────────────────────────────────────
+
+export function ExitWorkflowWizard({
+  defaultValidatorIndex,
+  beaconNodeUrl,
+  operatorId,
+  onComplete,
+  onClose,
+}: ExitWorkflowWizardProps) {
+  const {
+    step,
+    validatorIndex,
+    currentEpoch,
+    unsignedHexBlob,
+    messageHash,
+    signedBlob,
+    cooldownSecondsLeft,
+    cooldownComplete,
+    loading,
+    error,
+    initiateExit,
+    acceptSignedBlob,
+    broadcastExit,
+    abortExit,
+    reset,
+  } = useVoluntaryExit({ beaconNodeUrl, operatorId });
+
+  // ── Local state ────────────────────────────────────────────────────────────
+  const [validatorInput, setValidatorInput] = useState(
+    defaultValidatorIndex !== undefined ? String(defaultValidatorIndex) : '',
+  );
+  const [signedInput, setSignedInput] = useState('');
+  const [signedError, setSignedError] = useState('');
+  const [qrDataUrl, setQrDataUrl] = useState<string | null>(null);
+  const [qrError, setQrError] = useState('');
+  const [confirmChecked, setConfirmChecked] = useState(false);
+  const [broadcastSuccess, setBroadcastSuccess] = useState(false);
+  const videoRef = useRef<HTMLVideoElement | null>(null);
+  const [cameraActive, setCameraActive] = useState(false);
+  const [cameraError, setCameraError] = useState('');
+
+  // ── Generate QR when blob is ready ────────────────────────────────────────
+  useEffect(() => {
+    if (!unsignedHexBlob) { setQrDataUrl(null); return; }
+    encodeExitQR(unsignedHexBlob)
+      .then((r) => setQrDataUrl(r.dataUrl))
+      .catch((err) => setQrError(err instanceof Error ? err.message : 'QR generation failed'));
+  }, [unsignedHexBlob]);
+
+  // ── Watch for broadcast done ───────────────────────────────────────────────
+  useEffect(() => {
+    if (step === 'done') {
+      setBroadcastSuccess(true);
+      onComplete?.();
+    }
+  }, [step, onComplete]);
+
+  // ── Camera cleanup on unmount ──────────────────────────────────────────────
+  useEffect(() => {
+    return () => {
+      if (videoRef.current?.srcObject) {
+        (videoRef.current.srcObject as MediaStream).getTracks().forEach((t) => t.stop());
+      }
+    };
+  }, []);
+
+  // ── Handlers ──────────────────────────────────────────────────────────────
+
+  const handleInitiate = useCallback(async () => {
+    const idx = parseInt(validatorInput, 10);
+    if (!Number.isFinite(idx) || idx < 0) {
+      return;
+    }
+    await initiateExit(idx);
+  }, [validatorInput, initiateExit]);
+
+  const handleAcceptSigned = useCallback(() => {
+    setSignedError('');
+    if (!signedInput.trim()) {
+      setSignedError('Please paste the signed hex blob from your cold-storage device.');
+      return;
+    }
+    acceptSignedBlob(signedInput.trim());
+  }, [signedInput, acceptSignedBlob]);
+
+  const handleBroadcast = useCallback(async () => {
+    await broadcastExit();
+  }, [broadcastExit]);
+
+  const handleAbort = useCallback(async () => {
+    await abortExit();
+    reset();
+    setValidatorInput(defaultValidatorIndex !== undefined ? String(defaultValidatorIndex) : '');
+    setSignedInput('');
+    setConfirmChecked(false);
+    setBroadcastSuccess(false);
+  }, [abortExit, reset, defaultValidatorIndex]);
+
+  const handleCameraToggle = useCallback(async () => {
+    if (cameraActive) {
+      if (videoRef.current?.srcObject) {
+        (videoRef.current.srcObject as MediaStream).getTracks().forEach((t) => t.stop());
+      }
+      setCameraActive(false);
+      return;
+    }
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({ video: { facingMode: 'environment' } });
+      if (videoRef.current) {
+        videoRef.current.srcObject = stream;
+        await videoRef.current.play();
+      }
+      setCameraActive(true);
+      setCameraError('');
+    } catch {
+      setCameraError('Camera not available — please paste the hex signature instead.');
+    }
+  }, [cameraActive]);
+
+  // ── Derived ───────────────────────────────────────────────────────────────
+  const wizardStep: 1 | 2 | 3 =
+    step === 'idle' || step === 'initiate' ? 1 : step === 'sign' ? 2 : 3;
+
+  const isStep1Active = step === 'idle';
+  const isStep2Active = step === 'initiate';
+  const isStep3Active = step === 'sign' || step === 'broadcast' || step === 'done';
+
+  // ── Aborted / done states ─────────────────────────────────────────────────
+  if (step === 'aborted') {
+    return (
+      <div className="rounded-3xl border border-white/10 bg-slate-900/80 p-6 text-white">
+        <p className="text-slate-400">Exit workflow cancelled.</p>
+        <button
+          type="button"
+          onClick={() => { reset(); setValidatorInput(defaultValidatorIndex !== undefined ? String(defaultValidatorIndex) : ''); setSignedInput(''); setConfirmChecked(false); }}
+          className="mt-4 rounded-xl bg-sky-600 px-5 py-2 text-sm font-semibold text-white hover:bg-sky-500"
+        >
+          Start again
+        </button>
+        {onClose && (
+          <button
+            type="button"
+            onClick={onClose}
+            className="ml-3 mt-4 rounded-xl border border-white/10 px-5 py-2 text-sm font-semibold text-slate-300 hover:bg-white/5"
+          >
+            Close
+          </button>
+        )}
+      </div>
+    );
+  }
+
+  if (broadcastSuccess) {
+    return (
+      <div className="rounded-3xl border border-emerald-500/30 bg-slate-900/80 p-6 text-white">
+        <div className="mb-4 flex items-center gap-3">
+          <span className="text-2xl">✓</span>
+          <h3 className="text-lg font-semibold text-emerald-300">Exit broadcast successfully</h3>
+        </div>
+        <p className="mb-2 text-sm text-slate-300">
+          Validator <span className="font-mono text-sky-300">#{validatorIndex}</span> voluntary exit
+          has been submitted to the beacon chain.
+        </p>
+        <p className="text-sm font-semibold text-red-400">
+          ⚠ This action is irreversible. The validator will begin the exit queue process.
+        </p>
+        {onClose && (
+          <button
+            type="button"
+            onClick={onClose}
+            className="mt-5 rounded-xl bg-sky-600 px-5 py-2 text-sm font-semibold text-white hover:bg-sky-500"
+          >
+            Close
+          </button>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-6 rounded-3xl border border-white/10 bg-slate-900/80 p-6 text-white">
+      {/* Header */}
+      <div className="flex items-start justify-between gap-4">
+        <div>
+          <h2 className="text-xl font-semibold">Voluntary Exit Workflow</h2>
+          <p className="mt-1 text-sm text-slate-400">
+            Air-gapped cold-storage signing · 3-step guided process
+          </p>
+        </div>
+        {onClose && (
+          <button
+            type="button"
+            onClick={onClose}
+            className="rounded-lg border border-white/10 p-1.5 text-slate-400 hover:bg-white/5 hover:text-white"
+            aria-label="Close"
+          >
+            ✕
+          </button>
+        )}
+      </div>
+
+      <StepIndicator current={wizardStep} />
+
+      {/* Global error banner */}
+      {error && (
+        <div
+          className="rounded-xl border border-red-500/40 bg-red-500/10 px-4 py-3 text-sm text-red-300"
+          role="alert"
+        >
+          {error}
+        </div>
+      )}
+
+      {/* ── Step 1: Validator selection + QR display ──────────────────────── */}
+      {(isStep1Active || isStep2Active) && (
+        <section className="space-y-5">
+          <div>
+            <h3 className="mb-3 text-base font-semibold text-slate-200">
+              Step 1 — Initiate exit
+            </h3>
+
+            {isStep1Active && (
+              <div className="space-y-4">
+                <div>
+                  <label
+                    htmlFor="exit-validator-index"
+                    className="mb-1.5 block text-sm font-medium text-slate-300"
+                  >
+                    Validator index
+                  </label>
+                  <input
+                    id="exit-validator-index"
+                    type="number"
+                    min="0"
+                    value={validatorInput}
+                    onChange={(e) => setValidatorInput(e.target.value)}
+                    className="w-full rounded-xl border border-white/10 bg-slate-950 px-4 py-2.5 font-mono text-white placeholder-slate-600 focus:border-sky-500 focus:outline-none"
+                    placeholder="e.g. 123456"
+                  />
+                </div>
+                <button
+                  type="button"
+                  onClick={handleInitiate}
+                  disabled={loading || !validatorInput.trim()}
+                  className="rounded-xl bg-sky-600 px-6 py-2.5 text-sm font-semibold text-white transition hover:bg-sky-500 disabled:cursor-not-allowed disabled:opacity-40"
+                >
+                  {loading ? 'Building message…' : 'Build unsigned exit message'}
+                </button>
+              </div>
+            )}
+
+            {/* Cooldown timer displayed during step 1 (after initiate) */}
+            {isStep2Active && (
+              <div className="space-y-5">
+                <CooldownBadge seconds={cooldownSecondsLeft} />
+
+                {/* Unsigned message details */}
+                <div className="rounded-2xl border border-white/10 bg-slate-950/60 p-4 text-sm">
+                  <div className="mb-3 grid grid-cols-2 gap-3">
+                    <Stat label="Validator index" value={`#${validatorIndex}`} mono />
+                    <Stat label="Epoch" value={String(currentEpoch ?? '—')} mono />
+                  </div>
+                  <div>
+                    <p className="mb-1 text-xs uppercase tracking-wide text-slate-500">
+                      SHA-256 message hash (audit)
+                    </p>
+                    <p className="break-all font-mono text-xs text-slate-300">{messageHash}</p>
+                  </div>
+                </div>
+
+                {/* QR code */}
+                <div className="text-center">
+                  {qrError ? (
+                    <p className="text-sm text-red-400">{qrError}</p>
+                  ) : qrDataUrl ? (
+                    <div className="inline-block rounded-2xl border border-white/10 bg-white p-3">
+                      <img
+                        src={qrDataUrl}
+                        alt="Unsigned voluntary exit message QR code for air-gapped signing"
+                        className="h-56 w-56"
+                      />
+                    </div>
+                  ) : (
+                    <p className="text-sm text-slate-400">Generating QR…</p>
+                  )}
+                  <p className="mt-2 text-xs text-slate-500">
+                    Scan this QR code with your air-gapped signing device
+                  </p>
+                </div>
+
+                {/* Hex blob (scrollable) */}
+                <div>
+                  <p className="mb-1.5 text-xs font-medium uppercase tracking-wide text-slate-500">
+                    Unsigned exit hex blob
+                  </p>
+                  <div className="max-h-24 overflow-y-auto rounded-xl border border-white/10 bg-slate-950 px-3 py-2">
+                    <code className="break-all font-mono text-xs text-sky-300">
+                      {unsignedHexBlob}
+                    </code>
+                  </div>
+                </div>
+
+                <div className="flex gap-3">
+                  <button
+                    type="button"
+                    onClick={handleAbort}
+                    className="rounded-xl border border-white/10 px-5 py-2.5 text-sm font-semibold text-slate-300 hover:bg-white/5"
+                  >
+                    Abort
+                  </button>
+                  <button
+                    type="button"
+                    onClick={() => {
+                      // Advance to the sign step so the operator can paste/scan their blob
+                      useExitStore.getState().advanceToSign();
+                    }}
+                    className="rounded-xl bg-sky-600 px-5 py-2.5 text-sm font-semibold text-white hover:bg-sky-500"
+                  >
+                    I have signed it → continue
+                  </button>
+                </div>
+              </div>
+            )}
+          </div>
+        </section>
+      )}
+
+      {/* ── Step 2: Accept signed blob ───────────────────────────────────── */}
+      {isStep3Active && step === 'sign' && (
+        <section className="space-y-5">
+          <h3 className="text-base font-semibold text-slate-200">
+            Step 2 — Submit signed blob
+          </h3>
+
+          <p className="text-sm text-slate-400">
+            Paste the 192-character hex BLS signature produced by your cold-storage device, or
+            scan the signed QR code with your camera.
+          </p>
+
+          {/* Camera toggle */}
+          <div>
+            <button
+              type="button"
+              onClick={handleCameraToggle}
+              className="mb-2 rounded-xl border border-white/10 px-4 py-2 text-sm text-slate-300 hover:bg-white/5"
+            >
+              {cameraActive ? 'Stop camera' : '📷 Scan QR with camera'}
+            </button>
+            {cameraError && <p className="text-xs text-amber-400">{cameraError}</p>}
+            {cameraActive && (
+              <video
+                ref={videoRef}
+                className="mt-2 w-full max-w-xs rounded-xl border border-white/10"
+                aria-label="Camera viewfinder for QR scan"
+              />
+            )}
+          </div>
+
+          {/* Paste hex */}
+          <div>
+            <label
+              htmlFor="signed-blob-input"
+              className="mb-1.5 block text-sm font-medium text-slate-300"
+            >
+              Signed hex signature
+            </label>
+            <textarea
+              id="signed-blob-input"
+              rows={4}
+              value={signedInput}
+              onChange={(e) => { setSignedInput(e.target.value); setSignedError(''); }}
+              className="w-full resize-none rounded-xl border border-white/10 bg-slate-950 px-4 py-3 font-mono text-xs text-sky-300 placeholder-slate-600 focus:border-sky-500 focus:outline-none"
+              placeholder="0x... (192 hex characters, BLS signature)"
+              spellCheck={false}
+              aria-describedby="signed-blob-hint"
+            />
+            <p id="signed-blob-hint" className="mt-1 text-xs text-slate-500">
+              Format: 0x followed by 192 lowercase hex characters (96-byte BLS G2 signature)
+            </p>
+            {signedError && (
+              <p className="mt-1 text-xs text-red-400" role="alert">{signedError}</p>
+            )}
+          </div>
+
+          <div className="flex gap-3">
+            <button
+              type="button"
+              onClick={handleAbort}
+              className="rounded-xl border border-white/10 px-5 py-2.5 text-sm font-semibold text-slate-300 hover:bg-white/5"
+            >
+              Abort
+            </button>
+            <button
+              type="button"
+              onClick={handleAcceptSigned}
+              className="rounded-xl bg-sky-600 px-5 py-2.5 text-sm font-semibold text-white hover:bg-sky-500"
+            >
+              Validate signature →
+            </button>
+          </div>
+        </section>
+      )}
+
+      {/* ── Step 3: Broadcast ─────────────────────────────────────────────── */}
+      {isStep3Active && !!signedBlob && (step === 'broadcast' || step === 'done') && (
+        <section className="space-y-5">
+          <h3 className="text-base font-semibold text-slate-200">
+            Step 3 — Broadcast to beacon chain
+          </h3>
+
+          {/* Cooldown badge */}
+          <CooldownBadge seconds={cooldownSecondsLeft} />
+
+          {/* Irreversibility warning */}
+          <div className="rounded-xl border border-red-500/40 bg-red-500/10 px-4 py-3">
+            <p className="text-sm font-semibold text-red-300">
+              ⚠ This action is irreversible.
+            </p>
+            <p className="mt-1 text-xs text-red-400">
+              Once broadcast, the validator exit cannot be undone. The validator will enter the
+              exit queue and its stake will eventually be withdrawn. Ensure you have signed the
+              correct exit message.
+            </p>
+          </div>
+
+          {/* Summary */}
+          <div className="rounded-2xl border border-white/10 bg-slate-950/60 p-4 text-sm">
+            <div className="grid grid-cols-2 gap-3">
+              <Stat label="Validator index" value={`#${validatorIndex}`} mono />
+              <Stat label="Epoch" value={String(currentEpoch ?? '—')} mono />
+            </div>
+            <div className="mt-3">
+              <p className="mb-1 text-xs uppercase tracking-wide text-slate-500">Signature (BLS)</p>
+              <p className="truncate font-mono text-xs text-emerald-300">{signedBlob}</p>
+            </div>
+          </div>
+
+          {/* 3-step confirmation checkbox */}
+          <label className="flex cursor-pointer items-start gap-3">
+            <input
+              type="checkbox"
+              checked={confirmChecked}
+              onChange={(e) => setConfirmChecked(e.target.checked)}
+              className="mt-0.5 h-4 w-4 rounded border-white/20 bg-slate-800 accent-sky-500"
+              aria-label="I understand this exit is irreversible"
+            />
+            <span className="text-sm text-slate-300">
+              I confirm that I want to voluntarily exit validator{' '}
+              <span className="font-mono text-sky-300">#{validatorIndex}</span>. I understand
+              this is <span className="font-semibold text-red-400">irreversible</span> and the
+              validator will enter the exit queue.
+            </span>
+          </label>
+
+          <div className="flex gap-3">
+            <button
+              type="button"
+              onClick={handleAbort}
+              disabled={loading}
+              className="rounded-xl border border-white/10 px-5 py-2.5 text-sm font-semibold text-slate-300 hover:bg-white/5 disabled:cursor-not-allowed disabled:opacity-40"
+            >
+              Abort
+            </button>
+            <button
+              type="button"
+              onClick={handleBroadcast}
+              disabled={!cooldownComplete || !confirmChecked || loading}
+              className="rounded-xl bg-red-600 px-6 py-2.5 text-sm font-semibold text-white transition hover:bg-red-500 disabled:cursor-not-allowed disabled:opacity-40"
+              aria-describedby="broadcast-cooldown-hint"
+            >
+              {loading ? 'Broadcasting…' : 'Broadcast exit'}
+            </button>
+          </div>
+          {!cooldownComplete && (
+            <p id="broadcast-cooldown-hint" className="text-xs text-amber-400">
+              Broadcast will be enabled after the {cooldownSecondsLeft}s cooldown completes.
+            </p>
+          )}
+        </section>
+      )}
+    </div>
+  );
+}
+
+// ── Small stat display helper ────────────────────────────────────────────────
+
+function Stat({
+  label,
+  value,
+  mono = false,
+}: {
+  label: string;
+  value: string;
+  mono?: boolean;
+}) {
+  return (
+    <div className="rounded-xl border border-white/10 bg-slate-950/60 p-3">
+      <p className="text-[11px] uppercase tracking-wide text-slate-500">{label}</p>
+      <p className={`mt-1 font-semibold text-slate-100 ${mono ? 'font-mono' : ''}`}>{value}</p>
+    </div>
+  );
+}
diff --git a/src/components/validators/ValidatorDetail.tsx b/src/components/validators/ValidatorDetail.tsx
index 03c522a..2410092 100644
--- a/src/components/validators/ValidatorDetail.tsx
+++ b/src/components/validators/ValidatorDetail.tsx
@@ -5,6 +5,7 @@ import { SyncCommitteeHeatmap } from '@/src/components/canvas/SyncCommitteeHeatm
 import { SyncCommitteeSummary } from '@/src/components/validators/SyncCommitteeSummary'
 import { DelayHistogram } from '@/src/components/canvas/DelayHistogram'
 import { EpochRangeSelector } from '@/src/components/validators/EpochRangeSelector'
+import { ExitWorkflowWizard } from '@/src/components/validators/ExitWorkflowWizard'
 import { useSyncCommitteeHistory } from '@/src/hooks/useSyncCommitteeHistory'
 import { useAttestationInclusion, MIN_SPAN } from '@/src/hooks/useAttestationInclusion'
 
@@ -29,6 +30,7 @@ export function ValidatorDetail({
   beaconNodeUrl?: string
 }) {
   const [tab, setTab] = useState<TabKey>('sync-committee')
+  const [showExitWizard, setShowExitWizard] = useState(false)
   const history = useSyncCommitteeHistory(validatorIndex, { beaconNodeUrl })
   const { periods, currentPeriod, loadPeriod } = history
 
@@ -55,6 +57,40 @@ export function ValidatorDetail({
 
   return (
     <div className="space-y-6">
+      {/* Actions toolbar */}
+      <div className="flex flex-wrap items-center justify-between gap-3 rounded-2xl border border-white/10 bg-slate-900/60 px-5 py-3">
+        <p className="text-sm font-medium text-slate-300">
+          Validator <span className="font-mono text-sky-300">#{validatorIndex}</span>
+        </p>
+        <button
+          type="button"
+          onClick={() => setShowExitWizard(true)}
+          className="rounded-xl border border-red-500/40 bg-red-500/10 px-4 py-2 text-sm font-semibold text-red-300 transition hover:bg-red-500/20"
+          aria-label={`Initiate voluntary exit for validator ${validatorIndex}`}
+        >
+          ⚠ Voluntary Exit
+        </button>
+      </div>
+
+      {/* Exit wizard (modal-style overlay) */}
+      {showExitWizard && (
+        <div
+          className="fixed inset-0 z-50 flex items-center justify-center bg-slate-950/80 p-4 backdrop-blur-sm"
+          role="dialog"
+          aria-modal="true"
+          aria-label="Voluntary exit workflow"
+        >
+          <div className="w-full max-w-2xl max-h-[90vh] overflow-y-auto rounded-3xl">
+            <ExitWorkflowWizard
+              defaultValidatorIndex={validatorIndex}
+              beaconNodeUrl={beaconNodeUrl}
+              onComplete={() => setShowExitWizard(false)}
+              onClose={() => setShowExitWizard(false)}
+            />
+          </div>
+        </div>
+      )}
+
       <nav className="flex gap-1 border-b border-white/10">
         {TABS.map(({ key, label }) => (
           <button
diff --git a/src/hooks/useVoluntaryExit.ts b/src/hooks/useVoluntaryExit.ts
new file mode 100644
index 0000000..958917b
--- /dev/null
+++ b/src/hooks/useVoluntaryExit.ts
@@ -0,0 +1,277 @@
+/**
+ * useVoluntaryExit – main hook managing the 3-step voluntary-exit workflow.
+ *
+ * Responsibilities:
+ *  1. Build the unsigned SSZ exit message from validator index + current epoch.
+ *  2. Drive the 60-second cooldown timer (countdown → enables broadcast).
+ *  3. Enforce a 4-per-epoch rate limit per operator account.
+ *  4. Validate the signed blob submitted in step 2.
+ *  5. Post the signed exit to the beacon node (step 3).
+ *  6. Write all state transitions to the IndexedDB audit trail.
+ *  7. Allow the operator to abort before broadcast (exit is irreversible after).
+ */
+
+'use client';
+
+import { useEffect, useRef, useCallback } from 'react';
+import { useExitStore, COOLDOWN_SECONDS, MAX_EXITS_PER_EPOCH } from '@/src/store/exitSlice';
+import {
+  buildUnsignedExitMessage,
+  fetchCurrentEpoch,
+  isValidSignatureHex,
+} from '@/src/utils/exitMessageBuilder';
+import {
+  saveExitAuditEntry,
+  updateExitAuditStatus,
+  generateExitAuditId,
+} from '@/src/services/exitAuditStore';
+import { postVoluntaryExit } from '@/src/services/beaconChainService';
+import type { VoluntaryExitPayload } from '@/src/services/beaconChainService';
+
+export interface UseVoluntaryExitOptions {
+  beaconNodeUrl?: string;
+  /** Operator identifier stored in the audit log (e.g. wallet pubkey). */
+  operatorId?: string;
+}
+
+export interface UseVoluntaryExitReturn {
+  // ── State ────────────────────────────────────────────────────────
+  step: ReturnType<typeof useExitStore.getState>['step'];
+  validatorIndex: number | null;
+  currentEpoch: number | null;
+  unsignedHexBlob: string | null;
+  messageHash: string | null;
+  signedBlob: string | null;
+  cooldownSecondsLeft: number;
+  loading: boolean;
+  error: string | null;
+  /** True when the 60-second cooldown has elapsed and broadcast is enabled. */
+  cooldownComplete: boolean;
+
+  // ── Actions ──────────────────────────────────────────────────────
+  /** Step 1 → fetches epoch, builds SSZ blob, starts cooldown. */
+  initiateExit: (validatorIndex: number) => Promise<void>;
+  /** Step 2 → validates and stores the signed blob from cold storage. */
+  acceptSignedBlob: (signedHex: string) => void;
+  /** Step 3 → broadcasts to beacon node (only enabled after cooldown). */
+  broadcastExit: () => Promise<void>;
+  /** Cancel the in-progress exit (only before broadcast). */
+  abortExit: () => void;
+  /** Reset the wizard to idle. */
+  reset: () => void;
+}
+
+export function useVoluntaryExit(options: UseVoluntaryExitOptions = {}): UseVoluntaryExitReturn {
+  const { beaconNodeUrl, operatorId } = options;
+
+  const {
+    step,
+    validatorIndex,
+    currentEpoch,
+    unsignedHexBlob,
+    messageHash,
+    signedBlob,
+    cooldownStartedAt,
+    cooldownSecondsLeft,
+    auditEntryId,
+    loading,
+    error,
+    initiate,
+    setCooldownSecondsLeft,
+    setSignedBlob,
+    confirmBroadcast,
+    markDone,
+    abort,
+    setLoading,
+    setError,
+    checkAndIncrementRateLimit,
+    reset,
+  } = useExitStore();
+
+  // ── Cooldown tick ──────────────────────────────────────────────────────────
+  const timerRef = useRef<number | undefined>(undefined);
+
+  useEffect(() => {
+    if (!cooldownStartedAt) {
+      // No active cooldown
+      if (timerRef.current !== undefined) {
+        window.clearInterval(timerRef.current);
+        timerRef.current = undefined;
+      }
+      return;
+    }
+
+    const tick = () => {
+      const elapsed = Math.floor((Date.now() - cooldownStartedAt) / 1000);
+      const remaining = Math.max(0, COOLDOWN_SECONDS - elapsed);
+      setCooldownSecondsLeft(remaining);
+      if (remaining === 0 && timerRef.current !== undefined) {
+        window.clearInterval(timerRef.current);
+        timerRef.current = undefined;
+      }
+    };
+
+    tick(); // immediate first tick
+    timerRef.current = window.setInterval(tick, 500);
+
+    return () => {
+      if (timerRef.current !== undefined) {
+        window.clearInterval(timerRef.current);
+        timerRef.current = undefined;
+      }
+    };
+  }, [cooldownStartedAt, setCooldownSecondsLeft]);
+
+  const cooldownComplete = cooldownSecondsLeft === 0 && cooldownStartedAt !== null;
+
+  // ── Step 1: initiate ───────────────────────────────────────────────────────
+  const initiateExit = useCallback(
+    async (validatorIdx: number) => {
+      setError(null);
+      setLoading(true);
+      try {
+        // Fetch current epoch
+        const epoch = await fetchCurrentEpoch(beaconNodeUrl);
+
+        // Rate-limit check
+        const allowed = checkAndIncrementRateLimit(epoch);
+        if (!allowed) {
+          throw new Error(
+            `Rate limit reached: max ${MAX_EXITS_PER_EPOCH} voluntary exits per epoch.`,
+          );
+        }
+
+        // Build unsigned message
+        const { hexBlob, messageHash: hash } = await buildUnsignedExitMessage({
+          epoch,
+          validatorIndex: validatorIdx,
+        });
+
+        // Audit log — write before anything else
+        const entryId = generateExitAuditId();
+        await saveExitAuditEntry({
+          id: entryId,
+          validatorIndex: validatorIdx,
+          epoch,
+          unsignedMsgHash: hash,
+          timestamp: Date.now(),
+          broadcastStatus: 'pending',
+          ...(operatorId ? { operatorId } : {}),
+        });
+
+        // Update store
+        initiate(validatorIdx, epoch, hexBlob, hash, entryId);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to initiate exit');
+      } finally {
+        setLoading(false);
+      }
+    },
+    [beaconNodeUrl, operatorId, checkAndIncrementRateLimit, initiate, setError, setLoading],
+  );
+
+  // ── Step 2: accept signed blob ─────────────────────────────────────────────
+  const acceptSignedBlob = useCallback(
+    (signedHex: string) => {
+      setError(null);
+      if (!isValidSignatureHex(signedHex)) {
+        setError(
+          'Invalid signature format. Expected a 192-character hex BLS signature (with or without 0x prefix).',
+        );
+        return;
+      }
+      setSignedBlob(signedHex.startsWith('0x') ? signedHex : `0x${signedHex}`);
+    },
+    [setSignedBlob, setError],
+  );
+
+  // ── Step 3: broadcast ─────────────────────────────────────────────────────
+  const broadcastExit = useCallback(async () => {
+    if (!cooldownComplete) {
+      setError(`Please wait ${cooldownSecondsLeft}s before broadcasting.`);
+      return;
+    }
+    if (!validatorIndex || !signedBlob || !currentEpoch || !unsignedHexBlob) {
+      setError('Exit workflow is incomplete. Please restart.');
+      return;
+    }
+    if (!beaconNodeUrl) {
+      setError('No beacon node URL configured. Cannot broadcast.');
+      return;
+    }
+
+    setError(null);
+    setLoading(true);
+    confirmBroadcast();
+
+    try {
+      const payload: VoluntaryExitPayload = {
+        message: {
+          epoch: String(currentEpoch),
+          validator_index: String(validatorIndex),
+        },
+        // The signed blob already has the 0x prefix after acceptSignedBlob normalisation
+        signature: signedBlob,
+      };
+
+      await postVoluntaryExit(beaconNodeUrl, payload);
+
+      // Update audit log
+      if (auditEntryId) {
+        await updateExitAuditStatus(auditEntryId, 'broadcast');
+      }
+
+      markDone();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : 'Broadcast failed';
+      setError(msg);
+      // Update audit log with failure
+      if (auditEntryId) {
+        await updateExitAuditStatus(auditEntryId, 'failed', msg);
+      }
+    } finally {
+      setLoading(false);
+    }
+  }, [
+    cooldownComplete,
+    cooldownSecondsLeft,
+    validatorIndex,
+    signedBlob,
+    currentEpoch,
+    unsignedHexBlob,
+    beaconNodeUrl,
+    auditEntryId,
+    setError,
+    setLoading,
+    confirmBroadcast,
+    markDone,
+  ]);
+
+  // ── Abort ──────────────────────────────────────────────────────────────────
+  const abortExit = useCallback(async () => {
+    // Update audit log as aborted
+    const { auditEntryId: entryId } = useExitStore.getState();
+    if (entryId) {
+      await updateExitAuditStatus(entryId, 'aborted');
+    }
+    abort();
+  }, [abort]);
+
+  return {
+    step,
+    validatorIndex,
+    currentEpoch,
+    unsignedHexBlob,
+    messageHash,
+    signedBlob,
+    cooldownSecondsLeft,
+    loading,
+    error,
+    cooldownComplete,
+    initiateExit,
+    acceptSignedBlob,
+    broadcastExit,
+    abortExit,
+    reset,
+  };
+}
diff --git a/src/services/exitAuditStore.ts b/src/services/exitAuditStore.ts
new file mode 100644
index 0000000..c27cdb9
--- /dev/null
+++ b/src/services/exitAuditStore.ts
@@ -0,0 +1,127 @@
+/**
+ * IndexedDB audit store for voluntary exit workflow.
+ *
+ * Each unsigned message is logged with its SHA-256 hash, validator index,
+ * timestamp, and eventual broadcast status, forming a tamper-evident audit
+ * trail for compliance.
+ */
+
+export type ExitBroadcastStatus = 'pending' | 'broadcast' | 'failed' | 'aborted';
+
+export interface ExitAuditEntry {
+  /** Unique entry ID */
+  id: string;
+  /** Validator index this exit relates to */
+  validatorIndex: number;
+  /** Beacon-chain epoch at which the exit was initiated */
+  epoch: number;
+  /** SHA-256 hex of the SSZ-encoded unsigned exit message */
+  unsignedMsgHash: string;
+  /** ISO-8601 timestamp when the entry was created */
+  timestamp: number;
+  /** Broadcast status, updated as the workflow progresses */
+  broadcastStatus: ExitBroadcastStatus;
+  /** Optional operator account identifier */
+  operatorId?: string;
+  /** Error description when broadcastStatus === 'failed' */
+  errorDetail?: string;
+}
+
+const DB_NAME = 'exit_audit_db';
+const DB_VERSION = 1;
+const STORE_NAME = 'exit_audit';
+
+async function openExitAuditDB(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, DB_VERSION);
+    req.onerror = () => reject(new Error('Failed to open exit audit database'));
+    req.onsuccess = () => resolve(req.result);
+    req.onupgradeneeded = (event) => {
+      const db = (event.target as IDBOpenDBRequest).result;
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        const store = db.createObjectStore(STORE_NAME, { keyPath: 'id' });
+        store.createIndex('validatorIndex', 'validatorIndex', { unique: false });
+        store.createIndex('timestamp', 'timestamp', { unique: false });
+        store.createIndex('broadcastStatus', 'broadcastStatus', { unique: false });
+        store.createIndex('unsignedMsgHash', 'unsignedMsgHash', { unique: false });
+      }
+    };
+  });
+}
+
+/** Persists a new audit entry. */
+export async function saveExitAuditEntry(entry: ExitAuditEntry): Promise<void> {
+  const db = await openExitAuditDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction([STORE_NAME], 'readwrite');
+    const store = tx.objectStore(STORE_NAME);
+    store.put(entry);
+    tx.oncomplete = () => { db.close(); resolve(); };
+    tx.onerror = () => reject(new Error('Failed to save exit audit entry'));
+  });
+}
+
+/** Updates the broadcast status of an existing entry. */
+export async function updateExitAuditStatus(
+  id: string,
+  broadcastStatus: ExitBroadcastStatus,
+  errorDetail?: string,
+): Promise<void> {
+  const db = await openExitAuditDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction([STORE_NAME], 'readwrite');
+    const store = tx.objectStore(STORE_NAME);
+    const getReq = store.get(id);
+    getReq.onsuccess = () => {
+      const existing = getReq.result as ExitAuditEntry | undefined;
+      if (!existing) { resolve(); return; }
+      store.put({ ...existing, broadcastStatus, ...(errorDetail ? { errorDetail } : {}) });
+    };
+    tx.oncomplete = () => { db.close(); resolve(); };
+    tx.onerror = () => reject(new Error('Failed to update exit audit entry'));
+  });
+}
+
+/** Returns all audit entries, sorted by timestamp ascending. */
+export async function getAllExitAuditEntries(): Promise<ExitAuditEntry[]> {
+  const db = await openExitAuditDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction([STORE_NAME], 'readonly');
+    const store = tx.objectStore(STORE_NAME);
+    const req = store.getAll();
+    req.onsuccess = () => {
+      const entries = (req.result as ExitAuditEntry[]) ?? [];
+      entries.sort((a, b) => a.timestamp - b.timestamp);
+      resolve(entries);
+    };
+    req.onerror = () => reject(new Error('Failed to read exit audit entries'));
+    tx.oncomplete = () => db.close();
+  });
+}
+
+/** Returns audit entries for a specific validator, sorted by timestamp. */
+export async function getExitAuditEntriesByValidator(
+  validatorIndex: number,
+): Promise<ExitAuditEntry[]> {
+  const db = await openExitAuditDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction([STORE_NAME], 'readonly');
+    const store = tx.objectStore(STORE_NAME);
+    const index = store.index('validatorIndex');
+    const req = index.getAll(validatorIndex);
+    req.onsuccess = () => {
+      const entries = (req.result as ExitAuditEntry[]) ?? [];
+      entries.sort((a, b) => a.timestamp - b.timestamp);
+      resolve(entries);
+    };
+    req.onerror = () => reject(new Error('Failed to read exit audit entries by validator'));
+    tx.oncomplete = () => db.close();
+  });
+}
+
+/** Generates a unique entry ID. */
+export function generateExitAuditId(): string {
+  const ts = Date.now().toString(36);
+  const rnd = Math.random().toString(36).slice(2, 10);
+  return `exit_${ts}_${rnd}`;
+}
diff --git a/src/store/exitSlice.ts b/src/store/exitSlice.ts
new file mode 100644
index 0000000..438db6f
--- /dev/null
+++ b/src/store/exitSlice.ts
@@ -0,0 +1,175 @@
+/**
+ * Zustand store for the voluntary exit workflow.
+ *
+ * Tracks:
+ *  - current step in the 3-step wizard
+ *  - cooldown timer state (60-second countdown)
+ *  - per-epoch rate-limit counter (max 4 per epoch per operator)
+ *  - the constructed unsigned exit message (hex blob + hash)
+ *  - the signed blob returned from the cold-storage device
+ *  - abort / broadcast lifecycle
+ */
+
+import { create } from 'zustand';
+
+/** Represents the exit workflow's step in the 3-step wizard. */
+export type ExitStep = 'idle' | 'initiate' | 'sign' | 'broadcast' | 'done' | 'aborted';
+
+/** Maximum voluntary exits that may be submitted per epoch per operator. */
+export const MAX_EXITS_PER_EPOCH = 4;
+
+/** Cooldown window in seconds before broadcast is enabled. */
+export const COOLDOWN_SECONDS = 60;
+
+export interface ExitWorkflowState {
+  // ── Wizard state ─────────────────────────────────────────────────
+  step: ExitStep;
+  validatorIndex: number | null;
+  /** Current epoch fetched from the beacon node. */
+  currentEpoch: number | null;
+  /** Hex blob of the SSZ-encoded unsigned VoluntaryExit message. */
+  unsignedHexBlob: string | null;
+  /** SHA-256 hash of the SSZ bytes (for audit log). */
+  messageHash: string | null;
+  /** Signed blob pasted / scanned by the operator from cold storage. */
+  signedBlob: string | null;
+
+  // ── Cooldown timer ────────────────────────────────────────────────
+  /** Timestamp (ms) when the cooldown started; null when no cooldown active. */
+  cooldownStartedAt: number | null;
+  /** Seconds remaining in the cooldown (derived; updated by the hook). */
+  cooldownSecondsLeft: number;
+
+  // ── Rate limiting ─────────────────────────────────────────────────
+  /** Epoch during which exits have been counted. */
+  rateLimitEpoch: number | null;
+  /** Number of exits initiated in the current rate-limit epoch. */
+  exitsThisEpoch: number;
+
+  // ── Error / loading ───────────────────────────────────────────────
+  loading: boolean;
+  error: string | null;
+
+  // ── Audit entry ID ────────────────────────────────────────────────
+  auditEntryId: string | null;
+
+  // ── Actions ───────────────────────────────────────────────────────
+  initiate: (
+    validatorIndex: number,
+    currentEpoch: number,
+    unsignedHexBlob: string,
+    messageHash: string,
+    auditEntryId: string,
+  ) => void;
+  setCooldownSecondsLeft: (seconds: number) => void;
+  setSignedBlob: (blob: string) => void;
+  /** Advance the wizard to the sign step (step 2) without setting a blob. */
+  advanceToSign: () => void;
+  confirmBroadcast: () => void;
+  markDone: () => void;
+  abort: () => void;
+  setLoading: (loading: boolean) => void;
+  setError: (error: string | null) => void;
+  /** Increments the per-epoch counter; returns false if the rate limit is exceeded. */
+  checkAndIncrementRateLimit: (epoch: number) => boolean;
+  reset: () => void;
+}
+
+const initialState: Omit<
+  ExitWorkflowState,
+  | 'initiate'
+  | 'setCooldownSecondsLeft'
+  | 'setSignedBlob'
+  | 'advanceToSign'
+  | 'confirmBroadcast'
+  | 'markDone'
+  | 'abort'
+  | 'setLoading'
+  | 'setError'
+  | 'checkAndIncrementRateLimit'
+  | 'reset'
+> = {
+  step: 'idle',
+  validatorIndex: null,
+  currentEpoch: null,
+  unsignedHexBlob: null,
+  messageHash: null,
+  signedBlob: null,
+  cooldownStartedAt: null,
+  cooldownSecondsLeft: COOLDOWN_SECONDS,
+  rateLimitEpoch: null,
+  exitsThisEpoch: 0,
+  loading: false,
+  error: null,
+  auditEntryId: null,
+};
+
+export const useExitStore = create<ExitWorkflowState>((set, get) => ({
+  ...initialState,
+
+  initiate(validatorIndex, currentEpoch, unsignedHexBlob, messageHash, auditEntryId) {
+    set({
+      step: 'initiate',
+      validatorIndex,
+      currentEpoch,
+      unsignedHexBlob,
+      messageHash,
+      auditEntryId,
+      signedBlob: null,
+      cooldownStartedAt: Date.now(),
+      cooldownSecondsLeft: COOLDOWN_SECONDS,
+      error: null,
+    });
+  },
+
+  setCooldownSecondsLeft(seconds) {
+    set({ cooldownSecondsLeft: Math.max(0, seconds) });
+  },
+
+  setSignedBlob(blob) {
+    // Advance to broadcast-review step once the operator provides a valid signed blob.
+    set({ step: 'broadcast', signedBlob: blob });
+  },
+
+  advanceToSign() {
+    set({ step: 'sign' });
+  },
+
+  confirmBroadcast() {
+    set({ step: 'broadcast' });
+  },
+
+  markDone() {
+    set({ step: 'done' });
+  },
+
+  abort() {
+    set({ step: 'aborted', cooldownStartedAt: null, cooldownSecondsLeft: COOLDOWN_SECONDS });
+  },
+
+  setLoading(loading) {
+    set({ loading });
+  },
+
+  setError(error) {
+    set({ error });
+  },
+
+  checkAndIncrementRateLimit(epoch) {
+    const { rateLimitEpoch, exitsThisEpoch } = get();
+    if (rateLimitEpoch !== epoch) {
+      // New epoch — reset counter
+      set({ rateLimitEpoch: epoch, exitsThisEpoch: 1 });
+      return true;
+    }
+    if (exitsThisEpoch >= MAX_EXITS_PER_EPOCH) {
+      return false;
+    }
+    set({ exitsThisEpoch: exitsThisEpoch + 1 });
+    return true;
+  },
+
+  reset() {
+    set({ ...initialState });
+  },
+}));
diff --git a/src/utils/exitMessageBuilder.ts b/src/utils/exitMessageBuilder.ts
new file mode 100644
index 0000000..3d83fa1
--- /dev/null
+++ b/src/utils/exitMessageBuilder.ts
@@ -0,0 +1,139 @@
+/**
+ * Voluntary Exit message construction
+ *
+ * Builds a minimal SSZ-encoded VoluntaryExit struct per the Ethereum consensus
+ * spec (phase0) and computes its SHA-256 hash for audit-log persistence.
+ *
+ * SSZ layout of VoluntaryExit:
+ *   epoch          : uint64  (8 bytes, little-endian)
+ *   validator_index: uint64  (8 bytes, little-endian)
+ * Total             : 16 bytes
+ *
+ * The signing domain used for voluntary exits on mainnet is:
+ *   DOMAIN_VOLUNTARY_EXIT = 0x04000000
+ */
+
+export const DOMAIN_VOLUNTARY_EXIT = '0x04000000' as const;
+
+/** Max 2 953 bytes for Version-40 QR with Medium error-correction (binary mode). */
+export const QR_MAX_PAYLOAD_BYTES = 2_953;
+
+export interface VoluntaryExitMessage {
+  /** Current beacon chain epoch (fetched from /eth/v1/beacon/genesis). */
+  epoch: number;
+  /** Validator index on the beacon chain. */
+  validatorIndex: number;
+}
+
+/**
+ * Returns the domain bytes for DOMAIN_VOLUNTARY_EXIT.
+ * The domain is prepended to the exit message root during signing per the spec.
+ */
+export function getVoluntaryExitDomain(): Uint8Array {
+  // 0x04000000 as 4-byte big-endian
+  return new Uint8Array([0x04, 0x00, 0x00, 0x00]);
+}
+
+/**
+ * Encodes a VoluntaryExit message to SSZ (16 bytes).
+ * SSZ uint64 is little-endian.
+ */
+export function encodeVoluntaryExitSSZ(msg: VoluntaryExitMessage): Uint8Array {
+  const buf = new Uint8Array(16);
+  const view = new DataView(buf.buffer);
+  // epoch: bytes 0–7
+  view.setBigUint64(0, BigInt(msg.epoch), /* littleEndian= */ true);
+  // validator_index: bytes 8–15
+  view.setBigUint64(8, BigInt(msg.validatorIndex), /* littleEndian= */ true);
+  return buf;
+}
+
+/**
+ * Converts a Uint8Array to a lowercase hex string (no 0x prefix).
+ */
+export function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Converts a hex string (with or without 0x prefix) to a Uint8Array.
+ */
+export function hexToBytes(hex: string): Uint8Array {
+  const cleaned = hex.startsWith('0x') ? hex.slice(2) : hex;
+  if (cleaned.length % 2 !== 0) {
+    throw new Error('Hex string must have an even length');
+  }
+  const bytes = new Uint8Array(cleaned.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(cleaned.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * Computes a SHA-256 hash, returning a lowercase hex string.
+ * Works in both browser (SubtleCrypto) and Node.js (for tests).
+ */
+export async function sha256Hex(data: Uint8Array): Promise<string> {
+  if (typeof window !== 'undefined' && window.crypto?.subtle) {
+    const hashBuf = await window.crypto.subtle.digest('SHA-256', data as BufferSource);
+    return bytesToHex(new Uint8Array(hashBuf));
+  }
+  // Node.js fallback (used in Vitest)
+  const { createHash } = await import('crypto');
+  return createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * Builds the unsigned exit message:
+ *  - SSZ-encodes the VoluntaryExit struct
+ *  - Returns the hex blob and its SHA-256 hash (for the audit log)
+ */
+export async function buildUnsignedExitMessage(msg: VoluntaryExitMessage): Promise<{
+  /** SSZ-encoded bytes */
+  sszBytes: Uint8Array;
+  /** Lower-case hex of the SSZ bytes (no 0x prefix) */
+  hexBlob: string;
+  /** Lower-case SHA-256 hex of the SSZ bytes */
+  messageHash: string;
+}> {
+  const sszBytes = encodeVoluntaryExitSSZ(msg);
+  const hexBlob = bytesToHex(sszBytes);
+  const messageHash = await sha256Hex(sszBytes);
+  return { sszBytes, hexBlob, messageHash };
+}
+
+/**
+ * Validates a signed exit blob.
+ * A BLS signature is 96 bytes = 192 hex chars (no 0x prefix) or 194 with prefix.
+ */
+export function isValidSignatureHex(sig: string): boolean {
+  const cleaned = sig.startsWith('0x') ? sig.slice(2) : sig;
+  return /^[0-9a-fA-F]{192}$/.test(cleaned);
+}
+
+/**
+ * Fetches the current epoch from the beacon node's genesis info.
+ * Falls back to a locally-derived epoch when the node is unreachable.
+ */
+export async function fetchCurrentEpoch(beaconNodeUrl?: string): Promise<number> {
+  const GENESIS_TIME = 1_606_824_023; // mainnet genesis unix-seconds
+  const EPOCH_SECONDS = 32 * 12; // 32 slots × 12 s
+
+  if (!beaconNodeUrl) {
+    return Math.max(0, Math.floor((Date.now() / 1000 - GENESIS_TIME) / EPOCH_SECONDS));
+  }
+
+  const url = beaconNodeUrl.replace(/\/$/, '');
+  try {
+    const res = await fetch(`${url}/eth/v1/beacon/genesis`);
+    if (!res.ok) throw new Error('genesis fetch failed');
+    const body = (await res.json()) as { data?: { genesis_time?: string | number } };
+    const genesisTime = Number(body.data?.genesis_time ?? GENESIS_TIME);
+    return Math.max(0, Math.floor((Date.now() / 1000 - genesisTime) / EPOCH_SECONDS));
+  } catch {
+    return Math.max(0, Math.floor((Date.now() / 1000 - GENESIS_TIME) / EPOCH_SECONDS));
+  }
+}
diff --git a/src/utils/qrEncoder.ts b/src/utils/qrEncoder.ts
new file mode 100644
index 0000000..895cfdc
--- /dev/null
+++ b/src/utils/qrEncoder.ts
@@ -0,0 +1,61 @@
+/**
+ * Binary QR code generation for air-gapped signing workflows.
+ *
+ * Uses the `qrcode` package's byte (binary) mode to encode raw hex blobs so
+ * that high-density binary data scans reliably at medium error-correction.
+ *
+ * Capacity reference (Version 40, byte mode, Medium ECC): 2 953 bytes.
+ * We reject payloads larger than that limit so the QR stays scannable.
+ */
+
+import QRCode from 'qrcode';
+import { QR_MAX_PAYLOAD_BYTES } from './exitMessageBuilder';
+
+export interface ExitQRResult {
+  /** Data-URL PNG of the generated QR code (for <img src=…>) */
+  dataUrl: string;
+  /** Raw hex payload encoded inside the QR (the unsigned exit hex blob) */
+  payload: string;
+  /** Byte length of the encoded payload */
+  payloadBytes: number;
+}
+
+/**
+ * Generates a binary-mode QR code for the given `hexBlob`.
+ *
+ * We encode the hex string as bytes directly (UTF-8 byte mode) rather than
+ * alphanumeric mode to guarantee reliable scanning of mixed-case hex.
+ *
+ * @throws if the payload exceeds the Version-40 byte-mode capacity.
+ */
+export async function encodeExitQR(hexBlob: string): Promise<ExitQRResult> {
+  const payloadBytes = new TextEncoder().encode(hexBlob).length;
+
+  if (payloadBytes > QR_MAX_PAYLOAD_BYTES) {
+    throw new Error(
+      `QR payload too large: ${payloadBytes} bytes (max ${QR_MAX_PAYLOAD_BYTES} bytes for Version-40 Medium ECC)`,
+    );
+  }
+
+  const dataUrl = await QRCode.toDataURL(hexBlob, {
+    errorCorrectionLevel: 'M',
+    // Version 40 supports up to 2 953 bytes in byte mode at Medium ECC.
+    // Specifying version 40 explicitly ensures the encoder never downgrades.
+    version: 40,
+    margin: 2,
+    width: 512,
+    // Use byte mode (the qrcode library calls this 'byte'; it maps to ISO
+    // 8859-1 byte encoding which handles the ASCII hex alphabet correctly).
+    type: 'image/png',
+  });
+
+  return { dataUrl, payload: hexBlob, payloadBytes };
+}
+
+/**
+ * Validates that a hex string is within the QR capacity limit.
+ */
+export function validateQRPayloadSize(hexBlob: string): boolean {
+  const bytes = new TextEncoder().encode(hexBlob).length;
+  return bytes <= QR_MAX_PAYLOAD_BYTES;
+}
diff --git a/src/utils/sszSerialization.ts b/src/utils/sszSerialization.ts
new file mode 100644
index 0000000..5d094bc
--- /dev/null
+++ b/src/utils/sszSerialization.ts
@@ -0,0 +1,29 @@
+/**
+ * SSZ serialization utilities for Ethereum consensus-layer types.
+ *
+ * This module re-exports the core SSZ encoding primitives used throughout the
+ * voluntary-exit workflow so that callers have a single, stable import path
+ * for consensus serialization helpers.
+ *
+ * All SSZ encoding for voluntary exits follows the Ethereum Phase-0 spec:
+ *   https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md
+ *
+ * VoluntaryExit SSZ layout (16 bytes, little-endian uint64 fields):
+ *   epoch          : uint64  (bytes 0–7)
+ *   validator_index: uint64  (bytes 8–15)
+ */
+
+export {
+  encodeVoluntaryExitSSZ,
+  bytesToHex,
+  hexToBytes,
+  sha256Hex,
+  buildUnsignedExitMessage,
+  isValidSignatureHex,
+  fetchCurrentEpoch,
+  getVoluntaryExitDomain,
+  DOMAIN_VOLUNTARY_EXIT,
+  QR_MAX_PAYLOAD_BYTES,
+} from './exitMessageBuilder';
+
+export type { VoluntaryExitMessage } from './exitMessageBuilder';

From 6142449db7a441de638c900515645290ee00845d Mon Sep 17 00:00:00 2001
From: mona-i <josephenemona300@gmail.com>
Date: Sun, 19 Jul 2026 15:55:22 +0100
Subject: [PATCH 2/2] feat: correlated slashing risk analyzer for
 geographically distributed node clusters #57

- src/utils/dbscan.ts: DBSCAN clustering (epsilon=500km, minPts=3) with Haversine distance
- src/utils/riskScore.ts: weighted risk score formula (0.4*IP + 0.3*ASN + 0.3*region), tier thresholds
- src/utils/mitigationRecommender.ts: per-factor diversification recommendations with human-readable details
- src/services/infrastructureService.ts: IP/ASN/cloud metadata aggregation with demo + production providers
- src/store/riskSlice.ts: Zustand state for risk nodes, cluster results, and analysis lifecycle
- src/workers/riskClusterWorker.ts: off-thread DBSCAN + risk scoring via postMessage
- src/hooks/useCorrelationRisk.ts: orchestration hook with worker integration and main-thread fallback
- src/components/canvas/RiskTopologyMap.tsx: equirectangular canvas map, convex hulls, zoom/pan, click-to-inspect
- src/components/validators/RiskSummaryPanel.tsx: tabular cluster summary with risk scores and top mitigations
- src/components/validators/ValidatorDashboard.tsx: mount Correlation Risk accordion section
- .github/pull_request_template.md: add PR template
---
 .github/pull_request_template.md              |  29 ++
 src/components/canvas/RiskTopologyMap.tsx     | 446 ++++++++++++++++++
 .../validators/RiskSummaryPanel.tsx           | 108 +++++
 .../validators/ValidatorDashboard.tsx         | 107 +++++
 src/hooks/useCorrelationRisk.ts               | 207 ++++++++
 src/services/infrastructureService.ts         | 186 ++++++++
 src/store/riskSlice.ts                        |  65 +++
 src/utils/dbscan.ts                           | 102 ++++
 src/utils/mitigationRecommender.ts            | 122 +++++
 src/utils/riskScore.ts                        |  68 +++
 src/workers/riskClusterWorker.ts              | 157 ++++++
 11 files changed, 1597 insertions(+)
 create mode 100644 .github/pull_request_template.md
 create mode 100644 src/components/canvas/RiskTopologyMap.tsx
 create mode 100644 src/components/validators/RiskSummaryPanel.tsx
 create mode 100644 src/hooks/useCorrelationRisk.ts
 create mode 100644 src/services/infrastructureService.ts
 create mode 100644 src/store/riskSlice.ts
 create mode 100644 src/utils/dbscan.ts
 create mode 100644 src/utils/mitigationRecommender.ts
 create mode 100644 src/utils/riskScore.ts
 create mode 100644 src/workers/riskClusterWorker.ts

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..c488cfd
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,29 @@
+## Summary
+
+<!-- Briefly describe the changes introduced by this PR. -->
+
+## Related Issue
+
+Closes #
+
+## Changes
+
+<!-- List the files added or modified and what each does. -->
+
+### New files
+- 
+### Modified files
+- 
+
+## Testing
+
+<!-- Describe how the changes were tested. -->
+
+- [ ] TypeScript: no type errors (`npm run build`)
+- [ ] Linting: no errors (`npm run lint`)
+- [ ] Unit tests pass (`npm run test:unit`)
+- [ ] E2E tests pass (`npm run test:e2e:ci`)
+
+## Notes
+
+<!-- Any additional context, known limitations, or follow-up work. -->
diff --git a/src/components/canvas/RiskTopologyMap.tsx b/src/components/canvas/RiskTopologyMap.tsx
new file mode 100644
index 0000000..8568b3e
--- /dev/null
+++ b/src/components/canvas/RiskTopologyMap.tsx
@@ -0,0 +1,446 @@
+'use client'
+
+// Equirectangular canvas map for correlated slashing risk topology.
+//
+// Features:
+//   • Up to 500 nodes rendered as dots colored by risk tier
+//   • Cluster convex-hull polygons (semi-transparent fill)
+//   • Zoom / pan via mouse wheel and drag
+//   • Click cluster → fire onSelectCluster callback
+//   • Offscreen canvas caches the static world outline layer
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { RiskNode, ClusterRiskResult } from '@/src/store/riskSlice'
+import type { RiskTier } from '@/src/utils/riskScore'
+
+const DISPLAY_HEIGHT = 420
+const MAX_NODES = 500
+
+/** Pixel color per risk tier. */
+const TIER_COLOR: Record<RiskTier | 'noise', string> = {
+  low: '#22c55e',
+  medium: '#f59e0b',
+  high: '#f97316',
+  critical: '#ef4444',
+  noise: '#64748b',
+}
+
+const TIER_COLOR_ALPHA: Record<RiskTier | 'noise', string> = {
+  low: 'rgba(34,197,94,0.15)',
+  medium: 'rgba(245,158,11,0.15)',
+  high: 'rgba(249,115,22,0.15)',
+  critical: 'rgba(239,68,68,0.15)',
+  noise: 'rgba(100,116,139,0.10)',
+}
+
+interface Transform {
+  /** Zoom scale (1 = fit full map). */
+  scale: number
+  /** Translation in logical map pixels. */
+  tx: number
+  ty: number
+}
+
+const INITIAL_TRANSFORM: Transform = { scale: 1, tx: 0, ty: 0 }
+
+// ── Equirectangular projection ────────────────────────────────────────────────
+
+function lngLatToXY(lng: number, lat: number, w: number, h: number): [number, number] {
+  const x = ((lng + 180) / 360) * w
+  const y = ((90 - lat) / 180) * h
+  return [x, y]
+}
+
+// ── Convex hull (Graham scan) ─────────────────────────────────────────────────
+
+function cross(o: [number, number], a: [number, number], b: [number, number]): number {
+  return (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0])
+}
+
+function convexHull(pts: Array<[number, number]>): Array<[number, number]> {
+  const n = pts.length
+  if (n < 3) return pts
+  const sorted = [...pts].sort((a, b) => a[0] - b[0] || a[1] - b[1])
+  const lower: Array<[number, number]> = []
+  for (const p of sorted) {
+    while (lower.length >= 2 && cross(lower[lower.length - 2], lower[lower.length - 1], p) <= 0)
+      lower.pop()
+    lower.push(p)
+  }
+  const upper: Array<[number, number]> = []
+  for (let i = sorted.length - 1; i >= 0; i--) {
+    const p = sorted[i]
+    while (upper.length >= 2 && cross(upper[upper.length - 2], upper[upper.length - 1], p) <= 0)
+      upper.pop()
+    upper.push(p)
+  }
+  upper.pop()
+  lower.pop()
+  return [...lower, ...upper]
+}
+
+// ── Component ────────────────────────────────────────────────────────────────
+
+interface Hover {
+  nodeId: string
+  tier: RiskTier | 'noise'
+  clusterId: number
+  px: number
+  py: number
+}
+
+export interface RiskTopologyMapProps {
+  nodes: RiskNode[]
+  clusters: ClusterRiskResult[]
+  /** Called when user clicks a cluster hull or node dot. */
+  onSelectCluster?: (clusterId: number) => void
+}
+
+export function RiskTopologyMap({ nodes, clusters, onSelectCluster }: RiskTopologyMapProps) {
+  const containerRef = useRef<HTMLDivElement | null>(null)
+  const canvasRef = useRef<HTMLCanvasElement | null>(null)
+  const offscreenRef = useRef<HTMLCanvasElement | null>(null)
+
+  const [size, setSize] = useState({ w: 0, h: DISPLAY_HEIGHT })
+  const [transform, setTransform] = useState<Transform>(INITIAL_TRANSFORM)
+  const [hover, setHover] = useState<Hover | null>(null)
+
+  const dragRef = useRef<{ startX: number; startY: number; origTx: number; origTy: number } | null>(null)
+
+  // Limit to MAX_NODES.
+  const visibleNodes = nodes.slice(0, MAX_NODES)
+
+  // ── Resize observer ─────────────────────────────────────────────────────────
+  useEffect(() => {
+    const el = containerRef.current
+    if (!el) return
+    const update = () => setSize({ w: el.clientWidth, h: DISPLAY_HEIGHT })
+    update()
+    const ro = new ResizeObserver(update)
+    ro.observe(el)
+    return () => ro.disconnect()
+  }, [])
+
+  // ── Cluster lookup map ──────────────────────────────────────────────────────
+  const clusterByIdRef = useRef<Map<number, ClusterRiskResult>>(new Map())
+  useEffect(() => {
+    clusterByIdRef.current = new Map(clusters.map((c) => [c.clusterId, c]))
+  }, [clusters])
+
+  // ── Projection helpers (scoped to current size) ─────────────────────────────
+  const project = useCallback(
+    (lng: number, lat: number, t: Transform): [number, number] => {
+      const [mx, my] = lngLatToXY(lng, lat, size.w, size.h)
+      return [mx * t.scale + t.tx, my * t.scale + t.ty]
+    },
+    [size],
+  )
+
+  // ── Build convex hulls for clusters ─────────────────────────────────────────
+  const hullsRef = useRef<Map<number, Array<[number, number]>>>(new Map())
+  useEffect(() => {
+    const map = new Map<number, Array<[number, number]>>()
+    const clusterPts = new Map<number, Array<[number, number]>>()
+    for (const node of visibleNodes) {
+      if (node.clusterId < 0) continue
+      const pts = clusterPts.get(node.clusterId) ?? []
+      pts.push([node.lng, node.lat])
+      clusterPts.set(node.clusterId, pts)
+    }
+    for (const [cid, pts] of clusterPts) {
+      map.set(cid, convexHull(pts))
+    }
+    hullsRef.current = map
+  }, [visibleNodes])
+
+  // ── Offscreen world grid (redrawn on size change) ───────────────────────────
+  useEffect(() => {
+    if (size.w === 0) return
+    const dpr = typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1
+    let offscreen = offscreenRef.current
+    if (!offscreen) {
+      offscreen = document.createElement('canvas')
+      offscreenRef.current = offscreen
+    }
+    offscreen.width = Math.round(size.w * dpr)
+    offscreen.height = Math.round(size.h * dpr)
+    const ctx = offscreen.getContext('2d')
+    if (!ctx) return
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0)
+    ctx.clearRect(0, 0, size.w, size.h)
+
+    // Background.
+    ctx.fillStyle = '#0c1627'
+    ctx.fillRect(0, 0, size.w, size.h)
+
+    // Graticule lines every 30°.
+    ctx.strokeStyle = 'rgba(148,163,184,0.07)'
+    ctx.lineWidth = 0.5
+    for (let lng = -180; lng <= 180; lng += 30) {
+      const x = ((lng + 180) / 360) * size.w
+      ctx.beginPath()
+      ctx.moveTo(x, 0)
+      ctx.lineTo(x, size.h)
+      ctx.stroke()
+    }
+    for (let lat = -90; lat <= 90; lat += 30) {
+      const y = ((90 - lat) / 180) * size.h
+      ctx.beginPath()
+      ctx.moveTo(0, y)
+      ctx.lineTo(size.w, y)
+      ctx.stroke()
+    }
+
+    // Equator & prime meridian.
+    ctx.strokeStyle = 'rgba(148,163,184,0.18)'
+    ctx.lineWidth = 0.8
+    const equatorY = size.h / 2
+    ctx.beginPath()
+    ctx.moveTo(0, equatorY)
+    ctx.lineTo(size.w, equatorY)
+    ctx.stroke()
+    const meridianX = size.w / 2
+    ctx.beginPath()
+    ctx.moveTo(meridianX, 0)
+    ctx.lineTo(meridianX, size.h)
+    ctx.stroke()
+  }, [size])
+
+  // ── Main paint ───────────────────────────────────────────────────────────────
+  const paint = useCallback(() => {
+    const canvas = canvasRef.current
+    if (!canvas || size.w === 0) return
+    const dpr = typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1
+    canvas.width = Math.round(size.w * dpr)
+    canvas.height = Math.round(size.h * dpr)
+    const ctx = canvas.getContext('2d')
+    if (!ctx) return
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0)
+    ctx.clearRect(0, 0, size.w, size.h)
+
+    // Composite offscreen world background.
+    const offscreen = offscreenRef.current
+    if (offscreen) {
+      ctx.save()
+      ctx.translate(transform.tx, transform.ty)
+      ctx.scale(transform.scale, transform.scale)
+      ctx.drawImage(offscreen, 0, 0, size.w, size.h)
+      ctx.restore()
+    }
+
+    // Draw cluster convex hulls.
+    for (const [cid, hull] of hullsRef.current) {
+      if (hull.length < 2) continue
+      const cluster = clusterByIdRef.current.get(cid)
+      const tier = cluster?.tier ?? 'noise'
+      const projected = hull.map(([lng, lat]) => project(lng, lat, transform))
+
+      ctx.beginPath()
+      const [fx, fy] = projected[0]
+      ctx.moveTo(fx, fy)
+      for (let i = 1; i < projected.length; i++) {
+        ctx.lineTo(projected[i][0], projected[i][1])
+      }
+      ctx.closePath()
+      ctx.fillStyle = TIER_COLOR_ALPHA[tier]
+      ctx.fill()
+      ctx.strokeStyle = TIER_COLOR[tier]
+      ctx.lineWidth = 1.5
+      ctx.globalAlpha = 0.5
+      ctx.stroke()
+      ctx.globalAlpha = 1
+    }
+
+    // Draw node dots.
+    for (const node of visibleNodes) {
+      const [px, py] = project(node.lng, node.lat, transform)
+      const cluster = node.clusterId >= 0 ? clusterByIdRef.current.get(node.clusterId) : undefined
+      const tier = cluster?.tier ?? 'noise'
+      const isHovered = hover?.nodeId === node.nodeId
+      const radius = isHovered ? 7 : 4
+
+      ctx.beginPath()
+      ctx.arc(px, py, radius, 0, Math.PI * 2)
+      ctx.fillStyle = TIER_COLOR[tier]
+      ctx.fill()
+      if (isHovered) {
+        ctx.strokeStyle = '#f8fafc'
+        ctx.lineWidth = 2
+        ctx.stroke()
+      }
+    }
+  }, [size, transform, visibleNodes, hover, project])
+
+  useEffect(() => {
+    paint()
+  }, [paint])
+
+  // ── Hit-test ─────────────────────────────────────────────────────────────────
+  const nodeAt = useCallback(
+    (px: number, py: number): RiskNode | null => {
+      let best: RiskNode | null = null
+      let bestDist = 10 * 10
+      for (const node of visibleNodes) {
+        const [nx, ny] = project(node.lng, node.lat, transform)
+        const d = (nx - px) ** 2 + (ny - py) ** 2
+        if (d < bestDist) {
+          bestDist = d
+          best = node
+        }
+      }
+      return best
+    },
+    [visibleNodes, project, transform],
+  )
+
+  // ── Mouse events ──────────────────────────────────────────────────────────────
+  const onMouseMove = useCallback(
+    (e: React.MouseEvent<HTMLCanvasElement>) => {
+      if (dragRef.current) {
+        const dx = e.clientX - dragRef.current.startX
+        const dy = e.clientY - dragRef.current.startY
+        setTransform((t) => ({
+          ...t,
+          tx: dragRef.current!.origTx + dx,
+          ty: dragRef.current!.origTy + dy,
+        }))
+        return
+      }
+      const rect = e.currentTarget.getBoundingClientRect()
+      const px = e.clientX - rect.left
+      const py = e.clientY - rect.top
+      const node = nodeAt(px, py)
+      if (node) {
+        const cluster = node.clusterId >= 0 ? clusterByIdRef.current.get(node.clusterId) : undefined
+        setHover({
+          nodeId: node.nodeId,
+          tier: cluster?.tier ?? 'noise',
+          clusterId: node.clusterId,
+          px,
+          py,
+        })
+      } else {
+        setHover(null)
+      }
+    },
+    [nodeAt],
+  )
+
+  const onMouseDown = useCallback((e: React.MouseEvent<HTMLCanvasElement>) => {
+    dragRef.current = {
+      startX: e.clientX,
+      startY: e.clientY,
+      origTx: 0,
+      origTy: 0,
+    }
+    // Capture current transform values.
+    setTransform((t) => {
+      dragRef.current!.origTx = t.tx
+      dragRef.current!.origTy = t.ty
+      return t
+    })
+  }, [])
+
+  const onMouseUp = useCallback(() => {
+    dragRef.current = null
+  }, [])
+
+  const onMouseLeave = useCallback(() => {
+    dragRef.current = null
+    setHover(null)
+  }, [])
+
+  const onClick = useCallback(
+    (e: React.MouseEvent<HTMLCanvasElement>) => {
+      const rect = e.currentTarget.getBoundingClientRect()
+      const px = e.clientX - rect.left
+      const py = e.clientY - rect.top
+      const node = nodeAt(px, py)
+      if (node && node.clusterId >= 0 && onSelectCluster) {
+        onSelectCluster(node.clusterId)
+      }
+    },
+    [nodeAt, onSelectCluster],
+  )
+
+  const onWheel = useCallback((e: React.WheelEvent<HTMLCanvasElement>) => {
+    e.preventDefault()
+    const factor = e.deltaY < 0 ? 1.15 : 1 / 1.15
+    setTransform((t) => {
+      const newScale = Math.min(8, Math.max(0.5, t.scale * factor))
+      return { scale: newScale, tx: t.tx, ty: t.ty }
+    })
+  }, [])
+
+  const resetView = useCallback(() => setTransform(INITIAL_TRANSFORM), [])
+
+  const isZoomed = transform.scale !== 1 || transform.tx !== 0 || transform.ty !== 0
+
+  return (
+    <div className="space-y-2">
+      <div className="flex items-center justify-between text-xs text-slate-400">
+        <span>
+          {visibleNodes.length} nodes · {clusters.length} cluster{clusters.length !== 1 ? 's' : ''}
+          {nodes.length > MAX_NODES && ` (showing first ${MAX_NODES})`}
+        </span>
+        {isZoomed && (
+          <button
+            type="button"
+            onClick={resetView}
+            className="rounded-md border border-white/10 px-2 py-1 font-medium text-slate-200 hover:bg-white/5"
+          >
+            Reset view
+          </button>
+        )}
+      </div>
+
+      <div ref={containerRef} className="relative w-full" style={{ height: DISPLAY_HEIGHT }}>
+        <canvas
+          ref={canvasRef}
+          onMouseMove={onMouseMove}
+          onMouseDown={onMouseDown}
+          onMouseUp={onMouseUp}
+          onMouseLeave={onMouseLeave}
+          onClick={onClick}
+          onWheel={onWheel}
+          className="h-full w-full cursor-grab rounded-xl"
+          style={{ width: '100%', height: DISPLAY_HEIGHT }}
+          aria-label="Correlated slashing risk topology map"
+        />
+
+        {hover && (
+          <div
+            className="pointer-events-none absolute z-10 rounded-md border border-white/10 bg-slate-950/95 px-2.5 py-1.5 text-xs text-slate-100 shadow-lg"
+            style={{
+              left: Math.min(hover.px + 12, size.w - 160),
+              top: Math.min(hover.py + 12, DISPLAY_HEIGHT - 60),
+            }}
+          >
+            <div className="font-semibold">{hover.nodeId}</div>
+            <div className="capitalize" style={{ color: TIER_COLOR[hover.tier] }}>
+              {hover.clusterId >= 0 ? `Cluster ${hover.clusterId} · ${hover.tier}` : 'Noise (unclustered)'}
+            </div>
+          </div>
+        )}
+      </div>
+
+      <div className="flex flex-wrap items-center gap-4 text-xs text-slate-400">
+        <Legend color={TIER_COLOR.low} label="Low risk" />
+        <Legend color={TIER_COLOR.medium} label="Medium risk" />
+        <Legend color={TIER_COLOR.high} label="High risk" />
+        <Legend color={TIER_COLOR.critical} label="Critical risk" />
+        <Legend color={TIER_COLOR.noise} label="Unclustered" />
+        <span className="ml-auto text-slate-500">Scroll to zoom · drag to pan · click node to inspect</span>
+      </div>
+    </div>
+  )
+}
+
+function Legend({ color, label }: { color: string; label: string }) {
+  return (
+    <span className="flex items-center gap-1.5">
+      <span className="inline-block h-3 w-3 rounded-full" style={{ backgroundColor: color }} />
+      {label}
+    </span>
+  )
+}
diff --git a/src/components/validators/RiskSummaryPanel.tsx b/src/components/validators/RiskSummaryPanel.tsx
new file mode 100644
index 0000000..631aecd
--- /dev/null
+++ b/src/components/validators/RiskSummaryPanel.tsx
@@ -0,0 +1,108 @@
+'use client'
+
+// Tabular summary of all DBSCAN clusters with risk scores, node counts,
+// and top mitigation recommendations.
+
+import type { ClusterRiskResult } from '@/src/store/riskSlice'
+import type { RiskTier } from '@/src/utils/riskScore'
+
+const TIER_STYLES: Record<RiskTier, { bg: string; text: string; label: string }> = {
+  low: { bg: 'bg-emerald-500/10', text: 'text-emerald-300', label: 'Low' },
+  medium: { bg: 'bg-amber-500/10', text: 'text-amber-300', label: 'Medium' },
+  high: { bg: 'bg-orange-500/10', text: 'text-orange-300', label: 'High' },
+  critical: { bg: 'bg-red-500/10', text: 'text-red-300', label: 'Critical' },
+}
+
+interface RiskSummaryPanelProps {
+  clusters: ClusterRiskResult[]
+  /** Cluster ID currently selected on the map (highlights the row). */
+  selectedClusterId?: number | null
+  onSelectCluster?: (clusterId: number) => void
+}
+
+/**
+ * Tabular overview of detected geographic risk clusters. Each row shows the
+ * cluster ID, node count, weighted risk score, tier badge, shared-infra
+ * breakdown, and the top mitigation recommendation.
+ */
+export function RiskSummaryPanel({
+  clusters,
+  selectedClusterId,
+  onSelectCluster,
+}: RiskSummaryPanelProps) {
+  if (clusters.length === 0) {
+    return (
+      <p className="py-8 text-center text-sm text-slate-400">
+        No clusters detected. Ensure nodes have valid coordinates.
+      </p>
+    )
+  }
+
+  return (
+    <div className="overflow-x-auto">
+      <table className="w-full text-sm text-slate-200">
+        <thead>
+          <tr className="border-b border-white/10 text-xs uppercase tracking-wide text-slate-500">
+            <th className="pb-2 pr-4 text-left">Cluster</th>
+            <th className="pb-2 pr-4 text-right">Nodes</th>
+            <th className="pb-2 pr-4 text-right">Score</th>
+            <th className="pb-2 pr-4 text-left">Tier</th>
+            <th className="pb-2 pr-4 text-right">Shared IPs</th>
+            <th className="pb-2 pr-4 text-right">Shared ASNs</th>
+            <th className="pb-2 pr-4 text-right">Shared Regions</th>
+            <th className="pb-2 text-left">Top Mitigation</th>
+          </tr>
+        </thead>
+        <tbody>
+          {clusters.map((cluster) => {
+            const style = TIER_STYLES[cluster.tier]
+            const isSelected = cluster.clusterId === selectedClusterId
+            const topRec = cluster.recommendations[0]
+
+            return (
+              <tr
+                key={cluster.clusterId}
+                onClick={() => onSelectCluster?.(cluster.clusterId)}
+                className={`cursor-pointer border-b border-white/5 transition-colors hover:bg-white/5 ${
+                  isSelected ? 'bg-sky-500/10' : ''
+                }`}
+              >
+                <td className="py-3 pr-4 font-mono text-sky-300">#{cluster.clusterId}</td>
+                <td className="py-3 pr-4 text-right">{cluster.nodeCount}</td>
+                <td className="py-3 pr-4 text-right font-semibold">
+                  {(cluster.riskScore * 100).toFixed(1)}%
+                </td>
+                <td className="py-3 pr-4">
+                  <span
+                    className={`rounded-full px-2 py-0.5 text-xs font-semibold ${style.bg} ${style.text}`}
+                  >
+                    {style.label}
+                  </span>
+                </td>
+                <td className="py-3 pr-4 text-right text-slate-300">
+                  {cluster.sharedIpCount} / {cluster.nodeCount}
+                </td>
+                <td className="py-3 pr-4 text-right text-slate-300">
+                  {cluster.sharedAsnCount} / {cluster.nodeCount}
+                </td>
+                <td className="py-3 pr-4 text-right text-slate-300">
+                  {cluster.sharedCloudRegionCount} / {cluster.nodeCount}
+                </td>
+                <td className="py-3 max-w-xs">
+                  {topRec ? (
+                    <span className="text-slate-400" title={topRec.detail}>
+                      {topRec.title}{' '}
+                      <span className="text-slate-500">({topRec.sharedValue})</span>
+                    </span>
+                  ) : (
+                    <span className="text-slate-600">—</span>
+                  )}
+                </td>
+              </tr>
+            )
+          })}
+        </tbody>
+      </table>
+    </div>
+  )
+}
diff --git a/src/components/validators/ValidatorDashboard.tsx b/src/components/validators/ValidatorDashboard.tsx
index 64502f8..61d8d4d 100644
--- a/src/components/validators/ValidatorDashboard.tsx
+++ b/src/components/validators/ValidatorDashboard.tsx
@@ -10,28 +10,61 @@ import { ConsolidationDashboard } from '@/src/components/validators/Consolidatio
 import { useValidatorBalances } from '@/src/hooks/useValidatorBalances'
 import { useCommitteeAssignments } from '@/src/hooks/useCommitteeAssignments'
 import { StakingCalculator } from '@/src/components/validators/StakingCalculator'
+import { RiskTopologyMap } from '@/src/components/canvas/RiskTopologyMap'
+import { RiskSummaryPanel } from '@/src/components/validators/RiskSummaryPanel'
+import { useCorrelationRisk } from '@/src/hooks/useCorrelationRisk'
+import type { NodeConfig } from '@/src/services/infrastructureService'
 
 const DEFAULT_VALIDATORS = [100, 101, 102, 103, 104, 105]
 
+/** Build demo node configs from validator indices (used when no real topology is supplied). */
+function buildDemoNodeConfigs(validatorIndices: number[]): NodeConfig[] {
+  return validatorIndices.map((vi) => ({
+    nodeId: `validator-${vi}`,
+    ip: null,
+    cloudRegion: null,
+    lat: null,
+    lng: null,
+  }))
+}
+
 /**
  * Validator dashboard. Hosts the "Balance Reconciliation" accordion: a
  * per-validator effective-vs-actual breakdown table, plus projected-unlock
  * cards for any validators currently over the effective-balance cap.
+ * Also includes the Correlation Risk section powered by DBSCAN cluster analysis.
  */
 export function ValidatorDashboard({
   validatorIndices = DEFAULT_VALIDATORS,
   beaconNodeUrl,
+  nodeConfigs,
 }: {
   validatorIndices?: number[]
   beaconNodeUrl?: string
+  /** Optional topology configs for the correlation risk analyzer. */
+  nodeConfigs?: NodeConfig[]
 }) {
   const [open, setOpen] = useState(true)
   const [queueOpen, setQueueOpen] = useState(true)
   const [topoOpen, setTopoOpen] = useState(true)
   const [consolidationOpen, setConsolidationOpen] = useState(true)
+  const [riskOpen, setRiskOpen] = useState(true)
+  const [selectedClusterId, setSelectedClusterId] = useState<number | null>(null)
   const { byValidator } = useValidatorBalances(validatorIndices, { beaconNodeUrl })
   const committee = useCommitteeAssignments(validatorIndices, { beaconNodeUrl })
 
+  const indicesKey = validatorIndices.join(',')
+  const effectiveNodeConfigs = useMemo(
+    () => nodeConfigs ?? buildDemoNodeConfigs(validatorIndices),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [nodeConfigs, indicesKey],
+  )
+
+  const { nodes: riskNodes, clusters: riskClusters, status: riskStatus } = useCorrelationRisk(
+    effectiveNodeConfigs,
+    { beaconNodeUrl },
+  )
+
   const cappedValidators = useMemo(
     () => validatorIndices.filter((vi) => byValidator[vi]?.summary.latest?.capped),
     [validatorIndices, byValidator],
@@ -158,6 +191,80 @@ export function ValidatorDashboard({
           </div>
         )}
       </section>
+
+      <section className="overflow-hidden rounded-3xl border border-white/10 bg-slate-900/80 text-white">
+        <button
+          type="button"
+          onClick={() => setRiskOpen((o) => !o)}
+          className="flex w-full items-center justify-between gap-4 p-6 text-left"
+          aria-expanded={riskOpen}
+        >
+          <div>
+            <h2 className="text-xl font-semibold">Correlation Risk</h2>
+            <p className="text-sm text-slate-400">
+              Correlated slashing risk · {riskClusters.length} cluster{riskClusters.length !== 1 ? 's' : ''} detected
+              {riskStatus === 'running' && ' · Analysing…'}
+              {riskClusters.some((c) => c.tier === 'critical') && ' · ⚠ critical risk'}
+            </p>
+          </div>
+          <span className="flex h-8 w-8 items-center justify-center rounded-full border border-white/10 text-lg text-slate-300">
+            {riskOpen ? '−' : '+'}
+          </span>
+        </button>
+
+        {riskOpen && (
+          <div className="space-y-6 px-6 pb-6">
+            {riskStatus === 'running' && riskNodes.length === 0 ? (
+              <p className="py-6 text-center text-sm text-slate-400">Running cluster analysis…</p>
+            ) : (
+              <>
+                <RiskTopologyMap
+                  nodes={riskNodes}
+                  clusters={riskClusters}
+                  onSelectCluster={setSelectedClusterId}
+                />
+                <RiskSummaryPanel
+                  clusters={riskClusters}
+                  selectedClusterId={selectedClusterId}
+                  onSelectCluster={setSelectedClusterId}
+                />
+                {selectedClusterId !== null && (() => {
+                  const cluster = riskClusters.find((c) => c.clusterId === selectedClusterId)
+                  if (!cluster || cluster.recommendations.length === 0) return null
+                  return (
+                    <div className="space-y-3 rounded-2xl border border-white/10 bg-slate-950/60 p-5">
+                      <div className="flex items-center justify-between">
+                        <h3 className="text-sm font-semibold text-slate-200">
+                          Cluster #{selectedClusterId} — Mitigation Recommendations
+                        </h3>
+                        <button
+                          type="button"
+                          onClick={() => setSelectedClusterId(null)}
+                          className="text-xs text-slate-500 hover:text-slate-300"
+                        >
+                          Dismiss
+                        </button>
+                      </div>
+                      <ul className="space-y-2">
+                        {cluster.recommendations.map((rec, i) => (
+                          <li key={i} className="rounded-xl border border-white/5 bg-slate-900/60 p-3">
+                            <p className="text-xs font-semibold text-slate-300">{rec.title}</p>
+                            <p className="mt-1 text-xs text-slate-400">{rec.detail}</p>
+                            <p className="mt-1 text-[11px] text-slate-500">
+                              Shared value: <span className="font-mono text-slate-400">{rec.sharedValue}</span>
+                              {' · '}{rec.affectedNodes} node{rec.affectedNodes !== 1 ? 's' : ''} affected
+                            </p>
+                          </li>
+                        ))}
+                      </ul>
+                    </div>
+                  )
+                })()}
+              </>
+            )}
+          </div>
+        )}
+      </section>
     </div>
   )
 }
diff --git a/src/hooks/useCorrelationRisk.ts b/src/hooks/useCorrelationRisk.ts
new file mode 100644
index 0000000..7de2d14
--- /dev/null
+++ b/src/hooks/useCorrelationRisk.ts
@@ -0,0 +1,207 @@
+'use client'
+
+// Risk analysis hook for correlated slashing.
+//
+// 1. Accepts a list of node configs (with optional self-reported geo/IP/region).
+// 2. Resolves infra metadata via infrastructureService (demo or production).
+// 3. Posts to riskClusterWorker for off-thread DBSCAN + risk scoring.
+// 4. Falls back to main-thread analysis when workers are unavailable.
+// 5. Persists results to useRiskStore.
+
+import { useEffect, useRef, useState } from 'react'
+import { useRiskStore, type ClusterRiskResult, type RiskNode } from '@/src/store/riskSlice'
+import {
+  createDemoInfrastructureService,
+  type NodeConfig,
+  type NodeInfraMetadata,
+} from '@/src/services/infrastructureService'
+import { dbscan, DBSCAN_EPSILON_KM, DBSCAN_MIN_PTS, type GeoPoint } from '@/src/utils/dbscan'
+import { computeRiskScore, sharedCount, riskTier } from '@/src/utils/riskScore'
+import { generateMitigationReport, ipToSubnet } from '@/src/utils/mitigationRecommender'
+import type { RiskClusterRequest, RiskClusterResponse, RiskClusterError } from '@/src/workers/riskClusterWorker'
+
+const REFRESH_INTERVAL_MS = 60_000
+
+/** Create the cluster worker (returns null in environments without Worker). */
+function createWorker(): Worker | null {
+  try {
+    return new Worker(new URL('../workers/riskClusterWorker.ts', import.meta.url))
+  } catch {
+    return null
+  }
+}
+
+/** Main-thread fallback: synchronous DBSCAN + risk scoring. */
+function analyseOnMainThread(
+  nodes: NodeInfraMetadata[],
+): { riskNodes: RiskNode[]; clusters: ClusterRiskResult[] } {
+  const geoPoints: GeoPoint[] = nodes.map((n, i) => ({ index: i, lat: n.lat, lng: n.lng }))
+  const labels = dbscan(geoPoints, DBSCAN_EPSILON_KM, DBSCAN_MIN_PTS)
+
+  const riskNodes: RiskNode[] = nodes.map((n, i) => ({ ...n, clusterId: labels[i] }))
+
+  const clusterMap = new Map<number, number[]>()
+  for (let i = 0; i < labels.length; i++) {
+    const cid = labels[i]
+    if (cid < 0) continue
+    const arr = clusterMap.get(cid)
+    if (arr) arr.push(i)
+    else clusterMap.set(cid, [i])
+  }
+
+  const clusters: ClusterRiskResult[] = []
+  for (const [clusterId, indices] of clusterMap) {
+    const members = indices.map((i) => nodes[i])
+    const totalNodes = members.length
+    const ips = members.map((m) => (m.ip ? ipToSubnet(m.ip) : null))
+    const asns = members.map((m) => m.asn)
+    const cloudRegions = members.map((m) => m.cloudRegion)
+
+    const sharedIpCount = sharedCount(ips)
+    const sharedAsnCount = sharedCount(asns)
+    const sharedCloudRegionCount = sharedCount(cloudRegions)
+
+    const riskScore = computeRiskScore({ sharedIpCount, sharedAsnCount, sharedCloudRegionCount, totalNodes })
+    const tier = riskTier(riskScore)
+    const report = generateMitigationReport(clusterId, riskScore, tier, members.map((m) => m.ip), asns, cloudRegions)
+
+    clusters.push({
+      clusterId,
+      nodeIds: members.map((m) => m.nodeId),
+      nodeCount: totalNodes,
+      riskScore,
+      tier,
+      sharedIpCount,
+      sharedAsnCount,
+      sharedCloudRegionCount,
+      recommendations: report.recommendations,
+    })
+  }
+  clusters.sort((a, b) => b.riskScore - a.riskScore)
+  return { riskNodes, clusters }
+}
+
+export interface UseCorrelationRiskOptions {
+  /** Beacon node URL; omit to use demo data. */
+  beaconNodeUrl?: string
+  /** Override for polling interval (ms). Defaults to 60 s. */
+  refreshIntervalMs?: number
+}
+
+export interface CorrelationRiskState {
+  nodes: RiskNode[]
+  clusters: ClusterRiskResult[]
+  status: 'idle' | 'running' | 'complete' | 'error'
+  error: string | null
+  lastAnalysedAt: number | null
+  /** Manually trigger a re-analysis. */
+  refresh: () => void
+}
+
+/**
+ * Hook that orchestrates infra metadata resolution and risk cluster analysis.
+ * Accepts node configs, periodically re-analyses, and exposes results from
+ * the shared Zustand risk store.
+ */
+export function useCorrelationRisk(
+  nodeConfigs: NodeConfig[],
+  options: UseCorrelationRiskOptions = {},
+): CorrelationRiskState {
+  const { refreshIntervalMs = REFRESH_INTERVAL_MS } = options
+
+  const setStatus = useRiskStore((s) => s.setStatus)
+  const setResults = useRiskStore((s) => s.setResults)
+  const nodes = useRiskStore((s) => s.nodes)
+  const clusters = useRiskStore((s) => s.clusters)
+  const status = useRiskStore((s) => s.status)
+  const error = useRiskStore((s) => s.error)
+  const lastAnalysedAt = useRiskStore((s) => s.lastAnalysedAt)
+
+  const workerRef = useRef<Worker | null>(null)
+  const requestIdRef = useRef(0)
+  const pendingRef = useRef<string | null>(null)
+  const [refreshTick, setRefreshTick] = useState(0)
+
+  // Stable key to detect config changes.
+  const configKey = nodeConfigs.map((c) => c.nodeId).sort().join(',')
+
+  // Worker lifecycle.
+  useEffect(() => {
+    const worker = createWorker()
+    workerRef.current = worker
+
+    const handler = (e: MessageEvent<RiskClusterResponse | RiskClusterError>) => {
+      const msg = e.data
+      if (msg.payload.requestId !== pendingRef.current) return
+      if (msg.type === 'RESULT') {
+        setResults(msg.payload.nodes, msg.payload.clusters)
+      } else if (msg.type === 'ERROR') {
+        setStatus('error', msg.payload.message)
+      }
+    }
+    worker?.addEventListener('message', handler)
+    return () => {
+      worker?.removeEventListener('message', handler)
+      worker?.terminate()
+    }
+  }, [setResults, setStatus])
+
+  // Main analysis effect.
+  useEffect(() => {
+    if (nodeConfigs.length === 0) return
+
+    let cancelled = false
+
+    const run = async () => {
+      setStatus('running')
+      try {
+        const service = createDemoInfrastructureService()
+        const infraNodes = await service.fetchNodeMetadata(nodeConfigs)
+        if (cancelled) return
+
+        const worker = workerRef.current
+        if (worker) {
+          const requestId = `risk-${++requestIdRef.current}`
+          pendingRef.current = requestId
+          const req: RiskClusterRequest = {
+            type: 'ANALYSE',
+            payload: { requestId, nodes: infraNodes },
+          }
+          worker.postMessage(req)
+          // Worker response handled in the handler above.
+          return
+        }
+
+        // Main-thread fallback.
+        const { riskNodes, clusters: computed } = analyseOnMainThread(infraNodes)
+        if (!cancelled) setResults(riskNodes, computed)
+      } catch (err) {
+        if (!cancelled) {
+          setStatus('error', err instanceof Error ? err.message : 'Analysis failed')
+        }
+      }
+    }
+
+    run()
+    return () => {
+      cancelled = true
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [configKey, refreshTick, setStatus, setResults])
+
+  // Periodic refresh.
+  useEffect(() => {
+    if (refreshIntervalMs <= 0) return
+    const id = window.setInterval(() => setRefreshTick((t) => t + 1), refreshIntervalMs)
+    return () => window.clearInterval(id)
+  }, [refreshIntervalMs])
+
+  return {
+    nodes,
+    clusters,
+    status: status as CorrelationRiskState['status'],
+    error,
+    lastAnalysedAt,
+    refresh: () => setRefreshTick((t) => t + 1),
+  }
+}
diff --git a/src/services/infrastructureService.ts b/src/services/infrastructureService.ts
new file mode 100644
index 0000000..05d3cfa
--- /dev/null
+++ b/src/services/infrastructureService.ts
@@ -0,0 +1,186 @@
+// Infrastructure metadata aggregation service.
+//
+// Sources (per issue spec):
+//   1. Node self-reported config  – nodeConfig.ip, nodeConfig.cloudRegion
+//   2. IP geolocation API         – lat/lng derived from IP
+//   3. BGP ASN lookup             – ASN for the node's IP
+//
+// In demo mode all data is deterministically derived from the node ID so no
+// real network calls are made. In production each method hits a real API.
+
+export interface NodeConfig {
+  /** Unique node identifier. */
+  nodeId: string
+  /** Self-reported IP address (IPv4). */
+  ip: string | null
+  /** Self-reported cloud region tag (e.g. "aws:us-east-1"). */
+  cloudRegion: string | null
+  /** Self-reported geographic coordinates (may be null). */
+  lat: number | null
+  lng: number | null
+}
+
+export interface NodeInfraMetadata {
+  nodeId: string
+  ip: string | null
+  /** BGP Autonomous System Number, e.g. "AS15169". */
+  asn: string | null
+  cloudRegion: string | null
+  lat: number
+  lng: number
+}
+
+// ── Deterministic demo helpers ────────────────────────────────────────────────
+
+function fnv32(s: string): number {
+  let h = 0x811c9dc5
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i)
+    h = Math.imul(h, 0x01000193)
+  }
+  return h >>> 0
+}
+
+function demoFloat(seed: string, lo: number, hi: number): number {
+  return lo + (fnv32(seed) / 0x1_0000_0000) * (hi - lo)
+}
+
+const DEMO_PROVIDERS = ['aws', 'gcp', 'azure', 'hetzner', 'ovh']
+const DEMO_REGIONS: Record<string, string[]> = {
+  aws: ['us-east-1', 'us-west-2', 'eu-west-1', 'ap-southeast-1'],
+  gcp: ['us-central1', 'europe-west1', 'asia-east1'],
+  azure: ['eastus', 'westeurope', 'southeastasia'],
+  hetzner: ['nbg1', 'fsn1', 'hel1'],
+  ovh: ['rbx', 'sbg', 'gra'],
+}
+const DEMO_ASNS: Record<string, string> = {
+  aws: 'AS16509',
+  gcp: 'AS15169',
+  azure: 'AS8075',
+  hetzner: 'AS24940',
+  ovh: 'AS16276',
+}
+
+function demoMetadata(nodeId: string): NodeInfraMetadata {
+  const providerIdx = fnv32(`prov:${nodeId}`) % DEMO_PROVIDERS.length
+  const provider = DEMO_PROVIDERS[providerIdx]
+  const regions = DEMO_REGIONS[provider]
+  const regionIdx = fnv32(`reg:${nodeId}`) % regions.length
+  const cloudRegion = `${provider}:${regions[regionIdx]}`
+  const asn = DEMO_ASNS[provider]
+  // Spread across major data-center latitudes.
+  const lat = demoFloat(`lat:${nodeId}`, -55, 70)
+  const lng = demoFloat(`lng:${nodeId}`, -120, 140)
+  const ipA = (fnv32(`ipa:${nodeId}`) % 200) + 10
+  const ipB = (fnv32(`ipb:${nodeId}`) % 255)
+  const ipC = (fnv32(`ipc:${nodeId}`) % 255)
+  const ipD = (fnv32(`ipd:${nodeId}`) % 254) + 1
+  const ip = `${ipA}.${ipB}.${ipC}.${ipD}`
+  return { nodeId, ip, asn, cloudRegion, lat, lng }
+}
+
+// ── HTTP service ──────────────────────────────────────────────────────────────
+
+/**
+ * Resolve lat/lng for an IP via an open geolocation JSON endpoint.
+ * Falls back to [0, 0] on any error so we never block cluster analysis.
+ */
+async function fetchIpGeo(ip: string): Promise<{ lat: number; lng: number }> {
+  try {
+    const res = await fetch(`https://ipapi.co/${ip}/json/`)
+    if (!res.ok) return { lat: 0, lng: 0 }
+    const body = (await res.json()) as { latitude?: number; longitude?: number }
+    return {
+      lat: typeof body.latitude === 'number' ? body.latitude : 0,
+      lng: typeof body.longitude === 'number' ? body.longitude : 0,
+    }
+  } catch {
+    return { lat: 0, lng: 0 }
+  }
+}
+
+/**
+ * Resolve the BGP ASN for an IP via ipapi.co.
+ * Returns null on any error.
+ */
+async function fetchAsn(ip: string): Promise<string | null> {
+  try {
+    const res = await fetch(`https://ipapi.co/${ip}/json/`)
+    if (!res.ok) return null
+    const body = (await res.json()) as { asn?: string }
+    return body.asn ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Build infrastructure metadata for a node from its self-reported config plus
+ * optional API-enriched geo/ASN data.
+ */
+export async function resolveNodeMetadata(config: NodeConfig): Promise<NodeInfraMetadata> {
+  let lat = config.lat ?? 0
+  let lng = config.lng ?? 0
+  let asn: string | null = null
+
+  if (config.ip) {
+    // Fetch geo and ASN in parallel.
+    const [geo, resolvedAsn] = await Promise.all([
+      config.lat == null || config.lng == null ? fetchIpGeo(config.ip) : Promise.resolve({ lat, lng }),
+      fetchAsn(config.ip),
+    ])
+    lat = geo.lat
+    lng = geo.lng
+    asn = resolvedAsn
+  }
+
+  return {
+    nodeId: config.nodeId,
+    ip: config.ip,
+    asn,
+    cloudRegion: config.cloudRegion,
+    lat,
+    lng,
+  }
+}
+
+// ── Service factory ────────────────────────────────────────────────────────────
+
+export type InfrastructureProvider = {
+  /**
+   * Fetch infrastructure metadata for a set of node configs.
+   * In demo mode returns deterministic synthetic data immediately.
+   * In production issues real API calls for geo/ASN enrichment.
+   */
+  fetchNodeMetadata(configs: NodeConfig[]): Promise<NodeInfraMetadata[]>
+}
+
+/** Demo provider — fully deterministic, zero network calls. */
+export function createDemoInfrastructureService(): InfrastructureProvider {
+  return {
+    async fetchNodeMetadata(configs) {
+      return configs.map((c) => {
+        if (c.ip && c.lat != null && c.lng != null) {
+          return {
+            nodeId: c.nodeId,
+            ip: c.ip,
+            asn: null,
+            cloudRegion: c.cloudRegion,
+            lat: c.lat,
+            lng: c.lng,
+          }
+        }
+        return demoMetadata(c.nodeId)
+      })
+    },
+  }
+}
+
+/** Production provider — enriches configs with real geo/ASN API calls. */
+export function createInfrastructureService(): InfrastructureProvider {
+  return {
+    async fetchNodeMetadata(configs) {
+      return Promise.all(configs.map(resolveNodeMetadata))
+    },
+  }
+}
diff --git a/src/store/riskSlice.ts b/src/store/riskSlice.ts
new file mode 100644
index 0000000..031dc94
--- /dev/null
+++ b/src/store/riskSlice.ts
@@ -0,0 +1,65 @@
+// State management for correlated slashing risk analysis.
+//
+// Holds per-cluster risk results as they are returned by the DBSCAN
+// worker and the risk-score computation pass. Components read from this
+// store; useCorrelationRisk writes to it.
+
+import { create } from 'zustand'
+import type { RiskTier } from '@/src/utils/riskScore'
+import type { MitigationRecommendation } from '@/src/utils/mitigationRecommender'
+import type { NodeInfraMetadata } from '@/src/services/infrastructureService'
+
+export type AnalysisStatus = 'idle' | 'running' | 'complete' | 'error'
+
+/** Per-node enrichment stored after infrastructure resolution. */
+export interface RiskNode extends NodeInfraMetadata {
+  /** Cluster ID assigned by DBSCAN (-1 = noise). */
+  clusterId: number
+}
+
+/** Aggregated risk result for one DBSCAN-detected cluster. */
+export interface ClusterRiskResult {
+  clusterId: number
+  nodeIds: string[]
+  /** Number of nodes in the cluster. */
+  nodeCount: number
+  riskScore: number
+  tier: RiskTier
+  /** Factor breakdowns. */
+  sharedIpCount: number
+  sharedAsnCount: number
+  sharedCloudRegionCount: number
+  recommendations: MitigationRecommendation[]
+}
+
+interface RiskState {
+  status: AnalysisStatus
+  error: string | null
+  nodes: RiskNode[]
+  clusters: ClusterRiskResult[]
+  lastAnalysedAt: number | null
+
+  // ── Actions ────────────────────────────────────────────────────────────────
+  setStatus: (status: AnalysisStatus, error?: string) => void
+  setResults: (nodes: RiskNode[], clusters: ClusterRiskResult[]) => void
+  reset: () => void
+}
+
+const initialState = {
+  status: 'idle' as AnalysisStatus,
+  error: null,
+  nodes: [] as RiskNode[],
+  clusters: [] as ClusterRiskResult[],
+  lastAnalysedAt: null,
+}
+
+export const useRiskStore = create<RiskState>((set) => ({
+  ...initialState,
+
+  setStatus: (status, error = null) => set({ status, error }),
+
+  setResults: (nodes, clusters) =>
+    set({ nodes, clusters, status: 'complete', error: null, lastAnalysedAt: Date.now() }),
+
+  reset: () => set({ ...initialState }),
+}))
diff --git a/src/utils/dbscan.ts b/src/utils/dbscan.ts
new file mode 100644
index 0000000..a69737b
--- /dev/null
+++ b/src/utils/dbscan.ts
@@ -0,0 +1,102 @@
+// DBSCAN density-based clustering algorithm for geo-coordinates.
+//
+// Parameters:
+//   ε  = 500 km  (maximum neighbourhood radius)
+//   minPts = 3   (minimum cluster member count)
+//
+// Distance is computed via the Haversine formula on WGS-84 lat/lng pairs.
+// Noise points (not reachable from any core point) are assigned cluster -1.
+// This runs synchronously; for large node sets post to riskClusterWorker.
+
+export const DBSCAN_EPSILON_KM = 500
+export const DBSCAN_MIN_PTS = 3
+
+const EARTH_RADIUS_KM = 6_371
+
+/** Haversine great-circle distance in kilometres between two lat/lng points. */
+export function haversineKm(
+  lat1: number,
+  lng1: number,
+  lat2: number,
+  lng2: number,
+): number {
+  const dLat = ((lat2 - lat1) * Math.PI) / 180
+  const dLng = ((lng2 - lng1) * Math.PI) / 180
+  const a =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos((lat1 * Math.PI) / 180) *
+      Math.cos((lat2 * Math.PI) / 180) *
+      Math.sin(dLng / 2) ** 2
+  return EARTH_RADIUS_KM * 2 * Math.asin(Math.sqrt(a))
+}
+
+export interface GeoPoint {
+  /** Index into the original input array. */
+  index: number
+  lat: number
+  lng: number
+}
+
+/**
+ * Run DBSCAN on an array of geo-points.
+ *
+ * Returns an array of cluster IDs parallel to the input: -1 = noise,
+ * 0..N-1 = cluster index.
+ */
+export function dbscan(
+  points: GeoPoint[],
+  epsilonKm: number = DBSCAN_EPSILON_KM,
+  minPts: number = DBSCAN_MIN_PTS,
+): number[] {
+  const n = points.length
+  const labels = new Array<number>(n).fill(-2) // -2 = unvisited
+  let clusterCount = 0
+
+  /** Return indices of all points within ε of point i. */
+  function regionQuery(i: number): number[] {
+    const neighbours: number[] = []
+    const { lat, lng } = points[i]
+    for (let j = 0; j < n; j++) {
+      if (haversineKm(lat, lng, points[j].lat, points[j].lng) <= epsilonKm) {
+        neighbours.push(j)
+      }
+    }
+    return neighbours
+  }
+
+  for (let i = 0; i < n; i++) {
+    if (labels[i] !== -2) continue // already visited
+    const neighbours = regionQuery(i)
+    if (neighbours.length < minPts) {
+      labels[i] = -1 // noise (may be absorbed later)
+      continue
+    }
+
+    const clusterId = clusterCount++
+    labels[i] = clusterId
+
+    // Expand cluster: seed queue with all current neighbours.
+    const queue = [...neighbours]
+    const queued = new Set<number>(neighbours)
+    let qi = 0
+
+    while (qi < queue.length) {
+      const q = queue[qi++]
+      if (labels[q] === -1) labels[q] = clusterId // absorb border noise
+      if (labels[q] !== -2) continue // already labelled
+      labels[q] = clusterId
+
+      const qNeighbours = regionQuery(q)
+      if (qNeighbours.length >= minPts) {
+        for (const nb of qNeighbours) {
+          if (!queued.has(nb)) {
+            queued.add(nb)
+            queue.push(nb)
+          }
+        }
+      }
+    }
+  }
+
+  return labels
+}
diff --git a/src/utils/mitigationRecommender.ts b/src/utils/mitigationRecommender.ts
new file mode 100644
index 0000000..81ee7c7
--- /dev/null
+++ b/src/utils/mitigationRecommender.ts
@@ -0,0 +1,122 @@
+// Mitigation recommendation engine for correlated slashing risk.
+//
+// For each risk factor (IP subnet, ASN, cloud region) it generates human-
+// readable diversification suggestions based on the count of affected nodes
+// and the specific shared values detected in a cluster.
+
+import type { RiskTier } from '@/src/utils/riskScore'
+
+export interface MitigationRecommendation {
+  /** Short machine-readable key for the risk factor. */
+  factor: 'ip_subnet' | 'asn' | 'cloud_region'
+  /** Human-readable title. */
+  title: string
+  /** Full recommendation text. */
+  detail: string
+  /** Number of nodes affected by this factor. */
+  affectedNodes: number
+  /** The shared value (e.g. "AS15169", "us-east-1"). */
+  sharedValue: string
+}
+
+export interface ClusterMitigationReport {
+  clusterId: number
+  riskScore: number
+  tier: RiskTier
+  recommendations: MitigationRecommendation[]
+}
+
+/** IP addresses → /24 subnet prefix (e.g. "203.0.113.5" → "203.0.113"). */
+export function ipToSubnet(ip: string): string {
+  const parts = ip.split('.')
+  if (parts.length === 4) return parts.slice(0, 3).join('.')
+  // IPv6 or unexpected: return as-is
+  return ip
+}
+
+/**
+ * Generate mitigation recommendations for a cluster.
+ *
+ * @param clusterId  Numeric cluster identifier
+ * @param riskScore  Pre-computed risk score [0,1]
+ * @param tier       Pre-computed risk tier
+ * @param ips        Per-node IP strings (null = unknown)
+ * @param asns       Per-node ASN strings like "AS12345" (null = unknown)
+ * @param cloudRegions  Per-node cloud region strings like "us-east-1" (null = unknown)
+ */
+export function generateMitigationReport(
+  clusterId: number,
+  riskScore: number,
+  tier: RiskTier,
+  ips: Array<string | null>,
+  asns: Array<string | null>,
+  cloudRegions: Array<string | null>,
+): ClusterMitigationReport {
+  const recommendations: MitigationRecommendation[] = []
+
+  // ── IP subnet analysis ────────────────────────────────────────────────────
+  const subnetFreq = new Map<string, number>()
+  for (const ip of ips) {
+    if (ip == null) continue
+    const subnet = ipToSubnet(ip)
+    subnetFreq.set(subnet, (subnetFreq.get(subnet) ?? 0) + 1)
+  }
+  for (const [subnet, count] of subnetFreq) {
+    if (count > 1) {
+      recommendations.push({
+        factor: 'ip_subnet',
+        title: 'Diversify IP subnets',
+        detail: `${count} node${count !== 1 ? 's' : ''} share the ${subnet}.0/24 subnet. ` +
+          `Move ${count - 1} node${count - 1 !== 1 ? 's' : ''} to a different network ` +
+          `provider or subnet to eliminate correlated network-layer failures.`,
+        affectedNodes: count,
+        sharedValue: `${subnet}.0/24`,
+      })
+    }
+  }
+
+  // ── ASN analysis ──────────────────────────────────────────────────────────
+  const asnFreq = new Map<string, number>()
+  for (const asn of asns) {
+    if (asn == null) continue
+    asnFreq.set(asn, (asnFreq.get(asn) ?? 0) + 1)
+  }
+  for (const [asn, count] of asnFreq) {
+    if (count > 1) {
+      recommendations.push({
+        factor: 'asn',
+        title: 'Diversify autonomous systems',
+        detail: `${count} node${count !== 1 ? 's' : ''} are on ${asn}. ` +
+          `Move ${count - 1} node${count - 1 !== 1 ? 's' : ''} to a different ISP or ` +
+          `autonomous system to avoid BGP-level correlated outages.`,
+        affectedNodes: count,
+        sharedValue: asn,
+      })
+    }
+  }
+
+  // ── Cloud region analysis ─────────────────────────────────────────────────
+  const regionFreq = new Map<string, number>()
+  for (const region of cloudRegions) {
+    if (region == null) continue
+    regionFreq.set(region, (regionFreq.get(region) ?? 0) + 1)
+  }
+  for (const [region, count] of regionFreq) {
+    if (count > 1) {
+      recommendations.push({
+        factor: 'cloud_region',
+        title: 'Diversify cloud regions',
+        detail: `${count} node${count !== 1 ? 's' : ''} are deployed in ${region}. ` +
+          `Move ${count - 1} node${count - 1 !== 1 ? 's' : ''} to a different cloud region ` +
+          `or provider to eliminate single-AZ failure correlation.`,
+        affectedNodes: count,
+        sharedValue: region,
+      })
+    }
+  }
+
+  // Sort by most-affected first.
+  recommendations.sort((a, b) => b.affectedNodes - a.affectedNodes)
+
+  return { clusterId, riskScore, tier, recommendations }
+}
diff --git a/src/utils/riskScore.ts b/src/utils/riskScore.ts
new file mode 100644
index 0000000..2bcb950
--- /dev/null
+++ b/src/utils/riskScore.ts
@@ -0,0 +1,68 @@
+// Correlated slashing risk score computation.
+//
+// Formula (from issue spec):
+//   score = 0.4 × (shared_IP_count / total_nodes)
+//          + 0.3 × (shared_ASN_count / total_nodes)
+//          + 0.3 × (shared_cloud_region_count / total_nodes)
+//
+// "shared_X_count" = nodes whose X value appears more than once in the cluster.
+// Score is bounded to [0, 1].
+
+export type RiskTier = 'low' | 'medium' | 'high' | 'critical'
+
+export const RISK_TIER_THRESHOLDS: Record<RiskTier, [number, number]> = {
+  low: [0, 0.25],
+  medium: [0.25, 0.5],
+  high: [0.5, 0.75],
+  critical: [0.75, 1.0001], // upper-open; catches exactly 1.0
+}
+
+/** Determine the risk tier for a given score. */
+export function riskTier(score: number): RiskTier {
+  if (score >= 0.75) return 'critical'
+  if (score >= 0.5) return 'high'
+  if (score >= 0.25) return 'medium'
+  return 'low'
+}
+
+export interface RiskFactors {
+  /** IP subnet prefix (/24) or full IP string that are shared by >1 node. */
+  sharedIpCount: number
+  /** Nodes sharing a common ASN with at least one other node in the cluster. */
+  sharedAsnCount: number
+  /** Nodes sharing a cloud region with at least one other node in the cluster. */
+  sharedCloudRegionCount: number
+  totalNodes: number
+}
+
+/**
+ * Compute the weighted correlated slashing risk score for a cluster.
+ * Returns a value in [0, 1].
+ */
+export function computeRiskScore(factors: RiskFactors): number {
+  const { sharedIpCount, sharedAsnCount, sharedCloudRegionCount, totalNodes } = factors
+  if (totalNodes === 0) return 0
+  const score =
+    0.4 * (sharedIpCount / totalNodes) +
+    0.3 * (sharedAsnCount / totalNodes) +
+    0.3 * (sharedCloudRegionCount / totalNodes)
+  return Math.min(1, Math.max(0, score))
+}
+
+/**
+ * Given a list of values (IP / ASN / region per node), return the count of
+ * nodes whose value is shared with at least one other node in the cluster.
+ * Nodes with a null/undefined value are treated as unique (not shared).
+ */
+export function sharedCount(values: Array<string | null | undefined>): number {
+  const freq = new Map<string, number>()
+  for (const v of values) {
+    if (v == null) continue
+    freq.set(v, (freq.get(v) ?? 0) + 1)
+  }
+  let count = 0
+  for (const v of values) {
+    if (v != null && (freq.get(v) ?? 0) > 1) count++
+  }
+  return count
+}
diff --git a/src/workers/riskClusterWorker.ts b/src/workers/riskClusterWorker.ts
new file mode 100644
index 0000000..67af3b7
--- /dev/null
+++ b/src/workers/riskClusterWorker.ts
@@ -0,0 +1,157 @@
+// Web worker for DBSCAN clustering and risk score computation.
+//
+// Accepts a list of NodeInfraMetadata objects, runs DBSCAN on the lat/lng
+// coordinates (ε=500 km, minPts=3), then computes the weighted slashing risk
+// score and mitigation recommendations for every detected cluster.
+//
+// Worker message protocol:
+//   Request  → { type: 'ANALYSE'; payload: { requestId: string; nodes: NodeInfraMetadata[] } }
+//   Response → { type: 'RESULT';  payload: { requestId: string; nodes: RiskNode[]; clusters: ClusterRiskResult[] } }
+//            | { type: 'ERROR';   payload: { requestId: string; message: string } }
+
+import {
+  dbscan,
+  DBSCAN_EPSILON_KM,
+  DBSCAN_MIN_PTS,
+  type GeoPoint,
+} from '@/src/utils/dbscan'
+import { computeRiskScore, sharedCount, riskTier } from '@/src/utils/riskScore'
+import { generateMitigationReport, ipToSubnet } from '@/src/utils/mitigationRecommender'
+import type { NodeInfraMetadata } from '@/src/services/infrastructureService'
+import type { RiskNode, ClusterRiskResult } from '@/src/store/riskSlice'
+
+// ── Message types ─────────────────────────────────────────────────────────────
+
+export interface RiskClusterRequest {
+  type: 'ANALYSE'
+  payload: {
+    requestId: string
+    nodes: NodeInfraMetadata[]
+  }
+}
+
+export interface RiskClusterResponse {
+  type: 'RESULT'
+  payload: {
+    requestId: string
+    nodes: RiskNode[]
+    clusters: ClusterRiskResult[]
+  }
+}
+
+export interface RiskClusterError {
+  type: 'ERROR'
+  payload: {
+    requestId: string
+    message: string
+  }
+}
+
+function post(msg: RiskClusterResponse | RiskClusterError): void {
+  ;(self as unknown as Worker).postMessage(msg)
+}
+
+// ── Core analysis ─────────────────────────────────────────────────────────────
+
+function analyse(
+  nodes: NodeInfraMetadata[],
+): { riskNodes: RiskNode[]; clusters: ClusterRiskResult[] } {
+  // 1. Build geo-points for DBSCAN.
+  const geoPoints: GeoPoint[] = nodes.map((n, i) => ({
+    index: i,
+    lat: n.lat,
+    lng: n.lng,
+  }))
+
+  // 2. Cluster.
+  const labels = dbscan(geoPoints, DBSCAN_EPSILON_KM, DBSCAN_MIN_PTS)
+
+  // 3. Annotate nodes.
+  const riskNodes: RiskNode[] = nodes.map((n, i) => ({
+    ...n,
+    clusterId: labels[i],
+  }))
+
+  // 4. Group nodes by cluster (skip noise = -1).
+  const clusterMap = new Map<number, number[]>()
+  for (let i = 0; i < labels.length; i++) {
+    const cid = labels[i]
+    if (cid < 0) continue
+    const arr = clusterMap.get(cid)
+    if (arr) arr.push(i)
+    else clusterMap.set(cid, [i])
+  }
+
+  // 5. Compute risk scores & mitigations per cluster.
+  const clusters: ClusterRiskResult[] = []
+  for (const [clusterId, indices] of clusterMap) {
+    const members = indices.map((i) => nodes[i])
+    const totalNodes = members.length
+
+    // Normalise IP subnets so /24 sharing is detected.
+    const ips = members.map((m) => (m.ip ? ipToSubnet(m.ip) : null))
+    const asns = members.map((m) => m.asn)
+    const cloudRegions = members.map((m) => m.cloudRegion)
+
+    const sharedIpCount = sharedCount(ips)
+    const sharedAsnCount = sharedCount(asns)
+    const sharedCloudRegionCount = sharedCount(cloudRegions)
+
+    const riskScore = computeRiskScore({
+      sharedIpCount,
+      sharedAsnCount,
+      sharedCloudRegionCount,
+      totalNodes,
+    })
+    const tier = riskTier(riskScore)
+
+    const report = generateMitigationReport(
+      clusterId,
+      riskScore,
+      tier,
+      members.map((m) => m.ip),
+      asns,
+      cloudRegions,
+    )
+
+    clusters.push({
+      clusterId,
+      nodeIds: members.map((m) => m.nodeId),
+      nodeCount: totalNodes,
+      riskScore,
+      tier,
+      sharedIpCount,
+      sharedAsnCount,
+      sharedCloudRegionCount,
+      recommendations: report.recommendations,
+    })
+  }
+
+  // Sort clusters by descending risk score.
+  clusters.sort((a, b) => b.riskScore - a.riskScore)
+
+  return { riskNodes, clusters }
+}
+
+// ── Message handler ───────────────────────────────────────────────────────────
+
+self.onmessage = (e: MessageEvent<RiskClusterRequest>) => {
+  const msg = e.data
+  if (msg.type !== 'ANALYSE') return
+
+  const { requestId, nodes } = msg.payload
+  try {
+    const { riskNodes, clusters } = analyse(nodes)
+    post({ type: 'RESULT', payload: { requestId, nodes: riskNodes, clusters } })
+  } catch (err) {
+    post({
+      type: 'ERROR',
+      payload: {
+        requestId,
+        message: err instanceof Error ? err.message : 'Unknown worker error',
+      },
+    })
+  }
+}
+
+export {}