protoscan 0.1.0

package/src/registry/uniswap-v3.ts

@@ -0,0 +1,198 @@
+import { parseAbi } from 'viem';
+import type { ProtocolDef } from './schema.js';
+
+const factoryAbi = parseAbi([
+  'function owner() view returns (address)',
+  'function feeAmountTickSpacing(uint24 fee) view returns (int24)',
+  'function getPool(address tokenA, address tokenB, uint24 fee) view returns (address pool)',
+]);
+
+const swapRouterAbi = parseAbi([
+  'function factory() view returns (address)',
+  'function factoryV2() view returns (address)',
+  'function positionManager() view returns (address)',
+  'function WETH9() view returns (address)',
+]);
+
+const positionManagerAbi = parseAbi([
+  'function factory() view returns (address)',
+  'function WETH9() view returns (address)',
+]);
+
+const ownerAbi = parseAbi([
+  'function owner() view returns (address)',
+]);
+
+export const uniswapV3: ProtocolDef = {
+  id: 'uniswap-v3',
+  name: 'Uniswap V3',
+  version: '3.0',
+  website: 'https://uniswap.org',
+  description: 'Concentrated liquidity automated market maker protocol',
+
+  contracts: {
+    Factory: { name: 'UniswapV3Factory', role: 'Deploys pools, controls fee tiers and protocol fee switch — sole admin surface in the protocol', type: 'raw' },
+    SwapRouter: { name: 'SwapRouter02', role: 'Multicall swap router for exact-in/out swaps across V2 & V3 pools, immutable with no admin', type: 'raw' },
+    NonfungiblePositionManager: { name: 'NonfungiblePositionManager', role: 'ERC-721 wrapper for concentrated liquidity positions, immutable with no admin', type: 'raw' },
+    QuoterV2: { name: 'QuoterV2', role: 'Off-chain quote simulation via revert-based swap simulation, stateless', type: 'raw' },
+  },
+
+  deployments: {
+    ethereum: {
+      Factory: '0x1F98431c8aD98523631AE4a59f267346ea31F984',
+      SwapRouter: '0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45',
+      NonfungiblePositionManager: '0xC36442b4a4522E871399CD717aBDD847Ab11FE88',
+      QuoterV2: '0x61fFE014bA17989E743c5F6cB21bF9697530B21e',
+    },
+    arbitrum: {
+      Factory: '0x1F98431c8aD98523631AE4a59f267346ea31F984',
+      SwapRouter: '0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45',
+      NonfungiblePositionManager: '0xC36442b4a4522E871399CD717aBDD847Ab11FE88',
+      QuoterV2: '0x61fFE014bA17989E743c5F6cB21bF9697530B21e',
+    },
+    optimism: {
+      Factory: '0x1F98431c8aD98523631AE4a59f267346ea31F984',
+      SwapRouter: '0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45',
+      NonfungiblePositionManager: '0xC36442b4a4522E871399CD717aBDD847Ab11FE88',
+      QuoterV2: '0x61fFE014bA17989E743c5F6cB21bF9697530B21e',
+    },
+    polygon: {
+      Factory: '0x1F98431c8aD98523631AE4a59f267346ea31F984',
+      SwapRouter: '0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45',
+      NonfungiblePositionManager: '0xC36442b4a4522E871399CD717aBDD847Ab11FE88',
+      QuoterV2: '0x61fFE014bA17989E743c5F6cB21bF9697530B21e',
+    },
+    base: {
+      Factory: '0x33128a8fC17869897dcE68Ed026d694621f6FDfD',
+      SwapRouter: '0x2626664c2603336E57B271c5C0b26F421741e481',
+      NonfungiblePositionManager: '0x03a520b32C04BF3bEEf7BEb72E919cf822Ed34f1',
+      QuoterV2: '0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a',
+    },
+  },
+
+  params: [
+    {
+      name: 'factoryOwner',
+      description: 'Factory owner — can enable fee tiers, transfer ownership, and set/collect protocol fee on any pool',
+      contract: 'Factory',
+      functionName: 'owner',
+      abi: factoryAbi,
+      decode: 'address',
+      category: 'access',
+      severity: 'critical',
+    },
+    {
+      name: 'feeTier100TickSpacing',
+      description: 'Tick spacing for the 0.01% fee tier (1 = enabled, stable-stable pairs)',
+      contract: 'Factory',
+      functionName: 'feeAmountTickSpacing',
+      args: [100],
+      abi: factoryAbi,
+      decode: 'uint',
+      category: 'config',
+      severity: 'info',
+    },
+    {
+      name: 'feeTier500TickSpacing',
+      description: 'Tick spacing for the 0.05% fee tier (10 = enabled, correlated pairs)',
+      contract: 'Factory',
+      functionName: 'feeAmountTickSpacing',
+      args: [500],
+      abi: factoryAbi,
+      decode: 'uint',
+      category: 'config',
+      severity: 'info',
+    },
+    {
+      name: 'feeTier3000TickSpacing',
+      description: 'Tick spacing for the 0.3% fee tier (60 = enabled, default general pairs)',
+      contract: 'Factory',
+      functionName: 'feeAmountTickSpacing',
+      args: [3000],
+      abi: factoryAbi,
+      decode: 'uint',
+      category: 'config',
+      severity: 'info',
+    },
+    {
+      name: 'feeTier10000TickSpacing',
+      description: 'Tick spacing for the 1% fee tier (200 = enabled, exotic pairs)',
+      contract: 'Factory',
+      functionName: 'feeAmountTickSpacing',
+      args: [10000],
+      abi: factoryAbi,
+      decode: 'uint',
+      category: 'config',
+      severity: 'info',
+    },
+    {
+      name: 'routerFactory',
+      description: 'Factory address the SwapRouter02 is wired to — must match canonical Factory or swaps route to a rogue deployment',
+      contract: 'SwapRouter',
+      functionName: 'factory',
+      abi: swapRouterAbi,
+      decode: 'address',
+      category: 'config',
+      severity: 'warning',
+    },
+    {
+      name: 'routerPositionManager',
+      description: 'NonfungiblePositionManager address referenced by SwapRouter02 (used for approve-and-call flows)',
+      contract: 'SwapRouter',
+      functionName: 'positionManager',
+      abi: swapRouterAbi,
+      decode: 'address',
+      category: 'config',
+      severity: 'info',
+    },
+    {
+      name: 'routerWETH9',
+      description: 'Wrapped native token used by SwapRouter02 for ETH-in/out swaps',
+      contract: 'SwapRouter',
+      functionName: 'WETH9',
+      abi: swapRouterAbi,
+      decode: 'address',
+      category: 'config',
+      severity: 'info',
+    },
+    {
+      name: 'positionManagerFactory',
+      description: 'Factory address the NonfungiblePositionManager is wired to — must match canonical Factory',
+      contract: 'NonfungiblePositionManager',
+      functionName: 'factory',
+      abi: positionManagerAbi,
+      decode: 'address',
+      category: 'config',
+      severity: 'warning',
+    },
+    {
+      name: 'positionManagerWETH9',
+      description: 'Wrapped native token used by the NonfungiblePositionManager for mint/increase/decrease liquidity in native ETH',
+      contract: 'NonfungiblePositionManager',
+      functionName: 'WETH9',
+      abi: positionManagerAbi,
+      decode: 'address',
+      category: 'config',
+      severity: 'info',
+    },
+  ],
+
+  access: [
+    {
+      role: 'Factory Owner — Fee Tier Governance',
+      description: 'Can permanently enable new fee tiers via enableFeeAmount (irreversible once set) and transfer factory ownership via setOwner',
+      contract: 'Factory',
+      functionName: 'owner',
+      abi: ownerAbi,
+      severity: 'critical',
+    },
+    {
+      role: 'Factory Owner — Protocol Fee Switch',
+      description: 'Can call the onlyFactoryOwner-gated setFeeProtocol and collectProtocol on ANY pool deployed by this factory — full economic control over the protocol-wide fee switch (up to 1/4 of LP swap fees) across every pool',
+      contract: 'Factory',
+      functionName: 'owner',
+      abi: ownerAbi,
+      severity: 'critical',
+    },
+  ],
+};

package/src/scanner.ts

@@ -0,0 +1,181 @@
+import { createPublicClient, http, type Address, type PublicClient } from 'viem';
+import { resolveChain } from './chains.js';
+import { detectProxy, readCommonState } from './protocols/index.js';
+import { getProtocolForChain, type ProtocolDef, type ParamDef, type AccessDef } from './registry/index.js';
+import type { ChainConfig, ContractEntry, ContractSnapshot } from './types.js';
+
+export function createClient(chainName: string, config: ChainConfig): PublicClient {
+  const chain = resolveChain(chainName);
+  return createPublicClient({
+    chain,
+    transport: http(config.rpc),
+    batch: { multicall: true },
+  });
+}
+
+export async function scanContract(
+  client: PublicClient,
+  chainName: string,
+  name: string,
+  entry: ContractEntry,
+): Promise<ContractSnapshot> {
+  const address = entry.address as Address;
+
+  const [blockNumber, block, proxyInfo, publicReads] = await Promise.all([
+    client.getBlockNumber(),
+    client.getBlock({ blockTag: 'latest' }),
+    entry.type === 'proxy' ? detectProxy(client, address) : Promise.resolve(null),
+    readCommonState(client, address),
+  ]);
+
+  if (proxyInfo?.implementation) {
+    const implReads = await readCommonState(client, proxyInfo.implementation);
+    for (const [key, value] of Object.entries(implReads)) {
+      if (!(key in publicReads)) {
+        publicReads[`impl.${key}`] = value;
+      }
+    }
+  }
+
+  return {
+    address,
+    chain: chainName,
+    blockNumber,
+    timestamp: Number(block.timestamp),
+    proxyInfo,
+    storageSlots: [],
+    publicReads,
+  };
+}
+
+async function readParam(
+  client: PublicClient,
+  address: Address,
+  param: ParamDef,
+): Promise<{ name: string; value: string; description: string } | null> {
+  try {
+    const result = await client.readContract({
+      address,
+      abi: param.abi,
+      functionName: param.functionName,
+      args: param.args || [],
+    });
+
+    let value = String(result);
+
+    if (param.decode === 'bps' && typeof result === 'bigint') {
+      value = `${result} (${(Number(result) / 100).toFixed(2)}%)`;
+    } else if (param.decode === 'ray' && typeof result === 'bigint') {
+      value = `${(Number(result) / 1e27).toFixed(6)}`;
+    } else if (param.decode === 'wad' && typeof result === 'bigint') {
+      value = `${(Number(result) / 1e18).toFixed(6)}`;
+    } else if (param.decode === 'percent' && typeof result === 'bigint') {
+      value = `${Number(result)}%`;
+    }
+
+    return { name: param.name, value, description: param.description };
+  } catch {
+    return null;
+  }
+}
+
+async function readAccess(
+  client: PublicClient,
+  address: Address,
+  access: AccessDef,
+): Promise<{ role: string; holder: string; description: string } | null> {
+  try {
+    const result = await client.readContract({
+      address,
+      abi: access.abi,
+      functionName: access.functionName,
+    });
+    return { role: access.role, holder: String(result), description: access.description };
+  } catch {
+    return null;
+  }
+}
+
+export interface ProtocolScanResult {
+  protocolId: string;
+  protocolName: string;
+  chain: string;
+  blockNumber: bigint;
+  timestamp: number;
+  contracts: Record<string, {
+    address: string;
+    role: string;
+    proxyInfo: { implementation: string | null; admin: string | null } | null;
+  }>;
+  params: Record<string, { value: string; description: string; category: string; severity: string }>;
+  access: Array<{ role: string; holder: string; description: string; severity: string }>;
+}
+
+export async function scanProtocol(
+  client: PublicClient,
+  protocolId: string,
+  chainName: string,
+): Promise<ProtocolScanResult | null> {
+  const found = getProtocolForChain(protocolId, chainName);
+  if (!found) return null;
+
+  const { protocol, addresses } = found;
+
+  const [blockNumber, block] = await Promise.all([
+    client.getBlockNumber(),
+    client.getBlock({ blockTag: 'latest' }),
+  ]);
+
+  const contracts: ProtocolScanResult['contracts'] = {};
+  for (const [key, def] of Object.entries(protocol.contracts)) {
+    const addr = addresses[key];
+    if (!addr) continue;
+    const proxyInfo = def.type === 'proxy'
+      ? await detectProxy(client, addr as Address)
+      : null;
+    contracts[key] = {
+      address: addr,
+      role: def.role,
+      proxyInfo: proxyInfo ? {
+        implementation: proxyInfo.implementation,
+        admin: proxyInfo.admin,
+      } : null,
+    };
+  }
+
+  const params: ProtocolScanResult['params'] = {};
+  for (const paramDef of protocol.params) {
+    const contractAddr = addresses[paramDef.contract];
+    if (!contractAddr) continue;
+    const result = await readParam(client, contractAddr as Address, paramDef);
+    if (result) {
+      params[result.name] = {
+        value: result.value,
+        description: result.description,
+        category: paramDef.category,
+        severity: paramDef.severity,
+      };
+    }
+  }
+
+  const access: ProtocolScanResult['access'] = [];
+  for (const accessDef of protocol.access) {
+    const contractAddr = addresses[accessDef.contract];
+    if (!contractAddr) continue;
+    const result = await readAccess(client, contractAddr as Address, accessDef);
+    if (result) {
+      access.push({ ...result, severity: accessDef.severity });
+    }
+  }
+
+  return {
+    protocolId,
+    protocolName: protocol.name,
+    chain: chainName,
+    blockNumber,
+    timestamp: Number(block.timestamp),
+    contracts,
+    params,
+    access,
+  };
+}

package/src/snapshot.ts

@@ -0,0 +1,70 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Snapshot, ContractSnapshot } from './types.js';
+
+const SNAPSHOT_DIR = '.protoscan';
+
+function ensureDir(dir: string): void {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+function snapshotPath(dir: string, chain: string, label: string): string {
+  return join(dir, `${chain}_${label}.json`);
+}
+
+function serializeSnapshot(snap: Snapshot): string {
+  return JSON.stringify(
+    snap,
+    (_, value) => (typeof value === 'bigint' ? value.toString() : value),
+    2,
+  );
+}
+
+export function saveSnapshot(
+  contracts: Record<string, ContractSnapshot>,
+  chain: string,
+  label?: string,
+): string {
+  const dir = SNAPSHOT_DIR;
+  ensureDir(dir);
+
+  const now = new Date();
+  const autoLabel = label || now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+
+  const firstContract = Object.values(contracts)[0];
+
+  const snapshot: Snapshot = {
+    version: '1',
+    createdAt: now.toISOString(),
+    chain,
+    blockNumber: firstContract ? firstContract.blockNumber.toString() : '0',
+    contracts: contracts as any,
+  };
+
+  const filePath = snapshotPath(dir, chain, autoLabel);
+  writeFileSync(filePath, serializeSnapshot(snapshot), 'utf-8');
+  return filePath;
+}
+
+export function loadSnapshot(filePath: string): Snapshot {
+  const raw = readFileSync(filePath, 'utf-8');
+  return JSON.parse(raw);
+}
+
+export function listSnapshots(chain?: string): string[] {
+  if (!existsSync(SNAPSHOT_DIR)) return [];
+  const files = readdirSync(SNAPSHOT_DIR).filter((f) => f.endsWith('.json'));
+  if (chain) return files.filter((f) => f.startsWith(`${chain}_`));
+  return files;
+}
+
+export function resolveSnapshotFile(nameOrPath: string, chain?: string): string {
+  if (existsSync(nameOrPath)) return nameOrPath;
+  const inDir = join(SNAPSHOT_DIR, nameOrPath);
+  if (existsSync(inDir)) return inDir;
+  if (chain) {
+    const withChain = join(SNAPSHOT_DIR, `${chain}_${nameOrPath}.json`);
+    if (existsSync(withChain)) return withChain;
+  }
+  throw new Error(`Snapshot not found: ${nameOrPath}`);
+}

package/src/types.ts

@@ -0,0 +1,67 @@
+import type { Address, Hex } from 'viem';
+
+export interface ChainConfig {
+  rpc: string;
+  name?: string;
+  blockExplorer?: string;
+}
+
+export interface ContractEntry {
+  address: Address;
+  chains: string[];
+  type: 'proxy' | 'raw' | 'gnosis-safe';
+  abi?: string;
+  label?: string;
+}
+
+export interface ProtoscanConfig {
+  chains: Record<string, ChainConfig>;
+  contracts: Record<string, ContractEntry>;
+  snapshotDir?: string;
+}
+
+export interface SlotReading {
+  slot: string;
+  label: string;
+  value: Hex;
+  decoded?: string;
+}
+
+export interface ProxyInfo {
+  implementation: Address | null;
+  admin: Address | null;
+  beacon: Address | null;
+}
+
+export interface ContractSnapshot {
+  address: Address;
+  chain: string;
+  blockNumber: bigint;
+  timestamp: number;
+  proxyInfo: ProxyInfo | null;
+  storageSlots: SlotReading[];
+  publicReads: Record<string, string>;
+}
+
+export interface Snapshot {
+  version: string;
+  createdAt: string;
+  chain: string;
+  blockNumber: string;
+  contracts: Record<string, ContractSnapshot>;
+}
+
+export interface DiffEntry {
+  contract: string;
+  field: string;
+  before: string;
+  after: string;
+  severity: 'info' | 'warning' | 'critical';
+}
+
+export interface SnapshotDiff {
+  from: string;
+  to: string;
+  chain: string;
+  entries: DiffEntry[];
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}