refactor(ssz): depend on the released SSZ specification (#1205)

The SSZ specification was extracted into its own repository and released as
eth-ssz-specs 0.1.0. leanSpec now imports it instead of carrying a copy.

Deleted: the nine-module vendored package, the merkleization module, their
mirrored unit tests, and the two consensus vector modules whose cases the
upstream release ships verbatim (merkleization boundaries and the decode-failure
smoke test). The generic cases in the basic-types vectors go the same way; the
field-element and attestation-subnet cases stay, since upstream cannot express
them.

Kept, in a new module for the shapes the SSZ package leaves to the protocol:

- The struct base, frozen and camelCase. Fork choice keeps one state per block
  root and hands it to every branch below, so a writable state would let one
  branch rewrite history for its siblings. The SSZ shapes are mutable, so each
  leanSpec base restates the freeze. The key casing is what cross-client test
  vectors carry.
- The byte widths, declared against the SSZ byte vector, as the consensus specs
  declare theirs. The 32-byte one is the root type itself: a separate vector of
  that width would be its sibling, and SSZ refuses equality between siblings, so
  every check of a stored root against a computed one would raise.

Two behaviors needed porting rather than renaming:

- The KoalaBear field element now rides on the 32-bit unsigned integer. That is
  what packs eight elements to a leaf; a type outside the unsigned integers
  takes a leaf each, and every XMSS key, signature and registry root would move.
  A test pins the packing.
- The sequence decoder builds its result past validation, so the validator
  registry stopped meeting its position rule on the wire. A registry read off
  the wire is re-checked, which keeps two clients from disagreeing on whether a
  malformed registry is valid.

Every consensus byte is unchanged: the serialized payloads and Merkle roots in
all surviving vectors are identical to what the vendored code produced. The one
JSON difference is that a bare field element now renders as a decimal string,
the way every other integer already did, instead of a Python repr.

Co-authored-by: Thomas Coratger <thomas.coratger@ethereum.org>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: 3 people

.claude/agents/code-tester.md

@@ -17,7 +17,7 @@ The fork specs under `src/lean_spec/spec/forks/` are tested EXCLUSIVELY through
 
 - There is NO `tests/spec/forks/` tree, and you must never create one.
 - For ANY fork behavior — fork choice, state transition, block production, validator duties, aggregation, the containers, slot/interval math, the fork registry or protocol — write or update a consensus test-vector fixture (`state_transition`, `fork_choice`, `ssz`, `slot_clock`, `verify_signatures`, etc.), never a pytest.
-- Mirrored pytest unit tests apply only to NON-fork modules (`node/`, `spec/crypto/`, `spec/ssz/`, and similar).
+- Mirrored pytest unit tests apply only to NON-fork modules (`node/`, `spec/crypto/`, and similar).
 - If asked to "add tests" for a fork container or function (for example a new container under `spec/forks/lstar/containers/`), produce a consensus vector fixture, not a pytest under `tests/`.
 
 ## Auto-Invoke Skills

.claude/rules/code-style.md

@@ -24,13 +24,13 @@ paths:
 Bad:
 ```python
 def process(data):
-    from lean_spec.spec.crypto.merkleization import hash_tree_root
+    from ssz import hash_tree_root
     return hash_tree_root(data)
 ```
 
 Good:
 ```python
-from lean_spec.spec.crypto.merkleization import hash_tree_root
+from ssz import hash_tree_root
 
 def process(data):
     return hash_tree_root(data)

.claude/skills/audit/SKILL.md

@@ -85,7 +85,6 @@ orchestrator sharded the tree only so the work parallelizes.
 2. **Shard.** Split the in-scope tree into coherent subsystems so agents run in parallel.
    The natural shards:
    - `src/lean_spec/spec/crypto/` (XMSS, hashing, signatures, aggregation)
-   - `src/lean_spec/spec/ssz/`
    - `src/lean_spec/spec/forks/` (state transition, fork choice, containers, validator
      duties, aggregation)
    - `src/lean_spec/node/networking/` (gossipsub, reqresp, quic, discovery)

.claude/skills/test/SKILL.md

@@ -19,7 +19,7 @@ Pass additional arguments after `--`:
 
 - `/test -- -v` - Verbose output
 - `/test -- -k "test_serialize"` - Run matching tests
-- `/test -- tests/spec/ssz/` - Run specific test directory
+- `/test -- tests/spec/crypto/` - Run specific test directory
 
 ## Examples
 

CLAUDE.md

@@ -96,7 +96,7 @@ subspecifications that the Lean Ethereum protocol relies on.
   - A test file must never test a type that lives in a different source module. For example, tests
     for `SlotClock` (in `node/chain/clock.py`) belong in `tests/node/chain/test_clock.py`,
     never in an unrelated test module.
-  - This mirroring covers non-fork modules only (`node/`, `spec/crypto/`, `spec/ssz/`, etc.). The
+  - This mirroring covers non-fork modules only (`node/`, `spec/crypto/`, etc.). The
     fork specs under `src/lean_spec/spec/forks/` are exempt — see the forks-are-vectors rule below.
 - **CRITICAL - FORKS ARE TESTED BY VECTORS, NOT PYTESTS**: This is a STRICT requirement. The fork
   specs under `src/lean_spec/spec/forks/` are tested exclusively through consensus test vectors

README.md

@@ -88,7 +88,7 @@ just test
 │       └── spec/                       # Protocol specifications
 │           ├── crypto/                 # Cryptographic subspecs (poseidon, koalabear, xmss, ...)
 │           ├── forks/                  # Fork specifications (tested via consensus vectors)
-│           ├── ssz/                    # SSZ serialization
+│           ├── ssz_types.py            # The SSZ shapes leanSpec declares itself
 │           └── observability/          # Observability spec
 ├── tests/                              # Test suite
 │   ├── consensus/                      # Consensus test vectors

packages/testing/src/consensus_testing/genesis.py

@@ -1,7 +1,8 @@
 """Consensus layer genesis state, block, and anchor construction for tests."""
 
+from ssz import Uint64, hash_tree_root
+
 from consensus_testing.keys import XmssKeyManager
-from lean_spec.spec.crypto.merkleization import hash_tree_root
 from lean_spec.spec.forks import Checkpoint, Interval, Slot, ValidatorIndex
 from lean_spec.spec.forks.lstar import Store
 from lean_spec.spec.forks.lstar.containers import (
@@ -16,7 +17,7 @@
     Validators,
 )
 from lean_spec.spec.forks.lstar.spec import LstarSpec
-from lean_spec.spec.ssz import Bytes52, Uint64
+from lean_spec.spec.ssz_types import Bytes52
 
 
 def build_genesis_state(

packages/testing/src/consensus_testing/keys.py

@@ -12,9 +12,10 @@
 from pathlib import Path
 from typing import ClassVar, Literal
 
+from ssz import hash_tree_root
+
 from lean_spec.config import LEAN_ENV
 from lean_spec.spec.crypto.koalabear import Fp
-from lean_spec.spec.crypto.merkleization import hash_tree_root
 from lean_spec.spec.crypto.xmss.constants import TARGET_CONFIG
 from lean_spec.spec.crypto.xmss.containers import (
     PublicKey,
@@ -39,7 +40,7 @@
     AttestationData,
     SingleMessageAggregate,
 )
-from lean_spec.spec.ssz import Bytes32
+from lean_spec.spec.ssz_types import Bytes32
 
 KeyRole = Literal["attestation", "proposal"]
 """Discriminator for which signing role's key to load from a validator key pair."""

packages/testing/src/consensus_testing/keys_cli.py

@@ -15,6 +15,7 @@
 from pathlib import Path
 
 import click
+from ssz import Uint64
 
 from consensus_testing.keys import (
     LEAN_ENV_TO_SCHEMES,
@@ -24,7 +25,6 @@
 from lean_spec.spec.crypto.xmss.containers import ValidatorKeyPair
 from lean_spec.spec.crypto.xmss.interface import GeneralizedXmssScheme
 from lean_spec.spec.forks import Slot
-from lean_spec.spec.ssz import Uint64
 
 KEY_DOWNLOAD_URLS = {
     "test": "https://github.com/leanEthereum/leansig-test-keys/releases/download/latest/test_scheme.tar.gz",

packages/testing/src/consensus_testing/mocks.py

@@ -8,6 +8,8 @@
 from types import MappingProxyType
 from typing import cast
 
+from ssz import Uint64, hash_tree_root
+
 from lean_spec.node.chain.clock import SlotClock
 from lean_spec.node.networking import PeerId
 from lean_spec.node.networking.peer import PeerInfo
@@ -17,7 +19,6 @@
 from lean_spec.node.sync.block_cache import BlockCache
 from lean_spec.node.sync.peer_manager import PeerManager
 from lean_spec.node.sync.service import SyncService
-from lean_spec.spec.crypto.merkleization import hash_tree_root
 from lean_spec.spec.forks import (
     Checkpoint,
     RejectionReason,
@@ -34,7 +35,7 @@
     State,
 )
 from lean_spec.spec.forks.lstar.spec import LstarSpec
-from lean_spec.spec.ssz import Bytes32, Uint64
+from lean_spec.spec.ssz_types import Bytes32
 
 
 @dataclass