aether-hub 1.1.8 → 1.2.0

package/commands/validators.js

@@ -1,326 +1,665 @@
-/**
- * aether-cli validators - Aether Validator Registry
- *
- * List and explore validators available for staking.
- *   aether validators list         — Show all active validators
- *   aether validators list --json  — JSON output for scripting
- *   aether validators list --tier <full|lite|observer> — Filter by tier
- *
- * @see docs/MINING_VALIDATOR_TOOLS.md for spec
- */
-
-const http = require('http');
-const https = require('https');
-
-// ANSI colours
-const C = {
-  reset: '\x1b[0m',
-  bright: '\x1b[1m',
-  dim: '\x1b[2m',
-  red: '\x1b[31m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  blue: '\x1b[34m',
-  cyan: '\x1b[36m',
-  magenta: '\x1b[35m',
-};
-
-const DEFAULT_RPC = process.env.AETHER_RPC || 'http://127.0.0.1:8899';
-
-// ---------------------------------------------------------------------------
-// HTTP helpers (mirrors network.js patterns)
-// ---------------------------------------------------------------------------
-
-function httpRequest(rpcUrl, path) {
-  return new Promise((resolve, reject) => {
-    const url = new URL(path, rpcUrl);
-    const isHttps = url.protocol === 'https:';
-    const lib = isHttps ? https : http;
-
-    const req = lib.request({
-      hostname: url.hostname,
-      port: url.port || (isHttps ? 443 : 80),
-      path: url.pathname + url.search,
-      method: 'GET',
-      timeout: 8000,
-      headers: { 'Content-Type': 'application/json' },
-    }, (res) => {
-      let data = '';
-      res.on('data', (chunk) => (data += chunk));
-      res.on('end', () => {
-        try { resolve(JSON.parse(data)); }
-        catch { resolve({ raw: data }); }
-      });
-    });
-
-    req.on('error', reject);
-    req.on('timeout', () => { req.destroy(); reject(new Error('Request timeout')); });
-    req.end();
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Argument parsing
-// ---------------------------------------------------------------------------
-
-function parseArgs() {
-  const args = process.argv.slice(3); // skip 'validators' and subcommand
-  const opts = {
-    rpc: DEFAULT_RPC,
-    tier: null,
-    asJson: false,
-    sort: 'stake', // 'stake' | 'name' | 'uptime'
-    limit: 50,
-  };
-
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--rpc' || args[i] === '-r') {
-      opts.rpc = args[++i];
-    } else if (args[i] === '--tier' || args[i] === '-t') {
-      opts.tier = args[++i]?.toLowerCase();
-    } else if (args[i] === '--json' || args[i] === '-j') {
-      opts.asJson = true;
-    } else if (args[i] === '--sort' || args[i] === '-s') {
-      opts.sort = args[++i]?.toLowerCase();
-    } else if (args[i] === '--limit' || args[i] === '-l') {
-      opts.limit = parseInt(args[++i], 10) || 50;
-    } else if (args[i] === '--help' || args[i] === '-h') {
-      showHelp();
-      process.exit(0);
-    }
-  }
-
-  return opts;
-}
-
-function showHelp() {
-  console.log(`
-${C.bright}${C.cyan}aether-cli validators${C.reset} - Aether Validator Registry
-
-${C.bright}Usage:${C.reset}
-  aether validators list [options]
-
-${C.bright}Options:${C.reset}
-  -r, --rpc <url>      RPC endpoint (default: ${DEFAULT_RPC} or $AETHER_RPC)
-  -t, --tier <tier>    Filter by tier: full, lite, observer
-  -s, --sort <field>   Sort by: stake (default), name, uptime
-  -l, --limit <n>      Max validators to show (default: 50)
-  -j, --json           Output raw JSON
-  -h, --help           Show this help
-
-${C.bright}Examples:${C.reset}
-  aether validators list
-  aether validators list --tier full
-  aether validators list --sort stake --limit 20
-  aether validators list --json
-`.trim());
-}
-
-// ---------------------------------------------------------------------------
-// Data fetching
-// ---------------------------------------------------------------------------
-
-/** Fetch validators list from RPC */
-async function fetchValidators(rpc) {
-  try {
-    const res = await httpRequest(rpc, '/v1/validators');
-    if (Array.isArray(res)) return res;
-    if (res.validators && Array.isArray(res.validators)) return res.validators;
-    return [];
-  } catch (err) {
-    return [];
-  }
-}
-
-/** Fetch epoch info for context */
-async function fetchEpoch(rpc) {
-  try {
-    const res = await httpRequest(rpc, '/v1/epoch');
-    return res;
-  } catch {
-    return null;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Formatting helpers
-// ---------------------------------------------------------------------------
-
-function formatAether(lamports) {
-  if (!lamports && lamports !== 0) return '?';
-  const aeth = lamports / 1e9;
-  if (aeth === 0) return '0';
-  return aeth.toFixed(2).replace(/\.?0+$/, '');
-}
-
-function formatPct(n) {
-  if (n === undefined || n === null) return '?';
-  return n.toFixed(1) + '%';
-}
-
-function tierBadge(tier) {
-  const map = {
-    full: `${C.cyan}FULL${C.reset}`,
-    lite: `${C.yellow}LITE${C.reset}`,
-    observer: `${C.green}OBS${C.reset}`,
-  };
-  return map[tier?.toLowerCase()] || `${C.dim}?${C.reset}`;
-}
-
-function scoreColor(score) {
-  if (score === undefined || score === null) return C.dim;
-  if (score >= 90) return C.green;
-  if (score >= 70) return C.yellow;
-  return C.red;
-}
-
-function shortenAddr(addr, len = 16) {
-  if (!addr) return '?';
-  if (addr.length <= len) return addr;
-  return addr.slice(0, 8) + '…' + addr.slice(-6);
-}
-
-// ---------------------------------------------------------------------------
-// Renderers
-// ---------------------------------------------------------------------------
-
-function renderList(validators, epochData, opts, rpc) {
-  const filtered = opts.tier
-    ? validators.filter(v => (v.tier || v.node_type || '').toLowerCase() === opts.tier)
-    : validators;
-
-  // Sort
-  if (opts.sort === 'name') {
-    filtered.sort((a, b) => (a.name || a.address || '').localeCompare(b.name || b.address || ''));
-  } else if (opts.sort === 'uptime') {
-    filtered.sort((a, b) => (b.uptime || b.score || 0) - (a.uptime || a.score || 0));
-  } else {
-    // Default: by stake (descending)
-    filtered.sort((a, b) => (b.stake || b.stake_amount || 0) - (a.stake || a.stake_amount || 0));
-  }
-
-  const shown = filtered.slice(0, opts.limit);
-  const totalStake = validators.reduce((sum, v) => sum + (v.stake || v.stake_amount || 0), 0);
-  const networkScore = validators.reduce((sum, v) => sum + (v.score || v.uptime || 0) * (v.stake || 1), 0) / (totalStake || 1);
-
-  console.log();
-  console.log(`${C.bright}${C.cyan}╔═══════════════════════════════════════════════════════════════════════╗${C.reset}`);
-  console.log(`${C.bright}${C.cyan}║${C.reset}              ${C.bright}AETHER VALIDATOR REGISTRY${C.reset}${C.cyan}                           ║${C.reset}`);
-  console.log(`${C.bright}${C.cyan}╚═══════════════════════════════════════════════════════════════════════╝${C.reset}`);
-  console.log(`  ${C.dim}RPC:${C.reset} ${rpc}`);
-  console.log(`  ${C.dim}Total validators:${C.reset} ${C.bright}${validators.length}${C.reset}`);
-  if (opts.tier) console.log(`  ${C.dim}Filtered by tier:${C.reset} ${C.bright}${opts.tier}${C.reset}`);
-  console.log();
-
-  // Summary stats
-  console.log(`  ${C.bright}┌──────────────────────────────────────────────────────────────────────────┐${C.reset}`);
-  console.log(`  ${C.bright}│${C.reset}  ${C.cyan}Total Stake${C.reset}         ${C.bright}│${C.reset}  ${C.green}${formatAether(totalStake).padEnd(20)} AETH${C.reset}`.padEnd(80) + `${C.bright}│${C.reset}`);
-  console.log(`  ${C.bright}│${C.reset}  ${C.cyan}Network Uptime${C.reset}     ${C.bright}│${C.reset}  ${scoreColor(networkScore)}${formatPct(networkScore).padEnd(20)}${C.reset}`.padEnd(80) + `${C.bright}│${C.reset}`);
-  if (epochData && epochData.epoch !== undefined) {
-    console.log(`  ${C.bright}│${C.reset}  ${C.cyan}Current Epoch${C.reset}      ${C.bright}│${C.reset}  ${C.green}${epochData.epoch}${C.reset}`.padEnd(80) + `${C.bright}│${C.reset}`);
-  }
-  console.log(`  ${C.bright}└──────────────────────────────────────────────────────────────────────────┘${C.reset}`);
-  console.log();
-
-  if (shown.length === 0) {
-    console.log(`  ${C.yellow}⚠ No validators found${C.reset}${opts.tier ? ` for tier "${opts.tier}"` : ''}.`);
-    console.log(`  ${C.dim}Try without --tier filter or check RPC connectivity.${C.reset}`);
-    console.log();
-    return;
-  }
-
-  // Table header
-  console.log(`  ${C.bright}┌────┬────────────────────────┬────────┬─────────┬────────┬─────────────┐${C.reset}`);
-  console.log(`  ${C.bright}│${C.reset} ${C.cyan}#${C.reset}  ${C.cyan}Validator${C.reset}                    ${C.cyan}Tier${C.reset}     ${C.cyan}Stake${C.reset}    ${C.cyan}Uptime${C.reset} ${C.cyan}Commission${C.reset} ${C.bright}│${C.reset}`);
-  console.log(`  ${C.bright}├────┼────────────────────────┼────────┼─────────┼────────┼─────────────┤${C.reset}`);
-
-  for (let i = 0; i < shown.length; i++) {
-    const v = shown[i];
-    const num = (i + 1).toString().padStart(3);
-    const addr = shortenAddr(v.address || v.pubkey || v.id);
-    const tierStr = tierBadge(v.tier || v.node_type);
-    const stake = formatAether(v.stake || v.stake_amount || 0);
-    const uptime = formatPct(v.uptime || v.score);
-    const commission = formatPct(v.commission || v.fee);
-    const row = `  ${C.bright}│${C.reset} ${C.dim}${num}${C.reset}  ${addr.padEnd(24)} ${tierStr.padEnd(8)} ${stake.padEnd(9)} ${scoreColor(v.uptime || v.score)}${uptime.padEnd(9)}${C.reset} ${C.dim}${commission}${C.reset} ${C.bright}│${C.reset}`;
-    console.log(row);
-  }
-
-  console.log(`  ${C.bright}└────┴────────────────────────┴────────┴─────────┴────────┴─────────────┘${C.reset}`);
-  console.log();
-
-  if (filtered.length > opts.limit) {
-    console.log(`  ${C.dim}Showing ${opts.limit} of ${filtered.length} validators. Use --limit to see more.${C.reset}`);
-  }
-
-  console.log();
-  console.log(`  ${C.dim}Stake to a validator:${C.reset}`);
-  console.log(`    ${C.cyan}aether stake --validator <address> --amount <aeth>${C.reset}`);
-  console.log(`    ${C.cyan}aether stake --validator <address> --amount <aeth> --dry-run${C.reset}  ${C.dim}(preview)${C.reset}`);
-  console.log();
-}
-
-function renderJson(validators, epochData, opts, rpc) {
-  const out = {
-    rpc,
-    fetchedAt: new Date().toISOString(),
-    total: validators.length,
-    epoch: epochData?.epoch ?? null,
-    validators: validators.map(v => ({
-      address: v.address || v.pubkey || v.id,
-      name: v.name || null,
-      tier: v.tier || v.node_type || null,
-      stake: v.stake || v.stake_amount || 0,
-      stakeAETH: formatAether(v.stake || v.stake_amount || 0),
-      uptime: v.uptime ?? v.score ?? null,
-      uptimePct: formatPct(v.uptime ?? v.score),
-      commission: v.commission ?? v.fee ?? null,
-      commissionPct: formatPct(v.commission ?? v.fee),
-      lastSeen: v.last_seen || v.lastActive || null,
-      version: v.version || v.clientVersion || null,
-    })),
-  };
-  console.log(JSON.stringify(out, null, 2));
-}
-
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
-
-async function validatorsListCommand() {
-  const opts = parseArgs();
-  const rpc = opts.rpc;
-
-  if (!opts.asJson) {
-    console.log(`\n${C.cyan}Fetching validators...${C.reset} ${C.dim}(${rpc})${C.reset}`);
-  }
-
-  const [validators, epochData] = await Promise.all([
-    fetchValidators(rpc),
-    fetchEpoch(rpc),
-  ]);
-
-  if (validators.length === 0 && !opts.asJson) {
-    console.log(`\n  ${C.yellow}⚠ No validator data returned from RPC.${C.reset}`);
-    console.log(`  ${C.dim}  Is your validator running and fully synced?${C.reset}`);
-    console.log(`  ${C.dim}  Check: aether-cli network${C.reset}`);
-    console.log(`  ${C.dim}  Set custom RPC: AETHER_RPC=http://your-rpc-url${C.reset}\n`);
-    return;
-  }
-
-  if (opts.asJson) {
-    renderJson(validators, epochData, opts, rpc);
-  } else {
-    renderList(validators, epochData, opts, rpc);
-  }
-}
-
-module.exports = { validatorsListCommand };
-
-if (require.main === module) {
-  validatorsListCommand().catch((err) => {
-    console.error(`\n${C.red}✗ Validators command failed:${C.reset} ${err.message}`);
-    console.error(`  ${C.dim}Check that your validator is running and RPC is accessible.${C.reset}\n`);
-    process.exit(1);
-  });
-}
+#!/usr/bin/env node
+/**
+ * aether-cli validators
+ *
+ * List, filter, and inspect validators on the Aether network.
+ * Shows identity, tier, stake, APY, uptime, and performance metrics.
+ *
+ * Usage:
+ *   aether validators list              List all active validators
+ *   aether validators list --tier full   Filter by tier (full|lite|observer)
+ *   aether validators list --json        JSON output for scripting
+ *   aether validators list --rpc <url>   Query a specific RPC endpoint
+ *   aether validators list --sort stake  Sort by stake (default: score)
+ *
+ * Requires AETHER_RPC env var (default: http://127.0.0.1:8899)
+ */
+
+const http = require('http');
+const https = require('https');
+
+// ANSI colours
+const C = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  magenta: '\x1b[35m',
+};
+
+const DEFAULT_RPC = process.env.AETHER_RPC || 'http://127.0.0.1:8899';
+
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+
+function httpRequest(rpcUrl, path) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(path, rpcUrl);
+    const lib = url.protocol === 'https:' ? https : http;
+    const req = lib.request({
+      hostname: url.hostname,
+      port: url.port || (url.protocol === 'https:' ? 443 : 80),
+      path: url.pathname + url.search,
+      method: 'GET',
+      timeout: 8000,
+      headers: { 'Content-Type': 'application/json' },
+    }, (res) => {
+      let data = '';
+      res.on('data', (chunk) => data += chunk);
+      res.on('end', () => { try { resolve(JSON.parse(data)); } catch { resolve({ raw: data }); } });
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error('Request timeout')); });
+    req.end();
+  });
+}
+
+function httpPost(rpcUrl, path, body) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(path, rpcUrl);
+    const lib = url.protocol === 'https:' ? https : http;
+    const bodyStr = JSON.stringify(body);
+    const req = lib.request({
+      hostname: url.hostname,
+      port: url.port || (url.protocol === 'https:' ? 443 : 80),
+      path: url.pathname + url.search,
+      method: 'POST',
+      timeout: 8000,
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(bodyStr) },
+    }, (res) => {
+      let data = '';
+      res.on('data', (chunk) => data += chunk);
+      res.on('end', () => { try { resolve(JSON.parse(data)); } catch { resolve(data); } });
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error('Request timeout')); });
+    req.write(bodyStr);
+    req.end();
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+function parseArgs() {
+  const args = process.argv.slice(3); // [node, index.js, validators, list, ...]
+  const opts = {
+    rpc: DEFAULT_RPC,
+    subcmd: 'list',
+    tier: null,
+    asJson: false,
+    sortBy: 'score',
+    limit: 100,
+    rank: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--tier' || arg === '-t') {
+      const tier = (args[++i] || '').toLowerCase();
+      if (['full', 'lite', 'observer'].includes(tier)) {
+        opts.tier = tier;
+      } else {
+        console.log(`  ${C.yellow}⚠ Invalid tier "${tier}". Valid: full, lite, observer${C.reset}`);
+      }
+    } else if (arg === '--json' || arg === '-j') {
+      opts.asJson = true;
+    } else if (arg === '--rpc' || arg === '-r') {
+      opts.rpc = args[++i];
+    } else if (arg === '--sort' || arg === '-s') {
+      const sortVal = (args[++i] || '').toLowerCase();
+      if (['stake', 'score', 'apy', 'uptime', 'name'].includes(sortVal)) {
+        opts.sortBy = sortVal;
+      } else {
+        console.log(`  ${C.yellow}⚠ Invalid sort "${sortVal}". Valid: stake, score, apy, uptime, name${C.reset}`);
+      }
+    } else if (arg === '--limit' || arg === '-l') {
+      const limit = parseInt(args[++i], 10);
+      if (!isNaN(limit) && limit > 0 && limit <= 500) {
+        opts.limit = limit;
+      }
+    } else if (arg === '--help' || arg === '-h') {
+      showHelp();
+      process.exit(0);
+    } else if (arg === '--rank') {
+      opts.rank = true;
+      opts.subcmd = 'rank';
+    }
+  }
+
+  return opts;
+}
+
+function showHelp() {
+  console.log(`
+${C.bright}${C.cyan}aether-cli validators${C.reset} - List and inspect Aether validators
+
+${C.bright}Usage:${C.reset}
+  aether validators list [options]
+  aether validators rank [options]        Ranked leaderboard (sorted by stake)
+
+${C.bright}Options (list):${C.reset}
+  -t, --tier <type>   Filter by tier: full, lite, observer
+  -s, --sort <field>  Sort by: stake, score, apy, uptime, name (default: score)
+  -l, --limit <n>     Max validators to show (default: 100, max: 500)
+  -r, --rpc <url>     RPC endpoint (default: ${DEFAULT_RPC} or $AETHER_RPC)
+  -j, --json          Output raw JSON (for scripting)
+  -h, --help          Show this help message
+
+${C.bright}Options (rank):${C.reset}
+  -t, --tier <type>   Filter by tier: full, lite, observer
+  -l, --limit <n>     Max validators to show (default: 50, max: 200)
+  -r, --rpc <url>     RPC endpoint (default: ${DEFAULT_RPC} or $AETHER_RPC)
+  -j, --json          Output raw JSON (for scripting)
+  -h, --help          Show this help message
+
+${C.bright}Examples:${C.reset}
+  aether validators list                  # All validators, sorted by score
+  aether validators list --tier full       # Full validators only
+  aether validators list --sort stake      # Sort by total stake
+  aether validators list --sort apy        # Sort by estimated APY
+  aether validators list --json           # JSON for scripts
+  aether validators rank                  # Top validators by stake (leaderboard)
+  aether validators rank --tier full       # Full validators only
+  aether validators rank --limit 20       # Top 20 validators
+  aether validators list --rpc http://custom-rpc:8899
+`.trim());
+}
+
+// ---------------------------------------------------------------------------
+// Data fetchers
+// ---------------------------------------------------------------------------
+
+/** Fetch all validators from the network */
+async function fetchValidators(rpc) {
+  try {
+    // Try /v1/validators first (standard Aether RPC endpoint)
+    const res = await httpRequest(rpc, '/v1/validators');
+    if (res && !res.error) {
+      if (Array.isArray(res)) return res;
+      if (res.validators && Array.isArray(res.validators)) return res.validators;
+      if (res.accounts && Array.isArray(res.accounts)) return res.accounts;
+    }
+    // Fallback: POST to a validators query endpoint
+    const res2 = await httpPost(rpc, '/v1/validators', {});
+    if (res2 && !res2.error) {
+      if (Array.isArray(res2)) return res2;
+      if (res2.validators && Array.isArray(res2.validators)) return res2.validators;
+    }
+    return [];
+  } catch {
+    return [];
+  }
+}
+
+/** Fetch epoch info for APY calculations */
+async function fetchEpochInfo(rpc) {
+  try {
+    const res = await httpRequest(rpc, '/v1/epoch-info');
+    return res;
+  } catch {
+    return null;
+  }
+}
+
+/** Fetch network-wide stake totals for APY estimation */
+async function fetchSupply(rpc) {
+  try {
+    const res = await httpRequest(rpc, '/v1/supply');
+    return res;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Normalise validator record from various RPC response shapes
+// ---------------------------------------------------------------------------
+
+function normaliseValidator(v) {
+  // Handle different response shapes from different RPC implementations
+  const pubkey = v.pubkey || v.address || v.identity || v.id || null;
+  const name = v.name || v.moniker || v.label || v.identity_name || null;
+  const tier = (v.tier || v.node_type || v.type || 'full').toLowerCase();
+  const stake = BigInt(v.stake || v.delegatedStake || v.stake_lamports || v.lamports || 0);
+  const score = v.score !== undefined ? v.score : (v.uptime !== undefined ? Math.round(v.uptime * 100) : null);
+  const apy = v.apy !== undefined ? v.apy : (v.apy_bps !== undefined ? v.apy_bps / 100 : null);
+  const commission = v.commission !== undefined ? v.commission : (v.commission_bps !== undefined ? v.commission_bps / 100 : null);
+  const version = v.version || v.agent || v.app_version || null;
+  const ip = v.ip || v.remote || null;
+  const lastVote = v.last_vote || v.lastVote || null;
+  const epoch = v.epoch || null;
+  const voteAccount = v.vote_account || v.voteAccount || null;
+
+  return {
+    pubkey,
+    name,
+    tier,
+    stake: stake.toString(),
+    stakeFormatted: formatAether(stake),
+    stakeAeth: Number(stake) / 1e9,
+    score,
+    apy,
+    commission,
+    version,
+    ip,
+    lastVote,
+    epoch,
+    voteAccount,
+    // Raw for JSON export
+    _raw: v,
+  };
+}
+
+function formatAether(lamports) {
+  const aeth = Number(lamports) / 1e9;
+  if (aeth === 0) return '0 AETH';
+  return aeth.toFixed(2).replace(/\.?0+$/, '') + ' AETH';
+}
+
+function formatScore(score) {
+  if (score === null || score === undefined) return `${C.dim}—${C.reset}`;
+  if (score >= 80) return `${C.green}${score}${C.reset}`;
+  if (score >= 50) return `${C.yellow}${score}${C.reset}`;
+  return `${C.red}${score}${C.reset}`;
+}
+
+// ---------------------------------------------------------------------------
+// Render outputs
+// ---------------------------------------------------------------------------
+
+function tierColor(tier) {
+  if (tier === 'full') return `${C.cyan}FULL${C.reset}`;
+  if (tier === 'lite') return `${C.yellow}LITE${C.reset}`;
+  if (tier === 'observer') return `${C.green}OBS${C.reset}`;
+  return `${C.dim}${tier.toUpperCase()}${C.reset}`;
+}
+
+function tierBadge(tier) {
+  if (tier === 'full') return `${C.cyan}◆ FULL${C.reset}`;
+  if (tier === 'lite') return `${C.yellow}◇ LITE${C.reset}`;
+  if (tier === 'observer') return `${C.green}○ OBS${C.reset}`;
+  return `${C.dim}[${tier}]${C.reset}`;
+}
+
+function renderTable(validators, opts) {
+  const sortBy = opts.sortBy;
+  const tier = opts.tier;
+
+  // Sort validators
+  const sorted = [...validators].sort((a, b) => {
+    if (sortBy === 'stake') return b.stakeAeth - a.stakeAeth;
+    if (sortBy === 'score') return (b.score || 0) - (a.score || 0);
+    if (sortBy === 'apy') return (b.apy || 0) - (a.apy || 0);
+    if (sortBy === 'name') return (a.name || '').localeCompare(b.name || '');
+    return 0;
+  });
+
+  // Filter by tier
+  const filtered = tier
+    ? sorted.filter(v => v.tier === tier)
+    : sorted;
+
+  const shown = filtered.slice(0, opts.limit);
+  const total = filtered.length;
+
+  // Header
+  console.log();
+  console.log(`${C.bright}${C.cyan}╔═══════════════════════════════════════════════════════════════════════════════╗${C.reset}`);
+  console.log(`${C.bright}${C.cyan}║${C.reset}              ${C.bright}AETHER VALIDATORS${C.reset}  ${C.dim}(total: ${total})${C.reset}                      ${C.bright}║${C.reset}`);
+  console.log(`${C.bright}${C.cyan}╚═══════════════════════════════════════════════════════════════════════════════╝${C.reset}`);
+  if (tier) console.log(`  ${C.dim}Tier filter: ${tier.toUpperCase()}   Sort: ${sortBy}   RPC: ${opts.rpc}${C.reset}`);
+  else console.log(`  ${C.dim}Sort: ${sortBy}   RPC: ${opts.rpc}${C.reset}`);
+  console.log();
+
+  if (shown.length === 0) {
+    console.log(`  ${C.yellow}⚠ No validators found${C.reset}${tier ? ` for tier "${tier}"` : ''}.`);
+    console.log(`  ${C.dim}  Check your RPC endpoint: ${opts.rpc}${C.reset}\n`);
+    return;
+  }
+
+  // Table header
+  console.log(`  ${C.bright}┌──────────────────────────────────────────────────────────────────────────────────────┐${C.reset}`);
+  console.log(
+    `  ${C.bright}│${C.reset}` +
+    ` ${C.cyan}#${C.reset}`.padEnd(4) +
+    `${C.cyan}Validator${C.reset}`.padEnd(36) +
+    `${C.cyan}Tier${C.reset}`.padEnd(8) +
+    `${C.cyan}Stake${C.reset}`.padEnd(14) +
+    `${C.cyan}Score${C.reset}`.padEnd(8) +
+    `${C.cyan}APY${C.reset}`.padEnd(8) +
+    `${C.cyan}Version${C.reset}`.padEnd(10) +
+    `${C.bright}│${C.reset}`
+  );
+  console.log(`  ${C.bright}├${'─'.repeat(90)}${C.bright}│${C.reset}`);
+
+  for (let i = 0; i < shown.length; i++) {
+    const v = shown[i];
+    const num = (i + 1).toString().padStart(3);
+    const nameOrKey = v.name
+      ? v.name.substring(0, 20).padEnd(20)
+      : (v.pubkey ? v.pubkey.substring(0, 20).padEnd(20) : 'unknown'.padEnd(20));
+    const tierStr = tierBadge(v.tier);
+    const stakeStr = v.stakeFormatted.padEnd(12);
+    const scoreStr = v.score !== null && v.score !== undefined
+      ? `${v.score}%`.padEnd(6)
+      : '—'.padEnd(6);
+    const apyStr = v.apy !== null && v.apy !== undefined
+      ? `${v.apy.toFixed(1)}%`.padEnd(6)
+      : '—'.padEnd(6);
+    const versionStr = v.version ? v.version.substring(0, 10).padEnd(10) : '—'.padEnd(10);
+
+    const scoreColor = v.score === null || v.score === undefined ? C.dim
+      : v.score >= 80 ? C.green
+      : v.score >= 50 ? C.yellow
+      : C.red;
+
+    console.log(
+      `  ${C.bright}│${C.reset}` +
+      ` ${C.dim}${num}${C.reset} `.substring(0, 5) +
+      `${C.cyan}${nameOrKey}${C.reset} ` +
+      `${tierStr} `.substring(0, 9) +
+      `${C.green}${stakeStr}${C.reset} ` +
+      `${scoreColor}${scoreStr}${C.reset} ` +
+      `${C.green}${apyStr}${C.reset} ` +
+      `${C.dim}${versionStr}${C.reset} ` +
+      `${C.bright}│${C.reset}`
+    );
+  }
+
+  console.log(`  ${C.bright}└${'─'.repeat(90)}${C.bright}│${C.reset}`);
+  console.log();
+
+  // Summary row
+  const totalStake = shown.reduce((sum, v) => sum + v.stakeAeth, 0);
+  const avgScore = shown.reduce((sum, v) => sum + (v.score || 0), 0) / shown.filter(v => v.score !== null).length;
+  const fullCount = shown.filter(v => v.tier === 'full').length;
+  const liteCount = shown.filter(v => v.tier === 'lite').length;
+  const obsCount = shown.filter(v => v.tier === 'observer').length;
+
+  console.log(`  ${C.dim}Showing ${shown.length} of ${total} validators${total !== shown.length ? ` (limit ${opts.limit})` : ''}${C.reset}`);
+  console.log(`  ${C.dim}Total stake shown: ${C.reset}${C.green}${totalStake.toFixed(2)} AETH${C.reset}  ${C.dim}Avg score: ${C.reset}${avgScore ? `${avgScore.toFixed(1)}%` : '—'}${C.reset}`);
+  if (!tier) {
+    console.log(`  ${C.cyan}◆${C.reset} ${C.cyan}Full${C.reset}: ${fullCount}   ${C.yellow}◇${C.reset} ${C.yellow}Lite${C.reset}: ${liteCount}   ${C.green}○${C.reset} ${C.green}Observer${C.reset}: ${obsCount}`);
+  }
+  console.log();
+  console.log(`  ${C.dim}Tip: --tier full|lite|observer  |  --sort stake|score|apy|name  |  --json for data${C.reset}`);
+  console.log();
+}
+
+function renderJson(validators, opts) {
+  const tier = opts.tier;
+  const filtered = tier
+    ? validators.filter(v => v.tier === tier)
+    : validators;
+
+  const out = {
+    rpc: opts.rpc,
+    total: filtered.length,
+    sort: opts.sortBy,
+    tier_filter: tier,
+    fetched_at: new Date().toISOString(),
+    validators: filtered.map(v => ({
+      pubkey: v.pubkey,
+      name: v.name,
+      tier: v.tier,
+      stake: v.stake,
+      stake_aeth: v.stakeAeth,
+      stake_formatted: v.stakeFormatted,
+      score: v.score,
+      apy: v.apy,
+      commission: v.commission,
+      version: v.version,
+      ip: v.ip,
+      vote_account: v.voteAccount,
+      last_vote: v.lastVote,
+      epoch: v.epoch,
+    })),
+  };
+
+  console.log(JSON.stringify(out, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function validatorsList(opts) {
+  const rpc = opts.rpc;
+
+  if (!opts.asJson) {
+    console.log(`${C.dim}Fetching validators from ${rpc}...${C.reset}`);
+  }
+
+  const [rawValidators, epochInfo, supply] = await Promise.all([
+    fetchValidators(rpc),
+    fetchEpochInfo(rpc),
+    fetchSupply(rpc),
+  ]);
+
+  if (rawValidators.length === 0) {
+    if (opts.asJson) {
+      console.log(JSON.stringify({ rpc, validators: [], total: 0, error: 'No validator data returned from RPC' }, null, 2));
+    } else {
+      console.log(`\n  ${C.yellow}⚠ No validator data returned from RPC.${C.reset}`);
+      console.log(`  ${C.dim}  RPC: ${rpc}${C.reset}`);
+      console.log(`  ${C.dim}  Check that your validator is running and the RPC endpoint is accessible.${C.reset}`);
+      console.log(`  ${C.dim}  Set custom RPC: AETHER_RPC=http://your-rpc-url${C.reset}\n`);
+    }
+    return;
+  }
+
+  // Normalise all validators
+  let validators = rawValidators.map(normaliseValidator);
+
+  // Estimate APY if not provided by RPC (rough approximation)
+  if (supply && !supply.error) {
+    const totalStake = Number(supply.total_staked || supply.total || 0);
+    const rewardsPerEpoch = Number(epochInfo?.rewards_per_epoch || '2000000000');
+    if (totalStake > 0 && rewardsPerEpoch > 0) {
+      const apyEstimate = (rewardsPerEpoch / totalStake) * 73; // ~73 epochs/year
+      validators = validators.map(v => {
+        if (v.apy === null || v.apy === undefined) {
+          return { ...v, apy: apyEstimate };
+        }
+        return v;
+      });
+    }
+  }
+
+  if (opts.asJson) {
+    renderJson(validators, opts);
+  } else {
+    renderTable(validators, opts);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Validators Rank — leaderboard sorted by stake
+// ---------------------------------------------------------------------------
+
+function rankBadge(rank) {
+  if (rank === 1) return `${C.yellow}🥇 1${C.reset}`;
+  if (rank === 2) return `${C.dim}🥈 2${C.reset}`;
+  if (rank === 3) return `${C.yellow}🥉 3${C.reset}`;
+  return `${C.dim}${String(rank).padStart(3)}${C.reset}`;
+}
+
+function renderRankTable(validators, opts) {
+  const tier = opts.tier;
+
+  // Sort by stake descending, filter by tier
+  const sorted = [...validators]
+    .sort((a, b) => b.stakeAeth - a.stakeAeth);
+
+  const filtered = tier
+    ? sorted.filter(v => v.tier === tier)
+    : sorted;
+
+  const shown = filtered.slice(0, opts.limit);
+  const total = filtered.length;
+
+  // Total staked across all shown validators
+  const totalStaked = shown.reduce((sum, v) => sum + v.stakeAeth, 0);
+  const maxStake = shown.length > 0 ? shown[0].stakeAeth : 1;
+
+  console.log();
+  console.log(`${C.bright}${C.cyan}╔═══════════════════════════════════════════════════════════════════════════════════╗${C.reset}`);
+  console.log(`${C.bright}${C.cyan}║${C.reset}              ${C.bright}AETHER VALIDATOR LEADERBOARD${C.reset}  ${C.dim}(${total} validators)${C.reset}         ${C.bright}║${C.reset}`);
+  console.log(`${C.bright}${C.cyan}╚═══════════════════════════════════════════════════════════════════════════════════╝${C.reset}`);
+  if (tier) console.log(`  ${C.dim}Tier: ${tier.toUpperCase()}   RPC: ${opts.rpc}${C.reset}`);
+  else console.log(`  ${C.dim}Sorted by stake   RPC: ${opts.rpc}${C.reset}`);
+  console.log();
+  console.log(`  ${C.bright}┌────────────────────────────────────────────────────────────────────────────────────────────┐${C.reset}`);
+  console.log(
+    `  ${C.bright}│${C.reset}` +
+    ` ${C.cyan}Rank${C.reset}`.padEnd(6) +
+    `${C.cyan}Validator${C.reset}`.padEnd(34) +
+    `${C.cyan}Tier${C.reset}`.padEnd(8) +
+    `${C.cyan}Stake (AETH)${C.reset}`.padEnd(16) +
+    `${C.cyan}Score${C.reset}`.padEnd(8) +
+    `${C.cyan}APY${C.reset}`.padEnd(8) +
+    `${C.bright}│${C.reset}`
+  );
+  console.log(`  ${C.bright}├${'─'.repeat(94)}${C.bright}│${C.reset}`);
+
+  for (let i = 0; i < shown.length; i++) {
+    const v = shown[i];
+    const rank = i + 1;
+    const rankStr = rankBadge(rank);
+    const nameOrKey = v.name
+      ? v.name.substring(0, 20).padEnd(20)
+      : (v.pubkey ? v.pubkey.substring(0, 20).padEnd(20) : 'unknown'.padEnd(20));
+    const tierStr = tierBadge(v.tier);
+    const stakeFormatted = v.stakeFormatted.padEnd(14);
+    const scoreStr = v.score !== null && v.score !== undefined
+      ? `${v.score}%`.padEnd(6)
+      : '—'.padEnd(6);
+    const apyStr = v.apy !== null && v.apy !== undefined
+      ? `${v.apy.toFixed(1)}%`.padEnd(6)
+      : '—'.padEnd(6);
+
+    const scoreColor = v.score === null || v.score === undefined ? C.dim
+      : v.score >= 80 ? C.green
+      : v.score >= 50 ? C.yellow
+      : C.red;
+
+    // Mini bar for relative stake
+    const barLen = 12;
+    const fillLen = maxStake > 0 ? Math.round((v.stakeAeth / maxStake) * barLen) : 0;
+    const stakeBar = `${C.green}${'█'.repeat(fillLen)}${C.dim}${'░'.repeat(barLen - fillLen)}${C.reset}`;
+
+    console.log(
+      `  ${C.bright}│${C.reset}` +
+      ` ${rankStr} `.substring(0, 7) +
+      `${C.cyan}${nameOrKey}${C.reset} ` +
+      `${tierStr} `.substring(0, 9) +
+      `${stakeBar}${C.reset} ` +
+      `${C.green}${stakeFormatted}${C.reset} ` +
+      `${scoreColor}${scoreStr}${C.reset} ` +
+      `${C.green}${apyStr}${C.reset} ` +
+      `${C.bright}│${C.reset}`
+    );
+  }
+
+  console.log(`  ${C.bright}└${'─'.repeat(94)}${C.bright}│${C.reset}`);
+  console.log();
+
+  // Summary
+  const avgApy = shown.reduce((sum, v) => sum + (v.apy || 0), 0) / shown.filter(v => v.apy !== null).length;
+  console.log(`  ${C.dim}Total staked (shown): ${C.reset}${C.green}${totalStaked.toFixed(2)} AETH${C.reset}  ${C.dim}Avg APY: ${C.reset}${avgApy.toFixed(1)}%  ${C.dim}Top stake: ${C.reset}${maxStake.toFixed(2)} AETH${C.reset}`);
+  console.log(`  ${C.dim}Run with ${C.cyan}--json${C.reset}${C.dim} for raw data, ${C.cyan}--limit 20${C.reset}${C.dim} for top 20${C.reset}`);
+  console.log();
+}
+
+async function validatorsRank(opts) {
+  const rpc = opts.rpc;
+  const limit = Math.min(opts.limit || 50, 200);
+
+  if (!opts.asJson) {
+    console.log(`${C.dim}Fetching validator leaderboard from ${rpc}...${C.reset}`);
+  }
+
+  const [rawValidators, epochInfo, supply] = await Promise.all([
+    fetchValidators(rpc),
+    fetchEpochInfo(rpc),
+    fetchSupply(rpc),
+  ]);
+
+  if (rawValidators.length === 0) {
+    if (opts.asJson) {
+      console.log(JSON.stringify({ rpc, validators: [], total: 0, error: 'No validator data returned from RPC' }, null, 2));
+    } else {
+      console.log(`\n  ${C.yellow}⚠ No validator data returned from RPC.${C.reset}`);
+      console.log(`  ${C.dim}  RPC: ${rpc}${C.reset}`);
+      console.log(`  ${C.dim}  Check that your validator is running and the RPC endpoint is accessible.${C.reset}\n`);
+    }
+    return;
+  }
+
+  let validators = rawValidators.map(normaliseValidator);
+
+  // Estimate APY if not provided
+  if (supply && !supply.error) {
+    const totalStake = Number(supply.total_staked || supply.total || 0);
+    const rewardsPerEpoch = Number(epochInfo?.rewards_per_epoch || '2000000000');
+    if (totalStake > 0 && rewardsPerEpoch > 0) {
+      const apyEstimate = (rewardsPerEpoch / totalStake) * 73;
+      validators = validators.map(v => {
+        if (v.apy === null || v.apy === undefined) {
+          return { ...v, apy: apyEstimate };
+        }
+        return v;
+      });
+    }
+  }
+
+  opts.limit = limit;
+
+  if (opts.asJson) {
+    const ranked = [...validators]
+      .sort((a, b) => b.stakeAeth - a.stakeAeth)
+      .filter(v => !opts.tier || v.tier === opts.tier)
+      .slice(0, limit)
+      .map((v, i) => ({ rank: i + 1, ...v }));
+    console.log(JSON.stringify({ rpc, validators: ranked, total: ranked.length, fetched_at: new Date().toISOString() }, null, 2));
+  } else {
+    renderRankTable(validators, opts);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const opts = parseArgs();
+
+  if (opts.subcmd === 'list') {
+    await validatorsList(opts);
+  } else if (opts.subcmd === 'rank') {
+    await validatorsRank(opts);
+  } else {
+    console.log(`\n  ${C.red}Unknown subcommand:${C.reset} ${opts.subcmd}`);
+    console.log(`  ${C.dim}Usage: aether validators list [--tier full] [--sort stake] [--json]${C.reset}\n`);
+    process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error(`\n${C.red}✗ Validators command failed:${C.reset} ${err.message}`);
+  console.error(`  ${C.dim}Set custom RPC: AETHER_RPC=http://your-rpc-url${C.reset}\n`);
+  process.exit(1);
+});
+
+module.exports = { validatorsListCommand: main };
+
+if (require.main === module) {
+  main();
+}