Skip to content

engine_getBlobsV4 #774

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mkalinin merged 13 commits into from
May 1, 2026
Merged

engine_getBlobsV4 #774

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
1c3b82d
Update engine_getBlobsV4 specification and examples
kamilsa Mar 21, 2026
9ccfb81
Clarify engine_getBlobsV4 spec
kamilsa Apr 10, 2026
df71176
Add blobcellsandproofsv into the wordlist
kamilsa Apr 10, 2026
c931b99
add BlobCellsAndProofsV1 to the schema
kamilsa Apr 10, 2026
23a2060
self review
kamilsa Apr 10, 2026
8b8ce18
Update engine_forkchoiceUpdatedV4 with custody columns
kamilsa Apr 14, 2026
c342e06
Apply suggestions from code review
kamilsa Apr 14, 2026
e9c94ce
Add missing null type to return type in engine_getBlobsV4
kamilsa Apr 29, 2026
fcb1359
Update quotes
kamilsa Apr 29, 2026
486a27b
Update src/engine/openrpc/schemas/blob.yaml
kamilsa Apr 29, 2026
60731bb
engine_forkchoiceUpdatedV4 runtime error clarification
kamilsa Apr 30, 2026
e5b89d0
Add 2 slots delay after reducing custody set
kamilsa Apr 30, 2026
7baa97b
Merge remote-tracking branch 'upstream/main' into update/engine-getBl…
kamilsa Apr 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 69 additions & 0 deletions src/engine/amsterdam.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec
- [ExecutionPayloadV4](#executionpayloadv4)
- [ExecutionPayloadBodyV2](#executionpayloadbodyv2)
- [PayloadAttributesV4](#payloadattributesv4)
- [BlobCellsAndProofsV1](#blobcellsandproofsv1)
- [Methods](#methods)
- [engine_newPayloadV5](#engine_newpayloadv5)
- [Request](#request)
Expand All @@ -34,6 +35,14 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec
- [Request](#request-4)
- [Response](#response-4)
- [Specification](#specification-4)
- [Request](#request-5)
- [Response](#response-5)
- [Specification](#specification-5)
- [engine_getBlobsV4](#engine_getblobsv4)
- [Request](#request-6)
- [Response](#response-6)
- [Specification](#specification-6)
- [PayloadAttributesV4](#payloadattributesv4)
- [Update the methods of previous forks](#update-the-methods-of-previous-forks)
- [Osaka API](#osaka-api)

Expand Down Expand Up @@ -84,6 +93,12 @@ This structure has the syntax of [`PayloadAttributesV3`](./cancun.md#payloadattr
- `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block.
- `slotNumber`: `QUANTITY`, 64 Bits - value for the `slotNumber` field of the new payload


### 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](https://eips.ethereum.org/EIPS/eip-4844), 48 bytes each (`DATA`). Entries corresponding to `null` cells **MUST** also be `null`.

## Methods

### engine_newPayloadV5
Expand Down Expand Up @@ -200,6 +215,7 @@ This method follows the same specification as [`engine_getPayloadBodiesByRangeV1
* 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.
Copy link
Copy Markdown
Contributor

@mkalinin mkalinin Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown

@healthykim healthykim Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor

@mkalinin mkalinin Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

* timeout: 8s

#### Response
Expand All @@ -220,6 +236,59 @@ This method follows the same specification as [`engine_forkchoiceUpdatedV3`](./c

4. If any of the above checks fails, the `forkchoiceState` update **MUST NOT** be rolled back.

3. If `custodyColumns` is provided (non-null), the following rules apply:

1. `custodyColumns` **MUST** be a 16-byte `DATA` value. If it is not, the client software **MUST** return `-32602: Invalid params`.

2. The Execution client **MUST** adopt the provided custody set when acting as a sampler for type 3 transactions.

3. For type 3 transactions pending in the blobpool:

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. To prevent peers from perceiving an availability fault, this pruning **SHOULD** occur only after a delay of 2 slots following the broadcast of an updated `NewPooledTransactionHashes` announcement that reflects the reduced set.

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


### 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`](./osaka.md#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.
Copy link
Copy Markdown
Member

@raulk raulk Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#774 (review)

Copy link
Copy Markdown
Contributor Author

@kamilsa kamilsa Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

* timeout: 1s

#### Response

* result: `(Array of BlobCellsAndProofsV1) | null` - Array of [`BlobCellsAndProofsV1`](#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.

### PayloadAttributesV4

This structure has the syntax of [`PayloadAttributesV3`](./cancun.md#payloadattributesv3) and appends a single field: `slotNumber`.

- `timestamp`: `QUANTITY`, 64 Bits - value for the `timestamp` field of the new payload
- `prevRandao`: `DATA`, 32 Bytes - value for the `prevRandao` field of the new payload
- `suggestedFeeRecipient`: `DATA`, 20 Bytes - suggested value for the `feeRecipient` field of the new payload
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.
- `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block.
- `slotNumber`: `QUANTITY`, 64 Bits - value for the `slotNumber` field of the new payload

### Update the methods of previous forks

#### Osaka API
Expand Down
Loading
Loading