add engine_getBlobsV3 method and BlobAndProofV3 type alias.

- Introduce mandatory `engine_getBlobsV3` method to support partial
  responses when fetching blobs from the EL blob pool.
- Add associated BlobAndProofV3 alias for BlobAndProofV2.
- Restore `engine_getBlobsV2` to all-or-nothing.

This mandates partial blob return support in Osaka, but avoids
extra serde in V2 while unutilized by the CL. The CL can switch to
V3 when p2p optimizations ship, without having to coordinate with
EL devs.

Author: raulk

src/engine/openrpc/methods/blob.yaml

@@ -27,3 +27,7 @@ BlobAndProofV2:
       type: array
       items:
         $ref: "#/components/schemas/bytes48"
+
+BlobAndProofV3:
+  title: Blob and proof object V3
+  $ref: '#/components/schemas/BlobAndProofV2'

src/engine/openrpc/schemas/blob.yaml

@@ -11,6 +11,7 @@ This specification is based on and extends [Engine API - Prague](./prague.md) sp
 - [Structures](#structures)
   - [BlobsBundleV2](#blobsbundlev2)
   - [BlobAndProofV2](#blobandproofv2)
+  - [BlobAndProofV3](#blobandproofv3)
 - [Methods](#methods)
   - [engine_getPayloadV5](#engine_getpayloadv5)
     - [Request](#request)
@@ -20,6 +21,10 @@ This specification is based on and extends [Engine API - Prague](./prague.md) sp
     - [Request](#request-1)
     - [Response](#response-1)
     - [Specification](#specification-1)
+  - [engine_getBlobsV3](#engine_getblobsv3)
+    - [Request](#request-2)
+    - [Response](#response-2)
+    - [Specification](#specification-2)
   - [Update the methods of previous forks](#update-the-methods-of-previous-forks)
     - [Cancun API](#cancun-api)
     - [Prague API](#prague-api)
@@ -47,6 +52,10 @@ The fields are encoded as follows:
 
 `proofs` **MUST** contain exactly `CELLS_PER_EXT_BLOB` cell proofs.
 
+### BlobAndProofV3
+
+Alias for `BlobAndProofV2`.
+
 ## Methods
 
 ### engine_getPayloadV5
@@ -89,7 +98,7 @@ This method follows the same specification as [`engine_getPayloadV4`](./prague.m
 
 ### engine_getBlobsV2
 
-Consensus layer clients **MAY** use this method to fetch blobs from the execution layer blob pool.
+Consensus layer clients **MAY** use this method to fetch blobs from the execution layer blob pool, in a all-or-nothing fashion. For partial response support, refer to `engine_getBlobsV3`.
 
 #### Request
 
@@ -108,12 +117,39 @@ Consensus layer clients **MAY** use this method to fetch blobs from the executio
 Refer to the specification for [`engine_getBlobsV1`](./cancun.md#engine_getblobsv1) with changes of the following:
 
 1. Given an array of blob versioned hashes client software **MUST** respond with an array of `BlobAndProofV2` objects with matching versioned hashes, respecting the order of versioned hashes in the input array.
-1. Given an array of blob versioned hashes, if client software has every one of the requested blobs, it **MUST** return an array of `BlobAndProofV2` objects whose order exactly matches the input array. For instance, if the request is `[A_versioned_hash, B_versioned_hash, C_versioned_hash]` and client software has `A`, `B` and `C` available, the response **MUST** be `[A, B, C]`.
-2. If one or more of the requested blobs are unavailable, the client **MUST** return either `null` or an array of the same length and order, inserting `null` only at the positions of the 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 either `null` or `[A, null, C]`.
+2. Given an array of blob versioned hashes, if client software has every one of the requested blobs, it **MUST** return an array of `BlobAndProofV2` objects whose order exactly matches the input array. For instance, if the request is `[A_versioned_hash, B_versioned_hash, C_versioned_hash]` and client software has `A`, `B` and `C` available, the response **MUST** be `[A, B, C]`.
+3. If one or more of the requested blobs are unavailable, the client **MUST** return `null` or an array of the same length and order, inserting `null` only at the positions of the 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 either `null` or `[A, null, C]`.
 3. 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.
-4. Client software **MUST** return `null` if syncing or otherwise unable to serve blob pool data.
+4. Client software **MUST** return `null` if syncing or otherwise unable to generally serve blob pool data.
 5. 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.
 
+### engine_getBlobsV3
+
+Consensus layer clients **MAY** use this method to fetch blobs from the execution layer blob pool, with support for partial responses. For an all-or-nothing query style, refer to `engine_getBlobsV2`.
+
+#### Request
+
+* method: `engine_getBlobsV3`
+* params:
+  1. `Array of DATA`, 32 Bytes - Array of blob versioned hashes.
+* timeout: 1s
+
+#### Response
+
+* result: `Array of BlobAndProofV3` - Array of [`BlobAndProofV3`](#BlobAndProofV2), inserting `null` only at the positions of the missing blobs, or a `null` literal in the designated cases specified below.
+* error: code and message set in case an error occurs during processing of the request.
+
+#### Specification
+
+> To assist the reader, we highlight differences against `engine_getBlobsV2` using italic.
+
+1. Given an array of blob versioned hashes client software **MUST** respond with an array of _`BlobAndProofV3`_ objects with matching versioned hashes, respecting the order of versioned hashes in the input array.
+2. Given an array of blob versioned hashes, if client software has every one of the requested blobs, it **MUST** return an array of _`BlobAndProofV3`_ objects whose order exactly matches the input array. For instance, if the request is `[A_versioned_hash, B_versioned_hash, C_versioned_hash]` and client software has `A`, `B` and `C` available, the response **MUST** be `[A, B, C]`.
+3. If one or more of the requested blobs are unavailable, _the client **MUST** return an array of the same length and order, inserting `null` only at the positions of the 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]`. If all blobs are missing, the client software must return an array of matching length, filled with `null` at all positions._
+4. 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.
+5. Client software **MUST** return `null` if syncing or otherwise unable to generally serve blob pool data.
+6. Callers **MUST** consider that execution layer clients may prune old blobs from their pool, and will respond with `null` at the corresponding position if a blob has been pruned.
+
 ### Update the methods of previous forks
 
 #### Cancun API