[spencer-tb]

Description

Summary

Merges the fill side of the projects/zkevm framework tier: the execution witness types, the fixture fields and the fill orchestration needed to carry witnesses. Deliberately nothing the EIP process governs. Witness generation itself (the EELS stateless modules) stays on its EIP branch.

With no witness emitter present every new field stays None and is excluded from fixture output. The machinery is dormant until a transition tool emits a witness.

Key Notes

• Zero changes under src/. Nothing outside packages/testing and docs/ is touched.
• Default fills are byte for byte identical to the base branch, fixture hashes included.
• The framework never imports spec code tied to one fork. Stateless guest operations are an optional backend capability (the StatelessBackend protocol) resolved at the point of use. The EELS implementation lands with the witness generation tier, where the spec side already resolves forks by name. The branch type checks fully with no mypy overrides.
• One enabler is carried ahead of its consumer on purpose. Environment preserves extra_data and the header reads it from the env, because the witness tier t8n builds the stateless input header from env fields. Landing the carry here means that tier ships whole.
• just static clean, full mypy clean, all framework unit tests pass.

Changes vs projects/zkevm

• Witness generation is opt in behind a new fill --stateless flag, off by default, symmetric with the consume side. Upstream fills generate witnesses on every run with only a per test opt out, which doubles fill time, churns every fixture hash and corrupts opcode counts. With the flag off default fills are byte for byte unchanged, and even with it on the machinery stays dormant until an emitter exists.
• The fork specific guest bridge is gone. Upstream's fill pipeline imports the EELS Amsterdam stateless modules directly to rerun the guest, rebuild inputs and decode outputs. Here those become six operations on an optional StatelessBackend capability protocol on the transition tool interface, the same channel everything else uses to reach the spec. Backends gain guest support by implementing the protocol. Unsupported backends are rejected with a typed error at the point of use, which is unreachable for fills that produced no guest payloads.
• The fallback artifact builder is dropped as vestigial. The EELS t8n always emits both stateless byte fields beside a witness, and no other backend emits a witness at all.
• Implicit witness codes are derived from system_contracts() minus per EIP exemptions instead of a flat latest fork list. EIP-6110's deposit contract is exempt because it is log scraped and never executed. Future forks inherit correct expectations automatically.
• The post t8n stateless pipeline collapses behind one facade. The stateless surface of blockchain.py is two calls plus the data model, and the trust path gate moves into the stateless module.
• A typed StatelessValidationError replaces bare Exception raises throughout the orchestration.
• The skip_stateless_validation marker is registered. Upstream applies it unregistered, so the decorator usage in its own test suite warns and errors under --strict-markers. A comment records why the gas heavy system contract variants skip: their oversized mock contracts exceed the SSZ code size bound of the stateless input.
• The stateless fixture fields are documented across all four affected fixture format pages, including the rlp_decoded rule that invalid blocks carry the fields at the top level only.
• New unit tests, notably:
  • test_supporting_backend_satisfies_the_capability, test_unsupporting_backend_is_rejected and test_partial_backend_is_rejected cover the StatelessBackend capability contract
  • test_execution_witness_implicit_code_addresses covers the per fork implicit code derivation, EIP by EIP
  • test_environment_fork_requirements_preserve_extra_data covers the env extra data carry
• Assorted structure cleanups vs upstream. The three identical mutated expectation assertions fold into one loop, a one test expectation file merges into test_execution_witness.py, and the two scoped pyproject mypy overrides from upstream are unnecessary once the bridge is gone.

Deferred with the witness generation tier: the pytester fill tests that assert witness content (they need a real emitter), the EELS implementation of the backend operations, and the consume side, which follows separately.

Related Issues or PRs

N/A.

Checklist

• Ran fast static checks to avoid CI fails, see Code Standards & Verifying Changes: just static
• PR title has the form <type>(<area>): <title>, where <type> and <area> come from an appropriate C-<type>, respectively A-<area>, label. The title should match the target squash commit message.

Cute Animal Picture