Introduce experimental flag/option #16229

nikola-matic · 2025-10-06T12:15:30Z

Under development, don't review yet.

github-actions · 2026-01-06T12:08:01Z

This pull request is stale because it has been open for 14 days with no activity.
It will be closed in 7 days unless the stale label is removed.

libsolidity/interface/StandardCompiler.cpp

clonker · 2026-01-13T10:06:41Z

libsolidity/analysis/SyntaxChecker.cpp

+			m_errorReporter.syntaxError(
+				2816_error,
+				_pragma.location(),
+				"Experimental pragmas can only be used if the experimental mode has been enabled."


It would be good to add a link here to somewhere in the docs where it's detailed how to do that and/or just say that one must specify --experimental or settings.experimental in standard JSON.

Link to this?

Yeah. Generally I think we could do better with our error messages and not only say that something is wrong, but also - if possible at least - say what to do differently. We could say that --experimental or settings.experimental is required to be toggled on depending on input mode and/or link to that, yeah :)

I think it's best to separate the error (which is factually correct about what happened, just not necessarily why) from hints (which are just speculation and may or may no be correct). We should really have some kind of "hint" field in errors.

But for the time being, sure, would not hurt to mention --experimental. I'd avoid direct links though. Links break. IMO it's best to just include some something that is easy to search for, like the name of the feature or the flag. At the same time also to try to make it relatively self-contained so that the user has a fighting change of figuring it out on their own without having to leave the terminal.

test/cmdlineTests/experimental_flag_with_standard_json/args

test/cmdlineTests/standard_cli_import_ast_storage_layout_specifier_missing_expression/args

solc/CommandLineParser.cpp

solc/CommandLineParser.h

nikola-matic · 2026-01-15T17:04:58Z

docs/using-the-compiler.rst

+-----------------------+--------------------------+------------------+-------------------------------------------------------------------+
+| EOF                   | ``eof``                  | yes              | ``--eof-version``                                                 |
+-----------------------+--------------------------+------------------+-------------------------------------------------------------------+
+| Osaka EVM             | ``evm-osaka``            | yes              | ``--evm-version osaka``                                           |


Wait, fusaka fork was in December, no? So this should be removed. I also didn't implement an evm version check for >current.

Hm, not only that, Osaka is our current version; how could I go about testing the implementation?

It wasn't yet released when I created the spec :) Now we have no experimental EVM versions, but you could add Amsterdam already if you want to have one for testing. It's supposed to be ready in half a year, so we can already start preparing.

Also, now that I think about it, we could change the ID here to just evm covering all non-mainnet EVMs. This way we won't have to be all that fine-grained.

cameel · 2026-01-17T00:11:15Z

docs/using-the-compiler.rst

+-----------------------+--------------------------+------------------+-------------------------------------------------------------------+
+| EVM Assembly import   | ``evmasm-import``        | yes              | ``--import-asm-json``                                             |
+-----------------------+--------------------------+------------------+-------------------------------------------------------------------+
+| Generic Solidity      | ``generic-solidity``     | yes              | ``pragma experimental solidity``                                  |


cameel · 2026-01-17T00:16:54Z

docs/using-the-compiler.rst

+| Yul SSA CFG exporter  | ``yul-ssa-cfg-exporter`` | no               | ``--yul-cfg-json``                                                |
+-----------------------+--------------------------+------------------+-------------------------------------------------------------------+
+| SSA CFG codegen       | ``ssa-cfg-codegen``      | yes              | ``--ssa-cfg-codegen`` (not yet on ``develop``)                    |


@clonker Do we actually need two separate flags for this? Like, are we planning to have the exporter stable before the codegen? Or do we need people to be able to export the CFG without enabling the codegen? To me they seem like parts of the same bigger feature.

Also, the docs should be written from the perspective of a release. So if it's not merged into develop, it should not be listed in the docs. It should be added as a part of the PR that introduces the flag.

cameel · 2026-01-17T00:27:48Z

libsolidity/interface/StandardCompiler.cpp


+bool isExperimentalArtifactRequested(Json const& _outputSelection)
+{
+	static std::array<std::string, 3> const experimentalArtifacts{"irAst", "irOptimizedAst", "yulCFGJson"};


What about ethdebug outputs?

cameel · 2026-01-17T00:35:10Z

test/externalTests/ens.sh

    sed -i "s|it\(('Cannot be called if PARENT_CANNOT_CONTROL is burned and is an existing subdomain',\)|it.skip\1|g" test/wrapper/NameWrapper.js

    find . -name "*.sol" -type f -exec sed -i -e 's/^\(\s*\)\(assembly\)/\1\/\/\/ @solidity memory-safe-assembly\n\1\2/' '{}' \;
+    find . -name "*.sol" -type f -exec sed -i '/pragma experimental/d' {} \;


I think we should be more specific in these replacements (in prb-math.py as well). If you're only looking for the ABI coder pragma, specify just that.

cameel · 2026-01-17T00:38:59Z

test/libsolidity/syntaxTests/experimental/builtin/builtin_type_definition.sol

I would consider moving these tests into syntaxTests/coreSolidity or something like that. Otherwise we'll likely end up with tests for random experimental features landing here.

Though that's probably best done after this PR is merged not to make the diff bigger.

Or maybe it does not matter if you're going to remove all of that in the near future...

cameel · 2026-01-17T00:42:29Z

Note that there is an issue for this: #16123. Please include it in the description and also check if the PR covers everything.

cameel · 2026-01-17T00:49:18Z

Changelog.md


 Compiler Features:
+* Commandline Interface: Introduce `--experimental` flag required for toggling the experimental mode.
+* Standard JSON Interface: Introduce `settings.experimental` setting required for toggling the experimental mode.


I wonder if it wouldn't be a good idea to make a prerelease once we merge this PR.

I imagine that this kind of change could cause some disruption for those who were relying on experimental features but shouldn't have.

Should we also mention (as a separate entry) that some features now require the experimental mode (and list those features)?. If we do make a prerelease that will be the primary source of information about this.

cameel · 2026-01-17T01:26:16Z

docs/using-the-compiler.rst

+Experimental mode has been introduced as of version 0.8.34 as an additional safeguard when using experimental features.
+Prior to version 0.8.34, all experimental features not requiring an explicit ``pragma experimental ...`` in source file(s)
+were freely available to be used without any additional safeguards. Given that experimental features are sparsely documented,
+if at all, often not adequately tested, and thus not intended for production use, we decided to add  the ``--experimental``
+flag to the command line interface, and the analogous ``settings.experimental`` boolean setting to the Standard JSON interface.
+Going forward, usage of any experimental feature will require the experimental mode to be toggled.


This feels more like something that would go into the release notes. In docs we usually just focus on describing the current state rather than the future and the past.

It's also missing some information. Here's my attempt at documenting it:

Suggested change

Experimental mode has been introduced as of version 0.8.34 as an additional safeguard when using experimental features.

Prior to version 0.8.34, all experimental features not requiring an explicit ``pragma experimental ...`` in source file(s)

were freely available to be used without any additional safeguards. Given that experimental features are sparsely documented,

if at all, often not adequately tested, and thus not intended for production use, we decided to add the ``--experimental``

flag to the command line interface, and the analogous ``settings.experimental`` boolean setting to the Standard JSON interface.

Going forward, usage of any experimental feature will require the experimental mode to be toggled.

Some language and compiler features included in stable releases are not themselves considered stable.

They are sparsely documented, if at all, often not adequately tested, and thus not yet intended for production use.

In many cases it is possible to develop a big feature incrementally, with each iteration being already stable.

Sometimes, however, it is preferable to start with a prototype and stabilize it over multiple releases, while receiving feedback from users.

To prevent accidental use, such features can be only accessed by enabling the experimental mode.

There are no backwards compatibility guarantees for experimental features.

They are subject to change in breaking ways in non-breaking releases of the compiler.

Only major changes affecting them are recorded in the changelog.

To enable the experimental mode, use the ``--experimental`` flag on the command line,

or the analogous ``settings.experimental`` boolean setting in the Standard JSON input.

Note that if the feature has any impact on the generated bytecode, this fact is recorded in the metadata:

- ``experimental`` flag in CBOR metadata is set to ``true``,

- ``settings.experimental`` in JSON metadata is set to ``true``,

- ``experimentalFeatures`` field in JSON metadata includes the IDs of all the experimental features which may have affected the bytecode.

.. note::

Prior to version 0.8.34, most of the experimental features were usable without any extra safeguards.

Some were gated behind ``pragma experimental``, but this was not done consistently.

The information about them was also only recorded in CBOR metadata and even then not always.

The main goal of the experimental mode is to systematize this and make users fully when they are relying on features which are unfinished or not production-ready.

I'd also include some links, e.g. to changelog, metadata, section on pragmas.

Actually, I don't think the PR adds the metadata info. Full extent of it could be done separately, but we need to at least record at the use of --experimental so that the bytecode can be reproduced based on from metadata.

nikola-matic force-pushed the introduce-experimental-flag branch 5 times, most recently from 1beb509 to ba48a91 Compare October 9, 2025 13:17

nikola-matic force-pushed the introduce-experimental-flag branch 4 times, most recently from fd70f82 to 98cad7c Compare October 21, 2025 09:40

github-actions bot added the stale The issue/PR was marked as stale because it has been open for too long. label Nov 4, 2025

argotorg deleted a comment from github-actions bot Nov 4, 2025

nikola-matic removed the stale The issue/PR was marked as stale because it has been open for too long. label Nov 4, 2025

github-actions bot added the stale The issue/PR was marked as stale because it has been open for too long. label Nov 19, 2025

nikola-matic removed the stale The issue/PR was marked as stale because it has been open for too long. label Nov 19, 2025

argotorg deleted a comment from github-actions bot Nov 19, 2025

nikola-matic force-pushed the introduce-experimental-flag branch 3 times, most recently from 5c5a463 to 2518378 Compare November 20, 2025 11:55

github-actions bot added the stale The issue/PR was marked as stale because it has been open for too long. label Dec 4, 2025

nikola-matic removed the stale The issue/PR was marked as stale because it has been open for too long. label Dec 4, 2025

argotorg deleted a comment from github-actions bot Dec 4, 2025

nikola-matic mentioned this pull request Dec 8, 2025

ABIEncoderV2 deprecation foundry-rs/forge-std#766

Closed

nikola-matic force-pushed the introduce-experimental-flag branch from 2518378 to 83b670d Compare December 8, 2025 09:43

github-actions bot added the stale The issue/PR was marked as stale because it has been open for too long. label Dec 22, 2025

nikola-matic removed the stale The issue/PR was marked as stale because it has been open for too long. label Dec 22, 2025

argotorg deleted a comment from github-actions bot Dec 22, 2025

github-actions bot added the stale The issue/PR was marked as stale because it has been open for too long. label Jan 6, 2026

clonker removed the stale The issue/PR was marked as stale because it has been open for too long. label Jan 6, 2026

nikola-matic force-pushed the introduce-experimental-flag branch from 83b670d to 17c3e0e Compare January 6, 2026 12:22

clonker reviewed Jan 13, 2026

View reviewed changes

nikola-matic force-pushed the introduce-experimental-flag branch 8 times, most recently from 6c4e799 to 136bd18 Compare January 15, 2026 16:37

nikola-matic marked this pull request as ready for review January 15, 2026 16:57

nikola-matic commented Jan 15, 2026

View reviewed changes

nikola-matic added 6 commits January 16, 2026 14:38

Introduce experimental flag/option

9a2a1ea

Cover experimental pragmas and tests

bfbe66e

Introduce experimental option in standard JSON

6101b5f

Documentation for experimental mode

997dabd

Changelog

a86bf20

Remove experimental pragma from external tests

8f8a1dc

nikola-matic force-pushed the introduce-experimental-flag branch from 136bd18 to 8f8a1dc Compare January 16, 2026 13:38

cameel added this to the 0.8.34 milestone Jan 16, 2026

cameel reviewed Jan 17, 2026

View reviewed changes

	\| Generic Solidity \| ``generic-solidity`` \| yes \| ``pragma experimental solidity`` \|
	\| Core Solidity \| ``core-solidity`` \| yes \| ``pragma experimental solidity`` \|

-Experimental mode has been introduced as of version 0.8.34 as an additional safeguard when using experimental features.
-Prior to version 0.8.34, all experimental features not requiring an explicit ``pragma experimental ...`` in source file(s)
-were freely available to be used without any additional safeguards. Given that experimental features are sparsely documented,
-if at all, often not adequately tested, and thus not intended for production use, we decided to add  the ``--experimental``
-flag to the command line interface, and the analogous ``settings.experimental`` boolean setting to the Standard JSON interface.
-Going forward, usage of any experimental feature will require the experimental mode to be toggled.
+Some language and compiler features included in stable releases are not themselves considered stable.
+They are sparsely documented, if at all, often not adequately tested, and thus not yet intended for production use.
+In many cases it is possible to develop a big feature incrementally, with each iteration being already stable.
+Sometimes, however, it is preferable to start with a prototype and stabilize it over multiple releases, while receiving feedback from users.
+To prevent accidental use, such features can be only accessed by enabling the experimental mode.
+There are no backwards compatibility guarantees for experimental features.
+They are subject to change in breaking ways in non-breaking releases of the compiler.
+Only major changes affecting them are recorded in the changelog.
+To enable the experimental mode, use the ``--experimental`` flag on the command line,
+or the analogous ``settings.experimental`` boolean setting in the Standard JSON input.
+Note that if the feature has any impact on the generated bytecode, this fact is recorded in the metadata:
+- ``experimental`` flag in CBOR metadata is set to ``true``,
+- ``settings.experimental`` in JSON metadata is set to ``true``,
+- ``experimentalFeatures`` field in JSON metadata includes the IDs of all the experimental features which may have affected the bytecode.
+.. note::
+    Prior to version 0.8.34, most of the experimental features were usable without any extra safeguards.
+    Some were gated behind ``pragma experimental``, but this was not done consistently.
+    The information about them was also only recorded in CBOR metadata and even then not always.
+    The main goal of the experimental mode is to systematize this and make users fully when they are relying on features which are unfinished or not production-ready.

Introduce experimental flag/option #16229

Are you sure you want to change the base?

Introduce experimental flag/option #16229

Conversation

nikola-matic commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 6, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cameel Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cameel Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cameel commented Jan 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cameel Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cameel Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nikola-matic commented Oct 6, 2025 •

edited

Loading

cameel Jan 17, 2026 •

edited

Loading

cameel Jan 17, 2026 •

edited

Loading

cameel Jan 17, 2026 •

edited

Loading

cameel Jan 17, 2026 •

edited

Loading