From f0ffbb8f85f152cbcfe5974c41d0b93cb7264a9d Mon Sep 17 00:00:00 2001 From: realbigsean Date: Tue, 16 May 2023 17:40:53 -0400 Subject: [PATCH] Add blob signing endpoints (#302) Co-authored-by: 0xGabi Co-authored-by: Paul Harris Co-authored-by: Jimmy Chen --- CHANGES.md | 1 + apis/beacon/blocks/blinded_blocks.yaml | 5 +- apis/beacon/blocks/blocks.yaml | 5 +- apis/validator/blinded_block.yaml | 2 +- apis/validator/block.v2.yaml | 2 +- beacon-node-oapi.yaml | 22 ++++++- types/deneb/blob_sidecar.yaml | 90 ++++++++++++++++++++++++++ types/deneb/block_contents.yaml | 37 +++++++++++ types/primitive.yaml | 12 ++++ 9 files changed, 168 insertions(+), 8 deletions(-) create mode 100644 types/deneb/blob_sidecar.yaml create mode 100644 types/deneb/block_contents.yaml diff --git a/CHANGES.md b/CHANGES.md index 7266ce9e..bee60b95 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -16,6 +16,7 @@ There are likely to be descriptions etc outside of the list below, but new query | [#289](https://github.com/ethereum/beacon-APIs/pull/289) `/eth/v2/beacon/blocks/{block_id}` added `deneb` block to response | | | | | | | [#289](https://github.com/ethereum/beacon-APIs/pull/289) `/eth/v1/validator/blinded_blocks/{slot}` added `deneb` blinded block | | | | | | | [#289](https://github.com/ethereum/beacon-APIs/pull/289) `/eth/v1/validator/blocks/{slot}` added `deneb` block | | | | | | +| [#302](https://github.com/ethereum/beacon-APIs/pull/302) Added `BlockContents` structures for `deneb` blocks and blob_sidecars | | | | | | The Following are no longer in the Standard API, removed since the latest version. diff --git a/apis/beacon/blocks/blinded_blocks.yaml b/apis/beacon/blocks/blinded_blocks.yaml index 75253448..23748c99 100644 --- a/apis/beacon/blocks/blinded_blocks.yaml +++ b/apis/beacon/blocks/blinded_blocks.yaml @@ -13,7 +13,8 @@ post: successful. The beacon node is expected to integrate the new block into its state, and therefore validate the block internally, however blocks which fail the validation are still broadcast but a different status code is returned (202). Pre-Bellatrix, this endpoint will accept - a `SignedBeaconBlock`. + a `SignedBeaconBlock`. After Deneb, this additionally instructs the beacon node to broadcast all given + signed blobs. parameters: - in: header schema: @@ -32,7 +33,7 @@ post: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Altair.SignedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.SignedBlindedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Capella.SignedBlindedBeaconBlock" - - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBlindedBeaconBlock" + - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBlindedBlockContents" application/octet-stream: schema: description: "SSZ serialized block bytes. Use content type header to indicate that SSZ data is contained in the request body." diff --git a/apis/beacon/blocks/blocks.yaml b/apis/beacon/blocks/blocks.yaml index a7cd3b96..18be883f 100644 --- a/apis/beacon/blocks/blocks.yaml +++ b/apis/beacon/blocks/blocks.yaml @@ -11,7 +11,8 @@ post: The beacon node is also expected to integrate the block into state, but may broadcast it before doing so, so as to aid timely delivery of the block. Should the block fail full validation, a separate success response code (202) is used to indicate that the block was - successfully broadcast but failed integration. + successfully broadcast but failed integration. After Deneb, this additionally instructs + the beacon node to broadcast all given signed blobs. parameters: - in: header schema: @@ -30,7 +31,7 @@ post: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Altair.SignedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.SignedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Capella.SignedBeaconBlock" - - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBeaconBlock" + - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBlockContents" application/octet-stream: schema: description: "SSZ serialized block bytes. Use content type header to indicate that SSZ data is contained in the request body." diff --git a/apis/validator/blinded_block.yaml b/apis/validator/blinded_block.yaml index d879919e..52edf072 100644 --- a/apis/validator/blinded_block.yaml +++ b/apis/validator/blinded_block.yaml @@ -62,7 +62,7 @@ get: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Altair.BeaconBlock" - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.BlindedBeaconBlock" - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Capella.BlindedBeaconBlock" - - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Deneb.BlindedBeaconBlock" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Deneb.BlindedBlockContents" application/octet-stream: schema: description: "SSZ serialized block bytes. Use Accept header to choose this response type, version string is sent in header `Eth-Consensus-Version`." diff --git a/apis/validator/block.v2.yaml b/apis/validator/block.v2.yaml index ce30e427..403d4ffb 100644 --- a/apis/validator/block.v2.yaml +++ b/apis/validator/block.v2.yaml @@ -59,7 +59,7 @@ get: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Altair.BeaconBlock" - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.BeaconBlock" - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Capella.BeaconBlock" - - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Deneb.BeaconBlock" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Deneb.BlockContents" application/octet-stream: schema: description: "SSZ serialized block bytes. Use Accept header to choose this response type, version string is sent in header `Eth-Consensus-Version`." diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 58276833..a046dc02 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -352,18 +352,36 @@ components: $ref: './types/capella/light_client.yaml#/Capella/LightClientFinalityUpdate' Capella.LightClientOptimisticUpdate: $ref: './types/capella/light_client.yaml#/Capella/LightClientOptimisticUpdate' + Capella.Withdrawal: + $ref: './types/withdrawal.yaml#/Withdrawal' Deneb.BeaconState: $ref: './types/deneb/state.yaml#/Deneb/BeaconState' Deneb.BeaconBlock: $ref: './types/deneb/block.yaml#/Deneb/BeaconBlock' + Deneb.BlockContents: + $ref: './types/deneb/block_contents.yaml#/Deneb/BlockContents' Deneb.SignedBeaconBlock: $ref: './types/deneb/block.yaml#/Deneb/SignedBeaconBlock' + Deneb.SignedBlockContents: + $ref: './types/deneb/block_contents.yaml#/Deneb/SignedBlockContents' Deneb.BlindedBeaconBlock: $ref: './types/deneb/block.yaml#/Deneb/BlindedBeaconBlock' + Deneb.SignedBlindedBlockContents: + $ref: './types/deneb/block_contents.yaml#/Deneb/SignedBlindedBlockContents' + Deneb.BlindedBlockContents: + $ref: './types/deneb/block_contents.yaml#/Deneb/BlindedBlockContents' Deneb.SignedBlindedBeaconBlock: $ref: './types/deneb/block.yaml#/Deneb/SignedBlindedBeaconBlock' - Capella.Withdrawal: - $ref: './types/withdrawal.yaml#/Withdrawal' + Blob: + $ref: './types/primitive.yaml#/Blob' + Deneb.BlobSidecar: + $ref: './types/deneb/blob_sidecar.yaml#/Deneb/BlobSidecar' + Deneb.SignedBlobSidecar: + $ref: './types/deneb/blob_sidecar.yaml#/Deneb/SignedBlobSidecar' + Deneb.BlindedBlobSidecar: + $ref: './types/deneb/blob_sidecar.yaml#/Deneb/BlindedBlobSidecar' + Deneb.SignedBlindedBlobSidecar: + $ref: './types/deneb/blob_sidecar.yaml#/Deneb/SignedBlindedBlobSidecar' Node: $ref: './types/fork_choice.yaml#/Node' ExtraData: diff --git a/types/deneb/blob_sidecar.yaml b/types/deneb/blob_sidecar.yaml new file mode 100644 index 00000000..9fd0e511 --- /dev/null +++ b/types/deneb/blob_sidecar.yaml @@ -0,0 +1,90 @@ +Deneb: + BlobSidecars: + type: array + items: + $ref: '#/Deneb/BlobSidecar' + minItems: 0 + maxItems: 4 + + BlobSidecar: + type: object + description: "A blob sidecar as defined in the Deneb consensus spec." + properties: + block_root: + $ref: "../primitive.yaml#/Root" + index: + $ref: "../primitive.yaml#/Uint64" + slot: + $ref: "../primitive.yaml#/Uint64" + block_parent_root: + $ref: "../primitive.yaml#/Root" + proposer_index: + $ref: "../primitive.yaml#/Uint64" + blob: + $ref: "../primitive.yaml#/Blob" + kzg_commitment: + $ref: '../primitive.yaml#/KZGCommitment' + kzg_proof: + $ref: '../primitive.yaml#/KZGProof' + + SignedBlobSidecars: + type: array + items: + $ref: '#/Deneb/SignedBlobSidecar' + minItems: 0 + maxItems: 4 + + SignedBlobSidecar: + type: object + description: "The `SignedBlobSidecar` object envelope from the CL Deneb spec." + properties: + message: + $ref: "#/Deneb/BlobSidecar" + signature: + $ref: "../primitive.yaml#/Signature" + + BlindedBlobSidecars: + type: array + items: + $ref: '#/Deneb/BlindedBlobSidecar' + minItems: 0 + maxItems: 4 + + BlindedBlobSidecar: + type: object + description: "A blob sidecar with the SSZ root of the blob rather than the full blob." + properties: + block_root: + $ref: "../primitive.yaml#/Root" + index: + $ref: "../primitive.yaml#/Uint64" + slot: + $ref: "../primitive.yaml#/Uint64" + block_parent_root: + $ref: "../primitive.yaml#/Root" + proposer_index: + $ref: "../primitive.yaml#/Uint64" + blob_root: + $ref: "../primitive.yaml#/Root" + kzg_commitment: + $ref: '../primitive.yaml#/KZGCommitment' + kzg_proof: + $ref: '../primitive.yaml#/KZGProof' + + SignedBlindedBlobSidecars: + type: array + items: + $ref: '#/Deneb/SignedBlindedBlobSidecar' + minItems: 0 + maxItems: 4 + + SignedBlindedBlobSidecar: + type: object + description: "A variant of the `SignedBlobSidecar` object envelope from the CL Deneb spec, which contains a `BlindedBlobSidecar` rather than a `BlobSidecar`." + properties: + message: + $ref: "#/Deneb/BlindedBlobSidecar" + signature: + $ref: "../primitive.yaml#/Signature" + + diff --git a/types/deneb/block_contents.yaml b/types/deneb/block_contents.yaml new file mode 100644 index 00000000..1fa4fddf --- /dev/null +++ b/types/deneb/block_contents.yaml @@ -0,0 +1,37 @@ +Deneb: + BlockContents: + type: object + description: "The required object for block production according to the Deneb CL spec." + properties: + block: + $ref: "./block.yaml#/Deneb/BeaconBlock" + blob_sidecars: + $ref: "./blob_sidecar.yaml#/Deneb/BlobSidecars" + + BlindedBlockContents: + type: object + description: "The required object for blinded block production according to the Deneb CL spec." + properties: + blinded_block: + $ref: "./block.yaml#/Deneb/BlindedBeaconBlock" + blinded_blob_sidecars: + $ref: "./blob_sidecar.yaml#/Deneb/BlindedBlobSidecars" + + SignedBlockContents: + type: object + description: "The required signed components of block production according to the Deneb CL spec." + properties: + signed_block: + $ref: "./block.yaml#/Deneb/SignedBeaconBlock" + signed_blob_sidecars: + $ref: "./blob_sidecar.yaml#/Deneb/SignedBlobSidecars" + + SignedBlindedBlockContents: + type: object + description: "The required signed components of block production according to the Deneb CL spec." + properties: + signed_blinded_block: + $ref: "./block.yaml#/Deneb/SignedBlindedBeaconBlock" + signed_blinded_blob_sidecars: + $ref: "./blob_sidecar.yaml#/Deneb/SignedBlindedBlobSidecars" + \ No newline at end of file diff --git a/types/primitive.yaml b/types/primitive.yaml index 85334f5a..d3cdede3 100644 --- a/types/primitive.yaml +++ b/types/primitive.yaml @@ -123,9 +123,21 @@ LogsBloom: example: "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000" pattern: "^0x[a-fA-F0-9]{512}$" +Blob: + type: string + format: hex + pattern: "^0x[a-fA-F0-9]{262144}$" + description: "A blob is `FIELD_ELEMENTS_PER_BLOB * size_of(BLSFieldElement) = 4096 * 32 = 131072` bytes (`DATA`) representing a SSZ-encoded Blob as defined in Deneb" + KZGCommitment: type: string format: hex pattern: "^0x[a-fA-F0-9]{96}$" description: "A G1 curve point. Same as BLS standard \"is valid pubkey\" check but also allows `0x00..00` for point-at-infinity" example: "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a" + +KZGProof: + type: string + format: hex + pattern: "^0x[a-fA-F0-9]{96}$" + description: "A KZG proof. Same check as `KZGCommitment`"