From db11adcc8fe3b2869f298190e9a39c4b3251ed13 Mon Sep 17 00:00:00 2001 From: g11tech Date: Fri, 16 Sep 2022 22:51:49 +0530 Subject: [PATCH 1/7] Add bid proofs to the builder bid response --- types/bellatrix/bid.yaml | 6 ++++++ types/proof.yaml | 13 +++++++++++++ 2 files changed, 19 insertions(+) create mode 100644 types/proof.yaml diff --git a/types/bellatrix/bid.yaml b/types/bellatrix/bid.yaml index 3e9e7fb..8d512b4 100644 --- a/types/bellatrix/bid.yaml +++ b/types/bellatrix/bid.yaml @@ -12,6 +12,12 @@ Bellatrix: pubkey: $ref: "../../beacon-apis/types/primitive.yaml#/Pubkey" description: "BLS public key of builder." + fee_recipient: + $ref: '../../beacon-apis/types/primitive.yaml#/ExecutionAddress' + description: "The address the bid is paid to" + proofs: + $ref: "../proof.yaml#/Proofs" + description: "Proofs of pre and post balances of the `fee_recipient` account" SignedBuilderBid: type: object diff --git a/types/proof.yaml b/types/proof.yaml new file mode 100644 index 0000000..5d80d35 --- /dev/null +++ b/types/proof.yaml @@ -0,0 +1,13 @@ +Proofs: + type: array + items: + allOf: + - $ref: '#/Proof' + maxItems: 2 + +Proof: + type: array + items: + allOf: + - $ref: "../beacon-apis/types/primitive.yaml#/Bytes32" + maxItems: 32 From 97f6f85c18838a767449131175f1b54a884b54c4 Mon Sep 17 00:00:00 2001 From: g11tech Date: Sat, 17 Sep 2022 14:12:06 +0530 Subject: [PATCH 2/7] reduce proof requirement to post and fix proof length --- specs/builder.md | 8 ++++++++ types/bellatrix/bid.yaml | 6 +++--- types/proof.yaml | 9 +-------- 3 files changed, 12 insertions(+), 11 deletions(-) diff --git a/specs/builder.md b/specs/builder.md index 17c3337..5cc824a 100644 --- a/specs/builder.md +++ b/specs/builder.md @@ -31,6 +31,12 @@ | - | - | | `DOMAIN_APPLICATION_BUILDER` | `DomainType('0x00000001')` | +### Execution proof + +| Name | Value | +| - | - | +| `MAX_EXECUTION_PROOF_DEPTH` | `256/4` (= 64) | + ## Containers Consider the following definitions supplementary to the definitions in @@ -76,6 +82,8 @@ class BuilderBid(Container): header: ExecutionPayloadHeader value: uint256 pubkey: BLSPubkey + fee_recipient: ExecutionAddress + proof: List[Bytes32, MAX_EXECUTION_PROOF_DEPTH] ``` ##### `SignedBuilderBid` diff --git a/types/bellatrix/bid.yaml b/types/bellatrix/bid.yaml index 8d512b4..e8f7b9d 100644 --- a/types/bellatrix/bid.yaml +++ b/types/bellatrix/bid.yaml @@ -15,9 +15,9 @@ Bellatrix: fee_recipient: $ref: '../../beacon-apis/types/primitive.yaml#/ExecutionAddress' description: "The address the bid is paid to" - proofs: - $ref: "../proof.yaml#/Proofs" - description: "Proofs of pre and post balances of the `fee_recipient` account" + proof: + $ref: "../proof.yaml#/Proof" + description: "Merkle proof of post balance of the `fee_recipient` account" SignedBuilderBid: type: object diff --git a/types/proof.yaml b/types/proof.yaml index 5d80d35..bcc32ae 100644 --- a/types/proof.yaml +++ b/types/proof.yaml @@ -1,13 +1,6 @@ -Proofs: - type: array - items: - allOf: - - $ref: '#/Proof' - maxItems: 2 - Proof: type: array items: allOf: - $ref: "../beacon-apis/types/primitive.yaml#/Bytes32" - maxItems: 32 + maxItems: 64 From 3a8ab8442c3d46f15b60b5a7866c2f85028a9f84 Mon Sep 17 00:00:00 2001 From: g11tech Date: Sat, 17 Sep 2022 17:49:57 +0530 Subject: [PATCH 3/7] improve description --- types/bellatrix/bid.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/types/bellatrix/bid.yaml b/types/bellatrix/bid.yaml index e8f7b9d..5e12161 100644 --- a/types/bellatrix/bid.yaml +++ b/types/bellatrix/bid.yaml @@ -14,7 +14,7 @@ Bellatrix: description: "BLS public key of builder." fee_recipient: $ref: '../../beacon-apis/types/primitive.yaml#/ExecutionAddress' - description: "The address the bid is paid to" + description: "The address the bid will be paid to, as registered previously with builder" proof: $ref: "../proof.yaml#/Proof" description: "Merkle proof of post balance of the `fee_recipient` account" From 089109c45ab1f79fcb046aee730d98602fa0fa1b Mon Sep 17 00:00:00 2001 From: g11tech Date: Sun, 23 Oct 2022 23:26:35 +0530 Subject: [PATCH 4/7] improve wording Co-authored-by: lightclient <14004106+lightclient@users.noreply.github.com> --- specs/builder.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specs/builder.md b/specs/builder.md index 5cc824a..b2287ce 100644 --- a/specs/builder.md +++ b/specs/builder.md @@ -35,7 +35,8 @@ | Name | Value | | - | - | -| `MAX_EXECUTION_PROOF_DEPTH` | `256/4` (= 64) | +| `MAX_EXECUTION_PROOF_DEPTH` | 64 | +| `MAX_BRANCH_SIZE` | `17` | ## Containers From 9ce0b1d52433e090b4848e054de7635289f6d13a Mon Sep 17 00:00:00 2001 From: g11tech Date: Sun, 23 Oct 2022 23:28:19 +0530 Subject: [PATCH 5/7] correct proof size Co-authored-by: lightclient <14004106+lightclient@users.noreply.github.com> --- specs/builder.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/builder.md b/specs/builder.md index b2287ce..08166a9 100644 --- a/specs/builder.md +++ b/specs/builder.md @@ -84,7 +84,7 @@ class BuilderBid(Container): value: uint256 pubkey: BLSPubkey fee_recipient: ExecutionAddress - proof: List[Bytes32, MAX_EXECUTION_PROOF_DEPTH] + proof: List[ByteList[544], MAX_EXECUTION_PROOF_DEPTH] ``` ##### `SignedBuilderBid` From 3713df9480ac2709bb978c3856b65f5d0b61c96f Mon Sep 17 00:00:00 2001 From: g11tech Date: Mon, 24 Oct 2022 03:08:44 +0530 Subject: [PATCH 6/7] add proposal as separate v2 version and fix proof --- apis/builder/header.v2.yaml | 78 +++++++++++++++++++ apis/builder/header.yaml | 1 + examples/bellatrix/signed_builder_bid_v2.json | 29 +++++++ specs/builder.md | 5 +- types/bellatrix/bid.v2.yaml | 27 +++++++ types/bellatrix/bid.yaml | 6 ++ types/proof.yaml | 24 +++++- 7 files changed, 166 insertions(+), 4 deletions(-) create mode 100644 apis/builder/header.v2.yaml create mode 100644 examples/bellatrix/signed_builder_bid_v2.json create mode 100644 types/bellatrix/bid.v2.yaml 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 08166a9..9f7e25e 100644 --- a/specs/builder.md +++ b/specs/builder.md @@ -79,12 +79,13 @@ Bellatrix). ##### `BuilderBid` ```python -class BuilderBid(Container): +class BuilderBidV2(Container): header: ExecutionPayloadHeader value: uint256 pubkey: BLSPubkey fee_recipient: ExecutionAddress - proof: List[ByteList[544], MAX_EXECUTION_PROOF_DEPTH] + # 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/bellatrix/bid.yaml b/types/bellatrix/bid.yaml index 5e12161..002eb29 100644 --- a/types/bellatrix/bid.yaml +++ b/types/bellatrix/bid.yaml @@ -15,10 +15,16 @@ Bellatrix: fee_recipient: $ref: '../../beacon-apis/types/primitive.yaml#/ExecutionAddress' description: "The address the bid will be paid to, as registered previously with builder" + + BidProof: + type: object + description: "Post balance proof of the bid" + properties: proof: $ref: "../proof.yaml#/Proof" description: "Merkle proof of post balance of the `fee_recipient` account" + SignedBuilderBid: type: object description: "The `SignedBuilderBid` object from the Builder API spec." diff --git a/types/proof.yaml b/types/proof.yaml index bcc32ae..e74f61b 100644 --- a/types/proof.yaml +++ b/types/proof.yaml @@ -1,6 +1,26 @@ -Proof: +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: "../beacon-apis/types/primitive.yaml#/Bytes32" + - $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" From 7d1da61f140e33e0461880d14b8f3705a19efd0d Mon Sep 17 00:00:00 2001 From: g11tech Date: Mon, 24 Oct 2022 03:13:00 +0530 Subject: [PATCH 7/7] restore previous bid object --- types/bellatrix/bid.yaml | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/types/bellatrix/bid.yaml b/types/bellatrix/bid.yaml index 002eb29..3e9e7fb 100644 --- a/types/bellatrix/bid.yaml +++ b/types/bellatrix/bid.yaml @@ -12,18 +12,6 @@ Bellatrix: pubkey: $ref: "../../beacon-apis/types/primitive.yaml#/Pubkey" description: "BLS public key of builder." - fee_recipient: - $ref: '../../beacon-apis/types/primitive.yaml#/ExecutionAddress' - description: "The address the bid will be paid to, as registered previously with builder" - - BidProof: - type: object - description: "Post balance proof of the bid" - properties: - proof: - $ref: "../proof.yaml#/Proof" - description: "Merkle proof of post balance of the `fee_recipient` account" - SignedBuilderBid: type: object