Explain this tx example

[1evi7eo]

Description

This PR introduces a new Transaction Explainer tool for BNB Smart Chain (BSC), a BNBChain Cookbook demo that fetches and explains what any transaction does in human-readable format. The tool helps users understand blockchain transactions without needing to manually decode hex data or read contract ABIs.

Key Features:

• Transaction Fetching: Retrieves transaction data from BSC using JSON-RPC (eth_getTransaction and eth_getTransactionReceipt)
• Function Decoding: Automatically decodes common contract function calls (ERC-20 transfers, approvals, DEX swaps, etc.) using function selectors
• Intelligent Explanations: Provides rule-based explanations in plain English covering:
  • Simple BNB transfers
  • Contract function calls with decoded parameters
  • Contract creation transactions
  • Token operations (transfer, approve, mint, burn, etc.)
• Optional LLM Enhancement: When OPENAI_API_KEY is set, explanations are enhanced using OpenAI's GPT-4o-mini for more detailed and contextual insights
• Full-Stack Architecture: Express backend serves the SPA and provides /api/explain endpoint; Vite-powered frontend with dark theme UI
• Comprehensive Display: Shows transaction details (sender, receiver, value, gas, status), explanation, and links to BSCTrace explorer

Tech Stack:

• TypeScript for type safety
• Express.js for backend API server
• ethers v6 for RPC client and transaction parsing
• Vite for build tooling and dev server
• Vitest for unit testing
• OpenAI (optional) for LLM-enhanced explanations

This implementation provides a complete, production-ready tool that makes blockchain transactions accessible to both technical and non-technical users.

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 transaction fetching, decoding, and explanation logic
• Tested transaction hash validation and error handling for invalid inputs
• Verified function decoding for common ERC-20 operations (transfer, approve, transferFrom)
• Tested DEX function decoding (swapExactETHForTokens, swapExactTokensForTokens)
• Validated explanation generation for different transaction types (transfers, contract calls, contract creation)
• Tested Express API endpoint /api/explain with various transaction hashes
• Verified frontend UI displays transaction details and explanations correctly
• Tested optional OpenAI LLM enhancement when OPENAI_API_KEY is set
• Verified fallback to rule-based explanations when OpenAI is unavailable
• Built and tested production build with npm run build && npm start
• Tested on BSC mainnet with real transaction hashes

Reproduction Steps:

1. Clone the repository and run ./clone-and-run.sh (or manually: npm install, cp .env.example .env, npm run build, npm start)
2. Open http://localhost:3000 in a browser
3. Enter a valid BSC transaction hash (e.g., from BSCTrace)
4. Verify the transaction is fetched, decoded, and explained correctly
5. (Optional) Set OPENAI_API_KEY in .env to test LLM-enhanced explanations

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