Sync gate: stall-window fencepost in the docs, `future` peers never age out, two doc typos

Open
#813 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 6 days

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
65/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
rust

Research direction

Start with the referenced sync gate code in crates/blockchain/src/sync_status.rs and the peer tracking code in crates/net/p2p/src/peer_heads.rs, then check their tests for stall timing and expiry behavior. The issue allows either changing the stall count or clarifying the docs; also expire future peer heads and fix the two specified documentation typos. Done when the timing is consistent, inactive future peers age out, and the documentation renders and reads correctly.

Written by the indexing model from the issue text.

Description

Leftovers from the last review round of lambdaclass/ethlambda#791, which stopped at the review-round cap. None of them changes which way the gate decides, apart from one slot of timing in item 1.

  1. The stall window's fencepost.
    • StallCount::count counts the first behind judgment as 0 (crates/blockchain/src/sync_status.rs:198), and the backstop trips on behind_for > stall_window (sync_status.rs:358).
    • A node whose head stays flat therefore reads syncing, skipping its duties, on 17 distinct slots on lean (33 on beacon). a_lead_that_never_turns_into_progress_is_a_stall pins this (last_syncing = 100 + stall_window).
    • The docs say 16 slots: SyncThresholds::stall_window (crates/net/api/src/sync.rs), docs/spec_deviations.md, and .claude/skills/multi-server-devnet/references/node-health.md:94,108 ("after 16 slots of that").
    • Fix either side: count the first behind slot (start at 1, adjust the tests and the randomized bounds), or say "more than 16 slots" in the docs.
  2. PeerHeads::future never ages out (crates/net/p2p/src/peer_heads.rs:207).
    • A peer enters the set when its Status head is past the clock, and leaves it only on a later in-clock Status or its disconnect (record, forget, peer_heads.rs:231-234). The report lifetime that ages claims (PeerHeads::expire, peer_heads.rs:263) does not apply.
    • A connected peer that reported a future head once and then stopped answering therefore stays counted in lean_sync_peers_held_back{reason="future"} and in the slow-clock warning's majority.
    • The gate is unaffected, since a future head never counts.
    • Fix: keep the wall slot with each entry and drop it in expire with the claims.
  3. Typos.
    • docs/metrics.md, lean_sync_peers_held_back row: a comma is missing after "range requests that kept failing)", before "peers cooling down".
    • docs/spec_deviations.md: "consensus-specs has no sync gate, and the Beacon API leaves is_syncing to the client." needs a blank line before it. Without one it renders as part of the beacon paragraph above.
Dominant language
Rust
Stars
86
Forks
34
Avg merge
9d 20h
Merged PRs (30d)
77

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from lambdaclass/ethlambda

All issues in lambdaclass/ethlambda

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.