Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/lean_spec/node/node.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
20 changes: 15 additions & 5 deletions src/lean_spec/node/sync/service.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)."""
Expand Down Expand Up @@ -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:
Expand All @@ -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

Expand Down
19 changes: 6 additions & 13 deletions src/lean_spec/node/sync/states.py
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
Loading