argotorg · djolertrk · May 26, 2026 · May 26, 2026 · May 26, 2026 · May 26, 2026
diff --git a/docs/index.rst b/docs/index.rst
@@ -149,6 +149,7 @@ Contents
    internals/layout_in_calldata.rst
    internals/variable_cleanup.rst
    internals/source_mappings.rst
+   internals/ethdebug_internal_metadata.rst
    internals/optimizer.rst
    metadata.rst
    abi-spec.rst

diff --git a/docs/internals/ethdebug_internal_metadata.rst b/docs/internals/ethdebug_internal_metadata.rst
diff --git a/docs/using-the-compiler.rst b/docs/using-the-compiler.rst
@@ -275,6 +275,17 @@ Input Description
           }
         }
       },
+      // Optional auxiliary inputs.
+      "auxiliaryInput": {
+        // Internal ethdebug semantic data sidecar for Yul input (experimental).
+        // This is the object emitted as the Solidity `irEthdebug` output.
+        "ethdebug": {
+          "format": "solidity-ethdebug-semantic-data",
+          "version": 1,
+          "contractName": "ContractName",
+          "entries": [/* ... */]
+        }
+      },
       // Optional
       "settings":
       {
@@ -391,7 +402,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`; explicitly selecting
+          //   `ethdebug` without `ast-id` is an error. The required pair is automatically enabled when
+          //   an ethdebug output is requested without an explicit `debugInfo` selection.
           // - `*`: Wildcard value that can be used to request all non-experimental components.
           "debugInfo": ["location", "snippet", "ast-id", "ethdebug"]
         },
@@ -444,6 +457,7 @@ Input Description
         //   userdoc - User documentation (natspec)
         //   metadata - Metadata
         //   ir - Yul intermediate representation of the code before optimization
+        //   irEthdebug - Internal ethdebug semantic data sidecar for the Yul IR (experimental)
         //   irAst - AST of Yul intermediate representation of the code before optimization (experimental)
         //   irOptimized - Intermediate representation after optimization
         //   irOptimizedAst - AST of intermediate representation after optimization (experimental)
@@ -602,6 +616,8 @@ Output Description
             "devdoc": {},
             // Intermediate representation before optimization (string)
             "ir": "",
+            // Internal ethdebug semantic data sidecar for Yul (experimental)
+            "irEthdebug": {/* ... */},
             // AST of intermediate representation before optimization
             "irAst":  {/* ... */},
             // Intermediate representation after optimization (string)
@@ -769,7 +785,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``, ``--ir-ethdebug``,        |
+|                       |                          |                  | ``--ethdebug-input``, ``--debug-info ast-id,ethdebug``                                                                                  |
 +-----------------------+--------------------------+------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
 |                       |                          | no               | ``--yul-cfg-json``                                                                                                                      |
 | SSA CFG               + ``ssa-cfg``              +------------------+-----------------------------------------------------------------------------------------------------------------------------------------+

diff --git a/libevmasm/Ethdebug.cpp b/libevmasm/Ethdebug.cpp
@@ -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,
@@ -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;
 }
 

diff --git a/libevmasm/Ethdebug.h b/libevmasm/Ethdebug.h
@@ -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
 {
 
@@ -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);

diff --git a/libevmasm/EthdebugSchema.cpp b/libevmasm/EthdebugSchema.cpp
@@ -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)
 	{
@@ -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)

diff --git a/libevmasm/EthdebugSchema.h b/libevmasm/EthdebugSchema.h
@@ -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;
 	};
 
 	std::optional<materials::SourceRange> code;

diff --git a/liblangutil/CMakeLists.txt b/liblangutil/CMakeLists.txt
@@ -17,6 +17,10 @@ set(sources
 	Scanner.cpp
 	Scanner.h
 	CharStreamProvider.h
+	SemanticDebugData.h
+	SemanticDebugDataSerialization.cpp
+	SemanticDebugDataSerialization.h
+	SemanticDebugDataTable.h
 	SemVerHandler.cpp
 	SemVerHandler.h
 	SourceLocation.h

diff --git a/liblangutil/DebugData.h b/liblangutil/DebugData.h
@@ -18,9 +18,11 @@
 
 #pragma once
 
+#include <liblangutil/SemanticDebugData.h>
 #include <liblangutil/SourceLocation.h>
 #include <optional>
 #include <memory>
+#include <utility>
 
 namespace solidity::langutil
 {
@@ -32,23 +34,27 @@ struct DebugData
 	explicit DebugData(
 		langutil::SourceLocation _nativeLocation = {},
 		langutil::SourceLocation _originLocation = {},
-		std::optional<int64_t> _astID = {}
+		std::optional<int64_t> _astID = {},
+		SemanticDebugData::ConstPtr _semanticDebugData = {}
 	):
 		nativeLocation(std::move(_nativeLocation)),
 		originLocation(std::move(_originLocation)),
-		astID(_astID)
+		astID(_astID),
+		semanticDebugData(std::move(_semanticDebugData))
 	{}
 
 	static DebugData::ConstPtr create(
 		langutil::SourceLocation _nativeLocation,
 		langutil::SourceLocation _originLocation = {},
-		std::optional<int64_t> _astID = {}
+		std::optional<int64_t> _astID = {},
+		SemanticDebugData::ConstPtr _semanticDebugData = {}
 	)
 	{
 		return std::make_shared<DebugData>(
 			std::move(_nativeLocation),
 			std::move(_originLocation),
-			_astID
+			_astID,
+			std::move(_semanticDebugData)
 		);
 	}
 
@@ -65,6 +71,8 @@ struct DebugData
 	langutil::SourceLocation originLocation;
 	/// ID in the (Solidity) source AST.
 	std::optional<int64_t> astID;
+	/// Extended semantic debug data that cannot be represented in Yul comments.
+	SemanticDebugData::ConstPtr semanticDebugData;
 };
 
 } // namespace solidity::langutil