Repository navigation
Add Builder API schema #2
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from 5 commits
Commits
Show all changes
38 commits
Select commit
Hold shift + click to select a range
899c416
re-add schema
lightclient 7ae1541
return execution payload after blinded block is posted
lightclient 079f909
remove unused components
lightclient 0fdd92a
clean up endpoint defns
lightclient 198f9e1
add ssz defns
lightclient 50411ce
add builder bid
lightclient abae993
adjust get header path and few other fixes
lightclient a4ec2dc
update oapi
lightclient 5cfc51e
use double quotes instead of single quotes
lightclient 74c66c1
add more explanation in readme
lightclient 9800cdb
fix ci badge
lightclient a3ef9a1
more updates to readme
lightclient e6c62a4
move tags below description
lightclient 2be3b64
add execution payload versioning to blinded block endpoint
lightclient 5ef6847
status endpoint
metachris 5b78234
Merge pull request #1 from metachris/status-endpoint
lightclient 9554c8a
update status description, add internal error
lightclient e055511
version payload header in bid, not bid itself
lightclient 7d21dc0
add examples, update internal error to be builder specific
lightclient bb138f4
insert sample builder node url
lightclient fd2fe9a
update endpoint summaries
lightclient f8d1fc8
fix typo
lightclient d9f4d11
fix typo
lightclient 285c1c2
add signed objects, improve ssz defns
lightclient 90238e1
fix ssz def
lightclient c449d4e
use snake case in ssz
lightclient 8b9f722
fix typo
lightclient 2a06980
better wording
lightclient b286dba
make builder bid objects versioned by fork
lightclient a63e070
update builder bid example
lightclient def9ba6
fix builder bid example
lightclient 7e0aa1b
clean up spec
lightclient 3162878
use 0x10000001 as DomainType
lightclient 9573a87
fix broken link
lightclient 40a8e67
apply pr feedback
lightclient 6513551
add feedback from review
lightclient 565d1db
accept only single validator registrations
lightclient 85b0c48
add spellcheck to ci
lightclient File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| post: | ||
| tags: | ||
| - Builder | ||
| operationId: "submitBlindedBlock" | ||
| summary: Submit a signed blinded block. | ||
| description: | | ||
| Submits a `SignedBlindedBeaconBlock` to the builder, binding the proposer | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
| to the block. The builder is now able to unblind the transactions in | ||
| `ExecutionPayloadHeader` without the possibility of the validator modifying | ||
| them. | ||
|
|
||
| If the builder is not able to unblind the corresponding | ||
| `ExecutionPayloadHeader`, it must error. | ||
| requestBody: | ||
| description: | | ||
| A `SignedBlindedBeaconBlock`. | ||
| required: true | ||
| content: | ||
| application/json: | ||
| schema: | ||
| oneOf: | ||
| - $ref: "../../builder-oapi.yaml#/components/schemas/Bellatrix.SignedBlindedBeaconBlock" | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
| responses: | ||
| "200": | ||
| description: Success response. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| oneOf: | ||
| - $ref: "../../builder-oapi.yaml#/components/schemas/Bellatrix.ExecutionPayload" | ||
| "400": | ||
| description: Error response. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| allOf: | ||
| - $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage" | ||
| - example: | ||
| code: 400 | ||
| message: "Invalid block: missing signature" | ||
| "500": | ||
| $ref: '../../builder-oapi.yaml#/components/responses/InternalError' | ||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| get: | ||
| tags: | ||
| - Builder | ||
| operationId: "getHeader" | ||
| summary: Get an `ExecutionPayloadHeader`. | ||
| description: | | ||
| Requests a builder node to produce a valid execution payload header, which | ||
| can integrated into a blinded beacon block and signed. | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
|
|
||
| Builder must immediately return the header that is able to pay | ||
| `feeRecipient` the most. If the builder is unaware of `parent_hash`, it | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
| must error. If `pubkey` does not match the builder's expected proposer | ||
| `pubkey` for `slot, it must error. If the builder has not received a | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
| validator registration associated with `pubkey`, it must error. | ||
|
|
||
| When possibe, the builder must return a header with `gas_limit` equal to | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
| proposer's registered value. If this isn't possible due to the large | ||
| difference between `parent.gas_limit` and the preferred `gas_limit`, the | ||
| builder must return a header that moves `gas_limit` the maximum amount | ||
| allowed under the rules of consensus (currently `parent.gas_limit +/- | ||
| parent.gas_limit / 1024`). | ||
| parameters: | ||
| - name: slot | ||
| in: path | ||
| required: true | ||
| description: The slot for which the block should be proposed. | ||
| schema: | ||
| $ref: "../../builder-oapi.yaml#/components/schemas/Uint64" | ||
| - name: parent_hash | ||
| in: path | ||
| required: true | ||
| description: Hash of execution layer block the proposer will build on. | ||
| schema: | ||
| $ref: '../../builder-oapi.yaml#/components/schemas/Root' | ||
| - name: pubkey | ||
| in: query | ||
| required: true | ||
| description: The validator's BLS public key. | ||
| schema: | ||
| $ref: '../../builder-oapi.yaml#/components/schemas/Pubkey' | ||
| responses: | ||
| "200": | ||
| description: Success response. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| title: GetHeaderResponse | ||
| type: object | ||
| properties: | ||
| version: | ||
| type: string | ||
| enum: [ bellatrix ] | ||
| example: "bellatrix" | ||
| data: | ||
| oneOf: | ||
| - $ref: '../../builder-oapi.yaml#/components/schemas/Bellatrix.ExecutionPayloadHeader' | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
| "400": | ||
| description: Error response. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage" | ||
| examples: | ||
| InvalidRequest: | ||
| value: | ||
| code: 400 | ||
| message: "Unknown hash: missing parent hash" | ||
| "500": | ||
| $ref: '../../builder-oapi.yaml#/components/responses/InternalError' | ||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,37 @@ | ||
| post: | ||
| tags: | ||
| - Builder | ||
| operationId: "registerValidator" | ||
| summary: Register or update a validator's block building preferences. | ||
| description: | | ||
| Registers a validator's preferred fee recipient and gas limit. | ||
|
|
||
| Builders should verify that `pubkey` corresponds to an active or pending | ||
| validator, and that `signature` is valid under `pubkey`. Otherwise, builder | ||
| must error. Requests with `timestamp` less than or equal to the previous | ||
| announcement must error. Requests with `timestamp` greater than 10 seconds | ||
| +/- the builder's local time must error. | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
| requestBody: | ||
| description: An array of signed validator block building preferences. | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
| required: true | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: array | ||
| items: | ||
| $ref: '../../builder-oapi.yaml#/components/schemas/SignedValidatorRegistration' | ||
| responses: | ||
| "200": | ||
| description: Success response. | ||
| "400": | ||
| description: Error response. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| allOf: | ||
| - $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage" | ||
| - example: | ||
| code: 400 | ||
| message: "Unknown validator: 0x933ad9491b62059dd065b560d256d8957a8c402cc6e8d8ee7290ae11e8f7329267a8811c397529dac52ae1342ba58c95" | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
| "500": | ||
| $ref: '../../builder-oapi.yaml#/components/responses/InternalError' | ||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,74 @@ | ||
| openapi: "3.0.3" | ||
|
|
||
| info: | ||
| title: "Builder API" | ||
| description: | | ||
| API specification for external builder clients, which enables validators to delegate block building duties. | ||
|
|
||
| All requests by default send and receive JSON, and as such should have either or both of the "Content-Type: application/json" | ||
| and "Accept: application/json" headers. In addition, some requests can return data in the SSZ format. To indicate that SSZ | ||
| data is required in response to a request the header "Accept: application/octet-stream" should be sent. Note that only a subset | ||
| of requests can respond with data in SSZ format; these are noted in each individual request. | ||
|
|
||
| API endpoints are individually versioned. As such, there is no direct relationship between all v1 endpoints, all v2 endpoints, | ||
| _etc._ and no such relationship should be inferred. All JSON responses return the requested data under a `data` key in the top | ||
| level of their response. Additional metadata may or may not be present in other keys at the top level of the response, dependent | ||
| on the endpoint. The rules that require an increase in version number are as follows: | ||
|
|
||
| - no field that is listed in an endpoint shall be removed without an increase in the version number | ||
| - no field that is listed in an endpoint shall be altered in terms of format (_e.g._ from a string to an array) without an | ||
| increase in the version number | ||
|
|
||
| Note that it is possible for a field to be added to an endpoint's data or metadata without an increase in the version number. | ||
|
|
||
| version: "dev" | ||
| contact: | ||
| name: Ethereum Github | ||
| url: https://github.com/ethereum/builder-apis/issues | ||
| license: | ||
| name: "Apache 2.0" | ||
| url: "https://www.apache.org/licenses/LICENSE-2.0.html" | ||
|
|
||
| servers: | ||
| - url: "{server_url}" | ||
| variables: | ||
| server_url: | ||
| description: "Builder node API url" | ||
| default: "???" | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
|
|
||
| tags: | ||
| - name: Builder | ||
| description: Set of endpoints to interact with an external block builder. | ||
| paths: | ||
|
|
||
| /eth/v1/builder/validators: | ||
| $ref: "./apis/builder/validators.yaml" | ||
| /eth/v1/builder/{slot}/{parent_hash}/header: | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
| $ref: "./apis/builder/header.yaml" | ||
| /eth/v1/builder/blinded_blocks: | ||
| $ref: "./apis/builder/blinded_blocks.yaml" | ||
|
|
||
|
|
||
| components: | ||
| schemas: | ||
| Uint64: | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
| $ref: './beacon-apis/types/primitive.yaml#/Uint64' | ||
| Root: | ||
| $ref: './beacon-apis/types/primitive.yaml#/Root' | ||
| Pubkey: | ||
| $ref: './beacon-apis/types/primitive.yaml#/Pubkey' | ||
| ErrorMessage: | ||
| $ref: './beacon-apis/types/http.yaml#/ErrorMessage' | ||
| Bellatrix.ExecutionPayload: | ||
| $ref: './beacon-apis/types/bellatrix/execution_payload.yaml#/Bellatrix/ExecutionPayload' | ||
| Bellatrix.ExecutionPayloadHeader: | ||
| $ref: './beacon-apis/types/bellatrix/execution_payload.yaml#/Bellatrix/ExecutionPayloadHeader' | ||
| Bellatrix.SignedBlindedBeaconBlock: | ||
| $ref: './beacon-apis/types/bellatrix/block.yaml#/Bellatrix/SignedBlindedBeaconBlock' | ||
|
|
||
| SignedValidatorRegistration: | ||
| $ref: './types/registration.yaml#/SignedValidatorRegistration' | ||
|
|
||
| responses: | ||
| InternalError: | ||
| $ref: './beacon-apis/types/http.yaml#/InternalError' | ||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,81 @@ | ||
| # Builder Specification | ||
|
|
||
| This document specifies the behaviour of external block builders not already | ||
| covered in the corresponding API schema. | ||
|
|
||
| ## Structures | ||
|
|
||
| ### SSZ Objects | ||
|
|
||
| Consider the following definitions supplementary to the definitions in | ||
| [`consensus-specs`][consensus-specs]. | ||
|
|
||
| ##### `ValidatorRegistrationV1` | ||
|
|
||
| ```python | ||
| class ValidatorRegistrationV1(Container): | ||
| feeRecipient: Bytes20 | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
| gasLimit: uint64 | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
| timestamp: uint64 | ||
| pubkey: BLSPubkey | ||
| ``` | ||
|
|
||
| ##### `BuilderBidV1` | ||
|
|
||
| ```python | ||
| class BuilderBidV1(Container): | ||
| header: ExecutionPayloadHeader | ||
| value: uint256 | ||
| pubkey: BLSPubkey | ||
| ``` | ||
|
|
||
| ###### `BlindedBeaconBlock` | ||
|
|
||
| ```python | ||
| class BlindedBeaconBlock(Container): | ||
| slot: Slot | ||
| proposer_index: ValidatorIndex | ||
| parent_root: Root | ||
| state_root: Root | ||
| body: BlindedBeaconBlockBody | ||
| ``` | ||
|
|
||
| ###### `BlindedBeaconBlockBody` | ||
|
|
||
| ```python | ||
| class BlindedBeaconBlockBody(Container): | ||
| randao_reveal: BLSSignature | ||
| eth1_data: Eth1Data | ||
| graffiti: Bytes32 | ||
| proposer_slashings: List[ProposerSlashing, MAX_PROPOSER_SLASHINGS] | ||
| attester_slashings: List[AttesterSlashing, MAX_ATTESTER_SLASHINGS] | ||
| attestations: List[Attestation, MAX_ATTESTATIONS] | ||
| deposits: List[Deposit, MAX_DEPOSITS] | ||
| voluntary_exits: List[SignedVoluntaryExit, MAX_VOLUNTARY_EXITS] | ||
| sync_aggregate: SyncAggregate | ||
| execution_payload_header: ExecutionPayloadHeader | ||
| ``` | ||
|
|
||
| ## Routines | ||
|
|
||
| ### Signing | ||
|
|
||
| All signature operations should follow the [standard BLS operations][bls] | ||
| interface defined in `consensus-specs`. | ||
|
|
||
| There are two types of data to sign over in the Builder API: | ||
| * In-protocol messages, e.g. [`BlindedBeaconBlock`](#blindedbeaconblock), which | ||
| should compute the signing root using [`compute_signing_root`][compute-root] | ||
| and use the domain specified for beacon block proposals. | ||
| * Builder API messages, e.g. validator registration, which should compute the | ||
| signing root using [`compute_signing_root`][compute-root] and the domain | ||
| `DomainType('0xXXXXXXXX')` (TODO: get a proper domain). | ||
|
|
||
| As `compute_signing_root` takes `SSZObject` as input, client software should | ||
| convert in-protocol messages to their SSZ representation to compute the signing | ||
| root and Builder API messages to the SSZ representations defined | ||
| [above](#sszobjects). | ||
|
|
||
| [consensus-specs]: https://github.com/ethereum/consensus-specs | ||
| [bls]: https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#bls-signatures | ||
| [compute-root]: https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#compute_signing_root | ||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| ValidatorRegistration: | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
| type: object | ||
| description: "The [`ValidatorRegistration`]() object from the Builder API spec." | ||
| properties: | ||
| fee_recipient: | ||
| allOf: | ||
| - $ref: '../beacon-apis/types/primitive.yaml#/ExecutionAddress' | ||
| - description: "Address to receive fees from the block." | ||
| gas_limit: | ||
| allOf: | ||
| - $ref: "../beacon-apis/types/primitive.yaml#/Uint64" | ||
| - description: "Gas limit the validator desires to target." | ||
| timestamp: | ||
| allOf: | ||
| - $ref: '../beacon-apis/types/primitive.yaml#/Uint64' | ||
| - description: "Unix timestamp of registration." | ||
| pubkey: | ||
| allOf: | ||
| - $ref: '../beacon-apis/types/primitive.yaml#/Pubkey' | ||
| - description: "BLS public key of validator." | ||
|
|
||
| SignedValidatorRegistration: | ||
| type: object | ||
| description: "The [`SignedValidatorRegistration`]() object from the Builder API spec." | ||
| properties: | ||
| message: | ||
| $ref: "#/ValidatorRegistration" | ||
| signature: | ||
| $ref: "../beacon-apis/types/primitive.yaml#/Signature" | ||
|
lightclient marked this conversation as resolved.
Resolved
|
||
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.
Uh oh!
There was an error while loading. Please reload this page.