Skip to content

docs(testing): align aggregation-bits vectors with doc-writer conventions#919

Merged
tcoratger merged 2 commits into
leanEthereum:mainfrom
tcoratger:docs-aggregation-bits-vector-conventions
Jun 10, 2026
Merged

docs(testing): align aggregation-bits vectors with doc-writer conventions#919
tcoratger merged 2 commits into
leanEthereum:mainfrom
tcoratger:docs-aggregation-bits-vector-conventions

Conversation

@tcoratger

Copy link
Copy Markdown
Collaborator

Motivation

Follow-up to #899. That PR added the aggregation-bits bounds vectors, but the documentation did not yet follow the consensus test-vector standard (Given/When/Then with zero body comments). This brings them in line and tightens a few related docstrings.

Changes

Test vectors (tests/consensus/lstar/state_transition/test_aggregation_bits.py)

  • Remove all inline body comments; the Given/When/Then docstring is the single source of truth.
  • Strip the "a client that…" divergence narration from every Then section so each states only the asserted outcome (rejection reason, or justified/finalized/tally for the valid case).
  • Move the bitfield layout and the zero-length-vs-all-false SSZ-encoding rationale into Given as atomic facts.
  • Add the bitfield-limit vs validator-registry distinction to the out-of-range vector's Given (index 4 is within the 4096 bitfield limit but past the 4-entry registry).

Framework (packages/testing/.../attestation_specs.py, state_transition.py)

  • Collapse the aggregation_bits field and resolver docstrings to terse, one-sentence-per-line phrasing (drop the usage clause).
  • Make is_final_block keyword-only on the block builder.

Spec (src/lean_spec/spec/forks/lstar/state_transition.py)

  • Note that signature verification normally rejects an out-of-range bit first, so the bounds check guards the unsigned state-transition path.

No behavior change: the four vectors fill and pass unchanged, and the determinism check passes.

Testing

  • uv run fill --fork=lstar -k test_aggregation_bits --clean: 4 passed, determinism check passes
  • just check: clean

tcoratger and others added 2 commits June 10, 2026 18:31
…ions

Follow-up to leanEthereum#899. Brings the aggregation-bits bounds vectors in line
with the consensus test-vector documentation standard:

- Drop all inline body comments from the test vectors; the
  Given/When/Then docstring is the single source of truth.
- Strip the "a client that..." narration from every Then section so it
  states only the asserted outcome (rejection reason or post-state).
- Move the bitfield layout and SSZ-encoding rationale into Given as
  atomic facts, and note the bitfield-limit vs registry distinction.
- Tighten the aggregation_bits field and resolver docstrings to terse
  one-sentence-per-line phrasing.
- Note in process_attestations that signature verification normally
  rejects an out-of-range bit first, so this guards the unsigned path.
- Make is_final_block keyword-only on the block builder.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Per the doc-writer rules, render the field's three behaviors as bullet
points instead of prose, and fix the summary line so it describes the
default (derived) case rather than only the verbatim override.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@tcoratger tcoratger merged commit 2810c20 into leanEthereum:main Jun 10, 2026
13 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