completed event entropy analyzer spam detection

[buggythanos]

Description

This PR adds an Event Entropy Analyzer for detecting spam patterns in blockchain events on BNB Smart Chain (BSC). The tool analyzes Transfer and Approval events from smart contracts using Shannon entropy calculations to identify suspicious patterns that indicate automated spam activity.

By measuring the randomness and diversity of event data (addresses and values), the analyzer can distinguish between legitimate activity and spam. It calculates entropy scores, detects repetitive patterns, and provides actionable recommendations for security teams and developers.

Key Features:

• Shannon Entropy Calculation: Measures randomness/diversity in event data (addresses and values)
• Pattern Detection: Identifies repeated addresses, values, and sequential block patterns
• Spam Scoring System: Combines entropy and patterns into a 0-100 spam likelihood score
• Spam Level Classification: Categorizes results as LOW, MEDIUM, HIGH, or CRITICAL
• Intelligent Recommendations: Provides actionable insights based on detected patterns
• Support for Multiple Event Types: Analyzes both Transfer and Approval events
• Modern Web UI: Dark mode interface with interactive analysis visualization
• RESTful API: /api/analyze endpoint for programmatic access
• CLI Support: Command-line interface for batch analysis

Spam Detection Indicators:

• Many events from the same address (bot activity)
• Many events to the same address (airdrop spam)
• Identical values across multiple events
• Events occurring in sequential blocks
• Low unique address ratio relative to total events
• Low entropy (lack of diversity in data)

Spam Score Components:

• Entropy Component (40 points): Lower entropy = higher spam score
• Repetition Component (30 points): Higher repetition = higher spam score
• Sequential Blocks (20 points): More sequential blocks = higher spam score
• Unique Address Ratio (10 points): Lower ratio = higher spam score

Fixes # (issue)

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

The implementation includes a comprehensive test suite with 33 unit tests covering:

1. Entropy Calculation:

   • Empty array handling (returns 0)
   • Single value handling (returns 0)
   • All identical values (returns 0)
   • Maximum entropy for all unique values
   • Correct entropy calculation for mixed values
   • Large array handling (performance testing)

2. Pattern Analysis:

   • Empty events handling (returns zeros)
   • Repeated address detection (from and to)
   • Repeated value detection
   • Sequential block detection
   • Non-sequential block handling

3. Spam Score Calculation:

   • Zero score for no events
   • High score for low entropy scenarios
   • Low score for high entropy scenarios
   • Score bounds validation (0-100)
   • Score increase with high repetition

4. Spam Level Classification:

   • LOW level for scores < 40
   • MEDIUM level for scores 40-59
   • HIGH level for scores 60-79
   • CRITICAL level for scores >= 80

5. Recommendation Generation:

   • Recommendations for high spam levels
   • Detection of repeated from address patterns
   • Detection of repeated to address patterns
   • Detection of repeated value patterns
   • Detection of sequential blocks patterns
   • Low entropy detection
   • Low unique addresses ratio detection
   • Positive messages for normal patterns

6. Complete Event Entropy Analysis:

   • Default analysis for empty events
   • Analysis of events with high diversity
   • Spam detection in repetitive events
   • Correct unique address calculation
   • Recommendations included in results

Test execution:

npm test

All 33 tests pass successfully. The test suite uses Jest with comprehensive edge case coverage to ensure reliable spam detection across various scenarios.

Manual testing:

• Web UI tested by accessing http://localhost:3000 and analyzing various contract addresses and block ranges
• API endpoint tested via POST requests to /api/analyze with different contract addresses, event types, and block ranges
• CLI mode tested with different contract addresses, event types (Transfer/Approval), and block ranges
• Server mode tested by running npm start without arguments and accessing the web interface
• Tested with real BSC contracts including USDT and other high-volume tokens
• Validated spam detection accuracy with known spam patterns and legitimate activity

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Additional notes:

• Includes comprehensive README.md with setup instructions, usage examples, API documentation, and technical details
• Includes setup.sh script for one-command installation and setup
• Includes env.template for environment variable configuration
• TypeScript implementation with full type safety and comprehensive interfaces
• Uses ethers.js v6 for blockchain interactions and event parsing
• Express server with RESTful API endpoints
• Modern, responsive web UI with dark mode styling
• Graceful error handling for network issues, rate limits, and invalid inputs
• Support for both Transfer and Approval event types
• Efficient entropy calculation using Shannon entropy formula: H(X) = -Σ P(x) * log2(P(x))
• Weighted entropy calculation combining address entropy (70%) and value entropy (30%)
• Comprehensive pattern detection for various spam indicators
• Actionable recommendations based on detected patterns

[vivixu-cmd]

Congratulations! You have received a Cookbook reward. Please reply with your BSC wallet address.Thanks

[buggythanos]

Hi there, thank you!
0x4e5d4a29F7b02c8cf1310D112A42231Bde049180