completed proxy upgrade history reconstructor

[buggythanos]

Description

Adds the Proxy Upgrade History Reconstructor to the BNBChain Cookbook. The tool reconstructs and visualizes the upgrade history of proxy contracts on BNB Smart Chain (BSC). It detects proxy types (EIP-1967, Beacon, Custom) by reading EIP-1967 storage slots and reconstructs upgrade events by scanning blockchain history. Includes a Web UI and CLI for analyzing upgradeable contracts.

Motivation: Helps developers, auditors, and researchers analyze upgradeable smart contracts, verify upgrade transparency, track contract changes, and perform security audits on proxy patterns.

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• 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?

• Unit tests: npm test (Jest). Coverage includes:
  • BSC provider initialization with default and custom RPC URLs
  • Contract vs EOA detection (isContract)
  • Storage slot reading (getStorageSlot) and address extraction
  • Proxy detection for EIP-1967, Beacon, and Custom patterns
  • Upgrade event retrieval (getUpgradeEvents) for various event signatures
  • Complete upgrade history reconstruction (reconstructUpgradeHistory)
  • Error handling for network failures and invalid addresses
• Build: npm run build (TypeScript compiles without errors)
• Setup: bash setup.sh (installs dependencies, creates .env from template, builds project, runs tests)
• Manual testing:
  • Web UI: npm run server → open http://localhost:3000 → enter proxy address → verify upgrade history display
  • CLI: npm start <proxy-address> [from-block] [to-block] with known proxy addresses on BSC
  • API: Tested /api/reconstruct endpoint with various proxy addresses and block ranges

Reproduction steps:

1. Clone repository
2. Run bash setup.sh (or chmod +x setup.sh && ./setup.sh)
3. Run npm test to verify all tests pass
4. Run npm run build to verify TypeScript compilation
5. Start server: npm run server
6. Open browser to http://localhost:3000 and test with a proxy address
7. Alternatively, test CLI: npm start <proxy-address>

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

[buggythanos]

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

Hi there, thank you!
0x4e5d4a29F7b02c8cf1310D112A42231Bde049180