Skip to content

ethdebug: Emit type documents and state variable pointers #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
djolertrk wants to merge 2 commits into from
Closed

ethdebug: Emit type documents and state variable pointers #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
19a7db3
ethdebug: Require an explicit debug info selection and ast-id for eth…
djolertrk Aug 31, 2026
bdfb826
ethdebug: Emit type documents, state variable pointers and the progra…
djolertrk Aug 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions Changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,14 @@ Language Features:

Compiler Features:
* Commandline Interface: Remove support for the experimental Language Server Protocol (LSP) mode.
* Commandline Interface: Selecting an ethdebug output no longer implicitly enables the `ethdebug` and `ast-id` components of `--debug-info`; they have to be selected explicitly.
* EVM-ASM Optimizer: Improve performance of block deduplicator.
* General: Improve performance throughout the compiler using Boost's flat versions of unordered set and map.
* General: Remove support for the experimental Generic Solidity prototype (`pragma experimental solidity`).
* SMTChecker: Emit a deprecation warning for the BMC engine.
* SMTChecker: Support `block.slotnum`.
* Standard JSON Interface: Selecting an ethdebug output no longer implicitly enables the `ethdebug` and `ast-id` components of `settings.debug.debugInfo`; they have to be selected explicitly.
* ethdebug: Populate `ethdebug/format/info/resources` with the type documents and the pointer templates of the state variables in storage and transient storage, and publish the state variables in a program-level context (experimental).
* Standard JSON Interface: Fix the entire output being replaced by a `JSONError` ("Error writing output JSON.") when an error message quotes a long source line and truncating it splits a multi-byte character.

Bugfixes:
Expand Down
7 changes: 5 additions & 2 deletions docs/using-the-compiler.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -392,7 +392,9 @@ Input Description
// The snippet is quoted and follows the corresponding `@src` annotation.
// - `ast-id`: Annotations of the form `@ast-id <id>` over elements that can be mapped back to a definition in the original Solidity file.
// `<id>` is a node ID in the Solidity AST ('ast' output).
// - `ethdebug`: Ethdebug annotations (experimental). Automatically enabled when any ethdebug output is requested.
// - `ethdebug`: Ethdebug annotations (experimental). Depends on `ast-id`; selecting
// `ethdebug` without `ast-id` is an error. Requesting a program ethdebug output
// does not change this selection, which must then contain `ethdebug`.
// - `*`: Wildcard value that can be used to request all non-experimental components.
"debugInfo": ["location", "snippet", "ast-id", "ethdebug"]
},
Expand Down Expand Up @@ -770,7 +772,8 @@ The table below details all currently available experimental features.
+-----------------------+--------------------------+------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
| Non-mainnet EVMs | ``evm`` | yes | ``--evm-version <version name>`` |
+-----------------------+--------------------------+------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
| Ethdebug | ``ethdebug`` | no | ``--ethdebug-resources``, ``--ethdebug-compilation``, ``--ethdebug-program``, ``--ethdebug-program-runtime``, ``--debug-info ethdebug`` |
| Ethdebug | ``ethdebug`` | no | ``--ethdebug-resources``, ``--ethdebug-compilation``, ``--ethdebug-program``, ``--ethdebug-program-runtime``, |
| | | | ``--debug-info ast-id,ethdebug`` |
+-----------------------+--------------------------+------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
| | | no | ``--yul-cfg-json`` |
| SSA CFG + ``ssa-cfg`` +------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
Expand Down
15 changes: 10 additions & 5 deletions libevmasm/Ethdebug.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,7 +171,7 @@ schema::materials::Compilation materialCompilation(std::vector<Source> const& _s

} // anonymous namespace

Json ethdebug::program(std::string_view _name, unsigned _sourceID, Assembly const& _assembly, LinkerObject const& _linkerObject)
Json ethdebug::program(std::string_view _name, unsigned _sourceID, Assembly const& _assembly, LinkerObject const& _linkerObject, std::optional<schema::program::Context> _programContext)
{
return schema::Program{
.compilation = std::nullopt,
Expand All @@ -186,17 +186,22 @@ Json ethdebug::program(std::string_view _name, unsigned _sourceID, Assembly cons
}
},
.environment = _assembly.isCreation() ? schema::Program::Environment::CREATE : schema::Program::Environment::CALL,
.context = std::nullopt,
.context = std::move(_programContext),
.instructions = programInstructions(_assembly, _linkerObject, _sourceID)
};
}

Json ethdebug::resources(std::vector<Source> const& _sources, std::string_view _version)
Json ethdebug::resources(
std::vector<Source> const& _sources,
std::string_view _version,
Json _types,
Json _pointers
)
{
schema::info::Resources result;
result.compilation = materialCompilation(_sources, _version);
result.types = Json::object();
result.pointers = Json::object();
result.types = std::move(_types);
result.pointers = std::move(_pointers);
return result;
}

Expand Down
18 changes: 16 additions & 2 deletions libevmasm/Ethdebug.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,11 @@
#include <libsolutil/JSON.h>

#include <libevmasm/Assembly.h>
#include <libevmasm/EthdebugSchema.h>
#include <libevmasm/LinkerObject.h>

#include <optional>

namespace solidity::evmasm::ethdebug
{

Expand All @@ -35,10 +38,21 @@ struct Source
};

// returns ethdebug/format/program.
Json program(std::string_view _name, unsigned _sourceID, Assembly const& _assembly, LinkerObject const& _linkerObject);
Json program(
std::string_view _name,
unsigned _sourceID,
Assembly const& _assembly,
LinkerObject const& _linkerObject,
std::optional<schema::program::Context> _programContext = std::nullopt
);

// returns ethdebug/format/info/resources
Json resources(std::vector<Source> const& _sources, std::string_view _version);
Json resources(
std::vector<Source> const& _sources,
std::string_view _version,
Json _types = Json::object(),
Json _pointers = Json::object()
);

// returns the 'compilation' object from ethdebug/format/info/resources
Json compilation(std::vector<Source> const& _sources, std::string_view _version);
Expand Down
8 changes: 7 additions & 1 deletion libevmasm/EthdebugSchema.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,9 @@ void schema::program::to_json(Json& _json, Context::Variable const& _contextVari
{
auto const numProperties =
_contextVariable.identifier.has_value() +
_contextVariable.declaration.has_value();
_contextVariable.declaration.has_value() +
_contextVariable.type.has_value() +
_contextVariable.pointer.has_value();
solRequire(numProperties >= 1, EthdebugException, "Context variable has no properties.");
if (_contextVariable.identifier)
{
Expand All @@ -111,6 +113,10 @@ void schema::program::to_json(Json& _json, Context::Variable const& _contextVari
}
if (_contextVariable.declaration)
_json["declaration"] = *_contextVariable.declaration;
if (_contextVariable.type)
_json["type"] = *_contextVariable.type;
if (_contextVariable.pointer)
_json["pointer"] = *_contextVariable.pointer;
}

void schema::program::to_json(Json& _json, Context const& _context)
Expand Down
6 changes: 4 additions & 2 deletions libevmasm/EthdebugSchema.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,8 +123,10 @@ struct Context
{
std::optional<std::string> identifier;
std::optional<materials::SourceRange> declaration;
// TODO: type
// TODO: pointer according to ethdebug/format/spec/pointer
// ethdebug/format/type/specifier: a full type representation or an { "id": ... } reference.
std::optional<Json> type;
// ethdebug/format/pointer: a region or collection describing where the value lives.
std::optional<Json> pointer;
Comment on lines -126 to +129

@cameel cameel Sep 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer if these weren't just JSON blobs but proper data structures. Once the input is validated, we should be able to rely on the type system to provide some constraints to prevent mistakes.

Not sure why they were defined as Json in Resources below in the first place, but I think this is something we should change.

};

std::optional<materials::SourceRange> code;
Expand Down
6 changes: 6 additions & 0 deletions liblangutil/CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,12 @@ set(sources
Scanner.cpp
Scanner.h
CharStreamProvider.h
SemanticDebugData.h
SemanticDebugDataAnalysis.cpp
SemanticDebugDataAnalysis.h
SemanticDebugDataSerialization.cpp
SemanticDebugDataSerialization.h
SemanticDebugDataTable.h
SemVerHandler.cpp
SemVerHandler.h
SourceLocation.h
Expand Down
Loading
Loading