/spec-diff - Spec Changelog Between Versions

Show what changed in the spec code (src/lean_spec/) and consensus test vectors (tests/consensus/) between two devnet versions (or HEAD).

Scope: Protocol-level spec types, functions, containers, forkchoice logic, and the test fixtures that generate cross-client test vectors.

Excluded: Test framework infrastructure (packages/testing/, consensus_testing/), unit tests (tests/), interop tests (tests/interop/), documentation (docs/), CI/tooling configs, and the node implementation layer (networking, sync, storage, node runner).

Usage

• /spec-diff devnet3 - Changes from devnet 3 to HEAD
• /spec-diff devnet2 devnet3 - Changes from devnet 2 to devnet 3
• /spec-diff devnet0 devnet3 - Full changelog across multiple devnets

Steps

1. Resolve version commits

Look up commit hashes from VERSIONS.md in the repo root. It contains a table mapping version names (e.g. "Devnet 3") to commit hashes.

Parse the argument(s):

• If one argument: compare that version → HEAD
• If two arguments: compare first → second
• Match case-insensitively and flexibly (e.g. devnet3, Devnet 3, d3 should all resolve to the same entry)

If a version is not found in VERSIONS.md, report the available versions and abort.

2. Get changed files

Run both commands:

git diff --name-only <from-commit> <to-commit> -- src/lean_spec/
git diff --name-only <from-commit> <to-commit> -- tests/consensus/

Filter to .py files only.

3. Analyze spec changes

For each changed spec file (src/lean_spec/), run:

git diff <from-commit> <to-commit> -- <file>

Categorize each item as:

• New - functions/types/modules that didn't exist in the from-version
• Modified - functions/types whose signature or body changed (includes renames)
• Removed - functions/types that were deleted

For modified items, briefly describe what changed (e.g. "added deadline parameter", "changed return type from bool to Optional[bool]").

Detecting renames: A rename+change appears in the diff as a removal in one place and an addition in another. Before classifying something as [Removed] + [New], check whether the removed item has a corresponding new item with a similar name, similar parameters, or similar objective. If so, report it as a single [Modified] entry: old_name() → renamed to new_name(), with a description of what else changed. Common rename patterns: prefix/suffix changes (gossip_ → attestation_), class extraction (function → Class.method), split (one_func → two_funcs).

4. Analyze test vector changes

For each changed consensus test file (tests/consensus/), run:

git diff <from-commit> <to-commit> -- <file>

Summarize changes to test vectors grouped by test category (fork choice, SSZ, signature verification, etc.). Focus on:

• New test cases added
• Tests whose scenarios changed (e.g. "blocks now carry explicit attestations instead of relying on auto-collection")
• Tests removed
• Behavioral changes in what's being tested (e.g. "fork weight now based on attestations not block count")

5. Output report

Group changes by component (logical area of the spec), not by file path. Within each component, prefix each item with [New], [Modified], or [Removed].

After the spec component sections, include a Test Vectors section covering changes to consensus test fixtures (tests/consensus/).

## Spec changes: Devnet 3 → HEAD

### Block Envelope

- [New] `SignedBlock` — replaces `SignedBlockWithAttestation`
- [Removed] `BlockWithAttestation` — no longer needed

### State Transition

- [Modified] `State` — added `deposit_index` field (Uint64)

### Test Vectors

**Fork Choice** (5 files, +770 -407 lines)
- [Modified] Tests now use explicit attestations — weight from attestations not block count
- [Removed] `test_auto_collect_proposer_attestations` — auto-collection removed

**SSZ Containers** (2 files)
- [Modified] `Validator` tests — dual pubkeys

### Summary
- X spec files, Z test files changed
- Brief description of core design changes

Guidelines:

• Group spec changes by logical component (e.g. "Block Envelope", "Validator Model", "Aggregation", "Forkchoice Store"), not by file path.
• Each item is a bullet prefixed with [New], [Modified], or [Removed].
• The Test Vectors section groups by test category (fork choice, SSZ, signature verification, state transition, etc.) with file counts and line stats.
• Keep descriptions concise. The goal is to give implementation teams a clear picture of what they need to update, not a line-by-line diff.
• End with a Summary section highlighting core design changes.