Define engine_getBlobsV1 (#559)

* Define `engine_getBlobsV1`

* Add `getBlobs` method and schema. (#1)

* engine: Add `getBlobsV1` method (#2)

* Fix spell check

* Fix typo and formatting

* Apply Mikhail's clarifications

Co-authored-by: Mikhail Kalinin <[email protected]>

* Add error to schema

Co-authored-by: Mikhail Kalinin <[email protected]>

* Update toc in cancun.md

---------

Co-authored-by: Jimmy Chen <[email protected]>
Co-authored-by: Mikhail Kalinin <[email protected]>

src/engine/cancun.md

@@ -12,6 +12,7 @@ This specification is based on and extends [Engine API - Shanghai](./shanghai.md
 - [Structures](#structures)
   - [ExecutionPayloadV3](#executionpayloadv3)
   - [BlobsBundleV1](#blobsbundlev1)
+  - [BlobAndProofV1](#blobandproofv1)
   - [PayloadAttributesV3](#payloadattributesv3)
 - [Methods](#methods)
   - [engine_newPayloadV3](#engine_newpayloadv3)
@@ -26,7 +27,12 @@ This specification is based on and extends [Engine API - Shanghai](./shanghai.md
     - [Request](#request-2)
     - [Response](#response-2)
     - [Specification](#specification-2)
+  - [engine_getBlobsV1](#engine_getblobsv1)
+    - [Request](#request-3)
+    - [Response](#response-3)
+    - [Specification](#specification-3)
   - [Deprecate `engine_exchangeTransitionConfigurationV1`](#deprecate-engine_exchangetransitionconfigurationv1)
+  - [Update the methods of previous forks](#update-the-methods-of-previous-forks)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -64,6 +70,13 @@ The fields are encoded as follows:
 
 All of the above three arrays **MUST** be of same length.
 
+### BlobAndProofV1
+
+The fields are encoded as follows:
+
+- `blob`: `DATA` - `FIELD_ELEMENTS_PER_BLOB * BYTES_PER_FIELD_ELEMENT = 4096 * 32 = 131072` bytes (`DATA`) representing a SSZ-encoded `Blob` as defined in [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844).
+- `proof`: `DATA` - `KZGProof` as defined in [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844), 48 bytes (`DATA`).
+
 ### PayloadAttributesV3
 
 This structure has the syntax of [`PayloadAttributesV2`](./shanghai.md#payloadattributesv2) and appends a single field: `parentBeaconBlockRoot`.
@@ -170,6 +183,36 @@ Refer to the specification for [`engine_getPayloadV2`](./shanghai.md#engine_getp
 
 5. Client software **MAY** use any heuristics to decide whether to set `shouldOverrideBuilder` flag or not. If client software does not implement any heuristic this flag **SHOULD** be set to `false`.
 
+### engine_getBlobsV1
+
+Consensus layer clients **MAY** use this method to fetch blobs from the execution layer blob pool.
+
+*Note*: This is a new optional method introduced after Cancun. It is defined here because it is backwards-compatible with Cancun.
+
+#### Request
+
+* method: `engine_getBlobsV1`
+* params:
+  1. `Array of DATA`, 32 Bytes - Array of blob versioned hashes.
+* timeout: 1s
+
+#### Response
+
+* result: `Array of BlobAndProofV1` - Array of [`BlobAndProofV1`](#BlobAndProofV1), items of which may be `null`.
+* error: code and message set in case an error occurs during processing of the request.
+
+#### Specification
+
+1. Given an array of blob versioned hashes client software **MUST** respond with an array of `BlobAndProofV1` objects with matching versioned hashes, respecting the order of versioned hashes in the input array.
+
+1. Client software **MUST** place responses in the order given in the request, using `null` for any missing blobs. For instance, if the request is `[A_versioned_hash, B_versioned_hash, C_versioned_hash]` and client software has data for blobs `A` and `C`, but doesn't have data for `B`, the response **MUST** be `[A, null, C]`.
+
+1. Client software **MUST** support request sizes of at least 128 blob versioned hashes. The client **MUST** return `-38004: Too large request` error if the number of requested blobs is too large.
+
+1. Client software **MAY** return an array of all `null` entries if syncing or otherwise unable to serve blob pool data.
+
+1. Callers **MUST** consider that execution layer clients may prune old blobs from their pool, and will respond with `null` if a blob has been pruned.
+
 ### Deprecate `engine_exchangeTransitionConfigurationV1`
 
 This document introduces deprecation of [`engine_exchangeTransitionConfigurationV1`](./paris.md#engine_exchangetransitionconfigurationv1). The deprecation is specified as follows:
@@ -192,4 +235,4 @@ For the following methods:
 
 a validation **MUST** be added:
 
-1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload or payloadAttributes greater or equal to the Cancun activation timestamp.
+1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload or payloadAttributes greater or equal to the Cancun activation timestamp.

src/engine/openrpc/schemas/blob.yaml

@@ -0,0 +1,14 @@
+BlobAndProofV1:
+  title: Blob and proof object V1
+  type: object
+  required:
+    - blob
+    - proof
+  properties:
+    blob: 
+      title: Blob
+      $ref: '#/components/schemas/bytes'
+    proof:
+      title: proof
+      $ref: '#/components/schemas/bytes48'
+

wordlist.txt

@@ -15,6 +15,7 @@ ethereum
 ethereumjs
 erigon
 getclientversionv
+getblobsv
 interop
 js
 json
@@ -53,6 +54,7 @@ ipc
 cli
 blobsbundlev
 getblobsbundlev
+blobandproofv
 ssz
 kzg
 besu