[GH-ISSUE #3748] [Feature] Foundry and Hardhat project reverse engineering: build-info, deployments, broadcasts, libraries and contract dependency graphs #1457

New issue

Open

opened 2026-10-16 21:05:37 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:05:37 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 14, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3748

Problem Statement & Context

In smart contract auditing, vulnerability research, and incident response, analysts often receive local developer project folders authored in Foundry (forge) or Hardhat.

While REA issue #2389 addresses the raw solc Standard JSON format, modern developer frameworks generate extensive multi-file build and deployment pipelines:

Build Info Containers (artifacts/build-info/*.json / out/build-info/*.json): Massive JSON files containing complete compiler input configurations, optimizer runs, EVM versions, and compiler outputs (ASTs, source files, bytecodes, method identifiers).
Foundry Broadcasts & Deployments (broadcast/**/*.json): Transaction receipts, CREATE2 parameters, salts, deployed addresses, deployer nonces, and gas usage from automated deployment scripts.
Hardhat Artifacts & Deployments (artifacts/contracts/**/*.json): Per-contract artifacts containing ABI, bytecode, deployedBytecode, linkReferences, and immutableReferences.
Multi-Contract Dependency Graphs: Complex inter-contract relationships: base inheritance, interface implementations, imported libraries, external calls, and proxy bindings.

Without framework-aware project ingestion, analysts must manually correlate scattered build-info JSON files with on-chain addresses. REA needs a dedicated Foundry and Hardhat project reverse engineering engine capable of reconstructing the complete repository architecture, source graph, and deployment record.

Proposed Architecture

flowchart TD
    A["Developer Project Root (Foundry or Hardhat Repo)"] --> B["Smart Contract Project Engine"]
    B --> C["Framework Detector & Config Parser"]
    B --> D["Build-Info & Artifact Deserializer"]
    B --> E["Broadcast & Deployment Reconstructor"]
    B --> F["Inheritance & Dependency Graph Synthesizer"]
    
    C --> C1["foundry.toml / hardhat.config.ts Recognition"]
    C --> C2["Solc Compiler Settings & Re-mappings"]
    
    D --> D1["build-info/*.json Solc Input/Output Slicing"]
    D --> D2["LinkReferences & ImmutableReferences Extraction"]
    
    E --> E1["broadcast/ Run Receipts & Transactions (CREATE/CREATE2)"]
    E --> E2["Deployed Contract Address Book (Chain ID -> Address)"]
    
    F --> F1["Inheritance DAG (is Base, Initializable)"]
    F --> F2["Cross-Contract Call Topology & Interface Implementations"]
    
    C & D & E & F --> G["Synthesized Project Architecture Blueprint & Verified Address Manifest"]

Technical Capabilities & Modules

Framework Detection & Configuration Parsing:
- Detect project type: Foundry (foundry.toml), Hardhat (hardhat.config.js / .ts), or Brownie/Truffle.
- Parse path re-mappings (remappings.txt or foundry.toml remappings = [...]) to resolve dependency aliases (e.g. @openzeppelin/ -> lib/openzeppelin-contracts/).
Build-Info File Parsing:
- Stream and parse multi-megabyte build-info JSON files without memory exhaustion.
- Extract compiler metadata: compiler version, optimizer settings (runs), evmVersion (cancun, shanghai, paris).
- Map contract source files to compiled creation bytecode and runtime bytecode.
Link References & Immutables Mapping:
- Parse linkReferences: identify which bytecode offsets require external library addresses.
- Parse immutableReferences: map immutable variable names to their exact byte offsets inside the deployed runtime bytecode.
Foundry Broadcast & Deployment Analysis:
- Parse Foundry broadcast execution logs (broadcast/<script>/<chain_id>/run-latest.json):
  - Extract deployed contract addresses, deployer addresses, transaction hashes, gas used.
  - Extract CREATE2 salts and constructor arguments.
- Build a verified address book correlating local contracts with their on-chain deployment addresses per network.
Inheritance & Dependency Graph Synthesis:
- Parse contract ASTs from build-info to extract inheritance trees (is Ownable, ERC20).
- Map external function calls and interface dependencies (IERC20(token).transfer(...)).
- Generate an interactive Mermaid class diagram illustrating the contract architecture.

Acceptance Criteria

Automated detection and configuration ingestion for Foundry and Hardhat repositories.
Efficient streaming and parsing of large build-info JSON files.
Extraction of library link references and immutable variable byte offsets.
Reconstruction of deployed contract address books from Foundry broadcast logs.
Generation of an interactive contract inheritance and dependency graph.

Complements #972 (Solidity/EVM reverse engineering)
Complements #2389 (EVM Standard JSON and compiler metadata)
Complements #3734 (EVM deployment lineage reverse engineering)

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3748 [![Type: Feature](https://img.shields.io/badge/type-feature-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Domain: Reverse Engineering](https://img.shields.io/badge/domain-reverse_engineering-blueviolet.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ### Problem Statement & Context In smart contract auditing, vulnerability research, and incident response, analysts often receive local developer project folders authored in **Foundry** (`forge`) or **Hardhat**. While REA issue #2389 addresses the raw solc Standard JSON format, modern developer frameworks generate extensive multi-file build and deployment pipelines: 1. **Build Info Containers (`artifacts/build-info/*.json` / `out/build-info/*.json`)**: Massive JSON files containing complete compiler input configurations, optimizer runs, EVM versions, and compiler outputs (ASTs, source files, bytecodes, method identifiers). 2. **Foundry Broadcasts & Deployments (`broadcast/**/*.json`)**: Transaction receipts, CREATE2 parameters, salts, deployed addresses, deployer nonces, and gas usage from automated deployment scripts. 3. **Hardhat Artifacts & Deployments (`artifacts/contracts/**/*.json`)**: Per-contract artifacts containing ABI, bytecode, deployedBytecode, linkReferences, and immutableReferences. 4. **Multi-Contract Dependency Graphs**: Complex inter-contract relationships: base inheritance, interface implementations, imported libraries, external calls, and proxy bindings. Without framework-aware project ingestion, analysts must manually correlate scattered build-info JSON files with on-chain addresses. REA needs a dedicated Foundry and Hardhat project reverse engineering engine capable of reconstructing the complete repository architecture, source graph, and deployment record. ### Proposed Architecture ```mermaid flowchart TD A["Developer Project Root (Foundry or Hardhat Repo)"] --> B["Smart Contract Project Engine"] B --> C["Framework Detector & Config Parser"] B --> D["Build-Info & Artifact Deserializer"] B --> E["Broadcast & Deployment Reconstructor"] B --> F["Inheritance & Dependency Graph Synthesizer"] C --> C1["foundry.toml / hardhat.config.ts Recognition"] C --> C2["Solc Compiler Settings & Re-mappings"] D --> D1["build-info/*.json Solc Input/Output Slicing"] D --> D2["LinkReferences & ImmutableReferences Extraction"] E --> E1["broadcast/ Run Receipts & Transactions (CREATE/CREATE2)"] E --> E2["Deployed Contract Address Book (Chain ID -> Address)"] F --> F1["Inheritance DAG (is Base, Initializable)"] F --> F2["Cross-Contract Call Topology & Interface Implementations"] C & D & E & F --> G["Synthesized Project Architecture Blueprint & Verified Address Manifest"] ``` ### Technical Capabilities & Modules 1. **Framework Detection & Configuration Parsing:** - Detect project type: Foundry (`foundry.toml`), Hardhat (`hardhat.config.js` / `.ts`), or Brownie/Truffle. - Parse path re-mappings (`remappings.txt` or `foundry.toml` `remappings = [...]`) to resolve dependency aliases (e.g. `@openzeppelin/` -> `lib/openzeppelin-contracts/`). 2. **Build-Info File Parsing:** - Stream and parse multi-megabyte `build-info` JSON files without memory exhaustion. - Extract compiler metadata: compiler version, optimizer settings (runs), `evmVersion` (cancun, shanghai, paris). - Map contract source files to compiled creation bytecode and runtime bytecode. 3. **Link References & Immutables Mapping:** - Parse `linkReferences`: identify which bytecode offsets require external library addresses. - Parse `immutableReferences`: map immutable variable names to their exact byte offsets inside the deployed runtime bytecode. 4. **Foundry Broadcast & Deployment Analysis:** - Parse Foundry broadcast execution logs (`broadcast/<script>/<chain_id>/run-latest.json`): - Extract deployed contract addresses, deployer addresses, transaction hashes, gas used. - Extract `CREATE2` salts and constructor arguments. - Build a verified address book correlating local contracts with their on-chain deployment addresses per network. 5. **Inheritance & Dependency Graph Synthesis:** - Parse contract ASTs from build-info to extract inheritance trees (`is Ownable, ERC20`). - Map external function calls and interface dependencies (`IERC20(token).transfer(...)`). - Generate an interactive Mermaid class diagram illustrating the contract architecture. ### Acceptance Criteria - [ ] Automated detection and configuration ingestion for Foundry and Hardhat repositories. - [ ] Efficient streaming and parsing of large `build-info` JSON files. - [ ] Extraction of library link references and immutable variable byte offsets. - [ ] Reconstruction of deployed contract address books from Foundry broadcast logs. - [ ] Generation of an interactive contract inheritance and dependency graph. ### Related Issues & Dependencies - Complements #972 (Solidity/EVM reverse engineering) - Complements #2389 (EVM Standard JSON and compiler metadata) - Complements #3734 (EVM deployment lineage reverse engineering)

bsakaguchi referenced this issue

2026-10-17 21:01:32 +00:00

[GH-ISSUE #2383] [Tracker] Audit analysis and debugging coverage for the TIOBE top 100 languages (October 2026) #794

bsakaguchi referenced this issue

2026-10-17 21:11:33 +00:00

[PR #1457] [MERGED] perf(javascript): hash each semantic evidence context once #2899