Whale tracker example

[1evi7eo]

Description

This PR introduces a new Whale Tracker tool for BNB Smart Chain (BSC), a BNBChain Cookbook demo that tracks large transactions (whale movements) by scanning blocks and filtering transactions above a configurable value threshold. This tool helps users identify and analyze high-value transactions on BSC for market analysis, whale watching, security monitoring, and on-chain analytics.

Key Features:

• Whale Detection: Automatically identifies large transactions above a configurable threshold (default: 10 BNB, configurable via MIN_WHALE_VALUE_BNB environment variable)
• Block Range Tracking: Scan specific block ranges (from/to block numbers) or recent blocks (last N blocks) for whale transactions
• Address Filtering: Optionally track whales for specific addresses, filtering by either sender (from) or receiver (to) address
• Transaction Details: View comprehensive transaction information including hash, block number, timestamp, from/to addresses, value (in both wei and BNB), gas usage, gas price, and transaction status (success/failed)
• Real-time Statistics: See total value tracked across all whale transactions, transaction count, and the block range analyzed
• Direct RPC Integration: Uses standard JSON-RPC methods (eth_blockNumber, eth_getBlockByNumber, eth_getTransactionReceipt) directly with BSC RPC endpoints
• Value Formatting: Automatic conversion from wei to BNB (18 decimals) for human-readable display
• Zero-Value Filtering: Automatically excludes zero-value transactions to focus on actual value transfers
• RESTful API: Express.js backend with endpoints for latest block number and whale tracking
• User-friendly UI: Modern dark-themed interface with left info pane and right tracking pane for seamless whale monitoring

How It Works:

1. Block Scanning: Fetches blocks from BSC using JSON-RPC eth_getBlockByNumber with full transaction details
2. Transaction Filtering: Filters transactions by:
   • Non-zero value (excludes contract calls without value)
   • Value above minimum threshold (whale threshold)
   • Optional address match (from or to address)
3. Status Checking: Fetches transaction receipts using eth_getTransactionReceipt to determine success/failure status
4. Aggregation: Calculates total value across all whale transactions and provides comprehensive statistics

Use Cases:

• Market Analysis: Monitor large transfers to understand market movements and liquidity flows
• Whale Watching: Track specific large holders and their transaction patterns
• Security Monitoring: Detect unusual large transactions that might indicate security issues or exploits
• On-chain Analytics: Analyze high-value transaction patterns on BSC for research and insights
• Portfolio Tracking: Monitor whale movements for specific addresses or contracts

Tech Stack:

• TypeScript for type safety and maintainability
• Express.js for HTTP server and RESTful API endpoints
• Direct JSON-RPC calls using native fetch API
• Plain HTML/CSS/JS for frontend with modern dark theme UI
• Vitest for comprehensive unit testing

This implementation provides a complete, production-ready tool that makes whale transaction tracking accessible and efficient, enabling users to gain insights into high-value blockchain activity on BSC.

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?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce.

• Ran unit tests with npm test to verify all whale tracking and formatting functions
• Tested hexToNumber and hexToBigInt conversion functions with various hex inputs
• Verified weiToBnb function correctly converts wei to BNB with proper decimal formatting
• Tested isWhaleTransaction function correctly identifies transactions above threshold
• Validated getLatestBlockNumber function fetches current block number from BSC RPC
• Tested getBlock function retrieves block data with transaction details
• Verified getTransactionReceipt function retrieves transaction status correctly
• Tested trackWhales function with various block ranges and thresholds
• Validated trackRecentWhales function correctly tracks recent blocks
• Tested address filtering functionality for both from and to addresses
• Verified zero-value transactions are correctly excluded
• Tested total value aggregation across multiple whale transactions
• Validated Express API endpoints (/api/latest-block, /api/track-whales) return correct data
• Tested error handling for invalid block ranges, RPC failures, and edge cases
• Verified frontend UI correctly displays whale transactions, statistics, and transaction details
• Tested with real BSC blocks and transactions to verify RPC integration
• Built and tested production build with npm run build && npm start
• Tested on BSC mainnet with real block ranges and various whale thresholds

Reproduction Steps:

1. Clone the repository and run ./clone-and-run.sh (or manually: npm install, cp .env.example .env, npm run build, npm test, npm start)
2. Open http://localhost:3000 in a browser
3. Set the minimum whale value threshold (default: 10 BNB)
4. Choose tracking mode:
   • Recent Blocks: Enter number of recent blocks to scan (e.g., 10)
   • Block Range: Enter specific from/to block numbers
5. Optionally enter a target address to filter whales for that specific address
6. Click "Track Whales" to scan blocks and display all whale transactions found
7. Review the results showing transaction details, total value tracked, and block range analyzed
8. Click on individual transactions to view full details including status, gas, and timestamps

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

[vivixu-cmd]

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

[1evi7eo]

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

Thank you for the opportunity to contribute!
0x23b23556c3CAA3C582EeE23Fc0D972352FB2a62c