protoscan 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# 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.
+
+```bash
+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
+```
+
+```bash
+# 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
+
+```bash
+npm install -g protoscan
+```
+
+## Quick Start
+
+### Scan a known protocol
+
+```bash
+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
+
+```bash
+# 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`:
+
+```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

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node