diff --git a/apis/builder/blinded_blocks.yaml b/apis/builder/blinded_blocks.yaml index d355353..536c9e1 100644 --- a/apis/builder/blinded_blocks.yaml +++ b/apis/builder/blinded_blocks.yaml @@ -10,8 +10,7 @@ post: must return an error response (400) with a description of the validation failure. - After Deneb, this endpoint will additionally accept `SignedBlindedBlobSidecars`, and return - with additional unblinded blobs in response. + After Deneb, this endpoint will additionally return the associated blobs in the response. tags: - Builder parameters: @@ -22,7 +21,7 @@ post: name: Eth-Consensus-Version description: "Version of the block being submitted" requestBody: - description: A `SignedBlindedBeaconBlock` before Deneb, or `SignedBlindedBlockContents` after Deneb. + description: A `SignedBlindedBeaconBlock`. required: true content: application/json: @@ -30,14 +29,14 @@ post: oneOf: - $ref: "../../builder-oapi.yaml#/components/schemas/Bellatrix.SignedBlindedBeaconBlock" - $ref: "../../builder-oapi.yaml#/components/schemas/Capella.SignedBlindedBeaconBlock" - - $ref: "../../builder-oapi.yaml#/components/schemas/Deneb.SignedBlindedBlockContents" + - $ref: "../../builder-oapi.yaml#/components/schemas/Deneb.SignedBlindedBeaconBlockWithKZGCommitmentInclusionProofs", examples: bellatrix: $ref: "../../builder-oapi.yaml#/components/examples/Bellatrix.SignedBlindedBeaconBlock" capella: $ref: "../../builder-oapi.yaml#/components/examples/Capella.SignedBlindedBeaconBlock" deneb: - $ref: "../../builder-oapi.yaml#/components/examples/Deneb.SignedBlindedBlockContents" + $ref: "../../builder-oapi.yaml#/components/examples/Deneb.SignedBlindedBeaconBlockWithKZGCommitmentInclusionProofs" responses: "200": diff --git a/apis/builder/header.yaml b/apis/builder/header.yaml index 1fd0c42..2411dc8 100644 --- a/apis/builder/header.yaml +++ b/apis/builder/header.yaml @@ -9,6 +9,8 @@ get: 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. + + After Deneb, return the KZG commitments for any associated blobs attached to the execution payload. tags: - Builder parameters: diff --git a/builder-oapi.yaml b/builder-oapi.yaml index af72fc3..89e3596 100644 --- a/builder-oapi.yaml +++ b/builder-oapi.yaml @@ -69,8 +69,8 @@ components: $ref: "./beacon-apis/types/capella/block.yaml#/Capella/SignedBlindedBeaconBlock" Capella.SignedBuilderBid: $ref: "./types/capella/bid.yaml#/Capella/SignedBuilderBid" - Deneb.SignedBlindedBlockContents: - $ref: "./beacon-apis/types/deneb/block_contents.yaml#/Deneb/SignedBlindedBlockContents" + Deneb.SignedBlindedBeaconBlockWithKZGCommitmentInclusionProofs: + $ref: "./types/deneb/block.yaml#/Deneb/SignedBlindedBeaconBlockWithKZGCommitmentInclusionProofs" Deneb.SignedBuilderBid: $ref: "./types/deneb/bid.yaml#/Deneb/SignedBuilderBid" Deneb.ExecutionPayloadAndBlobsBundle: @@ -95,10 +95,9 @@ components: $ref: "./examples/capella/execution_payload.json" Capella.SignedBuilderBid: $ref: "./examples/capella/signed_builder_bid.json" - Deneb.SignedBlindedBlockContents: - $ref: "./examples/deneb/signed_blinded_block_contents.json" + Deneb.SignedBlindedBeaconBlockWithKZGCommitmentInclusionProofs: + $ref: "./examples/deneb/signed_blinded_beacon_block_with_kzg_commitment_inclusion_proofs.json" Deneb.ExecutionPayloadAndBlobsBundle: $ref: "./examples/deneb/execution_payload_and_blobs_bundle.json" Deneb.SignedBuilderBid: $ref: "./examples/deneb/signed_builder_bid.json" - diff --git a/examples/deneb/execution_payload_and_blobs_bundle.json b/examples/deneb/execution_payload_and_blobs_bundle.json index 095bab6..d3ab864 100644 --- a/examples/deneb/execution_payload_and_blobs_bundle.json +++ b/examples/deneb/execution_payload_and_blobs_bundle.json @@ -15,7 +15,7 @@ "timestamp": "1", "extra_data": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "base_fee_per_gas": "1", - "blob_gas_used" : "1", + "blob_gas_used": "1", "excess_blob_gas": "1", "block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "transactions": [ @@ -31,10 +31,16 @@ ] }, "blobs_bundle": { - "commitments": ["0x8dab030c51e16e84be9caab84ee3d0b8bbec1db4a0e4de76439da8424d9b957370a10a78851f97e4b54d2ce1ab0d686f"], - "proofs": ["0xb4021b0de10f743893d4f71e1bf830c019e832958efd6795baf2f83b8699a9eccc5dc99015d8d4d8ec370d0cc333c06a"], - "blobs": ["0x24564723180fcb3d994104538d351c8dcbde12d541676bb736cf678018ca4739"] + "commitments": [ + "0x8dab030c51e16e84be9caab84ee3d0b8bbec1db4a0e4de76439da8424d9b957370a10a78851f97e4b54d2ce1ab0d686f" + ], + "proofs": [ + "0xb4021b0de10f743893d4f71e1bf830c019e832958efd6795baf2f83b8699a9eccc5dc99015d8d4d8ec370d0cc333c06a" + ], + "blobs": [ + "0x24564723180fcb3d994104538d351c8dcbde12d541676bb736cf678018ca4739" + ] } } } -} \ No newline at end of file +} diff --git a/examples/deneb/signed_blinded_block_contents.json b/examples/deneb/signed_blinded_beacon_block_with_kzg_commitment_inclusion_proofs.json similarity index 89% rename from examples/deneb/signed_blinded_block_contents.json rename to examples/deneb/signed_blinded_beacon_block_with_kzg_commitment_inclusion_proofs.json index cefbd04..9794e32 100644 --- a/examples/deneb/signed_blinded_block_contents.json +++ b/examples/deneb/signed_blinded_beacon_block_with_kzg_commitment_inclusion_proofs.json @@ -1,6 +1,6 @@ { "value": { - "signed_blinded_block": { + "signed_blinded_beacon_block": { "message": { "slot": "1", "proposer_index": "1", @@ -170,7 +170,7 @@ "timestamp": "1", "extra_data": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "base_fee_per_gas": "1", - "blob_gas_used" : "1", + "blob_gas_used": "1", "excess_blob_gas": "1", "block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "transactions_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", @@ -193,20 +193,26 @@ }, "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505" }, - "signed_blinded_blob_sidecars": [ - { - "message": { - "block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", - "index": "0", - "slot": "1", - "block_parent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", - "proposer_index": "1", - "blob_root": "0x24564723180fcb3d994104538d351c8dcbde12d541676bb736cf678018ca4739", - "kzg_commitment": "0x8dab030c51e16e84be9caab84ee3d0b8bbec1db4a0e4de76439da8424d9b957370a10a78851f97e4b54d2ce1ab0d686f", - "kzg_proof": "0xb4021b0de10f743893d4f71e1bf830c019e832958efd6795baf2f83b8699a9eccc5dc99015d8d4d8ec370d0cc333c06a" - }, - "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505" - } + "kzg_commitment_inclusion_proofs": [ + [ + "0xc1a0d420dec217972fc26c96fcbc88db83f42cd2f8ff51fab07818f47f3e26ad", + "0x16f6260a5f7a771879d178c3e523413c7a2b2409f38eea7e8139b486cb571206", + "0xb5155e388c6afe6c40b4bc3dfb009825b91eb4e6b169eb5f50580e4136e243f5", + "0x527631cb8a1e0607537f022f3a3149c898d9c551614cabfb3f356ab26929d507", + "0x1618f36e86001d1a99acd04e2b203d74c7b84f6116175bddb0a84687ac718a35", + "0x1ccb252f7637942bd7e81e9a362a8ea5e8947c5617d2da0d6036cdd16c0ca25c", + "0x2a65c5295c4fe4e111527955ef97cfae784b4d560d80aa4db1dc52001cabe2e8", + "0x1978d9bc77e518b1ccd4e416ee73d615a5a4d9f1b0c7a1de78e327e2bd8a29f1", + "0x10f1de00532d6d0d5cce37d22051f85250c849b6139f440be3eafce2522b2648", + "0x6121284f5f1ed17c6919a00c7284f93528d4b2c00183c7be1fd2ed3dcba9622f", + "0x956aa1284fa223561eb7cfae1d61b6d5bd49fa1aaf1333fcf58a8ef08fdc2042", + "0x9d43338c4902e2a9b8805cd681d65138206b0d1b5d5c1382f279aaa6491f49de", + "0x94cf0b426854b6b71c158ef24e8db03314c1fb285343db048c869c0f99bbe6c9", + "0xc7fad25f4659019217b4a3469efc22f9bb9fa29e533d1d4e1ad9e03f54095348", + "0x3fcd4ffc5edb625b91e0bb8911135ef5d47f8502797adf89a14f145d95c40749", + "0x908096ee03c3d31c9abd2e0da707ab4ef6aa058d370facd6a71f8eeb883b6450", + "0x32524573b320430a6ded6baad5184da96258cf73c269ab4d033ebebce216262f" + ] ] } -} \ No newline at end of file +} diff --git a/examples/deneb/signed_builder_bid.json b/examples/deneb/signed_builder_bid.json index 3675e5e..7bb7957 100644 --- a/examples/deneb/signed_builder_bid.json +++ b/examples/deneb/signed_builder_bid.json @@ -16,21 +16,19 @@ "timestamp": "1", "extra_data": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "base_fee_per_gas": "1", - "blob_gas_used" : "1", + "blob_gas_used": "1", "excess_blob_gas": "1", "block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "transactions_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "withdrawals_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2" }, - "blinded_blobs_bundle": { - "commitments": ["0x8dab030c51e16e84be9caab84ee3d0b8bbec1db4a0e4de76439da8424d9b957370a10a78851f97e4b54d2ce1ab0d686f"], - "proofs": ["0xb4021b0de10f743893d4f71e1bf830c019e832958efd6795baf2f83b8699a9eccc5dc99015d8d4d8ec370d0cc333c06a"], - "blob_roots": ["0x24564723180fcb3d994104538d351c8dcbde12d541676bb736cf678018ca4739"] - }, + "blob_kzg_commitments": [ + "0xa94170080872584e54a1cf092d845703b13907f2e6b3b1c0ad573b910530499e3bcd48c6378846b80d2bfa58c81cf3d5" + ], "value": "1", "pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a" }, "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505" } } -} \ No newline at end of file +} diff --git a/specs/deneb/builder.md b/specs/deneb/builder.md index 11a27cf..ef19cc8 100644 --- a/specs/deneb/builder.md +++ b/specs/deneb/builder.md @@ -8,16 +8,18 @@ - [Introduction](#introduction) - [Containers](#containers) - [New containers](#new-containers) - - [`BlindedBlobsBundle`](#blindedblobsbundle) - - [`BlindedBlobSidecar`](#blindedblobsidecar) - - [`SignedBlindedBlobSidecar`](#signedblindedblobsidecar) - - [`SignedBlindedBlockContents`](#signedblindedblockcontents) - [`BlobsBundle`](#blobsbundle) - [`ExecutionPayloadAndBlobsBundle`](#executionpayloadandblobsbundle) + - [`KZGCommitmentInclusionProof`](#kzgcommitmentinclusionproof) + - [`SignedBlindedBeaconBlockWithKZGCommitmentInclusionProofs`](#signedblindedbeaconblockwithkzgcommitmentinclusionproofs) - [Extended containers](#extended-containers) - [`BuilderBid`](#builderbid) - [`ExecutionPayloadHeader`](#executionpayloadheader) - - [`BlindedBeaconBlockBody`](#blindedbeaconblockbody) + - [`BlindedBeaconBlockBody`](#blindedbeaconblockbody) +- [Building](#building) + - [Bidding](#bidding) + - [Revealing the `ExecutionPayload`](#revealing-the-executionpayload) + - [Blinded block processing](#blinded-block-processing) @@ -29,55 +31,33 @@ This is the modification of the builder specification accompanying the Deneb upg ### New containers -#### `BlindedBlobsBundle` +#### `BlobsBundle` -```python -class BlindedBlobsBundle(Container): - commitments: List[KZGCommitment, MAX_BLOB_COMMITMENTS_PER_BLOCK] - proofs: List[KZGProof, MAX_BLOB_COMMITMENTS_PER_BLOCK] - blob_roots: List[Root, MAX_BLOB_COMMITMENTS_PER_BLOCK] -``` +Same as [`BlobsBundle`](https://github.com/ethereum/consensus-specs/blob/dev/specs/deneb/validator.md#blobsbundle) in Deneb consensus specs. -#### `BlindedBlobSidecar` +#### `ExecutionPayloadAndBlobsBundle` ```python -class BlindedBlobSidecar(Container): - block_root: Root - index: BlobIndex - slot: Slot - block_parent_root: Root - proposer_index: ValidatorIndex - blob_root: Root - kzg_commitment: KZGCommitment - kzg_proof: KZGProof +class ExecutionPayloadAndBlobsBundle(Container): + execution_payload: ExecutionPayload + blobs_bundle: BlobsBundle ``` -#### `SignedBlindedBlobSidecar` +#### `KZGCommitmentInclusionProof` -```python -class SignedBlindedBlobSidecar(Container): - message: BlindedBlobSidecar - signature: BLSSignature -``` - -#### `SignedBlindedBlockContents` +Type alias for the inclusion proof. Refer to the [Deneb consensus specs for +`KZG_COMMITMENT_INCLUSION_PROOF_DEPTH`](https://github.com/ethereum/consensus-specs/blob/dev/specs/deneb/p2p-interface.md#preset). ```python -class SignedBlindedBlockContents(Container): - signed_blinded_block: SignedBlindedBeaconBlock - signed_blinded_blob_sidecars: List[SignedBlindedBlobSidecar, MAX_BLOBS_PER_BLOCK] +KZGCommimentInclusionProof = Vector[Bytes32, KZG_COMMITMENT_INCLUSION_PROOF_DEPTH] ``` -#### `BlobsBundle` - -Same as [`BlobsBundle`](https://github.com/ethereum/consensus-specs/blob/dev/specs/deneb/validator.md#blobsbundle) in Deneb consensus specs. - -#### `ExecutionPayloadAndBlobsBundle` +#### `SignedBlindedBeaconBlockWithKZGCommitmentInclusionProofs` ```python -class ExecutionPayloadAndBlobsBundle(Container): - execution_payload: ExecutionPayload - blobs_bundle: BlobsBundle +class SignedBlindedBeaconBlockWithKZGCommitmentInclusionProofs(Container): + signed_blinded_beacon_block: SignedBlindedBeaconBlock + kzg_commitment_inclusion_proofs: List[KZGCommitmentInclusionProof, MAX_BLOB_COMMITMENTS_PER_BLOCK] ``` ### Extended containers @@ -89,7 +69,7 @@ Note: `SignedBuilderBid` is updated indirectly. ```python class BuilderBid(Container): header: ExecutionPayloadHeader # [Modified in Deneb] - blinded_blobs_bundle: BlindedBlobsBundle # [New in Deneb] + blob_kzg_commitments: List[KZGCommitment, MAX_BLOB_COMMITMENTS_PER_BLOCK] # [New in Deneb] value: uint256 pubkey: BLSPubkey ``` @@ -98,7 +78,7 @@ class BuilderBid(Container): See [`ExecutionPayloadHeader`](https://github.com/ethereum/consensus-specs/blob/dev/specs/deneb/beacon-chain.md#executionpayloadheader) in Deneb consensus specs. -##### `BlindedBeaconBlockBody` +#### `BlindedBeaconBlockBody` Note: `BlindedBeaconBlock` and `SignedBlindedBeaconBlock` types are updated indirectly. @@ -117,3 +97,30 @@ class BlindedBeaconBlockBody(Container): bls_to_execution_changes: List[SignedBLSToExecutionChange, MAX_BLS_TO_EXECUTION_CHANGES] blob_kzg_commitments: List[KZGCommitment, MAX_BLOB_COMMITMENTS_PER_BLOCK] # [New in Deneb] ``` + +## Building + +Builders provide bids as they have in prior forks. + +Relays have a few additional duties to manage any blobs associated with a bid. + +### Bidding + +After a relay has verified the execution payload (including any blobs) is correctly constructed, the relay **MUST** additionally return any `KZGCommitments` for those blobs +in the `SignedBuilderBid`. + +### Revealing the `ExecutionPayload` + +#### Blinded block processing + +Relays verify signed blinded beacon blocks as before, with the additional requirement that they **MUST** verify the +included `KZGCommitmentInclusionProof`s against the `BeaconBlockHeader` derived from the provided `SignedBlindedBeaconBlock`. + +Execution payloads **SHOULD** only be returned to the proposer if the `SignedBlindedBeaconBlock` is valid **AND** the +inclusion proofs match the associated commitments for the execution payload's blobs. + +If the entire submission is valid, then the relay uses the inclusion proofs and signed header to construct [`BlobSidecar`s +defined in the Deneb consensus specs](https://github.com/ethereum/consensus-specs/blob/dev/specs/deneb/p2p-interface.md#blobsidecar) +for blob dissemination (alongside the `SignedBeaconBlock`) on the network-wide gossip layer. + +For the proposer specifically, the unblinded execution payload along with `BlobsBundle` is returned after the proposer block has been verified in full. diff --git a/types/deneb/bid.yaml b/types/deneb/bid.yaml index 87d1d57..9315ef1 100644 --- a/types/deneb/bid.yaml +++ b/types/deneb/bid.yaml @@ -7,9 +7,13 @@ Deneb: header: $ref: "../../beacon-apis/types/deneb/execution_payload.yaml#/Deneb/ExecutionPayloadHeader" description: "`ExecutionPayloadHeader` to use in block proposal." - blinded_blobs_bundle: - $ref: "./blobs_bundle.yaml#/Deneb/BlindedBlobsBundle" - description: "`BlindedBlobsBundle` to use in block proposal." + blob_kzg_commitments: + type: array + items: + $ref: '../../beacon-apis/types/primitive.yaml#/KZGCommitment' + minItems: 0 + maxItems: 6 + description: "the `KZGCommitment`s for the associated blobs for this `header`" - $ref: '../bellatrix/bid.yaml#/Bellatrix/BuilderBidCommon' SignedBuilderBid: diff --git a/types/deneb/blobs_bundle.yaml b/types/deneb/blobs_bundle.yaml index 2752db8..152665a 100644 --- a/types/deneb/blobs_bundle.yaml +++ b/types/deneb/blobs_bundle.yaml @@ -15,20 +15,6 @@ Deneb: minItems: 0 maxItems: 6 - BlindedBlobsBundle: - allOf: - - $ref: '#/Deneb/BlobsBundleCommon' - type: object - description: "A blobs container with the SSZ root of the blobs rather than the full blobs." - properties: - blob_roots: - type: array - items: - $ref: "../../beacon-apis/types/primitive.yaml#/Root" - minItems: 0 - maxItems: 6 - - BlobsBundle: allOf: - $ref: '#/Deneb/BlobsBundleCommon' diff --git a/types/deneb/block.yaml b/types/deneb/block.yaml new file mode 100644 index 0000000..ec82c67 --- /dev/null +++ b/types/deneb/block.yaml @@ -0,0 +1,12 @@ +Deneb: + SignedBlindedBeaconBlockWithKZGCommitmentInclusionProofs: + type: object + properties: + signed_blinded_beacon_block: + $ref: "../../beacon-apis/types/deneb/block.yaml#/Deneb/SignedBlindedBeaconBlock" + kzg_commitment_inclusion_proofs: + type: array + items: + $ref: '../../beacon-apis/types/deneb/blob_sidecar.yaml#/KZGCommitmentInclusionProof' + minItems: 0 + maxItems: 6 diff --git a/wordlist.txt b/wordlist.txt index d2ce2c5..7569811 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -28,3 +28,4 @@ validator's vc wei EIP +SignedBlindedBeaconBlockWithKZGCommitmentInclusionProofs