engine: fix stale references in the REST-SSZ docs - #1
Open
LukaszRozmej wants to merge 1 commit into
Open
LukaszRozmej wants to merge 1 commit into
LukaszRozmej wants to merge 1 commit into
Conversation
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
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
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.
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.mdpinsVALID = 0and its Example A correctly showsstatus: 0x00, butrefactor.md§ "Example: submit a payload" describes the same 41-byte response asstatus(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 referencesd39e9a27moved the fork from the URL intoEth-Execution-Versionand renumbered the base path to/engine/v1, but a few places still describe the earlier shape:refactor-ssz.mdwas 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.mdlinked#get-forkpayloadspayloadid, which no longer resolves — the heading is nowGET /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 a404on every REST URL — and per the transition-window section a404reads 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_idTTL vs the polling model — "valid until … the payload was retrieved" invalidates the token on the firstGET, 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-largevs400 ssz-decode-errorfor the SSZ count limits (bodies.max_count,blobs.max_versioned_hashes), which are also the containerMAX_*bounds — filed separately.MAX_BAL_BYTES(2**30) being 16xMAX_REQUEST_BODY_SIZE(2**26), already listed as an open sketch question.