engine_getBlobsV4 by kamilsa · Pull Request #774 · ethereum/execution-apis

kamilsa · 2026-03-21T14:06:33Z

Companion PR to ethereum/EIPs#11444 . The current PR is expected to be merged first.

To support EIP-8070 (sparse blobpools) :

engine_getBlobsV4: provides the mechanism for the CL to request partial blobs data from the the EL's blobpool
engine_forkchoiceupdatedv4: updated with the column custody field to update EL about CL's custody column set

- Expand V4 spec from 1 line to 7 detailed specification points mirroring V3 style - Add support for multiple blob versioned hashes in example (3 blobs) - Clarify missing blob handling (return null at corresponding positions) - Add support for partial blobs with null cells and null proofs - Update response schema to allow null entries (oneOf pattern) - Include example with: present blob, partial blob with null cell, missing blob Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Adds new Engine API capabilities needed for EIP-8070 “sparse blobpools”, enabling the CL to (1) communicate its blob column custody set to the EL and (2) request partial blob cell data (with proofs) from the EL blobpool.

Changes:

Introduces engine_blobCustodyUpdatedV1 for CL→EL custody-set updates via a 16-byte bitarray.
Introduces engine_getBlobsV4 for fetching requested blob cells + KZG proofs (including partial/missing data semantics).
Adds shared schema types (bytes16, BlobCellsAndProofsV1) and updates fork documentation/spellcheck wordlist accordingly.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
wordlist.txt	Adds the new versioned schema/method-related token for spellchecking.
src/schemas/base-types.yaml	Adds a reusable `bytes16` primitive used by the new methods’ bitarray params.
src/engine/openrpc/schemas/blob.yaml	Defines `BlobCellsAndProofsV1` response object for partial cell/proof returns.
src/engine/openrpc/methods/blob.yaml	Adds OpenRPC method entries for `engine_blobCustodyUpdatedV1` and `engine_getBlobsV4` (with examples).
src/engine/amsterdam.md	Documents the new structure and method specs in the Amsterdam fork markdown (including ToC updates).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

dapplion · 2026-04-27T13:50:41Z

we will ship this !!

mkalinin · 2026-04-29T03:17:33Z

 * params:
  1. `forkchoiceState`: [`ForkchoiceStateV1`](./paris.md#ForkchoiceStateV1).
  2. `payloadAttributes`: `Object|null` - Instance of [`PayloadAttributesV4`](#payloadattributesv4) or `null`.
+  3. `custodyColumns`: `DATA|null`, 16 Bytes - Interpreted as a bitarray of length `CELLS_PER_EXT_BLOB` indicating which column indices form the CL's custody set, or `null` if the CL does not provide custody services.


Are we certain that no network in the future will use CELLS_PER_EXT_BLOB > 128?

Yes, for the midterm, and we can adjust this length later, right ?

We could extend this field to Bytes32 with the high part zeroed out, doesn’t seem to be a big overhead. If we stick with Bytes16 for now and this number will be increased in the future we will have to introduce a new version of fcU. I don’t have a strong opinion on that, and would lean on whatever you think is reasonable

mkalinin · 2026-04-29T03:22:17Z

+
+        2. If the custody set has contracted, the Execution client **MAY** prune dropped cells from local storage, but **ONLY AFTER** it has broadcast an updated `NewPooledTransactionHashes` announcement with the reduced available set to avoid peers perceiving an availability fault.
+
+    4. The Execution client **MUST** treat a request to update the custody set to the current value as a no-op and return Ok.


Does “no-op and return OK" mean the forkchoiceUpdate processing MUST NOT be affected by the custodyColumns?

I would phrase it something like the following then:

The Execution client MUST run custody set update independently to the fork choice update, i.e. execution time and errors occurred during custody set update MUST NOT affect the main processing flow of this method.

I think this may be added as additional rule. So we keep 4. and introduce 5. as how you described it

mkalinin · 2026-04-29T03:24:44Z

+
+        1. If the custody set has expanded, the Execution client **SHOULD** issue new sampling requests for the delta. It **MAY** broadcast an updated `NewPooledTransactionHashes` announcement with the newly available set.
+
+        2. If the custody set has contracted, the Execution client **MAY** prune dropped cells from local storage, but **ONLY AFTER** it has broadcast an updated `NewPooledTransactionHashes` announcement with the reduced available set to avoid peers perceiving an availability fault.


What would a reasonable minimal delay between broadcasting updated NewPooledTransactionHashes and pruning? It would be helpful to specify it here to set expectations, like the minimal delay could be a slot duration or something like that.

We were considering 2 slots, but this number is (IIRC) quite arbitrary and needs to be tested on devnet. We will discuss this and update the PR. Thank you

mkalinin · 2026-04-29T03:33:23Z

      schema:
        $ref: '#/components/schemas/PayloadAttributesV4'
+    - name: Custody columns
+      required: false


I think it should be true as it either bytes or null, there is no case when custodyColumns param is completely missing

it was set to false for consistency with the previous field (payloadAttributes) which also could be null but is not required.

But no big deal making Custody columns required if needed

raulk

Re: optionality of the custody column filter. We have been designing solutions for in-transit reconstruction at the CL. There is a scenario in which we'd want the EL to serve all cells it has buffered, regardless of the CL's custody set. That would include "excess" cells when acting as a sampler, and all cells when acting as a provider.

healthykim · 2026-04-29T10:06:09Z

Re: optionality of the custody column filter. We have been designing solutions for in-transit reconstruction at the CL. There is a scenario in which we'd want the EL to serve all cells it has buffered, regardless of the CL's custody set. That would include "excess" cells when acting as a sampler, and all cells when acting as a provider.

What filter are you referring to ? This is possible with setting the bitmap array in getBlobsV4 request to all 1, right ?

raulk · 2026-04-29T12:21:15Z

+* 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.


#774 (review)

This is already doable with the proposed API.

CL can set indices_bitarray to all ones. That way CL requests EL to provide all cells it has for the requested versioned blob hashes. For the missing cells (e.g. for cells that EL was acting as a sampler) request will contain nulls in the blob_cells field

Co-authored-by: Mikhail Kalinin <noblesse.knight@gmail.com>

kamilsa and others added 5 commits March 21, 2026 19:04

Clarify engine_getBlobsV4 spec

9ccfb81

Add blobcellsandproofsv into the wordlist

df71176

add BlobCellsAndProofsV1 to the schema

c931b99

self review

23a2060

kamilsa changed the title ~~Update engine_getBlobsV4 specification and examples~~ engine_getBlobsV4 and engine_blobCustodyUpdatedV1 Apr 10, 2026

kamilsa marked this pull request as ready for review April 10, 2026 10:22

Copilot AI review requested due to automatic review settings April 10, 2026 10:22

Copilot started reviewing on behalf of kamilsa April 10, 2026 10:22 View session

Copilot AI reviewed Apr 10, 2026

View reviewed changes

Comment thread src/engine/openrpc/methods/blob.yaml Outdated

Comment thread src/engine/amsterdam.md Outdated

kamilsa and others added 2 commits April 14, 2026 14:40

Update engine_forkchoiceUpdatedV4 with custody columns

8b8ce18

Apply suggestions from code review

c342e06

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

kamilsa changed the title ~~engine_getBlobsV4 and engine_blobCustodyUpdatedV1~~ engine_getBlobsV4 Apr 14, 2026

healthykim approved these changes Apr 23, 2026

View reviewed changes

bomanaps mentioned this pull request Apr 23, 2026

All Core Devs - Execution (ACDE) #235, April 23, 2026 ethereum/pm#2015

Closed

4 tasks

healthykim mentioned this pull request Apr 24, 2026

All Core Devs - Consensus (ACDC) #178, May 14, 2026 ethereum/pm#2028

Open

4 tasks

flcl42 approved these changes Apr 27, 2026

View reviewed changes

dapplion approved these changes Apr 27, 2026

View reviewed changes

mattsse approved these changes Apr 28, 2026

View reviewed changes

mkalinin reviewed Apr 29, 2026

View reviewed changes

Comment thread src/engine/amsterdam.md Outdated

mkalinin reviewed Apr 29, 2026

View reviewed changes

Comment thread src/engine/openrpc/schemas/blob.yaml Outdated

mkalinin reviewed Apr 29, 2026

View reviewed changes

Comment thread src/engine/openrpc/schemas/blob.yaml Outdated

raulk reviewed Apr 29, 2026

View reviewed changes

Rjected approved these changes Apr 29, 2026

View reviewed changes

fjl approved these changes Apr 29, 2026

View reviewed changes

Giulio2002 approved these changes Apr 29, 2026

View reviewed changes

raulk reviewed Apr 29, 2026

View reviewed changes

dknopik approved these changes Apr 29, 2026

View reviewed changes

kamilsa and others added 3 commits April 29, 2026 18:29

Add missing null type to return type in engine_getBlobsV4

e9c94ce

Co-authored-by: Mikhail Kalinin <noblesse.knight@gmail.com>

Update quotes

fcb1359

Co-authored-by: Mikhail Kalinin <noblesse.knight@gmail.com>

Update src/engine/openrpc/schemas/blob.yaml

486a27b

Co-authored-by: Mikhail Kalinin <noblesse.knight@gmail.com>


		2. If the custody set has contracted, the Execution client MAY prune dropped cells from local storage, but ONLY AFTER it has broadcast an updated `NewPooledTransactionHashes` announcement with the reduced available set to avoid peers perceiving an availability fault.

		4. The Execution client MUST treat a request to update the custody set to the current value as a no-op and return Ok.


		1. If the custody set has expanded, the Execution client SHOULD issue new sampling requests for the delta. It MAY broadcast an updated `NewPooledTransactionHashes` announcement with the newly available set.

		2. If the custody set has contracted, the Execution client MAY prune dropped cells from local storage, but ONLY AFTER it has broadcast an updated `NewPooledTransactionHashes` announcement with the reduced available set to avoid peers perceiving an availability fault.

Conversation

kamilsa commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

dapplion commented Apr 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

raulk left a comment

Choose a reason for hiding this comment

Uh oh!

healthykim commented Apr 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

12 participants

kamilsa commented Mar 21, 2026 •

edited

Loading