[GH-ISSUE #3734] [Feature] EVM deployment lineage reverse engineering: CREATE/CREATE2 initcode, constructors, factories, clones and library-link graphs #1445

New issue

Open

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

bsakaguchi commented

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

Owner

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

Problem Statement & Context

In on-chain EVM forensics, inspecting a deployed contract's runtime bytecode only reveals its active state machine. It conceals the deployment ceremony that brought the contract into existence:

Creation Bytecode vs Runtime Bytecode: The initialization code (initcode) executes once in a transient context, evaluates constructor arguments, sets immutable variables, populates initial storage slots, and returns the runtime bytecode slice via the RETURN opcode.
Deterministic Addresses (CREATE2): Smart contracts deployed at predictable addresses via keccak256(0xff ++ deployer ++ salt ++ keccak256(initcode))[12:], widely used by Uniswap pair factories, rollup bridges, and account abstraction wallets.
Minimal Proxy Clones (EIP-1167 / ERC-3448 / ERC-1967): Ultra-cheap 45-byte proxy bytecodes (363d3d373d3d3d363d73bebebebebebebebebebebebebebebebebebebebe5af43d82803e903d91602b57fd5bf3) delegating all calls to a shared master implementation.
Link References & Libraries: Unlinked bytecodes containing 20-byte placeholder signatures (__$30bbc75f483...$__) replaced during deployment with external library addresses.
Constructor Arguments & Immutables: Trailing bytes appended to initcode or runtime code representing constructor parameter buffers and compiled immutable value offsets.

REA lacks a dedicated deployment lineage engine capable of dissecting initcode, reconstructing constructor arguments, calculating CREATE2 salts, and mapping factory-to-clone hierarchies.

Proposed Architecture

flowchart TD
    A["Creation Bytecode (initcode) / Factory Deployment Trace"] --> B["EVM Deployment Lineage Engine"]
    B --> C["Initcode & Constructor Slicer"]
    B --> D["CREATE & CREATE2 Address Deriver"]
    B --> E["Clone & Proxy Pattern Recognizer"]
    B --> F["Library Link & Immutable Resolver"]
    
    C --> C1["Constructor Execution Simulation (REVM / Static Slicer)"]
    C --> C2["Constructor ABI Parameter Decoding"]
    C --> C3["Extracted Runtime Bytecode Slice"]
    
    D --> D1["CREATE Derivation (Deployer Address + Nonce)"]
    D --> D2["CREATE2 Derivation (Deployer + Salt + initcode hash)"]
    
    E --> E1["EIP-1167 Minimal Proxy Clone Detection"]
    E --> E2["ERC-1967 Transparent & UUPS Implementation Slots"]
    
    F --> F1["Library Link Placeholders & Resolved Dependencies"]
    F --> F2["Immutable Variable Offset Extraction"]
    
    C & D & E & F --> G["Synthesized Contract Deployment Manifest & Factory Hierarchy Graph"]

Technical Capabilities & Modules

Initcode Disassembly & Constructor Parameter Extraction:
- Separate transient constructor bytecode from trailing ABI-encoded constructor parameters.
- Decompile constructor logic: initialization assignments, ownership setup, and storage initializations.
- Extract the returned runtime bytecode slice defined by the terminal CODECOPY / RETURN opcodes.
CREATE & CREATE2 Address Verification:
- Reconstruct CREATE addresses from deployer address and deployment transaction nonces (RLP encoding).
- Reconstruct CREATE2 addresses: extract 32-byte salt parameters, compute keccak256(initcode), and verify counterfactual deployment addresses.
Proxy Clone Family Detection:
- Recognize standardized clone bytecode templates:
  - EIP-1167 Minimal Proxy: extract target master implementation address from byte offsets 10..30.
  - ERC-3448 MetaProxy: extract trailing metadata payloads.
  - ERC-1967 Implementation and Admin storage slots (0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc).
External Library Link Resolution:
- Scan for unresolved library placeholder patterns in compiled artifacts (__$name$__ or 20-byte zero placeholders).
- Match linked addresses against deployed external utility libraries (e.g. OpenZeppelin SafeCast, Strings).
Factory Deployment Lineage Graph:
- Given a factory contract (e.g. AMM Pool Factory, Token Factory), trace all deployed child contracts.
- Reconstruct the deployment dependency tree showing parent factories, deployed instances, and implementation upgrades.

Acceptance Criteria

Automated separation of initcode into constructor logic, runtime bytecode, and constructor parameters.
Accurate calculation and validation of both CREATE and CREATE2 deployment addresses.
Detection and target address extraction for EIP-1167 minimal clones and ERC-1967 proxies.
Extraction of constructor arguments and matching against candidate Solidity ABI definitions.
Generation of an interactive factory-to-instance deployment lineage diagram.

Complements #972 (Solidity/EVM reverse engineering)
Complements #2389 (EVM Standard JSON and compiler metadata)
Complements #2393 (EVM storage layout and proxy detection)
Complements #2396 (EVM bytecode comparison and semantic diffing)

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3734 [![Type: Feature](https://img.shields.io/badge/type-feature-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Domain: Blockchain RE](https://img.shields.io/badge/domain-blockchain_RE-orange.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 on-chain EVM forensics, inspecting a deployed contract's runtime bytecode only reveals its active state machine. It conceals the deployment ceremony that brought the contract into existence: 1. **Creation Bytecode vs Runtime Bytecode**: The initialization code (`initcode`) executes once in a transient context, evaluates constructor arguments, sets immutable variables, populates initial storage slots, and returns the runtime bytecode slice via the `RETURN` opcode. 2. **Deterministic Addresses (`CREATE2`)**: Smart contracts deployed at predictable addresses via `keccak256(0xff ++ deployer ++ salt ++ keccak256(initcode))[12:]`, widely used by Uniswap pair factories, rollup bridges, and account abstraction wallets. 3. **Minimal Proxy Clones (EIP-1167 / ERC-3448 / ERC-1967)**: Ultra-cheap 45-byte proxy bytecodes (`363d3d373d3d3d363d73bebebebebebebebebebebebebebebebebebebebe5af43d82803e903d91602b57fd5bf3`) delegating all calls to a shared master implementation. 4. **Link References & Libraries**: Unlinked bytecodes containing 20-byte placeholder signatures (`__$30bbc75f483...$__`) replaced during deployment with external library addresses. 5. **Constructor Arguments & Immutables**: Trailing bytes appended to initcode or runtime code representing constructor parameter buffers and compiled immutable value offsets. REA lacks a dedicated deployment lineage engine capable of dissecting initcode, reconstructing constructor arguments, calculating CREATE2 salts, and mapping factory-to-clone hierarchies. ### Proposed Architecture ```mermaid flowchart TD A["Creation Bytecode (initcode) / Factory Deployment Trace"] --> B["EVM Deployment Lineage Engine"] B --> C["Initcode & Constructor Slicer"] B --> D["CREATE & CREATE2 Address Deriver"] B --> E["Clone & Proxy Pattern Recognizer"] B --> F["Library Link & Immutable Resolver"] C --> C1["Constructor Execution Simulation (REVM / Static Slicer)"] C --> C2["Constructor ABI Parameter Decoding"] C --> C3["Extracted Runtime Bytecode Slice"] D --> D1["CREATE Derivation (Deployer Address + Nonce)"] D --> D2["CREATE2 Derivation (Deployer + Salt + initcode hash)"] E --> E1["EIP-1167 Minimal Proxy Clone Detection"] E --> E2["ERC-1967 Transparent & UUPS Implementation Slots"] F --> F1["Library Link Placeholders & Resolved Dependencies"] F --> F2["Immutable Variable Offset Extraction"] C & D & E & F --> G["Synthesized Contract Deployment Manifest & Factory Hierarchy Graph"] ``` ### Technical Capabilities & Modules 1. **Initcode Disassembly & Constructor Parameter Extraction:** - Separate transient constructor bytecode from trailing ABI-encoded constructor parameters. - Decompile constructor logic: initialization assignments, ownership setup, and storage initializations. - Extract the returned runtime bytecode slice defined by the terminal `CODECOPY` / `RETURN` opcodes. 2. **CREATE & CREATE2 Address Verification:** - Reconstruct `CREATE` addresses from deployer address and deployment transaction nonces (RLP encoding). - Reconstruct `CREATE2` addresses: extract 32-byte salt parameters, compute `keccak256(initcode)`, and verify counterfactual deployment addresses. 3. **Proxy Clone Family Detection:** - Recognize standardized clone bytecode templates: - EIP-1167 Minimal Proxy: extract target master implementation address from byte offsets 10..30. - ERC-3448 MetaProxy: extract trailing metadata payloads. - ERC-1967 Implementation and Admin storage slots (`0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc`). 4. **External Library Link Resolution:** - Scan for unresolved library placeholder patterns in compiled artifacts (`__$name$__` or 20-byte zero placeholders). - Match linked addresses against deployed external utility libraries (e.g. OpenZeppelin `SafeCast`, `Strings`). 5. **Factory Deployment Lineage Graph:** - Given a factory contract (e.g. AMM Pool Factory, Token Factory), trace all deployed child contracts. - Reconstruct the deployment dependency tree showing parent factories, deployed instances, and implementation upgrades. ### Acceptance Criteria - [ ] Automated separation of initcode into constructor logic, runtime bytecode, and constructor parameters. - [ ] Accurate calculation and validation of both `CREATE` and `CREATE2` deployment addresses. - [ ] Detection and target address extraction for EIP-1167 minimal clones and ERC-1967 proxies. - [ ] Extraction of constructor arguments and matching against candidate Solidity ABI definitions. - [ ] Generation of an interactive factory-to-instance deployment lineage diagram. ### Related Issues & Dependencies - Complements #972 (Solidity/EVM reverse engineering) - Complements #2389 (EVM Standard JSON and compiler metadata) - Complements #2393 (EVM storage layout and proxy detection) - Complements #2396 (EVM bytecode comparison and semantic diffing)

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:28 +00:00

[PR #1445] [MERGED] fix(javascript): invalidate references stored through property targets #2892