diff --git a/apis/builder/header.v2.yaml b/apis/builder/header.v2.yaml new file mode 100644 index 0000000..ede5454 --- /dev/null +++ b/apis/builder/header.v2.yaml @@ -0,0 +1,78 @@ +get: + operationId: "getHeaderV2" + summary: Get an execution payload header along with the payout proof to the bid + description: | + Requests a builder node to produce a valid execution payload header, which + can be integrated into a blinded beacon block and signed. + + Builder must immediately return the header that is able to pay the + proposer's registered `fee_recipient` the most. If the builder is unaware + of `parent_hash`, it 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 validator registration associated with `pubkey`, it must + error. + + When possible, the builder must return a header with `gas_limit` equal to + 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`). + 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" + 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.SignedBuilderBidV2" + proof: + oneOf: + - $ref: "../../builder-oapi.yaml#/components/schemas/BidProof" + examples: + bellatrix: + $ref: "../../builder-oapi.yaml#/components/examples/Bellatrix.SignedBuilderBidV2" + "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" + "500": + $ref: "../../builder-oapi.yaml#/components/responses/InternalError" diff --git a/apis/builder/header.yaml b/apis/builder/header.yaml index cc07973..4db7c13 100644 --- a/apis/builder/header.yaml +++ b/apis/builder/header.yaml @@ -18,6 +18,7 @@ get: 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`). + deprecated: true tags: - Builder parameters: diff --git a/examples/bellatrix/signed_builder_bid_v2.json b/examples/bellatrix/signed_builder_bid_v2.json new file mode 100644 index 0000000..65d872c --- /dev/null +++ b/examples/bellatrix/signed_builder_bid_v2.json @@ -0,0 +1,29 @@ +{ + "value": { + "version": "bellatrix", + "data": { + "message": { + "header": { + "parent_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09", + "state_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "receipts_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "logs_bloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "prev_randao": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "block_number": "1", + "gas_limit": "1", + "gas_used": "1", + "timestamp": "1", + "extra_data": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "base_fee_per_gas": "1", + "block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", + "transactions_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2" + }, + "value": "1", + "pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a", + "fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09", + }, + "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505" + } + } +} diff --git a/specs/builder.md b/specs/builder.md index 17c3337..9f7e25e 100644 --- a/specs/builder.md +++ b/specs/builder.md @@ -31,6 +31,13 @@ | - | - | | `DOMAIN_APPLICATION_BUILDER` | `DomainType('0x00000001')` | +### Execution proof + +| Name | Value | +| - | - | +| `MAX_EXECUTION_PROOF_DEPTH` | 64 | +| `MAX_BRANCH_SIZE` | `17` | + ## Containers Consider the following definitions supplementary to the definitions in @@ -72,10 +79,13 @@ Bellatrix). ##### `BuilderBid` ```python -class BuilderBid(Container): +class BuilderBidV2(Container): header: ExecutionPayloadHeader value: uint256 pubkey: BLSPubkey + fee_recipient: ExecutionAddress + # RLP encoded size of list of max 17 32bytes branches is 564 bytes + proof: List[ByteList[564], MAX_EXECUTION_PROOF_DEPTH] ``` ##### `SignedBuilderBid` diff --git a/types/bellatrix/bid.v2.yaml b/types/bellatrix/bid.v2.yaml new file mode 100644 index 0000000..707c549 --- /dev/null +++ b/types/bellatrix/bid.v2.yaml @@ -0,0 +1,27 @@ +Bellatrix: + BuilderBidV2: + type: object + description: "The `BuilderBidV2` object from the Builder API spec." + properties: + header: + $ref: "../../beacon-apis/types/bellatrix/execution_payload.yaml#/Bellatrix/ExecutionPayloadHeader" + description: "`ExecutionPayloadHeader` to use in block proposal." + value: + $ref: "../../beacon-apis/types/primitive.yaml#/Uint256" + description: "Payment in wei that will be paid to the `fee_recipient` account." + pubkey: + $ref: "../../beacon-apis/types/primitive.yaml#/Pubkey" + description: "BLS public key of builder." + # Builder should return where its paying out the bid to + fee_recipient: + $ref: '../../beacon-apis/types/primitive.yaml#/ExecutionAddress' + description: "The address the bid will be paid to, as registered previously with builder" + + SignedBuilderBidV2: + type: object + description: "The `SignedBuilderBidV2` object from the Builder API spec." + properties: + message: + $ref: "#/Bellatrix/BuilderBidV2" + signature: + $ref: "../../beacon-apis/types/primitive.yaml#/Signature" diff --git a/types/proof.yaml b/types/proof.yaml new file mode 100644 index 0000000..e74f61b --- /dev/null +++ b/types/proof.yaml @@ -0,0 +1,26 @@ +ProofNode: + type: string + description: "An rlp encoded hex string representing a node in merkle proof branch" + example: "0xdf820023db808080c620841920682380c4208219208080808080808080808080" + # RLP encoded size of list of max 17 32bytes branches is 564 bytes + pattern: "^0x[a-fA-F0-9]{0,1128}$" + +ProofNodes: + type: array + items: + allOf: + - $ref: "#/ProofNode" + maxItems: 64 + +BidProof: + type: object + description: "The merkle proof of the `fee_recipient` account post the corresponding `BuilderBidV2` promised payout" + properties: + address: + $ref: '../../beacon-apis/types/primitive.yaml#/ExecutionAddress' + description: "The account address for which proof has been generated, should match `fee_recipient` of `BuilderBidV2`" + balance: + $ref: "../../beacon-apis/types/primitive.yaml#/Uint256" + description: "Post balance in gwei of the account (corresponding to the `stateRoot` of the `header` returned by `BuilderBidV2`)" + nodes: + $ref: "#/ProofNodes"