[PR #2415] [CLOSED] feat(evm): inspect exact Solidity compiler artifacts #5213

New issue

Closed

opened 2026-10-31 01:04:51 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:04:51 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2415
Author: @fangkangmi
Created: 10/12/2026
Status: ❌ Closed

Base: main ← Head: codex/solc-compiler-artifacts-2389

📝 Commits (1)

f9ecf7c feat(evm): inspect exact Solidity compiler artifacts

📊 Changes

29 files changed (+2599 additions, -139 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+8 -1)
📝 .github/workflows/real-evm-interface.yml (+2 -0)
📝 docs/evm-bytecode.md (+75 -4)
➕ docs/specs/solidity/compiler-artifacts/plan.md (+20 -0)
➕ docs/specs/solidity/compiler-artifacts/spec.md (+74 -0)
➕ docs/specs/solidity/compiler-artifacts/tasks.md (+12 -0)
➕ docs/specs/solidity/compiler-artifacts/verification.md (+87 -0)
📝 package.json (+1 -0)
📝 scripts/ci/scopes.mjs (+3 -0)
➕ scripts/fixtures/solidity/compiler-artifacts.mjs (+76 -0)
➕ scripts/fixtures/solidity/compiler-artifacts.sol (+29 -0)
➕ scripts/verify-solc-artifacts.mjs (+502 -0)
📝 src/application/evm/EvmInterfaceService.ts (+13 -2)
📝 src/cli/evmCommands.ts (+46 -4)
📝 src/contracts/evm/evmToolContracts.ts (+13 -1)
📝 src/domain/analysisView/analysisView.ts (+16 -7)
📝 src/domain/analysisView/analysisViewCoverage.ts (+8 -0)
📝 src/domain/analysisView/evmInterfaceView.ts (+66 -10)
📝 src/domain/evm/evmInterface.ts (+91 -14)
➕ src/domain/evm/solcArtifact.ts (+191 -0)

...and 9 more files

📄 Description

Summary

Fixes #2389. Inspect an exact source-unit/contract and creation/deployed bytecode object from an existing solc Standard JSON output through the existing EVM CLI/MCP workflow. Preserve compiler diagnostics and provenance even when interface inference is unavailable.

Problem and expected behavior

Raw/hex inspection cannot distinguish contracts or bytecode kinds within a compiler output. The new self-contained encoding requires every selector in both the advertised schema and the handler:

{
  "path": "/artifacts/compiler-output.json",
  "encoding": {
    "kind": "solc-json",
    "source_unit": "contracts/Example.sol",
    "contract_name": "Example",
    "bytecode_kind": "deployed"
  }
}

CLI equivalent: rea inspect-evm-interface ./compiler-output.json solc-json --source-unit contracts/Example.sol --contract-name Example --bytecode-kind deployed --json.

Concrete objects use unchanged EVMole inference. Unlinked/absent objects retain compiler facts with inference_status: unavailable, nullable decoded identity and unknown candidate coverage. Compiler errors remain visible on selection and downstream inference failures. Raw/hex calls retain their existing result shape.

Change and scope

One bounded parser owns selection, JSON coordinates, placeholders and reference spans. Compiler summaries omit duplicate object/raw metadata text while retaining diagnostics and references; complete parent Evidence remains accessible. Includes the requested spec/plan/tasks, owned compiler fixtures, public verifier and integration into the existing real-EVM CI lane.

Contract and boundary impact

Semantic owner: compiler encoding/portable facts in src/domain/evm; format parsing at the EVM adapter boundary; shared application validation and existing named CLI/MCP operation.
Scope decision: not applicable to a new provider or target-execution capability. This extends existing offline file analysis without compiling or executing selected contracts.
CLI/MCP: additive encoding choice and CLI selection flags; actual SDK-converted schemas validate required nested selectors. Existing raw/hex calls remain compatible.
Provider/platform: unchanged EVMole 0.9.3 and Linux x64 admission/owned-worker lifecycle.
Evidence: original carrier digest, exact opaque source/contract identities, selected JSON pointer, UTF-16 syntax ranges, raw diagnostics/metadata, link/immutable spans and explicit unavailable facets.
Resources: existing 4 MiB input, 16 MiB reply and worker limits; preflight depth/node ceilings before AST allocation. Metadata resource refusal remains distinct from malformed syntax.
Package/generated metadata: one development verifier command; no dependency, version or installer change. Ignored catalogs/skill outputs regenerated; authored skill updated.

Expected effects:

Read caller-selected files.
Launch the existing owned Node/WASM analysis worker.
Write owned temporary snapshots/replies and remove them through existing supervision.

Inspection does not run solc, acquire source/chain data, inject instrumentation or mutate selected artifacts. The verification harness compiles its own fixture with caller-supplied solc.

Evidence and regression coverage

75 focused parser/domain/view/service/provider/MCP tests passed; two host/optional real-engine cases skipped.
47 new actual CLI/stdio-MCP cases passed with solc 0.8.30 and EVMole 0.9.3, including schema conversion, raw/hex equivalence, unlinked/absent output, compiler error-only output, EOF rejection diagnostics and retained summaries.
59 existing real EVM cases passed, including syscall checks for the traced raw/hex workflows.
Both public verifier runs verified cleanup with zero descendants and empty stderr.
86 CI-routing tests passed; compiler fixture/verifier changes select the EVM lane.

Validation performed

npm run build:cached, npm run check, npm run docs:check, npm run verify:test-discovery — passed.
Focused regression suites listed above — passed.
node scripts/verify-solc-artifacts.mjs and node scripts/verify-evm-interface.mjs with pinned compiler/strace configuration — passed.

Completed CLI elapsed/CPU/sampled family-memory measurements and token estimates, with comparison limits, are recorded in verification.md. No latency or token-saving claim is made.

Compatibility, safety, and release

Existing calls require no migration. Compiler-aware clients discover the encoding schema and handle nullable decoded bytes/unknown coverage. Real verification covers Linux source builds and solc 0.8.30; other hosts/compilers, fresh installed-package selection and live model tool selection remain unverified. Network syscalls were not independently traced for the new compiler-JSON lane. No release or deployment is included.

Before merge

Concrete issue and one focused Conventional Commit outcome.
Existing static-analysis scope and authority preserved.
Changed behavior and meaningful failures covered.
Owning contracts, documentation, authored skill and generated metadata updated.
Representative CLI/MCP input and result semantics documented.
Final diff checked for secrets, unrelated changes and unsupported claims.
Current-head hosted CI passes.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/2415 **Author:** [@fangkangmi](https://github.com/fangkangmi) **Created:** 10/12/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `codex/solc-compiler-artifacts-2389` --- ### 📝 Commits (1) - [`f9ecf7c`](https://github.com/morluto/rea/commit/f9ecf7c98845542896764af273912d865fbc42dc) feat(evm): inspect exact Solidity compiler artifacts ### 📊 Changes **29 files changed** (+2599 additions, -139 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+8 -1) 📝 `.github/workflows/real-evm-interface.yml` (+2 -0) 📝 `docs/evm-bytecode.md` (+75 -4) ➕ `docs/specs/solidity/compiler-artifacts/plan.md` (+20 -0) ➕ `docs/specs/solidity/compiler-artifacts/spec.md` (+74 -0) ➕ `docs/specs/solidity/compiler-artifacts/tasks.md` (+12 -0) ➕ `docs/specs/solidity/compiler-artifacts/verification.md` (+87 -0) 📝 `package.json` (+1 -0) 📝 `scripts/ci/scopes.mjs` (+3 -0) ➕ `scripts/fixtures/solidity/compiler-artifacts.mjs` (+76 -0) ➕ `scripts/fixtures/solidity/compiler-artifacts.sol` (+29 -0) ➕ `scripts/verify-solc-artifacts.mjs` (+502 -0) 📝 `src/application/evm/EvmInterfaceService.ts` (+13 -2) 📝 `src/cli/evmCommands.ts` (+46 -4) 📝 `src/contracts/evm/evmToolContracts.ts` (+13 -1) 📝 `src/domain/analysisView/analysisView.ts` (+16 -7) 📝 `src/domain/analysisView/analysisViewCoverage.ts` (+8 -0) 📝 `src/domain/analysisView/evmInterfaceView.ts` (+66 -10) 📝 `src/domain/evm/evmInterface.ts` (+91 -14) ➕ `src/domain/evm/solcArtifact.ts` (+191 -0) _...and 9 more files_ </details> ### 📄 Description ## Summary Fixes #2389. Inspect an exact source-unit/contract and creation/deployed bytecode object from an existing solc Standard JSON output through the existing EVM CLI/MCP workflow. Preserve compiler diagnostics and provenance even when interface inference is unavailable. ## Problem and expected behavior Raw/hex inspection cannot distinguish contracts or bytecode kinds within a compiler output. The new self-contained encoding requires every selector in both the advertised schema and the handler: ```json { "path": "/artifacts/compiler-output.json", "encoding": { "kind": "solc-json", "source_unit": "contracts/Example.sol", "contract_name": "Example", "bytecode_kind": "deployed" } } ``` CLI equivalent: `rea inspect-evm-interface ./compiler-output.json solc-json --source-unit contracts/Example.sol --contract-name Example --bytecode-kind deployed --json`. Concrete objects use unchanged EVMole inference. Unlinked/absent objects retain compiler facts with `inference_status: unavailable`, nullable decoded identity and unknown candidate coverage. Compiler errors remain visible on selection and downstream inference failures. Raw/hex calls retain their existing result shape. ## Change and scope One bounded parser owns selection, JSON coordinates, placeholders and reference spans. Compiler summaries omit duplicate object/raw metadata text while retaining diagnostics and references; complete parent Evidence remains accessible. Includes the requested spec/plan/tasks, owned compiler fixtures, public verifier and integration into the existing real-EVM CI lane. ## Contract and boundary impact - Semantic owner: compiler encoding/portable facts in `src/domain/evm`; format parsing at the EVM adapter boundary; shared application validation and existing named CLI/MCP operation. - Scope decision: not applicable to a new provider or target-execution capability. This extends existing offline file analysis without compiling or executing selected contracts. - CLI/MCP: additive encoding choice and CLI selection flags; actual SDK-converted schemas validate required nested selectors. Existing raw/hex calls remain compatible. - Provider/platform: unchanged EVMole 0.9.3 and Linux x64 admission/owned-worker lifecycle. - Evidence: original carrier digest, exact opaque source/contract identities, selected JSON pointer, UTF-16 syntax ranges, raw diagnostics/metadata, link/immutable spans and explicit unavailable facets. - Resources: existing 4 MiB input, 16 MiB reply and worker limits; preflight depth/node ceilings before AST allocation. Metadata resource refusal remains distinct from malformed syntax. - Package/generated metadata: one development verifier command; no dependency, version or installer change. Ignored catalogs/skill outputs regenerated; authored skill updated. Expected effects: - [x] Read caller-selected files. - [x] Launch the existing owned Node/WASM analysis worker. - [x] Write owned temporary snapshots/replies and remove them through existing supervision. Inspection does not run solc, acquire source/chain data, inject instrumentation or mutate selected artifacts. The verification harness compiles its own fixture with caller-supplied solc. ## Evidence and regression coverage - 75 focused parser/domain/view/service/provider/MCP tests passed; two host/optional real-engine cases skipped. - 47 new actual CLI/stdio-MCP cases passed with solc 0.8.30 and EVMole 0.9.3, including schema conversion, raw/hex equivalence, unlinked/absent output, compiler error-only output, EOF rejection diagnostics and retained summaries. - 59 existing real EVM cases passed, including syscall checks for the traced raw/hex workflows. - Both public verifier runs verified cleanup with zero descendants and empty stderr. - 86 CI-routing tests passed; compiler fixture/verifier changes select the EVM lane. ## Validation performed - `npm run build:cached`, `npm run check`, `npm run docs:check`, `npm run verify:test-discovery` — passed. - Focused regression suites listed above — passed. - `node scripts/verify-solc-artifacts.mjs` and `node scripts/verify-evm-interface.mjs` with pinned compiler/strace configuration — passed. Completed CLI elapsed/CPU/sampled family-memory measurements and token estimates, with comparison limits, are recorded in [verification.md](https://github.com/fangkangmi/rea/blob/codex/solc-compiler-artifacts-2389/docs/specs/solidity/compiler-artifacts/verification.md). No latency or token-saving claim is made. ## Compatibility, safety, and release Existing calls require no migration. Compiler-aware clients discover the encoding schema and handle nullable decoded bytes/unknown coverage. Real verification covers Linux source builds and solc 0.8.30; other hosts/compilers, fresh installed-package selection and live model tool selection remain unverified. Network syscalls were not independently traced for the new compiler-JSON lane. No release or deployment is included. ## Before merge - [x] Concrete issue and one focused Conventional Commit outcome. - [x] Existing static-analysis scope and authority preserved. - [x] Changed behavior and meaningful failures covered. - [x] Owning contracts, documentation, authored skill and generated metadata updated. - [x] Representative CLI/MCP input and result semantics documented. - [x] Final diff checked for secrets, unrelated changes and unsupported claims. - [ ] Current-head hosted CI passes. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:04:51 +00:00