Skip to main content
netspecsEthereum networking

4.5.4.Engine blob access

Stage
In progress
Version
Pulled
execution-apiscancun.mdexecution-apisosaka.mdexecution-apisamsterdam.md
Related
Blob lifecycleData availability networkingeth/72 sparse blobpoolReq/Resp protocol

BlobAndProofV2

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.
  • proofs: Array of DATA - Array of KZGProof as defined in EIP-4844, 48 bytes each (DATA).

proofs MUST contain exactly CELLS_PER_EXT_BLOB cell proofs.

engine_getBlobsV2

Consensus layer clients MAY use this method to fetch blobs from the execution layer blob pool.

Request

  • method: engine_getBlobsV2
  • params:
    1. Array of DATA, 32 Bytes - Array of blob versioned hashes.
  • timeout: 1s

Response

  • result: Array of BlobAndProofV2 - Array of BlobAndProofV2 or null in case of any missing blobs.
  • error: code and message set in case an error occurs during processing of the request.

Specification

Refer to the specification for 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.
  2. Client software MUST return null in case of any missing or older version blobs. For instance,
    1. 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 null.
    2. if the request is [A_versioned_hash_for_blob_with_blob_proof], the response MUST be null as well.
  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.
  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 BlobAndProofV2 - Array of 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 BlobAndProofV2 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 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 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.

BlobCellsAndProofsV1

  • blob_cells: Array of DATA|null - a sequence of byte arrays (DATA) representing the partial matrix of the requested blobs, with null entries for missing cells.
  • proofs: Array of DATA|null - Array of KZGProof as defined in EIP-4844, 48 bytes each (DATA). Entries corresponding to null cells MUST also be null.

engine_getBlobsV4

Consensus layer clients MAY use this method to fetch blob cells from the execution layer blob pool, with support for partial responses. Unlike engine_getBlobsV3, this method returns individual cells and their KZG proofs rather than full blobs.

Request

  • method: engine_getBlobsV4
  • params:
    1. versioned_blob_hashes: Array of DATA, 32 Bytes - an array of blob versioned hashes.
    2. indices_bitarray: DATA, 16 Bytes - a bitarray denoting the indices of the cells to retrieve.
  • timeout: 1s

Response

  • result: (Array of BlobCellsAndProofsV1) | null - Array of BlobCellsAndProofsV1, 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

  1. Given an array of blob versioned hashes and a cell indices bitarray, client software MUST respond with an array of BlobCellsAndProofsV1 objects with matching versioned hashes, respecting the order of versioned hashes in the input array. Each BlobCellsAndProofsV1 object contains only the cells at the indices specified by the bitarray and their corresponding KZG proofs.
  2. Given an array of blob versioned hashes and a cell indices bitarray, if client software has every one of the requested blobs, it MUST return an array of BlobCellsAndProofsV1 objects whose order exactly matches the input array. The same indices_bitarray is applied to extract cells from each blob. For instance, if the request is [A_versioned_hash, B_versioned_hash, C_versioned_hash] with a specific indices_bitarray, and client software has A, B and C available, the response MUST be [A_cells_and_proofs, B_cells_and_proofs, C_cells_and_proofs], where each object contains the cells at the indices specified by the bitarray.
  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_cells_and_proofs, null, C_cells_and_proofs]. If all blobs are missing, the client software must return an array of matching length, filled with null at all positions.
  4. Within a BlobCellsAndProofsV1 object, if specific cells are unavailable for an otherwise available blob, those cells MUST be set to null in the blob_cells array, and the corresponding entries in the proofs array MUST also be null.
  5. 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.
  6. Client software MUST return null if syncing or otherwise unable to generally serve blob pool data.
  7. 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.