Merge upstream changes

.claude/commands/edit-workflow.md

@@ -13,6 +13,23 @@ uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 - Never use version tags alone (`@v4` is wrong)
 - Local actions (`./.github/actions/*`) are exempt from pinning
 
+## Runner Selection
+
+Self-hosted runners (`[self-hosted-ghr, size-*-x64]`) are a shared EF devops
+pool — reserve them for jobs that need the capacity. Non-critical or low-load
+jobs belong on GitHub-hosted runners (`ubuntu-latest`), which also avoids a
+provisioning wait (~2.5 min) if the self-hosted warm pool is exhausted.
+
+- **Pattern**: lightweight job (short runtime, no heavy parallelism) →
+  `ubuntu-latest` (e.g. `spec-tools` in #3177).
+- **Anti-pattern**: defaulting a quick gate, lint, or cache-restore job to
+  `size-xl-x64` "to be safe".
+- **Exception**: a job may need self-hosted for reasons other than load, e.g.
+  Docker Hub pulls from GHR egress IPs to dodge per-IP rate limits (#3185
+  keeps push runs self-hosted while PR runs use `ubuntu-latest`).
+
+If unsure which runner a job needs, flag it and ask instead of guessing.
+
 ## Validation
 
 Run `just lint-actions` before committing to validate YAML syntax and structure.

.claude/commands/fill-tests.md

@@ -19,7 +19,7 @@ uv run fill --collect-only tests/                      # Dry run: list tests wit
 - `-k "pattern"` — filter tests by name pattern
 - `-m "marker"` — filter by pytest marker (e.g. `-m state_test`, `-m blockchain_test`)
 - `-n auto --maxprocesses N` — parallel execution (use `--dist=loadgroup`)
-- `--evm-bin PATH` — specify t8n tool (default: `ethereum-spec-evm-resolver`)
+- `--evm-bin PATH` — t8n tool; defaults to the in-repo EELS Python spec (`src/ethereum/`)
 - `--verify-fixtures` — verify generated fixtures against geth blocktest
 - `--generate-all-formats` — generate all fixture formats (2-phase)
 
@@ -37,19 +37,9 @@ uv run fill --collect-only tests/                      # Dry run: list tests wit
 
 ## Benchmark Tests
 
-- Must use `-m benchmark` — benchmark tests are excluded by default
-- Require evmone as backend: `--evm-bin=evmone-t8n`
-- Default benchmark fork is Prague (set in `tests/benchmark/conftest.py`)
-- Gas values mode: `--gas-benchmark-values 1,10,100` (values in millions of gas)
-- Fixed opcode count mode: `--fixed-opcode-count 1,10,100` (values in thousands)
-- These two modes are **mutually exclusive**
-- Use `--generate-pre-alloc-groups` for stateful benchmarks
-
-## Static Tests (Legacy)
-
-- `uv run fill --fill-static-tests tests/static/` — fills YAML/JSON fillers from `ethereum/tests`
-- Legacy only — do NOT add new static fillers. Use Python tests instead
-- Useful to check if spec changes broke how legacy tests fill
+- Excluded from a broad `tests/` run: include them by targeting a `tests/benchmark/...` path, or add `--include-benchmark` when also collecting `tests/`.
+- Pick a mode (mutually exclusive): `--gas-benchmark-values 1,10,100` (millions of gas) or `--fixed-opcode-count 1,10,100` (thousands). These parametrize the tests, e.g. `...[fork_Prague-blockchain_test-benchmark-gas-value_1M]`.
+- Backend is optional: omitting `--evm-bin` runs the slow in-repo EELS Python spec; `--evm-bin=evmone` or `--evm-bin=evm` (geth, used by `just bench-gas`) are faster.
 
 ## Fixture Formats
 

.claude/commands/implement-eip.md

@@ -28,10 +28,22 @@ Each fork lives at `src/ethereum/forks/<fork_name>/`. Explore the latest fork di
 ## Adding a New Opcode
 
 1. Add to `Ops` enum in `vm/instructions/__init__.py` with hex value
-2. Implement function in appropriate `vm/instructions/<category>.py` — follows pattern: STACK → GAS (`charge_gas`) → OPERATION → PROGRAM COUNTER
+2. Implement function in appropriate `vm/instructions/<category>.py` — follows pattern: STACK → GAS (`charge_gas`) → OPERATION → PROGRAM COUNTER. Opcodes that touch state use the staged gas labels — see "Gas Handling" below.
 3. Register in `op_implementation` dict in `vm/instructions/__init__.py`
 4. Add gas constant in `vm/gas.py` if needed
 
+## Gas Handling
+
+Recent forks meter two gas dimensions: execution gas and state gas (for durable state growth). Key rules:
+
+1. Gas constants and calculations go in `vm/gas.py`; a frame's mutable gas state lives on `Evm.gas_meter`.
+2. Extend the named helper vocabulary (`charge_*`, `credit_*`, `restore_*`, `withhold_*`, ...) instead of doing gas arithmetic by hand at call sites; encode each helper's invariant as an assert.
+3. State gas is charged by the frame whose opcode causes the creation, before the child's execution-gas share is withheld; the whole reservoir passes to the child.
+4. A failing frame settles its own meter before returning, so parents incorporate children unconditionally.
+5. Opcodes that touch state use labeled stages, with all charging before the operation: `GAS (STATE-INDEPENDENT)` → `STATE ACCESS (STATE-DEPENDENT GAS)` → `STATE GAS` → `CHILD GRANT` → `OPERATION`. Simple opcodes keep the bare `GAS` marker. `generic_call`/`generic_create` contain no pricing; they run the child lifecycle: `PREFLIGHT` → `DESTINATION ACCESS` → `CHILD GRANT` → `DISPATCH` → `OUTCOME`.
+6. Avoid "frame" in gas identifiers (a future EIP claims the term); when a name diverges from the spec's variable name, cross-reference the spec name in the docstring.
+7. A gas change is behavior-preserving only if the relative order of every charge, check, and trace event is unchanged; verify with the gas-related fill tests under `tests/<fork>/`.
+
 ## Adding a New Precompile
 
 1. Define address constant in `vm/precompiled_contracts/__init__.py` using `hex_to_address("0x...")`

.claude/commands/write-test.md

@@ -6,8 +6,9 @@ Conventions and patterns for writing consensus tests. Run this skill before writ
 
 - All test imports come from `execution_testing` — it is the public API
 - Core fixtures: `pre: Alloc` (pre-state builder), `state_test: StateTestFiller`, `blockchain_test: BlockchainTestFiller`, `fork: Fork`
-- Prefer `state_test` for single-tx tests (simpler, avoids block-building false positives); `fill` auto-generates a `blockchain_test` from every `state_test`
-- Use `blockchain_test` only for multi-block scenarios
+- Rule: use `state_test` for single-transaction tests; `fill` auto-derives a `blockchain_test` from each, so no coverage is lost.
+- Exception: use `blockchain_test` when the test needs more than one transaction (a `state_test` holds exactly one) or more than one block (e.g. transaction-ordering or fork-transition tests).
+- Anti-pattern: wrapping one transaction in a `Block` to reach `blockchain_test`. A `state_test` can assert the transaction's gas used and receipt logs (the tx's `expected_receipt=TransactionReceipt(cumulative_gas_used=...)`), reserve state gas (the tx's `state_gas_reservoir=`), and other block-header fields (`blockchain_test_header_verify=Header(...)`) without it.
 
 ## Pre-State Setup
 
@@ -42,8 +43,26 @@ Conventions and patterns for writing consensus tests. Run this skill before writ
 ## Fork-Aware Logic
 
 - `fork >= Cancun` for conditional behavior based on fork
-- `fork.gas_costs()` returns `GasCosts` dataclass with constants like `G_WARM_SLOAD`, `GAS_COLD_ACCOUNT_ACCESS`, `G_BASE`, etc.
-- `fork.transaction_intrinsic_cost_calculator()` for computing tx intrinsic gas
+- `fork.fork_at(timestamp=...)` gives the fork active before/after a transition boundary
+- For gas amounts, see **Gas Cost Expectations** below — prefer framework cost constructs over reading `fork.gas_costs()` constants directly
+
+## Gas Cost Expectations
+
+Never hand-reconstruct a gas amount by summing `fork.gas_costs()` constants (`NEW_ACCOUNT`, `CALL_VALUE`, `COLD_STORAGE_WRITE`, `VERY_LOW`, ...). Re-deriving the schedule duplicates the framework's own calculation and silently breaks when a future fork reprices. Instead:
+
+- **Read the cost off the bytecode under test.** Set the relevant opcode metadata (`account_new`, `value_transfer`, `address_warm`, `key_warm`/`original_value`/`current_value`/`new_value`, `init_code_size`, `code_deposit_size`, `new_memory_size`, ...) and use `bytecode.gas_cost(fork)` (execution + state), `.execution_cost(fork)`, `.state_cost(fork)`, or `.refund(fork)`. Link the exact opcode to the behavior — e.g. `Op.SELFDESTRUCT(account_new=True).state_cost(fork)`.
+- **Transaction-level costs:** `fork.transaction_intrinsic_cost_calculator()`; `fork.transaction_top_frame_state_gas(contract_creation=True)` for the created account's `NEW_ACCOUNT` (under EIP-2780 it is NOT part of the intrinsic — never subtract it from the intrinsic); `fork.transaction_data_floor_cost_calculator()`; `fork.call_value_stipend()`.
+- **A single bare opcode/schedule cost** (e.g. an account-access constant) comes from a metadata-only opcode: `Op.BALANCE.with_metadata(address_warm=False).gas_cost(fork)`.
+- **Fork-transition / cross-fork comparisons:** evaluate the same bytecode or intrinsic at each fork (`before = fork.fork_at(timestamp=...)`, `after = ...`) and compare `before` vs `after` costs — do not compare raw schedule constants.
+- **Do not add "self-check" asserts** that compare a framework-computed value against a `fork.gas_costs()` decomposition of the same fork; they add no coverage over the runtime behavior the test already exercises and only break on repricing.
+- **If the framework cannot express a cost, fix the framework** (wire the opcode into its gas/state map, add an accessor) rather than reconstructing it in the test. If the use case does not support the framework, the framework needs an update.
+- **Exception:** a test whose *subject* is a specific schedule value (e.g. a regression that an opcode's cost is unchanged) may compare a runtime measurement (`CodeGasMeasure`) against `fork.gas_costs().OPCODE_*`. Even then, never hardcode the literal value.
+
+## Transactions
+
+- Rule: omit `gas_limit`. It auto-fills so the transaction executes in full without running out of gas.
+- Exception: set `gas_limit` explicitly for gas-sensitive tests (intrinsic-gas boundaries, OOG, code-deposit limits, or gas metering).
+- Anti-pattern: the `gas_limit=fork.transaction_gas_limit_cap()` boilerplate is now redundant.
 
 ## Exception Testing
 
@@ -56,6 +75,13 @@ Conventions and patterns for writing consensus tests. Run this skill before writ
 - Each EIP directory has `spec.py` with `ReferenceSpec(git_path=..., version=...)` and test files declaring `REFERENCE_SPEC_GIT_PATH` / `REFERENCE_SPEC_VERSION`
 - Use `conftest.py` for shared fixtures within an EIP directory
 
+## Test Docstrings
+
+- Keep the docstring to a short summary of the scenario and the rule it pins — a sentence or two.
+- Do not narrate the implementation: parametrized cases, gas decompositions, and case-by-case outcome walkthroughs are already expressed by the code. Prose restating them goes stale when the test changes and adds review burden.
+- State only what the code cannot show (e.g. why a boundary value is chosen). Prefer a short inline comment at the relevant line over growing the docstring.
+- Never hardcode numeric gas values in docstrings; name the constants instead.
+
 ## Parametrization
 
 - `@pytest.mark.parametrize("name", [pytest.param(val, id="label"), ...])` with descriptive `id=` strings

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,25 +1,17 @@
-## 🗒️ Description
+### Description
 <!-- Brief description of the changes introduced by this PR -->
 <!-- Don't submit this PR if it could expose a mainnet bug, see SECURITY.md in the repo root for details -->
 
-## 🔗 Related Issues or PRs
+### Related Issues or PRs
 <!-- Reference any related issues using the GitHub issue number (e.g., Fixes #123). Default is N/A. -->
 N/A.
 
-## ✅ Checklist
-<!-- Please check off all required items. For those that don't apply remove them accordingly. -->
+### Checklist
+<!-- Please check off all items before marking the PR ready for review. -->
 
-- [ ] All: Ran fast static checks to avoid unnecessary CI fails, see also [Code Standards](https://eest.ethereum.org/main/getting_started/code_standards/) and [Enabling Pre-commit Checks](https://eest.ethereum.org/main/dev/precommit/):
-    ```console
-    just static
-    ```
-- [ ] All: PR title adheres to the [repo standard](https://eest.ethereum.org/main/getting_started/contributing/?h=contri#commit-messages-issue-and-pr-titles) - it will be used as the squash commit message and should start `type(scope):`.
-- [ ] All: Considered updating the online docs in the [./docs/](/ethereum/execution-specs/blob/HEAD/docs/) directory.
-- [ ] All: Set appropriate labels for the changes (only maintainers can apply labels).
-- [ ] Tests: Ran `mkdocs serve` locally and verified the auto-generated docs for new tests in the [Test Case Reference](https://eest.ethereum.org/main/tests/) are correctly formatted.
-- [ ] Tests: For PRs implementing a missed test case, update the [post-mortem document](/ethereum/execution-specs/blob/HEAD/docs/writing_tests/post_mortems.md) to add an entry the list.
-- [ ] Ported Tests: All converted JSON/YML tests from [ethereum/tests](/ethereum/tests) or [tests/static](/ethereum/execution-specs/blob/HEAD/tests/static) have been assigned `@ported_from` marker.
+- [ ] Ran fast static checks to avoid CI fails, see [Code Standards](https://steel.ethereum.foundation/docs/execution-specs/getting_started/code_standards/) & [Verifying Changes](https://steel.ethereum.foundation/docs/execution-specs/getting_started/verifying_changes/): `just static`
+- [ ] PR title has the form `<type>(<area>): <title>`, where `<type>` and `<area>` come from an appropriate [`C-<type>`](https://github.com/ethereum/execution-specs/labels?q=C-), respectively [`A-<area>`](https://github.com/ethereum/execution-specs/labels?q=A-), label. The title should match the target squash commit message.
 
-#### Cute Animal Picture
+### Cute Animal Picture
 
 ![Put a link to a cute animal picture inside the parenthesis-->]()

.github/actions/build-evm-base/action.yaml

@@ -2,48 +2,61 @@ name: 'Build EVM'
 description: 'Resolves and builds the requested EVM binary by name'
 inputs:
   type:
-    description: 'Type of EVM binary to build'
+    description: 'Type of EVM binary to build (key in .github/configs/evm.yaml)'
     required: true
-    default: 'main'
+  repo_override:
+    description: 'Override the repo from evm.yaml (e.g. ethereum/go-ethereum)'
+    required: false
+    default: ''
+  ref_override:
+    description: 'Override the ref/branch/commit from evm.yaml'
+    required: false
+    default: ''
 outputs:
   impl:
     description: "Implementation of EVM binary to build"
     value: ${{ steps.config-evm-reader.outputs.impl }}
   repo:
     description: "Repository to use to build the EVM binary"
-    value: ${{ steps.config-evm-reader.outputs.repo }}
+    value: ${{ steps.resolved.outputs.repo }}
   ref:
     description: "Reference to branch, commit, or tag to use to build the EVM binary"
-    value: ${{ steps.config-evm-reader.outputs.ref }}
+    value: ${{ steps.resolved.outputs.ref }}
   evm-bin:
     description: "Binary name of the evm tool to use"
-    value: ${{ steps.config-evm-impl-config-reader.outputs.evm-bin }}
-  x-dist:
-    description: "Binary name of the evm tool to use"
-    value: ${{ steps.config-evm-impl-config-reader.outputs.x-dist }}
+    value: ${{ steps.config-evm-reader.outputs.evm-bin }}
+  xdist:
+    description: "Number of parallel pytest-xdist workers to use"
+    value: ${{ steps.config-evm-reader.outputs.xdist }}
 runs:
   using: "composite"
   steps:
-    - name: Get the selected EVM version from the .github/configs/evm.yaml
+    - name: Get the selected EVM configuration from .github/configs/evm.yaml
       id: config-evm-reader
       shell: bash
       run: |
         awk "/^${{ inputs.type }}:/{flag=1; next} /^[[:alnum:]]/{flag=0} flag" ./.github/configs/evm.yaml \
         | sed 's/ //g' | sed 's/:/=/g' >> "$GITHUB_OUTPUT"
-    - name: Get the EVM implementation configuration from .github/configs/evm-impl-config.yaml
-      id: config-evm-impl-config-reader
+    - name: Apply repo/ref overrides
+      id: resolved
       shell: bash
+      env:
+        DEFAULT_REPO: ${{ steps.config-evm-reader.outputs.repo }}
+        DEFAULT_REF: ${{ steps.config-evm-reader.outputs.ref }}
+        REPO_OVERRIDE: ${{ inputs.repo_override }}
+        REF_OVERRIDE: ${{ inputs.ref_override }}
       run: |
-        awk "/^${{ steps.config-evm-reader.outputs.impl }}:/{flag=1; next} /^[[:alnum:]]/{flag=0} flag" ./.github/configs/evm-impl.yaml \
-        | sed 's/ //g' | sed 's/:/=/g' >> "$GITHUB_OUTPUT"
+        echo "repo=${REPO_OVERRIDE:-$DEFAULT_REPO}" >> "$GITHUB_OUTPUT"
+        echo "ref=${REF_OVERRIDE:-$DEFAULT_REF}" >> "$GITHUB_OUTPUT"
     - name: Print Variables for the selected EVM type
       shell: bash
       run: |
+        echo "Type: ${{ inputs.type }}"
         echo "Implementation: ${{ steps.config-evm-reader.outputs.impl }}"
-        echo "Repository: ${{ steps.config-evm-reader.outputs.repo }}"
-        echo "Reference: ${{ steps.config-evm-reader.outputs.ref }}"
-        echo "EVM Binary: ${{ steps.config-evm-impl-config-reader.outputs.evm-bin }}"
-        echo "X-Dist parameter: ${{ steps.config-evm-impl-config-reader.outputs.x-dist }}"
+        echo "Repository: ${{ steps.resolved.outputs.repo }}"
+        echo "Reference: ${{ steps.resolved.outputs.ref }}"
+        echo "EVM Binary: ${{ steps.config-evm-reader.outputs.evm-bin }}"
+        echo "X-Dist parameter: ${{ steps.config-evm-reader.outputs.xdist }}"
     - name: Skip building for EELS
       if: steps.config-evm-reader.outputs.impl == 'eels'
       shell: bash

.github/actions/build-fixtures/action.yaml

@@ -13,13 +13,24 @@ inputs:
   split_label:
     description: "Label for this fork-range split. Empty for unsplit builds."
     default: ""
+  split_retention_days:
+    description: "retention-days for the split fixture artifact. Empty for the repo default."
+    default: ""
+  evm:
+    description: "Override the evm impl. Defaults to the feature's evm-type."
+    default: ""
+  evm_repo:
+    description: "Override the t8n tool repo (e.g. ethereum/go-ethereum)"
+    default: ""
+  evm_ref:
+    description: "Override the t8n tool branch / tag / commit"
+    default: ""
 runs:
   using: "composite"
   steps:
     - uses: ./.github/actions/setup-uv
       with:
         enable-cache: "false"
-    - uses: ./.github/actions/setup-env
     - name: Install EEST
       shell: bash
       run: uv sync --no-progress
@@ -32,13 +43,17 @@ runs:
     - uses: ./.github/actions/build-evm-base
       id: evm-builder
       with:
-        type: ${{ steps.properties.outputs.evm-type }}
+        type: ${{ inputs.evm != '' && inputs.evm || steps.properties.outputs.evm-type }}
+        repo_override: ${{ inputs.evm_repo }}
+        ref_override: ${{ inputs.evm_ref }}
     - name: Install pigz for parallel tarball compression
       if: inputs.split_label == ''
       shell: bash
       run: sudo apt-get install -y pigz
     - name: Generate fixtures using fill
       shell: bash
+      env:
+        PYTEST_XDIST_AUTO_NUM_WORKERS: ${{ steps.evm-builder.outputs.xdist }}
       run: |
         IS_SPLIT="${{ inputs.split_label }}"
 
@@ -50,13 +65,14 @@ runs:
           FORK_ARGS=""
         fi
 
+        EVM_ARGS=""
+        if [ "${{ steps.evm-builder.outputs.impl }}" != "eels" ]; then
+          EVM_ARGS="--evm-bin=${{ steps.evm-builder.outputs.evm-bin }}"
+        fi
+
         # Allow exit code 5 (NO_TESTS_COLLECTED) for fork ranges with no tests.
         EXIT_CODE=0
-        if [ "${{ steps.evm-builder.outputs.impl }}" = "eels" ]; then
-          uv run fill -n ${{ steps.evm-builder.outputs.x-dist }} ${{ steps.properties.outputs.fill-params }} $FORK_ARGS $OUTPUT_ARG --build-name ${{ inputs.release_name }} --no-html --durations=100 --log-level=DEBUG || EXIT_CODE=$?
-        else
-          uv run fill -n ${{ steps.evm-builder.outputs.x-dist }} --evm-bin=${{ steps.evm-builder.outputs.evm-bin }} ${{ steps.properties.outputs.fill-params }} $FORK_ARGS $OUTPUT_ARG --build-name ${{ inputs.release_name }} --no-html --durations=100 --log-level=DEBUG || EXIT_CODE=$?
-        fi
+        just fill-release $EVM_ARGS ${{ steps.properties.outputs.fill-params }} $FORK_ARGS $OUTPUT_ARG --build-name ${{ inputs.release_name }} || EXIT_CODE=$?
         if [ "$EXIT_CODE" -ne 0 ] && [ "$EXIT_CODE" -ne 5 ]; then
           exit "$EXIT_CODE"
         fi
@@ -72,3 +88,4 @@ runs:
         include-hidden-files: true
         path: fixtures_${{ inputs.release_name }}/
         if-no-files-found: ignore
+        retention-days: ${{ inputs.split_retention_days }}