diff --git a/.claude/commands/assess-eip.md b/.claude/commands/assess-eip.md deleted file mode 100644 index 1144a9fb93..0000000000 --- a/.claude/commands/assess-eip.md +++ /dev/null @@ -1,45 +0,0 @@ -# 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 diff --git a/.claude/commands/audit-config.md b/.claude/commands/audit-config.md deleted file mode 100644 index 932074ac9a..0000000000 --- a/.claude/commands/audit-config.md +++ /dev/null @@ -1,47 +0,0 @@ -# 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 diff --git a/.claude/commands/edit-workflow.md b/.claude/commands/edit-workflow.md deleted file mode 100644 index f576b8572f..0000000000 --- a/.claude/commands/edit-workflow.md +++ /dev/null @@ -1,18 +0,0 @@ -# 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. diff --git a/.claude/commands/eip-checklist.md b/.claude/commands/eip-checklist.md deleted file mode 100644 index 68170ca545..0000000000 --- a/.claude/commands/eip-checklist.md +++ /dev/null @@ -1,58 +0,0 @@ -# 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. diff --git a/.claude/commands/fill-tests.md b/.claude/commands/fill-tests.md deleted file mode 100644 index e1f3db7967..0000000000 --- a/.claude/commands/fill-tests.md +++ /dev/null @@ -1,60 +0,0 @@ -# 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. diff --git a/.claude/commands/grammar-check.md b/.claude/commands/grammar-check.md deleted file mode 100644 index 5f55a6eaa5..0000000000 --- a/.claude/commands/grammar-check.md +++ /dev/null @@ -1,59 +0,0 @@ -# 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 diff --git a/.claude/commands/implement-eip.md b/.claude/commands/implement-eip.md deleted file mode 100644 index c06c6e22d1..0000000000 --- a/.claude/commands/implement-eip.md +++ /dev/null @@ -1,62 +0,0 @@ -# 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//`. 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/.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/.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= --template-fork=