Mini subgraph event listener

[1evi7eo]

Description

This PR introduces a new Mini Subgraph Event Listener tool for BNB Smart Chain (BSC), a BNBChain Cookbook demo that enables listening to and querying blockchain events from smart contracts. This lightweight alternative to full subgraph infrastructure allows developers to monitor contract events in real-time or query historical events without deploying complex indexing infrastructure.

Key Features:

• Query Past Events: Fetch events from a specified block range on BSC using eth_getLogs RPC method
• Real-time Event Listening: Subscribe to new events as they're emitted on-chain using ethers.js event filters and provider event listeners
• Event Parsing & Decoding: Automatically decode event parameters using Solidity event signatures with ethers.js Interface
• Flexible Event Signatures: Support for custom event signatures in Solidity format (e.g., event Transfer(address indexed from, address indexed to, uint256 value))
• Sample Events: Pre-configured sample event signatures for common ERC-20 events (Transfer, Approval) and DEX events (PancakeSwap PairCreated)
• Event Data Structure: Comprehensive event data including block number, block hash, transaction hash, contract address, decoded arguments, topics, and raw data
• User-friendly UI: Modern dark-mode interface with left info pane explaining functionality and right interaction pane for event queries and real-time listening
• Error Handling: Robust validation for contract addresses and event signatures with clear error messages

Use Cases:

• Monitor ERC-20 token transfers and approvals
• Track DEX pair creation events
• Listen to custom contract events in real-time
• Query historical events for analytics or debugging
• Educational tool for understanding blockchain event indexing

Tech Stack:

• TypeScript for type safety and maintainability
• ethers.js v6 for blockchain interaction, event parsing, and RPC communication
• Vite for build tooling and development server
• Vitest for comprehensive unit testing

This implementation provides a complete, production-ready tool that makes blockchain event monitoring accessible without requiring subgraph infrastructure, perfect for prototyping, debugging, and educational purposes.

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 event listening and querying functions
• Tested address validation for valid and invalid BSC contract addresses
• Verified event signature validation for various Solidity event formats
• Tested queryPastEvents function with different block ranges and event signatures
• Validated event parsing and decoding logic for ERC-20 Transfer and Approval events
• Tested setupEventListener function for real-time event subscriptions
• Verified event listener cleanup function properly removes event listeners
• Tested getCurrentBlockNumber and getBlockTimestamp helper functions
• Validated parseEventLog function correctly extracts event data from logs
• Tested with real BSC contracts (WBNB, BUSD) to verify RPC integration
• Verified frontend UI correctly displays queried events and real-time event streams
• Tested error handling for invalid addresses, malformed event signatures, and RPC failures
• Built and tested production build with npm run build && npm run preview
• Tested on BSC mainnet with real contract addresses and event signatures

Reproduction Steps:

1. Clone the repository and run ./clone-and-run.sh (or manually: npm install, cp .env.example .env, npm test, npm run dev)
2. Open the dev server URL (e.g., http://localhost:5173) in a browser
3. Enter a valid BSC contract address (e.g., WBNB: 0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c)
4. Select a sample event signature (e.g., Transfer) or enter a custom one
5. For past events: Specify a block range and click "Query Events" to fetch historical events
6. For real-time: Click "Start Listening" to subscribe to new events as they're emitted
7. Verify events are correctly parsed, decoded, and displayed with all relevant details

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