Skip to content

engine: fix stale references in the REST-SSZ docs - #1

Open
LukaszRozmej wants to merge 1 commit into
mainfrom
engine-rest-ssz-doc-fixes
Open

LukaszRozmej wants to merge 1 commit into
mainfrom
engine-rest-ssz-doc-fixes

Conversation

@LukaszRozmej

Copy link
Copy Markdown
Owner

Editorial follow-up to ethereum#793, which merged with a few doc-level items from the implementer feedback still open. Both came out of implementing the REST+SSZ surface in Nethermind.

1. The worked byte example contradicts the status enum

refactor-ssz.md pins VALID = 0 and its Example A correctly shows status: 0x00, but refactor.md § "Example: submit a payload" describes the same 41-byte response as status (1 byte = 0x01, VALID). Since the point of that section is a byte-exact example, it is the version most likely to be copied into a test vector.

2. Stale v2 / fork-in-URL references

d39e9a27 moved the fork from the URL into Eth-Execution-Version and renumbered the base path to /engine/v1, but a few places still describe the earlier shape:

  • refactor-ssz.md was titled "Engine API v2 -- SSZ Container Sketches" and referred to "the Engine API v2 spec" / "the v2 API".
  • refactor.md's goals section still said the new API "puts the fork in the URL (/engine/v1/...)".
  • refactor-ssz.md linked #get-forkpayloadspayloadid, which no longer resolves — the heading is now GET /payloads/{payloadId}, and the doc's own table of contents already uses #get-payloadspayloadid.

This is the one that cost us real time: reading the goals section and the PR description table, we kept /engine/v2/{fork}/... while picking up the header move, so a CL following the draft got a 404 on every REST URL — and per the transition-window section a 404 reads as "this EL has no REST surface, fall back to JSON-RPC", making the divergence silent rather than loud.


No normative changes here. Three other items from that feedback are deliberately left out, since each needs a decision rather than an edit:

  • payload_id TTL vs the polling model — "valid until … the payload was retrieved" invalidates the token on the first GET, which makes the polling described a few lines above impossible. Review on engine: add Rest-SSZ spec ethereum/execution-apis#793 pointed at the polling reading ("a token ttl should be longer than a single get", engine: add Rest-SSZ spec ethereum/execution-apis#793 (comment)); a wording fix carrying that intent is ready to file separately.
  • 413 request-too-large vs 400 ssz-decode-error for the SSZ count limits (bodies.max_count, blobs.max_versioned_hashes), which are also the container MAX_* bounds — filed separately.
  • MAX_BAL_BYTES (2**30) being 16x MAX_REQUEST_BODY_SIZE (2**26), already listed as an open sketch question.

Editorial follow-ups to ethereum#793:

- the worked byte example claimed `status = 0x01` for VALID, while the
  normative enum in refactor-ssz.md pins `VALID = 0`
- refactor-ssz.md was still titled "Engine API v2", though the base
  path is `/engine/v1`
- the goals section still described the fork as living in the URL,
  which d39e9a2 moved into the `Eth-Execution-Version` header
- the `#get-forkpayloadspayloadid` link no longer resolves
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