morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[GH-ISSUE #972] [Feature] Modular EVM bytecode analysis and execution evidence adapters #372

New issue

Closed

opened 2026-10-15 18:24:23 +00:00 by bsakaguchi · 2 comments

bsakaguchi commented

2026-10-15 18:24:23 +00:00

Owner

Originally created by @N0zoM1z0 on GitHub (Oct 7, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/972

Originally assigned to: @N0zoM1z0 on GitHub.

Before submitting

I searched the open and closed issues and pull requests for a related proposal.
I removed credentials, tokens, private paths, and sensitive target data.

Area

Other — EVM bytecode analysis and execution evidence.

Current limitation

REA does not currently expose an EVM analysis provider. At f8d84da127, the existing bytecode family schema covers JVM/Python; native executable analysis and debugger adapters do not establish EVM interface, control-flow or world-state semantics.

An agent with deployed bytecode must manually combine selector recovery, ABI candidates, decompiler output, proxy state, source artifacts and execution traces. These tools also have different network defaults, output formats and hardfork coverage, making their evidence difficult to join reliably.

Use cases

Inspect an unfamiliar local bytecode artifact: recovered dispatch entries, byte PCs, storage access candidates and unresolved control flow.
Relate supplied compiler output or ABI to exact bytecode, retaining metadata, library/immutable differences and signature ambiguity.
Explain which implementation executes in a proxy/delegatecall storage context at a selected state snapshot.
Inspect an imported transaction trace or an explicitly selected local simulation, preserving the distinction between recorded observations and replay-derived results.

Web3 and CTF are application domains/showcases. The capability architecture is reusable modular reverse engineering: artifact inspection, interface recovery, control/data flow, relationship tracing and execution evidence.

Desired outcome and success criteria

Provide shared CLI/MCP workflows through independently replaceable EVM adapters, starting with offline runtime-bytecode interface recovery. Each increment should be independently reviewable and usable.

Exact artifacts and recovered interfaces. Accept explicit local bytes/hex and selected compiler-artifact entries. Distinguish creation/init from deployed/runtime bytes; keep the original carrier identity, decoded-byte digest, algorithm and input scope. Return dispatch selectors and byte offsets with evidence; mark derived arguments, mutability and storage types as inferences. Preserve ABI/signature candidates instead of choosing a guessed canonical identity.
Control flow and pseudocode. Reuse a mature CFG/decompiler provider. Return byte-referenced branches, selected-function pseudocode and explicit unresolved edges. Identify the actual provider version, fork/profile coverage and limitations; reconstructed pseudocode is not recovered original source.
Artifact and state relationships. Join compiler source maps, caller ABI and bytecode comparisons with explicit provenance. Separately report offline proxy patterns and state-backed implementation/beacon/delegation relationships. Preserve code address and execution/storage context separately.
Execution evidence. Import supported producer trace formats first, with original payload/configuration and chain/block/transaction identities. Optional RPC acquisition and owned local execution remain explicit operations with their exact state/fork and lifecycle effects.

Acceptance must include real upstream runs on source-owned, compiler-version-pinned fixtures; packaged CLI/MCP examples; final advertised schema validation; malformed input/output; cancellation, bounds and owned-process cleanup. No node/full chain or heavy symbolic solver should be necessary for the first offline lane.

Authority boundaries and non-goals

Offline inspection must not implicitly contact RPC, explorer, signature or LLM services. Optional enrichment/acquisition uses the endpoint and target selected by the caller and preserves its evidence origin.
Local execution may own an isolated node/state directory. An adapter must not reset or stop a caller's existing provider. Signing, wallets, transaction broadcasting and production-chain mutation are outside this roadmap's outcomes.
Retain caller-selected local evidence; redact transport authentication credentials and explicitly marked sensitive values. Do not infer secrecy from field or environment-variable names.
Explicitly report unsupported formats/forks/chains. Initial EVM coverage does not imply all L2 execution variants, EOF, or other Web3 VMs.
Reuse upstream engines and ABI codecs. Keep provider wire protocols and engine dependencies outside domain/application code; production provider creation belongs in composition. Preserve upstream code, version/integrity and license provenance; don't rewrite a decompiler, interpreter, solver or replay language.
A selected operation expresses intent; don't introduce repeated approval flags. Report actual acquisition, local execution and cleanup effects.

Alternatives considered

Extending the JVM/Python enum alone would leave EVM words, byte PCs, dispatch, fork and world-state semantics undefined.
Directly exposing every upstream MCP/CLI command would inherit inconsistent authority, pagination and evidence semantics. A thin REA adapter can reuse the engines while providing named, validated contracts and shared CLI/MCP behavior.
Source analyzers such as Slither are useful when sources exist but cannot replace unverified raw-bytecode analysis. Heavy symbolic security engines can be optional later providers rather than prerequisites.
Existing Frida/pwntools/pwndbg work shares evidence and lifecycle infrastructure, but host-native process semantics do not cover an EVM execution environment.

Possible direction

Proposed order: EVMole offline interface evidence → replaceable CFG/decompiler adapter → compiler/proxy/state relationships → trace import and optional local execution. This is a staged capability-family roadmap; detailed operation contracts and follow-up issues should be narrowed before implementation.

Upstream	Proposed adapter role	Source-level constraints found during research
EVMole	First provider for selectors, entry offsets, inferred arguments/mutability/storage; optional CFG	Official JSON CLI/agent API and MCP exist. Agent API accepts runtime bytes, has section pagination, and calls analysis synchronously. Its SHA-256 identity is not Ethereum Keccak codehash; the request exposes no selectable hardfork.
SEVM / Heimdall	Replaceable CFG and pseudocode engines	Inspected SEVM constructor defaults to Shanghai; test later opcodes explicitly. Heimdall exposes hardfork and per-function timeout; auto detection can fall back to Latest. Keep remote resolution/LLM enrichment explicit and bound the complete operation.
WhatsABI	Optional proxy/ABI/signature relationship provider	Autoload defaults activate external loaders; diamond facet loading can query state independently of followProxies. Adapt explicit snapshot-backed providers, retaining proxy edges and all signature candidates.
Geth tracers, Foundry, REVM / EthereumJS EVM	Recorded trace adapters, then optional owned local execution	Capture producer/version/configuration. Re-execution is distinct from a node's recorded trace; missing world state is not automatically zero. A chosen release must actually support the documented workflow.

Prefer unchanged lockfile-pinned JS/WASM packages for library adapters and verified pinned BYO binaries for larger native providers. Use a pinned source checkout/submodule only when a required boundary is unavailable in a release. Default-branch APIs examined here may be newer than published releases: verify the exact distribution before committing to an integration.

Evidence/regression requirements:

Creation vs runtime, multiple compiler JSON contracts, unlinked libraries/immutables, malformed hex/metadata and empty code; compiler standard-json diagnostics must be checked even when process exit status is successful.
Optimized/unoptimized/viaIR fixtures; selector zero/collisions/fallback/receive; PUSH immediates containing selector/JUMPDEST-like bytes; dynamic jumps and later-fork opcodes. Keep every uint256/slot lossless through JSON.
Compiler source maps use instruction indices, while EVM PCs and source spans use byte offsets; handle PUSH widths, inherited mapping fields, generated sources and invalid mappings.
ERC-1167/1967 implementations/beacons, proxy cycles/dynamic relationships, delegatecall code vs storage context, missing storage vs observed zero. EIP-7702 designations need separate handling; EOF is a separate format/support claim.
Preserve raw calldata/events/revert data and supplied vs derived ABI provenance. Byte equality, comparisons with explained masked spans, and third-party source claims are different evidence.
Real local tracer captures exercise nested calls, reverts, logs and storage coverage. Geth-specific claims require Geth captures; other clients' similarly named tracers are separate profiles.

References

Product roadmap: #32. Related capability families: #968 (Frida), #969 (binary diagnostics/debugger adapters).
Current REA boundaries: bytecodeProvider.ts, AnalysisProviderRegistry.ts, composition/directAnalysis.ts.
Inspected upstream boundaries: EVMole agent API, Heimdall arguments, WhatsABI autoload, SEVM default profile.
Semantics: Solidity standard JSON, ABI, source mappings, ERC-1167, ERC-1967, EIP-7702, EIP-3540 status.
Runtime distinction: Geth tracing, cast run.

Research status: source/documentation review on 2026-10-07; no real REA EVM workflow has been implemented or verified. This proposal records candidates and acceptance requirements, not current support claims.

Originally created by @N0zoM1z0 on GitHub (Oct 7, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/972 Originally assigned to: @N0zoM1z0 on GitHub. ### Before submitting - [x] I searched the open and closed issues and pull requests for a related proposal. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Area Other — EVM bytecode analysis and execution evidence. ### Current limitation REA does not currently expose an EVM analysis provider. At f8d84da127fad871050c098b004a503b36795ad0, the existing bytecode family schema covers JVM/Python; native executable analysis and debugger adapters do not establish EVM interface, control-flow or world-state semantics. An agent with deployed bytecode must manually combine selector recovery, ABI candidates, decompiler output, proxy state, source artifacts and execution traces. These tools also have different network defaults, output formats and hardfork coverage, making their evidence difficult to join reliably. ### Use cases - Inspect an unfamiliar local bytecode artifact: recovered dispatch entries, byte PCs, storage access candidates and unresolved control flow. - Relate supplied compiler output or ABI to exact bytecode, retaining metadata, library/immutable differences and signature ambiguity. - Explain which implementation executes in a proxy/delegatecall storage context at a selected state snapshot. - Inspect an imported transaction trace or an explicitly selected local simulation, preserving the distinction between recorded observations and replay-derived results. Web3 and CTF are application domains/showcases. The capability architecture is reusable modular reverse engineering: artifact inspection, interface recovery, control/data flow, relationship tracing and execution evidence. ### Desired outcome and success criteria Provide shared CLI/MCP workflows through independently replaceable EVM adapters, starting with **offline runtime-bytecode interface recovery**. Each increment should be independently reviewable and usable. 1. **Exact artifacts and recovered interfaces.** Accept explicit local bytes/hex and selected compiler-artifact entries. Distinguish creation/init from deployed/runtime bytes; keep the original carrier identity, decoded-byte digest, algorithm and input scope. Return dispatch selectors and byte offsets with evidence; mark derived arguments, mutability and storage types as inferences. Preserve ABI/signature candidates instead of choosing a guessed canonical identity. 2. **Control flow and pseudocode.** Reuse a mature CFG/decompiler provider. Return byte-referenced branches, selected-function pseudocode and explicit unresolved edges. Identify the actual provider version, fork/profile coverage and limitations; reconstructed pseudocode is not recovered original source. 3. **Artifact and state relationships.** Join compiler source maps, caller ABI and bytecode comparisons with explicit provenance. Separately report offline proxy patterns and state-backed implementation/beacon/delegation relationships. Preserve code address and execution/storage context separately. 4. **Execution evidence.** Import supported producer trace formats first, with original payload/configuration and chain/block/transaction identities. Optional RPC acquisition and owned local execution remain explicit operations with their exact state/fork and lifecycle effects. Acceptance must include real upstream runs on source-owned, compiler-version-pinned fixtures; packaged CLI/MCP examples; final advertised schema validation; malformed input/output; cancellation, bounds and owned-process cleanup. No node/full chain or heavy symbolic solver should be necessary for the first offline lane. ### Authority boundaries and non-goals - Offline inspection must not implicitly contact RPC, explorer, signature or LLM services. Optional enrichment/acquisition uses the endpoint and target selected by the caller and preserves its evidence origin. - Local execution may own an isolated node/state directory. An adapter must not reset or stop a caller's existing provider. Signing, wallets, transaction broadcasting and production-chain mutation are outside this roadmap's outcomes. - Retain caller-selected local evidence; redact transport authentication credentials and explicitly marked sensitive values. Do not infer secrecy from field or environment-variable names. - Explicitly report unsupported formats/forks/chains. Initial EVM coverage does not imply all L2 execution variants, EOF, or other Web3 VMs. - Reuse upstream engines and ABI codecs. Keep provider wire protocols and engine dependencies outside domain/application code; production provider creation belongs in composition. Preserve upstream code, version/integrity and license provenance; don't rewrite a decompiler, interpreter, solver or replay language. - A selected operation expresses intent; don't introduce repeated approval flags. Report actual acquisition, local execution and cleanup effects. ### Alternatives considered - Extending the JVM/Python enum alone would leave EVM words, byte PCs, dispatch, fork and world-state semantics undefined. - Directly exposing every upstream MCP/CLI command would inherit inconsistent authority, pagination and evidence semantics. A thin REA adapter can reuse the engines while providing named, validated contracts and shared CLI/MCP behavior. - Source analyzers such as Slither are useful when sources exist but cannot replace unverified raw-bytecode analysis. Heavy symbolic security engines can be optional later providers rather than prerequisites. - Existing Frida/pwntools/pwndbg work shares evidence and lifecycle infrastructure, but host-native process semantics do not cover an EVM execution environment. ### Possible direction **Proposed order:** EVMole offline interface evidence → replaceable CFG/decompiler adapter → compiler/proxy/state relationships → trace import and optional local execution. This is a staged capability-family roadmap; detailed operation contracts and follow-up issues should be narrowed before implementation. | Upstream | Proposed adapter role | Source-level constraints found during research | | --- | --- | --- | | [EVMole](https://github.com/cdump/evmole/tree/1bcfbca596df8e500620d3e133d3c48a4db3f07d) | First provider for selectors, entry offsets, inferred arguments/mutability/storage; optional CFG | Official JSON CLI/agent API and MCP exist. Agent API accepts runtime bytes, has section pagination, and calls analysis synchronously. Its SHA-256 identity is not Ethereum Keccak codehash; the request exposes no selectable hardfork. | | [SEVM](https://github.com/acuarica/evm/tree/0dc035022ee32d765699a99a2f4ee601941b7fec) / [Heimdall](https://github.com/Jon-Becker/heimdall-rs/tree/f0aebc565a236d2070056de6d9cf73e89ce48489) | Replaceable CFG and pseudocode engines | Inspected SEVM constructor defaults to Shanghai; test later opcodes explicitly. Heimdall exposes hardfork and per-function timeout; auto detection can fall back to Latest. Keep remote resolution/LLM enrichment explicit and bound the complete operation. | | [WhatsABI](https://github.com/shazow/whatsabi/tree/9a4eb4174993be4ed6f06d79d0bdcc4c3b43b6b3) | Optional proxy/ABI/signature relationship provider | Autoload defaults activate external loaders; diamond facet loading can query state independently of followProxies. Adapt explicit snapshot-backed providers, retaining proxy edges and all signature candidates. | | [Geth tracers](https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers), [Foundry](https://github.com/foundry-rs/foundry), [REVM](https://github.com/bluealloy/revm) / [EthereumJS EVM](https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/evm) | Recorded trace adapters, then optional owned local execution | Capture producer/version/configuration. Re-execution is distinct from a node's recorded trace; missing world state is not automatically zero. A chosen release must actually support the documented workflow. | Prefer unchanged lockfile-pinned JS/WASM packages for library adapters and verified pinned BYO binaries for larger native providers. Use a pinned source checkout/submodule only when a required boundary is unavailable in a release. Default-branch APIs examined here may be newer than published releases: verify the exact distribution before committing to an integration. Evidence/regression requirements: - Creation vs runtime, multiple compiler JSON contracts, unlinked libraries/immutables, malformed hex/metadata and empty code; compiler standard-json diagnostics must be checked even when process exit status is successful. - Optimized/unoptimized/viaIR fixtures; selector zero/collisions/fallback/receive; PUSH immediates containing selector/JUMPDEST-like bytes; dynamic jumps and later-fork opcodes. Keep every uint256/slot lossless through JSON. - Compiler source maps use **instruction indices**, while EVM PCs and source spans use byte offsets; handle PUSH widths, inherited mapping fields, generated sources and invalid mappings. - ERC-1167/1967 implementations/beacons, proxy cycles/dynamic relationships, delegatecall code vs storage context, missing storage vs observed zero. EIP-7702 designations need separate handling; EOF is a separate format/support claim. - Preserve raw calldata/events/revert data and supplied vs derived ABI provenance. Byte equality, comparisons with explained masked spans, and third-party source claims are different evidence. - Real local tracer captures exercise nested calls, reverts, logs and storage coverage. Geth-specific claims require Geth captures; other clients' similarly named tracers are separate profiles. ### References - Product roadmap: #32. Related capability families: #968 (Frida), #969 (binary diagnostics/debugger adapters). - Current REA boundaries: [bytecodeProvider.ts](https://github.com/morluto/rea/blob/f8d84da127fad871050c098b004a503b36795ad0/src/domain/bytecodeProvider.ts), [AnalysisProviderRegistry.ts](https://github.com/morluto/rea/blob/f8d84da127fad871050c098b004a503b36795ad0/src/application/binary/AnalysisProviderRegistry.ts), [composition/directAnalysis.ts](https://github.com/morluto/rea/blob/f8d84da127fad871050c098b004a503b36795ad0/src/composition/directAnalysis.ts). - Inspected upstream boundaries: [EVMole agent API](https://github.com/cdump/evmole/blob/1bcfbca596df8e500620d3e133d3c48a4db3f07d/javascript/src/agent_api.mjs), [Heimdall arguments](https://github.com/Jon-Becker/heimdall-rs/blob/f0aebc565a236d2070056de6d9cf73e89ce48489/crates/decompile/src/interfaces/args.rs), [WhatsABI autoload](https://github.com/shazow/whatsabi/blob/9a4eb4174993be4ed6f06d79d0bdcc4c3b43b6b3/src/auto.ts), [SEVM default profile](https://github.com/acuarica/evm/blob/0dc035022ee32d765699a99a2f4ee601941b7fec/src/index.ts). - Semantics: [Solidity standard JSON](https://docs.soliditylang.org/en/stable/using-the-compiler.html), [ABI](https://docs.soliditylang.org/en/stable/abi-spec.html), [source mappings](https://docs.soliditylang.org/en/latest/internals/source_mappings.html), [ERC-1167](https://eips.ethereum.org/EIPS/eip-1167), [ERC-1967](https://eips.ethereum.org/EIPS/eip-1967), [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702), [EIP-3540 status](https://eips.ethereum.org/EIPS/eip-3540). - Runtime distinction: [Geth tracing](https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers), [cast run](https://getfoundry.sh/cast/reference/run/). Research status: source/documentation review on 2026-10-07; no real REA EVM workflow has been implemented or verified. This proposal records candidates and acceptance requirements, not current support claims.

bsakaguchi

2026-10-15 18:24:23 +00:00

closed this issue
added the
area: mcp

triage

area: domain

roadmap

enhancement

P2: medium
labels

bsakaguchi commented

2026-10-15 18:24:23 +00:00

Author

Owner

@N0zoM1z0 commented on GitHub (Oct 8, 2026):

First modular EVM increment merged in #1051 (7af7bc88): inspect_evm_interface / inspect-evm-interface adapt unchanged pinned EVMole for explicit local raw/hex carriers, with complete inline Evidence, source byte offsets and inference/unknown distinctions. Current-head31 CI checks and follow-up review passed; fresh installed CLI/MCP valid/unsupported-target cases passed. The broader roadmap stays open: CFG/decompilation, metadata/proxy/state relationships and execution/traces remain separate capabilities. Continuing the independent recorded-crash/pwndbg increment under #969.

@N0zoM1z0 commented on GitHub (Oct 8, 2026): First modular EVM increment merged in #1051 (7af7bc88): inspect_evm_interface / inspect-evm-interface adapt unchanged pinned EVMole for explicit local raw/hex carriers, with complete inline Evidence, source byte offsets and inference/unknown distinctions. Current-head31 CI checks and follow-up review passed; fresh installed CLI/MCP valid/unsupported-target cases passed. The broader roadmap stays open: CFG/decompilation, metadata/proxy/state relationships and execution/traces remain separate capabilities. Continuing the independent recorded-crash/pwndbg increment under #969.

bsakaguchi commented

2026-10-15 18:24:23 +00:00

Author

Owner

@morluto commented on GitHub (Oct 8, 2026):

Verified fixed on main (7a7460f0). EVM interface adapter ships (domain/evm/evmInterface, cli/evmCommands, contracts/evm) with docs/evm-bytecode.md and verify-evm-interface workflow. Closing per audit.

@morluto commented on GitHub (Oct 8, 2026): Verified fixed on main (7a7460f0). EVM interface adapter ships (domain/evm/evmInterface, cli/evmCommands, contracts/evm) with docs/evm-bytecode.md and verify-evm-interface workflow. Closing per audit.

bsakaguchi added

enhancement

and removed

enhancement

labels

2026-10-31 00:29:06 +00:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#372

No description provided.

Rows
Columns