Skip to content

refactor(node/chain): simplify the chain service loop and docs#1106

Merged
tcoratger merged 1 commit into
leanEthereum:mainfrom
tcoratger:refactor/chain-service-clarity
Jun 16, 2026
Merged

refactor(node/chain): simplify the chain service loop and docs#1106
tcoratger merged 1 commit into
leanEthereum:mainfrom
tcoratger:refactor/chain-service-clarity

Conversation

@tcoratger

Copy link
Copy Markdown
Collaborator

Summary

Clarity and documentation pass over the ChainService that drives consensus timing. No behavior change to the timing logic; the existing chain tests pass (with one test updated for a simplified return contract).

Chain service (chain/service.py)

  • Retire the Interval | None sentinel. _initial_tick now returns the anchor interval Interval(0) before genesis instead of None. This collapses the run() loop guard into a single "wait unless a strictly-new interval is due" predicate and removes the post-sleep double-read of the interval. Verified safe: the clock clamps elapsed time to zero before genesis, so total_intervals() never underflows.
  • Trim verbose docs. The multi-paragraph _tick_to docstring shrinks to three lines (the skip/yield rationale already lives in the inline comments at the exact lines), stop() becomes one line, and several run() comment blocks lose their narration. All the genuine non-obvious rationale is preserved: the wall clock can step backward, why skipping stale intervals is safe, why we yield and re-read the store, and why catch-up aggregates are discarded.

Sync service (sync/service.py)

  • Document a concurrency invariant at the gossip-block store write-back: the processed path never awaits, so a concurrent clock tick cannot advance the store between the read and the write-back. This was verified by exhaustive path analysis (the only suspending paths return processed=False); the comment guards the emergent safety against a future change that makes block processing await.

Testing

  • just check passes (ruff, format, ty, codespell, mdformat).
  • uv run pytest tests/node/chain tests/node/sync — all pass.

🤖 Generated with Claude Code

- Drop the Interval | None sentinel: _initial_tick returns the anchor
  interval (0) before genesis, so the run loop guard collapses to a single
  "wait unless a strictly-new interval is due" predicate and the post-sleep
  re-read disappears.
- Trim the verbose docstrings and comments to the project documentation
  rules, keeping only the non-obvious rationale (clock can step backward,
  why skipping stale intervals is safe, why we yield and re-read the store,
  why catch-up aggregates are discarded).
- Update the startup-tick test for the new return contract.

Also document the concurrency invariant at the gossip-block write-back: the
processed path never awaits, so a concurrent clock tick cannot advance the
store between the read and the write-back. No behavior change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@tcoratger tcoratger merged commit 46c67cd into leanEthereum:main Jun 16, 2026
13 of 14 checks passed
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