Skip to content

docs(sync): align lifecycle comments with runtime behavior - #1214

Open
adust09 wants to merge 1 commit into
leanEthereum:mainfrom
adust09:docs/sync-lifecycle-20261013-2029
Open

adust09 wants to merge 1 commit into
leanEthereum:mainfrom
adust09:docs/sync-lifecycle-20261013-2029

Conversation

@adust09

@adust09 adust09 commented Oct 13, 2026

Copy link
Copy Markdown
Contributor

Summary

Correct the sync lifecycle descriptions to match the existing runtime behavior.

  • Describe idle as the initial phase when immediate gossip startup is disabled.
  • Document that peer disconnection and shutdown preserve the current sync phase.
  • Clarify that immediate gossip startup covers fresh genesis, database recovery, and checkpoint anchors.
  • Explain why accepting gossip immediately also allows local validator callbacks to process their products.

Runtime behavior stays unchanged. The patch touches comments and docstrings in three source files.

Motivation

The previous lifecycle description associated idle with peer disconnection and shutdown. The network service removes disconnected peers while preserving the sync phase, and node shutdown stops service tasks while preserving that phase.

The node also enables immediate gossip startup for every store source. Describing this as exclusive to genesis validators can lead downstream clients to implement different startup behavior.

Validation

  • uv tool run --from just-bin just check
  • uv run --locked --group test pytest tests/node/sync/test_states.py tests/node/sync/test_service.py tests/node/networking/service/test_service.py tests/node/test_node.py --no-cov -q (126 passed)
  • Compared the Python AST of each modified file against the base, excluding standalone documentation strings: executable AST unchanged.
  • git diff --check
  • uv.lock unchanged.
  • Independent read-only review completed with no findings.

The lifecycle descriptions tied idle to peer disconnection and shutdown, while the runtime preserves the current phase. Clarify immediate gossip startup for genesis, persisted state and checkpoint anchors so client implementers can follow the existing behavior.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant