Merge branch 'mig/missing' into HEAD

Author: pablodeymo

.cargo/config.toml

@@ -1,9 +1,21 @@
+# leanVM proves over a binary field tower, whose multiplication is a carryless
+# multiply. Both entries below have to enable it, or the prover falls back to
+# scalar bit-twiddling: `+pclmulqdq` on x86, and on aarch64 the `aes` feature,
+# which is what LLVM gates PMULL behind.
 [target.x86_64-unknown-linux-gnu]
 rustflags = [
     "-Ctarget-cpu=x86-64-v3",
     "-Ctarget-feature=+avx2,+sse2,+ssse3,+sse4.1,+sse4.2,+bmi1,+lzcnt,+pclmulqdq",
 ]
 
+[target.aarch64-unknown-linux-gnu]
+rustflags = [
+    # Baseline armv8.2 (the floor for Apple silicon and Neoverse N1/V1), plus the
+    # crypto extensions carrying PMULL and SHA-2.
+    "-Ctarget-cpu=neoverse-n1",
+    "-Ctarget-feature=+aes,+sha2,+neon",
+]
+
 # Supply-chain cooldown for dependency resolution (unstable min-publish-age,
 # tracking issue rust-lang/cargo#17009): crate versions published less than
 # 14 days ago are excluded when the resolver runs on a nightly cargo.

.github/workflows/ci.yml

@@ -59,6 +59,12 @@ jobs:
       - name: Clippy
         run: cargo clippy --locked --workspace --all-targets -- -D warnings
 
+      # The leanSpec spectests are `test = false` while the released fixtures
+      # lag leanVM, and `--all-targets` leaves such targets out. Name them so
+      # they keep compiling until they run again.
+      - name: Clippy (skipped spectests)
+        run: cargo clippy --locked --workspace --test forkchoice_spectests --test signature_spectests --test stf_spectests --test ssz_spectests -- -D warnings
+
   # Two features gate code that no step in `lint` reaches, so both would rot
   # silently between merges.
   #

.github/workflows/pr-main_mdbook.yml

@@ -8,11 +8,13 @@ on:
       - main
     paths:
       - "docs/**"
+      - "theme/**"
       - "book.toml"
       - ".github/workflows/pr-main_mdbook.yml"
   pull_request:
     paths:
       - "docs/**"
+      - "theme/**"
       - "book.toml"
       - ".github/workflows/pr-main_mdbook.yml"
   workflow_dispatch:

CLAUDE.md

@@ -39,7 +39,7 @@ crates/
         └─ src/metrics.rs   # State transition timing + counters
   common/
     ├─ types/               # Core types (State, Block, Attestation, Checkpoint)
-    ├─ crypto/              # XMSS aggregation (leansig wrapper)
+    ├─ crypto/              # XMSS sign/verify + aggregation (leanVM wrapper)
     ├─ ssz-tree/            # Persistent Merkle tree (List/Vector) behind the beacon registry and balances
     ├─ metrics/             # Prometheus re-exports, TimingGuard, gather utilities
     └─ test-fixtures/       # Spec-fixture loading (prod dep of rpc's Hive test driver)
@@ -279,9 +279,39 @@ actual_slot = finalized_slot + 1 + relative_index
 
 **XMSS (eXtended Merkle Signature Scheme):**
 - Post-quantum signature scheme
-- 52-byte public keys, 2536-byte signatures (`SIGNATURE_SIZE` in `common/types/src/signature.rs`)
+- Wire sizes: `PUBLIC_KEY_SIZE` (`common/types/src/state.rs`) and `SIGNATURE_SIZE`
+  (`common/types/src/attestation.rs`), static-asserted against leanVM's scheme
+  constants in `common/crypto/src/signature.rs`
 - Epoch-based to prevent reuse
-- Aggregation via leanVM (previously leanMultisig) for efficiency
+- Signing, verification, and aggregation all come from leanVM, which internalized
+  XMSS in its own `xmss` crate; there is no external leanSig dependency
+- BLAKE2s over binary fields, not Poseidon over KoalaBear: a leanVM `main` bump
+  across that rewrite invalidates every genesis key and every stored proof, even
+  when the wire sizes happen to match
+- `ethlambda_crypto::init_leanvm(use_arena)` must run once at startup, before any
+  proving or proof decoding. `--prover-arena` opts into leanVM's bump arena,
+  which recycles the prover's large buffers across proofs instead of re-faulting
+  them, so its pages stay resident for the node's lifetime
+- `ethlambda keygen` generates genesis validator keys through the same
+  `ValidatorSecretKey` the node loads them with, so a key set cannot be built
+  against a different leanVM than the client reading it. Keys are only usable by
+  a client on the matching revision, and no file size changes when the scheme
+  does, so the manifest records `leanvm_rev`. See [`docs/keygen.md`](docs/keygen.md)
+
+**Aggregation shape (one leanVM `AggregateSignature`, grouped by `(epoch, message)`):**
+- Type-1 and Type-2 are the same object: one `XmssGroup` per `(epoch, message)`
+  pair, carrying that group's sorted, deduplicated keys
+- **A slot can carry several messages.** Validators attesting moments apart
+  disagree within a slot, so two distinct `AttestationData` at one slot is
+  ordinary rather than equivocation and a block routinely carries both. The
+  groups are sorted on the whole pair: with two of them at one slot, sorting on
+  the epoch alone rebuilds a different signer set and fails a valid proof
+- **The binding is off the wire.** `to_bytes_without_pubkeys()` carries neither
+  the keys nor the `(slot, message)` pairs, so every decode rebuilds the whole
+  signer set from a `SignerSet` per claim. A wrong set, message or slot decodes
+  fine and fails inside the SNARK verifier, so there is no cheap binding check
+- Narrowing replaces splitting: re-aggregate the parent with a `declare` naming
+  the group to keep (`split_type_2_by_message`)
 
 **Signature Aggregation (Two-Phase):**
 1. **Gossip signatures**: Fresh XMSS from network → aggregate via leanVM
@@ -674,7 +704,7 @@ transitions are in `ethlambda-types`, per the section above. Nothing above
 GENESIS_TIME: 1770407233
 MILLISECONDS_PER_SLOT: 4000  # optional, defaults to DEFAULT_MILLISECONDS_PER_SLOT
 GENESIS_VALIDATORS:
-  - attestation_pubkey: "cd323f232b34ab26d6db7402c886e74ca81cfd3a..."  # 52-byte XMSS pubkeys (hex)
+  - attestation_pubkey: "cd323f232b34ab26d6db7402c886e74ca81cfd3a..."  # XMSS pubkeys, hex, PUBLIC_KEY_SIZE bytes
     proposal_pubkey: "b7b0f72e24801b02bda64073cb4de6699a416b37..."
 ```
 - Validator indices are assigned sequentially (0, 1, 2, ...) based on array order
@@ -780,7 +810,9 @@ behavior.
 ## External Dependencies
 
 **Critical:**
-- `leansig`: XMSS signatures (leanEthereum project)
+- `leanvm`: XMSS signatures and recursive aggregation, taken from leanVM's facade
+  crate (which re-exports `xmss`, `rec_aggregation` and its `rand`) and pinned to
+  one `main` revision (leanEthereum project)
 - `libssz` / `libssz-derive` / `libssz-types`: SSZ serialization
 - `libssz-merkle`: Merkle tree hashing (`hash_tree_root()`)
 - `spawned-concurrency`: Actor model

CONTRIBUTING.md

@@ -25,7 +25,7 @@ crates/
   └─ state_transition/          # Process slots, blocks, attestations
   common/
   ├─ types/                     # Core types
-  ├─ crypto/                    # XMSS aggregation (leansig wrapper)
+  ├─ crypto/                    # XMSS sign/verify + aggregation (leanVM wrapper)
   └─ metrics/                   # Prometheus metrics
   net/
   ├─ p2p/                       # libp2p: gossipsub + req-resp