[GH-ISSUE #2390] [Feature] Solidity: map EVM byte PCs to original and generated source spans #799

New issue

Open

opened 2026-10-15 18:28:35 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-15 18:28:35 +00:00

Owner

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

Analyst question and current gap

EVM interface results retain byte offsets but do not interpret Solidity source maps. Source-map entries index instructions, while PUSH immediates change byte PCs; direct index-to-PC substitution would produce incorrect debugging locations.

Proposed outcome

Consume caller-selected bytecode, source-map and source-ID facts from a selected compiler artifact, with explicit binding evidence.
Decode compressed mapping inheritance and instruction ordinals into byte PC ranges using the admitted bytecode profile.
Preserve original versus compiler-generated source identity, byte-based source spans, jump information and modifier depth when available.
Return unmapped/generated/invalid/unknown associations explicitly; validate source spans against caller-supplied source bytes before presenting snippets.
Keep compiler-attributed source positions distinct from reconstructed pseudocode and runtime observations. Do not read paths or fetch source URLs implicitly.

Acceptance and verification

Pinned owned fixtures cover PUSH1/PUSH32, omitted mapping fields, generated Yul sources, modifier nesting and UTF-8 source text.
Nonexistent source IDs, out-of-range spans, truncated instructions and wrong artifact associations never produce verified snippets.
Creation and deployed maps cannot be joined interchangeably.
CLI/MCP map exact selected PCs and retain coverage, bounds and cancellation.
Define one feature specification, one implementation plan and incremental tasks under docs/specs/solidity/source-mappings/ before implementation.

Scope and relationships

Offline caller-selected artifact inspection. Existing EVM interface recovery (PR #1051), retained delivery (PR #2308) and roadmap #972 are the foundations; this feature is independently scoped and does not reopen the entire roadmap. Parent language tracker: #2383. Use self-owned compiler fixtures and preserve provider/version provenance. New provider choices, if needed, follow CONTRIBUTING.md before substantial integration work.

Primary references

Solidity source mapping semantics

Originally created by @matbrgz on GitHub (Oct 12, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/2390 [![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) ## Analyst question and current gap EVM interface results retain byte offsets but do not interpret Solidity source maps. Source-map entries index instructions, while PUSH immediates change byte PCs; direct index-to-PC substitution would produce incorrect debugging locations. ## Proposed outcome - Consume caller-selected bytecode, source-map and source-ID facts from a selected compiler artifact, with explicit binding evidence. - Decode compressed mapping inheritance and instruction ordinals into byte PC ranges using the admitted bytecode profile. - Preserve original versus compiler-generated source identity, byte-based source spans, jump information and modifier depth when available. - Return unmapped/generated/invalid/unknown associations explicitly; validate source spans against caller-supplied source bytes before presenting snippets. - Keep compiler-attributed source positions distinct from reconstructed pseudocode and runtime observations. Do not read paths or fetch source URLs implicitly. ## Acceptance and verification - [ ] Pinned owned fixtures cover PUSH1/PUSH32, omitted mapping fields, generated Yul sources, modifier nesting and UTF-8 source text. - [ ] Nonexistent source IDs, out-of-range spans, truncated instructions and wrong artifact associations never produce verified snippets. - [ ] Creation and deployed maps cannot be joined interchangeably. - [ ] CLI/MCP map exact selected PCs and retain coverage, bounds and cancellation. - [ ] Define one feature specification, one implementation plan and incremental tasks under docs/specs/solidity/source-mappings/ before implementation. ## Scope and relationships Offline caller-selected artifact inspection. Existing EVM interface recovery (PR #1051), retained delivery (PR #2308) and roadmap #972 are the foundations; this feature is independently scoped and does not reopen the entire roadmap. Parent language tracker: #2383. Use self-owned compiler fixtures and preserve provider/version provenance. New provider choices, if needed, follow CONTRIBUTING.md before substantial integration work. ## Primary references - [Solidity source mapping semantics](https://docs.soliditylang.org/en/latest/internals/source_mappings.html)

bsakaguchi added the

area: domain

enhancement

P2: medium

labels

2026-10-15 18:28:35 +00:00

bsakaguchi commented

2026-10-15 18:28:36 +00:00

Author

Owner

@matbrgz commented on GitHub (Oct 12, 2026):

Triage & Architectural Review Notes

Objective (ELI5):
Map EVM program counters (PC byte offsets) back to exact source code spans (file, line, column, length) using compiler srcmap / srcmap-runtime.

Critical Considerations:

Compiler-Generated Code: In Solidity 0.8.x and Yul IR pipelines, certain opcodes originate from compiler internal routines (utility functions, panic reverts). These carry source index -1 or out-of-bounds spans. They must be explicitly classified as compiler-generated evidence rather than missing or faulty source files.
PC-to-Instruction Offset: EVM instruction byte offsets deviate from instruction indices due to variable-length PUSH<N> data bytes. The PC mapping table must index by exact byte PC.
Spec Target: docs/specs/evm/source-mappings/

@matbrgz commented on GitHub (Oct 12, 2026): ### Triage & Architectural Review Notes **Objective (ELI5):** Map EVM program counters (PC byte offsets) back to exact source code spans (file, line, column, length) using compiler `srcmap` / `srcmap-runtime`. **Critical Considerations:** 1. **Compiler-Generated Code:** In Solidity 0.8.x and Yul IR pipelines, certain opcodes originate from compiler internal routines (utility functions, panic reverts). These carry source index `-1` or out-of-bounds spans. They must be explicitly classified as `compiler-generated` evidence rather than missing or faulty source files. 2. **PC-to-Instruction Offset:** EVM instruction byte offsets deviate from instruction indices due to variable-length `PUSH<N>` data bytes. The PC mapping table must index by exact byte PC. 3. **Spec Target:** `docs/specs/evm/source-mappings/`

bsakaguchi referenced this issue

2026-10-16 21:02:34 +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-16 21:16:16 +00:00

[PR #801] [MERGED] feat(web): export captured scripts for JavaScript application analysis #2249

bsakaguchi added

enhancement

and removed

enhancement

labels

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