Skip to content

docs(sequencer-client): rewrite top-level and timing READMEs#23149

Merged
PhilWindle merged 3 commits into
merge-train/spartanfrom
palla/sequencer-readme-rewrite
May 13, 2026
Merged

docs(sequencer-client): rewrite top-level and timing READMEs#23149
PhilWindle merged 3 commits into
merge-train/spartanfrom
palla/sequencer-readme-rewrite

Conversation

@spalladino
Copy link
Copy Markdown
Contributor

Motivation

The top-level sequencer-client/README.md was years out of date — it still referred to single-block-per-slot building and made no mention of proposer pipelining or the multi-block checkpoint model. The timing-model README still documented both pipelined and non-pipelined scheduling even though the non-pipelined mode is about to be removed. New contributors (human or AI) lacked the context they need to make changes to block building.

Approach

Rewrote the top-level README from scratch following the package's readme-writer guidelines: slots / blocks / checkpoints, proposed vs checkpointed chain, an architecture diagram, the Sequencer work loop, CheckpointProposalJob lifecycle, per-block loop pseudocode, the SequencerPublisher Multicall3 bundling and sendRequestsAt semantics, events, configuration reference, and failure modes. Trimmed src/sequencer/README.md to cover only the pipelined timing model with formulas grounded in PipelinedCheckpointTimingModel and a corrected 72 s / 8 s walkthrough. Ran /codex for a critical review and fixed all flagged issues (last-sub-slot-is-not-cooldown, event-emit timing, config env-var names, attestation-deadline nuance, insufficient-valid-txs handling, publisher preCheck semantics).

Changes

  • sequencer-client: Replaced README.md with an architecture-first rewrite covering pipelining (build slot vs target slot, depth bound of 2, parent-invalidation discard), the per-slot job lifecycle, the publisher's Multicall3 flow, and the full config reference.
  • sequencer-client (sequencer): Replaced src/sequencer/README.md with a pipelining-only timing model. Documents timeReservedAtEnd, maxNumberOfBlocks, per-state deadlines, proposer-vs-committee parallel timeline, and timing-variation handling.

Rewrite the sequencer-client package README to document the current
multi-block-per-slot architecture and proposer pipelining flow, and trim
the timing-model README down to the pipelined case only since
non-pipelined scheduling is being removed.
@spalladino spalladino marked this pull request as ready for review May 12, 2026 21:54
@PhilWindle PhilWindle merged commit 99e99fd into merge-train/spartan May 13, 2026
22 checks passed
@PhilWindle PhilWindle deleted the palla/sequencer-readme-rewrite branch May 13, 2026 14:46
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.

2 participants