From 55bccc821273c4a2c89a11fc7e73f1eeaa10b0e4 Mon Sep 17 00:00:00 2001 From: adust09 Date: Tue, 13 Oct 2026 20:39:47 +0900 Subject: [PATCH] docs(sync): align lifecycle comments with runtime behavior 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. --- src/lean_spec/node/node.py | 4 ++-- src/lean_spec/node/sync/service.py | 20 +++++++++++++++----- src/lean_spec/node/sync/states.py | 19 ++++++------------- 3 files changed, 23 insertions(+), 20 deletions(-) diff --git a/src/lean_spec/node/node.py b/src/lean_spec/node/node.py index 71cc98e7c..0ac876f53 100644 --- a/src/lean_spec/node/node.py +++ b/src/lean_spec/node/node.py @@ -193,8 +193,8 @@ def from_genesis(cls, config: NodeConfig) -> Node: """ Create a fully-wired node from genesis configuration. - If a database path is provided and contains existing state, the node - resumes from the persisted state. Otherwise, it starts fresh from genesis. + Store selection prefers persisted state, then a checkpoint anchor, then fresh genesis. + All three startup paths enable gossip before the first peer status exchange. Args: config: Node configuration with genesis parameters. diff --git a/src/lean_spec/node/sync/service.py b/src/lean_spec/node/sync/service.py index 5beeef9e2..0579cce3a 100644 --- a/src/lean_spec/node/sync/service.py +++ b/src/lean_spec/node/sync/service.py @@ -96,10 +96,20 @@ class SyncService: """Async callback for publishing aggregated attestations, or None when no publisher is wired.""" state: SyncState = field(default=SyncState.IDLE) - """Current sync state. Defaults to IDLE, awaiting peer status.""" + """ + Current sync phase. + + Default construction awaits peer status. + Immediate gossip startup overrides the initial phase. + """ genesis_start: bool = field(default=False) - """When True, start in SYNCING state to accept gossip without waiting for peers.""" + """ + Enable gossip processing immediately at startup. + + The node enables this for genesis, database recovery, and checkpoint anchors. + The flag selects the initial phase independently of the store source. + """ _backfill: BackfillSync | None = field(default=None) """Backfill syncer instance (created lazily).""" @@ -159,7 +169,7 @@ class SyncService: """ def __post_init__(self) -> None: - """Wire sub-components and apply the genesis-start state hint.""" + """Sync component wiring and initial gossip eligibility.""" # Seed the persisted-head tracker from disk so a restarted node # diffs its slot index against the chain the database last saw. if self.database is not None: @@ -177,8 +187,8 @@ def __post_init__(self) -> None: process_block=self.process_block, ) - # Genesis validators already hold the full genesis state. - # They process gossip blocks immediately without a peer status exchange. + # Every node startup path already supplies a local store. + # Immediate gossip processing also lets local validator callbacks process their products. if self.genesis_start: self.state = SyncState.SYNCING diff --git a/src/lean_spec/node/sync/states.py b/src/lean_spec/node/sync/states.py index 790f02d4a..56dcda15f 100644 --- a/src/lean_spec/node/sync/states.py +++ b/src/lean_spec/node/sync/states.py @@ -7,24 +7,17 @@ class SyncState(Enum): """ - Three-phase progression for the sync service. + Sync lifecycle and gossip eligibility. - Lifecycle: + Peer status activates a service that starts idle. + A finalized-slot gap resumes syncing after the service catches up. - IDLE -> SYNCING -> SYNCED - ^ | | - +---------+---------+ - - - IDLE: no peers connected, or shutdown requested. - - SYNCING: active block processing and backfill driven by gossip. - - SYNCED: caught up to the network finalized slot. - - Either active state may fall back to IDLE on disconnect. - SYNCED falls back to SYNCING when a gap reappears. + Peer disconnection preserves the current phase. + Shutdown stops the service tasks while preserving the phase. """ IDLE = auto() - """No peers connected, or shutdown requested.""" + """Initial phase awaiting peer status when immediate gossip processing is disabled.""" SYNCING = auto() """Active block processing and backfill driven by gossip.""" SYNCED = auto()