refactor(forks): add Spec delegator surface (Stage 4A of #686)#702
Merged
tcoratger merged 3 commits intoMay 2, 2026
Merged
Conversation
…#686) Adds the LstarSpec method surface that mirrors the existing State / Store / SignedBlock methods one-for-one: - State transition: state_transition, process_slots, process_block, process_block_header, process_attestations, build_block. - Forkchoice: on_block, on_tick, on_gossip_attestation, on_gossip_aggregated_attestation, produce_attestation_data, produce_block_with_signatures, get_proposal_head. - Block signatures: verify_signatures. Each method is a pure delegator to the corresponding container method. No call sites change — the new surface is unused initially. Stage 4B will rewrite call sites to go through the spec; Stage 4C will move the bodies in and replace literal Block/State/Store references with self.*_class(...). Tests use unittest.mock.patch.object to verify each delegator forwards its arguments unchanged and returns the container method's result verbatim. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Rewrite the per-method docstrings on the fork-class delegators and the delegator test suite to follow the project documentation rules: - Each docstring describes the operation in plain English. - No explicit class or method names that rot when renamed. - No issue/stage references that belong in the PR description. - No banner-style separator comments inside the class body. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Extend ForkProtocol with class pointers for the inner container types (BlockBody, BlockHeader, AggregatedAttestations, AttestationSignatures) and the matching structural protocols. Hook them up on LstarSpec. This is the scaffolding the next stages of leanEthereum#686 need so that moving container method bodies into the spec can replace literal Block(...), BlockBody(...), AggregatedAttestations(...) constructors with self.<name>_class(...) — keeping inheriting forks free to swap any single inner type without re-implementing the parent's logic. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
38 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Stage 4A of the multi-fork architecture refactor (#686): add the spec-class method surface that mirrors the existing container methods one-for-one. The surface is added as pure delegators — bodies stay on the containers, call sites are unchanged. Stage 4B will rewrite call sites to go through the spec; Stage 4C will move the bodies in.
The new
LstarSpecmethods:state_transition,process_slots,process_block,process_block_header,process_attestations,build_blockon_block,on_tick,on_gossip_attestation,on_gossip_aggregated_attestation,produce_attestation_data,produce_block_with_signatures,get_proposal_headverify_signaturesEach delegator is a one-line forwarder to the existing State / Store / SignedBlock method.
Why concrete on
LstarSpec(not abstract onForkProtocol)Following Vision B (the chosen direction in #686): the architecture's central use case is "Devnet5 inherits from Devnet4 and overrides one attribute". Concrete delegators on
LstarSpecpropagate naturally through subclass inheritance —Devnet5Spec(LstarSpec)gets all of these for free until it needs to override one.Adding abstract declarations on
ForkProtocolwould force every fork class to redeclare all delegators and would clash with the structural-protocol parameter types (which don't expose container methods likestate.process_block). It is also premature without a second fork to validate the contract.Tests
tests/lean_spec/forks/test_lstar_spec_delegators.pyadds 14 tests usingunittest.mock.patch.objectto verify each delegator:The mock pattern proves delegation precisely without depending on the underlying container behaviour — which is exactly what Stage 4A is about.
Test plan
uvx tox -e all-checks(ruff check + format + ty + codespell + mdformat) green.uv run pytest tests/lean_spec/forks/— 32 fork tests pass (18 existing + 14 new).uv run pytest tests/lean_spec/— 3276 unit tests pass.🤖 Generated with Claude Code