Compound V2/V3 Risk Analyzer

A comprehensive risk assessment tool for analyzing wallet addresses across both Compound V2 and V3 protocols. This system evaluates on-chain transaction patterns to generate risk scores ranging from 0-1000 based on lending protocol interaction patterns, behavioral analysis, and protocol sophistication.

Overview

This analyzer processes Ethereum wallet addresses to assess their risk profiles based on interactions with Compound Finance protocols (both V2 and V3). It fetches transaction histories, extracts meaningful features, and calculates risk scores that reflect each wallet's lending protocol engagement and potential risk indicators.

Features

• Dual Protocol Support: Analyzes both Compound V2 (cToken) and V3 (Comet) transactions
• Comprehensive Feature Extraction: 40+ features covering transaction patterns, behavioral analysis, and protocol usage
• Advanced Risk Scoring: Multi-factor scoring system with realistic score distribution
• Behavioral Analysis: Timing patterns, gas usage consistency, and transaction spacing analysis
• Cross-Version Detection: Identifies users operating across both V2 and V3 protocols
• Robust Error Handling: Comprehensive API error handling with retry mechanisms

Requirements

• Python 3.8+
• Required packages: pandas, requests, numpy, python-dotenv
• Etherscan API key

Installation

1. Clone the repository:

git clone <repository-url>
cd compound-risk-analyzer

2. Install dependencies:

pip install -r requirements.txt

Alternatively, install manually:

pip install pandas requests numpy python-dotenv

3. Create a .env file with your Etherscan API key:

ETHERSCAN_API_KEY=your_api_key_here

4. Update file paths in the configuration section of main.py to match your directory structure.

requirements.txt

Create a requirements.txt file in your project root with the following content:

pandas>=1.3.0
requests>=2.25.0
numpy>=1.21.0
python-dotenv>=0.19.0

Configuration

Update the following paths in main.py:

INPUT_CSV = "path/to/your/wallet_addresses.csv"
OUTPUT_DIR = "path/to/json/cache/directory"
CSV_OUTPUT_DIR = "path/to/output/csv/directory"

Usage

1. Prepare a CSV file with wallet addresses in the first column
2. Run the analyzer:

python main.py

3. The system will:
   • Load wallet addresses from the input CSV
   • Fetch transaction histories from Etherscan API
   • Cache transaction data as JSON files
   • Extract comprehensive features
   • Calculate risk scores
   • Generate output CSV files

Output Files

The analyzer generates two main output files:

1. compound_v2_v3_wallet_scores.csv: Contains wallet addresses and their risk scores

   • Format: wallet_id,score
   • Sorted by score (highest to lowest)

2. compound_v2_v3_features.csv: Detailed feature matrix with all extracted features

   • Contains 40+ features per wallet for detailed analysis

Documentation

• analysis.md: Comprehensive technical documentation explaining the methodology
  • Data collection approach and API integration details
  • Feature selection rationale with detailed explanations of 40+ extracted features
  • Scoring algorithm methodology with mathematical formulas
  • Risk indicator justification covering primary, secondary, and tertiary factors
  • Model validation, limitations, and recommendations for enhancement

Supported Protocols

Compound V2 Contracts (cTokens)

• cETH, cUSDC, cDAI, cUSDT, cWBTC, cLEND, cREP, cSAI, cUNI, cTUSD, cLINK, cAAVE, cSUSHI

Compound V3 Contracts (Comet Markets)

• USDC base market, ETH base market, WETH base market
• Configurator and Rewards contracts

Risk Score Interpretation

• 800-1000: Excellent - Sophisticated users with consistent repayment history
• 650-799: Good - Active users with solid protocol engagement
• 450-649: Fair - Moderate activity with some risk indicators
• 0-449: Poor - High risk patterns or minimal activity

Key Features Analyzed

Transaction Patterns

• Total Compound transactions across V2/V3
• Supply, borrow, repay, and liquidation activities
• Cross-protocol usage patterns

Behavioral Indicators

• Transaction timing patterns (weekend/night activity)
• Gas price consistency
• Transaction spacing variance
• Protocol version sophistication

Risk Indicators

• Liquidation events
• Unpaid borrows
• Repayment ratios
• High-frequency trading patterns

Technical Architecture

Data Collection

• Etherscan API integration with robust error handling
• Transaction caching system to minimize API calls
• Comprehensive method signature detection

Feature Engineering

• 40+ quantitative features extracted per wallet
• Behavioral pattern analysis
• Cross-protocol activity detection
• Temporal activity analysis

Scoring Algorithm

• Multi-factor risk assessment
• Continuous scoring for better distribution
• Penalty system for high-risk behaviors
• Bonus system for sophisticated usage patterns

Error Handling

• API rate limiting with exponential backoff
• Network timeout handling
• Malformed transaction data handling
• Graceful degradation for failed wallet analysis

Performance

• Processes approximately 150-200 wallets per hour (depending on API limits)
• Efficient caching system reduces redundant API calls
• Batch processing with progress tracking

Limitations

• Limited to Etherscan API rate limits (5 calls/second for free tier)
• Transaction history limited to 10,000 most recent transactions per wallet
• Requires stable internet connection for API calls