completed gas inefficiency detector example

[buggythanos]

Description

Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context.

Adds a Gas Inefficiency Detector for BNB Smart Chain (BSC) that analyzes smart contract transactions to find gas optimization opportunities. It inspects transaction patterns, gas usage, and common inefficiency signals and returns structured findings and recommendations.

The tool fetches transaction receipts and details via BSC RPC, runs several heuristics, and produces an efficiency score (0–100), severity‑classified inefficiencies, and estimated gas savings where possible. It supports both single‑tx and batch analysis.

Features:

• Transaction analysis: Analyze any BSC transaction by hash.
• Efficiency score: 0–100 score per transaction (higher = more efficient).
• Inefficiency detection:
  • Storage: Contract creation, excessive events (>20 logs), unnecessary state changes.
  • Computation: Large calldata, high gas for simple-looking operations.
  • External calls: Multiple contract interactions that could be batched.
  • Other: Failed transactions (CRITICAL), high gas usage (>500k), gas price >> base fee.
• Severity levels: LOW, MEDIUM, HIGH, CRITICAL.
• Recommendations: Targeted optimization suggestions.
• Gas savings estimates: Approximate savings for several inefficiency types.
• Batch analysis: analyzeMultipleTransactions with aggregate stats (total/average gas, average score, most common issues).
• Web UI: Dark-mode interface to submit hashes and view results.
• API: POST /api/analyze (single tx), POST /api/analyze-multiple (batch).

Tech stack: TypeScript, ethers.js v6, Express, Jest.

---

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.

The project includes a Jest test suite that targets:

1. getBSCProvider

   • Uses default BSC RPC URL when BSC_RPC_URL is unset.
   • Uses custom RPC URL from BSC_RPC_URL when set.

2. analyzeTransaction

   • Successful analysis returns txHash, blockNumber, from, to, gasUsed, inefficiencies, and efficiencyScore in [0, 100].
   • Throws if receipt or transaction is missing.
   • Detects: high gas usage (>500k), contract creation, excessive events (>20 logs), failed transactions (CRITICAL + gas wasted), and gas price significantly above base fee.

3. analyzeMultipleTransactions

   • Analyzes multiple hashes and returns analyses plus aggregate (e.g. totalGasUsed, averageGasUsed, averageEfficiencyScore, mostCommonIssues).
   • Skips failed fetches and continues with successful ones; aggregate reflects only successful analyses.

4. Efficiency score (via analyzeTransaction)

   • Score is always in [0, 100].
   • Lower score for higher gas usage.
   • Lower score when more inefficiencies are reported.

Tests use a custom __mocks__/ethers.ts that replaces JsonRpcProvider with a shared mock provider; all RPC calls are mocked.

How to run:

npm test

Manual checks:

• Start server: npm start server or npm run dev server, then open http://localhost:3000.
• Submit a BSC transaction hash in the UI and confirm analysis, score, and recommendations.
• Call POST /api/analyze with { "txHash": "0x..." } and POST /api/analyze-multiple with { "txHashes": ["0x...", "0x..."] }.

Note: The suite currently fails with TypeScript errors (see terminal output): mutating read‑only properties on mockReceipt/mockTransaction (e.g. gasUsed, contractAddress, logs, status, maxFeePerGas) and mock objects not matching TransactionReceipt (e.g. #private). Fixing these (e.g. by creating new mock objects per test instead of mutating, and using as any or minimal mock types) is required for npm test to pass. The PR description above assumes that work is done before submission.

---

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