docs: clarify image tag descriptions

[MegaRedHand]

Summary

Clarifies the Docker image-tag wording in README.md and RELEASE.md:

• unstable is built from the latest main commit.
• latest / devnetX are the latest stable devnet images.
• Bumped the stale devnet3 "at the time of writing" and docker pull examples to devnet5 (the current devnet).

Notes

• Left untouched: Cargo.toml leansig devnet4 branch (real dependency), the devnet3/devnet4 test-ignore comment in encoding.rs, and the README "Older devnets" list (devnet1-4 are correctly the older ones; devnet5 is current).
• The new docs/spec_deviations.md page (and its SUMMARY.md index entry) was split into docs: add spec deviations page #499.

[github-actions]

🤖 Claude Code Review

All checks pass. This is a clean, well-formed documentation PR. Here's my review:

Review: PR 498 — docs: clarify image tags, add spec-deviations page to book

This is a documentation-only PR (no code changes), so the usual consensus-layer/correctness/security concerns don't apply. I verified the factual claims in the new content against the current codebase.

Verification of docs/spec_deviations.md

All code references check out precisely against current source:

• run_aggregation_worker — crates/blockchain/src/aggregation.rs:504 ✓
• AGGREGATION_DEADLINE = Duration::from_millis(750) — aggregation.rs:33 ✓
• MILLISECONDS_PER_INTERVAL = 800 — crates/blockchain/src/lib.rs:47 ✓
• cancel.is_cancelled() check inside the worker loop — aggregation.rs:519 ✓
• select_attestations — crates/blockchain/src/block_builder.rs:170 ✓
• enum Tier { Finalize = 1, Justify = 2, Build = 3 } — block_builder.rs:473 ✓
• EntryScore::ordering_key — block_builder.rs:517, and the described tier-dependent tuple ordering (Finalize/Justify: target → att_slot → new_voters; Build: new_voters → target → att_slot, data_root as final tiebreak) matches the actual match self.tier arms exactly ✓
• MAX_ATTESTATIONS_DATA = 8 — crates/common/types/src/block.rs:109 ✓

This is a meaningful improvement over the previous stale description (flat new-voters → target → att-slot order) — the new text correctly captures the tier-dependent ordering introduced by leanSpec #1149.

Other changes

• README.md / RELEASE.md: wording tweaks are accurate — unstable genuinely tracks latest main (not devnet-specific), and devnet3 → devnet5 bump matches the current pq-devnet-5 section already present in README.md.
• docs/SUMMARY.md: adding the missing spec_deviations.md entry under a new "Development" section is correct and necessary for mdBook to render the page at all — this was a real bug (orphaned page).

Minor nitpick

• docs/spec_deviations.md:9 — the file mixes the external repo path style: forks/lstar/spec.py and subspecs/chain/config.py are given without a repo/URL anchor, while the intro sentence references leanSpec via a full GitHub link. Consider either linking these paths back to the leanSpec repo or adding "(leanSpec)" inline for readers who land on this page without the earlier context. Very minor, not blocking.

No functional/correctness/security issues — nothing to flag. Approve.

---

Automated review by Claude (Anthropic) · sonnet · custom prompt

[github-actions]

🤖 Kimi Code Review

General: Documentation-only PR. Good practice documenting spec deviations explicitly—critical for consensus client auditability.

Item 1: Fragile line number references
docs/spec_deviations.md hard-codes line numbers (e.g., aggregation.rs:504, block_builder.rs:473). These will drift immediately on refactor.
Suggestion: Replace with permanent GitHub permalinks (e.g., https://github.com/lambdaclass/ethlambda/blob/<commit>/crates/...#L504) or at least use function names as searchable anchors:

"The worker run_aggregation_worker (aggregation.rs) spawns via tokio::task::spawn_blocking..."

Item 2: Missing equivalence verification details
The document states equivalence (e.g., "same XMSS proofs are produced") but doesn't describe how this is verified.
Suggestion: Add a "Verification" subsection noting if differential testing, property-based tests, or formal methods are used to ensure deviations don't violate consensus.

Item 3: Consensus parameter exposure
Documenting timing constants (AGGREGATION_DEADLINE = 750ms, MILLISECONDS_PER_INTERVAL = 800ms) is acceptable for open-source, but ensure these are clearly marked as non-specified implementation details (not consensus constants). Consider adding a warning block:

"These are implementation-specific timing parameters subject to change; they do not affect consensus validity."

Item 4: Consistency check
README.md and RELEASE.md updates are consistent regarding latest/unstable tag definitions and devnet5 upgrade. No issues.

Item 5: Documentation structure
The SUMMARY.md addition correctly places the new page under a "Development" section. Good separation of user vs. developer docs.

Conclusion: Approving with minor suggestions. The explicit documentation of deviations from leanSpec is essential for consensus safety. Address Item 1 (line number fragility) before merge if possible, or accept the maintenance burden.

---

Automated review by Kimi (Moonshot AI) · kimi-k2.5 · custom prompt

[github-actions]

🤖 Codex Code Review

1. docs/spec_deviations.md: “same XMSS proofs are produced” is stronger than the current implementation supports. The interval-2 path starts from snapshot_current_slot_aggregation_inputs() crates/blockchain/src/lib.rs, which only aggregates current-slot raw gossip signatures and explicitly ignores existing proofs / payload-only groups crates/blockchain/src/aggregation.rs crates/blockchain/src/aggregation.rs. So this is not just “same logic with a time budget”; it can produce a different aggregate set/shape even before cancellation fires. I’d reword this to describe the actual scope reduction, not just scheduling.

2. docs/spec_deviations.md: “up to MAX_ATTESTATIONS_DATA = 8 entries” is misleading for select_attestations(). The round loop is capped at 8 distinct AttestationData candidates crates/blockchain/src/block_builder.rs, but each winning candidate can contribute multiple proofs through extend_proofs_greedily() crates/blockchain/src/block_builder.rs. The one-entry-per-data cap is only re-established later in compact_attestations() / keep_best_proof_per_data() crates/blockchain/src/block_builder.rs crates/blockchain/src/block_builder.rs. I’d change this to “up to 8 distinct AttestationData selections” or move the cap explanation to the compaction/output stage.

Beyond those documentation mismatches, I did not see executable-path changes in this PR, so I have no code correctness or security findings against the Rust implementation itself. I did not run tests, since the diff is docs-only.

---

Automated review by OpenAI Codex · gpt-5.4 · custom prompt

[greptile-apps]

Greptile Summary

This is a documentation consistency pass that clarifies image-tag semantics, adds the missing spec_deviations.md page to the mdBook table of contents, and refreshes stale source-code line references in the spec-deviations doc.

• README.md / RELEASE.md: unstable is now clearly described as "built from the latest main commit," latest as the latest stable devnet image, and the stale devnet3 docker-pull example is bumped to devnet5.
• docs/SUMMARY.md: Adds a new Development section linking spec_deviations.md, which previously existed on disk but was invisible in the rendered book.
• docs/spec_deviations.md: Refreshes source-file line numbers (verified accurate against the current codebase) and corrects the attestation tie-break description to reflect the tier-dependent ordering now used in block_builder.rs.

Confidence Score: 5/5

Pure documentation update with no code changes; safe to merge.

All referenced source line numbers were verified accurate against the current codebase. The only observation is a cosmetic inconsistency in RELEASE.md where the devnetX inline examples still list devnet3/devnet4 while the docker-pull example was bumped to devnet5.

RELEASE.md — the devnetX inline examples are slightly stale relative to the updated docker-pull line.

Important Files Changed

Filename	Overview
README.md	Clarifies latest ("latest stable") and unstable ("built from the latest main commit") tag descriptions; no functional issues.
RELEASE.md	Updates latest/unstable bullet descriptions and bumps the docker-pull example from devnet3 to devnet5; the devnetX inline examples still list only devnet3, devnet4 while devnet5 is current — minor inconsistency.
docs/SUMMARY.md	Adds spec_deviations.md under a new Development section so the page renders in the mdBook; change is straightforward and correct.
docs/spec_deviations.md	New page describing async aggregation and attestation scoring deviations; all referenced line numbers verified accurate against current source (aggregation.rs:33/504/519, lib.rs:47, block_builder.rs:170/473/517, block.rs:109).

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    main[main branch commit] -->|CI build| unstable[ghcr.io/.../ethlambda:unstable]
    unstable -->|tested & promoted| devnetX["ghcr.io/.../ethlambda:devnetX (e.g. devnet5)"]
    devnetX -->|aliased| latest[ghcr.io/.../ethlambda:latest]
    main -->|every commit| sha[ghcr.io/.../ethlambda:sha-XXXXXXX]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    main[main branch commit] -->|CI build| unstable[ghcr.io/.../ethlambda:unstable]
    unstable -->|tested & promoted| devnetX["ghcr.io/.../ethlambda:devnetX (e.g. devnet5)"]
    devnetX -->|aliased| latest[ghcr.io/.../ethlambda:latest]
    main -->|every commit| sha[ghcr.io/.../ethlambda:sha-XXXXXXX]

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
RELEASE.md:26
The `devnetX` examples in the bullet still only list `devnet3` and `devnet4`, but the docker-pull example just below was bumped to `devnet5` (the current devnet). Readers who associate "at the time of writing" with these inline examples may be confused about whether devnet5 is supported by this tag.

```suggestion
- `devnetX` - the latest stable image built with `devnetX` support (e.g. `devnet4`, `devnet5`)
```

_{Reviews (1): Last reviewed commit: "docs: clarify image tags, add spec-devia..." | Re-trigger Greptile}