From a5242d7ff47d6b28430cf946815ba8b082a3b49c Mon Sep 17 00:00:00 2001 From: Bharath Vedartham Date: Fri, 28 Nov 2025 19:43:21 +0530 Subject: [PATCH 1/9] use shane-moore's beacon-api submodule --- beacon-apis | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beacon-apis b/beacon-apis index 69d2feb..bcbb22b 160000 --- a/beacon-apis +++ b/beacon-apis @@ -1 +1 @@ -Subproject commit 69d2feb12a6047c4f21e628dea8b0135b7e9013a +Subproject commit bcbb22b490027c6243544a1d96f3217ceee50f3d From 62acb201e4b4a72f978ef419924bc13996be7916 Mon Sep 17 00:00:00 2001 From: Bharath Vedartham Date: Fri, 28 Nov 2025 21:29:18 +0530 Subject: [PATCH 2/9] Add initial pass of gloas builder-api spec --- apis/builder/execution_payload_bid.yaml | 100 ++++++++++++++++++ .../signed_block_and_envelope_root.yaml | 47 ++++++++ beacon-apis | 2 +- builder-oapi.yaml | 11 +- types/gloas/bid.yaml | 23 ++++ .../gloas/signed_block_and_envelope_root.yaml | 13 +++ 6 files changed, 194 insertions(+), 2 deletions(-) create mode 100644 apis/builder/execution_payload_bid.yaml create mode 100644 apis/builder/signed_block_and_envelope_root.yaml create mode 100644 types/gloas/bid.yaml create mode 100644 types/gloas/signed_block_and_envelope_root.yaml diff --git a/apis/builder/execution_payload_bid.yaml b/apis/builder/execution_payload_bid.yaml new file mode 100644 index 0000000..d30fc2d --- /dev/null +++ b/apis/builder/execution_payload_bid.yaml @@ -0,0 +1,100 @@ +get: + operationId: "getExecutionPayloadBid" + summary: Get an execution payload bid. + description: | + Requests a builder node to produce a valid execution payload bid, which + can be integrated into a blinded beacon block and signed. + + If the builder is unable to produce a valid execution payload bid, then + the builder MUST return a 204 response. If the request is invalid, then the + builder MUST return an error response (400) with a description of the + validation failure. + + This API is applicable from Glamsterdam fork onwards. + tags: + - Builder + 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: path + required: true + description: The validator's BLS public key. + schema: + $ref: "../../builder-oapi.yaml#/components/schemas/Pubkey" + - name: Date-Milliseconds + in: header + required: false + description: | + Optional header containing a Unix timestamp in milliseconds representing + the point-in-time the request was sent. This header can be used to measure + latency. + schema: + type: integer + format: int64 + example: 1710338135000 + - name: X-Timeout-Ms + in: header + required: false + description: | + Optional header containing the proposer's timeout for the request in milliseconds. + Relays should use this header to adjust the amount of time by which they delay getBid + requests to maximise block rewards. Otherwise, getBid requests will timeout and the proposer + will not receive the header in time. + schema: + type: integer + format: int64 + example: 10000 + responses: + "200": + description: Success response. + headers: + Eth-Consensus-Version: + $ref: "../../builder-oapi.yaml#/components/headers/Eth-Consensus-Version" + required: false + content: + application/json: + schema: + title: GetBidResponse + type: object + required: [version, data] + properties: + version: + type: string + enum: [ gloas ] + example: "gloas" + data: + $ref: "../../builder-oapi.yaml#/components/schemas/Gloas.SignedBuilderBid" + # examples: + # gloas: + # $ref: "../../builder-oapi.yaml#/components/examples/Gloas.SignedBuilderBid" + application/octet-stream: + schema: + description: "SSZ serialized `SignedBuilderBid` bytes. Use Accept header to choose this response type" + "204": + description: No header is available. + "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" + "406": + $ref: "../../builder-oapi.yaml#/components/responses/NotAcceptable" + "500": + $ref: "../../builder-oapi.yaml#/components/responses/InternalError" diff --git a/apis/builder/signed_block_and_envelope_root.yaml b/apis/builder/signed_block_and_envelope_root.yaml new file mode 100644 index 0000000..f6138be --- /dev/null +++ b/apis/builder/signed_block_and_envelope_root.yaml @@ -0,0 +1,47 @@ +post: + operationId: "submitSignedBlockAndEnvelopeRoot" + summary: Submit a signed beacon block with the execution payload bid along with the signature of the execution payload envelope root. + description: | + Submits a `SignedBlockAndEnvelopeRoot` to the builder, binding the proposer + to the bid. + + A success response (202) indicates that the signed builder bid response was + valid. If the signed builder bid response was invalid, then the builder + must return an error response (400) with a description of the validation + failure. + tags: + - Builder + parameters: + - in: header + schema: + $ref: "../../builder-oapi.yaml#/components/schemas/ConsensusVersion" + required: false + name: Eth-Consensus-Version + description: "The active consensus version to which the block being submitted belongs. Required if request is SSZ encoded." + requestBody: + description: A `SignedBlockAndEnvelopeRoot`. + required: true + content: + application/json: + schema: + anyOf: + - $ref: "../../builder-oapi.yaml#/components/schemas/Gloas.SignedBlockAndEnvelopeRoot" + application/octet-stream: + schema: + description: "SSZ serialized `SignedBlockAndEnvelopeRoot` bytes. Use content type header to indicate that SSZ data is contained in the request body." + responses: + "202": + description: Success response. + "400": + description: Error response. + content: + application/json: + schema: + $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 400 + message: "Invalid signed block and envelope root: missing signature" + "415": + $ref: "../../builder-oapi.yaml#/components/responses/UnsupportedMediaType" + "500": + $ref: "../../builder-oapi.yaml#/components/responses/InternalError" diff --git a/beacon-apis b/beacon-apis index bcbb22b..8d90551 160000 --- a/beacon-apis +++ b/beacon-apis @@ -1 +1 @@ -Subproject commit bcbb22b490027c6243544a1d96f3217ceee50f3d +Subproject commit 8d9055187f5a8b8ed89b2160d9718eaa0c955726 diff --git a/builder-oapi.yaml b/builder-oapi.yaml index a9c05f0..058da9b 100644 --- a/builder-oapi.yaml +++ b/builder-oapi.yaml @@ -53,6 +53,10 @@ paths: $ref: "./apis/builder/validators.yaml" /eth/v1/builder/header/{slot}/{parent_hash}/{pubkey}: $ref: "./apis/builder/header.yaml" + /eth/v1/builder/execution_payload_bid/{slot}/{parent_hash}/{pubkey}: + $ref: "./apis/builder/execution_payload_bid.yaml" + /eth/v1/builder/signed_block_and_envelope_root: + $ref: "./apis/builder/signed_block_and_envelope_root.yaml" /eth/v1/builder/blinded_blocks: $ref: "./apis/builder/blinded_blocks.yaml" /eth/v2/builder/blinded_blocks: @@ -72,7 +76,7 @@ components: $ref: "./beacon-apis/types/http.yaml#/ErrorMessage" ConsensusVersion: $ref: "./beacon-apis/beacon-node-oapi.yaml#/components/schemas/ConsensusVersion" - enum: [bellatrix, capella, deneb, electra, fulu] + enum: [bellatrix, capella, deneb, electra, fulu, gloas] example: "bellatrix" Bellatrix.ExecutionPayload: $ref: "./beacon-apis/types/bellatrix/execution_payload.yaml#/Bellatrix/ExecutionPayload" @@ -102,6 +106,11 @@ components: $ref: "./types/fulu/blobs_bundle.yaml#/Fulu/BlobsBundle" Fulu.ExecutionPayloadAndBlobsBundle: $ref: "./types/fulu/execution_payload_and_blobs_bundle.yaml#/Fulu/ExecutionPayloadAndBlobsBundle" + Gloas.SignedBuilderBid: + $ref: "./types/gloas/bid.yaml#/Gloas/SignedBuilderBid" + Gloas.SignedBlockAndEnvelopeRoot: + $ref: "./types/gloas/signed_block_and_envelope_root.yaml#/Gloas/SignedBlockAndEnvelopeRoot" + responses: InternalError: diff --git a/types/gloas/bid.yaml b/types/gloas/bid.yaml new file mode 100644 index 0000000..cbd20e9 --- /dev/null +++ b/types/gloas/bid.yaml @@ -0,0 +1,23 @@ +Gloas: + BuilderBid: + description: "The `BuilderBid` object from the Builder API Deneb spec." + allOf: + - type: object + required: [execution_payload_bid, execution_payload_envelope_root] + properties: + execution_payload_bid: + $ref: "../../beacon-apis/types/gloas/execution_payload_bid.yaml#/Gloas/ExecutionPayloadBid" + description: "`ExecutionPayloadBid` to use in block proposal." + execution_payload_envelope_root: + $ref: "../../beacon-apis/types/primitive.yaml#/Root" + description: "Hash tree root of the execution payload envelope to use in block proposal." + + SignedBuilderBid: + type: object + description: "The `SignedBuilderBid` object from the Builder API spec." + required: [message, signature] + properties: + message: + $ref: "#/Gloas/BuilderBid" + signature: + $ref: "../../beacon-apis/types/primitive.yaml#/Signature" diff --git a/types/gloas/signed_block_and_envelope_root.yaml b/types/gloas/signed_block_and_envelope_root.yaml new file mode 100644 index 0000000..7d9f6dd --- /dev/null +++ b/types/gloas/signed_block_and_envelope_root.yaml @@ -0,0 +1,13 @@ +Gloas: + SignedBlockAndEnvelopeRoot: + description: "The Signed Beacon Block and Signed Execution Payload Envelope Root" + allOf: + - type: object + required: [signed_beacon_block, signed_execution_payload_envelope_root] + properties: + signed_beacon_block: + $ref: "../../beacon-apis/types/gloas/block.yaml#/Gloas/SignedBeaconBlock" + description: "Signed beacon block with the execution payload bid sent by the relay included in." + signed_execution_payload_envelope_root: + $ref: "../../beacon-apis/types/primitive.yaml#/Signature" + description: "Signature of the execution payload envelope root by the proposer." From 15114313c3d83bfc67d8ebd204c60b879e01e95c Mon Sep 17 00:00:00 2001 From: Bharath Vedartham Date: Fri, 28 Nov 2025 23:32:51 +0530 Subject: [PATCH 3/9] updates --- apis/builder/beacon_block.yaml | 58 +++++++++++++++++++ ...l => execution_payload_envelope_root.yaml} | 23 ++++---- builder-oapi.yaml | 9 ++- types/gloas/bid.yaml | 17 +----- 4 files changed, 77 insertions(+), 30 deletions(-) create mode 100644 apis/builder/beacon_block.yaml rename apis/builder/{signed_block_and_envelope_root.yaml => execution_payload_envelope_root.yaml} (56%) diff --git a/apis/builder/beacon_block.yaml b/apis/builder/beacon_block.yaml new file mode 100644 index 0000000..066fcfb --- /dev/null +++ b/apis/builder/beacon_block.yaml @@ -0,0 +1,58 @@ +post: + operationId: "submitSignedBeaconBlock" + summary: Submit a signed beacon block with the execution payload bid. + description: | + Submits a `SignedBeaconBlock` to the builder, binding the proposer + to the bid. + + A success response (200) indicates that the signed beacon block was + valid. If the signed beacon block was invalid, then the builder + must return an error response (400) with a description of the validation + failure. + + On success response (200), the builder returns the signing root of the execution payload envelope. + tags: + - Builder + parameters: + - in: header + schema: + $ref: "../../builder-oapi.yaml#/components/schemas/ConsensusVersion" + required: false + name: Eth-Consensus-Version + description: "The active consensus version to which the block being submitted belongs. Required if request is SSZ encoded." + requestBody: + description: A `SignedBeaconBlock`. + required: true + content: + application/json: + schema: + anyOf: + - $ref: "../../beacon-apis/types/gloas/block.yaml#/Gloas/SignedBeaconBlock" + application/octet-stream: + schema: + description: "SSZ serialized `SignedBeaconBlock` bytes. Use content type header to indicate that SSZ data is contained in the request body." + responses: + "200": + description: Success response. + content: + application/json: + schema: + type: object + required: [data] + properties: + data: + $ref: "../../builder-oapi.yaml#/components/schemas/Root" + description: "The signing root of the execution payload envelope." + "400": + description: Error response. + content: + application/json: + schema: + $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 400 + message: "Invalid signed block and envelope root: missing signature" + "415": + $ref: "../../builder-oapi.yaml#/components/responses/UnsupportedMediaType" + "500": + $ref: "../../builder-oapi.yaml#/components/responses/InternalError" diff --git a/apis/builder/signed_block_and_envelope_root.yaml b/apis/builder/execution_payload_envelope_root.yaml similarity index 56% rename from apis/builder/signed_block_and_envelope_root.yaml rename to apis/builder/execution_payload_envelope_root.yaml index f6138be..e44abe7 100644 --- a/apis/builder/signed_block_and_envelope_root.yaml +++ b/apis/builder/execution_payload_envelope_root.yaml @@ -1,12 +1,11 @@ post: - operationId: "submitSignedBlockAndEnvelopeRoot" - summary: Submit a signed beacon block with the execution payload bid along with the signature of the execution payload envelope root. + operationId: "submitSignedExecutionPayloadEnvelopeRoot" + summary: Submit a signed execution payload envelope root. description: | - Submits a `SignedBlockAndEnvelopeRoot` to the builder, binding the proposer - to the bid. + Submits a `SignedExecutionPayloadEnvelopeRoot` to the builder. - A success response (202) indicates that the signed builder bid response was - valid. If the signed builder bid response was invalid, then the builder + A success response (200) indicates that the signed execution payload envelope root was + valid. If the signed execution payload envelope root was invalid, then the builder must return an error response (400) with a description of the validation failure. tags: @@ -19,16 +18,20 @@ post: name: Eth-Consensus-Version description: "The active consensus version to which the block being submitted belongs. Required if request is SSZ encoded." requestBody: - description: A `SignedBlockAndEnvelopeRoot`. + description: A `SignedExecutionPayloadEnvelopeRoot`. required: true content: application/json: schema: anyOf: - - $ref: "../../builder-oapi.yaml#/components/schemas/Gloas.SignedBlockAndEnvelopeRoot" + - type: object + required: [signature] + properties: + signature: + $ref: "../../beacon-apis/types/primitive.yaml#/Signature" application/octet-stream: schema: - description: "SSZ serialized `SignedBlockAndEnvelopeRoot` bytes. Use content type header to indicate that SSZ data is contained in the request body." + description: "SSZ serialized `Signature` bytes. Use content type header to indicate that SSZ data is contained in the request body." responses: "202": description: Success response. @@ -40,7 +43,7 @@ post: $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage" example: code: 400 - message: "Invalid signed block and envelope root: missing signature" + message: "Invalid signed envelope root: missing signature" "415": $ref: "../../builder-oapi.yaml#/components/responses/UnsupportedMediaType" "500": diff --git a/builder-oapi.yaml b/builder-oapi.yaml index 058da9b..0797bfe 100644 --- a/builder-oapi.yaml +++ b/builder-oapi.yaml @@ -55,8 +55,10 @@ paths: $ref: "./apis/builder/header.yaml" /eth/v1/builder/execution_payload_bid/{slot}/{parent_hash}/{pubkey}: $ref: "./apis/builder/execution_payload_bid.yaml" - /eth/v1/builder/signed_block_and_envelope_root: - $ref: "./apis/builder/signed_block_and_envelope_root.yaml" + /eth/v1/builder/beacon_block: + $ref: "./apis/builder/beacon_block.yaml" + /eth/v1/builder/execution_payload_envelope_root: + $ref: "./apis/builder/execution_payload_envelope_root.yaml" /eth/v1/builder/blinded_blocks: $ref: "./apis/builder/blinded_blocks.yaml" /eth/v2/builder/blinded_blocks: @@ -108,9 +110,6 @@ components: $ref: "./types/fulu/execution_payload_and_blobs_bundle.yaml#/Fulu/ExecutionPayloadAndBlobsBundle" Gloas.SignedBuilderBid: $ref: "./types/gloas/bid.yaml#/Gloas/SignedBuilderBid" - Gloas.SignedBlockAndEnvelopeRoot: - $ref: "./types/gloas/signed_block_and_envelope_root.yaml#/Gloas/SignedBlockAndEnvelopeRoot" - responses: InternalError: diff --git a/types/gloas/bid.yaml b/types/gloas/bid.yaml index cbd20e9..6977e9b 100644 --- a/types/gloas/bid.yaml +++ b/types/gloas/bid.yaml @@ -1,23 +1,10 @@ Gloas: - BuilderBid: - description: "The `BuilderBid` object from the Builder API Deneb spec." - allOf: - - type: object - required: [execution_payload_bid, execution_payload_envelope_root] - properties: - execution_payload_bid: - $ref: "../../beacon-apis/types/gloas/execution_payload_bid.yaml#/Gloas/ExecutionPayloadBid" - description: "`ExecutionPayloadBid` to use in block proposal." - execution_payload_envelope_root: - $ref: "../../beacon-apis/types/primitive.yaml#/Root" - description: "Hash tree root of the execution payload envelope to use in block proposal." - SignedBuilderBid: type: object description: "The `SignedBuilderBid` object from the Builder API spec." - required: [message, signature] + required: [execution_payload_bid, signature] properties: message: - $ref: "#/Gloas/BuilderBid" + $ref: "../../beacon-apis/types/gloas/execution_payload_bid.yaml#/Gloas/ExecutionPayloadBid" signature: $ref: "../../beacon-apis/types/primitive.yaml#/Signature" From 0d955fd4c14ba6034fdd7e323155958a1bd12203 Mon Sep 17 00:00:00 2001 From: Bharath Vedartham Date: Mon, 1 Dec 2025 14:48:56 +0530 Subject: [PATCH 4/9] remove signed_block_and_envelope_root.yaml --- types/gloas/signed_block_and_envelope_root.yaml | 13 ------------- 1 file changed, 13 deletions(-) delete mode 100644 types/gloas/signed_block_and_envelope_root.yaml diff --git a/types/gloas/signed_block_and_envelope_root.yaml b/types/gloas/signed_block_and_envelope_root.yaml deleted file mode 100644 index 7d9f6dd..0000000 --- a/types/gloas/signed_block_and_envelope_root.yaml +++ /dev/null @@ -1,13 +0,0 @@ -Gloas: - SignedBlockAndEnvelopeRoot: - description: "The Signed Beacon Block and Signed Execution Payload Envelope Root" - allOf: - - type: object - required: [signed_beacon_block, signed_execution_payload_envelope_root] - properties: - signed_beacon_block: - $ref: "../../beacon-apis/types/gloas/block.yaml#/Gloas/SignedBeaconBlock" - description: "Signed beacon block with the execution payload bid sent by the relay included in." - signed_execution_payload_envelope_root: - $ref: "../../beacon-apis/types/primitive.yaml#/Signature" - description: "Signature of the execution payload envelope root by the proposer." From f1558734aad461a6672639002d9fc9e04afd5886 Mon Sep 17 00:00:00 2001 From: Bharath Vedartham Date: Wed, 3 Dec 2025 15:52:49 +0530 Subject: [PATCH 5/9] sign a BlindedExecutionPayloadEnvelope instead of a blind signing root --- apis/builder/beacon_block.yaml | 6 +-- .../execution_payload_envelope_root.yaml | 20 ++++------ types/gloas/bid.yaml | 2 +- .../blinded_execution_payload_envelope.yaml | 39 +++++++++++++++++++ 4 files changed, 51 insertions(+), 16 deletions(-) create mode 100644 types/gloas/blinded_execution_payload_envelope.yaml diff --git a/apis/builder/beacon_block.yaml b/apis/builder/beacon_block.yaml index 066fcfb..fd07c8e 100644 --- a/apis/builder/beacon_block.yaml +++ b/apis/builder/beacon_block.yaml @@ -10,7 +10,7 @@ post: must return an error response (400) with a description of the validation failure. - On success response (200), the builder returns the signing root of the execution payload envelope. + On success response (200), the builder returns the blinded execution payload envelope. tags: - Builder parameters: @@ -41,8 +41,8 @@ post: required: [data] properties: data: - $ref: "../../builder-oapi.yaml#/components/schemas/Root" - description: "The signing root of the execution payload envelope." + $ref: "../../types/gloas/blinded_execution_payload_envelope.yaml#/Gloas/BlindedExecutionPayloadEnvelope" + description: "The blinded execution payload envelope." "400": description: Error response. content: diff --git a/apis/builder/execution_payload_envelope_root.yaml b/apis/builder/execution_payload_envelope_root.yaml index e44abe7..da5a33b 100644 --- a/apis/builder/execution_payload_envelope_root.yaml +++ b/apis/builder/execution_payload_envelope_root.yaml @@ -1,11 +1,11 @@ post: - operationId: "submitSignedExecutionPayloadEnvelopeRoot" + operationId: "submitSignedBlindedExecutionPayloadEnvelope" summary: Submit a signed execution payload envelope root. description: | - Submits a `SignedExecutionPayloadEnvelopeRoot` to the builder. + Submits a `SignedBlindedExecutionPayloadEnvelope` to the builder. - A success response (200) indicates that the signed execution payload envelope root was - valid. If the signed execution payload envelope root was invalid, then the builder + A success response (202) indicates that the signed blinded execution payload envelope was + valid. If the signed blinded execution payload envelope was invalid, then the builder must return an error response (400) with a description of the validation failure. tags: @@ -18,20 +18,16 @@ post: name: Eth-Consensus-Version description: "The active consensus version to which the block being submitted belongs. Required if request is SSZ encoded." requestBody: - description: A `SignedExecutionPayloadEnvelopeRoot`. + description: A `SignedBlindedExecutionPayloadEnvelope`. required: true content: application/json: schema: anyOf: - - type: object - required: [signature] - properties: - signature: - $ref: "../../beacon-apis/types/primitive.yaml#/Signature" + - $ref: "../../types/gloas/blinded_execution_payload_envelope.yaml#/Gloas/SignedBlindedExecutionPayloadEnvelope" application/octet-stream: schema: - description: "SSZ serialized `Signature` bytes. Use content type header to indicate that SSZ data is contained in the request body." + description: "SSZ serialized `SignedBlindedExecutionPayloadEnvelope` bytes. Use content type header to indicate that SSZ data is contained in the request body." responses: "202": description: Success response. @@ -43,7 +39,7 @@ post: $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage" example: code: 400 - message: "Invalid signed envelope root: missing signature" + message: "Invalid signed blinded execution payload envelope: missing signature" "415": $ref: "../../builder-oapi.yaml#/components/responses/UnsupportedMediaType" "500": diff --git a/types/gloas/bid.yaml b/types/gloas/bid.yaml index 6977e9b..ffe6092 100644 --- a/types/gloas/bid.yaml +++ b/types/gloas/bid.yaml @@ -1,7 +1,7 @@ Gloas: SignedBuilderBid: type: object - description: "The `SignedBuilderBid` object from the Builder API spec." + description: "The `SignedBuilderBid` object from the Builder API spec. The bid is signed by the builder BLS key." required: [execution_payload_bid, signature] properties: message: diff --git a/types/gloas/blinded_execution_payload_envelope.yaml b/types/gloas/blinded_execution_payload_envelope.yaml new file mode 100644 index 0000000..ead84ab --- /dev/null +++ b/types/gloas/blinded_execution_payload_envelope.yaml @@ -0,0 +1,39 @@ +Gloas: + BlindedExecutionPayloadEnvelope: + type: object + description: "The `BlindedExecutionPayloadEnvelope` object from the Builder API spec. The execution payload envelope is blinded by the builder BLS key." + required: [payload, execution_requests, builder_index, beacon_block_root, slot, blob_kzg_commitments, state_root] + properties: + payload_root: + $ref: "../primitive.yaml#/Root" + description: "Root of the execution payload" + execution_requests_root: + $ref: "../primitive.yaml#/Root" + description: "Root of the execution requests" + builder_index: + $ref: "../primitive.yaml#/Uint64" + description: "Index of the builder that created this execution payload envelope" + beacon_block_root: + $ref: "../primitive.yaml#/Root" + description: "Root of the beacon block for this payload" + slot: + $ref: "../primitive.yaml#/Uint64" + description: "Slot number for this execution payload" + blob_kzg_commitments: + type: array + items: + $ref: "../primitive.yaml#/KZGCommitment" + minItems: 0 + maxItems: 4096 + state_root: + $ref: "../primitive.yaml#/Root" + description: "Beacon state root after executing this payload" + SignedBlindedExecutionPayloadEnvelope: + type: object + description: "The `SignedBlindedExecutionPayloadEnvelope` object from the Builder API spec. The execution payload envelope is signed by the proposer's BLS key." + required: [message, signature] + properties: + message: + $ref: "#/Gloas/BlindedExecutionPayloadEnvelope" + signature: + $ref: "../primitive.yaml#/Signature" \ No newline at end of file From 7849cf92af74ffee5f06bd9ae7687e2f76fc4074 Mon Sep 17 00:00:00 2001 From: Bharath Vedartham Date: Wed, 3 Dec 2025 15:55:16 +0530 Subject: [PATCH 6/9] minor fixes --- ...root.yaml => execution_payload_envelope.yaml} | 0 builder-oapi.yaml | 4 ++-- .../blinded_execution_payload_envelope.yaml | 16 ++++++++-------- 3 files changed, 10 insertions(+), 10 deletions(-) rename apis/builder/{execution_payload_envelope_root.yaml => execution_payload_envelope.yaml} (100%) diff --git a/apis/builder/execution_payload_envelope_root.yaml b/apis/builder/execution_payload_envelope.yaml similarity index 100% rename from apis/builder/execution_payload_envelope_root.yaml rename to apis/builder/execution_payload_envelope.yaml diff --git a/builder-oapi.yaml b/builder-oapi.yaml index 0797bfe..ebf7f6d 100644 --- a/builder-oapi.yaml +++ b/builder-oapi.yaml @@ -57,8 +57,8 @@ paths: $ref: "./apis/builder/execution_payload_bid.yaml" /eth/v1/builder/beacon_block: $ref: "./apis/builder/beacon_block.yaml" - /eth/v1/builder/execution_payload_envelope_root: - $ref: "./apis/builder/execution_payload_envelope_root.yaml" + /eth/v1/builder/execution_payload_envelope: + $ref: "./apis/builder/execution_payload_envelope.yaml" /eth/v1/builder/blinded_blocks: $ref: "./apis/builder/blinded_blocks.yaml" /eth/v2/builder/blinded_blocks: diff --git a/types/gloas/blinded_execution_payload_envelope.yaml b/types/gloas/blinded_execution_payload_envelope.yaml index ead84ab..e3dc576 100644 --- a/types/gloas/blinded_execution_payload_envelope.yaml +++ b/types/gloas/blinded_execution_payload_envelope.yaml @@ -5,28 +5,28 @@ Gloas: required: [payload, execution_requests, builder_index, beacon_block_root, slot, blob_kzg_commitments, state_root] properties: payload_root: - $ref: "../primitive.yaml#/Root" + $ref: "../../beacon-apis/types/primitive.yaml#/Root" description: "Root of the execution payload" execution_requests_root: - $ref: "../primitive.yaml#/Root" + $ref: "../../beacon-apis/types/primitive.yaml#/Root" description: "Root of the execution requests" builder_index: - $ref: "../primitive.yaml#/Uint64" + $ref: "../../beacon-apis/types/primitive.yaml#/Uint64" description: "Index of the builder that created this execution payload envelope" beacon_block_root: - $ref: "../primitive.yaml#/Root" + $ref: "../../beacon-apis/types/primitive.yaml#/Root" description: "Root of the beacon block for this payload" slot: - $ref: "../primitive.yaml#/Uint64" + $ref: "../../beacon-apis/types/primitive.yaml#/Uint64" description: "Slot number for this execution payload" blob_kzg_commitments: type: array items: - $ref: "../primitive.yaml#/KZGCommitment" + $ref: "../../beacon-apis/types/primitive.yaml#/KZGCommitment" minItems: 0 maxItems: 4096 state_root: - $ref: "../primitive.yaml#/Root" + $ref: "../../beacon-apis/types/primitive.yaml#/Root" description: "Beacon state root after executing this payload" SignedBlindedExecutionPayloadEnvelope: type: object @@ -36,4 +36,4 @@ Gloas: message: $ref: "#/Gloas/BlindedExecutionPayloadEnvelope" signature: - $ref: "../primitive.yaml#/Signature" \ No newline at end of file + $ref: "../../beacon-apis/types/primitive.yaml#/Signature" \ No newline at end of file From 6b009f8720a44a9003e7331688774c213f76086c Mon Sep 17 00:00:00 2001 From: Bharath Vedartham Date: Wed, 3 Dec 2025 15:55:59 +0530 Subject: [PATCH 7/9] fix summary --- apis/builder/execution_payload_envelope.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apis/builder/execution_payload_envelope.yaml b/apis/builder/execution_payload_envelope.yaml index da5a33b..e12eca1 100644 --- a/apis/builder/execution_payload_envelope.yaml +++ b/apis/builder/execution_payload_envelope.yaml @@ -1,6 +1,6 @@ post: operationId: "submitSignedBlindedExecutionPayloadEnvelope" - summary: Submit a signed execution payload envelope root. + summary: Submit a signed blinded execution payload envelope. description: | Submits a `SignedBlindedExecutionPayloadEnvelope` to the builder. From 266276ac4e19b82cfc8221c4765c90ee7c394673 Mon Sep 17 00:00:00 2001 From: Bharath Vedartham Date: Thu, 4 Dec 2025 14:38:02 +0530 Subject: [PATCH 8/9] update apis --- apis/builder/beacon_block.yaml | 28 +++++------- apis/builder/execution_payload_bid.yaml | 7 +-- apis/builder/execution_payload_envelope.yaml | 46 -------------------- builder-oapi.yaml | 2 - specs/gloas/builder.md | 1 + types/gloas/bid.yaml | 21 ++++++++- 6 files changed, 34 insertions(+), 71 deletions(-) delete mode 100644 apis/builder/execution_payload_envelope.yaml create mode 100644 specs/gloas/builder.md diff --git a/apis/builder/beacon_block.yaml b/apis/builder/beacon_block.yaml index fd07c8e..6e9ddd8 100644 --- a/apis/builder/beacon_block.yaml +++ b/apis/builder/beacon_block.yaml @@ -2,15 +2,13 @@ post: operationId: "submitSignedBeaconBlock" summary: Submit a signed beacon block with the execution payload bid. description: | - Submits a `SignedBeaconBlock` to the builder, binding the proposer - to the bid. + Submits a `SignedBeaconBlock` and `SignedBlindedExecutionPayloadEnvelope` to the builder, + binding the proposer to the bid. A success response (200) indicates that the signed beacon block was valid. If the signed beacon block was invalid, then the builder must return an error response (400) with a description of the validation failure. - - On success response (200), the builder returns the blinded execution payload envelope. tags: - Builder parameters: @@ -26,23 +24,21 @@ post: content: application/json: schema: - anyOf: - - $ref: "../../beacon-apis/types/gloas/block.yaml#/Gloas/SignedBeaconBlock" + type: object + required: [block] + properties: + block: + $ref: "../../beacon-apis/types/gloas/block.yaml#/Gloas/SignedBeaconBlock" + description: "The signed beacon block." + blinded_envelope: + $ref: "../../types/gloas/blinded_execution_payload_envelope.yaml#/Gloas/SignedBlindedExecutionPayloadEnvelope" + description: "The signed blinded execution payload envelope." application/octet-stream: schema: description: "SSZ serialized `SignedBeaconBlock` bytes. Use content type header to indicate that SSZ data is contained in the request body." responses: - "200": + "202": description: Success response. - content: - application/json: - schema: - type: object - required: [data] - properties: - data: - $ref: "../../types/gloas/blinded_execution_payload_envelope.yaml#/Gloas/BlindedExecutionPayloadEnvelope" - description: "The blinded execution payload envelope." "400": description: Error response. content: diff --git a/apis/builder/execution_payload_bid.yaml b/apis/builder/execution_payload_bid.yaml index d30fc2d..2d6ad4f 100644 --- a/apis/builder/execution_payload_bid.yaml +++ b/apis/builder/execution_payload_bid.yaml @@ -65,7 +65,7 @@ get: content: application/json: schema: - title: GetBidResponse + title: GetExecutionPayloadBidResponse type: object required: [version, data] properties: @@ -74,10 +74,7 @@ get: enum: [ gloas ] example: "gloas" data: - $ref: "../../builder-oapi.yaml#/components/schemas/Gloas.SignedBuilderBid" - # examples: - # gloas: - # $ref: "../../builder-oapi.yaml#/components/examples/Gloas.SignedBuilderBid" + $ref: "../../types/gloas/bid.yaml#/Gloas/SignedBuilderBid" application/octet-stream: schema: description: "SSZ serialized `SignedBuilderBid` bytes. Use Accept header to choose this response type" diff --git a/apis/builder/execution_payload_envelope.yaml b/apis/builder/execution_payload_envelope.yaml deleted file mode 100644 index e12eca1..0000000 --- a/apis/builder/execution_payload_envelope.yaml +++ /dev/null @@ -1,46 +0,0 @@ -post: - operationId: "submitSignedBlindedExecutionPayloadEnvelope" - summary: Submit a signed blinded execution payload envelope. - description: | - Submits a `SignedBlindedExecutionPayloadEnvelope` to the builder. - - A success response (202) indicates that the signed blinded execution payload envelope was - valid. If the signed blinded execution payload envelope was invalid, then the builder - must return an error response (400) with a description of the validation - failure. - tags: - - Builder - parameters: - - in: header - schema: - $ref: "../../builder-oapi.yaml#/components/schemas/ConsensusVersion" - required: false - name: Eth-Consensus-Version - description: "The active consensus version to which the block being submitted belongs. Required if request is SSZ encoded." - requestBody: - description: A `SignedBlindedExecutionPayloadEnvelope`. - required: true - content: - application/json: - schema: - anyOf: - - $ref: "../../types/gloas/blinded_execution_payload_envelope.yaml#/Gloas/SignedBlindedExecutionPayloadEnvelope" - application/octet-stream: - schema: - description: "SSZ serialized `SignedBlindedExecutionPayloadEnvelope` bytes. Use content type header to indicate that SSZ data is contained in the request body." - responses: - "202": - description: Success response. - "400": - description: Error response. - content: - application/json: - schema: - $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage" - example: - code: 400 - message: "Invalid signed blinded execution payload envelope: missing signature" - "415": - $ref: "../../builder-oapi.yaml#/components/responses/UnsupportedMediaType" - "500": - $ref: "../../builder-oapi.yaml#/components/responses/InternalError" diff --git a/builder-oapi.yaml b/builder-oapi.yaml index ebf7f6d..dcfe7e0 100644 --- a/builder-oapi.yaml +++ b/builder-oapi.yaml @@ -57,8 +57,6 @@ paths: $ref: "./apis/builder/execution_payload_bid.yaml" /eth/v1/builder/beacon_block: $ref: "./apis/builder/beacon_block.yaml" - /eth/v1/builder/execution_payload_envelope: - $ref: "./apis/builder/execution_payload_envelope.yaml" /eth/v1/builder/blinded_blocks: $ref: "./apis/builder/blinded_blocks.yaml" /eth/v2/builder/blinded_blocks: diff --git a/specs/gloas/builder.md b/specs/gloas/builder.md new file mode 100644 index 0000000..7c1a7b6 --- /dev/null +++ b/specs/gloas/builder.md @@ -0,0 +1 @@ +# Gloas - Builder Specification \ No newline at end of file diff --git a/types/gloas/bid.yaml b/types/gloas/bid.yaml index ffe6092..fdf633c 100644 --- a/types/gloas/bid.yaml +++ b/types/gloas/bid.yaml @@ -1,10 +1,27 @@ Gloas: + BuilderBid: + type: object + description: "The `BuilderBid` object from the Builder API spec. The bid is signed by the builder BLS key." + required: [execution_payload_bid] + properties: + execution_payload_bid: + $ref: "../../beacon-apis/types/gloas/execution_payload_bid.yaml#/Gloas/ExecutionPayloadBid" + payload_root: + $ref: "../../beacon-apis/types/primitive.yaml#/Root" + description: "Root of the execution payload" + execution_requests_root: + $ref: "../../beacon-apis/types/primitive.yaml#/Root" + description: "Root of the execution requests" + blob_kzg_commitments_root: + $ref: "../../beacon-apis/types/primitive.yaml#/Root" + description: "Root of the blob KZG commitments" + SignedBuilderBid: type: object description: "The `SignedBuilderBid` object from the Builder API spec. The bid is signed by the builder BLS key." - required: [execution_payload_bid, signature] + required: [message, signature] properties: message: - $ref: "../../beacon-apis/types/gloas/execution_payload_bid.yaml#/Gloas/ExecutionPayloadBid" + $ref: "#/Gloas/BuilderBid" signature: $ref: "../../beacon-apis/types/primitive.yaml#/Signature" From 01bb9e62f15042507e41912ce6a1aca37344cccb Mon Sep 17 00:00:00 2001 From: Bharath Vedartham Date: Thu, 4 Dec 2025 19:56:38 +0530 Subject: [PATCH 9/9] wip specs --- specs/gloas/validator.md | 84 +++++++++++++++++++ types/gloas/bid.yaml | 3 - .../blinded_execution_payload_envelope.yaml | 11 +-- 3 files changed, 88 insertions(+), 10 deletions(-) create mode 100644 specs/gloas/validator.md diff --git a/specs/gloas/validator.md b/specs/gloas/validator.md new file mode 100644 index 0000000..75315f8 --- /dev/null +++ b/specs/gloas/validator.md @@ -0,0 +1,84 @@ + + +**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* + +- [Gloas - Honest Validator](#gloas---honest-validator) + - [Introduction](#introduction) + - [Containers](#containers) + - [New Containers](#new-containers) + - [`BlindedExecutionPayloadEnvelope`](#blindedexecutionpayloadenvelope) + - [Extended Containers](#extended-containers) + - [`BuilderBid`](#builderbid) + - [Block proposal](#block-proposal) + - [Constructing the `BeaconBlockBody`](#constructing-the-beaconblockbody) + - [ExecutionPayloadBid](#executionpayloadbid) + + + +# Gloas - Honest Validator + + +## Introduction + +This document explains how a beacon-chain validator can participate in the external block building market post ePBS. + +Validators request an `ExecutionPayloadBid` from the external builder network to put it in their `SignedBeaconBlock`. The external builder network broadcasts the `SignedExecutionPayloadEnvelope` corresponding to the bid to the PTC commitee. + +## Containers + +### New Containers + +### `BlindedExecutionPayloadEnvelope` + +```python +class BlindedExecutionPayloadEnvelope(Container): + payload_root: Root + execution_requests_root: Root + builder_index: ValidatorIndex + beacon_block_root: Root + slot: Slot + blob_kzg_commitments_root: Root + state_root: Root +``` + +```python +class SignedBlindedExecutionPayloadEnvelope(Container): + message: BlindedExecutionPayloadEnvelope + signature: Signature +``` + +### Extended Containers + +### `BuilderBid` + +```python +class BuilderBid(Container): + bid: ExecutionPayloadBid + payload_root: Root + execution_requests_root: Root + pubkey: BLSPubkey +``` + +### Block proposal + +#### Constructing the `BeaconBlockBody` + +##### ExecutionPayloadBid + +To obtain an execution payload, a block proposer building a block on top of a beacon `state` in a given `slot` must take +the following actions: + +1. Call upstream builder software to get an `ExecutionPayloadBid` and the roots of the `payload` and `execution_requests` + with the required data `slot`, `parent_hash` and `pubkey`, where: + * `slot` is the proposal's slot + * `parent_hash` is the value `state.latest_execution_payload_header.block_hash` + * `pubkey` is the proposer's public key +2. Assemble a `SignedBeaconBlock` according to the process outlined in the [Gloas specs][gloas-specs] but with + the `ExecutionPayloadBid` from the prior step. +3. The proposer assembles a `SignedBlindedExecutionPayloadEnvelope` with the `payload` and `execution_requests` roots provided + from the prior step. +4. The proposer returns the `SignedBeaconBlock` and `SignedBlindedExecutionPayloadEnvelope` back to the upstream block + building software. +5. The upstream block building software constructs the `SignedExecutionPayloadEnvelope` from the + `SignedBlindedExecutionPayloadEnvelope` and broadcasts it to the PTC commitee. + diff --git a/types/gloas/bid.yaml b/types/gloas/bid.yaml index fdf633c..a5c3272 100644 --- a/types/gloas/bid.yaml +++ b/types/gloas/bid.yaml @@ -12,9 +12,6 @@ Gloas: execution_requests_root: $ref: "../../beacon-apis/types/primitive.yaml#/Root" description: "Root of the execution requests" - blob_kzg_commitments_root: - $ref: "../../beacon-apis/types/primitive.yaml#/Root" - description: "Root of the blob KZG commitments" SignedBuilderBid: type: object diff --git a/types/gloas/blinded_execution_payload_envelope.yaml b/types/gloas/blinded_execution_payload_envelope.yaml index e3dc576..c94d29e 100644 --- a/types/gloas/blinded_execution_payload_envelope.yaml +++ b/types/gloas/blinded_execution_payload_envelope.yaml @@ -2,7 +2,7 @@ Gloas: BlindedExecutionPayloadEnvelope: type: object description: "The `BlindedExecutionPayloadEnvelope` object from the Builder API spec. The execution payload envelope is blinded by the builder BLS key." - required: [payload, execution_requests, builder_index, beacon_block_root, slot, blob_kzg_commitments, state_root] + required: [payload, execution_requests, builder_index, beacon_block_root, slot, blob_kzg_commitments_root, state_root] properties: payload_root: $ref: "../../beacon-apis/types/primitive.yaml#/Root" @@ -19,12 +19,9 @@ Gloas: slot: $ref: "../../beacon-apis/types/primitive.yaml#/Uint64" description: "Slot number for this execution payload" - blob_kzg_commitments: - type: array - items: - $ref: "../../beacon-apis/types/primitive.yaml#/KZGCommitment" - minItems: 0 - maxItems: 4096 + blob_kzg_commitments_root: + $ref: "../../beacon-apis/types/primitive.yaml#/Root" + description: "Root of the blob KZG commitments" state_root: $ref: "../../beacon-apis/types/primitive.yaml#/Root" description: "Beacon state root after executing this payload"