Merge pull request #7 from monad-developers/upstream

Merge upstreadm changes - reopened

Author: pdobacz

.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

.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

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

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

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

.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

.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/<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>`

.claude/commands/lint.md

@@ -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
+```