protoscan

On-chain protocol state tracker and diff tool for DeFi teams.

Track deployed contract state across chains — proxy implementations, admin addresses, protocol parameters, access control — and detect changes between snapshots.

Why

During audits and post-deployment ops I kept repeating the same manual checks: verifying proxy implementations on Etherscan, comparing admin addresses across chains, checking that governance proposals actually changed what they were supposed to. Multiply that by 5 chains and 20 contracts and it becomes unsustainable.

With Defender sunsetting, there's even less tooling for this. protoscan fills the gap — a self-hosted CLI that gives you a complete picture of your protocol's on-chain state in one command.

Built-in Protocol Registry

protoscan ships with curated definitions for major DeFi protocols — contract addresses, ABIs, parameter names, and access control mappings across all deployed chains. No configuration needed.

protoscan protocols

  aave-v3          Aave V3 v3.0         5 chains | 10 params | 3 access roles
  compound-v3      Compound V3 v3.0     3 chains | 13 params | 3 access roles
  uniswap-v3       Uniswap V3 v3.0      5 chains | 10 params | 2 access roles
  maker            Maker (Sky) vMCD      1 chain  |  9 params | 2 access roles
  eigenlayer       EigenLayer v1.0       1 chain  |  7 params | 6 access roles
  pendle           Pendle v2.0           2 chains |  5 params | 2 access roles
  lido             Lido v2.0             1 chain  | 36 params | 4 access roles
  morpho-blue      Morpho Blue v1.0      2 chains | 20 params | 4 access roles

# Full protocol scan — contracts, access control, parameters
protoscan scan aave-v3 -c ethereum

# Save and compare
protoscan scan aave-v3 -c ethereum -l before-proposal
# ... governance executes ...
protoscan scan aave-v3 -c ethereum -l after-proposal
protoscan diff before-proposal after-proposal

Install

npm install -g protoscan

Quick Start

Scan a known protocol

protoscan scan morpho-blue -c ethereum

Output:

Contracts
  Morpho: 0xBBBB...FFCb
    Core immutable lending singleton
  MetaMorphoFactory: 0xA9c3...6101
    Factory deploying MetaMorpho vault instances
    ...

Access Control
  ✗ Morpho Core Owner
    holder: 0xcBa2...9AFa
    Can enable new IRMs/LLTVs and change fee recipient
  ✗ Vault Owner
    holder: 0x0A0e...8DD
    Full control over MetaMorpho vault
    ...

Config Parameters
  ! reserveFeePercent: 1000 (10.00%)
    Fee percentage taken from yield as protocol revenue
    ...

Track your own contracts

# Initialize config
protoscan init

# Edit protoscan.config.json with your contracts
protoscan snapshot -l baseline
# ... time passes ...
protoscan snapshot -l current
protoscan diff baseline current

Configuration

protoscan.config.json:

{
  "chains": {
    "ethereum": {
      "rpc": "https://ethereum-rpc.publicnode.com"
    },
    "arbitrum": {
      "rpc": "https://arbitrum-one-rpc.publicnode.com"
    }
  },
  "contracts": {
    "MyPool": {
      "address": "0x...",
      "chains": ["ethereum", "arbitrum"],
      "type": "proxy"
    }
  }
}

Contract types

| Type | Description | |------|-------------| | proxy | ERC-1967 proxy — tracks implementation, admin, beacon | | raw | Non-proxy contract — tracks public state only | | gnosis-safe | Safe multisig — tracks owners, threshold |

Commands

| Command | Description | |---------|-------------| | protoscan protocols | List supported protocols in the built-in registry | | protoscan scan <id> -c <chain> | Scan a known protocol | | protoscan snapshot | Snapshot custom contracts from config | | protoscan diff <from> <to> | Compare two snapshots | | protoscan show <snapshot> | Display a snapshot | | protoscan list | List saved snapshots |

What it reads

• Proxy implementation, admin, beacon (ERC-1967)
• Owner, admin, guardian, governance addresses
• Paused state, pending ownership transfers
• Protocol-specific parameters (rates, fees, ceilings, limits)
• Access control role holders
• Token supply and configuration

Changes are classified by severity:

• critical — implementation upgrade, admin/owner change, oracle swap
• warning — paused state, fee changes, beacon change
• info — supply changes, utilization metrics

Supported chains

Ethereum, Arbitrum, Optimism, Base, Polygon, Avalanche, BSC, Gnosis, Scroll, Linea, Blast, zkSync.

Adding a protocol

Protocol definitions live in src/registry/. Each file exports a ProtocolDef with contracts, deployment addresses, parameter definitions, and access control mappings. See existing definitions for the pattern.

PRs welcome — especially for protocols not yet covered.

License

MIT