aether-hub 1.2.0 → 1.2.3

package/commands/broadcast.js

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+/**
+ * aether-cli broadcast
+ *
+ * Broadcast a signed transaction to the Aether network.
+ * Accepts a base58-encoded transaction signature or a raw JSON payload.
+ * Useful for submitting offline-constructed transactions.
+ *
+ * Usage:
+ *   aether broadcast --tx <signature>           Broadcast by tx signature
+ *   aether broadcast --json <payload>          Broadcast raw JSON tx payload
+ *   aether broadcast --file <path>             Read tx from a JSON file
+ *   aether broadcast --rpc <url>                Use a specific RPC endpoint
+ *   aether broadcast --json-output            Output result as JSON
+ *
+ * Examples:
+ *   aether broadcast --tx 5abcdef...           # Submit pre-signed tx
+ *   aether broadcast --json '{"type":"Transfer",...}'
+ *   aether broadcast --file ./unsigned_tx.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const http = require('http');
+
+// ANSI colours
+const C = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+};
+
+const CLI_VERSION = '1.0.0';
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+function getDefaultRpc() {
+  return process.env.AETHER_RPC || 'http://127.0.0.1:8899';
+}
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const opts = {
+    rpc: getDefaultRpc(),
+    signature: null,
+    jsonPayload: null,
+    filePath: null,
+    asJson: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--tx' || args[i] === '-t') {
+      opts.signature = args[++i];
+    } else if (args[i] === '--json' || args[i] === '-j') {
+      opts.jsonPayload = args[++i];
+    } else if (args[i] === '--file' || args[i] === '-f') {
+      opts.filePath = args[++i];
+    } else if (args[i] === '--rpc' || args[i] === '-r') {
+      opts.rpc = args[++i];
+    } else if (args[i] === '--json-output') {
+      opts.asJson = true;
+    } else if (args[i] === '--help' || args[i] === '-h') {
+      showHelp();
+      process.exit(0);
+    }
+  }
+
+  return opts;
+}
+
+function showHelp() {
+  console.log(`
+${C.bright}${C.cyan}aether-cli broadcast${C.reset} - Broadcast a Signed Transaction
+
+${C.bright}Usage:${C.reset}
+  aether-cli broadcast --tx <signature>         Broadcast by base58 signature
+  aether-cli broadcast --json <payload>        Broadcast inline JSON payload
+  aether-cli broadcast --file <path>            Read tx from a JSON file
+  aether-cli broadcast --rpc <url>             Override default RPC
+  aether-cli broadcast --json-output          JSON output for scripting
+
+${C.bright}Examples:${C.reset}
+  aether-cli broadcast --tx 5abcdef123456...  # Submit by signature
+  aether-cli broadcast --json '{"type":"Transfer","data":{...}}'
+  aether-cli broadcast --file ./my_tx.json    # Read and broadcast from file
+`.trim());
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+
+function httpRequest(rpcUrl, pathStr, method = 'GET', body = null, timeoutMs = 15000) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(pathStr, rpcUrl);
+    const lib = url.protocol === 'https:' ? https : http;
+    const bodyStr = body ? JSON.stringify(body) : null;
+
+    const reqOptions = {
+      hostname: url.hostname,
+      port: url.port || (url.protocol === 'https:' ? 443 : 80),
+      path: url.pathname + url.search,
+      method,
+      timeout: timeoutMs,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(bodyStr ? { 'Content-Length': Buffer.byteLength(bodyStr) } : {}),
+      },
+    };
+
+    const req = lib.request(reqOptions, (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')); });
+    if (bodyStr) req.write(bodyStr);
+    req.end();
+  });
+}
+
+function httpPost(rpcUrl, pathStr, body, timeoutMs = 15000) {
+  return httpRequest(rpcUrl, pathStr, 'POST', body, timeoutMs);
+}
+
+// ---------------------------------------------------------------------------
+// Validate transaction payload
+// ---------------------------------------------------------------------------
+
+function validateTxPayload(tx) {
+  const errors = [];
+
+  if (!tx) {
+    errors.push('Transaction payload is null or empty');
+    return errors;
+  }
+
+  // Must have signer
+  if (!tx.signer && !tx.from && !tx.pubkey) {
+    errors.push('Missing signer field (signer | from | pubkey)');
+  }
+
+  // Must have tx_type or type
+  if (!tx.tx_type && !tx.type) {
+    errors.push('Missing tx_type or type field');
+  }
+
+  // Must have payload
+  if (!tx.payload && !tx.data) {
+    errors.push('Missing payload or data field');
+  }
+
+  return errors;
+}
+
+// ---------------------------------------------------------------------------
+// Broadcast logic
+// ---------------------------------------------------------------------------
+
+async function broadcast({ rpc, signature, jsonPayload, filePath, asJson }) {
+  // Build the tx object from inputs (priority: signature > file > inline JSON)
+  let tx = null;
+
+  if (signature) {
+    // Signature-only broadcast: POST /v1/tx with { signature }
+    tx = { signature };
+  } else if (filePath) {
+    // Read from file
+    const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+    if (!fs.existsSync(absPath)) {
+      throw new Error(`File not found: ${absPath}`);
+    }
+    try {
+      tx = JSON.parse(fs.readFileSync(absPath, 'utf8'));
+    } catch {
+      throw new Error(`Invalid JSON in file: ${absPath}`);
+    }
+  } else if (jsonPayload) {
+    try {
+      tx = JSON.parse(jsonPayload);
+    } catch {
+      throw new Error('Invalid JSON payload provided with --json');
+    }
+  } else {
+    throw new Error('No transaction provided. Use --tx, --json, or --file');
+  }
+
+  // Validate the transaction has required fields
+  if (!signature) {
+    const validationErrors = validateTxPayload(tx);
+    if (validationErrors.length > 0) {
+      throw new Error('Invalid transaction payload:\n  ' + validationErrors.join('\n  '));
+    }
+  }
+
+  if (!asJson) {
+    console.log(`\n${C.bright}${C.cyan}── Broadcast Transaction ─────────────────────────────────────${C.reset}`);
+    console.log(`  ${C.dim}RPC: ${rpc}${C.reset}`);
+    if (signature) {
+      console.log(`  ${C.dim}Signature:${C.reset} ${C.cyan}${signature}${C.reset}`);
+    } else {
+      const txType = tx.tx_type || tx.type || 'Unknown';
+      const signer = tx.signer || tx.from || tx.pubkey || 'unknown';
+      console.log(`  ${C.dim}Type:${C.reset} ${C.cyan}${txType}${C.reset}`);
+      console.log(`  ${C.dim}Signer:${C.reset} ${C.cyan}${signer}${C.reset}`);
+    }
+    console.log();
+  }
+
+  // Submit the transaction
+  let result;
+  let latencyMs;
+
+  try {
+    const start = Date.now();
+    result = await httpPost(rpc, '/v1/tx', tx);
+    latencyMs = Date.now() - start;
+  } catch (err) {
+    if (asJson) {
+      console.log(JSON.stringify({
+        success: false,
+        error: err.message,
+        rpc,
+        cli_version: CLI_VERSION,
+        timestamp: new Date().toISOString(),
+      }, null, 2));
+    } else {
+      console.log(`  ${C.red}✗ Network error:${C.reset} ${err.message}`);
+      console.log(`  ${C.dim}  Check that your RPC is accessible: ${rpc}${C.reset}`);
+    }
+    process.exit(1);
+  }
+
+  const success = result && !result.error && result.accepted !== false;
+
+  if (asJson) {
+    console.log(JSON.stringify({
+      success,
+      accepted: result?.accepted ?? null,
+      signature: result?.signature ?? result?.tx_signature ?? signature ?? null,
+      slot: result?.slot ?? null,
+      error: result?.error ?? null,
+      rpc,
+      latency_ms: latencyMs,
+      cli_version: CLI_VERSION,
+      timestamp: new Date().toISOString(),
+    }, null, 2));
+    return;
+  }
+
+  if (success) {
+    const sig = result?.signature ?? result?.tx_signature ?? signature ?? 'unknown';
+    console.log(`${C.green}✓ Transaction accepted!${C.reset}`);
+    console.log(`  ${C.green}★${C.reset} ${C.bright}Signature:${C.reset} ${sig}`);
+    if (result?.slot) {
+      console.log(`  ${C.dim}  Slot:${C.reset} ${result.slot}`);
+    }
+    console.log(`  ${C.dim}  Latency:${C.reset} ${latencyMs}ms`);
+    console.log(`  ${C.dim}  RPC:${C.reset} ${rpc}`);
+    console.log();
+  } else {
+    const errMsg = result?.error || 'Transaction rejected by network';
+    console.log(`${C.red}✗ Transaction rejected${C.reset}`);
+    if (result?.error) {
+      console.log(`  ${C.red}  Error:${C.reset} ${result.error}`);
+    }
+    if (result?.logs) {
+      console.log(`  ${C.dim}  Logs:${C.reset}`);
+      for (const log of result.logs) {
+        console.log(`    ${C.dim}${log}${C.reset}`);
+      }
+    }
+    console.log(`  ${C.dim}  Latency:${C.reset} ${latencyMs}ms`);
+    console.log(`  ${C.dim}  RPC:${C.reset} ${rpc}`);
+    console.log();
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const opts = parseArgs();
+
+  try {
+    await broadcast(opts);
+  } catch (err) {
+    if (opts.asJson) {
+      console.log(JSON.stringify({
+        success: false,
+        error: err.message,
+        rpc: opts.rpc,
+        cli_version: CLI_VERSION,
+        timestamp: new Date().toISOString(),
+      }, null, 2));
+    } else {
+      console.log(`\n  ${C.red}✗ ${err.message}${C.reset}\n`);
+    }
+    process.exit(1);
+  }
+}
+
+main();
+
+module.exports = { broadcastCommand: main };

package/commands/epoch.js

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+/**
+ * aether-cli epoch
+ *
+ * Display current epoch information including timing, schedule,
+ * slots per epoch, and estimated staking rewards rate.
+ *
+ * Usage:
+ *   aether epoch                    Show current epoch with timing breakdown
+ *   aether epoch --json            JSON output for scripting/monitoring
+ *   aether epoch --rpc <url>       Query a specific RPC endpoint
+ *   aether epoch --schedule        Show upcoming epoch schedule
+ *
+ * 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',
+  cyan: '\x1b[36m',
+  magenta: '\x1b[35m',
+};
+
+const CLI_VERSION = '1.0.0';
+
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+
+function httpRequest(rpcUrl, pathStr, timeoutMs) {
+  timeoutMs = timeoutMs || 8000;
+  return new Promise(function(resolve, reject) {
+    const url = new URL(pathStr, 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: timeoutMs,
+      headers: { 'Content-Type': 'application/json' },
+    }, function(res) {
+      let data = '';
+      res.on('data', function(chunk) { data += chunk; });
+      res.on('end', function() {
+        try { resolve(JSON.parse(data)); }
+        catch { resolve({ raw: data }); }
+      });
+    });
+    req.on('error', reject);
+    req.on('timeout', function() { req.destroy(); reject(new Error('Request timeout')); });
+    req.end();
+  });
+}
+
+function httpPost(rpcUrl, pathStr, body, timeoutMs) {
+  timeoutMs = timeoutMs || 8000;
+  return new Promise(function(resolve, reject) {
+    const url = new URL(pathStr, 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: timeoutMs,
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(bodyStr),
+      },
+    }, function(res) {
+      let data = '';
+      res.on('data', function(chunk) { data += chunk; });
+      res.on('end', function() {
+        try { resolve(JSON.parse(data)); }
+        catch { resolve({ raw: data }); }
+      });
+    });
+    req.on('error', reject);
+    req.on('timeout', function() { req.destroy(); reject(new Error('Request timeout')); });
+    req.write(bodyStr);
+    req.end();
+  });
+}
+
+function getDefaultRpc() {
+  return process.env.AETHER_RPC || 'http://127.0.0.1:8899';
+}
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+function parseArgs() {
+  const args = process.argv.slice(3); // [node, index.js, epoch, ...]
+  return {
+    rpc: getDefaultRpc(),
+    asJson: args.indexOf('--json') !== -1 || args.indexOf('-j') !== -1,
+    showSchedule: args.indexOf('--schedule') !== -1 || args.indexOf('-s') !== -1,
+    rpcUrl: getDefaultRpc(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Fetch epoch info from RPC
+// ---------------------------------------------------------------------------
+
+async function fetchEpochInfo(rpc) {
+  // Try Aether-native endpoint first
+  try {
+    const epochInfo = await httpRequest(rpc, '/v1/epoch-info');
+    if (epochInfo && !epochInfo.error && (epochInfo.epoch !== undefined || epochInfo.current_epoch)) {
+      return { data: epochInfo, source: 'aether' };
+    }
+  } catch(e) {
+    // fall through
+  }
+
+  // Fallback: try Solana-compat JSON-RPC
+  try {
+    const result = await httpPost(rpc, '/', {
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'getEpochInfo',
+    });
+    if (result && result.result) {
+      return { data: result.result, source: 'solana-compat' };
+    }
+  } catch(e) {
+    // fall through
+  }
+
+  // Try getEpochSchedule
+  try {
+    const schedule = await httpPost(rpc, '/', {
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'getEpochSchedule',
+    });
+    if (schedule && schedule.result) {
+      return { data: schedule.result, source: 'schedule-only' };
+    }
+  } catch(e) {
+    // fall through
+  }
+
+  throw new Error('Failed to fetch epoch info from RPC. Is your validator running?');
+}
+
+// ---------------------------------------------------------------------------
+// Format helpers
+// ---------------------------------------------------------------------------
+
+function formatAether(lamports) {
+  const aeth = lamports / 1e9;
+  if (aeth === 0) return '0 AETH';
+  return aeth.toFixed(4).replace(/\.?0+$/, '') + ' AETH';
+}
+
+function formatDuration(seconds) {
+  if (seconds < 0) return '\u2014';
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  const s = Math.floor(seconds % 60);
+  if (h > 24) {
+    const d = Math.floor(h / 24);
+    return d + 'd ' + (h % 24) + 'h';
+  }
+  if (h > 0) return h + 'h ' + m + 'm';
+  if (m > 0) return m + 'm ' + s + 's';
+  return s + 's';
+}
+
+function fmtPct(value, decimals) {
+  decimals = decimals || 1;
+  return (value || 0).toFixed(decimals) + '%';
+}
+
+// ---------------------------------------------------------------------------
+// Box drawing helpers
+// ---------------------------------------------------------------------------
+
+// Box drawing characters
+const BOX_H  = '\u2500'; // ─
+const BOX_V  = '\u2502'; // │
+const BOX_TL = '\u256d'; // ╭
+const BOX_TR = '\u256e'; // ╮
+const BOX_BL = '\u2570'; // ╰
+const BOX_BR = '\u256f'; // ╯
+const BOX_Cross = '\u253c'; // ┼
+
+function makeBoxLine(chars, width) {
+  let s = '';
+  for (let i = 0; i < width; i++) s += chars;
+  return s;
+}
+
+function makeSectionHeader(label) {
+  const total = 62;
+  const labelWithSpaces = ' ' + label + ' ';
+  const remaining = total - 4 - labelWithSpaces.length; // 4 for ╼ on each side
+  const half = Math.floor(remaining / 2);
+  const left = makeBoxLine('\u2550', half);
+  const right = makeBoxLine('\u2550', remaining - half);
+  return C.bright + C.cyan + '\u256e' + left + '\u2554' + labelWithSpaces + '\u2557' + right + '\u256f' + C.reset;
+}
+
+// ---------------------------------------------------------------------------
+// Main display
+// ---------------------------------------------------------------------------
+
+async function showEpochInfo(opts) {
+  const rpc = opts.rpcUrl;
+  const { data, source } = await fetchEpochInfo(rpc);
+
+  // Normalise fields across different RPC response formats
+  const epoch           = data.epoch ?? data.current_epoch ?? 0;
+  const slotIndex       = data.slotIndex ?? data.current_slot ?? 0;
+  const slotsInEpoch     = data.slotsInEpoch ?? data.slots_per_epoch ?? 8192;
+  const epochProgress    = slotsInEpoch > 0 ? (slotIndex / slotsInEpoch) * 100 : 0;
+  const absoluteSlot     = data.absoluteSlot ?? data.slot ?? 0;
+  const totalStaked      = BigInt(data.totalStaked ?? data.total_staked ?? data.stake ?? 0);
+  const rewardsPerEpoch  = BigInt(data.rewardsPerEpoch ?? data.rewards_per_epoch ?? data.rewards ?? 0);
+
+  // Estimate seconds per slot from slot data
+  const epochDurationSecs = data.epochDurationSecs ?? (slotsInEpoch * 0.4); // ~400ms/slot default
+  const secsPerSlot       = epochDurationSecs / slotsInEpoch;
+  const secondsIntoEpoch  = slotIndex * secsPerSlot;
+  const secondsRemaining  = (slotsInEpoch - slotIndex) * secsPerSlot;
+
+  // APY estimate: rewards per epoch / total staked * epochs per year
+  const epochsPerYear = 365 * 24 * 3600 / epochDurationSecs;
+  const apyRate = totalStaked > 0n
+    ? (Number(rewardsPerEpoch) / Number(totalStaked)) * epochsPerYear
+    : 0;
+  const apyBps = Math.round(apyRate * 10000);
+
+  if (opts.asJson) {
+    const out = {
+      epoch: epoch,
+      slotIndex: slotIndex,
+      slotsInEpoch: slotsInEpoch,
+      absoluteSlot: absoluteSlot,
+      epochProgress: epochProgress,
+      secondsIntoEpoch: Math.round(secondsIntoEpoch),
+      secondsRemaining: Math.round(secondsRemaining),
+      totalStaked: totalStaked.toString(),
+      totalStakedFormatted: formatAether(totalStaked),
+      rewardsPerEpoch: rewardsPerEpoch.toString(),
+      rewardsPerEpochFormatted: formatAether(rewardsPerEpoch),
+      estimatedApyBps: apyBps,
+      estimatedApy: fmtPct(apyRate),
+      source: source,
+      fetchedAt: new Date().toISOString(),
+    };
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+
+  // ASCII art header
+  console.log('');
+  const line1 = C.bright + C.cyan + BOX_TL + makeBoxLine(BOX_H, 60) + BOX_TR + C.reset;
+  console.log(line1);
+  const line2 = C.bright + C.cyan + BOX_V + '         AeTHer Epoch ' + epoch + ' Info         ' + BOX_V + C.reset;
+  console.log(line2);
+  const line3 = C.bright + C.cyan + BOX_BL + makeBoxLine(BOX_H, 60) + BOX_BR + C.reset;
+  console.log(line3);
+  console.log('');
+
+  console.log('  ' + C.dim + 'RPC: ' + rpc + C.reset);
+  console.log('');
+
+  // ── Epoch timing ───────────────────────────────────────────────────────
+  console.log(makeSectionHeader('Epoch Timing'));
+
+  const progressBars = 40;
+  const filled = Math.round((epochProgress / 100) * progressBars);
+  const empty = progressBars - filled;
+  const bar = C.green + '#'.repeat(filled) + C.dim + '\u2500'.repeat(empty) + C.reset;
+
+  console.log('  ' + C.dim + '  Progress:  [' + bar + '] ' + C.bright + fmtPct(epochProgress) + C.reset);
+  console.log('  ' + C.dim + '  Slot:      ' + C.reset + C.bright + slotIndex.toLocaleString() + C.reset + ' / ' + slotsInEpoch.toLocaleString() + ' slots into epoch');
+  console.log('  ' + C.dim + '  Abs slot:   ' + C.reset + absoluteSlot.toLocaleString());
+  console.log('  ' + C.dim + '  Elapsed:   ' + C.reset + formatDuration(Math.round(secondsIntoEpoch)));
+  console.log('  ' + C.dim + '  Remaining: ' + C.reset + C.yellow + formatDuration(Math.round(secondsRemaining)) + C.reset);
+  console.log('  ' + C.dim + '  Duration:  ' + C.reset + '~' + formatDuration(Math.round(epochDurationSecs)) + ' per epoch');
+  console.log('');
+
+  // ── Staking rewards ─────────────────────────────────────────────────────
+  console.log(makeSectionHeader('Staking Rewards'));
+
+  console.log('  ' + C.dim + '  Network stake:   ' + C.reset + C.bright + formatAether(totalStaked) + C.reset);
+  console.log('  ' + C.dim + '  Rewards/epoch:   ' + C.reset + C.green + formatAether(rewardsPerEpoch) + C.reset);
+  console.log('  ' + C.dim + '  Estimated APY:  ' + C.reset + C.green + C.bright + fmtPct(apyRate) + C.reset + ' ' + C.dim + '(~' + (apyBps / 100).toFixed(0) + ' bps)' + C.reset);
+  console.log('');
+
+  // ── Epoch schedule ──────────────────────────────────────────────────────
+  if (opts.showSchedule) {
+    console.log(makeSectionHeader('Upcoming Epochs'));
+    const startSlotNext = absoluteSlot + (slotsInEpoch - slotIndex);
+    for (let i = 0; i < 5; i++) {
+      const e = epoch + i;
+      const start = startSlotNext + i * slotsInEpoch;
+      const end = start + slotsInEpoch - 1;
+      const isNext = i === 0 ? ' ' + C.green + '(next)' + C.reset : '';
+      console.log('  ' + C.dim + '  Epoch ' + String(e).padStart(4) + ': slots ' + start.toLocaleString() + ' \u2013 ' + end.toLocaleString() + isNext + C.reset);
+    }
+    console.log('');
+  }
+
+  // ── Raw data ─────────────────────────────────────────────────────────────
+  console.log(makeSectionHeader('Raw RPC Data'));
+  console.log('  ' + C.dim + '  Source: ' + source + C.reset);
+  const rawPreview = JSON.stringify(data).substring(0, 80);
+  console.log('  ' + C.dim + '  ' + rawPreview + C.reset);
+  console.log('');
+
+  console.log('  ' + C.dim + 'Run "aether validators list" to see validator performance for epoch ' + epoch + '.' + C.reset);
+  console.log('  ' + C.dim + 'Run "aether rewards list --address <addr>" to check your staking rewards.' + C.reset);
+  console.log('');
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+async function epochCommand() {
+  const opts = parseArgs();
+  try {
+    await showEpochInfo(opts);
+  } catch (err) {
+    if (opts.asJson) {
+      console.log(JSON.stringify({ error: err.message }, null, 2));
+    } else {
+      console.log('');
+      console.log('  ' + C.red + '\u2514 Error: ' + C.reset + ' ' + err.message);
+      console.log('  ' + C.dim + 'Set a custom RPC: AETHER_RPC=https://your-rpc-url' + C.reset);
+      console.log('');
+    }
+    process.exit(1);
+  }
+}
+
+module.exports = { epochCommand };
+
+if (require.main === module) {
+  epochCommand();
+}