🦙 LlamaScan

Comprehensive trust & security analysis for DeFi protocols

LlamaScan answers the critical question: "Is this protocol safe to use?"

Built as a contribution to DefiLlama.

⚠️ Note: This tool currently works for protocols that have a GitHub link on DefiLlama. Protocols without public GitHub repositories cannot be analyzed for code quality and activity metrics.

🎯 What It Does

LlamaScan performs deep security analysis across 5 layers:

Layer	Analysis	Status
1. Source Code	GitHub activity, code quality, contributors	✅ Done
2. Verification	Contract verified on Etherscan/Sourcify	✅ Done
3. Privileges	Admin powers, proxy detection, ownership	✅ Done
4. AI Audit	Automated vulnerability detection	📋 Planned
5. On-chain	Historical behavior, suspicious patterns	📋 Planned

⚠️ What It Detects

Dangerous Admin Functions

🔴 CRITICAL
├─ withdraw()      - Admin can drain funds
├─ pause()         - Admin can freeze user funds
├─ blacklist()     - Admin can block addresses
└─ emergencyWithdraw()

🟠 HIGH
├─ upgradeTo()     - Contract logic can be changed
├─ mint()          - Can inflate token supply
└─ setImplementation()

🟡 MEDIUM
├─ setFee()        - Can change fees (to 100%?)
├─ setOracle()     - Can manipulate prices
└─ transferOwnership()

Proxy Patterns

• EIP-1967 (UUPS/Transparent) - Upgradeable, HIGH risk
• Diamond (EIP-2535) - Modular, HIGH risk
• Beacon Proxy - All clones upgrade together, HIGH risk
• Minimal Proxy (EIP-1167) - Fixed implementation, LOW risk

Centralization Risks

• Single EOA owner
• No timelock on upgrades
• No multisig protection
• Renounced ownership (good!)

🚀 Quick Start

cd llamascan
npm install
cp .env.example .env  # Then add your API keys (see below)

# Scan a protocol (GitHub + optional contract analysis)
npm run dev -- scan aave

# Scan with specific contract addresses
npm run dev -- scan uniswap --contracts 0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984

# Verify a single contract (privilege analysis)
npm run dev -- verify 0xdAC17F958D2ee523a2206206994597C13D831ec7

# Scan with JSON output
npm run dev -- scan uniswap --json

# Scan a GitHub org directly (skip DefiLlama lookup)
npm run dev -- scan aave --github-only

# Check API rate limit
npm run dev -- rate-limit

🔑 API Keys Setup

Etherscan API Key (Recommended)

The Etherscan API key significantly improves contract verification coverage (~90% vs ~30% with Sourcify alone).

1. Go to etherscan.io/apis
2. Create a free account
3. Generate an API key (free tier: 5 calls/sec, 100k calls/day)
4. Add to your .env file:

ETHERSCAN_API_KEY=your_api_key_here

Without API key: Falls back to Sourcify (free, but lower coverage)

GitHub Token (Optional but Recommended)

Increases rate limit from 60 to 5000 requests/hour:

1. Go to github.com/settings/tokens
2. Generate a classic token with public_repo scope
3. Add to .env:

GITHUB_TOKEN=ghp_your_token_here

How It Works

1. You provide a protocol name (e.g., aave)
2. LlamaScan looks up the protocol on DefiLlama API
3. Gets the GitHub org(s) linked to that protocol
4. Analyzes GitHub activity, contributors, maturity
5. (Optional) Analyzes smart contracts for privileges
6. Calculates trust score

📊 Example Output

Protocol Scan

🦙 LlamaScan v0.3.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔍 Looking up "uniswap" on DefiLlama...
   Found: Uniswap
   GitHub: Uniswap
   Twitter: @Uniswap

📊 Fetching GitHub metrics...
   Found 163 repositories
   Total stars: 40,200
   Contributors: 10

🔐 Analyzing 1 contract(s) on ethereum...
   0x1f9840a8...4201F984
   ├─ Verified: ✅ Yes (Sourcify)
   ├─ Name: Uni
   ├─ Proxy: ✅ No
   ├─ Dangerous functions: 2
   └─ Privilege Score: 85/100

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Trust Score: 94/100 (Grade: A)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Contract Verification

npm run dev -- verify 0xdAC17F958D2ee523a2206206994597C13D831ec7

📋 Fetching verification status...
   Verified: ✅ Yes
   Name: TetherToken

⚠️  Dangerous Functions Found: 3
   🔴 CRITICAL (2):
      - pause(): Admin can freeze funds
      - unpause(): Admin can freeze funds
   🟡 MEDIUM (1):
      - transferOwnership()

Privilege Score: 65/100
Risk Assessment: 🟡 MEDIUM RISK

🏗️ Architecture

llamascan/
├── src/
│   ├── types/              # TypeScript interfaces
│   │   ├── index.ts        # Core types (GitHub)
│   │   ├── contracts.ts    # Contract analysis types
│   │   ├── ai.ts           # AI audit types
│   │   └── report.ts       # Final report types
│   │
│   ├── analyzers/          # Analysis modules
│   │   ├── source/         # Layer 1: GitHub
│   │   ├── verification/   # Layer 2: Etherscan/Sourcify
│   │   ├── privileges/     # Layer 3: Admin powers
│   │   ├── ai/             # Layer 4: Vulnerabilities
│   │   └── onchain/        # Layer 5: Behavior
│   │
│   ├── data/               # Reference databases
│   │   ├── dangerousFunctions.ts
│   │   └── proxyPatterns.ts
│   │
│   ├── scoring/            # Score calculation
│   └── cli.ts              # Command-line interface
│
├── data/                   # Generated reports
└── ARCHITECTURE.md         # Detailed design doc

📋 Scoring Methodology

Weights

Layer	Weight	Rationale
Source Code	15%	Active development indicates maintenance
Verification	20%	Verified = auditable, unverified = red flag
Privileges	30%	Most important - can admin steal funds?
AI Audit	20%	Automated vulnerability detection
On-chain	15%	Historical behavior matters

Risk Flags

Level	Score Impact	Meaning
🔴 CRITICAL	-40 to -50	Immediate danger
🟠 HIGH	-20 to -30	Significant risk
🟡 MEDIUM	-10 to -15	Moderate concern
🟢 LOW	-5	Minor issue

Mitigations (Bonus Points)

Finding	Bonus	Why
Timelock > 48h	+15	Time to react to malicious upgrades
Multisig (3/5+)	+10	Reduces single point of failure
Renounced ownership	+20	Contract is immutable
Battle-tested (>1yr, >$100M TVL)	+15	Proven track record

🔧 Configuration

Environment Variables

# GitHub (5000 req/hr vs 60)
GITHUB_TOKEN=ghp_xxx

# Block explorers (for contract verification)
ETHERSCAN_API_KEY=xxx
ARBISCAN_API_KEY=xxx
BASESCAN_API_KEY=xxx

# AI analysis (optional)
OPENAI_API_KEY=xxx

Supported Chains

• Ethereum
• Arbitrum
• Optimism
• Polygon
• Base
• BSC
• Avalanche
• Fantom
• Gnosis

📈 Roadmap

Phase 1: Core Infrastructure ✅

• Project structure
• GitHub analyzer
• Trust scoring algorithm
• CLI tool
• Type definitions for all layers

Phase 2: Contract Verification ✅

• Etherscan API integration
• Sourcify integration (free fallback)
• Bytecode matching
• Multi-chain support (9 chains)

Phase 3: Privilege Analysis ✅

• Dangerous function database (40+ patterns)
• Proxy pattern detection (EIP-1967, Diamond, Beacon, Minimal)
• Privilege score calculation
• Owner type detection (EOA/Multisig/DAO)
• Timelock detection

Phase 4: AI Analysis 📋

• Static vulnerability patterns
• Known exploit similarity matching
• LLM-powered code review
• Automated audit report generation

Phase 5: On-chain Behavior 📋

• Admin action history
• Fund flow analysis
• Suspicious pattern detection
• TVL history correlation

Phase 6: Integration 📋

• DefiLlama protocol database integration
• Batch scanning all protocols
• API endpoint for real-time queries
• Frontend dashboard

🤝 Contributing

This project is being built as a contribution to DefiLlama.

The goal is to become the "Head of Trust" - building the trust layer that helps users make informed decisions about DeFi protocols.

📜 License

MIT

---

Built with 🦙 by rontoTech