protoscan 0.1.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "protoscan",
+  "version": "0.1.0",
+  "description": "On-chain protocol state tracker and diff tool for DeFi teams",
+  "type": "module",
+  "bin": {
+    "protoscan": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx src/index.ts",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "defi",
+    "protocol",
+    "ethereum",
+    "smart-contract",
+    "proxy",
+    "upgrade",
+    "monitoring",
+    "snapshot",
+    "diff",
+    "multi-chain",
+    "governance",
+    "admin"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "viem": "^2.21.0",
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/protoscan.config.json

@@ -0,0 +1,20 @@
+{
+  "chains": {
+    "ethereum": {
+      "rpc": "https://ethereum-rpc.publicnode.com",
+      "name": "Ethereum Mainnet"
+    }
+  },
+  "contracts": {
+    "AaveV3Pool": {
+      "address": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
+      "chains": ["ethereum"],
+      "type": "proxy"
+    },
+    "AaveV3PoolConfigurator": {
+      "address": "0x64b761D848206f447Fe2dd461b0c635Ec39EbB27",
+      "chains": ["ethereum"],
+      "type": "proxy"
+    }
+  }
+}

package/src/chains.ts

@@ -0,0 +1,38 @@
+import {
+  mainnet,
+  arbitrum,
+  optimism,
+  polygon,
+  base,
+  avalanche,
+  bsc,
+  gnosis,
+  scroll,
+  linea,
+  blast,
+  zkSync,
+  type Chain,
+} from 'viem/chains';
+
+const chainMap: Record<string, Chain> = {
+  ethereum: mainnet,
+  arbitrum,
+  optimism,
+  polygon,
+  base,
+  avalanche,
+  bsc,
+  gnosis,
+  scroll,
+  linea,
+  blast,
+  zksync: zkSync,
+};
+
+export function resolveChain(name: string): Chain | undefined {
+  return chainMap[name.toLowerCase()];
+}
+
+export function listSupportedChains(): string[] {
+  return Object.keys(chainMap);
+}

package/src/config.ts

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import type { ProtoscanConfig } from './types.js';
+
+const CONFIG_FILE = 'protoscan.config.json';
+
+const DEFAULT_CONFIG: ProtoscanConfig = {
+  chains: {
+    ethereum: {
+      rpc: 'https://eth.llamarpc.com',
+      name: 'Ethereum Mainnet',
+    },
+  },
+  contracts: {},
+};
+
+export function loadConfig(): ProtoscanConfig {
+  if (!existsSync(CONFIG_FILE)) {
+    throw new Error(
+      `No ${CONFIG_FILE} found. Run "protoscan init" to create one.`,
+    );
+  }
+  const raw = readFileSync(CONFIG_FILE, 'utf-8');
+  return JSON.parse(raw);
+}
+
+export function initConfig(): string {
+  if (existsSync(CONFIG_FILE)) {
+    throw new Error(`${CONFIG_FILE} already exists.`);
+  }
+  writeFileSync(CONFIG_FILE, JSON.stringify(DEFAULT_CONFIG, null, 2), 'utf-8');
+  return CONFIG_FILE;
+}
+
+export function configExists(): boolean {
+  return existsSync(CONFIG_FILE);
+}

package/src/diff.ts

@@ -0,0 +1,113 @@
+import type { Snapshot, SnapshotDiff, DiffEntry } from './types.js';
+
+const CRITICAL_FIELDS = new Set([
+  'erc1967.implementation',
+  'erc1967.admin',
+  'owner',
+  'admin',
+  'guardian',
+  'governance',
+  'timelock',
+  'pendingOwner',
+]);
+
+const WARNING_FIELDS = new Set([
+  'paused',
+  'erc1967.beacon',
+]);
+
+function severity(field: string): DiffEntry['severity'] {
+  if (CRITICAL_FIELDS.has(field)) return 'critical';
+  if (WARNING_FIELDS.has(field)) return 'warning';
+  return 'info';
+}
+
+export function diffSnapshots(from: Snapshot, to: Snapshot): SnapshotDiff {
+  const entries: DiffEntry[] = [];
+
+  const allContracts = new Set([
+    ...Object.keys(from.contracts),
+    ...Object.keys(to.contracts),
+  ]);
+
+  for (const name of allContracts) {
+    const fromContract = from.contracts[name];
+    const toContract = to.contracts[name];
+
+    if (!fromContract && toContract) {
+      entries.push({
+        contract: name,
+        field: '_contract',
+        before: '(not present)',
+        after: toContract.address,
+        severity: 'warning',
+      });
+      continue;
+    }
+
+    if (fromContract && !toContract) {
+      entries.push({
+        contract: name,
+        field: '_contract',
+        before: fromContract.address,
+        after: '(removed)',
+        severity: 'critical',
+      });
+      continue;
+    }
+
+    if (!fromContract || !toContract) continue;
+
+    // proxy info diff
+    if (fromContract.proxyInfo || toContract.proxyInfo) {
+      const fp = fromContract.proxyInfo || { implementation: null, admin: null, beacon: null };
+      const tp = toContract.proxyInfo || { implementation: null, admin: null, beacon: null };
+
+      for (const key of ['implementation', 'admin', 'beacon'] as const) {
+        const fromVal = fp[key] || '(none)';
+        const toVal = tp[key] || '(none)';
+        if (fromVal !== toVal) {
+          entries.push({
+            contract: name,
+            field: `erc1967.${key}`,
+            before: fromVal,
+            after: toVal,
+            severity: severity(`erc1967.${key}`),
+          });
+        }
+      }
+    }
+
+    // public reads diff
+    const allKeys = new Set([
+      ...Object.keys(fromContract.publicReads),
+      ...Object.keys(toContract.publicReads),
+    ]);
+
+    for (const key of allKeys) {
+      const fromVal = fromContract.publicReads[key] ?? '(none)';
+      const toVal = toContract.publicReads[key] ?? '(none)';
+      if (fromVal !== toVal) {
+        entries.push({
+          contract: name,
+          field: key,
+          before: fromVal,
+          after: toVal,
+          severity: severity(key),
+        });
+      }
+    }
+  }
+
+  entries.sort((a, b) => {
+    const sev = { critical: 0, warning: 1, info: 2 };
+    return sev[a.severity] - sev[b.severity];
+  });
+
+  return {
+    from: from.createdAt,
+    to: to.createdAt,
+    chain: to.chain,
+    entries,
+  };
+}

package/src/index.ts

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { loadConfig, initConfig } from './config.js';
+import { createClient, scanContract, scanProtocol } from './scanner.js';
+import { saveSnapshot, loadSnapshot, listSnapshots, resolveSnapshotFile } from './snapshot.js';
+import { diffSnapshots } from './diff.js';
+import { listProtocols, getProtocol } from './registry/index.js';
+import type { ContractSnapshot } from './types.js';
+
+const program = new Command();
+
+program
+  .name('protoscan')
+  .description('On-chain protocol state tracker and diff tool for DeFi teams')
+  .version('0.1.0');
+
+program
+  .command('init')
+  .description('Initialize protoscan config in current directory')
+  .action(() => {
+    try {
+      const path = initConfig();
+      console.log(chalk.green(`Created ${path}`));
+      console.log(chalk.dim('Edit it to add your chains and contracts.\n'));
+      console.log('Or use built-in protocol definitions:');
+      console.log(chalk.cyan('  protoscan protocols           # list supported protocols'));
+      console.log(chalk.cyan('  protoscan scan aave-v3 -c ethereum  # scan Aave V3'));
+    } catch (e: any) {
+      console.error(chalk.red(e.message));
+      process.exit(1);
+    }
+  });
+
+// ── Built-in protocol registry commands ──
+
+program
+  .command('protocols')
+  .description('List supported protocols in the built-in registry')
+  .action(() => {
+    const protos = listProtocols();
+    console.log(chalk.bold('\nSupported protocols:\n'));
+    for (const p of protos) {
+      const chains = Object.keys(p.deployments).join(', ');
+      const paramCount = p.params.length;
+      const accessCount = p.access.length;
+      console.log(`  ${chalk.cyan(p.id.padEnd(16))} ${p.name} v${p.version}`);
+      console.log(chalk.dim(`${''.padEnd(18)}chains: ${chains}`));
+      console.log(chalk.dim(`${''.padEnd(18)}${paramCount} params, ${accessCount} access roles, ${Object.keys(p.contracts).length} contracts\n`));
+    }
+    console.log(chalk.dim('Usage: protoscan scan <protocol-id> -c <chain>'));
+  });
+
+program
+  .command('scan')
+  .description('Scan a known protocol using built-in definitions')
+  .argument('<protocol>', 'Protocol ID (e.g. aave-v3, compound-v3)')
+  .option('-c, --chain <chain>', 'Chain to scan', 'ethereum')
+  .option('-l, --label <label>', 'Label for saved snapshot')
+  .action(async (protocolId, opts) => {
+    const proto = getProtocol(protocolId);
+    if (!proto) {
+      console.error(chalk.red(`Unknown protocol: ${protocolId}`));
+      console.log(chalk.dim('Run "protoscan protocols" to see available protocols.'));
+      process.exit(1);
+    }
+
+    const chainName = opts.chain;
+    if (!proto.deployments[chainName]) {
+      console.error(chalk.red(`${proto.name} is not deployed on ${chainName}`));
+      console.log(chalk.dim(`Available: ${Object.keys(proto.deployments).join(', ')}`));
+      process.exit(1);
+    }
+
+    const config = loadConfig();
+    const chainConfig = config.chains[chainName];
+    if (!chainConfig) {
+      console.error(chalk.red(`Chain "${chainName}" not in config. Add an RPC URL first.`));
+      process.exit(1);
+    }
+
+    const spinner = ora(`Scanning ${proto.name} on ${chainName}...`).start();
+    const client = createClient(chainName, chainConfig);
+
+    try {
+      const result = await scanProtocol(client, protocolId, chainName);
+      if (!result) {
+        spinner.fail('Scan returned no results');
+        process.exit(1);
+      }
+
+      spinner.succeed(`${proto.name} on ${chainName} @ block ${result.blockNumber}\n`);
+
+      // Contracts
+      console.log(chalk.bold.underline('Contracts'));
+      for (const [key, info] of Object.entries(result.contracts)) {
+        const proxyTag = info.proxyInfo ? chalk.dim(' (proxy)') : '';
+        console.log(`  ${chalk.bold(key)}${proxyTag}: ${info.address}`);
+        console.log(chalk.dim(`    ${info.role}`));
+        if (info.proxyInfo?.implementation) {
+          console.log(`    impl: ${chalk.cyan(info.proxyInfo.implementation)}`);
+        }
+        if (info.proxyInfo?.admin) {
+          console.log(`    admin: ${chalk.yellow(info.proxyInfo.admin)}`);
+        }
+      }
+
+      // Access control
+      if (result.access.length > 0) {
+        console.log(chalk.bold.underline('\nAccess Control'));
+        for (const a of result.access) {
+          const icon = a.severity === 'critical' ? chalk.red('✗') : chalk.yellow('!');
+          console.log(`  ${icon} ${chalk.bold(a.role)}`);
+          console.log(`    holder: ${chalk.yellow(a.holder)}`);
+          console.log(chalk.dim(`    ${a.description}`));
+        }
+      }
+
+      // Parameters
+      const categories = ['risk', 'rate', 'config', 'state', 'access'];
+      for (const cat of categories) {
+        const catParams = Object.entries(result.params).filter(([_, v]) => v.category === cat);
+        if (catParams.length === 0) continue;
+
+        console.log(chalk.bold.underline(`\n${cat.charAt(0).toUpperCase() + cat.slice(1)} Parameters`));
+        for (const [name, info] of catParams) {
+          const icon = info.severity === 'critical' ? chalk.red('✗')
+            : info.severity === 'warning' ? chalk.yellow('!') : chalk.dim('~');
+          console.log(`  ${icon} ${name}: ${chalk.cyan(info.value)}`);
+          console.log(chalk.dim(`    ${info.description}`));
+        }
+      }
+
+      // Save as snapshot
+      const snapData: Record<string, any> = {
+        _protocol: { id: protocolId, name: proto.name, chain: chainName },
+        _block: result.blockNumber.toString(),
+        _timestamp: result.timestamp,
+        contracts: result.contracts,
+        params: result.params,
+        access: result.access,
+      };
+
+      const label = opts.label || new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+      const { writeFileSync, mkdirSync, existsSync } = await import('node:fs');
+      const dir = '.protoscan';
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+      const filePath = `${dir}/${protocolId}_${chainName}_${label}.json`;
+      writeFileSync(filePath, JSON.stringify(snapData, null, 2), 'utf-8');
+      console.log(chalk.dim(`\nSaved: ${filePath}`));
+
+    } catch (e: any) {
+      spinner.fail(`Scan failed: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+// ── Custom contract commands (existing) ──
+
+program
+  .command('snapshot')
+  .description('Snapshot custom contracts from config')
+  .option('-c, --chain <chain>', 'Chain to snapshot (default: all)')
+  .option('-l, --label <label>', 'Snapshot label')
+  .action(async (opts) => {
+    const config = loadConfig();
+    const targetChains = opts.chain ? [opts.chain] : Object.keys(config.chains);
+
+    for (const chainName of targetChains) {
+      const chainConfig = config.chains[chainName];
+      if (!chainConfig) {
+        console.error(chalk.red(`Chain "${chainName}" not in config.`));
+        continue;
+      }
+
+      const spinner = ora(`Scanning ${chainName}...`).start();
+      const client = createClient(chainName, chainConfig);
+
+      const results: Record<string, ContractSnapshot> = {};
+      const contractEntries = Object.entries(config.contracts).filter(
+        ([_, entry]) => entry.chains.includes(chainName),
+      );
+
+      if (contractEntries.length === 0) {
+        spinner.warn(`No contracts configured for ${chainName}`);
+        continue;
+      }
+
+      for (const [name, entry] of contractEntries) {
+        spinner.text = `Scanning ${chainName} / ${name}...`;
+        try {
+          results[name] = await scanContract(client, chainName, name, entry);
+        } catch (e: any) {
+          spinner.warn(`Failed to scan ${name}: ${e.message}`);
+        }
+      }
+
+      const filePath = saveSnapshot(results, chainName, opts.label);
+      spinner.succeed(`${chainName}: ${Object.keys(results).length} contracts → ${filePath}`);
+    }
+  });
+
+program
+  .command('diff')
+  .description('Compare two snapshots')
+  .argument('<from>', 'First snapshot')
+  .argument('<to>', 'Second snapshot')
+  .option('-c, --chain <chain>', 'Chain filter')
+  .action((fromArg, toArg, opts) => {
+    try {
+      const fromFile = resolveSnapshotFile(fromArg, opts.chain);
+      const toFile = resolveSnapshotFile(toArg, opts.chain);
+      const fromSnap = loadSnapshot(fromFile);
+      const toSnap = loadSnapshot(toFile);
+      const result = diffSnapshots(fromSnap, toSnap);
+
+      if (result.entries.length === 0) {
+        console.log(chalk.green('No changes detected.'));
+        return;
+      }
+
+      console.log(chalk.bold(`\nChanges: ${result.from} → ${result.to} (${result.chain})\n`));
+
+      for (const entry of result.entries) {
+        const icon = entry.severity === 'critical' ? chalk.red('✗')
+          : entry.severity === 'warning' ? chalk.yellow('!') : chalk.dim('~');
+        console.log(`  ${icon} ${chalk.bold(`${entry.contract}.${entry.field}`)}`);
+        console.log(chalk.dim(`    ${entry.before}`));
+        console.log(chalk.green(`    ${entry.after}`));
+        console.log();
+      }
+
+      const critCount = result.entries.filter((e) => e.severity === 'critical').length;
+      const warnCount = result.entries.filter((e) => e.severity === 'warning').length;
+      const infoCount = result.entries.filter((e) => e.severity === 'info').length;
+      console.log(`${chalk.red(`${critCount} critical`)} | ${chalk.yellow(`${warnCount} warning`)} | ${chalk.dim(`${infoCount} info`)}`);
+    } catch (e: any) {
+      console.error(chalk.red(e.message));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('list')
+  .description('List saved snapshots')
+  .option('-c, --chain <chain>', 'Filter by chain')
+  .action((opts) => {
+    const snapshots = listSnapshots(opts.chain);
+    if (snapshots.length === 0) {
+      console.log(chalk.dim('No snapshots found.'));
+      return;
+    }
+    for (const s of snapshots) console.log(`  ${s}`);
+  });
+
+program
+  .command('show')
+  .description('Display a snapshot')
+  .argument('<snapshot>', 'Snapshot file or label')
+  .option('-c, --chain <chain>', 'Chain filter')
+  .action((snapArg, opts) => {
+    try {
+      const file = resolveSnapshotFile(snapArg, opts.chain);
+      const snap = loadSnapshot(file);
+
+      console.log(chalk.bold(`\nSnapshot: ${snap.chain} @ block ${snap.blockNumber}`));
+      console.log(chalk.dim(`Created: ${snap.createdAt}\n`));
+
+      for (const [name, contract] of Object.entries(snap.contracts)) {
+        console.log(chalk.bold.underline(name));
+        console.log(`  address: ${contract.address}`);
+        if (contract.proxyInfo) {
+          if (contract.proxyInfo.implementation) console.log(`  implementation: ${chalk.cyan(contract.proxyInfo.implementation)}`);
+          if (contract.proxyInfo.admin) console.log(`  proxy admin: ${chalk.yellow(contract.proxyInfo.admin)}`);
+        }
+        for (const [key, value] of Object.entries(contract.publicReads)) {
+          console.log(`  ${key}: ${value}`);
+        }
+        console.log();
+      }
+    } catch (e: any) {
+      console.error(chalk.red(e.message));
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/src/protocols/common.ts

@@ -0,0 +1,66 @@
+import { type PublicClient, type Address, parseAbi } from 'viem';
+
+const ownershipAbi = parseAbi([
+  'function owner() view returns (address)',
+  'function admin() view returns (address)',
+  'function guardian() view returns (address)',
+  'function pendingOwner() view returns (address)',
+  'function paused() view returns (bool)',
+  'function timelock() view returns (address)',
+  'function governance() view returns (address)',
+]);
+
+const tokenAbi = parseAbi([
+  'function name() view returns (string)',
+  'function symbol() view returns (string)',
+  'function decimals() view returns (uint8)',
+  'function totalSupply() view returns (uint256)',
+]);
+
+interface ReadResult {
+  key: string;
+  value: string;
+}
+
+async function tryRead(
+  client: PublicClient,
+  address: Address,
+  abi: readonly any[],
+  functionName: string,
+): Promise<ReadResult | null> {
+  try {
+    const result = await client.readContract({
+      address,
+      abi,
+      functionName,
+    });
+    return { key: functionName, value: String(result) };
+  } catch {
+    return null;
+  }
+}
+
+export async function readCommonState(
+  client: PublicClient,
+  address: Address,
+): Promise<Record<string, string>> {
+  const reads = await Promise.all([
+    tryRead(client, address, ownershipAbi, 'owner'),
+    tryRead(client, address, ownershipAbi, 'admin'),
+    tryRead(client, address, ownershipAbi, 'guardian'),
+    tryRead(client, address, ownershipAbi, 'pendingOwner'),
+    tryRead(client, address, ownershipAbi, 'paused'),
+    tryRead(client, address, ownershipAbi, 'timelock'),
+    tryRead(client, address, ownershipAbi, 'governance'),
+    tryRead(client, address, tokenAbi, 'name'),
+    tryRead(client, address, tokenAbi, 'symbol'),
+    tryRead(client, address, tokenAbi, 'decimals'),
+    tryRead(client, address, tokenAbi, 'totalSupply'),
+  ]);
+
+  const result: Record<string, string> = {};
+  for (const read of reads) {
+    if (read) result[read.key] = read.value;
+  }
+  return result;
+}

package/src/protocols/index.ts

@@ -0,0 +1,2 @@
+export { detectProxy, getProxySlots } from './proxy.js';
+export { readCommonState } from './common.js';

package/src/protocols/proxy.ts

@@ -0,0 +1,50 @@
+import { type PublicClient, type Address, type Hex, getAddress, pad, trim } from 'viem';
+import type { ProxyInfo } from '../types.js';
+
+// ERC-1967 storage slots
+const IMPLEMENTATION_SLOT = '0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc' as Hex;
+const ADMIN_SLOT = '0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103' as Hex;
+const BEACON_SLOT = '0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50' as Hex;
+
+// OpenZeppelin TransparentUpgradeableProxy (older pattern)
+const OZ_IMPL_SLOT = '0x7050c9e0f4ca769c69bd3a8ef740bc37934f8e2c036e5a723fd8ee048ed3f8c3' as Hex;
+
+async function readSlotAsAddress(client: PublicClient, address: Address, slot: Hex): Promise<Address | null> {
+  try {
+    const value = await client.getStorageAt({ address, slot });
+    if (!value || value === '0x0000000000000000000000000000000000000000000000000000000000000000') {
+      return null;
+    }
+    const trimmed = trim(value);
+    if (trimmed === '0x' || trimmed === '0x0') return null;
+    return getAddress(pad(trimmed, { size: 20 }));
+  } catch {
+    return null;
+  }
+}
+
+export async function detectProxy(client: PublicClient, address: Address): Promise<ProxyInfo | null> {
+  const [implementation, admin, beacon] = await Promise.all([
+    readSlotAsAddress(client, address, IMPLEMENTATION_SLOT),
+    readSlotAsAddress(client, address, ADMIN_SLOT),
+    readSlotAsAddress(client, address, BEACON_SLOT),
+  ]);
+
+  if (!implementation && !admin && !beacon) {
+    const ozImpl = await readSlotAsAddress(client, address, OZ_IMPL_SLOT);
+    if (ozImpl) {
+      return { implementation: ozImpl, admin: null, beacon: null };
+    }
+    return null;
+  }
+
+  return { implementation, admin, beacon };
+}
+
+export function getProxySlots(): Array<{ slot: Hex; label: string }> {
+  return [
+    { slot: IMPLEMENTATION_SLOT, label: 'erc1967.implementation' },
+    { slot: ADMIN_SLOT, label: 'erc1967.admin' },
+    { slot: BEACON_SLOT, label: 'erc1967.beacon' },
+  ];
+}