Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
155 commits
Select commit Hold shift + click to select a range
645d820
chore(forks): update Osaka and BPO fork deployment status (#2013)
spencer-tb Jan 13, 2026
8cdef0c
refactor(test-benchmark): relabel repricing marker (#2015)
LouisTsai-Csie Jan 13, 2026
36b4720
chore(ci): reduce docker hub rate limit usage in hive-consume workflo…
spencer-tb Jan 13, 2026
180dcec
fix(test-types): log `Transaction` values as readable hex-strings ins…
felix314159 Jan 13, 2026
7ed5f38
fix(test-types): strip extra fields from geth receipts (#2014)
danceratopz Jan 14, 2026
2c83b84
feat(benchmark): support tx gas limit cap in stateful benchmarks (#1962)
CPerezz Jan 14, 2026
5eb4e7b
feat(testing/forks): Implement `bytecode.gas_cost(fork)` (#2002)
marioevz Jan 15, 2026
7282b64
feat(specs): Implement EIP-7928: Block-Level Access Lists
fselmo Nov 11, 2025
6de5318
fix(specs): Fix zero value withdrawals BAL tracking (#29)
fselmo Oct 30, 2025
69e182e
fix(specs): static upfront check for create + selfdestruct (#22)
nerolation Oct 30, 2025
ab9cf9f
feat(tests): Implement more EIP-7928 tests
raxhvl Oct 29, 2025
786fdbb
fix(specs): Ensure tracking before first access (#1722)
nerolation Oct 31, 2025
0642045
fix(spec-specs): duplicate storage writes in state tracker (#1743)
fselmo Nov 4, 2025
68e1714
fix(test-specs): validate t8n BAL independent of expectation existenc…
fselmo Nov 13, 2025
5e7249d
feat(specs): EIP-7928 refactoring
nerolation Nov 5, 2025
e87d13a
fix(spec-specs): require and use blockenv for state tracking
fselmo Nov 5, 2025
873710c
refactor(spec-specs): track BAL changes via frames
fselmo Nov 6, 2025
2ec75b2
fix(spec-specs): Mark original addr warm before delegation
fselmo Nov 11, 2025
18472bf
fix(spec-specs): Make sure we account for no changes
fselmo Nov 11, 2025
0f8bc3b
fix(spec-specs): Better tracking for code changes; ensure with BAL test
fselmo Nov 12, 2025
ab4f8f7
fix(spec-specs): Use child frame for create message
fselmo Nov 12, 2025
1c119fb
fix(spec-specs): Normalize transaction before merging to block frame
fselmo Nov 12, 2025
4e8cbcc
fix(spec-specs): Early static check for SSTORE before any reads
fselmo Nov 12, 2025
eb3ac57
fix(spec-specs): Track storage writes more appropriately wrt index
fselmo Nov 13, 2025
e668cc3
fix(spec-specs): Use functions, not methods; fix create revert
fselmo Nov 13, 2025
37edacd
fix(spec-specs): Default code to b"" in tracker, skip empty setting
fselmo Nov 14, 2025
f9c58f3
fix(spec-specs): Fix BAL cross-transaction tracking and nonce dedup
fselmo Nov 14, 2025
54b574f
fix(spec-specs): Move destroy_account before BAL normalization
fselmo Nov 14, 2025
7c39948
fix(spec-specs): Check delegation access gas before reading
fselmo Nov 14, 2025
ad4c8ee
fix(spec-specs): Track code per auth; filter pre at tx frame
fselmo Nov 15, 2025
0bf53c6
fix(spec-specs): Use proper frames for system transactions
fselmo Nov 16, 2025
20321c8
fix(spec-specs): Track address at init collision
fselmo Nov 21, 2025
771ad19
chore(spec-specs): Add Amsterdam docstring; update prepare msg
fselmo Nov 21, 2025
080df16
chore: Add pre-amsterdam BAL tests to doc for tracking
fselmo Nov 21, 2025
325b338
fix(spec-specs): Calculate all gas we can before accessing state
fselmo Nov 24, 2025
09b1524
fix(test-tools): Remove named forks from blobSchedule; turn off BPOs
fselmo Nov 25, 2025
4d36e86
fix(cli): add bal exception for erigon (#1809)
felix314159 Nov 26, 2025
05ca48f
feat(test): Better describe the BAL for selfdestruct revert
fselmo Nov 26, 2025
b5d922e
test(eip7928): add EXTCODECOPY OOG memory expansion BAL test
qu0b Nov 30, 2025
854ee19
refactor(test-tests): parametrize existing test oog case instead
fselmo Dec 1, 2025
355c575
test(eip7928): add cross-block precompile state leak test
qu0b Dec 1, 2025
6606aff
refactor(test-tests): Add BAL expectation to state leak test; fix lint
fselmo Dec 1, 2025
0f9ef2d
feat(test): add SELFDESTRUCT OOG BAL test
qu0b Dec 4, 2025
89232f2
refactor(tests): move selfdestruct bal tests to oog file; add gas bou…
fselmo Dec 4, 2025
09ec902
feat(tests): Port oog create refund test; add BAL >= Amsterdam
fselmo Dec 1, 2025
c40db83
refactor(spec-specs): Refactor state changes and frame hierarchy (#1841)
fselmo Dec 8, 2025
cfa66a2
fix(spec,tests): Change BAL to List[AccountChange] (#1844)
gurukamath Dec 8, 2025
a6745fa
fix(spec-specs): Fix issues after rebasing with forks/osaka
fselmo Dec 8, 2025
2eb8a61
feat(test): add more bal test cases (#1812)
qu0b Dec 8, 2025
f6d51e8
feat(test-tests): BAL test for nested storage write reset same tx (#1…
fselmo Dec 8, 2025
acaca8d
fix(spec-specs): post-exec net-zero filtering post specs refactor
fselmo Dec 9, 2025
7eb798b
feat(test-tests): Expand BAL CALL opcode OOG boundary test cases (#1882)
fselmo Dec 12, 2025
28ef367
feat(spec): update eip7928 to latest rlp specs wrt storage; rename tx…
fselmo Dec 12, 2025
632044a
fix(test-tests): Avoid hard-coding precompile range for lexicographic…
fselmo Dec 12, 2025
35a4bb5
feat(specs): EIP-7928 move bal from payload (#1917)
nerolation Dec 17, 2025
7339217
fix(test-tests): Use `ZeroPaddedHexNumber` instead of `HexNumber` for…
fselmo Dec 30, 2025
bd0f217
refactor(spec-specs): Refactor specs to be more coherent wrt gas acco…
fselmo Dec 30, 2025
368ac87
feat(tests): add more 7928 test descriptions (#1815)
nerolation Dec 31, 2025
ad7be9e
feat(tests): EIP-7928 tests targeting EIP-4788 (#1887)
raxhvl Jan 7, 2026
19a3960
feat(tests): add invalid BAL tests for spurious block_access_index (#…
nerolation Jan 7, 2026
059f38d
feat(tests): EIP-7928 tests targeting EIP-7002 (#1918)
raxhvl Jan 7, 2026
ba6e884
feat(tests): Test extraneous entries for BAL (#1992)
raxhvl Jan 8, 2026
1075f15
refactor(eip7928): refactor net zero filtering in BALs (#1899)
gurukamath Jan 12, 2026
9f2237a
feat(test): OOG and success selfdestruct tests to all precompiles
fselmo Dec 29, 2025
dcca0f4
refactor(test): `Tangerine` -> `TangerineWhistle`; comments on PR #1954
fselmo Dec 30, 2025
6e74073
fix(tool): Fix EvmOneTransitionTool parsing for TangerineWhistle (add…
fselmo Dec 31, 2025
c288a16
feat(test): Extend selfdestruct tests to all Amsterdam gas boundaries
fselmo Jan 6, 2026
c2c020b
refactor(test): fork.supports_protected_txs() instead of direct compa…
fselmo Jan 8, 2026
a21221e
refactor: address comments from PR #1954
fselmo Jan 8, 2026
d7324de
feat(test): Add selfdestruct to system contracts + to self from initcode
fselmo Jan 9, 2026
a0ae1db
feat(test-commands): Allow pytest valid fork markers as params; add u…
fselmo Jan 9, 2026
fe25717
refactor(spec): Remove `check_gas` where unnecessary for instructions
fselmo Jan 12, 2026
aa9f253
fix(test-fill): organize alloc groups by pytest param (enginex)
fselmo Jan 12, 2026
4f6006c
fix(tests): remove bal from block body (#2017)
gurukamath Jan 13, 2026
a378636
feat(spec-tests): Update json_infra tests version (#1939)
fselmo Jan 15, 2026
0313063
chore: clean up based on comments on PR #1719
fselmo Jan 15, 2026
1d11d8d
tests(eip-7928): generalize eip-7934 tests (#2022)
gurukamath Jan 16, 2026
05117e5
chore(spec-specs): fix typos in `src/ethereum/` (#1965)
danceratopz Jan 19, 2026
acd8d6c
chore(ci): add all EL clients to hive master config (#2034)
danceratopz Jan 19, 2026
dbbb75f
chore: fix PR template links to execution-specs (#2035)
danceratopz Jan 19, 2026
eeb65f7
fix(docs): replace `master` with `mainnet` branch (#2037)
danceratopz Jan 19, 2026
b84b68a
feat(benchmarks): fix bytecode attack for EXT-like opcodes to work in…
jsign Jan 19, 2026
40a25f0
chore(tests,test-*,doc): remove eof from eest (#1873)
spencer-tb Jan 19, 2026
e0c64f0
fix(tests-execute): relax pydantic checks on `GetPayloadResponse`
danceratopz Jan 19, 2026
89b3e8a
chore(ci): skip redundant checks in workflows (#2038)
spencer-tb Jan 19, 2026
4ef381a
chore(testing/vm): Remove UndefinedOpcodes (#2044)
marioevz Jan 20, 2026
d3c4047
chore(tooling): do not gitignore source files in `fixtures` packages …
felix314159 Jan 20, 2026
77c2b9c
fix(tooling,test-*): enable project ruff config for packages/testing …
danceratopz Jan 20, 2026
c14e9c9
fix(tools): fix remaining lint checks after large ruff refactor (#2050)
fselmo Jan 20, 2026
7b9fc7d
feat(ci): Create Devnet Workflows (#2053)
marioevz Jan 21, 2026
f1ba2b1
feat(test): port static context static tests to python (#1960)
fselmo Jan 21, 2026
3b9b018
feat(tests): turn on EIP-7934 tests with BALs (fill all for amsterdam…
fselmo Jan 22, 2026
31defc8
refactor(spec): refactor `execute_code` into `process_message` (#2061)
fselmo Jan 22, 2026
f9ae69d
chore(docs): bump docs fork to amsterdam (#2064)
spencer-tb Jan 22, 2026
6e5f1f8
bugfix(tests): Put BAL back into test fixtures for next bal release (…
fselmo Jan 23, 2026
16316e2
chore(test-specs): fix fork transition tests (#2065)
spencer-tb Jan 23, 2026
a554634
fix(tests): Remove bad opcode test; opt for test_all_opcodes coverage…
fselmo Jan 23, 2026
fd9789f
feat(ci): Run static checks on all generated branches (#2071)
marioevz Jan 23, 2026
c3813a5
feat(test-benchmark): Introduce create2 helper for address computatio…
LouisTsai-Csie Jan 23, 2026
58b4bb0
refactor(test-tests): Port create collision tests (#2031)
chfast Jan 26, 2026
c6c380a
feat(tests): add BAL tests that dequeue consolidations (#2076)
gurukamath Jan 26, 2026
9325a81
fix(tests): fix EIP-7934 tests logic accuracy (#2078)
fselmo Jan 27, 2026
7c8ec4f
feat(test-cli): add `hasher compare` subcommand (#2080)
danceratopz Jan 27, 2026
590bc9f
fix(tests): update nethermind exceptions (#2098)
flcl42 Jan 29, 2026
b68a532
feat(test-fill): speed up filling (#2079)
fselmo Jan 29, 2026
1b266ab
fix(test-benchmark): support `blobhash` benchmark (#2067)
LouisTsai-Csie Jan 29, 2026
2c549ce
feat(testing/fixtures): Add logs to state fixtures (#2091)
marioevz Jan 29, 2026
438bac1
refactor(test-benchmark): update benchmark fork to Osaka (#2104)
LouisTsai-Csie Feb 2, 2026
5cb915f
doc(test-benchmark): framework description and developer guideline (#…
LouisTsai-Csie Feb 2, 2026
3821cb4
feat(test-benchmark): add EIP-7825 tx splitting and fix & include stu…
CPerezz Feb 2, 2026
1872234
fix(test,hive): Add hive ruleset BPO2ToAmsterdamAtTime15k (#2111)
fselmo Feb 2, 2026
2e0c8c6
chore(pyproject): declare Python 3.12 support in package metadata (#1…
talhaaktss Feb 2, 2026
0c65695
chore(test-benchmark): skip rlp size limit check (#2118)
LouisTsai-Csie Feb 3, 2026
d0fd339
fix(fixtures): stream fixture JSON writes to reduce peak memory. (#2124)
danceratopz Feb 3, 2026
2c1a10d
fix(test-fill): improve memory buildup for fill; merge on `SIGINT` / …
fselmo Feb 3, 2026
0d5a00b
Add BlockException.GAS_USED_OVERFLOW to BesuExceptionMapper (#2126)
daniellehrner Feb 3, 2026
72af492
fix(test): lint (#2128)
fselmo Feb 3, 2026
72addb2
chore(tests): use representative blob combos in high blob count forks…
danceratopz Feb 4, 2026
554c353
feat(benchmark/tests): Extra sstore benchmark tests (#2130)
marioevz Feb 4, 2026
b808aa2
fix(test-fill): use k-way merge for fixture json to reduce memory foo…
fselmo Feb 4, 2026
28eb3d5
feat(tools): retry rpc calls on server-side error (#2056)
SamWilsn Feb 4, 2026
26918e5
feat(test-fill): performance improvements for release processes and f…
fselmo Feb 5, 2026
a9df61a
feat(test-benchmark): add gas limit check for BLS12_G2_MSM benchmark …
LouisTsai-Csie Feb 5, 2026
0a07c00
fix(test-ci): Fix benchmark artifact expectation for new builder prea…
fselmo Feb 5, 2026
1140c0e
refactor(testing): Implement IteratingBytecode, FixedIterationsByteco…
marioevz Feb 5, 2026
7ab5c83
feat(test-benchmark): updates and fixes for fixed opcode count (#1985)
spencer-tb Feb 5, 2026
ea028c9
fix(docs): add missing lines code coverage field to eip checklist (#2…
felix314159 Feb 5, 2026
f74aa1c
test(benchmark): skip test_blockhash pending investigation (#2145)
spencer-tb Feb 5, 2026
e7d8ccf
chore(ci): only fill native test formats in tox's `pypy3` env (#2116)
danceratopz Feb 5, 2026
35f83db
fix(tests/benchmark): Max size contract deployment execution (#2149)
marioevz Feb 5, 2026
b206688
fix(test-ci): fix issues with recent changes to checklist (#2151)
fselmo Feb 5, 2026
8a5a2d5
feat(tests): BAL tests for 7702 delegation reset, create and access (…
gurukamath Feb 6, 2026
cad8b90
feat(tests): add warm and cold account query benchmark (#2138)
LouisTsai-Csie Feb 6, 2026
a321481
fix(benchmark): reduce stateful stubs to 4 representative tokens (#2141)
CPerezz Feb 6, 2026
c5f1dc7
docs: Update package names from ethereum_test_* to execution_testing.…
aryanpatil2703 Feb 6, 2026
e1b871b
feat(benchmarks): add keccak benchmark with updated memory (#1849)
jochem-brouwer Feb 6, 2026
02456f2
feat(tests): add test case for create2 selfdestruct and recreate (#2121)
nerolation Feb 6, 2026
551c8f8
refactor(spec-tool): remove unused fields (#2105)
Galoretka Feb 7, 2026
342c7bc
chore(tooling): add initial claude config and skills (#2024)
danceratopz Feb 8, 2026
7f584cd
chore(test-client-clis): add Nethermind exception for `BlockException…
benaadams Feb 9, 2026
09ac716
fix(testing/execute): Phase not being correctly passed as tx request …
marioevz Feb 9, 2026
eb62025
refactor(test-benchmark): failing `sstore` / `sload` benchmark cases …
LouisTsai-Csie Feb 9, 2026
87a414f
feat: enhance keccak benchmark (#2152)
LouisTsai-Csie Feb 9, 2026
2fc0504
Merge branch 'forks/amsterdam' into upstream
pdobacz Feb 10, 2026
c114704
Port upstream grammar fixes and interpreter refactoring to monad forks
pdobacz Feb 10, 2026
597a1da
Revert adding new gh actions & workflows
pdobacz Feb 10, 2026
7e3acf1
Fix mypy error from shadowed except variable
pdobacz Feb 10, 2026
8f41245
Add mip3 feature release
pdobacz Jan 28, 2026
e56d4f0
MIP-3 implementation & tests
pdobacz Jan 30, 2026
fd60c76
Fix TX_MAX_GAS_LIMIT for monad forks
pdobacz Jan 26, 2026
a76d494
Update MIP-3 memory cost formula to words // 2
pdobacz Jan 29, 2026
2277a4c
refactor(tests): Add fork parameter to Initcode for MIP-3 gas calcula…
pdobacz Jan 30, 2026
5e59e30
Fix, tidy and add test for MIP-3
pdobacz Feb 2, 2026
f78cb6e
Spec update - OOM is OOG
pdobacz Feb 3, 2026
770c263
Fix mypy
pdobacz Feb 9, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
45 changes: 45 additions & 0 deletions .claude/commands/assess-eip.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Assess EIP

Structured assessment of EIP implementation complexity. When invoked with an EIP number or description, perform the following analysis.

## 1. Classify the Change Type(s)

- **New opcode** — requires: `vm/instructions/`, gas cost, `op_implementation` registration
- **New precompile** — requires: `vm/precompiled_contracts/`, address constant, mapping, gas cost
- **New transaction type** — requires: `transactions.py`, `fork.py` validation, exception types
- **System contract** — requires: contract deployment in genesis, state handling
- **Block header/body field** — requires: `blocks.py`, RLP encoding changes
- **Gas cost change** — requires: `vm/gas.py` constant updates, possibly interpreter changes
- **Execution layer request** — requires: request handling in `requests.py`
- **Constraint change** — requires: validation logic in `fork.py` or `blocks.py`

## 2. Estimate Scope

- **Small** (1-2 files in spec, 1 test file): gas repricing, simple constraint
- **Medium** (3-5 files in spec, 2-3 test files): new opcode, new precompile
- **Large** (5-10 files in spec, 5+ test files): new tx type, new system contract
- **XL** (10+ files, multi-EIP umbrella): VM overhaul (e.g., EOF)

## 3. Identify Required Test Categories

Map the change types to the relevant `EIPChecklist` categories (from `execution_testing.checklists.eip_checklist`). List the checklist items that need to be covered.

## 4. Identify Prior Art

Find similar completed EIPs in the repo to use as implementation reference:

- New opcode → check recent opcode additions in latest fork's `vm/instructions/`
- New precompile → `tests/osaka/eip7951_p256verify_precompiles/`
- New tx type → `tests/prague/eip7702_set_code_tx/`
- Gas changes → check `vm/gas.py` diffs between recent forks

## 5. Output Structured Assessment

Produce a summary with:

- Change types identified
- Estimated scope (Small / Medium / Large / XL)
- Spec files to modify (with paths)
- Test files to create
- EIPChecklist categories to cover
- Reference implementations to follow
47 changes: 47 additions & 0 deletions .claude/commands/audit-config.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Audit Config

Periodic verification skill to prevent CLAUDE.md and skills from going stale. Run this manually to check freshness (e.g., after a major refactor, before a release, or when onboarding).

## Checks to Perform

### 1. Verify File Paths

Check that every file path or directory referenced in `CLAUDE.md` and `.claude/commands/*.md` still exists. Report any broken references.

### 2. Verify CLI Commands

Run `--help` on referenced commands and confirm mentioned flags still exist:

- `uv run fill --help`
- `uv run ethereum-spec-new-fork --help`
- `uv run ethereum-spec-lint --help`
- `uv run checklist --help`

### 3. Verify Code Patterns

Spot-check code patterns mentioned in skills against actual code:

- Does `op_implementation` dict exist in the latest fork's `vm/instructions/__init__.py`?
- Does `PRE_COMPILED_CONTRACTS` exist in the latest fork's `vm/precompiled_contracts/mapping.py`?
- Does the `Ops` enum exist in `vm/instructions/__init__.py`?
- Does `FORK_CRITERIA` or equivalent exist in the latest fork's `__init__.py`?

### 4. Verify Fork List

Check that the fork order and default branch mentioned in `CLAUDE.md` match reality by inspecting `src/ethereum/forks/` and git branch configuration.

### 5. Verify Docs References

Confirm that `docs/` paths referenced in skills still exist:

- `docs/writing_tests/`
- `docs/writing_tests/opcode_metadata.md`
- `docs/writing_tests/checklist_templates/`
- `docs/filling_tests/`

## Output

Produce a summary with:

- **Current**: references that are still valid
- **Stale**: references that need updating, with suggested fixes
18 changes: 18 additions & 0 deletions .claude/commands/edit-workflow.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Edit Workflow

GitHub Actions conventions. Run this skill before modifying workflow files in `.github/`.

## Action Version Pinning (Required)

All actions must be pinned to commit SHA with version comment:

```yaml
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
```

- Never use version tags alone (`@v4` is wrong)
- Local actions (`./.github/actions/*`) are exempt from pinning

## Validation

Run `uvx tox -e static` before committing — this runs `actionlint` to validate YAML syntax and structure.
58 changes: 58 additions & 0 deletions .claude/commands/eip-checklist.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# EIP Checklist

Guide for using the EIP testing checklist system to track test coverage. Run this skill when working on EIP test coverage or checklists.

## What It Is

The `EIPChecklist` class (in `execution_testing.checklists.eip_checklist`) provides a hierarchical marker system for tagging tests with what aspect of an EIP they cover. Categories include:

- `General`, `Opcode`, `Precompile`, `SystemContract`, `TransactionType`
- `BlockHeaderField`, `BlockBodyField`, `GasCostChanges`, `GasRefundsChanges`
- `ExecutionLayerRequest`, `BlobCountChanges`

Each category has deep sub-items (e.g., `EIPChecklist.Opcode.Test.GasUsage.Normal`).

## Usage in Tests

```python
@EIPChecklist.TransactionType.Test.IntrinsicValidity.GasLimit.Exact()
def test_exact_intrinsic_gas(state_test: StateTestFiller):
...

# Multi-EIP coverage:
@EIPChecklist.TransactionType.Test.Signature.Invalid.V.Two(eip=[2930])
def test_invalid_v(state_test: StateTestFiller):
...
```

## Generating Checklists

Run `uv run checklist` to generate coverage reports. Template at `docs/writing_tests/checklist_templates/eip_testing_checklist_template.md`.

## Marking Items as Externally Covered or N/A

Create `eip_checklist_external_coverage.txt` in the EIP test directory:

```
general/code_coverage/eels = Covered by EELS test suite
```

Create `eip_checklist_not_applicable.txt` for inapplicable items:

```
system_contract = EIP-7702 does not introduce a system contract
precompile/ = EIP-7702 does not introduce a precompile
```

(trailing `/` marks entire category as N/A)

## Completed Examples

Reference these for patterns:

- `tests/prague/eip7702_set_code_tx/` — comprehensive checklist for a transaction type EIP
- `tests/osaka/eip7951_p256verify_precompiles/` — precompile checklist example

## References

See `docs/writing_tests/checklist_templates/` for templates and detailed documentation.
60 changes: 60 additions & 0 deletions .claude/commands/fill-tests.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Fill Tests

CLI reference for the `fill` command. Run this skill before filling test fixtures. The `fill` command is pytest-based — all standard pytest flags work.

## Basic Usage

```
uv run fill tests/ # Fill all tests
uv run fill tests/cancun/ --fork Cancun # Specific fork
uv run fill tests/path/to/test.py -k "test_name" # Specific test
uv run fill tests/osaka/ --until Osaka # Up to fork (inclusive)
uv run fill --collect-only tests/ # Dry run: list tests without executing
```

## Key Flags

- `--fork FORK` / `--until FORK` — target specific fork or range
- `--output DIR` + `--clean` — output directory; `--clean` required when re-filling
- `-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`)
- `--verify-fixtures` — verify generated fixtures against geth blocktest
- `--generate-all-formats` — generate all fixture formats (2-phase)

## Debugging

- `--evm-dump-dir DIR` — dump t8n input/output for debugging
- `--traces` — collect execution traces
- `--pdb` — drop into debugger on failure
- `-vv` — verbose output; `-x` — stop on first failure; `-s` — print stdout

## Watch Mode

- `--watch` — re-run on file changes (clears screen between runs)
- `--watcherfall` — same but keeps output history

## 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

## Fixture Formats

One test function auto-generates multiple formats: `StateFixture`, `BlockchainFixture`, `BlockchainEngineFixture`. Use `--generate-all-formats` for additional formats via 2-phase execution.

## References

See `docs/filling_tests/` for detailed documentation.
59 changes: 59 additions & 0 deletions .claude/commands/grammar-check.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Grammar Check

Audit grammar in documentation and code comments.

## Files to Check

Check `$ARGUMENTS` (default: `src/`). Use Glob to find:

- `**/*.py` - check docstrings and `#` comments only
- `**/*.md` - check prose content, skip code blocks

## What to Detect

1. Missing prepositions ("refer the" → "refer to the", "comply the" → "comply with the")
2. Subject-verb disagreement
3. Missing articles where required
4. Incorrect word order
5. Sentence fragments in documentation
6. Double words ("the the", "is is")

## What to Ignore

- Code syntax and variable names
- Technical terms, EIP numbers, hex values
- Intentional shorthand in inline code comments
- Content inside code blocks (``` or indented blocks in markdown)
- URLs and email addresses

## Output Format

For each issue, output a clickable link with line number:

```
path/to/file.md:42 - "original problematic text"
Suggestion: "corrected text"
Reason: brief explanation
```

For issues spanning multiple lines, use range format:

```
path/to/file.py:15-17 - "multi-line docstring issue"
Suggestion: "corrected text"
Reason: brief explanation
```

## Process

1. Find all matching files
2. For `.md` files: check full prose content, skip code blocks
3. For `.py` files: extract and check only docstrings (triple-quoted) and `#` comments
4. Group findings by file
5. End with summary: "Found N grammar issues in M files." or "No grammar issues found."

## Important

- Report findings only, do not auto-fix
- Be conservative: only flag clear errors, not style preferences
- When uncertain, skip rather than false-positive
62 changes: 62 additions & 0 deletions .claude/commands/implement-eip.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Implement EIP

Patterns for implementing spec changes in `src/ethereum/forks/`. Run this skill before implementing an EIP or modifying fork code.

## Fork Directory Layout

Each fork lives at `src/ethereum/forks/<fork_name>/`. Explore the latest fork directory for current structure. Key files:

- `__init__.py` — FORK_CRITERIA, fork metadata
- `fork.py` — state transition functions
- `blocks.py` — block structure and validation
- `transactions.py` — transaction types and processing
- `state.py` — state trie operations
- `vm/instructions/__init__.py` — Ops enum + `op_implementation` dict
- `vm/gas.py` — gas constants and calculations
- `vm/precompiled_contracts/__init__.py` — precompile address constants
- `vm/precompiled_contracts/mapping.py` — `PRE_COMPILED_CONTRACTS` registry

## Import Isolation (enforced by `ethereum-spec-lint`)

- **Within same fork**: relative imports (`from . import vm`, `from .state import ...`)
- **Previous fork only**: absolute imports (`from ethereum.cancun import ...`)
- **Shared modules**: always OK (`ethereum.crypto`, `ethereum.utils`, `ethereum.exceptions`)
- **Future forks**: NEVER allowed
- **Ancient forks (2+ back)**: NEVER allowed
- Run `ethereum-spec-lint` to verify before committing

## 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
3. Register in `op_implementation` dict in `vm/instructions/__init__.py`
4. Add gas constant in `vm/gas.py` if needed

## Adding a New Precompile

1. Define address constant in `vm/precompiled_contracts/__init__.py` using `hex_to_address("0x...")`
2. Create implementation file `vm/precompiled_contracts/<name>.py`
3. Register in `PRE_COMPILED_CONTRACTS` dict in `vm/precompiled_contracts/mapping.py`
4. Add gas constant in `vm/gas.py`

## Adding a New Transaction Type

1. Define `@slotted_freezable @dataclass` class in `transactions.py`
2. Add to `Transaction` union type at bottom of file
3. Handle in `fork.py` validation/processing logic
4. Add exception type in `exceptions.py` if needed

## Creating a New Fork

```bash
uv run ethereum-spec-new-fork --new-fork=<name> --template-fork=<template>
```

- Copies all files from template fork and applies codemods (renames, constant updates)
- After running: update `__init__.py` docstring, fork-specific constants, run `uv run ruff format`
- Fork criteria types: `ByBlockNumber(N)` (pre-merge), `ByTimestamp(T)` (post-merge), `Unscheduled(order_index=N)` (in development)

## Branch Naming

- Feature branches: `eips/<fork_name>/eip-<number>`
- PR targets: `forks/<fork_name>`
42 changes: 42 additions & 0 deletions .claude/commands/lint.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Lint

Run the full static analysis suite and fix issues. This matches the CI check on every PR.

## Step 1: Run the Full Check

```bash
uvx tox -e static
```

This runs ruff, mypy, codespell, ethereum-spec-lint, and actionlint in one pass. If everything passes, you're done.

## Step 2: Auto-Fix Formatting and Lint Issues

If tox reports ruff errors, run these first — they resolve most issues automatically:

```bash
uv run ruff format
uv run ruff check --fix
```

## Step 3: Resolve Remaining Issues Manually

After auto-fix, re-run to see what's left:

```bash
uvx tox -e static
```

- **Remaining ruff issues**: fix manually (auto-fix can't handle all rules)
- **mypy errors**: fix type annotations, add missing types, correct signatures
- **codespell errors**: fix typos, or add intentional words to `whitelist.txt`
- **ethereum-spec-lint errors**: fix import isolation violations (see `/implement-eip` for import rules)
- **actionlint errors**: fix workflow YAML issues (see `/edit-workflow`)

## Step 4: Final Verification

Re-run until clean:

```bash
uvx tox -e static
```
Loading