feat(fw): add eest utils and improve user repo init experience

.github/workflows/fixtures.yaml

@@ -17,13 +17,11 @@ jobs:
           - name: 'fixtures'
             evm-type: 'main'
             fill-params: ''
-            solc: '0.8.21'
-            python: '3.11'
+            python: '3.12'
           - name: 'fixtures_develop'
             evm-type: 'develop'
             fill-params: '--until=Cancun'
-            solc: '0.8.21'
-            python: '3.11'
+            python: '3.12'
     steps:
       - uses: actions/checkout@v3
         with:
@@ -36,21 +34,11 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python }}
-      - name: Install solc compiler
-        shell: bash
-        run: |
-          if [ "$RUNNER_OS" == "Linux" ]; then PLATFORM="linux-amd64"; else PLATFORM="macosx-amd64"; fi
-          RELEASE_NAME=$(curl https://binaries.soliditylang.org/${PLATFORM}/list.json | jq -r --arg SOLC_VERSION "${{ matrix.solc }}" '.releases[$SOLC_VERSION]')
-          wget -O $GITHUB_WORKSPACE/bin/solc https://binaries.soliditylang.org/${PLATFORM}/$RELEASE_NAME
-          chmod a+x $GITHUB_WORKSPACE/bin/solc
-          echo $GITHUB_WORKSPACE/bin >> $GITHUB_PATH
       - name: Run fixtures fill
         shell: bash
         run: |
-          pip install --upgrade pip
-          python -m venv env
+          python src/entry_points/eest_utils.py init
           source env/bin/activate
-          pip install -e .
           fill ${{ matrix.fill-params }}
       - name: Create fixtures info file
         shell: bash

.github/workflows/test.yaml → .github/workflows/tox.yaml

@@ -10,22 +10,18 @@ jobs:
         include:
           - os: ubuntu-latest
             python: '3.10'
-            solc: '0.8.20'
-            evm-type: 'main'
-            tox-cmd: 'tox run-parallel --parallel-no-spinner'
-          - os: ubuntu-latest
-            python: '3.12'
-            solc: '0.8.23'
             evm-type: 'main'
             tox-cmd: 'tox run-parallel --parallel-no-spinner'
           - os: ubuntu-latest
             python: '3.11'
-            solc: '0.8.21'
             evm-type: 'develop'
             tox-cmd: 'tox -e tests-develop'
+          - os: ubuntu-latest
+            python: '3.12'
+            evm-type: 'main'
+            tox-cmd: 'tox run-parallel --parallel-no-spinner'
           - os: macos-latest
             python: '3.11'
-            solc: '0.8.22'
             evm-type: 'main'
             tox-cmd: 'tox run-parallel --parallel-no-spinner'
     steps:
@@ -41,13 +37,6 @@ jobs:
         with:
           python-version: ${{ matrix.python }}
           allow-prereleases: true
-      - name: Install solc compiler
-        run: |
-          if [ "$RUNNER_OS" == "Linux" ]; then PLATFORM="linux-amd64"; else PLATFORM="macosx-amd64"; fi
-          RELEASE_NAME=$(curl https://binaries.soliditylang.org/${PLATFORM}/list.json | jq -r --arg SOLC_VERSION "${{ matrix.solc }}" '.releases[$SOLC_VERSION]')
-          wget -O $GITHUB_WORKSPACE/bin/solc https://binaries.soliditylang.org/${PLATFORM}/$RELEASE_NAME
-          chmod a+x $GITHUB_WORKSPACE/bin/solc
-          echo $GITHUB_WORKSPACE/bin >> $GITHUB_PATH
       - name: Setup Tools/Dependencies Ubuntu
         if: runner.os == 'Linux'
         run: |

README.md

@@ -82,34 +82,20 @@ The following requires a Python 3.10, 3.11 or 3.12 installation.
 
 ### Quick Start
 
-This guide installs stable versions of the required external (go-ethereum) `evm` and `solc` executables and will only enable generation of test fixtures for features deployed to mainnet. In order to generate fixtures for features under active development, you can follow the steps below and then follow the [additional steps in the online doc](https://ethereum.github.io/execution-spec-tests/getting_started/executing_tests_dev_fork/).
+This guide installs stable versions of the required external (go-ethereum) `evm` executable and will only enable generation of test fixtures for features deployed to mainnet. In order to generate fixtures for features under active development, you can follow the steps below and then follow the [additional steps in the online doc](https://ethereum.github.io/execution-spec-tests/getting_started/executing_tests_dev_fork/).
 
-1. Ensure go-ethereum's `evm` tool and `solc` ([0.8.20](https://github.com/ethereum/solidity/releases/tag/v0.8.20), [0.8.21](https://github.com/ethereum/solidity/releases/tag/v0.8.21), [0.8.22](https://github.com/ethereum/solidity/releases/tag/v0.8.22), [0.8.23](https://github.com/ethereum/solidity/releases/tag/v0.8.23)  supported) are in your path. Either build the required versions, or alternatively:
+1. Ensure `go-ethereum`'s `evm` tool is in your path. Either build the required version from source, or alternatively install the evm directly using the [geth installation doc](https://geth.ethereum.org/docs/getting-started/installing-geth#ubuntu-via-ppas). Help for other platforms is available in the [execution-spec-tests online doc](https://ethereum.github.io/execution-spec-tests/getting_started/quick_start/).
+
+2. Clone the [execution-spec-tests](https://github.com/ethereum/execution-spec-tests) repo and install its dependencies and additional entry points. Note the virtual environment is a requirement, as the `solc` dependency is self-contained with the venv.
 
     ```console
-    sudo add-apt-repository -y ppa:ethereum/ethereum
-    sudo apt-get update
-    sudo apt-get install ethereum solc
+    git clone https://github.com/ethereum/execution-spec-tests
+    cd execution-spec-tests
+    python src/entry_points/eest_utils.py init
+    source venv/bin/activate
     ```
 
-    More help:
-
-    - [geth installation doc](https://geth.ethereum.org/docs/getting-started/installing-geth#ubuntu-via-ppas).
-    - [solc installation doc](https://docs.soliditylang.org/en/latest/installing-solidity.html#linux-packages).
-
-    Help for other platforms is available in the [online doc](https://ethereum.github.io/execution-spec-tests/getting_started/quick_start/).
-
-2. Clone the [execution-spec-tests](https://github.com/ethereum/execution-spec-tests) repo and install its dependencies (it's recommended to use a virtual environment for the installation):
-
-   ```console
-   git clone https://github.com/ethereum/execution-spec-tests
-   cd execution-spec-tests
-   python3 -m venv ./venv/
-   source ./venv/bin/activate
-   pip install -e '.[docs,lint,test]'
-   ```
-
-3. Verify the installation:
+3. Verify the installation of the `fill` command:
     1. Explore test cases:
 
        ```console
@@ -136,6 +122,14 @@ This guide installs stable versions of the required external (go-ethereum) `evm`
            head fixtures/berlin/eip2930_access_list/acl/access_list.json
            ```
 
+## Useful Commands
+
+After installing the execution-spec-tests framework, our repo specific command line tool can be used for convenient utilities:
+
+- `eest reset`: Performs a clean up of the repo, by removing all generated files and folders, then re-initializes and installs all required packages & dependencies (removes the virtual environment).
+- `eest clean`: Cleans up and removes all generated folders and files (doesn't remove the virtual environment).
+- `eest init`: Initializes the repo by installing all the relevant packages & dependencies (equivalent to running `python src/entry_points/eest_utils.py init` as before).
+
 ## Usage
 
 More information on how to obtain and consume the [released test fixtures](https://github.com/ethereum/execution-spec-tests/releases) can be found in the [documentation](https://ethereum.github.io/execution-spec-tests/main/consuming_tests/).

docs/CHANGELOG.md

@@ -9,7 +9,6 @@ Test fixtures for use by clients are available for each release on the [Github r
 ### 🧪 Test Cases
 
 - 🐞 Dynamic create2 collision from different transactions same block ([#430](https://github.com/ethereum/execution-spec-tests/pull/430)).
-
 - 🐞 Fix beacon root contract deployment tests so the account in the pre-alloc is not empty ([#425](https://github.com/ethereum/execution-spec-tests/pull/425)).
 
 ### 🛠️ Framework
@@ -22,6 +21,8 @@ Test fixtures for use by clients are available for each release on the [Github r
 - 🔀 Locally calculate state root for the genesis blocks in the blockchain tests instead of calling t8n ([#450](https://github.com/ethereum/execution-spec-tests/pull/450)).
 - 🐞 Fix bug that causes an exception during test collection because the fork parameter contains `None` ([#452](https://github.com/ethereum/execution-spec-tests/pull/452)).
 - ✨ The `_info` field in the test fixtures now contains a `hash` field, which is the hash of the test fixture, and a `hasher` script has been added which prints and performs calculations on top of the hashes of all fixtures (see `hasher -h`) ([#454](https://github.com/ethereum/execution-spec-tests/pull/454)).
+- ✨ Adds an `eest` entry point for common EEST commands and utilities, including initialization, clean up and repo resets ([#461](https://github.com/ethereum/execution-spec-tests/pull/461)).
+- 🔀 Removes `solc` as a dependency, utilizing `solc-select` to contain all `solc` versions within the python virtual environment ([#461](https://github.com/ethereum/execution-spec-tests/pull/461)).
 
 ### 🔧 EVM Tools
 
@@ -30,6 +31,11 @@ Test fixtures for use by clients are available for each release on the [Github r
 - 🐞 Fix deprecation warnings due to outdated config in recommended VS Code project settings ([#420](https://github.com/ethereum/execution-spec-tests/pull/420)).
 - 🐞 Fix typo in the selfdestruct revert tests module ([#421](https://github.com/ethereum/execution-spec-tests/pull/421)).
 
+### 💥 Breaking Changes
+
+- Windows users must now use Windows Subsystem for Linux (WSL) to work with EEST.
+- As `solc` is now deprecated as a dependency and self contained within the repo initialization, support will no longer be provided for users not using virtual environments.
+
 ## [v2.1.0](https://github.com/ethereum/execution-spec-tests/releases/tag/v2.1.0) - 2024-01-29: 🐍🏖️ Cancun
 
 Release [v2.1.0](https://github.com/ethereum/execution-spec-tests/releases/tag/v2.1.0) primarily fixes a small bug introduced within the previous release where transition forks are used within the new `StateTest` format. This was highlighted by @chfast within #405 (https://github.com/ethereum/execution-spec-tests/issues/405), where the fork name `ShanghaiToCancunAtTime15k` was found within state tests.

docs/getting_started/quick_start.md

@@ -1,62 +1,38 @@
 # Quick Start
 
 !!! info "Testing features under active development"
-    The EVM features under test must be implemented in the `evm` tool and `solc` executables that are used by the execution-spec-tests framework. The following guide installs stable versions of these tools.
+    The EVM features under test must be implemented in the `evm` tool used by the execution-spec-tests framework. The following guide installs stable versions of these tools.
 
     To test features under active development, start with this base configuration and then follow the steps in [executing tests for features under development](./executing_tests_dev_fork.md). 
 
 The following requires a Python 3.10, 3.11 or 3.12 installation.
 
-1. Ensure `go-ethereum`'s `evm` tool and `solc` ([0.8.20](https://github.com/ethereum/solidity/releases/tag/v0.8.20), [0.8.21](https://github.com/ethereum/solidity/releases/tag/v0.8.21), [0.8.22](https://github.com/ethereum/solidity/releases/tag/v0.8.22), [0.8.23](https://github.com/ethereum/solidity/releases/tag/v0.8.23)  supported) are in your path. Either build the required versions, or alternatively:
+1. Ensure `go-ethereum`'s `evm` tool is in your path. Either build the required versions, or alternatively:
 
     === "Ubuntu"
 
-          ```console
-          sudo add-apt-repository -y ppa:ethereum/ethereum
-          sudo apt-get update
-          sudo apt-get install ethereum solc
-          ```
-          More help:
-
-          - [geth installation doc](https://geth.ethereum.org/docs/getting-started/installing-geth#ubuntu-via-ppas).
-          - [solc installation doc](https://docs.soliditylang.org/en/latest/installing-solidity.html#linux-packages).
+         - Install the geth evm using the [Ubuntu installation doc](https://geth.ethereum.org/docs/getting-started/installing-geth#ubuntu-via-ppas).
 
     === "macOS"
 
-          ```console
-          brew update
-          brew upgrade
-          brew tap ethereum/ethereum
-          brew install ethereum solidity
-          ```
-          More help:
-
-          - [geth installation doc](https://geth.ethereum.org/docs/getting-started/installing-geth#macos-via-homebrew).
-          - [solc installation doc](https://docs.soliditylang.org/en/latest/installing-solidity.html#macos-packages).
+         - Install the geth evm using the [macOS installation doc](https://geth.ethereum.org/docs/getting-started/installing-geth#macos-via-homebrew).
 
     === "Windows"
 
-          Binaries available here:
-
-          - [geth](https://geth.ethereum.org/downloads) (binary or installer).
-          - [solc](https://github.com/ethereum/solidity/releases).
-
-          More help:
+          - Execution-spec-tests doesn't fully support the Windows OS natively, however Windows Subsystem for Linux (WSL) can be used as a stable alternative.
+          - For those unfamiliar with WSL it's recommended to follow this [tutorial](https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-vscode) to develop from the WSL environment alongside VS code.
+          - Assuming Ubuntu is the Linux distribution within WSL please follow the geth [Ubuntu installation doc](https://geth.ethereum.org/docs/getting-started/installing-geth#ubuntu-via-ppas).
 
-          - [geth installation doc](https://geth.ethereum.org/docs/getting-started/installing-geth#windows).
-          - [solc static binaries doc](https://docs.soliditylang.org/en/latest/installing-solidity.html#static-binaries).
-
-2. Clone the [execution-spec-tests](https://github.com/ethereum/execution-spec-tests) repo and install its dependencies (it's recommended to use a virtual environment for the installation):
+2. Clone the [execution-spec-tests](https://github.com/ethereum/execution-spec-tests) repo and install its dependencies and additional entry points. Note the virtual environment is a requirement, as the `solc` dependency is self-contained.
 
     ```console
     git clone https://github.com/ethereum/execution-spec-tests
     cd execution-spec-tests
-    python3 -m venv ./venv/
-    source ./venv/bin/activate
-    pip install -e '.[docs,lint,test]'
+    python src/entry_points/eest_utils.py init
+    source venv/bin/activate
     ```
 
-3. Verify installation:
+3. Verify the installation of the `fill` command:
     1. Explore test cases:
 
         ```console
@@ -87,9 +63,17 @@ The following requires a Python 3.10, 3.11 or 3.12 installation.
             head fixtures/blockchain_tests/berlin/eip2930_access_list/acl/access_list.json
             ```
 
+## Useful Commands
+
+After installing the execution-spec-tests (EEST) framework, our repo specific command line tool can be used for convenient utilities:
+
+- `eest reset`: Performs a clean up of the repo, by removing all generated files and folders, then re-initializes and installs all required packages & dependencies (removes the virtual environment).
+- `eest clean`: Cleans up and removes all generated folders and files (doesn't remove the virtual environment).
+- `eest init`: Initializes the repo by installing all the relevant packages & dependencies (equivalent to running `python src/entry_points/eest_utils.py init` as before).
+
 ## Next Steps
 
-1. Learn [useful command-line flags](./executing_tests_command_line.md).
+1. Learn [useful fill command-line flags](./executing_tests_command_line.md).
 2. [Execute tests for features under development](./executing_tests_dev_fork.md) via the `--fork` flag.
-3. _Optional:_ [Configure VS Code](./setup_vs_code.md) to auto-format Python code and [execute tests within VS Code](./executing_tests_vs_code.md#executing-and-debugging-test-cases).
+3. _Recommended:_ [Configure VS Code](./setup_vs_code.md) to auto-format Python code and [execute tests within VS Code](./executing_tests_vs_code.md#executing-and-debugging-test-cases).
 4. Implement a new test case, see [Writing Tests](../writing_tests/index.md).

setup.cfg

@@ -33,6 +33,7 @@ install_requires =
     coincurve>=18.0.0,<19
     trie==2.1.1
     semver==3.0.1
+    solc-select>=1.0.4
 
 [options.package_data]
 ethereum_test_tools =
@@ -46,6 +47,7 @@ evm_transition_tool =
 console_scripts =
     fill = entry_points.fill:main
     tf = entry_points.tf:main
+    eest = entry_points.eest_utils:eest
     order_fixtures = entry_points.order_fixtures:main
     pyspelling_soft_fail = entry_points.pyspelling_soft_fail:main
     markdownlintcli2_soft_fail = entry_points.markdownlintcli2_soft_fail:main