diff --git a/.claude/commands/assess-eip.md b/.claude/commands/assess-eip.md new file mode 100644 index 0000000000..1144a9fb93 --- /dev/null +++ b/.claude/commands/assess-eip.md @@ -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 diff --git a/.claude/commands/audit-config.md b/.claude/commands/audit-config.md new file mode 100644 index 0000000000..932074ac9a --- /dev/null +++ b/.claude/commands/audit-config.md @@ -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 diff --git a/.claude/commands/edit-workflow.md b/.claude/commands/edit-workflow.md new file mode 100644 index 0000000000..f576b8572f --- /dev/null +++ b/.claude/commands/edit-workflow.md @@ -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. diff --git a/.claude/commands/eip-checklist.md b/.claude/commands/eip-checklist.md new file mode 100644 index 0000000000..68170ca545 --- /dev/null +++ b/.claude/commands/eip-checklist.md @@ -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. diff --git a/.claude/commands/fill-tests.md b/.claude/commands/fill-tests.md new file mode 100644 index 0000000000..e1f3db7967 --- /dev/null +++ b/.claude/commands/fill-tests.md @@ -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. diff --git a/.claude/commands/grammar-check.md b/.claude/commands/grammar-check.md new file mode 100644 index 0000000000..5f55a6eaa5 --- /dev/null +++ b/.claude/commands/grammar-check.md @@ -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 diff --git a/.claude/commands/implement-eip.md b/.claude/commands/implement-eip.md new file mode 100644 index 0000000000..c06c6e22d1 --- /dev/null +++ b/.claude/commands/implement-eip.md @@ -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//`. 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=