Merge branch 'main' into docs/spec-deviations-page

Author: MegaRedHand

.claude/skills/devnet-log-review/SKILL.md

@@ -145,7 +145,7 @@ grep "signature verification failed" lantern_0.log
 
 ### Finalization Debugging
 
-Finalization should advance every 6-12 slots. If it stalls, investigate:
+On a healthy devnet finalization advances every few slots. If it stalls, investigate:
 
 ```bash
 # Check finalization progress
@@ -154,9 +154,11 @@ grep "finalized_slot=" ethlambda_0.log | tail -20
 # If finalized_slot stays same for 50+ slots → finalization stalled
 ```
 
-**Finalization requires >2/3 supermajority:**
-- 6 validators → need 5 votes minimum
-- 9 validators → need 7 votes minimum
+**Justification requires a ≥2/3 supermajority** (`3 * votes >= 2 * validator_count`,
+i.e. `ceil(2N/3)` — see `crates/blockchain/state_transition/src/lib.rs`):
+- 6 validators → need 4 votes minimum
+- 9 validators → need 6 votes minimum
+- 16 validators → need 11 votes minimum
 
 **See [references/FINALIZATION_DEBUG.md](references/FINALIZATION_DEBUG.md) for:**
 - Common causes of finalization stalls
@@ -184,15 +186,15 @@ Different clients have different log formats and key patterns.
 
 ## Block Proposal Flow (ethlambda)
 
-A healthy block proposal follows this sequence:
+Since the pre-build change (#445), the proposer builds at the *previous* slot's
+interval 4 and publishes aligned to the slot boundary. A healthy block proposal
+follows this sequence:
 
-1. `We are the proposer for this slot` - Node detects it's the proposer
-2. `TODO precompute poseidons in parallel + SIMD` - XMSS aggregate proof starts
-3. `packed_pcs_commit` - Proof commitment
-4. `Logup data` - Logup protocol data
-5. `AIR proof{table=poseidon16}` / `AIR proof{table=poseidon24}` - AIR proofs
-6. `Published block` - Block successfully built and published
-7. `Published block to gossipsub` - Block broadcast to network
+1. `We are the proposer for this slot` - Node detects it's the proposer (fires one slot early)
+2. leanVM proving output (`packed_pcs_commit`, `Logup data`, `AIR proof{table=poseidon16|poseidon24}`) - XMSS aggregate proof
+3. `Finished building block` - Build complete (#474; this is where the build-time metric stops)
+4. `Published block` - Published at the slot boundary (the gap to step 3 is idle wait, not build cost)
+5. `Published block to gossipsub` - Block broadcast to network
 
 ## Summary Report Format
 

.claude/skills/test-pr-devnet/SKILL.md

@@ -53,7 +53,7 @@ Test ethlambda branch changes in a multi-client local devnet with zeam (Zig), re
 **Success criteria:**
 - ✅ No errors in ethlambda logs
 - ✅ All 4 nodes at same head slot
-- ✅ Finalization advancing (every 6-12 slots)
+- ✅ Finalization advancing (every few slots on a healthy devnet)
 - ✅ Each validator produces blocks for their slots
 
 ### Sync Recovery (~90-120s)
@@ -139,25 +139,13 @@ sleep 10  # Wait for sync
 # Quick status
 .claude/skills/test-pr-devnet/scripts/check-status.sh
 
-# Detailed analysis (use devnet-log-review skill in lean-quickstart)
-cd $LEAN_QUICKSTART
+# Detailed analysis (use this repo's devnet-log-review skill; dump logs first)
+for node in zeam_0 ream_0 qlean_0 ethlambda_0; do
+    docker logs "$node" > "${node}.log" 2>&1
+done
 .claude/skills/devnet-log-review/scripts/analyze-logs.sh
 ```
 
-## Protocol Compatibility
-
-| Client | Status | Gossipsub | BlocksByRoot |
-|--------|--------|-----------|--------------|
-| ream | ✅ Full | ✅ Full | ✅ Full |
-| zeam | ✅ Full | ✅ Full | ⚠️ Limited |
-| qlean | ✅ Full | ✅ Full | ⚠️ Limited |
-| ethlambda | ✅ Full | ✅ Full | ✅ Full |
-
-**Notes:**
-- zeam/qlean BlocksByRoot errors are expected (not a blocker)
-- ream ↔ ethlambda BlocksByRoot should work perfectly
-- All clients use Gossipsub for block propagation
-
 ## Verification Checklist
 
 | Check | Command | Expected |
@@ -256,5 +244,5 @@ docker logs ethlambda_0 2>&1 | grep -i "peer\|connection" | head -20
 
 ## References
 
-- **[ethlambda CLAUDE.md](../../CLAUDE.md)** - Development workflow, detailed debugging commands
-- **[lean-quickstart devnet-log-review](../../../lean-quickstart/.claude/skills/devnet-log-review/SKILL.md)** - Comprehensive log analysis
+- **[ethlambda CLAUDE.md](../../../CLAUDE.md)** - Development workflow, detailed debugging commands
+- **[devnet-log-review](../devnet-log-review/SKILL.md)** - Comprehensive log analysis (in this repo)

.github/PULL_REQUEST_TEMPLATE.md

@@ -23,4 +23,4 @@
 
 - [ ] Ran `make fmt` — clean
 - [ ] Ran `make lint` (clippy with `-D warnings`) — clean
-- [ ] Ran `cargo test --workspace --release` — all passing
+- [ ] Ran `make test` (`cargo test --workspace --profile release-fast`) — all passing

.github/actions/run-fixture-tests/action.yml

@@ -10,12 +10,43 @@ runs:
     - name: Get leanSpec fixtures release info
       id: fixtures-release
       shell: bash
+      env:
+        # Authenticate the API call: unauthenticated requests share the runner
+        # IP's low rate-limit pool, which is the usual cause of transient failures.
+        GH_TOKEN: ${{ github.token }}
       run: |
+        set -euo pipefail
         api_url="https://api.github.com/repos/leanEthereum/leanSpec/releases/latest"
-        json=$(curl -sL "$api_url")
-        fixtures_url=$(echo "$json" | python3 -c "import sys,json; j=json.load(sys.stdin); print(next(a.get('browser_download_url') for a in j.get('assets',[]) if a.get('name')=='fixtures-prod-scheme.tar.gz'))")
-        sha_url=$(echo "$json" | python3 -c "import sys,json; j=json.load(sys.stdin); print(next(a.get('browser_download_url') for a in j.get('assets',[]) if a.get('name')=='fixtures-prod-scheme.tar.gz.sha256'))")
-        sha=$(curl -sL "$sha_url" | cut -d' ' -f1)
+
+        # -f fails on HTTP errors (so an error body is never captured as data) and
+        # --retry rides out transient network/5xx hiccups. Fail loudly, since a
+        # command substitution in an assignment does not trip `set -e` on its own.
+        json=$(curl -sSL -f --retry 5 --retry-all-errors \
+          -H "Accept: application/vnd.github+json" \
+          -H "Authorization: Bearer $GH_TOKEN" \
+          "$api_url") \
+          || { echo "::error::Failed to fetch leanSpec latest release metadata from $api_url"; exit 1; }
+
+        asset_url() {
+          echo "$json" | python3 -c \
+            "import sys,json; name=sys.argv[1]; j=json.load(sys.stdin); print(next(a['browser_download_url'] for a in j.get('assets',[]) if a.get('name')==name))" \
+            "$1"
+        }
+        fixtures_url=$(asset_url "fixtures-prod-scheme.tar.gz") \
+          || { echo "::error::Release is missing the fixtures-prod-scheme.tar.gz asset"; exit 1; }
+        sha_url=$(asset_url "fixtures-prod-scheme.tar.gz.sha256") \
+          || { echo "::error::Release is missing the fixtures-prod-scheme.tar.gz.sha256 asset"; exit 1; }
+
+        sha=$(curl -sSL -f --retry 5 --retry-all-errors "$sha_url" | cut -d' ' -f1) \
+          || { echo "::error::Failed to download the fixtures checksum from $sha_url"; exit 1; }
+
+        # Validate before writing: a transient HTML error page captured as $sha
+        # previously corrupted $GITHUB_OUTPUT ("Invalid format '<!--'").
+        if [[ ! "$sha" =~ ^[0-9a-fA-F]{64}$ ]]; then
+          echo "::error::Expected a 64-char hex SHA256 for the fixtures archive, got: '$sha'"
+          exit 1
+        fi
+
         {
           echo "url=$fixtures_url"
           echo "sha_url=$sha_url"
@@ -39,8 +70,8 @@ runs:
         fixtures_url="${{ steps.fixtures-release.outputs.url }}"
         sha_url="${{ steps.fixtures-release.outputs.sha_url }}"
         echo "Downloading fixtures from $fixtures_url"
-        curl -L -f -o "$tmpdir/fixtures-prod-scheme.tar.gz" "$fixtures_url"
-        curl -L -f -o "$tmpdir/fixtures-prod-scheme.tar.gz.sha256" "$sha_url"
+        curl -L -f --retry 5 --retry-all-errors -o "$tmpdir/fixtures-prod-scheme.tar.gz" "$fixtures_url"
+        curl -L -f --retry 5 --retry-all-errors -o "$tmpdir/fixtures-prod-scheme.tar.gz.sha256" "$sha_url"
         expected=$(cut -d' ' -f1 "$tmpdir/fixtures-prod-scheme.tar.gz.sha256")
         actual=$(sha256sum "$tmpdir/fixtures-prod-scheme.tar.gz" | awk '{print $1}')
         if [ "$expected" != "$actual" ]; then
@@ -73,7 +104,7 @@ runs:
     - name: Setup Rust
       uses: dtolnay/rust-toolchain@master
       with:
-        toolchain: "1.92.0"
+        toolchain: "1.97.1"
 
     - name: Setup cache
       uses: Swatinem/rust-cache@v2

.github/workflows/ci.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@master
         with:
-          toolchain: "1.92.0"
+          toolchain: "1.97.1"
           components: rustfmt, clippy
 
       - name: Setup cache

.github/workflows/daily_loc_report.yml

@@ -39,7 +39,7 @@ jobs:
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@master
         with:
-          toolchain: "1.92.0"
+          toolchain: "1.97.1"
 
       - name: Setup cache
         uses: Swatinem/rust-cache@v2

.github/workflows/docker_publish.yaml

@@ -27,15 +27,33 @@ env:
 
 jobs:
   build-image:
-    name: Build Docker image (${{ matrix.arch }})
+    name: Build Docker image (${{ matrix.arch.name }}, ${{ matrix.variant.name }})
     strategy:
       matrix:
-        include:
+        arch:
           - runner: ubuntu-latest
-            arch: amd64
+            name: amd64
           - runner: ubuntu-22.04-arm
-            arch: arm64
-    runs-on: ${{ matrix.runner }}
+            name: arm64
+        # Each tag is published twice: once as the regular image and once as a
+        # Shadow-simulator-compatible image (tag suffixed "-shadow"). The shadow
+        # build args mirror the `shadow-docker-build` Makefile target. LOCKED=
+        # builds the shadow variant unlocked (the quinn-udp [patch] is absent
+        # from Cargo.lock; see Dockerfile), so -shadow images are not
+        # reproducible and should not be treated as equivalent-security
+        # artifacts to the regular tags.
+        variant:
+          - name: default
+            suffix: ""
+            build_args: ""
+          - name: shadow
+            suffix: "-shadow"
+            build_args: |
+              SHADOW=1
+              FEATURES=shadow-integration
+              NO_DEFAULT_FEATURES=--no-default-features
+              LOCKED=
+    runs-on: ${{ matrix.arch.runner }}
 
     steps:
       - name: Checkout repository
@@ -53,11 +71,14 @@ jobs:
 
       - name: Prepare tags
         id: prep
+        env:
+          SUFFIX: ${{ matrix.variant.suffix }}
+          ARCH: ${{ matrix.arch.name }}
         run: |
           TAGS=""
           IFS=',' read -ra TAG_ARRAY <<< "${TAGS_INPUT}"
           for t in "${TAG_ARRAY[@]}"; do
-            TAGS="${TAGS}${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${t}-${{ matrix.arch }},"
+            TAGS="${TAGS}${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${t}${SUFFIX}-${ARCH},"
           done
           TAGS="${TAGS%,}"  # Remove trailing comma
           echo "tags=${TAGS}" >> $GITHUB_OUTPUT
@@ -70,11 +91,12 @@ jobs:
           build-args: |
             GIT_COMMIT=${{ github.sha }}
             GIT_BRANCH=${{ github.ref_name }}
+            ${{ matrix.variant.build_args }}
           push: true
           tags: ${{ steps.prep.outputs.tags }}
-          platforms: linux/${{ matrix.arch }}
-          cache-from: type=gha,scope=${{ matrix.arch }}
-          cache-to: type=gha,scope=${{ matrix.arch }},mode=max
+          platforms: linux/${{ matrix.arch.name }}
+          cache-from: type=gha,scope=${{ matrix.arch.name }}-${{ matrix.variant.name }}
+          cache-to: type=gha,scope=${{ matrix.arch.name }}-${{ matrix.variant.name }},mode=max
 
   publish-manifest:
     name: Create and push multi-arch manifest
@@ -95,18 +117,24 @@ jobs:
         run: |
           IFS=',' read -ra TAG_ARRAY <<< "${TAGS_INPUT}"
           FIRST_TAG="${TAG_ARRAY[0]}"
+          SHORT="${SHORT_SHA::7}"
 
-          # Create manifest for first tag with SHA tag
-          docker buildx imagetools create \
-            -t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${FIRST_TAG} \
-            -t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:sha-${SHORT_SHA::7} \
-            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${FIRST_TAG}-amd64 \
-            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${FIRST_TAG}-arm64
-
-          # Create manifests for remaining tags
-          for t in "${TAG_ARRAY[@]:1}"; do
+          # Publish each tag twice: the regular image and its "-shadow" twin.
+          # These suffixes must stay in sync with the `variant` matrix suffixes
+          # in the build-image job above: a new variant must be added in both.
+          for suffix in "" "-shadow"; do
+            # First tag also gets an immutable sha-<sha> tag.
             docker buildx imagetools create \
-              -t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${t} \
-              ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${t}-amd64 \
-              ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${t}-arm64
+              -t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${FIRST_TAG}${suffix} \
+              -t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:sha-${SHORT}${suffix} \
+              ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${FIRST_TAG}${suffix}-amd64 \
+              ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${FIRST_TAG}${suffix}-arm64
+
+            # Remaining tags.
+            for t in "${TAG_ARRAY[@]:1}"; do
+              docker buildx imagetools create \
+                -t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${t}${suffix} \
+                ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${t}${suffix}-amd64 \
+                ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${t}${suffix}-arm64
+            done
           done