From b3542dfa5225d6079116f5a1d7e04380c08ef8a3 Mon Sep 17 00:00:00 2001
From: Jefferson Youashi <119521983+clintjeff2@users.noreply.github.com>
Date: Wed, 24 Jun 2026 21:31:16 +0100
Subject: [PATCH] Add validator consolidation dashboard

---
 .../validators/ConsolidationDashboard.tsx     | 85 ++++++++++++++++++
 .../validators/ValidatorDashboard.tsx         | 25 ++++++
 src/hooks/useConsolidationEligibility.ts      | 76 ++++++++++++++++
 src/utils/consolidationEligibility.ts         | 88 +++++++++++++++++++
 src/utils/ethMath.ts                          | 15 ++++
 src/utils/gasEstimator.ts                     | 28 ++++++
 src/workers/consolidationScannerWorker.ts     | 59 +++++++++++++
 7 files changed, 376 insertions(+)
 create mode 100644 src/components/validators/ConsolidationDashboard.tsx
 create mode 100644 src/hooks/useConsolidationEligibility.ts
 create mode 100644 src/utils/consolidationEligibility.ts
 create mode 100644 src/utils/ethMath.ts
 create mode 100644 src/utils/gasEstimator.ts
 create mode 100644 src/workers/consolidationScannerWorker.ts

diff --git a/src/components/validators/ConsolidationDashboard.tsx b/src/components/validators/ConsolidationDashboard.tsx
new file mode 100644
index 0000000..d59ded6
--- /dev/null
+++ b/src/components/validators/ConsolidationDashboard.tsx
@@ -0,0 +1,85 @@
+'use client'
+
+import { useMemo, useState } from 'react'
+import type { ValidatorReconciliation } from '@/src/hooks/useValidatorBalances'
+import { useConsolidationEligibility } from '@/src/hooks/useConsolidationEligibility'
+import { sortConsolidationRecommendations, type ConsolidationSortKey } from '@/src/utils/consolidationEligibility'
+
+interface ConsolidationDashboardProps {
+  validatorIndices: number[]
+  byValidator: Record<number, ValidatorReconciliation>
+}
+
+const sortLabels: Record<ConsolidationSortKey, string> = {
+  savings: 'Potential savings',
+  validator_count: 'Validator count',
+  readiness_score: 'Readiness score',
+}
+
+export function ConsolidationDashboard({ validatorIndices, byValidator }: ConsolidationDashboardProps) {
+  const [sortBy, setSortBy] = useState<ConsolidationSortKey>('savings')
+  const { recommendations, processed, total, isLoading, error } = useConsolidationEligibility(validatorIndices, byValidator)
+  const sorted = useMemo(() => sortConsolidationRecommendations(recommendations, sortBy), [recommendations, sortBy])
+
+  return (
+    <div className="space-y-4 px-6 pb-6">
+      <div className="flex flex-col justify-between gap-3 rounded-2xl border border-sky-400/20 bg-sky-400/10 p-4 sm:flex-row sm:items-center">
+        <div>
+          <h3 className="font-semibold text-sky-100">EIP-7251 consolidation eligibility</h3>
+          <p className="text-sm text-slate-300">
+            Scans up to 10,000 validators in 500-validator worker chunks and groups validators that share withdrawal credentials.
+          </p>
+        </div>
+        <label className="text-sm text-slate-300">
+          Sort by{' '}
+          <select
+            value={sortBy}
+            onChange={(event) => setSortBy(event.target.value as ConsolidationSortKey)}
+            className="rounded-lg border border-white/10 bg-slate-950 px-3 py-2 text-white"
+          >
+            {Object.entries(sortLabels).map(([value, label]) => (
+              <option key={value} value={value}>{label}</option>
+            ))}
+          </select>
+        </label>
+      </div>
+
+      {isLoading && <p className="text-sm text-slate-400">Scanning validators… {processed.toLocaleString()} / {total.toLocaleString()}</p>}
+      {error && <p className="text-sm text-red-300">{error}</p>}
+
+      <div className="overflow-x-auto rounded-2xl border border-white/10">
+        <table className="w-full min-w-[760px] text-left text-sm">
+          <thead className="bg-white/5 text-xs uppercase tracking-wide text-slate-400">
+            <tr>
+              <th className="px-4 py-3">Group ID</th>
+              <th className="px-4 py-3">Current count</th>
+              <th className="px-4 py-3">Merged count</th>
+              <th className="px-4 py-3">Potential gas savings/year</th>
+              <th className="px-4 py-3">Readiness score</th>
+              <th className="px-4 py-3">Total effective ETH</th>
+            </tr>
+          </thead>
+          <tbody className="divide-y divide-white/10">
+            {sorted.map((group) => (
+              <tr key={group.groupId} className="text-slate-200">
+                <td className="px-4 py-3 font-mono text-sky-300">{group.groupId}</td>
+                <td className="px-4 py-3 tabular-nums">{group.currentCount.toLocaleString()}</td>
+                <td className="px-4 py-3 tabular-nums">{group.mergedCount.toLocaleString()}</td>
+                <td className="px-4 py-3 tabular-nums text-emerald-300">{group.estimatedAnnualGasSavings.toLocaleString()} gas</td>
+                <td className="px-4 py-3 tabular-nums">{(group.readinessScore * 100).toFixed(1)}%</td>
+                <td className="px-4 py-3 tabular-nums">{group.totalEffectiveBalanceEth.toFixed(2)}</td>
+              </tr>
+            ))}
+            {!isLoading && sorted.length === 0 && (
+              <tr>
+                <td colSpan={6} className="px-4 py-8 text-center text-slate-400">
+                  No consolidation-eligible groups found for this validator set.
+                </td>
+              </tr>
+            )}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  )
+}
diff --git a/src/components/validators/ValidatorDashboard.tsx b/src/components/validators/ValidatorDashboard.tsx
index 3e1b355..3e5716f 100644
--- a/src/components/validators/ValidatorDashboard.tsx
+++ b/src/components/validators/ValidatorDashboard.tsx
@@ -6,6 +6,7 @@ import { ValidatorUnlockCard } from '@/src/components/validators/ValidatorUnlock
 import { ExitQueuePositionCard } from '@/src/components/validators/ExitQueuePositionCard'
 import { CommitteeTopologyMap } from '@/src/components/canvas/CommitteeTopologyMap'
 import { ShardLegend } from '@/src/components/validators/ShardLegend'
+import { ConsolidationDashboard } from '@/src/components/validators/ConsolidationDashboard'
 import { useValidatorBalances } from '@/src/hooks/useValidatorBalances'
 import { useCommitteeAssignments } from '@/src/hooks/useCommitteeAssignments'
 
@@ -26,6 +27,7 @@ export function ValidatorDashboard({
   const [open, setOpen] = useState(true)
   const [queueOpen, setQueueOpen] = useState(true)
   const [topoOpen, setTopoOpen] = useState(true)
+  const [consolidationOpen, setConsolidationOpen] = useState(true)
   const { byValidator } = useValidatorBalances(validatorIndices, { beaconNodeUrl })
   const committee = useCommitteeAssignments(validatorIndices, { beaconNodeUrl })
 
@@ -102,6 +104,29 @@ export function ValidatorDashboard({
         )}
       </section>
 
+      <section className="overflow-hidden rounded-3xl border border-white/10 bg-slate-900/80 text-white">
+        <button
+          type="button"
+          onClick={() => setConsolidationOpen((o) => !o)}
+          className="flex w-full items-center justify-between gap-4 p-6 text-left"
+          aria-expanded={consolidationOpen}
+        >
+          <div>
+            <h2 className="text-xl font-semibold">Consolidation</h2>
+            <p className="text-sm text-slate-400">
+              EIP-7251 merge recommendations · {validatorIndices.length} validators
+            </p>
+          </div>
+          <span className="flex h-8 w-8 items-center justify-center rounded-full border border-white/10 text-lg text-slate-300">
+            {consolidationOpen ? '−' : '+'}
+          </span>
+        </button>
+
+        {consolidationOpen && (
+          <ConsolidationDashboard validatorIndices={validatorIndices} byValidator={byValidator} />
+        )}
+      </section>
+
       <section className="overflow-hidden rounded-3xl border border-white/10 bg-slate-900/80 text-white">
         <button
           type="button"
diff --git a/src/hooks/useConsolidationEligibility.ts b/src/hooks/useConsolidationEligibility.ts
new file mode 100644
index 0000000..da98fd9
--- /dev/null
+++ b/src/hooks/useConsolidationEligibility.ts
@@ -0,0 +1,76 @@
+'use client'
+
+import { useEffect, useMemo, useState } from 'react'
+import type { ValidatorReconciliation } from '@/src/hooks/useValidatorBalances'
+import type { ConsolidationRecommendation, ConsolidationValidator } from '@/src/utils/consolidationEligibility'
+import type { ConsolidationScannerResponse } from '@/src/workers/consolidationScannerWorker'
+import { gweiToEth } from '@/src/utils/ethMath'
+
+interface UseConsolidationEligibilityOptions {
+  avgGasPerValidatorPerEpoch?: number
+}
+
+function fallbackWithdrawalCredentials(validatorIndex: number): string {
+  return `0xdemo${String(Math.floor(validatorIndex / 64)).padStart(60, '0')}`
+}
+
+export function useConsolidationEligibility(
+  validatorIndices: number[],
+  byValidator: Record<number, ValidatorReconciliation>,
+  options: UseConsolidationEligibilityOptions = {},
+) {
+  const [recommendations, setRecommendations] = useState<ConsolidationRecommendation[]>([])
+  const [processed, setProcessed] = useState(0)
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const scanKey = validatorIndices.join(',')
+
+  const validators = useMemo<ConsolidationValidator[]>(() => validatorIndices.map((validatorIndex) => {
+    const latest = byValidator[validatorIndex]?.summary.latest
+    return {
+      validatorIndex,
+      effectiveBalanceEth: latest ? gweiToEth(latest.effectiveBalanceGwei) : 32,
+      activationEpoch: Math.max(0, (latest?.epoch ?? 0) - (byValidator[validatorIndex]?.summary.recordCount ?? 0)),
+      withdrawalCredentials: fallbackWithdrawalCredentials(validatorIndex),
+    }
+  }), [validatorIndices, byValidator])
+
+  const [trackedScanKey, setTrackedScanKey] = useState<string | undefined>(undefined)
+  if (trackedScanKey !== scanKey) {
+    setTrackedScanKey(scanKey)
+    setIsLoading(validators.length > 0)
+    setError(null)
+    setProcessed(0)
+    setRecommendations([])
+  }
+
+  useEffect(() => {
+    if (validators.length === 0) return
+    const worker = new Worker(new URL('../workers/consolidationScannerWorker.ts', import.meta.url))
+
+    worker.onmessage = (event: MessageEvent<ConsolidationScannerResponse>) => {
+      const message = event.data
+      setProcessed(message.processed)
+      if (message.type === 'complete') {
+        setRecommendations(message.recommendations ?? [])
+        setIsLoading(false)
+        worker.terminate()
+      } else if (message.type === 'error') {
+        setError(message.error ?? 'Failed to scan validators')
+        setIsLoading(false)
+        worker.terminate()
+      }
+    }
+
+    worker.onerror = () => {
+      setError('Consolidation scanner worker failed')
+      setIsLoading(false)
+      worker.terminate()
+    }
+
+    worker.postMessage({ validators, avgGasPerValidatorPerEpoch: options.avgGasPerValidatorPerEpoch })
+    return () => worker.terminate()
+  }, [validators, options.avgGasPerValidatorPerEpoch])
+
+  return { recommendations, processed, total: validators.length, isLoading, error }
+}
diff --git a/src/utils/consolidationEligibility.ts b/src/utils/consolidationEligibility.ts
new file mode 100644
index 0000000..8422b9a
--- /dev/null
+++ b/src/utils/consolidationEligibility.ts
@@ -0,0 +1,88 @@
+import { CONSOLIDATED_VALIDATOR_EFFECTIVE_BALANCE_CAP_ETH, STANDARD_VALIDATOR_EFFECTIVE_BALANCE_ETH, clamp } from '@/src/utils/ethMath'
+import { DEFAULT_AVG_GAS_PER_VALIDATOR_PER_EPOCH, estimateAnnualGasSavings } from '@/src/utils/gasEstimator'
+
+export interface ConsolidationValidator {
+  validatorIndex: number
+  effectiveBalanceEth: number
+  activationEpoch: number
+  withdrawalCredentials: string
+}
+
+export interface ConsolidationRecommendation {
+  groupId: string
+  withdrawalCredentials: string
+  validatorIndices: number[]
+  currentCount: number
+  mergedCount: number
+  totalEffectiveBalanceEth: number
+  estimatedAnnualGasSavings: number
+  readinessScore: number
+  matchingWithdrawalCredsRatio: number
+}
+
+export type ConsolidationSortKey = 'savings' | 'validator_count' | 'readiness_score'
+
+function readinessScore(validators: ConsolidationValidator[], groupSize: number): number {
+  const matchingWithdrawalCredsRatio = validators.length === 0 ? 0 : groupSize / validators.length
+  const balanceProximityTo32 = validators.length === 0
+    ? 0
+    : validators.reduce((sum, v) => sum + clamp(1 - Math.abs(v.effectiveBalanceEth - STANDARD_VALIDATOR_EFFECTIVE_BALANCE_ETH) / STANDARD_VALIDATOR_EFFECTIVE_BALANCE_ETH), 0) / validators.length
+  const latestActivation = Math.max(...validators.map((v) => v.activationEpoch), 0)
+  const activationEpochProximity = validators.length === 0 || latestActivation === 0
+    ? 1
+    : validators.reduce((sum, v) => sum + clamp(v.activationEpoch / latestActivation), 0) / validators.length
+
+  return Number((0.5 * matchingWithdrawalCredsRatio + 0.3 * balanceProximityTo32 + 0.2 * activationEpochProximity).toFixed(4))
+}
+
+export function findConsolidationRecommendations(
+  validators: ConsolidationValidator[],
+  avgGasPerValidatorPerEpoch = DEFAULT_AVG_GAS_PER_VALIDATOR_PER_EPOCH,
+): ConsolidationRecommendation[] {
+  const byCreds = new Map<string, ConsolidationValidator[]>()
+  for (const validator of validators) {
+    const list = byCreds.get(validator.withdrawalCredentials) ?? []
+    list.push(validator)
+    byCreds.set(validator.withdrawalCredentials, list)
+  }
+
+  const recommendations: ConsolidationRecommendation[] = []
+  for (const [withdrawalCredentials, group] of byCreds) {
+    if (group.length < 2) continue
+    const sorted = [...group].sort((a, b) => b.effectiveBalanceEth - a.effectiveBalanceEth)
+    const bins: number[] = []
+    for (const validator of sorted) {
+      const fitIndex = bins.findIndex((balance) => balance + validator.effectiveBalanceEth <= CONSOLIDATED_VALIDATOR_EFFECTIVE_BALANCE_CAP_ETH)
+      if (fitIndex === -1) bins.push(validator.effectiveBalanceEth)
+      else bins[fitIndex] += validator.effectiveBalanceEth
+    }
+
+    const mergedCount = bins.length
+    if (mergedCount >= group.length) continue
+    const totalEffectiveBalanceEth = group.reduce((sum, v) => sum + v.effectiveBalanceEth, 0)
+    recommendations.push({
+      groupId: `wc-${withdrawalCredentials.slice(-8)}`,
+      withdrawalCredentials,
+      validatorIndices: group.map((v) => v.validatorIndex),
+      currentCount: group.length,
+      mergedCount,
+      totalEffectiveBalanceEth,
+      estimatedAnnualGasSavings: estimateAnnualGasSavings({ currentValidatorCount: group.length, mergedValidatorCount: mergedCount, avgGasPerValidatorPerEpoch }),
+      readinessScore: readinessScore(group, group.length),
+      matchingWithdrawalCredsRatio: 1,
+    })
+  }
+
+  return sortConsolidationRecommendations(recommendations, 'savings')
+}
+
+export function sortConsolidationRecommendations(
+  recommendations: ConsolidationRecommendation[],
+  sortBy: ConsolidationSortKey,
+): ConsolidationRecommendation[] {
+  return [...recommendations].sort((a, b) => {
+    if (sortBy === 'validator_count') return b.currentCount - a.currentCount
+    if (sortBy === 'readiness_score') return b.readinessScore - a.readinessScore
+    return b.estimatedAnnualGasSavings - a.estimatedAnnualGasSavings
+  })
+}
diff --git a/src/utils/ethMath.ts b/src/utils/ethMath.ts
new file mode 100644
index 0000000..7a75831
--- /dev/null
+++ b/src/utils/ethMath.ts
@@ -0,0 +1,15 @@
+export const GWEI_PER_ETH = BigInt(1_000_000_000)
+export const STANDARD_VALIDATOR_EFFECTIVE_BALANCE_ETH = 32
+export const CONSOLIDATED_VALIDATOR_EFFECTIVE_BALANCE_CAP_ETH = 2048
+
+export function gweiToEth(gwei: bigint): number {
+  return Number(gwei) / Number(GWEI_PER_ETH)
+}
+
+export function ethToGwei(eth: number): bigint {
+  return BigInt(Math.round(eth * Number(GWEI_PER_ETH)))
+}
+
+export function clamp(value: number, min = 0, max = 1): number {
+  return Math.min(max, Math.max(min, value))
+}
diff --git a/src/utils/gasEstimator.ts b/src/utils/gasEstimator.ts
new file mode 100644
index 0000000..6788b8f
--- /dev/null
+++ b/src/utils/gasEstimator.ts
@@ -0,0 +1,28 @@
+export interface GasSavingsInput {
+  currentValidatorCount: number
+  mergedValidatorCount: number
+  avgGasPerValidatorPerEpoch: number
+  epochsPerDay?: number
+}
+
+export const DEFAULT_AVG_GAS_PER_VALIDATOR_PER_EPOCH = 21_000
+export const DEFAULT_EPOCHS_PER_DAY = 225
+export const DAYS_PER_YEAR = 365.25
+
+export function estimateAnnualGasSavings({
+  currentValidatorCount,
+  mergedValidatorCount,
+  avgGasPerValidatorPerEpoch,
+  epochsPerDay = DEFAULT_EPOCHS_PER_DAY,
+}: GasSavingsInput): number {
+  const removedValidators = Math.max(0, currentValidatorCount - mergedValidatorCount)
+  return Math.round(removedValidators * avgGasPerValidatorPerEpoch * epochsPerDay * DAYS_PER_YEAR)
+}
+
+export function estimatePerValidatorEpochGas({
+  attestationGas = 14_000,
+  proposalGas = 5_000,
+  withdrawalGas = 2_000,
+}: Partial<Record<'attestationGas' | 'proposalGas' | 'withdrawalGas', number>> = {}): number {
+  return attestationGas + proposalGas + withdrawalGas
+}
diff --git a/src/workers/consolidationScannerWorker.ts b/src/workers/consolidationScannerWorker.ts
new file mode 100644
index 0000000..487ddf1
--- /dev/null
+++ b/src/workers/consolidationScannerWorker.ts
@@ -0,0 +1,59 @@
+import { findConsolidationRecommendations, type ConsolidationRecommendation, type ConsolidationValidator } from '@/src/utils/consolidationEligibility'
+
+export interface ConsolidationScannerRequest {
+  validators: ConsolidationValidator[]
+  chunkSize?: number
+  avgGasPerValidatorPerEpoch?: number
+}
+
+export interface ConsolidationScannerResponse {
+  type: 'progress' | 'complete' | 'error'
+  processed: number
+  total: number
+  recommendations?: ConsolidationRecommendation[]
+  error?: string
+}
+
+const DEFAULT_CHUNK_SIZE = 500
+
+function postMessageSafe(message: ConsolidationScannerResponse) {
+  self.postMessage(message)
+}
+
+self.onmessage = (event: MessageEvent<ConsolidationScannerRequest>) => {
+  const { validators, chunkSize = DEFAULT_CHUNK_SIZE, avgGasPerValidatorPerEpoch } = event.data
+  const scanned: ConsolidationValidator[] = []
+  let offset = 0
+
+  const processChunk = () => {
+    try {
+      const chunk = validators.slice(offset, offset + chunkSize)
+      scanned.push(...chunk)
+      offset += chunk.length
+      postMessageSafe({ type: 'progress', processed: scanned.length, total: validators.length })
+
+      if (offset < validators.length) {
+        setTimeout(processChunk, 0)
+        return
+      }
+
+      postMessageSafe({
+        type: 'complete',
+        processed: scanned.length,
+        total: validators.length,
+        recommendations: findConsolidationRecommendations(scanned, avgGasPerValidatorPerEpoch),
+      })
+    } catch (err) {
+      postMessageSafe({
+        type: 'error',
+        processed: scanned.length,
+        total: validators.length,
+        error: err instanceof Error ? err.message : 'Failed to scan validators',
+      })
+    }
+  }
+
+  processChunk()
+}
+
+export {}