docs: add slots and intervals chapter

[MegaRedHand]

🗒️ Description / Motivation

The book explained what the consensus algorithms do (3SF-mini, LMD-GHOST) but never when
each duty is due. This adds a Slots and Intervals chapter documenting the 5-interval
structure of a slot: who acts in each interval, what they publish, and why the intervals are
ordered the way they are.

Writing it surfaced that lmd_ghost.md's ethlambda scheduling section was stale: it still
described 4 intervals of 1 second with the old duty order (safe target at 2, end of slot at
3) and named the long-gone LatestNewAttestations / LatestKnownAttestations tables. Linking
the two documents would have made them contradict each other, so that section is updated here
too.

What Changed

• docs/slots_and_intervals.md (new) — duty table (interval / offset / who acts / what it
  publishes), slot timeline diagram, and one section per interval. Each section covers the
  mechanics plus the reasoning: why aggregation earns its own interval, what the safe target's
  two-thirds threshold buys, why promotion is staged. ethlambda-specific behaviour lives in
  blockquotes, following the convention the other consensus docs use.
• docs/SUMMARY.md — new first chapter of the Consensus section, since it is the
  prerequisite for the other two.
• docs/introduction.md — Consensus bullet now leads with it.
• docs/lmd_ghost.md — interval grid corrected to 5 × 800 ms, duty order and detailed
  sequence updated (aggregation at 2, safe target at 3, end of slot at 4), promotion points
  corrected to intervals 0 and 4, and the attestation-pipeline blockquote now names the
  in-memory new_payloads / known_payloads buffers instead of the removed tables.

Correctness / Behavior Guarantees

No code changes: documentation only.

Every claim was checked against the source rather than against the older docs:

Claim	Source
5 intervals of 800 ms	INTERVALS_PER_SLOT, MILLISECONDS_PER_INTERVAL in crates/common/types/src/constants.rs
Interval → duty mapping	SlotInterval and the tick dispatch in crates/blockchain/src/lib.rs
Promotion at intervals 0 (proposer) and 4	store::on_tick in crates/blockchain/src/store.rs
Round-robin proposer slot % num_validators	current_proposer in crates/blockchain/state_transition/src/lib.rs
Safe target: fresh votes, ⌈2V/3⌉ threshold; head: known votes, no threshold	update_safe_target / update_head in crates/blockchain/src/store.rs
Block body caps distinct attestation data	MAX_ATTESTATIONS_DATA in crates/common/types/src/block.rs
Subnet = validator_index % attestation_committee_count	crates/net/p2p/src/gossipsub/handler.rs
Gossip topics block / attestation_{id} / aggregation	crates/net/p2p/src/gossipsub/messages.rs

Tests Added / Run

• make docs — clean, including the mdbook-linkcheck2 pass (warning-policy = "error").
• Verified every cross-document anchor resolves against an id= in the rendered HTML.
• Checked both ASCII diagrams with a box-alignment script (multi-byte box characters make
  eyeballing unreliable).

Related Issues / PRs

None.

✅ Verification Checklist

• Ran make fmt — N/A, no Rust touched
• Ran make lint (clippy with -D warnings) — N/A, no Rust touched
• Ran make test (cargo test --workspace --profile release-fast) — N/A, no Rust touched

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.

[github-actions]

🤖 Codex Code Review

1. Low: docs/slots_and_intervals.md says interval-1 votes “are imported by aggregators” and that aggregators verify them. The implementation is broader: every subscriber validates attestation gossip, and every validator subscribes to its own committee subnet even when not acting as an aggregator; only persistence for later interval-2 aggregation is aggregator-gated. This wording blurs mesh participation vs. aggregation and could mislead operators about validation load and subnet behavior. See crates/net/p2p/src/lib.rs, crates/blockchain/src/store.rs, and crates/blockchain/src/lib.rs.

2. Low: docs/slots_and_intervals.md says early aggregation can start “once two thirds of the signatures are in,” but the actual trigger is narrower: one attestation-data group must reach a 2/3 threshold of the votes expected from this node’s subscribed subnets. That distinction matters for nodes subscribed to multiple subnets and for slots with competing vote groups. See crates/blockchain/src/lib.rs.

Other than those doc-precision issues, I didn’t find code-correctness, security, or consensus-behavior regressions in this PR. The 5-interval timing model and the interval-0/4 promotion points match the current implementation.

---

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

[github-actions]

🤖 Claude Code Review

Review: PR 578 — docs: add slots and intervals chapter

Scope: Documentation-only (docs/SUMMARY.md, docs/introduction.md, docs/lmd_ghost.md, new docs/slots_and_intervals.md). No Rust code is touched, so the usual correctness/security/performance/memory-safety categories don't apply here — I instead verified every factual/technical claim in the new prose against the current source.

Verification performed

I cross-checked the PR's claims against the actual implementation rather than trusting the PR description's table:

• 5 intervals × 800 ms: confirmed in crates/common/types/src/constants.rs (INTERVALS_PER_SLOT = 5, MILLISECONDS_PER_INTERVAL = 800).
• Interval → duty mapping (BlockPublication=0, AttestationProduction=1, Aggregation=2, SafeTargetUpdate=3, EndOfSlot=4): matches SlotInterval and its dispatch in crates/blockchain/src/lib.rs:88-125,371-461 exactly, including the subtle "build happens at the previous slot's interval 4" detail.
• Promotion points (intervals 0 and 4) and buffer names (new_payloads/known_payloads, extract_latest_new_attestations): confirmed in crates/blockchain/src/store.rs — this directly fixes the stale LatestNewAttestations/LatestKnownAttestations table names that no longer exist.
• Safe target's 2/3 threshold + reading the unpromoted buffer: confirmed in update_safe_target (store.rs:150-171), which calls extract_latest_new_attestations (not the promoted set) with min_target_score = (num_validators * 2).div_ceil(3).
• Subnet formula validator_index % attestation_committee_count: confirmed in crates/net/p2p/src/gossipsub/handler.rs:141.
• MAX_ATTESTATIONS_DATA = 8: confirmed in crates/common/types/src/block.rs:109.
• EARLY_AGGREGATION_WINDOW / two-thirds early-trigger / soft deadline lets in-flight proofs finish: confirmed in crates/blockchain/src/aggregation.rs and maybe_start_early_aggregation in lib.rs:584-624.
• Anchor links (#interval-0-block-proposal, #why-staged-promotion, #safe-target-selection, #recap-attestation-anatomy, etc.) all resolve to headers that exist with the expected mdbook slug.

Every claim I checked held up against the current source. No inaccuracies, stale references, or broken cross-links found.

Observations

• The rewrite correctly catches and fixes the drift the PR description calls out: lmd_ghost.md previously described 4×1s intervals with the old duty order and referenced tables that were removed from the codebase (LatestNewAttestations/LatestKnownAttestations). The new text matches the real new_payloads/known_payloads Store buffers and the corrected interval numbering (aggregation at 2, safe target at 3, end-of-slot at 4).
• The new chapter's blockquote convention (implementation-agnostic body + > **In ethlambda:** asides) is followed consistently with the existing docs style.
• The "chain never justifies if no validator aggregates" callout in the new doc is consistent with the "Aggregator Flag Required for Finalization" gotcha already documented in CLAUDE.md — good consistency across docs.
• Diagrams (box-drawing grids) render consistently in both files with matching column widths and interval boundaries.

No issues to flag. This is a well-researched, source-verified documentation update.

---

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